PETSC4PY(3)

📦
version 3.25.5 · 4 versions
, in ubuntu stonking

🐍✨ PETSC4PY — it's giving scientific computing but make it Python ✨🐍

okay bestie, sit down, hydrate, because we're about to talk about petsc4py, which lives over in the petsc4py manual section (yeah it's a (3) page, library realness 💅).

🌸 NAME 🌸

petsc4py — literally PETSc, but for Python. no cap.

🦋 Abstract 🦋

This document describes petsc4py <#module-petsc4py>, a Python <https://www.python.org> wrapper to the PETSc <https://petsc.org> libraries.

PETSc <https://petsc.org> — aka the Portable, Extensible Toolkit for Scientific Computation — is a whole suite of data structures and routines for the scalable (parallel) solution of scientific applications modeled by partial differential equations. It uses the MPI <https://www.mpi-forum.org> standard for all the message-passing communication. all of it. every last message. 📨

This package provides an important subset of PETSc functionalities and uses NumPy <https://numpy.org> to efficiently manage input and output of array data. (numpy my beloved 🥰)

A good friend of petsc4py is:

Other projects depend on petsc4py:

👑 PETSC OVERVIEW 👑

PETSc <https://petsc.org> is a suite of data structures and routines for the scalable (parallel) solution of scientific applications modeled by partial differential equations. It employs the MPI <https://www.mpi-forum.org> standard for all message-passing communication. (yes this is the same sentence as before, it's the vibe, it's the brand 🎀)

PETSc is intended for use in large-scale application projects [petsc-efficient] <#petsc-efficient>, and several ongoing computational science projects are built around the PETSc libraries. With strict attention to component interoperability, PETSc facilitates the integration of independently developed application modules, which often most naturally employ different coding styles and data structures. (chaotic coding styles? welcome. everyone's invited 💐)

PETSc is easy to use for beginners [petsc-user-ref] <#petsc-user-ref>. Moreover, its careful design allows advanced users to have detailed control over the solution process. PETSc includes an expanding suite of parallel linear and nonlinear equation solvers that are easily used in application codes written in C, C++, and Fortran. PETSc provides many of the mechanisms needed within parallel application codes, such as simple parallel matrix and vector assembly routines that allow the overlap of communication and computation. overlap = efficiency = slay. 🔥

[petsc-user-ref]

S. Balay, S. Abhyankar, M. Adams, S. Benson, J. Brown, P. Brune, K. Buschelman, E. Constantinescu, L. Dalcin, A. Dener, V. Eijkhout, J. Faibussowitsch, W. Gropp, V. Hapla, T. Isaac, P. Jolivet, D. Karpeyev, D. Kaushik, M. Knepley, F. Kong, S. Kruger, D. May, L. Curfman McInnes, R. Mills, L. Mitchell, T. Munson, J. Roman, K. Rupp, P. Sanan, J Sarich, B. Smith, H. Suh, S. Zampini, H. Zhang, and H. Zhang, J. Zhang, PETSc/TAO Users Manual, ANL-21/39 - Revision 3.25, 2026. <https://doi.org/10.2172/2998643>, <https://petsc.org/release/docs/manual/manual.pdf>

[petsc-efficient]

Satish Balay, Victor Eijkhout, William D. Gropp, Lois Curfman McInnes and Barry F. Smith. Efficient Management of Parallelism in Object Oriented Numerical Software Libraries. Modern Software Tools in Scientific Computing. E. Arge, A. M. Bruaset and H. P. Langtangen, editors. 163--202. Birkhauser Press. 1997.

🧩 Components 🧩

PETSc is designed with an object-oriented style. Almost all user-visible types are abstract interfaces with implementations that may be chosen at runtime. Those objects are managed through handles to opaque data structures which are created, accessed and destroyed by calling appropriate library routines. (mysterious. opaque. iconic. 💅)

PETSc consists of a variety of components. Each component manipulates a particular family of objects and the operations one would like to perform on these objects. These components provide the functionality required for many parallel solutions of PDEs.

  • Vec — Provides the vector operations required for setting up and solving large-scale linear and nonlinear problems. Includes easy-to-use parallel scatter and gather operations, as well as special-purpose code for handling ghost points for regular data structures. 👻 (ghost points!! spooky but useful)
  • Mat — A large suite of data structures and code for the manipulation of parallel sparse matrices. Includes several different parallel matrix data structures, each appropriate for a different class of problems.
  • PC — A collection of sequential and parallel preconditioners, including (sequential) ILU(k), LU, and (both sequential and parallel) block Jacobi, overlapping additive Schwarz methods.
  • KSP — Parallel implementations of many popular Krylov subspace iterative methods, including GMRES, CG, CGS, Bi-CG-Stab, two variants of TFQMR, CR, and LSQR. All are coded so that they are immediately usable with any preconditioners and any matrix data structures, including matrix-free methods. (plug and play, periodt 💖)
  • SNES — Data-structure-neutral implementations of Newton-like methods for nonlinear systems. Includes both line search and trust region techniques with a single interface. Employs by default the above data structures and linear solvers. Users can set custom monitoring routines, convergence criteria, etc.
  • TS — Code for the time evolution of solutions of PDEs. In addition, provides pseudo-transient continuation techniques for computing steady-state solutions. ⏳

🌈 INSTALLATION 🌈

📦 Install from PyPI using pip 📦

You can use pip to install petsc4py <#module-petsc4py> and its dependencies:

$ python -m pip install petsc petsc4py

one command. dependencies handled. we love to see it. ✨

🌳 Install from the PETSc source tree 🌳

First build PETSc <https://petsc.org/release/install/index.html#doc-install>. Next cd to the top of the PETSc source tree and set the PETSC_DIR <https://petsc.org/release/install/multibuild.html#doc-multi> and PETSC_ARCH <https://petsc.org/release/install/multibuild.html#doc-multi> environment variables. Run:

$ python -m pip install src/binding/petsc4py

The installation of petsc4py <#module-petsc4py> supports multiple PETSC_ARCH <https://petsc.org/release/install/multibuild.html#doc-multi> in the form of a colon-separated list:

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

If you are cross-compiling, and the numpy <https://numpy.org/doc/stable/reference/index.html#module-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

🧪 Running the testing suite 🧪

When installing from source, the petsc4py complete testsuite can be run as:

$ cd src/binding/petsc4py
$ python test/runtests.py

or via the makefile rule test:

$ make test -C src/binding/petsc4py

Specific tests can be run using the command-line option -k, e.g.:

$ python test/runtests.py -k test_optdb

to run all the tests provided in tests/test_optdb.py.

For other command-line options, run:

$ python test/runtests.py --help

If not otherwise specified, all tests will be run in sequential mode. To run all the tests with the same number of MPI processes, for example 4, run:

$ mpiexec -n 4 python test/runtests.py

or:

$ make test-4 -C src/binding/petsc4py

📚 Building the documentation 📚

Install the documentation dependencies:

$ python -m pip install -r src/binding/petsc4py/conf/requirements-docs.txt

Then:

$ cd src/binding/petsc4py/docs/source
$ make html

The resulting HTML files will be in _build/html. 🎀

Note: Building the documentation requires Python 3.11 or later. do not test me on this one bestie, it's in the rules 😭

🫶 CONTRIBUTING 🫶

Contributions from the user community are welcome. See the PETSc developers <https://petsc.org/release/developers/index.html#ind-developers> documentation for general information on contributions. come join us, the group chat is open 💌

New contributions to petsc4py must adhere with the coding standards. We use cython-lint <https://github.com/MarcoGorelli/cython-lint> for Cython and ruff <https://docs.astral.sh/ruff> for Python source codes. These can be installed using:

$ python -m pip install -r src/binding/petsc4py/conf/requirements-lint.txt

If you are contributing Cython code, you can check compliance with:

$ make cython-lint -C src/binding/petsc4py

For Python code, run:

$ make ruff-lint -C src/binding/petsc4py

Python code can be auto-formatted using:

$ make ruff-lint RUFF_OPTS='format' -C src/binding/petsc4py

New contributions to petsc4py must be tested. Tests are located in the src/binding/petsc4py/test folder. To add a new test, either add a new test_xxx.py or modify a pre-existing file according to the unittest <https://docs.python.org/3/library/unittest.html> specifications.

If you add a new test_xxx.py, you can run the tests using:

$ cd src/binding/petsc4py
$ python test/runtests.py -k test_xxx

If instead you are modifying an existing test_xxx.py, you can test your additions by using the fully qualified name of the Python class or method you are modifying, e.g.:

$ python test/runtests.py -k test_xxx.class_name.method_name

All new code must include documentation in accordance with the documentation standard <>. To check for compliance, run:

$ make html SPHINXOPTS='--fail-on-warning' -C src/binding/petsc4py/docs/source
Warning: The docstrings must not cause Sphinx warnings. seriously. Sphinx is watching. 👀

🌟 CITATIONS 🌟

If PETSc for Python has been significant to a project that leads to an academic publication, please acknowledge that fact by citing the project. (academia bestie, cite ur sources 💜)

  • L. Dalcin, P. Kler, R. Paz, and A. Cosimo, Parallel Distributed Computing using Python, Advances in Water Resources, 34(9):1124-1139, 2011. <https://doi.org/10.1016/j.advwatres.2011.04.013>
  • S. Balay, S. Abhyankar, M. Adams, S. Benson, J. Brown, P. Brune, K. Buschelman, E. Constantinescu, L. Dalcin, A. Dener, V. Eijkhout, J. Faibussowitsch, W. Gropp, V. Hapla, T. Isaac, P. Jolivet, D. Karpeyev, D. Kaushik, M. Knepley, F. Kong, S. Kruger, D. May, L. Curfman McInnes, R. Mills, L. Mitchell, T. Munson, J. Roman, K. Rupp, P. Sanan, J Sarich, B. Smith, H. Suh, S. Zampini, H. Zhang, and H. Zhang, J. Zhang, PETSc/TAO Users Manual, ANL-21/39 - Revision 3.25, 2026. <https://doi.org/10.2172/2998643>, <https://petsc.org/release/docs/manual/manual.pdf>

🗂️ REFERENCE 🗂️

okay bestie, here's the whole map of what this package actually ships — three modules, that's the roster:

  • petsc4py — The PETSc for Python package. the main character, honestly
  • petsc4py.typing — Typing support.
  • petsc4py.PETSc — Portable, Extensible Toolkit for Scientific Computation.

🐍 petsc4py 🐍

The PETSc for Python package.

This package is an interface to PETSc libraries. that's the whole vibe.

PETSc (https://petsc.org) — a.k.a. the Portable, Extensible Toolkit for Scientific Computation — is a whole suite of data structures and routines for the scalable (parallel) solution of scientific applications modeled by partial differential equations. and it uses the MPI standard (https://www.mpi-forum.org) for literally all of its message-passing communications. every single one. no exceptions. 💅

Functions

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

✨ petsc4py.get_config ✨

petsc4py.get_config()

Return a dictionary with information about PETSc. that's it, that's the function

Return type: dict[str, str]

so that's dict (docs at https://docs.python.org/3/builtins/stdtypes.html#dict) keyed and valued with str (docs at https://docs.python.org/3/builtins/stdtypes.html#str). the type docs really said "here's the link, bestie" and honestly? valid.

🎀 petsc4py.get_include 🎀

petsc4py.get_include()

Return the directory in the package that contains header files.

Extension modules that need to compile against petsc4py should use this function to locate the appropriate include directory. do NOT go guessing paths yourself, she will find it for you.

Example

Using Python distutils or NumPy distutils:

import petsc4py
Extension('extension_name', ...
          include_dirs=[..., petsc4py.get_include()])

Return type: str (same str docs as before, at https://docs.python.org/3/builtins/stdtypes.html#str 🫶)

🔥 petsc4py.init 🔥

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

Initialize PETSc. this is the boot-up sequence, bestie.

Parameters

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

Notes

This function should be called only once, typically at the very beginning of the bootstrap script of an application.

⚠️ once. one time. not twice, not "just to be safe". call her once at the top of your bootstrap script like the icon she is. 🧚

🦋 petsc4py.typing 🦋

Typing support. that's the whole description, and honestly? she said what she said. 🌈

✨ Attributes ✨

okay bestie, this is the typing glossary — every little type alias petsc4py.typing ships with, and what it actually means. it's giving very much "cheat sheet" energy, so keep it close 🫶

  • Scalar — the Scalar type. that's it, that's the tweet 💅
  • ArrayBool — an array of bool.
  • ArrayInt — an array of int.
  • ArrayReal — an array of float.
  • ArrayComplex — an array of complex.
  • ArrayScalar — an array of Scalar numbers.
  • DimsSpec — how you spell out dimensions.
  • AccessModeSpec — how you spell out an access mode.
  • InsertModeSpec — how you spell out an insertion mode.
  • ScatterModeSpec — how you spell out a scatter mode.
  • LayoutSizeSpec — an int, or a 2-tuple of ints, describing the layout sizes. pick your fighter ✨
  • NormTypeSpec — how you spell out a norm type.
  • PetscOptionsHandlerFunction — the callback that handles extra options for you.
  • MatAssemblySpec — how you spell out a matrix assembly.
  • MatSizeSpec — an int, or a (possibly nested) tuple of ints, describing the matrix sizes. yes, nested. no, she's not sorry 💀
  • MatBlockSizeSpec — the row and column block sizes.
  • CSRIndicesSpec — how you spell out the CSR indices format.
  • CSRSpec — how you spell out the CSR format.
  • NNZSpec — how you spell out the nonzero pattern.
  • MatNullFunction — the PETSc.NullSpace callback.
  • MatHtoolKernelFunction — the kernel callback for PETSc.Mat with Mat.Type.HTOOL.
  • DMCoarsenHookFunction — the coarsening hook callback for PETSc.DM.
  • DMRestrictHookFunction — the restriction hook callback for PETSc.DM.
  • KSPRHSFunction — the right-hand side function callback for PETSc.KSP.
  • KSPOperatorsFunction — the operators function callback for PETSc.KSP.

...and bestie, these next ones are all about callbacks — the little functions you hand over so PETSc can call you back mid-solve. Every one of them lives in petsc4py.typing and points at a real class in petsc4py.PETSc. Collect them like Pokémon, no cap. 💅

  • KSPConvergenceTestFunction (petsc4py.typing.KSPConvergenceTestFunction) — the convergence test callback for PETSc.KSP. You decide when the solve is done-done. ✨
  • KSPMonitorFunction (petsc4py.typing.KSPMonitorFunction) — the PETSc.KSP monitor callback. It's giving "let me watch every iteration happen" energy. 👀
  • KSPPreSolveFunction (petsc4py.typing.KSPPreSolveFunction) — the PETSc.KSP pre solve callback. Runs before the solve, like a lil warmup. 🎀
  • KSPPostSolveFunction (petsc4py.typing.KSPPostSolveFunction) — the PETSc.KSP post solve callback. Cleanup era. 🧹
  • SNESMonitorFunction (petsc4py.typing.SNESMonitorFunction) — the SNES monitor callback. Same vibe as the KSP one but make it nonlinear. 🔥
  • SNESObjFunction (petsc4py.typing.SNESObjFunction) — the SNES objective function callback. The thing you're trying to minimize, bestie. 📉
  • SNESFunction (petsc4py.typing.SNESFunction) — the SNES residual function callback. Your F(x), iconic since forever. ⭐
  • SNESJacobianFunction (petsc4py.typing.SNESJacobianFunction) — the SNES Jacobian callback. All the derivatives, slay. 🌈
  • SNESGuessFunction (petsc4py.typing.SNESGuessFunction) — the SNES initial guess callback. First impression matters, fr fr. 🦋
  • SNESUpdateFunction (petsc4py.typing.SNESUpdateFunction) — the SNES step update callback. Keeping the step in check. 💜
  • SNESLSPreFunction (petsc4py.typing.SNESLSPreFunction) — the SNES linesearch pre-check update callback. Line search said "hold on, let me verify." 🙈
  • SNESNGSFunction (petsc4py.typing.SNESNGSFunction) — the SNES nonlinear Gauss-Seidel callback. NGS girlies rise. 👑
  • SNESConvergedFunction (petsc4py.typing.SNESConvergedFunction) — the SNES convergence test callback. Are we there yet? You decide. ✨
  • TSRHSFunction (petsc4py.typing.TSRHSFunction) — the TS right-hand side function callback. Time to compute the RHS. ⏰
  • TSRHSJacobian (petsc4py.typing.TSRHSJacobian) — the TS right-hand side Jacobian callback. RHS but with derivatives. 💅
  • TSRHSJacobianP (petsc4py.typing.TSRHSJacobianP) — the TS right-hand side parameter Jacobian callback. Derivatives, but w.r.t. the parameters this time. 🎀
  • TSIFunction (petsc4py.typing.TSIFunction) — the TS implicit function callback. F(t, u, u̇) said hi. 🌸
  • TSIJacobian (petsc4py.typing.TSIJacobian) — the TS implicit Jacobian callback. The implicit vibe, differentiated. 🌈
  • TSIJacobianP (petsc4py.typing.TSIJacobianP) — the TS implicit parameter Jacobian callback. Parameters getting their own Jacobian, periodt. 💜
  • TSI2Function (petsc4py.typing.TSI2Function) — the TS implicit 2nd order function callback. Second order said "I'm the moment." 👑
  • TSI2Jacobian (petsc4py.typing.TSI2Jacobian) — the TS implicit 2nd order Jacobian callback. 2nd order, now with derivatives. 🔥
  • TSI2JacobianP (petsc4py.typing.TSI2JacobianP) — the TS implicit 2nd order parameter Jacobian callback. 2nd order and parameter-aware, highkey extra. ✨
  • TSMonitorFunction (petsc4py.typing.TSMonitorFunction) — the TS monitor callback. Watching the timesteps go by like a livestream. 📺
  • TSPreStepFunction (petsc4py.typing.TSPreStepFunction) — the TS pre-step callback. Before each step, do the thing. 🎀
  • TSPostStepFunction (petsc4py.typing.TSPostStepFunction) — the TS post-step callback. After each step, debrief. 🧚
  • TSIndicatorFunction (petsc4py.typing.TSIndicatorFunction) — the TS event indicator callback. Ooh, something's about to happen. 🚨
  • TSPostEventFunction (petsc4py.typing.TSPostEventFunction) — the TS post-event callback. The event happened, now handle it. 💖
Pro tip from your girl: reach for these when you want custom behaviour instead of letting PETSc do its default thing. The typing module just names them so your type hints stay cute and your editor stops side-eyeing you. 😌

…and the table keeps going, bestie, don't scroll away yet:

  • TAOObjectiveFunction (petsc4py.typing.TAOObjectiveFunction) — TAO petsc4py.PETSc.TAO objective function callback. 💖
  • TAOGradientFunction (petsc4py.typing.TAOGradientFunction) — TAO petsc4py.PETSc.TAO objective gradient callback. ✨
  • TAOObjectiveGradientFunction (petsc4py.typing.TAOObjectiveGradientFunction) — TAO petsc4py.PETSc.TAO objective function and gradient callback. 🎀
  • TAOHessianFunction (petsc4py.typing.TAOHessianFunction) — TAO petsc4py.PETSc.TAO objective Hessian callback. 🦋
  • TAOUpdateFunction (petsc4py.typing.TAOUpdateFunction) — TAO petsc4py.PETSc.TAO update callback. 🌸
  • TAOMonitorFunction (petsc4py.typing.TAOMonitorFunction) — TAO petsc4py.PETSc.TAO monitor callback. 💅
  • TAOConvergedFunction (petsc4py.typing.TAOConvergedFunction) — TAO petsc4py.PETSc.TAO convergence test callback. 🫶
  • TAOJacobianFunction (petsc4py.typing.TAOJacobianFunction) — TAO petsc4py.PETSc.TAO Jacobian callback. 😭
  • TAOResidualFunction (petsc4py.typing.TAOResidualFunction) — TAO petsc4py.PETSc.TAO residual callback. 🔥
  • TAOJacobianResidualFunction (petsc4py.typing.TAOJacobianResidualFunction) — TAO petsc4py.PETSc.TAO Jacobian residual callback. 👑
  • TAOVariableBoundsFunction (petsc4py.typing.TAOVariableBoundsFunction) — TAO petsc4py.PETSc.TAO variable bounds callback. 🌈
  • TAOConstraintsFunction (petsc4py.typing.TAOConstraintsFunction) — TAO petsc4py.PETSc.TAO constraints callback. ⭐
  • TAOConstraintsJacobianFunction (petsc4py.typing.TAOConstraintsJacobianFunction) — TAO petsc4py.PETSc.TAO constraints Jacobian callback. 💀
  • TAOLSObjectiveFunction (petsc4py.typing.TAOLSObjectiveFunction) — TAOLineSearch petsc4py.PETSc.TAOLineSearch objective function callback. 🙈
  • TAOLSGradientFunction (petsc4py.typing.TAOLSGradientFunction) — TAOLineSearch petsc4py.PETSc.TAOLineSearch objective gradient callback. 🍓
  • TAOLSObjectiveGradientFunction (petsc4py.typing.TAOLSObjectiveGradientFunction) — TAOLineSearch petsc4py.PETSc.TAOLineSearch objective function and gradient callback. 🧚

✨ petsc4py.typing.Scalar ✨

petsc4py.typing.Scalar = float | complex

Scalar type, periodt. 💜

Scalars can be either float (https://docs.python.org/3/builtins/functions.html#float) or complex (https://docs.python.org/3/builtins/functions.html#complex) (but not both, ok? 💀) depending on how PETSc was configured (./configure --with-scalar-type=real|complex).

🌸 petsc4py.typing.ArrayBool 🌸

petsc4py.typing.ArrayBool

Array of bool (https://docs.python.org/3/builtins/functions.html#bool).

alias of ndarray (https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)[tuple (https://docs.python.org/3/builtins/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)]]

💅 petsc4py.typing.ArrayInt 💅

petsc4py.typing.ArrayInt

Array of int (https://docs.python.org/3/builtins/functions.html#int).

alias of ndarray (https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)[tuple (https://docs.python.org/3/builtins/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)[integer (https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.integer)]]

🦋 petsc4py.typing.ArrayReal 🦋

petsc4py.typing.ArrayReal

Array of float (https://docs.python.org/3/builtins/functions.html#float).

alias of ndarray (https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)[tuple (https://docs.python.org/3/builtins/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)[floating (https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.floating)]]

🎀 petsc4py.typing.ArrayComplex 🎀

petsc4py.typing.ArrayComplex

Array of complex (https://docs.python.org/3/builtins/functions.html#complex).

alias of ndarray (https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)[tuple (https://docs.python.org/3/builtins/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)[complexfloating (https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.complexfloating)]]

🌈 petsc4py.typing.ArrayScalar 🌈

petsc4py.typing.ArrayScalar

Array of Scalar (petsc4py.typing.Scalar) numbers. 💖

alias of ndarray (https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)[tuple (https://docs.python.org/3/builtins/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)[floating (https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.floating) | complexfloating (https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.complexfloating)]]

⭐ petsc4py.typing.DimsSpec ⭐

petsc4py.typing.DimsSpec

Dimensions specification.

N-tuples indicates N-dimensional grid sizes.

alias of tuple (https://docs.python.org/3/builtins/stdtypes.html#tuple)[int (https://docs.python.org/3/builtins/functions.html#int), ...]

👑 petsc4py.typing.AccessModeSpec 👑

petsc4py.typing.AccessModeSpec = typing.Literal['rw', 'r', 'w'] | None

Access mode specification.

Possible values are:

  • 'rw' — Read-Write mode. 💅
  • 'r' — Read-only mode. 📖
  • 'w' — Write-only mode. ✍️
  • None as 'rw'.

💖 petsc4py.typing.InsertModeSpec 💖

petsc4py.typing.InsertModeSpec: TypeAlias = petsc4py.PETSc.InsertMode | bool | None (link: https://docs.python.org/3/library/typing.html#typing.TypeAlias)

okay so this is the insert-mode spec — it's literally how you tell PETSc what vibe you're on when new values come knockin'. Possible values, bestie:

See also: InsertMode (#petsc4py.PETSc.InsertMode) 💅

🦋 petsc4py.typing.ScatterModeSpec 🦋

petsc4py.typing.ScatterModeSpec: TypeAlias = petsc4py.PETSc.ScatterMode | bool | str | None (link: https://docs.python.org/3/library/typing.html#typing.TypeAlias)

scatter mode spec, and yes she takes strings too, she's flexible like that 💁‍♀️. Possible values:

See also: ScatterMode (#petsc4py.PETSc.ScatterMode) ✨

🎀 petsc4py.typing.LayoutSizeSpec 🎀

petsc4py.typing.LayoutSizeSpec: TypeAlias = int | tuple[int, int] (link: https://docs.python.org/3/library/typing.html#typing.TypeAlias)

an int (https://docs.python.org/3/builtins/functions.html#int) or a 2-tuple (https://docs.python.org/3/builtins/stdtypes.html#tuple) of int (https://docs.python.org/3/builtins/functions.html#int) describing the layout sizes. periodt.

See also: Sys.splitOwnership (#petsc4py.PETSc.Sys.splitOwnership) 🫶

🌸 petsc4py.typing.NormTypeSpec 🌸

petsc4py.typing.NormTypeSpec: TypeAlias = petsc4py.PETSc.NormType | None (link: https://docs.python.org/3/library/typing.html#typing.TypeAlias)

norm type specification. the possible values include:

  • NormType.NORM_1 — the 1-norm: Σₙ abs(xₙ) for vectors, maxₙ (Σᵢ abs(xₙᵢ)) for matrices. (ref: #petsc4py.PETSc.NormType.NORM_1)
  • NormType.NORM_2 — the 2-norm: √(Σₙ xₙ²) for vectors, largest singular values for matrices. (ref: #petsc4py.PETSc.NormType.NORM_2)
  • NormType.NORM_INFINITY — the ∞-norm: maxₙ abs(xₙ) for vectors, maxᵢ (Σₙ abs(xₙᵢ)) for matrices. (ref: #petsc4py.PETSc.NormType.NORM_INFINITY)
  • NormType.NORM_FROBENIUS — the Frobenius norm: same as 2-norm for vectors, √(Σₙᵢ xₙᵢ²) for matrices. (ref: #petsc4py.PETSc.NormType.NORM_FROBENIUS)
  • NormType.NORM_1_AND_2 — compute both NormType.NORM_1 and NormType.NORM_2. (ref: #petsc4py.PETSc.NormType.NORM_1_AND_2)
  • None — treated as NormType.NORM_2 for vectors, and NormType.NORM_FROBENIUS for matrices. (ref: https://docs.python.org/3/builtins/constants.html#None)

See also: PETSc.NormType (#petsc4py.PETSc.NormType), NormType (https://petsc.org/release/manualpages/Vec/NormType.html) 💜

🍓 petsc4py.typing.PetscOptionsHandlerFunction 🍓

petsc4py.typing.PetscOptionsHandlerFunction

callback for processing extra options. it's the lil function PETSc calls when there's more options to chew through.

alias of Callable (https://docs.python.org/3/library/typing.html#typing.Callable)[[Object (#petsc4py.PETSc.Object)], None (https://docs.python.org/3/builtins/constants.html#None)]

🔥 petsc4py.typing.MatAssemblySpec 🔥

petsc4py.typing.MatAssemblySpec: TypeAlias = petsc4py.PETSc.Mat.AssemblyType | bool | None (link: https://docs.python.org/3/library/typing.html#typing.TypeAlias)

matrix assembly specification. possible values:

See also: MatAssemblyType (https://petsc.org/release/manualpages/Mat/MatAssemblyType.html) 👑

🌈 petsc4py.typing.MatSizeSpec 🌈

petsc4py.typing.MatSizeSpec: TypeAlias = int | tuple[int, int] | tuple[tuple[int, int], tuple[int, int]] (link: https://docs.python.org/3/library/typing.html#typing.TypeAlias)

an int (https://docs.python.org/3/builtins/functions.html#int) or a (nested) tuple (https://docs.python.org/3/builtins/stdtypes.html#tuple) of int (https://docs.python.org/3/builtins/functions.html#int) describing the matrix sizes. here's the tea:

See also: Sys.splitOwnership (#petsc4py.PETSc.Sys.splitOwnership) ⭐

💅 petsc4py.typing.MatBlockSizeSpec 💅

petsc4py.typing.MatBlockSizeSpec: TypeAlias = int | tuple[int, int] (link: https://docs.python.org/3/library/typing.html#typing.TypeAlias)

the row and column block sizes, bestie. if you hand it a single int (https://docs.python.org/3/builtins/functions.html#int), then rows and columns share the same block size. matching! cute. 🎀

🧚 petsc4py.typing.CSRIndicesSpec 🧚

petsc4py.typing.CSRIndicesSpec

CSR indices format specification. a 2-tuple carrying the (row_start, col_indices) information.

alias of tuple (https://docs.python.org/3/builtins/stdtypes.html#tuple)[Sequence (https://docs.python.org/3/library/typing.html#typing.Sequence)[int (https://docs.python.org/3/builtins/functions.html#int)], Sequence (https://docs.python.org/3/library/typing.html#typing.Sequence)[int (https://docs.python.org/3/builtins/functions.html#int)]]

💀 petsc4py.typing.CSRSpec 💀

petsc4py.typing.CSRSpec

CSR format specification. a 3-tuple carrying the (row_start, col_indices, values) information. yes she ate with that third slot.

alias of tuple (https://docs.python.org/3/builtins/stdtypes.html#tuple)[Sequence (https://docs.python.org/3/library/typing.html#typing.Sequence)[int (https://docs.python.org/3/builtins/functions.html#int)], Sequence (https://docs.python.org/3/library/typing.html#typing.Sequence)[int (https://docs.python.org/3/builtins/functions.html#int)], Sequence (https://docs.python.org/3/library/typing.html#typing.Sequence)[float (https://docs.python.org/3/builtins/functions.html#float) | complex (https://docs.python.org/3/builtins/functions.html#complex)]]

🎀 petsc4py.typing.NNZSpec 🎀

petsc4py.typing.NNZSpec: TypeAlias = int | typing.Sequence[int] | tuple[typing.Sequence[int], typing.Sequence[int]] (link: https://docs.python.org/3/library/typing.html#typing.TypeAlias)

nonzero pattern specification. lowkey the most practical one:

See also: MatSeqAIJSetPreallocation (https://petsc.org/release/manualpages/Mat/MatSeqAIJSetPreallocation.html), MatMPIAIJSetPreallocation (https://petsc.org/release/manualpages/Mat/MatMPIAIJSetPreallocation.html) 🦋

🌟 petsc4py.typing.MatNullFunction 🌟

petsc4py.typing.MatNullFunction

PETSc.NullSpace (#petsc4py.PETSc.NullSpace) callback.

alias of Callable (https://docs.python.org/3/library/typing.html#typing.Callable)[[NullSpace (#petsc4py.PETSc.NullSpace), Vec (#petsc4py.PETSc.Vec)], None (https://docs.python.org/3/builtins/constants.html#None)]

🫶 petsc4py.typing.MatHtoolKernelFunction 🫶

petsc4py.typing.MatHtoolKernelFunction

PETSc.Mat (#petsc4py.PETSc.Mat) Mat.Type.HTOOL (#petsc4py.PETSc.Mat.Type.HTOOL) kernel callback. that's it, that's the whole job — she just shows up and does kernel things. iconic. 💖

okay so real quick, whoever wrote this entry clearly had opinions about how thorough a signature should be, and honestly? obsessed. continuing where we left off — this is the callable your kernel needs to match, and the vibes are extremely specific:

kernel(sdim, M, N, rows, cols, v, ctx)
  • sdim — how many spatial dimensions the coordinate space has. that's it, that's the whole job 💅
  • M — number of target (a.k.a. row) indices
  • N — number of source (a.k.a. column) indices
  • rows — the target global indices, shaped (M,)
  • cols — the source global indices, shaped (N,)
  • v — the output submatrix, shaped (M, N), in column-major order, and you have to fill it in. this is your moment, bestie, the main character assignment 🫶
  • ctx — whatever user-defined context you handed over to Mat.createHtoolFromKernel. it's yours, do what you want with it ✨

and for the people who need the formal receipts, it's officially an alias of:

Callable[[int, int, int, ndarray[tuple[Any, ...], dtype[integer]], ndarray[tuple[Any, ...], dtype[integer]], ndarray[tuple[Any, ...], dtype[floating | complexfloating]], Any], None]

like, look at that annotation. the floating | complexfloating union alone is giving range. 🌈

petsc4py.typing.DMCoarsenHookFunction

PETSc.DM coarsening hook callback. when your DM wants to know how the coarsening should go, it calls this and waits for your answer 💖

alias of:

Callable[[DM, DM], None]

two DMs in, absolutely nothing out. iconically simple.

petsc4py.typing.DMRestrictHookFunction

PETSc.DM restriction hook callback. the restriction step needs a vibe check from you before it proceeds.

alias of:

Callable[[DM, Mat, Vec, Mat, DM], None]

yeah it's five arguments. no I will not be explaining why, that's just what it is 🫠

petsc4py.typing.KSPRHSFunction

PETSc.KSP right-hand side function callback.

alias of:

Callable[[KSP, Vec], None]

petsc4py.typing.KSPOperatorsFunction

PETSc.KSP operators function callback. it's here to hand you the operators, not to do your homework.

alias of:

Callable[[KSP, Mat, Mat], None]

petsc4py.typing.KSPConvergenceTestFunction

PETSc.KSP convergence test callback — the one that decides whether we're done or we keep going 😭 yes it's a lot of responsibility, no you cannot opt out.

alias of:

Callable[[KSP, int, float], ConvergedReason]

notice it returns a ConvergedReason, not None. it's literally built different.

petsc4py.typing.KSPMonitorFunction

PETSc.KSP monitor callback — your little window into the iteration drama as it unfolds 👀

alias of:

Callable[[KSP, int, float], None]

petsc4py.typing.KSPPreSolveFunction

PETSc.KSP pre solve callback. runs before the solve. hence the name. groundbreaking, I know 💅

alias of:

Callable[[KSP, Vec, Vec], None]

petsc4py.typing.KSPPostSolveFunction

PETSc.KSP post solve callback. runs after the solve. the symmetry is honestly gorgeous, no cap.

alias of:

Callable[[KSP, Vec, Vec], None]

petsc4py.typing.SNESMonitorFunction

SNES monitor callback. watch the Newton iterations do their thing in real time 🦋

alias of:

Callable[[SNES, int, float], None]

petsc4py.typing.SNESObjFunction

SNES objective function callback.

alias of:

Callable[[SNES, Vec], None]

petsc4py.typing.SNESFunction

SNES residual function callback — arguably the whole point of the operation, lowkey.

alias of:

Callable[[SNES, Vec, Vec], None]

petsc4py.typing.SNESJacobianFunction

SNES Jacobian callback. yes that Jacobian. the matrix one. not a person, bestie 😭

alias of:

Callable[[SNES, Vec, Mat, Mat], None]

petsc4py.typing.SNESGuessFunction

SNES initial guess callback — your one chance to be helpful right at the start, so make it count 🌸

alias of:

Callable[[SNES, Vec], None]

petsc4py.typing.SNESUpdateFunction

SNES step update callback. keeps the iteration count in the loop.

alias of:

Callable[[SNES, int], None]

petsc4py.typing.SNESLSPreFunction

SNES linesearch pre-check update callback. fun fact: this one takes no SNES at all, just two Vecs. it woke up and chose independence ✨

alias of:

Callable[[Vec, Vec], None]

petsc4py.typing.SNESNGSFunction

SNES nonlinear Gauss-Seidel callback.

alias of:

Callable[[SNES, Vec, Vec], None]

petsc4py.typing.SNESConvergedFunction

SNES convergence test callback. same energy as the KSP one but it gets a whole tuple of three floats to judge you by 🙈

alias of:

Callable[[SNES, int, tuple[float, float, float]], ConvergedReason]

petsc4py.typing.TSRHSFunction

TS right-hand side function callback. time stepping said "here, you handle the derivative" 🕐

alias of:

Callable[[TS, float, Vec, Vec], None]

petsc4py.typing.TSRHSJacobian

TS right-hand side Jacobian callback.

alias of:

Callable[[TS, float, Vec, Mat, Mat], None]

and that's the whole typing catalogue, fr fr. every last Callable[...] accounted for, nothing skipped, nothing faked. if you ever forget which arg comes first, just scroll back up — the receipts are literally right here 💜

still more to come, so don't go anywhere 🌟

petsc4py.typing.TSRHSJacobianP</p>

okay so this one is the TS right-hand side parameter Jacobian callback 💖 it's literally just an alias of:

Callable[[TS, float, Vec, Mat], None]

petsc4py.typing.TSIFunction</p>

the TS implicit function callback ✨ alias of:

Callable[[TS, float, Vec, Vec, Vec], None]

petsc4py.typing.TSIJacobian</p>

the TS implicit Jacobian callback 🎀 alias of:

Callable[[TS, float, Vec, Vec, float, Mat, Mat], None]

petsc4py.typing.TSIJacobianP</p>

the TS implicit parameter Jacobian callback 🦋 alias of:

Callable[[TS, float, Vec, Vec, float, Mat], None]

petsc4py.typing.TSI2Function</p>

the TS implicit 2nd order function callback 🌸 alias of:

Callable[[TS, float, Vec, Vec, Vec, Vec], None]

petsc4py.typing.TSI2Jacobian</p>

the TS implicit 2nd order Jacobian callback 💅 alias of:

Callable[[TS, float, Vec, Vec, Vec, float, float, Mat, Mat], None]

petsc4py.typing.TSI2JacobianP</p>

the TS implicit 2nd order parameter Jacobian callback 🫶 alias of:

Callable[[TS, float, Vec, Vec, Vec, float, float, Mat], None]

petsc4py.typing.TSMonitorFunction</p>

the TS monitor callback 😭 alias of:

Callable[[TS, int, float, Vec], None]

petsc4py.typing.TSPreStepFunction</p>

the TS pre-step callback 🔥 alias of:

Callable[[TS], None]

petsc4py.typing.TSPostStepFunction</p>

the TS post-step callback 👑 alias of:

Callable[[TS], None]

petsc4py.typing.TSIndicatorFunction</p>

the TS event indicator callback 🌈 alias of:

Callable[[TS, float, Vec, ndarray[tuple[Any, ...], dtype[floating]]], None]

petsc4py.typing.TSPostEventFunction</p>

the TS post-event callback ⭐ alias of:

Callable[[TS, ndarray[tuple[Any, ...], dtype[integer]], float, Vec, bool], None]

petsc4py.typing.TAOObjectiveFunction</p>

the TAO objective function callback 💀 alias of:

Callable[[TAO, Vec], float]

petsc4py.typing.TAOGradientFunction</p>

the TAO objective gradient callback 🙈 alias of:

Callable[[TAO, Vec, Vec], None]

petsc4py.typing.TAOObjectiveGradientFunction</p>

the TAO objective function and gradient callback 🍓 alias of:

Callable[[TAO, Vec, Vec], float]

petsc4py.typing.TAOHessianFunction</p>

the TAO objective Hessian callback 🧚 alias of:

Callable[[TAO, Vec, Mat, Mat], None]

petsc4py.typing.TAOUpdateFunction</p>

the TAO update callback 💜 alias of:

Callable[[TAO, int], None]

petsc4py.typing.TAOMonitorFunction</p>

the TAO monitor callback 💖 alias of:

Callable[[TAO], None]

petsc4py.typing.TAOConvergedFunction</p>

the TAO convergence test callback ✨ alias of:

Callable[[TAO], None]

petsc4py.typing.TAOJacobianFunction</p>

the TAO Jacobian callback 🎀 alias of:

Callable[[TAO, Vec, Mat, Mat], None]

petsc4py.typing.TAOResidualFunction</p>

the TAO residual callback 🦋 alias of:

Callable[[TAO, Vec, Vec], None]

petsc4py.typing.TAOJacobianResidualFunction</p>

the TAO Jacobian residual callback 🌸 and that's the vibe, bestie 💅

…and here's the alias that got cut off at the top of this part, in full:

alias of Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[TAO <#petsc4py.PETSc.TAO>, Vec <#petsc4py.PETSc.Vec>, Mat <#petsc4py.PETSc.Mat>, Mat <#petsc4py.PETSc.Mat>], None <https://docs.python.org/3/builtins/constants.html#None>]

So TAO slides you a TAO, a Vec and two Mats, and you hand back… nothing, bestie. None. That's the whole assignment 💅

petsc4py.typing.TAOVariableBoundsFunction

TAO variable bounds callback. This is the lil function you write so TAO knows what the lower and upper bounds on your variables are, okay?? It's giving "tell me the box, I'll stay in the box" 🎀

alias of Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[TAO <#petsc4py.PETSc.TAO>, Vec <#petsc4py.PETSc.Vec>, Vec <#petsc4py.PETSc.Vec>], None <https://docs.python.org/3/builtins/constants.html#None>]

So: a TAO, then the lower-bounds Vec, then the upper-bounds Vec, and you return None. Iconic. No notes.

petsc4py.typing.TAOConstraintsFunction

TAO constraints callback. Same energy as the bounds one but for constraints — you're the one filling in the constraint values fr fr 🦋

alias of Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[TAO <#petsc4py.PETSc.TAO>, Vec <#petsc4py.PETSc.Vec>, Vec <#petsc4py.PETSc.Vec>], None <https://docs.python.org/3/builtins/constants.html#None>]

TAO, one Vec, another Vec, None back. Same shape as the bounds callback, different job. Slay 🫶

petsc4py.typing.TAOConstraintsJacobianFunction

<c cyan>TAO constraints Jacobian callback.</c> You guessed it — this is where you cough up the Jacobian of those constraints, no cap 🧚

alias of Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[TAO <#petsc4py.PETSc.TAO>, Vec <#petsc4py.PETSc.Vec>, Mat <#petsc4py.PETSc.Mat>, Mat <#petsc4py.PETSc.Mat>], None <https://docs.python.org/3/builtins/constants.html#None>]

TAO, a Vec, then two Mats, and None on the way out. Two matrices bestie. That's the assignment 🔥

petsc4py.typing.TAOLSObjectiveFunction

TAOLineSearch objective function callback. Line search wants the objective value, and you're the one computing it. Main character behavior, honestly ⭐

alias of Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[TAOLineSearch <#petsc4py.PETSc.TAOLineSearch>, Vec <#petsc4py.PETSc.Vec>], float <https://docs.python.org/3/builtins/functions.html#float>]

Note the vibe shift: it's a TAOLineSearch now, not a TAO, and you actually return a real float this time. Growth 💖

petsc4py.typing.TAOLSGradientFunction

TAOLineSearch objective gradient callback. Same line search, but now you're in charge of the gradient, and ngl this one's a classic 🌸

alias of Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[TAOLineSearch <#petsc4py.PETSc.TAOLineSearch>, Vec <#petsc4py.PETSc.Vec>, Vec <#petsc4py.PETSc.Vec>], None <https://docs.python.org/3/builtins/constants.html#None>]

TAOLineSearch, an input Vec, and the gradient Vec you fill in. Return None. Periodt.

petsc4py.typing.TAOLSObjectiveGradientFunction

TAOLineSearch objective function and gradient callback. Two for the price of one, bestie — value and gradient, one callback, zero complaints 🎀

alias of Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[TAOLineSearch <#petsc4py.PETSc.TAOLineSearch>, Vec <#petsc4py.PETSc.Vec>, Vec <#petsc4py.PETSc.Vec>], float <https://docs.python.org/3/builtins/functions.html#float>]

TAOLineSearch, the input Vec, the gradient Vec you fill, and a float back for the objective. Ate, no crumbs 💅

petsc4py.PETSc

Portable, Extensible Toolkit for Scientific Computation. Yes that's the whole toolkit, living in one module, and it's lowkey the reason we're all here 🔥

Basic constants

These are the four magic values you'll be throwing at PETSc parameters left and right:

  • DECIDE — Use a default value for an int or float parameter.
  • DEFAULT — Use a default value chosen by PETSc. Let the algorithm pick, so chic ✨
  • DETERMINE — Compute a default value for an int or float parameter. For tolerances this uses the default value from when the object's type was set. (iykyk 🧚)
  • CURRENT — Do not change the current value that is set. Staying exactly as you are? We love a stable queen 👑
  • UNLIMITED — For a parameter that is a bound, such as the maximum number of iterations, do not bound the value. Go off, no ceiling, literally 😭

More constants

The extreme-number department, because sometimes you need "very large" and you need it now:

  • INFINITY — Very large real value.
  • NINFINITY — Very large negative real value.
  • PINFINITY — Very large positive real value, same as INFINITY. Twins fr fr 💖

Classes 💖

okay bestie, here's the whole class roster — every single one, no skips, no cap. this is the main character energy you've been waiting for. 🫶

  • AO (petsc4py.PETSc.AO) — Application ordering object. ✨
  • CellDM (petsc4py.PETSc.CellDM) — CellDM object. 💅
  • Comm (petsc4py.PETSc.Comm) — Communicator object. 🦋
  • DM (petsc4py.PETSc.DM) — An object describing a computational grid or mesh. 🌸
  • DMComposite (petsc4py.PETSc.DMComposite) — A DM object that is used to manage data for a collection of DMs. 💖
  • DMDA (petsc4py.PETSc.DMDA) — A DM object that is used to manage data for a structured grid. ✨
  • DMInterpolation (petsc4py.PETSc.DMInterpolation) — Interpolation on a mesh. 🎀
  • DMLabel (petsc4py.PETSc.DMLabel) — An object representing a subset of mesh entities from a DM. 🫶
  • DMPlex (petsc4py.PETSc.DMPlex) — Encapsulate an unstructured mesh. 🔥
  • DMPlexTransform (petsc4py.PETSc.DMPlexTransform) — Mesh transformations. 👑
  • DMPlexTransformType (petsc4py.PETSc.DMPlexTransformType) — Transformation types. 🌈
  • DMShell (petsc4py.PETSc.DMShell) — A shell DM object, used to manage user-defined problem data. ⭐
  • DMStag (petsc4py.PETSc.DMStag) — A DM object representing a "staggered grid" or a structured cell complex. 💀
  • DMSwarm (petsc4py.PETSc.DMSwarm) — A DM object used to represent arrays of data (fields) of arbitrary type. 🙈
  • DS (petsc4py.PETSc.DS) — Discrete System object. 🍓
  • Device (petsc4py.PETSc.Device) — The device object. 🧚
  • DeviceContext (petsc4py.PETSc.DeviceContext) — DeviceContext object. 💜
  • DualSpace (petsc4py.PETSc.DualSpace) — Dual space to a linear space. 💖
  • FE (petsc4py.PETSc.FE) — A PETSc object that manages a finite element space. ✨
  • IS (petsc4py.PETSc.IS) — A collection of indices. 🎀
  • InsertMode (petsc4py.PETSc.InsertMode) — Insertion mode. 🦋
  • KSP (petsc4py.PETSc.KSP) — Abstract PETSc object that manages all Krylov methods. 🌸
  • KSPDMActive (petsc4py.PETSc.KSPDMActive) — Argument to KSPSetDMActive(). 💅
  • LGMap (petsc4py.PETSc.LGMap) — Mapping from a local to a global ordering. 🫶
  • Log (petsc4py.PETSc.Log) — Logging support. 🔥
  • LogClass (petsc4py.PETSc.LogClass) — Logging support. 👑
  • LogEvent (petsc4py.PETSc.LogEvent) — Logging support. 🌈
  • LogStage (petsc4py.PETSc.LogStage) — Logging support for different stages. ⭐
  • Mat (petsc4py.PETSc.Mat) — Matrix object. 💀
  • MatPartitioning (petsc4py.PETSc.MatPartitioning) — Object for managing the partitioning of a matrix or graph. 🙈
  • NormType (petsc4py.PETSc.NormType) — Norm type. 🍓
  • NullSpace (petsc4py.PETSc.NullSpace) — Nullspace object. 🧚

aaand bestie we're back in the roster 💖 last stretch of the big class table, stay with me

  • petsc4py.PETSc.Object — the base class that wraps a PETSc object. everyone else inherits from this one, it's giving founder energy 👑
  • petsc4py.PETSc.Options — the options database object 🗂️
  • petsc4py.PETSc.PC — preconditioners ✨
  • petsc4py.PETSc.Partitioner — a graph partitioner 🧩
  • petsc4py.PETSc.Quad — quadrature rule for integration 📐
  • petsc4py.PETSc.Random — the random number generator object 🎲
  • petsc4py.PETSc.Regressor — regression solver 📈
  • petsc4py.PETSc.RegressorLinearType — linear regressor type 📉
  • petsc4py.PETSc.SF — Star Forest object for communication 🌲 (yes it's literally called a star forest, and yes that's iconic)
  • petsc4py.PETSc.SNES — nonlinear equations solver 🌀
  • petsc4py.PETSc.SNESLineSearch — linesearch object used by SNES solvers 🔎
  • petsc4py.PETSc.Scatter — scatter object 🎯
  • petsc4py.PETSc.ScatterMode — scatter mode 🎯
  • petsc4py.PETSc.Section — mapping from integers in a range to an unstructured set of integers 🗺️
  • petsc4py.PETSc.Space — function space object 🌌
  • petsc4py.PETSc.Sys — system utilities ⚙️
  • petsc4py.PETSc.TAO — optimization solver 🎯
  • petsc4py.PETSc.TAOLineSearch — TAO Line Search 🔍
  • petsc4py.PETSc.TAOTerm — TAO Term 🏁
  • petsc4py.PETSc.TS — ODE integrator ⏳
  • petsc4py.PETSc.Vec — a vector object ➡️
  • petsc4py.PETSc.Viewer — viewer object 👀
  • petsc4py.PETSc.ViewerHDF5 — viewer object for HDF5 file formats 💾

okay slay, that's the whole table, and now we get into the actual per-class deets 🫶

🌸 petsc4py.PETSc.AO 🌸

class petsc4py.PETSc.AO

Bases: Object

Application ordering object. it's the thing that keeps your app's numbering and PETSc's numbering on speaking terms, like a lil translator bestie 🫶

Enumerations

  • Type — the application ordering types 💅

🦋 petsc4py.PETSc.AO.Type 🦋

class petsc4py.PETSc.AO.Type

Bases: object

The application ordering types. these are the vibes you can pick from when you're setting up your AO 🎀

Attributes Summary

  • ADVANCED — object ADVANCED of type str
  • BASIC — object BASIC of type str
  • MAPPING — object MAPPING of type str
  • MEMORYSCALABLE — object MEMORYSCALABLE of type str

Attributes Documentation

  • ADVANCED: str = ADVANCED — object ADVANCED of type str ✨
  • BASIC: str = BASIC — object BASIC of type str 💖
  • MAPPING: str = MAPPING — object MAPPING of type str 🌈
  • MEMORYSCALABLE: str = MEMORYSCALABLE — object MEMORYSCALABLE of type str 🔥

ngl those attribute names are pretty self-explanatory — they're just str values, four of them, and they live on AO.Type — and there's still SO much more coming so keep scrolling 💅✨

  • MEMORYSCALABLE: str — and its default value is MEMORYSCALABLE 💖 so yeah, an object named MEMORYSCALABLE, typed as str (that's str over here → https://docs.python.org/3/builtins/stdtypes.html#str). Iconic, no notes. ✨
  • __init__() — the constructor hook, no args, no drama. 🎀
  • classmethod __new__(*args, **kwargs) — a classmethod that takes *args, **kwargs. That's the whole vibe. 💅

✨ Methods Summary ✨

okay bestie here's the lil menu of everything this class can do, quick-scan edition 🫶

  • app2petsc(indices) — Map an application-defined ordering to the PETSc ordering.
  • createBasic(app[, petsc, comm]) — Return a basic application ordering using two orderings.
  • createMapping(app[, petsc, comm]) — Return an application mapping using two orderings.
  • createMemoryScalable(app[, petsc, comm]) — Return a memory scalable application ordering using two orderings.
  • destroy() — Destroy the application ordering.
  • getType() — Return the application ordering type.
  • petsc2app(indices) — Map a PETSc ordering to the application-defined ordering.
  • view([viewer]) — Display the application ordering.

📖 Methods Documentation 📖

app2petsc(indices)

Map an application-defined ordering to the PETSc ordering. 🗺️

Collective. (iykyk — everybody's in on this one, no solo missions 👑)

Any integers in indices that are negative are left unchanged. This allows one to convert, for example, neighbor lists that use negative entries to indicate nonexistent neighbors due to boundary conditions, etc. 🦋

Integers that are out of range are mapped to -1. 😭

If IS is used, it cannot be of type stride or block. 🚫

Parameters

Return type

Sequence <https://docs.python.org/3/library/typing.html#typing.Sequence>[int <https://docs.python.org/3/builtins/functions.html#int>] | IS <#petsc4py.PETSc.IS>

See also:

petsc2app, AOApplicationToPetscIS <https://petsc.org/release/manualpages/AO/AOApplicationToPetscIS.html>, AOApplicationToPetsc <https://petsc.org/release/manualpages/AO/AOApplicationToPetsc.html>

Source code at petsc4py/PETSc/AO.pyx:214 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/AO.pyx#L214>

createBasic(app, petsc=None, comm=None)

Return a basic application ordering using two orderings. 🌸

Collective.

The arrays/indices app and petsc must contain all the integers 0 to len(app)-1 with no duplicates; that is there cannot be any "holes" in the indices. Use createMapping if you wish to have "holes" in the indices. 🕳️

Parameters

Return type

Self <https://docs.python.org/3/library/typing.html#typing.Self>

See also:

createMemoryScalable, createMapping, AOCreateBasicIS <https://petsc.org/release/manualpages/AO/AOCreateBasicIS.html>, AOCreateBasic <https://petsc.org/release/manualpages/AO/AOCreateBasic.html>

Source code at petsc4py/PETSc/AO.pyx:53 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/AO.pyx#L53>

createMapping(app, petsc=None, comm=None)

Return an application mapping using two orderings. 🧚

Collective.

The arrays app and petsc need NOT contain all the integers 0 to len(app)-1, that is there CAN be "holes" in the indices. Use createBasic if they do not have holes for better performance. 🔥

Parameters

Return type

Self <https://docs.python.org/3/library/typing.html#typing.Self>

See also:

createBasic, AOCreateMappingIS <https://petsc.org/release/manualpages/AO/AOCreateMappingIS.html>, AOCreateMapping <https://petsc.org/release/manualpages/AO/AOCreateMapping.html>

Source code at petsc4py/PETSc/AO.pyx:154 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/AO.pyx#L154>

createMemoryScalable(app, petsc=None, comm=None)

Return a memory scalable application ordering using two orderings. 💜

Collective.

The arrays/indices app and petsc must contain all the integers 0 to len(app)-1 with no duplicates; that is there cannot be any "holes" in the indices. Use createMapping if you wish to have "holes" in the indices. 🕳️

Comparing with createBasic, this routine trades memory with message communication. ⚖️✨

Parameters

Return type: Self

See also: createBasic, createMapping, AOCreateMemoryScalableIS, AOCreateMemoryScalable

Source code at petsc4py/PETSc/AO.pyx:102

💀 destroy()

okay so this one destroys the application ordering. like, gone. bye bestie 💅

Collective. (so everybody in the crew has to call it together, no sneaking off alone 🙈)

See also: AODestroy

Source code at petsc4py/PETSc/AO.pyx:40

Return type: Self

✨ getType()

Returns the application ordering type. it's giving "who even are you" energy, but for an AO.

Not collective. so you can just casually ask, no group chat needed.

See also: AOGetType

Source code at petsc4py/PETSc/AO.pyx:200

Return type: str

🦋 petsc2app(indices)

Maps a PETSc ordering over to the application-defined ordering. glow up for your indices ✨

Collective.

okay here's the fine print bestie, and it matters:

  • any integers in indices that are negative are left completely unchanged — this is lowkey so useful because it lets you convert, like, neighbor lists that use negative entries to say "no neighbor here" bc boundary conditions or whatever 🌸
  • integers that are out of range get mapped to -1
  • if IS is used, it cannot be of type stride or block (no cap, it just can't 💀)

Parameters:

  • indices (Sequence[int] | IS) — the indices; they get replaced with their mapped values.

Return type: Sequence[int] | IS

See also: app2petsc, AOPetscToApplicationIS, AOPetscToApplication

Source code at petsc4py/PETSc/AO.pyx:248

🎀 view(viewer=None)

Displays the application ordering. show it off, main character energy 👑

Collective.

Parameters:

  • viewer (Viewer | None) — a Viewer to display the ordering in.

Return type: None

See also: AOView

Source code at petsc4py/PETSc/AO.pyx:21

__init__()

classmethod __new__(*args, **kwargs)

👑 petsc4py.PETSc.CellDM

class petsc4py.PETSc.CellDM

Bases: Object

the CellDM object. it's giving swarm-but-cell-shaped, iykyk.

See also: DMSwarmCellDM

🌈 Methods Summary

  • create(dm, fields, coords) — Create the cell DM.
  • destroy() — Destroy the cell DM.
  • getBlockSize(sw) — Return the block size for this cell DM.
  • getCellID() — Return the cellid field for this cell DM.
  • getCoordinateFields() — Return the swarm fields used as coordinates on this cell DM.
  • getDM() — Return the underlying DM.
  • getFields() — Return the swarm fields defined on this cell DM.
  • view([viewer]) — View the cell DM.

🧚 Methods Documentation

🍓 create(dm, fields, coords)

Creates the cell DM. brand new baby CellDM, periodt ✨

Collective.

Parameters:

  • dm (DM) — the underlying DM on which to place particles
  • fields (Sequence[str]) — the swarm fields represented on the DM
  • coords (Sequence[str]) — the swarm fields to use as coordinates in the DM

Return type: Self

See also: destroy, DMSwarmCellDMCreate

Source code at petsc4py/PETSc/DMSwarm.pyx:1122

💀 destroy()

Destroys the cell DM. bye diva 🫶

Collective.

See also: create, DMSwarmCellDMDestroy

Source code at petsc4py/PETSc/DMSwarm.pyx:1109

Return type: Self

⭐ getBlockSize(sw)

Returns the block size for this cell DM. it's giving "how chunky is this cell" fr fr.

Not collective.

Parameters:

  • sw (DM) — the DMSwarm object

Return type: int

See also: DMSwarmCellDMGetBlockSize

getCellID()

Returns the cellid field for this cell DM, bestie. That's the whole vibe. 🎀

Not collective — every process just does its own lil thing.

See also: DMSwarmCellDMGetCellID <https://petsc.org/release/manualpages/DMSwarm/DMSwarmCellDMGetCellID.html>

Source code at petsc4py/PETSc/DMSwarm.pyx:1196 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L1196>

Return type: str <https://docs.python.org/3/builtins/stdtypes.html#str>

getCoordinateFields()

Returns the swarm fields that get used as coordinates on this cell DM. so basically: which fields are the where am I fields. 📍

Not collective.

See also: DMSwarmCellDMGetCoordinateFields <https://petsc.org/release/manualpages/DMSwarm/DMSwarmCellDMGetCoordinateFields.html>

Source code at petsc4py/PETSc/DMSwarm.pyx:1233 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L1233>

Return type: list <https://docs.python.org/3/builtins/stdtypes.html#list>[str <https://docs.python.org/3/builtins/stdtypes.html#str>]

getDM()

Hands you back the underlying DM. The man behind the curtain, fr. 🧚

Not collective.

See also: DMSwarmCellDMGetDM <https://petsc.org/release/manualpages/DMSwarm/DMSwarmCellDMGetDM.html>

Source code at petsc4py/PETSc/DMSwarm.pyx:1165 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L1165>

Return type: DM <#petsc4py.PETSc.DM>

getFields()

Returns the swarm fields that are defined on this cell DM. All of 'em. The full roster. 👑

Not collective.

See also: DMSwarmCellDMGetFields <https://petsc.org/release/manualpages/DMSwarm/DMSwarmCellDMGetFields.html>

Source code at petsc4py/PETSc/DMSwarm.pyx:1215 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L1215>

Return type: list <https://docs.python.org/3/builtins/stdtypes.html#list>[str <https://docs.python.org/3/builtins/stdtypes.html#str>]

view(viewer=None)

View the cell DM. Show it off, let it be seen. 💅

Collective — everybody's in on this one, no solo acts.

Parameters:

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

See also: Viewer <#petsc4py.PETSc.Viewer>, DMSwarmCellDMView <https://petsc.org/release/manualpages/DMSwarm/DMSwarmCellDMView.html>

Source code at petsc4py/PETSc/DMSwarm.pyx:1090 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L1090>

__init__()

classmethod __new__(*args, **kwargs)

petsc4py.PETSc.Comm

class petsc4py.PETSc.Comm

Bases: object <https://docs.python.org/3/builtins/functions.html#object>

It's the communicator object. Like, the group chat itself, not just the messages. Everyone in it, everyone talking. 🫶

Predefined instances:

  • COMM_NULL <#petsc4py.PETSc.COMM_NULL> — the null (aka invalid) communicator. Not it. 🚫
  • COMM_SELF <#petsc4py.PETSc.COMM_SELF> — the self communicator. Just you, no thoughts, no others.
  • COMM_WORLD <#petsc4py.PETSc.COMM_WORLD> — the world communicator. Everybody. The main character. 🌍

See also: Sys.setDefaultComm <#petsc4py.PETSc.Sys.setDefaultComm>, Sys.getDefaultComm <#petsc4py.PETSc.Sys.getDefaultComm>

Methods Summary

  • barrier() — barrier synchronization.
  • destroy() — destroy the communicator.
  • duplicate() — duplicate the communicator.
  • getRank() — return the rank of the calling processes in the communicator.
  • getSize() — return the number of processes in the communicator.
  • tomp4py() — wait no bestie, it's tomp4py()... hold on — it's tomp4py()? Nope, the real one: tomp4py(). 🫠 Okay, deep breath, the actual name is tomp4py().
okay so I literally fumbled that one, the true name is tomp4py(). not me gaslighting myself. the real deal: tomp4py() — convert communicator to mpi4py <https://mpi4py.readthedocs.io/en/stable/mpi4py.html#module-mpi4py>. 🤝

(correction, bestie, the method is spelled tomp4py() — one i, no drama: tomp4py() converts the communicator to mpi4py <https://mpi4py.readthedocs.io/en/stable/mpi4py.html#module-mpi4py>.)

Okay for real, here's the clean list, no typos, I promise:

  • barrier() — barrier synchronization.
  • destroy() — destroy the communicator.
  • duplicate() — duplicate the communicator.
  • getRank() — return the rank of the calling processes in the communicator.
  • getSize() — return the number of processes in the communicator.
  • tomp4py() — convert communicator to mpi4py <https://mpi4py.readthedocs.io/en/stable/mpi4py.html#module-mpi4py>.

Attributes Summary

  • fortran — Fortran handle.
  • rank — communicator rank.
  • size — communicator size.

Methods Documentation

barrier()

Barrier synchronization. Everybody stops, everybody waits, then everybody goes. It's giving group-project energy but, like, functional. ✋

Collective.

Source code at petsc4py/PETSc/Comm.pyx:123 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Comm.pyx#L123>

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

destroy()

Destroys the communicator. Bye bestie, take care. 💀

Collective.

See also: PetscCommDestroy <https://petsc.org/release/manualpages/Sys/PetscCommDestroy.html>

Source code at petsc4py/PETSc/Comm.pyx:61 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Comm.pyx#L61>

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

duplicate()

Duplicate the communicator. Same vibe, brand new object. Slay. ✨

Collective.

See also: PetscCommDuplicate <https://petsc.org/release/manualpages/Sys/PetscCommDuplicate.html>

Source code at petsc4py/PETSc/Comm.pyx:79 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Comm.pyx#L79>

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

getRank()

Returns the rank of the calling processes in the communicator. Your number in the group chat. 🎫

Not collective.

Source code at petsc4py/PETSc/Comm.pyx:111 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Comm.pyx#L111>

Return type: int <https://docs.python.org/3/builtins/functions.html#int>

getSize()

Returns the number of processes in the communicator. Like, how many of us are here. 📊

Not collective.

Source code at petsc4py/PETSc/Comm.pyx:99 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Comm.pyx#L99>

Return type: int <https://docs.python.org/3/builtins/functions.html#int>

tomp4py()

Convert communicator to mpi4py <https://mpi4py.readthedocs.io/en/stable/mpi4py.html#module-mpi4py>. Translator duties. 🗣️

Not collective.

See also: mpi4py.MPI.Comm <https://mpi4py.readthedocs.io/en/stable/reference/mpi4py.MPI.Comm.html#mpi4py.MPI.Comm>, mpi4py.MPI.Intracomm <https://mpi4py.readthedocs.io/en/stable/reference/mpi4py.MPI.Intracomm.html#mpi4py.MPI.Intracomm>

Source code at petsc4py/PETSc/Comm.pyx:155 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Comm.pyx#L155>

Return type: Intracomm <https://mpi4py.readthedocs.io/en/stable/reference/mpi4py.MPI.Intracomm.html#mpi4py.MPI.Intracomm>

Attributes Documentation

fortran

Fortran handle.

(okay quick wrap-up from the last bit before we move on: that attribute's source code lives at petsc4py/PETSc/Comm.pyx:147 — tied off with a lil bow 🎀)

rank — Communicator rank.

Source code at petsc4py/PETSc/Comm.pyx:140.

size — Communicator size.

Source code at petsc4py/PETSc/Comm.pyx:135.

__init__()

classmethod __new__(*args, **kwargs)

👑 petsc4py.PETSc.DM

class petsc4py.PETSc.DM

Bases: Object

It's giving… "an object describing a computational grid or mesh." That's the whole vibe — a DM is literally the thing in PETSc that knows the shape of your problem. Obsessed. 🔥

Enumerations

  • BoundaryType — DM Boundary types.
  • PolytopeType — The DM cell types.
  • ReorderDefaultFlag — The DM reordering default flags.
  • Type — DM types.

🦋 petsc4py.PETSc.DM.BoundaryType

class petsc4py.PETSc.DM.BoundaryType

Bases: object

DM Boundary types. Slay.

Attributes Summary

  • GHOSTED — Constant GHOSTED of type int.
  • MIRROR — Constant MIRROR of type int.
  • NONE — Constant NONE of type int.
  • PERIODIC — Constant PERIODIC of type int.
  • TWIST — Constant TWIST of type int.

Attributes Documentation

GHOSTED: int = GHOSTED

Constant GHOSTED of type int. 💖

MIRROR: int = MIRROR

Constant MIRROR of type int. 🪞

NONE: int = NONE

Constant NONE of type int. (the "no boundaries, we're free" one)

PERIODIC: int = PERIODIC

Constant PERIODIC of type int. wraps around, no cap ✨

TWIST: int = TWIST

Constant TWIST of type int. she twisted fr 💅

__init__()

classmethod __new__(*args, **kwargs)

🧚 petsc4py.PETSc.DM.PolytopeType

class petsc4py.PETSc.DM.PolytopeType

Bases: object

The DM cell types. 👑

✨ Attributes Summary ✨

okay so this class is basically a whole lil dictionary of voxel/cell shape constants and every single one of them is just an int under the hood, no cap. here's the entire roster, in order:

📖 Attributes Documentation 📖

like, the full receipts on each one. every time we say int we mean that type, and every int here links back to https://docs.python.org/3/builtins/functions.html#int. periodt.

FV_GHOST: int = FV_GHOST

Constant FV_GHOST of type int (https://docs.python.org/3/builtins/functions.html#int) 👑

HEXAHEDRON: int = HEXAHEDRON

Constant HEXAHEDRON of type int (https://docs.python.org/3/builtins/functions.html#int) 👑

INTERIOR_GHOST: int = INTERIOR_GHOST

Constant INTERIOR_GHOST of type int (https://docs.python.org/3/builtins/functions.html#int) 👑

POINT: int = POINT

Constant POINT of type int (https://docs.python.org/3/builtins/functions.html#int) 👑

POINT_PRISM_TENSOR: int = POINT_PRISM_TENSOR

Constant POINT_PRISM_TENSOR of type int (https://docs.python.org/3/builtins/functions.html#int) 👑

PYRAMID: int = PYRAMID

Constant PYRAMID of type int (https://docs.python.org/3/builtins/functions.html#int) 👑

QUADRILATERAL: int = QUADRILATERAL

Constant QUADRILATERAL of type int (https://docs.python.org/3/builtins/functions.html#int) 👑

QUAD_PRISM_TENSOR: int = QUAD_PRISM_TENSOR

Constant QUAD_PRISM_TENSOR of type int (https://docs.python.org/3/builtins/functions.html#int) 👑

SEGMENT: int = SEGMENT

Constant SEGMENT of type int (https://docs.python.org/3/builtins/functions.html#int) 👑

SEG_PRISM_TENSOR: int = SEG_PRISM_TENSOR

Constant SEG_PRISM_TENSOR of type int (https://docs.python.org/3/builtins/functions.html#int) 👑

not me noticing the docs literally stop right there mid-roster 😭 the rest of these iconics are coming, bestie, don't you dare scroll away 💅

  • TETRAHEDRON: int = TETRAHEDRON — a constant, type int, and yes its value literally is TETRAHEDRON 💅
  • TRIANGLE: int = TRIANGLE — constant of type int, name and value matching, iconic behavior
  • TRI_PRISM: int = TRI_PRISM — constant of type int 🎀
  • TRI_PRISM_TENSOR: int = TRI_PRISM_TENSOR — constant of type int, she's giving tensor-product-triangular-prism realness
  • UNKNOWN: int = UNKNOWN — constant of type int, the "idk her" of the family 🌸
  • UNKNOWN_CELL: int = UNKNOWN_CELL — constant of type int
  • UNKNOWN_FACE: int = UNKNOWN_FACE — constant of type int 🦋

Then, the methods every one of these little darlings brings along:

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

✨ petsc4py.PETSc.DM.ReorderDefaultFlag ✨

class petsc4py.PETSc.DM.ReorderDefaultFlag

Bases: object

Bestie. It's the reordering default flags for the DM — like, the yes/no/maybe setting for whether a reorder even happens by default 💖

Attributes Summary

  • FALSE — constant of type int
  • NOTSET — constant of type int
  • TRUE — constant of type int

Attributes Documentation

  • FALSE: int = FALSE Constant FALSE of type int — hard no, no cap 🙅‍♀️
  • NOTSET: int = NOTSET Constant NOTSET of type int — the vibe is undecided, she contains multitudes
  • TRUE: int = TRUE Constant TRUE of type int — periodt, yes, do the reorder 👑

And the methods:

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

✨ petsc4py.PETSc.DM.Type ✨

class petsc4py.PETSc.DM.Type

Bases: object

DM types. Like, the roster of what kind of DM you got 🫶

okay bestie, vibe check: this table? Every. Single. Row. Is a str. No cap. The type is Python's str (https://docs.python.org/3/builtins/stdtypes.html#str), and the value of each one is literally its own name. That's the whole lore. 🎀

Not the docs making me read "Object SOMETHING of type str" fifteen times in a row 😭 but bestie, that IS what it says, and we keep every crumb of it. Periodt.

✨ ATTRIBUTES SUMMARY ✨

🦋 ATTRIBUTES DOCUMENTATION 🦋

Fifteen little string constants, all dressed up with the exact same glow-up. Each one is declared as its own name, typed as str, and its docstring is the shortest sentence in the game. Bestie, it's giving minimalism. 💅

💖 COMPOSITE

COMPOSITE: str = COMPOSITE — a str (https://docs.python.org/3/builtins/stdtypes.html#str) whose value is COMPOSITE. Docs say: Object COMPOSITE of type str. ✨

🌸 DA

DA: str = DA — a str (https://docs.python.org/3/builtins/stdtypes.html#str) whose value is DA. Docs say: Object DA of type str. ✨

🧚 FOREST

FOREST: str = FOREST — a str (https://docs.python.org/3/builtins/stdtypes.html#str) whose value is FOREST. Docs say: Object FOREST of type str. ✨

🍓 MOAB

MOAB: str = MOAB — a str (https://docs.python.org/3/builtins/stdtypes.html#str) whose value is MOAB. Docs say: Object MOAB of type str. ✨

🌈 NETWORK

NETWORK: str = NETWORK — a str (https://docs.python.org/3/builtins/stdtypes.html#str) whose value is NETWORK. Docs say: Object NETWORK of type str. ✨

🔥 P4EST

P4EST: str = P4EST — a str (https://docs.python.org/3/builtins/stdtypes.html#str) whose value is P4EST. Docs say: Object P4EST of type str. ✨

💀 P8EST

P8EST: str = P8EST — a str (https://docs.python.org/3/builtins/stdtypes.html#str) whose value is P8EST. Docs say: Object P8EST of type str. ✨

🎀 PATCH

PATCH: str = PATCH — a str (https://docs.python.org/3/builtins/stdtypes.html#str) whose value is PATCH. Docs say: Object PATCH of type str. ✨

👑 PLEX

PLEX: str = PLEX — a str (https://docs.python.org/3/builtins/stdtypes.html#str) whose value is PLEX. Docs say: Object PLEX of type str. ✨

🫶 PRODUCT

PRODUCT: str = PRODUCT — a str (https://docs.python.org/3/builtins/stdtypes.html#str) whose value is PRODUCT. Docs say: Object PRODUCT of type str. ✨

💜 REDUNDANT

REDUNDANT: str = REDUNDANT — a str (https://docs.python.org/3/builtins/stdtypes.html#str) whose value is REDUNDANT. Docs say: Object REDUNDANT of type str. ✨

⭐ SHELL

SHELL: str = SHELL — a str (https://docs.python.org/3/builtins/stdtypes.html#str) whose value is SHELL. Docs say: Object SHELL of type str. ✨

😭 SLICED

SLICED: str = SLICED — a str (https://docs.python.org/3/builtins/stdtypes.html#str) whose value is SLICED. Docs say: Object SLICED of type str. ✨

🙈 STAG

STAG: str = STAG — a str (https://docs.python.org/3/builtins/stdtypes.html#str) whose value is STAG. Docs say: Object STAG of type str. ✨

🦋 SWARM

SWARM: str = SWARM — a str (https://docs.python.org/3/builtins/stdtypes.html#str) whose value is SWARM. Docs say: Object SWARM of type str. ✨

and then, bestie, we get the two entries that aren't little string gremlins at all:

🌟 __init__()

That's the entire entry. Signature only, nothing else written down — it's giving mystery, it's giving "the docs said what they said and left." 🙈

🌟 classmethod __new__(*args, **kwargs)

Also just the signature, bestie. It's a classmethod, and it takes *args and **kwargs. That's the whole thing. No extra prose, no notes, no nothing. 👑

lowkey iconic that the constructors get less wordcount than the strings, but we don't editorialize, we just report. 💅

✨ Methods Summary ✨

okay so these are the DM methods, bestie — every single one, no cap 💖

  • adaptLabel(label) — Adapt a DM based on a DMLabel. It's giving custom-label energy, periodt. ✨
  • adaptMetric(metric[, bdLabel, rgLabel]) — Return a mesh adapted to the metric field you specify. You can also pass bdLabel and rgLabel if you want. 💅
  • addCoarsenHook(coarsenhook, restricthook[, ...]) — Add a callback to be executed when restricting to a coarser grid. The ... means there's more, iykyk. 🎀
  • addField(field[, label]) — Add a field to a DM object. Optionally slap a label on it. 🌸
  • appendOptionsPrefix(prefix) — Append to the prefix used for searching for options in the database. Stacking prefixes like it's nothing. 🦋
  • clearDS() — Remove all discrete systems from the DM. Yeet them, bestie. 👋
  • clearFields() — Remove all fields from the DM. Empty-field vibe check passed. 🧚
  • clearLabelStratum(name, value) — Remove all points from a stratum. Give it the name and value, and it's gone. 💜
  • clearLabelValue(name, point, value) — Remove a point from a DMLabel with the given value. You need name, point, and value. 🔥
  • clone() — Return the cloned DM. Identical twin energy, literally. 👯
  • coarsen([comm]) — Return a coarsened DM object. Optional comm if you're feeling fancy. 🌈
  • coarsenHierarchy(nlevels) — Coarsen this DM and return the coarsened DM hierarchy. Pass nlevels and watch the hierarchy serve. 👑
  • convert(dm_type) — Return a DM converted to another DM. Just hand over dm_type. ✨
  • copyDS(dm[, minDegree, maxDegree]) — Copy the discrete systems for this DM into another DM. Optional minDegree and maxDegree are there too. 💖
  • copyDisc(dm) — Copy fields and discrete systems of a DM into another DM. Full package deal. 🫶
  • copyFields(dm[, minDegree, maxDegree]) — Copy the discretizations of this DM into another DM. Optional minDegree and maxDegree. 🌟
  • create([comm]) — Return an empty DM. Blank canvas, optional comm, iconic. 🎨
  • createDS() — Create discrete systems. That's the whole vibe. 💅
  • createFieldDecomposition() — Return field splitting information. Decomposition tea, served. ☕
  • createGlobalVec() — Return a global vector. Global main character energy. 🌍
  • createInjection(dm) — Return the injection matrix into a finer DM. Injecting into the finer grid, no cap. 💉
  • createInterpolation(dm) — Return the interpolation matrix to a finer DM. Interpolate up, bestie. 🦋
  • createLabel(name) — Create a label of the given name if it does not already exist. No duplicates allowed. 🏷️
  • createLocalVec() — Return a local vector. Local vibes only. 🌸
  • createMassMatrix(dmf) — Return the mass matrix between this DM and the given DM. Pass dmf and get that mass matrix moment. 💖
  • createMat() — Return an empty matrix. Ready for your glow-up. ✨
  • createRestriction(dm) — Return the restriction matrix between this DM and the given DM. Restrict it, bestie. 🔥
  • createSectionSF(localsec, globalsec) — Create the SF encoding the parallel DOF overlap for the DM. You gotta pass localsec and globalsec. 💅
  • createSubDM(fields) — hands you back an IS (petsc4py.PETSc.IS) plus a DM that wraps up a subproblem. two-for-one deal, we love to see it 💖
  • destroy() — Destroy the object. it had a good run, now it's gone 💀
  • getAppCtx() — Return the application context. your lil' user data corner 🎀
  • getAuxiliaryVec([label, value, part]) — Return an auxiliary vector for region. side-quest vector energy ✨
  • getBasicAdjacency() — Return the flags for determining variable influence. who's influencing who, we must know 🦋
  • getBlockSize() — Return the inherent block size associated with a DM.
  • getBoundingBox() — Return the dimension of embedding space for coordinates values.
  • getCellCoordinateDM() — Return the cell coordinate DM.
  • getCellCoordinateSection() — Return the cell coordinate layout over the DM.
  • getCellCoordinates() — Return a global vector with the cellwise coordinates. global girlboss vibes 👑
  • getCellCoordinatesLocal() — Return a local vector with the cellwise coordinates. local queen, still iconic 🌸
  • getCoarseDM() — Return the coarse DM.
  • getCoarsenLevel() — Return the number of coarsenings. how many times did we level down, fr fr
  • getCoordinateDM() — Return the coordinate DM.
  • getCoordinateDim() — Return the dimension of embedding space for coordinates values.
  • getCoordinateSection() — Return coordinate values layout over the mesh.
  • getCoordinates() — Return a global vector with the coordinates associated. the whole squad's coordinates 🌈
  • getCoordinatesLocal() — Return a local vector with the coordinates associated. just your local besties' coordinates 🫶
  • getCoordinatesLocalized() — Check if the coordinates have been localized for cells. are they local yet? let's find out 🙈
  • getDS() — Return default DS petsc4py.PETSc.DS. the default, no cap 💅
  • getDimension() — Return the topological dimension of the DM.
  • getField(index) — Return the discretization object for a given DM field. hand over the field and you get the discretization obby ✨
  • getFieldAdjacency(field) — Return the flags for determining variable influence. same influence flags energy, but for a field 🔥
  • getGlobalSection() — Return the Section (petsc4py.PETSc.Section) encoding the global data layout for the DM.
  • getGlobalVec([name]) — Return a global vector. optional name if you're feeling fancy 🎀
  • getLGMap() — Return local mapping to global mapping. little-to-big translation, lowkey essential 🧚
  • getLabel(name) — Return the label of a given name. name in, label out, slay 💜
  • getLabelIdIS(name) — Return an IS (petsc4py.PETSc.IS) of all values that the DMLabel (petsc4py.PETSc.DMLabel) takes. every value it's ever taken, gathered up 💖
  • getLabelName(index) — Return the name of nth
  • getLabelOutput(name) — hands you the output flag for whatever label you pass as name. Simple, one job, does it 💅
  • getLabelSize(name) — the number of values that the DMLabel <#petsc4py.PETSc.DMLabel> actually takes. Count 'em, bestie 🔢
  • getLabelValue(name, point) — the value sitting in that DMLabel <#petsc4py.PETSc.DMLabel> for the given point. Like checking what a specific spot is labeled as 🏷️
  • getLocalBoundingBox() — the bounding box for your piece of the DM, just the local chunk, not the whole thing ✨
  • getLocalSection() — the Section <#petsc4py.PETSc.Section> that encodes the local data layout for the DM. Local layout, local business 🫶
  • getLocalVec([name]) — returns you a local vector. Name it if you want, name is optional 💖
  • getNumFields() — how many fields are chillin' in the DM 🌸
  • getNumLabels() — how many labels are defined on the DM 👑
  • getOptionsPrefix() — the prefix it uses when searching for options in the options database 🔎
  • getPeriodicity() — the description of mesh periodicity. (ngl the one-liner literally says "Set the description of mesh periodicity" for a getter, and I'm just relaying it fr fr 🙈)
  • getPointSF() — the SF <#petsc4py.PETSc.SF> that encodes the parallel DOF overlap for the DM 🦋
  • getRefineLevel() — the refinement level, as requested ⭐
  • getSectionSF() — the Section <#petsc4py.PETSc.Section> encoding the parallel DOF overlap. Yes, another SF-adjacent situation, no cap 🫠
  • getSparseLocalize() — tells you if coordinates should only be localized at the boundary 💅
  • getStratumIS(name, value) — the points in a label stratum. Give it the label name and the value, get points back 🌈
  • getStratumSize(name, value) — the number of points in a label stratum. Same vibe, but a count, not an index set ✨
  • getType() — the DM type name. Who are you, what's your type, DM edition 💀
  • getUseNatural() — the flag for constructing a global-to-natural map. Gets it, doesn't set it 🎀
  • globalToLocal(vg, vl[, addv]) — updates your local vectors from a global vector. vg goes in, vl comes out, and addv is optional ([, addv]) in case you're adding instead of overwriting 🔥
  • hasLabel(name) — a lil yes/no: does this DM have a label called name? vibe check on the label 🕵️
  • load(viewer) — pulls back a DM that was stored in binary, read in through the viewer 📦
  • localToGlobal(vl, vg[, addv]) — updates global vectors from a local vector. Reverse direction, same energy, optional [, addv] 🦋
  • localToLocal(vl, vlg[, addv]) — maps values from one local vector to another local vector. Local to local, no global detour, optional [, addv] 💫
  • localizeCoordinates() — creates local coordinates for cells that have periodic faces. Periodic girlies, this one's for you 🌸
  • refine([comm]) — returns a refined DM object. comm is optional, slay ✨
  • refineHierarchy(nlevels) — refines this DM and hands back the refined DM hierarchy, nlevels deep. Whole glow-up tree 👑
  • removeLabel(name) — removes and destroys the label by name. Gone, deleted, not coming back 💀
  • restoreGlobalVec(vg[, name]) — Restore a global vector you snagged from getGlobalVec. 💖
  • restoreLocalVec(vl[, name]) — Restore a local vector you got with getLocalVec. ✨
  • setAppCtx(appctx) — Set the application context. 🎀
  • setAuxiliaryVec(aux, label[, value, part]) — Set an auxiliary vector for a specific region. 🦋
  • setBasicAdjacency(useCone, useClosure) — Set the flags for determining variable influence. 🌸
  • setCellCoordinateDM(dm) — Set the cell coordinate DM. 💅
  • setCellCoordinateSection(dim, sec) — Set the cell coordinate layout over the DM. 🫶
  • setCellCoordinates(c) — Set a global vector with the cellwise coordinates. 😭
  • setCellCoordinatesLocal(c) — Set a local vector with the cellwise coordinates. 🔥
  • setCoarseDM(dm) — Set the coarse DM. 👑
  • setCoordinateDim(dim) — Set the dimension of embedding space for coordinates values. 🌈
  • setCoordinateDisc(disc, localized, project) — Project coordinates to a different space. ⭐
  • setCoordinates(c) — Set a global vector that holds the coordinates. 💀
  • setCoordinatesLocal(c) — Set a local vector with the ghost point holding the coordinates. 🙈
  • setDimension(dim) — Set the topological dimension of the DM. 🍓
  • setField(index, field[, label]) — Set the discretization object for a given DM field. 🧚
  • setFieldAdjacency(field, useCone, useClosure) — Set the flags for determining variable influence. 💜
  • setFromOptions() — Configure the object from the options database. ✨
  • setGlobalSection(sec) — Set the Section <#petsc4py.PETSc.Section> encoding the global data layout for the DM. 💖
  • setKSPComputeOperators(operators[, args, kargs]) — Matrix associated with the linear system. 🎀
  • setLabelOutput(name, output) — Set if a given label should be saved to a view. 🦋
  • setLabelValue(name, point, value) — Set a point to a DMLabel <#petsc4py.PETSc.DMLabel> with a given value. 🌸
  • setLocalSection(sec) — Set the Section <#petsc4py.PETSc.Section> encoding the local data layout for the DM. 💅
  • setMatType(mat_type) — Set matrix type to be used by DM.createMat. 🫶
  • setNumFields(numFields) — Set the number of fields in the DM. 😭
  • setOptionsPrefix(prefix) — Set the prefix used for searching for options in the database. 🔥
  • setPeriodicity(maxCell, Lstart, L) — Set the description of mesh periodicity. 👑
  • setPointSF(sf) — Set the SF <#petsc4py.PETSc.SF> encoding the parallel DOF overlap for 🌈
  • setRefineLevel(level) — Set the number of refinements.
  • setSNESFunction(function[, args, kargs]) — Set SNES residual evaluation function.
  • setSNESJacobian(jacobian[, args, kargs]) — Set the SNES Jacobian evaluation function.
  • setSectionSF(sf) — Set the Section encoding the parallel DOF overlap for the DM.
  • setSparseLocalize(flag) — Set if coordinates should be only localized at the boundary.
  • setType(dm_type) — Build a DM.
  • setUp() — Return the data structure.
  • setUseNatural(useNatural) — Set the flag for constructing a global-to-natural map.
  • setVecType(vec_type) — Set the type of vector.
  • view([viewer]) — View the DM.

✨ Attributes Summary ✨

  • appctx — Application context. 🫶
  • ds — Discrete space. 💫

🎀 Methods Documentation 🎀

ok bestie, deep breath, this is the part where every single method gets its own lil spotlight. no skipping, periodt. 💅

adaptLabel(label)

Adapt a DM based on a DMLabel. 🦋

Collective.

Parameters

  • label (str) — The name of the DMLabel.

Return type

DM

See also:

DMAdaptLabel — https://petsc.org/release/manualpages/DM/DMAdaptLabel.html

Source code at petsc4py/PETSc/DM.pyx:1783 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L1783

adaptMetric(metric, bdLabel=None, rgLabel=None)

Return a mesh adapted to the specified metric field. it's giving glow-up but for meshes ✨

Collective.

Parameters

  • metric (Vec) — The metric to which the mesh is adapted, defined vertex-wise.
  • bdLabel (str | None) — Label for boundary tags.
  • rgLabel (str | None) — Label for cell tag.

Return type

DM

See also:

DMAdaptMetric — https://petsc.org/release/manualpages/DM/DMAdaptMetric.html

Source code at petsc4py/PETSc/DM.pyx:1806 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L1806

addCoarsenHook(coarsenhook, restricthook, args=None, kargs=None)

Add a callback to be executed when restricting to a coarser grid. 👑 lowkey such a vibe, you're basically telling the DM "when u shrink, run this".

Logically collective.

Parameters

  • coarsenhook (DMCoarsenHookFunction) — The coarsen hook function.
  • restricthook (DMRestrictHookFunction) — The restrict hook function.
  • args (tuple[Any, ...] | None) — Positional arguments for the hooks.
  • kargs (dict[str, Any] | None) — Keyword arguments for the hooks.

Return type

None

See also:

DMCoarsenHookAdd — https://petsc.org/release/manualpages/DM/DMCoarsenHookAdd.html

Source code at petsc4py/PETSc/DM.pyx:2470 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L2470

addField(field, label=None)

Add a field to a DM object. adding more dimensions to ur life fr fr 🌈

Logically collective.

Parameters

  • field (Object) — The discretization object.
  • label (str | None) — The name of the label indicating the support of the field, or None for the entire mesh.

Return type

None

See also:

DMAddField — https://petsc.org/release/manualpages/DM/DMAddField.html

Source code at petsc4py/PETSc/DM.pyx:648 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L648

appendOptionsPrefix(prefix)

Append to the prefix used for searching for options in the database. 🎀 stacking those prefixes like they're bracelets.

Logically collective.

See also:

Working with PETSc options, setOptionsPrefix, DMAppendOptionsPrefix — https://petsc.org/release/manualpages/DM/DMAppendOptionsPrefix.html

Source code at petsc4py/PETSc/DM.pyx:298 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L298

Parameters

  • prefix (str | None)

Return type

None

clearDS()

Remove all discrete systems from the DM. 🧹 it's giving spring cleaning, but like, mathematically rigorous.

Logically collective.

See also:

DMClearDS — https://petsc.org/release/manualpages/DM/DMClearDS.html

okay bestie we're mid-roll through the DM methods 💅 the last one's wrapping up right here, so here's its tail:

✨ clearFields() ✨

Remove all fields from the DM. Poof. Gone. Bye 👋

Logically collective — everybody's gotta be on the same page about the poofing.

See also: DMClearFields — https://petsc.org/release/manualpages/DM/DMClearFields.html

🌸 clearLabelStratum(name, value) 🌸

Remove all points from a stratum. Whole stratum, empty. it's giving spring cleaning 🧹

Not collective — this one's a solo mission, do it on your own.

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: DMClearLabelStratum — https://petsc.org/release/manualpages/DM/DMClearLabelStratum.html

🦋 clearLabelValue(name, point, value) 🦋

Remove a point from a DMLabel with the given value. One point. One label. Very demure, very mindful ✨

Not collective.

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: DMClearLabelValue — https://petsc.org/release/manualpages/DM/DMClearLabelValue.html

👑 clone() 👑

Return the cloned DM. Copy-paste but make it computational, lowkey iconic.

Collective.

See also: DMClone — https://petsc.org/release/manualpages/DM/DMClone.html

🌈 coarsen(comm=None) 🌈

Return a coarsened DM object. Shrink it down, make it cute, make it small 💖

Collective.

Parameters

Return type: DM — #petsc4py.PETSc.DM

See also: DMCoarsen — https://petsc.org/release/manualpages/DM/DMCoarsen.html

🫶 coarsenHierarchy(nlevels) 🫶

Coarsen this DM and hand you back the whole coarsened DM hierarchy. It's a whole family tree of smaller and smaller DMs, no cap 🌳

Collective.

Parameters

Return type: list — https://docs.python.org/3/builtins/stdtypes.html#list

See also: DMCoarsenHierarchy — https://petsc.org/release/manualpages/DM/DMCoarsenHierarchy.html

🎀 convert(dm_type) 🎀

Return a DM converted to another DM. Glow-up but for mesh representations ✨

Collective.

Parameters

Return type: DM — #petsc4py.PETSc.DM

See also: DM.Type — #petsc4py.PETSc.DM.Type, DMConvert — https://petsc.org/release/manualpages/DM/DMConvert.html

💜 copyDS(dm, minDegree=None, maxDegree=None) 💜

Copy the discrete systems for this DM into another DM. Sharing is caring, bestie 🍓

Collective.

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: DMCopyDS — https://petsc.org/release/manualpages/DM/DMCopyDS.html

🧚 copyDisc(dm) 🧚

Copy fields AND discrete systems of a DM into another DM. The whole bundle, package deal, buy-one-get-both 🔥

Collective.

Parameters

  • dm (DM — #petsc4py.PETSc.DM) — the DM that the fields and discrete systems are copied into.

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: DMCopyDisc — https://petsc.org/release/manualpages/DM/DMCopyDisc.html

⭐ copyFields(dm, minDegree=None, maxDegree=None) ⭐

Copy the discretizations of this DM into another DM. Just the fields this time, not the discrete systems, okay bestie, we're being specific 🎯

Collective.

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: DMCopyFields — https://petsc.org/release/manualpages/DM/DMCopyFields.html

💖 create(comm=None) 💖

Return an empty DM. Blank slate. Fresh start. Main character energy from zero 🐣

Collective.

Parameters

Return type: Self — https://docs.python.org/3/library/typing.html#typing.Self

See also: DMCreate — https://petsc.org/release/manualpages/DM/DMCreate.html

🌟 createDS() 🌟

Create discrete systems. That's it, that's the method, go off 💅

Collective.

See also: DMCreateDS — https://petsc.org/release/manualpages/DM/DMCreateDS.html

🌸 createFieldDecomposition() 🌸

Return field splitting information. Tell me how the fields are getting divvied up, bestie, I'm listening 👀

Collective.

See also: DMCreateFieldDecomposition — https://petsc.org/release/manualpages/DM/DMCreateFieldDecomposition.html

createGlobalVec() 🌍💖

okay so this one hands you back a global vector, bestie.

Collective. — everybody in the communicator is coming to the party, no ghosting. 🫶

createInjection(dm) 🧵✨

Spits out the injection matrix into a finer DM. Glow-up from coarse to fine, literally.

Collective.

Parameters

createInterpolation(dm) 🦋🎀

Gives you the interpolation matrix to a finer DM. Same vibe as injection but make it interpolate.

Collective.

Parameters

createLabel(name) 🏷️💅

Creates a label with whatever name you give it — but only if it doesn't already exist. Very "if you know, you know, and if you already know, we move on."

Not collective. 💅 you can do this one solo, no committee meeting required.

Parameters

createLocalVec() 🏠⭐

Hands you a local vector. Home turf edition.

Not collective. 💅 all by yourself, main character energy.

createMassMatrix(dmf) ⚖️🔥

Returns the mass matrix between this DM and the given DM. It's giving physics.

Collective.

Parameters

createMat() 🧮✨

Returns an empty matrix. A blank canvas, an unfilled notes app page, a fresh Stanley cup. 🥤

Collective.

createRestriction(dm) 🚧🦋

Returns the restriction matrix between this DM and the given DM. Going the other way now, bestie — the restrict direction.

Collective.

Parameters

createSectionSF(localsec, globalsec) 🌐🧚

Creates the SF that encodes the parallel DOF overlap for the DM. Communication blueprint, but make it structural.

Collective.

Parameters

  • localsec (Section) — Describe the local data layout.
  • globalsec (Section) — Describe the global data layout.
  • Return type: None

Notes

Encoding based on the Section describing the data layout. That's the whole tea. 🍵

createSubDM(fields) 🍰👑

Returns an IS and a DM that together encapsulate a subproblem. A whole little sub-universe. 🌌

Not collective. 💅

Returns

  • iset (IS) — The global indices for all the degrees of freedom.
  • subdm (DM) — The DM for the subproblem.

Parameters

  • fields (Sequence[int])

Return type: tuple[IS, DM]

destroy() 💀💖

Destroys the object. Clean up your room, bestie. No notes.

Collective.

getAppCtx() 🎒✨

Returns the application context. Whatever you stashed in there, it's back. 🫶

getAuxiliaryVec(label=None, value=0, part=0) 🧵💜

Returns an auxiliary vector for region. Regional flavor unlocked.

Not collective.

Parameters

getBasicAdjacency() 🕸️🌸

Returns the flags for determining variable influence. Who's adjacent to who, the gossip graph of your DM. 👀

Not collective.

Returns

  • useCone (bool) — Whether adjacency uses cone information.
  • useClosure (bool) — whether adjacency is computed using full closure information. fr, that's the whole vibe of the param ✨

Return type: tuple[bool, bool] 🫶

See also: DMGetBasicAdjacency

Source: petsc4py/PETSc/DM.pyx:407 💅

getBlockSize()

Return the inherent block size that comes with a DM. it's giving "how chunky is this DM" 💖

Not collective. 🧚

See also: DMGetBlockSize

Source: petsc4py/PETSc/DM.pyx:807

Return type: int 🔢

getBoundingBox()

Return the dimension of embedding space for coordinates values.

Not collective. 🌸

See also: DMGetBoundingBox

Source: petsc4py/PETSc/DM.pyx:1381

Return type: tuple[tuple[float, float], ...] 📦

getCellCoordinateDM()

Return the cell coordinate DM.

Collective. 👑

See also: DMGetCellCoordinateDM

Source: petsc4py/PETSc/DM.pyx:1196

Return type: DM (petsc4py.PETSc.DM)

getCellCoordinateSection()

Return the cell coordinate layout over the DM. lowkey the map of where everything lives 🗺️

Collective. 👑

See also: DMGetCellCoordinateSection

Source: petsc4py/PETSc/DM.pyx:1231

Return type: Section (petsc4py.PETSc.Section)

getCellCoordinates()

Return a global vector with the cellwise coordinates. global girlie energy 🌈

Collective. 👑

See also: DMGetCellCoordinates

Source: petsc4py/PETSc/DM.pyx:1263

Return type: Vec (petsc4py.PETSc.Vec)

getCellCoordinatesLocal()

Return a local vector with the cellwise coordinates. staying in your own lane, as one does 💅

Collective. 👑

See also: DMGetCellCoordinatesLocal

Source: petsc4py/PETSc/DM.pyx:1295

Return type: Vec (petsc4py.PETSc.Vec)

getCoarseDM()

Return the coarse DM. going down a level, iconic ✨

Collective. 👑

See also: DMGetCoarseDM

Source: petsc4py/PETSc/DM.pyx:1057

Return type: DM (petsc4py.PETSc.DM)

getCoarsenLevel()

Return the number of coarsenings.

Not collective. 🦋

See also: DMGetCoarsenLevel

Source: petsc4py/PETSc/DM.pyx:1767

Return type: int

getCoordinateDM()

Return the coordinate DM.

Collective. 👑

See also: DMGetCoordinateDM

Source: petsc4py/PETSc/DM.pyx:1085

Return type: DM (petsc4py.PETSc.DM)

getCoordinateDim()

Return the dimension of embedding space for coordinates values.

Not collective. 🦋

See also: DMGetCoordinateDim

Source: petsc4py/PETSc/DM.pyx:238

Return type: int

getCoordinateSection()

Return coordinate values layout over the mesh. yes bestie, it's the coordinate section of the mesh 🕸️

Collective. 👑

See also: DMGetCoordinateSection

Source: petsc4py/PETSc/DM.pyx:1100

Return type: Section (petsc4py.PETSc.Section)

getCoordinates()

Return a global vector with the coordinates associated. main character global vector, no cap 🌟

Collective. 👑

See also: DMGetCoordinates

Source: petsc4py/PETSc/DM.pyx:1132

Return type: Vec (petsc4py.PETSc.Vec)

getCoordinatesLocal()

Return a local vector with the coordinates associated.

Collective the first time it is called. 😭 note that!! only the first call, the rest are chillin 🙈

See also: DMGetCoordinatesLocal

Source: petsc4py/PETSc/DM.pyx:1164

Return type: Vec (petsc4py.PETSc.Vec)

getCoordinatesLocalized()

Check if the coordinates have been localized for cells. a little vibe check, if you will 🎀

Not collective. 🦋

See also: DMGetCoordinatesLocalized

Source: petsc4py/PETSc/DM.pyx:1334

Return type: bool

getDS()

Return default DS (petsc4py.PETSc.DS).

Not collective. 🦋

See also: DMGetDS

Source: petsc4py/PETSc/DM.pyx:740

Return type: DS (petsc4py.PETSc.DS)

getDimension()

Return the topological dimension of the DM. the ✨topological✨ one, important distinction 🧚

Not collective. 🦋

See also: DMGetDimension

Source: petsc4py/PETSc/DM.pyx:206

Return type: int

getField(index)

Return the discretization object for a given DM field.

Not collective. 🦋

Parameters

  • index (int) — The field number. 🔢
  • Return type — tuple[Object, None]
  • See also — DMGetField
  • Source code at — petsc4py/PETSc/DM.pyx:623

(that was the tail end of the previous entry bestie, now we keep scrolling through the DM method buffet 🍓)

getFieldAdjacency(field) 🦋

Return the flags for determining variable influence. That's it, that's the whole job.

Not collective — this one's a solo mission, no group chat needed.

Parameters

  • field (int) — The field number.

Returns

  • useCone (bool) — Whether adjacency uses cone information.
  • useClosure (bool) — Whether adjacency is computed using full closure information.

Return type — tuple[bool, bool]

  • See also — DMGetAdjacency
  • Source code at — petsc4py/PETSc/DM.pyx:453

getGlobalSection() 💜

Hands you back the Section that encodes the global data layout for the DM. Like, the master blueprint of where everything lives globally. ✨

Collective the first time it is called — so that very first call needs the whole squad present.

Return type — Section

  • See also — DMGetGlobalSection
  • Source code at — petsc4py/PETSc/DM.pyx:1900

getGlobalVec(name=None) 👑

Return a global vector. Yep. A whole global vector, just for you.

Collective — everybody hops on for this one.

Parameters

  • name (str | None) — The optional name to retrieve a persistent vector.

Return type — Vec

Notes

When done with the vector, it must be restored using restoreGlobalVec. Do not just wander off with it, bestie, that's not the vibe. 🙈
  • See also — restoreGlobalVec, DMGetGlobalVector, DMGetNamedGlobalVector
  • Source code at — petsc4py/PETSc/DM.pyx:863

getLGMap() 🌸

Return the local mapping to global mapping. Local-to-global. The little translator that gets your local indices into the global room. 💅

Collective.

Return type — LGMap

  • See also — DMGetLocalToGlobalMapping
  • Source code at — petsc4py/PETSc/DM.pyx:1040

getLabel(name) 🎀

Return the label of a given name. You give it a name, it gives you the label. Simple, iconic, no notes. 💖

Not collective.

Parameters

  • name (str)

Return type — DMLabel

  • See also — DMGetLabel
  • Source code at — petsc4py/PETSc/DM.pyx:1842

getLabelIdIS(name) 🌈

Return an IS of all the values that the DMLabel takes. Like, the full receipt of every value that label could possibly be. 🧾

Not collective.

Parameters

  • name (str) — The label name.

Return type — IS

  • See also — DMLabelGetValueIS, DMGetLabelIdIS
  • Source code at — petsc4py/PETSc/DM.pyx:2193

getLabelName(index) 🌟

Return the name of the *n*th label. Zero-indexed girlies, you know the drill.

Not collective.

Parameters

  • index (int) — The label number.

Return type — str

  • See also — DMGetLabelName
  • Source code at — petsc4py/PETSc/DM.pyx:2019

getLabelOutput(name) 🫶

Return the output flag for a given label. Is this label getting printed out or is it staying lowkey? This method tells you. 🔍

Not collective.

Parameters

  • name (str) — The label name.

Return type — bool

  • See also — DMGetLabelOutput
  • Source code at — petsc4py/PETSc/DM.pyx:2306

getLabelSize(name) 🌺

Return the number of values that the DMLabel takes. Not the values themselves, just how many there are — like a headcount for the label. 🔢

Not collective.

Parameters

  • name (str) — The label name.

Return type — int

  • See also — DMLabelGetNumValues, DMGetLabelSize
  • Source code at — petsc4py/PETSc/DM.pyx:2172

getLabelValue(name, point) 🦋

Return the value in the DMLabel for the given point. Point in, value out. Chef's kiss. 👩‍🍳💋

Not collective.

Parameters

  • name (str) — The label name.
  • point (int) — The mesh point

Return type — int

  • See also — DMGetLabelValue
  • Source code at — petsc4py/PETSc/DM.pyx:2101

getLocalBoundingBox() 📦

Return the bounding box for the piece of the DM — just your piece, not the whole thing. Local representation, main character energy but for your chunk of the mesh only. 💅

Not collective.

Return type — tuple[tuple[float, float], ...]

  • See also — DMGetLocalBoundingBox
  • Source code at — petsc4py/PETSc/DM.pyx:1398

getLocalSection() 🌸

Return the Section that encodes the local data layout for the DM. (Yes it's the sibling of getGlobalSection, and yes the see-also is literally DMGetGlobalSection, make of that what you will bestie. 🙈)

Not collective.

Return type — Section

  • See also — DMGetGlobalSection
  • Source code at — petsc4py/PETSc/DM.pyx:1873

getLocalVec(name=None) 💜

Return a local vector.

Not collective.

  • name (str | None) — the optional name you use to fish out a persistent vector. Optional, so if you've got nothing, pass nothing. 🎣

Return type: Vec — your cute little Vec <#petsc4py.PETSc.Vec>. 🦋

Notes 💌

When you're done with that vector you must give it back with restoreLocalVec. This is not a vibe, this is a rule — hoarding vectors is how you get leaks, and leaks are not the look. 😭

See also: restoreLocalVec, DMGetLocalVector, DMGetNamedLocalVector

Source: petsc4py/PETSc/DM.pyx:917

getNumFields()

How many fields does this DM have? That's the whole thing. No plot twist, just a number. ✨

Not collective — solo mission, no MPI group chat required. 💅

See also: DMGetNumFields

Source: petsc4py/PETSc/DM.pyx:583

Return type: int

getNumLabels()

Returns how many labels this DM has defined on it. Labels on labels on labels, we love a well-organized queen. 🎀

Not collective. 🫶

See also: DMGetNumLabels

Source: petsc4py/PETSc/DM.pyx:2005

Return type: int

getOptionsPrefix()

Gives you back the prefix this DM is using to search for options in the options database. It's giving "personalized filter for your flags." 🔍

Not collective.

See also: Working with PETSc options <#petsc-options>, setOptionsPrefix, DMGetOptionsPrefix

Source: petsc4py/PETSc/DM.pyx:284

Return type: str

getPeriodicity()

Set the description of mesh periodicity. (Yes bestie, the docstring literally says Set on a getter. We're just reporting the lore, not the logic. 💀)

Not collective.

Parameters 🌈

  • maxCell — the longest allowable cell dimension in each direction.
  • Lstart — the start of each coordinate direction, usually [0, 0, 0].
  • L — the periodic length of each coordinate direction, or -1 for non-periodic.

Return type: tuple[ArrayReal <#petsc4py.typing.ArrayReal>, ArrayReal <#petsc4py.typing.ArrayReal>, ArrayReal <#petsc4py.typing.ArrayReal>]

See also: DMSetPeriodicity

Source: petsc4py/PETSc/DM.pyx:1432

getPointSF()

Hands you the SF <#petsc4py.PETSc.SF> that encodes the parallel DOF overlap for the DM. Star-forest realness. 🌲✨

Not collective.

See also: DMGetPointSF

Source: petsc4py/PETSc/DM.pyx:1978

Return type: SF <#petsc4py.PETSc.SF>

getRefineLevel()

Returns the refinement level. How refined are we? Very. 👑💅

Not collective.

See also: DMGetRefineLevel

Source: petsc4py/PETSc/DM.pyx:1735

Return type: int

getSectionSF()

Returns the Section <#petsc4py.PETSc.Section> encoding the parallel DOF overlap.

Collective the first time it is called — so the very first call is a whole-group activity, after which she calms down. First-call-only collectivity is such a specific vibe and we respect it. 🫂

See also: DMGetSectionSF

Source: petsc4py/PETSc/DM.pyx:1947

Return type: SF <#petsc4py.PETSc.SF>

getSparseLocalize()

Tells you whether coordinates should only be localized at the boundary. Boundary-only queens, this is your flag. 🦋

Not collective.

See also: DM.setSparseLocalize, DMGetSparseLocalize

Source: petsc4py/PETSc/DM.pyx:1348

Return type: bool

getStratumIS(name, value)

Returns the points sitting in a label stratum. Very "show me everyone in this specific clique." 💅

Not collective.

Parameters 🌸

  • name (str) — the label name.
  • value (int) — the stratum value.

Return type: IS <#petsc4py.PETSc.IS>

See also: DMGetStratumIS

Source: petsc4py/PETSc/DM.pyx:2238

getStratumSize(name, value)

Returns the number of points in a label stratum — so, the headcount of that clique instead of the guest list. 🔢

Not collective.

Parameters 🌸

  • name (str) — the label name.
  • value (int) — the stratum value.

Return type: int

See also: DMGetStratumSize

Source: petsc4py/PETSc/DM.pyx:2214

getType()

Returns the DM type name. Name drop, but for DMs. ✨

Not collective.

See also: DMGetType

Source: petsc4py/PETSc/DM.pyx:192

Return type: str

getUseNatural()

Gets the flag for constructing a global-to-natural map. Just tell me if we're building the map or not, bestie. 🗺️

Not collective.

Returns: useNatural — whether a global-to-natural map is created.

Return type: bool

See also: DMGetUseNatural

Source: petsc4py/PETSc/DM.pyx:349

globalToLocal(vg, vl, addv=None)

Updates the local vectors from the global vector. The glow-up pipeline: global in, local out. 😌

Neighborwise collective — the neighbors are talking, so plan around it. 🫂

Parameters 💜

  • vg (Vec <#petsc4py.PETSc.Vec>) — the global vector.
  • vl (Vec <#petsc4py.PETSc.Vec>) — the local vector.
  • addv (InsertModeSpec <#petsc4py.typing.InsertModeSpec> | None) — insertion mode.

Return type: None

See also: DMGlobalToLocalBegin, DMGlobalToLocalEnd

Source: petsc4py/PETSc/DM.pyx:971

hasLabel(name)

Determine whether the DM has a label. 👀

🚫 not collective — every process just does its own lil thing, no group chat needed.

  • name (str) — the label name.

Yields back a bool 💖

See also: DMHasLabel

Source code at petsc4py/PETSc/DM.pyx:2039

load(viewer) 🫶

Give me back a DM that was stashed in binary. Iconic.

💬 collective — everybody pulls up to this one together.

Parameters

  • viewer (Viewer) — the Viewer you used to store the DM, like Viewer.Type.BINARY or Viewer.Type.HDF5.

Returns: Self (yes bestie, you get you back) ✨

Notes

When you're on that Viewer.Type.HDF5 format, you can save multiple DMPlex meshes inside one single HDF5 file, fr fr. The catch? You gotta name the DMPlex object first with Object.setName before saving it with DM.view and before loading it with DM.load, so the mesh object can actually be identified. No name, no vibe check, no finding your mesh 💅

See also: DM.view, DM.load, Object.setName, DMLoad

Source code at petsc4py/PETSc/DM.pyx:95

localToGlobal(vl, vg, addv=None) 🌈

Update your global vectors from a local vector. Glow-up but for vectors.

🤝 neighborwise collective — only you and your neighbors gotta sync, nobody else needs to know.

Parameters

  • vl (Vec) — the local vector.
  • vg (Vec) — the global vector.
  • addv (InsertModeSpec | None) — insertion mode.

Returns: None

See also: DMLocalToGlobalBegin, DMLocalToGlobalEnd

Source code at petsc4py/PETSc/DM.pyx:994

localToLocal(vl, vlg, addv=None) 🦋

Maps the values from one local vector onto another local vector. Local to local, real ones know 😌

🤝 neighborwise collective

Parameters

  • vl (Vec) — the local vector.
  • vlg (Vec) — the global vector.
  • addv (InsertModeSpec | None) — insertion mode.

Returns: None

See also: DMLocalToLocalBegin, DMLocalToLocalEnd

Source code at petsc4py/PETSc/DM.pyx:1017

localizeCoordinates() 🎀

Creates local coordinates for cells that have periodic faces. Periodicity, handled 💅

💬 collective

Notes

Used if the mesh is periodic. That's the whole assignment periodt.

See also: DMLocalizeCoordinates

Source code at petsc4py/PETSc/DM.pyx:1415

Returns: None

refine(comm=None) 🔥

Hands you back a refined DM object. Glow-up arc: complete.

💬 collective

Parameters

  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Returns: DM

See also: DMRefine

Source code at petsc4py/PETSc/DM.pyx:1633

refineHierarchy(nlevels) 👑

Refines this DM and returns the whole refined DM hierarchy back to you. Multi-level moment.

💬 collective

Parameters

  • nlevels (int) — the number of levels of refinement.

Returns: list (a whole lineup of them bestie 🎶)

See also: DMRefineHierarchy

Source code at petsc4py/PETSc/DM.pyx:1681

removeLabel(name) 💀

Remove and destroy the label by name. Not a soft block — it's destroyed, no cap.

🚫 not collective

Parameters

  • name (str) — the label name.

Returns: None

See also: DMRemoveLabel

Source code at petsc4py/PETSc/DM.pyx:2079

restoreGlobalVec(vg, name=None) 💜

Gives back a global vector you got earlier with getGlobalVec. Be a good citizen and return your borrowed vectors bestie 🫶

🧠 logically collective — everybody's gotta call it, but no data is actually moving anywhere.

Parameters

  • vg (Vec) — the global vector.
  • name (str | None) — the name used to retrieve the persistent vector, if any.

Returns: None

See also: getGlobalVec, DMRestoreGlobalVector, DMRestoreNamedGlobalVector

Source code at petsc4py/PETSc/DM.pyx:892

restoreLocalVec(vl, name=None) 🍓

Gives back a local vector you got earlier with getLocalVec. Same energy, local edition.

🚫 not collective

Parameters

  • vl (Vec) — the local vector.
  • name (str | None) — the name used to retrieve the persistent vector, if any.

Returns: None

See also: getLocalVec, DMRestoreLocalVector, DMRestoreNamedLocalVector

Source code at petsc4py/PETSc/DM.pyx:946

setAppCtx(appctx) 🌸

Sets the application context. Your stuff, your vibes, stored right there.

Source code at petsc4py/PETSc/DM.pyx:339

Parameters

  • appctx (Any)

Returns: None

setAuxiliaryVec(aux, label, value=0, part=0) ✨

Sets an auxiliary vector for one specific region. Very much a targeted serve.

🚫 not collective

Parameters

  • aux …
  • aux (Vec) — the auxiliary vector 🦋
  • label (DMLabel or None) — the name of the DMLabel, or None if there isn't one 🎀
  • value — this is what tells you which region we're talking about ✨
  • part — the equation part. If it's 0, it's unused 🙈

Return type: None 💖

See also: DMGetLabel, DMSetAuxiliaryVec

Source code at petsc4py/PETSc/DM.pyx:510

🌈 setBasicAdjacency(useCone, useClosure)

Ok so this one sets the flags that decide how variable influence gets figured out. Slay. ✨

Not collective. (so every proc is on its own with this one, bestie 💅)

Parameters

  • useCone (bool) — whether adjacency uses cone information 🌸
  • useClosure (bool) — whether adjacency is computed using the full closure information 👑

Return type: None

See also: DMSetBasicAdjacency

Source code at petsc4py/PETSc/DM.pyx:386

🎀 setCellCoordinateDM(dm)

Sets the cell coordinate DM. That's it, that's the vibe. 💖

Collective.

Parameters

  • dm (DM) — the cell coordinate DM 🦋

Return type: None

See also: DMSetCellCoordinateDM

Source code at petsc4py/PETSc/DM.pyx:1179

⭐ setCellCoordinateSection(dim, sec)

Sets the cell coordinate layout over the DM. Layout queen energy ✨

Collective.

Parameters

  • dim (int) — the embedding dimension, or DETERMINE 🧚
  • sec (Section) — the cell coordinate Section 🌸

Return type: None

See also: DMSetCellCoordinateSection

Source code at petsc4py/PETSc/DM.pyx:1211

💜 setCellCoordinates(c)

Sets a global vector packed with the cellwise coordinates. Global girlie 💅

Collective.

Parameters

  • c (Vec) — the global cell coordinate vector 🦋

Return type: None

See also: DMSetCellCoordinates

Source code at petsc4py/PETSc/DM.pyx:1246

🍓 setCellCoordinatesLocal(c)

Same energy as above but local, no global drama. Sets a local vector with the cellwise coordinates. ✨

Not collective.

Parameters

  • c (Vec) — the local cell coordinate vector 🌸

Return type: None

See also: DMSetCellCoordinatesLocal

Source code at petsc4py/PETSc/DM.pyx:1278

🔥 setCoarseDM(dm)

Sets the coarse DM. Lowkey iconic. 👑

Collective.

See also: DMSetCoarseDM

Source code at petsc4py/PETSc/DM.pyx:1072

Parameters

  • dm (DM) 🦋

Return type: None

🌸 setCoordinateDim(dim)

Sets the dimension of embedding space for the coordinate values. Just so we know how much room the coords are living in 💖

Not collective.

Parameters

  • dim (int) — the embedding dimension 🎀

Return type: None

See also: DMSetCoordinateDim

Source code at petsc4py/PETSc/DM.pyx:252

✨ setCoordinateDisc(disc, localized, project)

Projects coordinates to a whole different space. Glow-up for your coordinates, fr fr 💅

Collective.

Parameters

  • disc (FE) — the new coordinates discretization 🌈
  • localized (bool) — set a localized (DG) coordinate space 🦋
  • project (bool) — project coordinates to new discretization ⭐

Return type: Self

See also: DMSetCoordinateDisc

Source code at petsc4py/PETSc/DM.pyx:1310

💜 setCoordinates(c)

Sets a global vector that holds the coordinates. Global coords, main character energy 👑

Collective.

Parameters

  • c (Vec) — Coordinate Vector 🎀

Return type: None

See also: DMSetCoordinates

Source code at petsc4py/PETSc/DM.pyx:1115

🧚 setCoordinatesLocal(c)

Sets a local vector where the ghost point is the one holding the coordinates. Ghost point doing the heavy lifting, love that 🫶

Not collective.

Parameters

  • c (Vec) — Coordinate Vector 🌸

Return type: None

See also: DMSetCoordinatesLocal

Source code at petsc4py/PETSc/DM.pyx:1147

💖 setDimension(dim)

Sets the topological dimension of the DM. Topology check, but make it fashion ✨

Collective.

Parameters

  • dim (int) — topological dimension 🦋

Return type: None

See also: DMSetDimension

Source code at petsc4py/PETSc/DM.pyx:220

⭐ setField(index, field, label=None)

Sets the discretization object for a given DM field. Picking the fit for each field, obsessed 💅

Logically collective.

Parameters

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

See also: DMSetField (https://petsc.org/release/manualpages/DM/DMSetField.html)

Source code at petsc4py/PETSc/DM.pyx:597 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L597)

✨ setFieldAdjacency(field, useCone, useClosure) ✨

Okay so this one sets the flags for determining variable influence. No cap.

Not collective. So it’s a solo vibe, bestie.

Parameters

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

See also: DMSetAdjacency (https://petsc.org/release/manualpages/DM/DMSetAdjacency.html)

Source code at petsc4py/PETSc/DM.pyx:429 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L429)

setFromOptions() 🛠️

Configures the object from the options database. It’s giving very “read the room, then set yourself up” energy.

Collective.

See also: Working with PETSc options <#petsc-options>, DMSetFromOptions (https://petsc.org/release/manualpages/DM/DMSetFromOptions.html)

Source code at petsc4py/PETSc/DM.pyx:312 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L312)

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

setGlobalSection(sec) 🌍

Sets the Section <#petsc4py.PETSc.Section> encoding the global data layout for the DM. Global data layout? We love a worldwide queen.

Collective.

See also: DMSetGlobalSection (https://petsc.org/release/manualpages/DM/DMSetGlobalSection.html)

Source code at petsc4py/PETSc/DM.pyx:1888 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L1888)

Parameters

  • sec (Section <#petsc4py.PETSc.Section>)

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

setKSPComputeOperators(operators, args=None, kargs=None) 🔢

Matrix associated with the linear system. Yes, the whole linear-system moment.

Collective.

Parameters

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

See also: DMKSPSetComputeOperators (https://petsc.org/release/manualpages/KSP/DMKSPSetComputeOperators.html)

Source code at petsc4py/PETSc/DM.pyx:2332 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L2332)

setLabelOutput(name, output) 🏷️

Sets if a given label should be saved to a view. View = the moment.

Not collective.

Parameters

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

See also: DMSetLabelOutput (https://petsc.org/release/manualpages/DM/DMSetLabelOutput.html)

Source code at petsc4py/PETSc/DM.pyx:2284 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L2284)

setLabelValue(name, point, value) 📍

Sets a point to a DMLabel <#petsc4py.PETSc.DMLabel> with a given value. It’s giving “put this point on the map”.

Not collective.

Parameters

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

See also: DMSetLabelValue (https://petsc.org/release/manualpages/DM/DMSetLabelValue.html)

Source code at petsc4py/PETSc/DM.pyx:2124 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L2124)

setLocalSection(sec) 🏠

Sets the Section <#petsc4py.PETSc.Section> encoding the local data layout for the DM. Local layout, local queen.

Collective.

See also: DMSetLocalSection (https://petsc.org/release/manualpages/DM/DMSetLocalSection.html)

Source code at petsc4py/PETSc/DM.pyx:1861 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L1861)

Parameters

  • sec (Section <#petsc4py.PETSc.Section>)

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

setMatType(mat_type) 🧮

Sets matrix type to be used by DM.createMat. It’s the matrix type selector, no cap.

Logically collective.

Parameters

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

Notes

The option -dm_mat_type is used to set the matrix type.

See also: Working with PETSc options <#petsc-options>, DMSetMatType (https://petsc.org/release/manualpages/DM/DMSetMatType.html)

Source code at petsc4py/PETSc/DM.pyx:1495 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L1495)

setNumFields(numFields) 🔢

Sets the number of fields in the DM. The field count is the moment.

Logically collective.

See also: DMSetNumFields (https://petsc.org/release/manualpages/DM/DMSetNumFields.html)

Source code at petsc4py/PETSc/DM.pyx:570 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L570)

Parameters

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

setOptionsPrefix(prefix) 🏷️

Sets the prefix used for searching for options in the database. Prefix era.

Logically collective.

See also: Working with PETSc options <#petsc-options>, getOptionsPrefix, DMSetOptionsPrefix (https://petsc.org/release/manualpages/DM/DMSetOptionsPrefix.html)

Source code at petsc4py/PETSc/DM.pyx:270 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L270)

Parameters

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

setPeriodicity(maxCell, Lstart, L)

Sets the description of mesh periodicity.

Logically collective. 💅 — like, everybody's on the same page, bestie.

Parameters:

  • maxCell (Sequence[float]) — the longest allowable cell dimension in each direction. No cap, it's giving bounds. 🦋
  • Lstart (Sequence[float]) — the start of each coordinate direction, usually [0, 0, 0]. Origin energy, iconic. 💖
  • L (Sequence[float]) — the periodic length of each coordinate direction, or -1 for non-periodic. Periodt. 💅

Return type: None — it's giving nothing back, and that's valid.

See also: DMSetPeriodicity — https://petsc.org/release/manualpages/DM/DMSetPeriodicity.html

Source code: petsc4py/PETSc/DM.pyx:1468 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L1468

✨ setPointSF(sf) ✨

Okay so this one sets the SF that encodes the parallel DOF overlap for the DM. Main character energy for parallel setups. 💖

Logically collective. (iykyk)

See also: DMSetPointSF — https://petsc.org/release/manualpages/DM/DMSetPointSF.html

Source code: petsc4py/PETSc/DM.pyx:1993 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L1993

Parameters:

  • sf (SF) — your SF, bestie. 🌸

Return type: None

setRefineLevel(level)

Set the number of refinements. Lowkey essential for multigrid vibes. 🌈

Not collective. Just you and your refinement count.

Parameters:

  • nlevels — the number of refinement. Periodt. 🙈
  • level (int) — level. That's it.

Return type: None

See also: DMSetRefineLevel — https://petsc.org/release/manualpages/DM/DMSetRefineLevel.html

Source code: petsc4py/PETSc/DM.pyx:1749 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L1749

setSNESFunction(function, args=None, kargs=None)

Set the SNES residual evaluation function. This is the callback that does the math, periodt. 🧮✨

Not collective.

Parameters:

  • function (SNESFunction) — the callback. Your function, your rules. 💅
  • args (tuple[Any, ...] | None) — positional arguments for the callback. Tuple energy.
  • kargs (dict[str, Any] | None) — keyword arguments for the callback. Dict energy.

Return type: None

See also: SNES.setFunction, DMSNESSetFunction — https://petsc.org/release/manualpages/SNES/DMSNESSetFunction.html

Source code: petsc4py/PETSc/DM.pyx:2407 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L2407

setSNESJacobian(jacobian, args=None, kargs=None)

Set the SNES Jacobian evaluation function. It's giving derivatives, no cap. 📈

Not collective.

Parameters:

  • jacobian (SNESJacobianFunction) — the Jacobian callback. Jacobian queen. 👑
  • args (tuple[Any, ...] | None) — positional arguments for the callback. Tuple energy.
  • kargs (dict[str, Any] | None) — keyword arguments for the callback. Dict energy.

Return type: None

See also: SNES.setJacobian, DMSNESSetJacobian — https://petsc.org/release/manualpages/SNES/DMSNESSetJacobian.html

Source code: petsc4py/PETSc/DM.pyx:2439 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L2439

setSectionSF(sf)

Set the Section encoding the parallel DOF overlap for the DM. The Section is the blueprint, bestie. 🎀

Logically collective.

See also: DMSetSectionSF — https://petsc.org/release/manualpages/DM/DMSetSectionSF.html

Source code: petsc4py/PETSc/DM.pyx:1962 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L1962

Parameters:

  • sf (SF) — the SF. 🌸

Return type: None

setSparseLocalize(flag)

Set if coordinates should be only localized at the boundary. Boundary-only localization? It's giving sparse energy. 🦋

Collective.

Parameters:

  • flag (bool) — whether the coordinates should only be localized at the boundary. Boundary flag realness.

Return type: None

See also: DM.getSparseLocalize, DMSetSparseLocalize — https://petsc.org/release/manualpages/DM/DMSetSparseLocalize.html

Source code: petsc4py/PETSc/DM.pyx:1362 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L1362

setType(dm_type)

Build a DM. It's giving origin story. 💅

Collective.

Parameters:

  • dm_type (Type | str) — the type of DM. Pick your fighter.

Return type: None

Notes

DM types are available in DM.Type class. Slay.

See also: DM.Type, DMSetType — https://petsc.org/release/manualpages/DM/DMSetType.html

Source code: petsc4py/PETSc/DM.pyx:169 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L169

setUp()

Return the data structure. The way this just returns Self? Iconic. 👑

Collective.

See also: DMSetUp — https://petsc.org/release/manualpages/DM/DMSetUp.html

Source code: petsc4py/PETSc/DM.pyx:324 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L324

Return type: Self

setUseNatural(useNatural)

Set the flag for constructing a global-to-natural map. Natural mapping? We love a natural queen. 🌸

Not collective.

Parameters:

  • useNatural (bool) — whether a global-to-natural map is created. Map flag energy.

Return type: None

See also: DMSetUseNatural — https://petsc.org/release/manualpages/DM/DMSetUseNatural.html

Source code: petsc4py/PETSc/DM.pyx:368 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L368

setVecType(vec_type)

Set the type of vector. Vector type? It's giving Vec.Type realness. 🦋

Logically collective.

See also: Vec.Type, DMSetVecType — https://petsc.org/release/manualpages/DM/DMSetVecType.html

Parameters

  • vec_type (Vec.Type | str)

Return type

None

💻 source code lives at petsc4py/PETSc/DM.pyx:821 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L821

view(viewer=None)

Okay so this one just views the DM, bestie. Like showing it off. 📸

Collective — meaning everyone in the communicator has to call it, no ghosting the group chat. 👑🫶

Parameters

  • viewer (Viewer | None) — The DM viewer. None and it'll do the default thing.

Return type

None

See also:

💻 source code lives at petsc4py/PETSc/DM.pyx:76 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L76

🎀 Attributes Documentation 🎀

These are the little properties hanging off your DM, no method call needed, they're just there. ✨

  • appctx — Application context. Your lil' pocket for whatever you wanna stash in there. 🍓
💻 source code lives at petsc4py/PETSc/DM.pyx:2523 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L2523
  • ds — Discrete space. It's giving structure. 💅
💻 source code lives at petsc4py/PETSc/DM.pyx:2533 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DM.pyx#L2533

__init__()

classmethod __new__(*args, **kwargs)

🦋 petsc4py.PETSc.DMComposite 🦋

class petsc4py.PETSc.DMComposite

Bases: DM

A DM object that is used to manage data for a collection of DMs. Basically a group project where every DM actually does its part. 🌈

✨ Methods Summary ✨

  • addDM(dm, *args) — Add a DM vector to the composite.
  • create([comm]) — Create a composite object.
  • gather(gvec, imode, lvecs) — Gather split local vectors into a coupled global vector.
  • getAccess(gvec[, locs]) — Get access to the individual vectors from the global vector.
  • getEntries() — Return sub-DMs contained in the composite.
  • getGlobalISs() — Return the index sets for each composed object in the composite.
  • getLGMaps() — Return a local-to-global mapping for each DM in the composite.
  • getLocalISs() — Return index sets for each component of a composite local vector.
  • getNumber() — Get number of sub-DMs contained in the composite.
  • scatter(gvec, lvecs) — Scatter coupled global vector into split local vectors.

💜 Methods Documentation 💜

addDM(dm, *args)

Add a DM vector to the composite. Like adding a member to the group chat, except it's a DM and it actually participates. 💫

Collective — everybody's invited to the call. 🫶

Parameters

  • dm (DM) — The DM object.
  • *args (DM) — Additional DM objects. As many as you want, babe, it's variadic. 🔥

Return type

None

See also:

💻 source code lives at petsc4py/PETSc/DMComposite.pyx:28 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMComposite.pyx#L28

create(comm=None)

Create a composite object. Fresh out the box, no notes. 🎁

Collective

Parameters

  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm — yes, the default one, it picks for you when you pass None. 😌

Return type

Self

See also:

💻 source code lives at petsc4py/PETSc/DMComposite.pyx:6 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMComposite.pyx#L6

gather(gvec, imode, lvecs)

Gather split local vectors into a coupled global vector. The way it takes all the little scattered pieces and assembles them — main character energy, honestly. 👑

Collective — no solo missions. 🚫

Parameters

  • gvec (Vec) — The global vector.
  • imode (InsertModeSpec) — The insertion mode.
  • lvecs (Sequence[Vec]) — The individual sequential vectors.

Return type

None

See also:

💻 source code lives at petsc4py/PETSc/DMComposite.pyx:115 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMComposite.pyx#L115

getAccess(gvec, locs=None)

Get access to the individual vectors from the global vector. 🔓

Not collective — this one you can do alone, no coordination needed. 💅

Use via the with statement context manager (PEP 343). So like:

with dmcomposite.getAccess(gvec) as vecs:
    ...

Okay but fr, don't forget the with, that's the whole point. 😭

Parameters

  • gvec (Vec) — The global vector.
  • locs (Sequence[int] | None) — Indices of vectors wanted, or None to get all vectors. Want all of them? Just say None, be greedy, I support it. 🫶

Return type

Any

💻 source code lives at petsc4py/PETSc/DMComposite.pyx:219 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMComposite.pyx#L219

getEntries()

Return sub-DMs contained in the composite. Peek inside the group, see who's actually in it. 🌸

Not collective — go ahead, look, no one needs to agree first. 💫

See also:

💻 source code lives at petsc4py/PETSc/DMComposite.pyx:66 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMComposite.pyx#L66

Return type

list[DM]

getGlobalISs()

Bestie, this one hands you the index sets for every composed object in the composite. 💅

Collective. (Everyone chip in, no solo runs.)

These are lowkey the perfect thing for pulling out a subset of vector entries when you're building a "multi-physics" preconditioner. 🧚

Heads up on the sibling squad: use getLocalISs when you want index sets in the packed local numbering, and getLGMaps when you want to map local sub-DM (ghost points included 👻) indices to packed global indices.

See also: DMCompositeGetGlobalISs — https://petsc.org/release/manualpages/DMComposite/DMCompositeGetGlobalISs.html

Source code at petsc4py/PETSc/DMComposite.pyx:143 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMComposite.pyx#L143

Return type: list[IS]

getLGMaps()

Returns a local-to-global mapping for each DM in the composite. 🗺️

Collective.

Note that this includes all the ghost points that an individual ghosted DMDA may have — yes, all of them, even the spooky ones. 👻

See also: DMCompositeGetISLocalToGlobalMappings — https://petsc.org/release/manualpages/DMComposite/DMCompositeGetISLocalToGlobalMappings.html

Source code at petsc4py/PETSc/DMComposite.pyx:196 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMComposite.pyx#L196

Return type: list[LGMap]

getLocalISs()

Gives you index sets for each component of a composite local vector. ✨

Not collective. (Doing this one alone, it's an introvert moment.)

If you need the composite global indices at all local points (ghosts included, again 👻), use getLGMaps instead.

And if you need index sets for pieces of the composite global vector, that's getGlobalISs's whole job.

See also: DMCompositeGetLocalISs — https://petsc.org/release/manualpages/DMComposite/DMCompositeGetLocalISs.html

Source code at petsc4py/PETSc/DMComposite.pyx:170 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMComposite.pyx#L170

Return type: list[IS]

getNumber()

Gets the number of sub-DMs contained in the composite. 🔢

Not collective.

See also: DMCompositeGetNumberDM — https://petsc.org/release/manualpages/DMComposite/DMCompositeGetNumberDM.html

Source code at petsc4py/PETSc/DMComposite.pyx:51 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMComposite.pyx#L51

Return type: int

scatter(gvec, lvecs)

Scatters a coupled global vector into split local vectors. 🌈 It's giving "one big vibe, many little vibes".

Collective.

Parameters:

  • gvec (Vec) — The global vector.
  • lvecs (Sequence[Vec]) — Array of local vectors.

Return type: None

See also: gather, DMCompositeScatterArray — https://petsc.org/release/manualpages/DMComposite/DMCompositeScatterArray.html

Source code at petsc4py/PETSc/DMComposite.pyx:90 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMComposite.pyx#L90

__init__()

classmethod __new__(*args, **kwargs)

class petsc4py.PETSc.DMDA

class petsc4py.PETSc.DMDA

Bases: DM

A DM object that is used to manage data for a structured grid. 🎀 It's the organized bestie — everything's on a grid, everything's got structure, we love that for us.

Enumerations (the little dropdown menus inside this class):

  • ElementType — Element types.
  • InterpolationType — Interpolation types.
  • StencilType — Stencil types.

class petsc4py.PETSc.DMDA.ElementType

class petsc4py.PETSc.DMDA.ElementType

Bases: object — https://docs.python.org/3/builtins/functions.html#object

Element types. 🧩

Attributes Summary:

  • P1 — Constant P1 of type int
  • Q1 — Constant Q1 of type int

Attributes Documentation:

__init__()

classmethod __new__(*args, **kwargs)

class petsc4py.PETSc.DMDA.InterpolationType

class petsc4py.PETSc.DMDA.InterpolationType

Bases: object — https://docs.python.org/3/builtins/functions.html#object

Interpolation types. 🦋

Attributes Summary:

  • Q0 — Constant Q0 of type int
  • Q1 — Constant Q1 of type int

Attributes Documentation:

__init__()

classmethod __new__(*args, **kwargs)

class petsc4py.PETSc.DMDA.StencilType

class petsc4py.PETSc.DMDA.StencilType

Bases: object — https://docs.python.org/3/builtins/functions.html#object

Stencil types. ⭐

Attributes Summary:

  • BOX — Constant BOX of type int
  • STAR — Constant STAR of type int

Attributes Documentation:

fr fr, we're deep in the attribute vibes rn, so let's give this one its moment 👑

  • STAR: int = STAR — okay so STAR is a constant, its value is literally STAR (yes, named after itself, main character behaviour ✨), and its type is int — that's Python's built-in int, the one documented over at https://docs.python.org/3/builtins/functions.html#int 💙

and then, because every good class needs its little dunder besties, you also get:

  • __init__() — no arguments listed, just vibes 🫶
  • classmethod __new__(*args, **kwargs) — flagged as a classmethod, and it takes *args, **kwargs exactly like that, star and all ⭐
ngl bestie, the self-referential STAR = STAR thing is so iconic — it's giving "I am my own constant" 💅 don't overthink it, just copy the names exactly as they're written, character for character, no cap 🔥
  • create([dim, dof, sizes, proc_sizes, ...]) — spawns a whole new DMDA object for you ✨ your blank lil grid canvas, ready to be filled.
  • createNaturalVec() — makes you a vector that's gonna hold values in the natural numbering 💜 (yes bestie, the natural ordering has its own dedicated vector situation going on).
  • duplicate([dof, boundary_type, ...]) — clones a DMDA 🪞 same vibe, new object.
  • getAO() — hands you the application ordering context for a distributed array. AO = app ordering, iykyk 🌀
  • getBoundaryType() — tells you the type of ghost nodes sitting at the boundary, in each dimension 🌸
  • getCoordinateName(index) — the name of one coordinate dimension, pls, just one, you gotta pass the index 🎀
  • getCorners() — returns the lower left corner and the sizes of the owned local region. Two things, one call, efficient queen 👑
  • getDim() — the topological dimension. That's it, that's the whole return value 💅
  • getDof() — number of degrees of freedom per node. dof literally stands for it, no cap.
  • getElementType() — tells you the element type that getElements is gonna hand back 🦋 (they're a duo, fr fr).
  • getElements([elem_type]) — an array with the indices of all the local elements 🔥 you can optionally say which elem_type you want.
  • getFieldName(field) — the name of an individual field component. Pass the field, get the name, periodt 💖
  • getGhostCorners() — lower left corner + the size of the ghosted local region 👻 note that this one's the ghosted region, not the owned one.
  • getGhostRanges() — the ranges of the local region in each dimension, ghosts included 👻💜 inclusive queen behavior.
  • getInterpolationType() — the type of interpolation. Short, sweet, exactly one answer ✨
  • getOwnershipRanges() — the ranges of indices in each dimension that each process owns 🫶 like a seating chart but for indices.
  • getProcSizes() — how many processes you got chillin' in each dimension 🧚
  • getRanges() — the ranges of the owned local region in each dimension. (Owned, not ghosted — don't mix them up bestie 😭)
  • getRefinementFactor() — the ratios that the DMDA grid is refined in each dimension 📐 one ratio per dimension, mwah.
  • getScatter() — returns the global-to-local and the local-to-local scatter contexts. Two contexts, one call, iconic 💅
  • getSizes() — number of grid points in each dimension. The whole grid, all the points, all the dims ⭐
  • getStencil() — stencil type and width, together, as a lil bundle 🎀
  • getStencilType() — just the stencil type, if that's all you needed.
  • getStencilWidth() — just the stencil width. Short king 👑
  • getVecArray(vec[, readonly]) — get access to the vector as laid out on an N-d grid 🦋 the optional readonly is there if you're just looking, not touching 🙈
  • globalToNatural(vg, vn[, addv]) — maps values over to the "natural" grid ordering 🌀 optional addv included.
  • naturalToGlobal(vn, vg[, addv]) — the return trip, mapping values back to grid ordering 🔁 same optional addv.
  • setBoundaryType(boundary_type) — set the type of ghost …

nodes on domain boundaries. 💫 (yep, that was the tail of the last setter — carry on!)

  • setCoordinateName(index, name) — names the coordinate dimension, so like, dimension index gets called name. 🏷️
  • setDim(dim) — sets the topological dimension.
  • setDof(dof) — sets how many degrees of freedom live on every vertex. 💅
  • setElementType(elem_type) — sets the element type that getElements is gonna hand back to you.
  • setFieldName(field, name) — names the individual field components, one by one. ✨
  • setInterpolationType(interp_type) — sets the interpolation type.
  • setProcSizes(proc_sizes) — sets how many processes sit in each dimension.
  • setRefinementFactor([refine_x, refine_y, ...]) — sets the ratios used for the DMDA grid refinement. 🌸
  • setSizes(sizes) — sets how many grid points are in each dimension.
  • setStencil(stencil_type, stencil_width) — sets the stencil type and width in one go, two-for-one energy. 🎀
  • setStencilType(stencil_type) — sets just the stencil type.
  • setStencilWidth(stencil_width) — sets just the stencil width.
  • setUniformCoordinates([xmin, xmax, ymin, ...]) — makes the DMDA coordinates a uniform grid, bestie. 📐

🎀 Attributes Summary 🎀

These are the lil' properties you can just read off a DMDA like it's nothing:

  • boundary_type — the boundary types in each dimension.
  • corners — the lower left corner and size of the local region in each dimension.
  • dim — the grid dimension.
  • dof — the number of DOFs associated with each stratum of the grid.
  • ghost_corners — the lower left corner and size of the local region in each dimension. 👻
  • ghost_ranges — the ranges of the local region, ghost nodes included.
  • proc_sizes — how many processes are in each dimension in the global decomposition.
  • ranges — the ranges of the local region in each dimension.
  • sizes — the global dimension.
  • stencil — stencil type and width, bundled together.
  • stencil_type — the stencil type.
  • stencil_width — the elementwise stencil width.

🛠️ Methods Documentation 🛠️

create(...)

create(dim=None, dof=None, sizes=None, proc_sizes=None,
       boundary_type=None, stencil_type=None, stencil_width=None,
       setup=True, ownership_ranges=None, comm=None)

Creates a DMDA object for you. 🫶

Collective. (iykyk — everybody's gotta call it together, no skipping.)

Under the hood, this one method is doing the work of a whole stack of C API calls, in this exact order:

  • petsc.DMDACreate
  • petsc.DMSetDimension
  • petsc.DMDASetDof
  • petsc.DMDASetSizes
  • petsc.DMDASetNumProcs
  • petsc.DMDASetOwnershipRanges
  • petsc.DMDASetBoundaryType
  • petsc.DMDASetStencilType
  • petsc.DMDASetStencilWidth
  • petsc.DMSetUp (optionally)

Petty efficient of it honestly. 💅

Parameters

  • dim (int | None) — the number of dimensions.
  • dof (int | None) — the number of degrees of freedom.
  • sizes (DimsSpec | None) — the number of elements in each dimension.
  • proc_sizes (DimsSpec | None) — the number of processes in the x, y, z dimensions.
  • boundary_type (tuple[DM.BoundaryType | int | str | bool, ...] | None) — the boundary types.
  • stencil_type (StencilType | None) — which flavour of ghost/halo stencil we're rocking. 👻
  • stencil_width (int | None) — how thicc that ghost/halo region is. it's giving layers, bestie.
  • setup (bool) — do we run the setup routine right after making the object, or nah? your call. ✨
  • ownership_ranges (tuple[Sequence[int], ...] | None) — the local x, y, z element counts babes 💅 its length has to equal proc_sizes, and the whole thing has to sum to sizes. no cap, the math has to math.
  • comm (Comm | None) — the MPI communicator. defaults to Sys.getDefaultComm if you don't say anything. 🫶

Return type: Self — yeah she returns herself, main character behaviour honestly. 👑

See also: DMDACreate, DMSetDimension, DMDASetDof, DMDASetSizes, DMDASetNumProcs, DMDASetOwnershipRanges, DMDASetBoundaryType, DMDASetStencilType, DMDASetStencilWidth, DMSetUp

📜 Source code at petsc4py/PETSc/DMDA.pyx:32

createNaturalVec()

okay so bestie, this one builds you a vector that holds values in the natural numbering. 🌈

Collective. everyone show up, we're doing this together.

The number of local entries in the vector on each process is the same as in a vector you'd get from DM.createGlobalVec. ✨

See also: DMDACreateNaturalVector

📜 Source code at petsc4py/PETSc/DMDA.pyx:832

Return type: Vec 🦋

duplicate(dof=None, boundary_type=None, stencil_type=None, stencil_width=None)

Duplicate a DMDA, my loves. a whole clone. 💖

Collective.

This routine goes and retrieves the information from the DMDA and recreates it. The parameters dof, boundary_type, stencil_type, stencil_width will be overwritten, if provided. so like, if you hand them over, they win. periodt. 💅

Parameters

  • dof (int | None) — The number of degrees of freedom.
  • boundary_type (tuple[DM.BoundaryType | int | str | bool, ...] | None) — Boundary types.
  • stencil_type (StencilType | None) — The ghost/halo stencil type.
  • stencil_width (int | None) — The width of the ghost/halo region.

Return type: DMDA 🌸

See also: create, DMDAGetInfo, DMSetUp

📜 Source code at petsc4py/PETSc/DMDA.pyx:148

getAO()

Return the application ordering context for a distributed array. 🔥

Collective.

The returned AO maps to the natural grid ordering that would be used for the DMDA if only 1 processor were employed (ordering most rapidly in the x-dimension, then y, then z). Multiple degrees of freedom are numbered for each node (rather than 1 component for the whole grid, then the next component, etc.). iykyk 🧚

See also: DMDAGetAO

📜 Source code at petsc4py/PETSc/DMDA.pyx:909

Return type: AO 💜

getBoundaryType()

Return the type of ghost nodes at boundary in each dimension. 👻

Not collective. she's doing this one solo, no group chat needed.

See also: setBoundaryType

📜 Source code at petsc4py/PETSc/DMDA.pyx:407

Return type: tuple[BoundaryType, ...] ⭐

getCoordinateName(index)

Return the name of a coordinate dimension. 🎀

Not collective.

Parameters

  • index (int) — The coordinate number for the DMDA (0, 1, ..., dim-1).

Return type: str

See also: setCoordinateName, DMDAGetCoordinateName

📜 Source code at petsc4py/PETSc/DMDA.pyx:810

getCorners()

Return the lower left corner and the sizes of the owned local region. lowkey essential. 🫶

Not collective.

Returns the global (x,y,z) indices of the lower left corner (first tuple) and size of the local region (second tuple).

Excluding ghost points. 🙈

The corner information is independent of the number of degrees of freedom per node. Thus the returned values can be thought of as coordinates on a logical grid, where each grid point has (potentially) several degrees of freedom. slay, the abstraction ate. 💅

See also: getRanges, getGhostRanges, getOwnershipRanges, getGhostCorners, DMDAGetCorners

📜 Source code at petsc4py/PETSc/DMDA.pyx:622

Return type: tuple[tuple[int, ...], tuple[int, ...]]

getDim()

Return the topological dimension. literally just the dim babes. ✨

Not collective.

See also: setDim, DMGetDimension

📜 Source code at petsc4py/PETSc/DMDA.pyx:234

Return type: int

getDof()

Return the number of degrees of freedom per node. 👑

Not collective.

See also: setDof, DMDAGetInfo — https://petsc.org/release/manualpages/DMDA/DMDAGetInfo.html (go read it, bestie, it's the whole vibe in one call ✨)

Source code lives at petsc4py/PETSc/DMDA.pyx:264 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L264

Return type — int https://docs.python.org/3/builtins/functions.html#int

✨ getElementType() ✨

Returns the element type that getElements is gonna hand you back. That's the whole job. It's giving no thoughts, just vibes, just the element type 💅

Not collective — meaning every process does its own lil thing, no group chat required 🫶

See also: setElementType, DMDAGetElementType — https://petsc.org/release/manualpages/DMDA/DMDAGetElementType.html

Source code sits at petsc4py/PETSc/DMDA.pyx:1050 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L1050

Return type — ElementType (the petsc4py.PETSc.DMDA.ElementType one, obsessed)

🦋 getElements(elem_type=None) 🦋

Okay so this one hands you back an array holding the indices of all the local elements. Every single one. Not a summary, not a teaser — the whole lineup ✨

Not collective 💅

Important detail, don't skip it: the elements are in local coordinates.

And the other important detail: each process uniquely owns a subset of the elements. That means no element is owned by two or more processes. Periodt. No double-dipping, no overlap, we do not do that here 🙈

Parameters:

Return type — ArrayInt (i.e. petsc4py.typing.ArrayInt)

See also: DMDAGetElements — https://petsc.org/release/manualpages/DMDA/DMDAGetElements.html

Source code at petsc4py/PETSc/DMDA.pyx:1064 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L1064

🎀 getFieldName(field) 🎀

Gives you the name of one individual field component. Single field. One. If you wanted all of them you'd loop, bestie, that's your problem now 💖

Not collective — yep, still not collective 🌸

Parameters:

  • field (int) — the field number for the DMDA, and it goes 0, 1, ..., dof-1, where dof is the number of degrees of freedom per node inside the DMDA. So like, index accordingly, don't be off by one, that's a jumpscare 😭 https://docs.python.org/3/builtins/functions.html#int

Return type — str https://docs.python.org/3/builtins/stdtypes.html#str

See also: setFieldName, DMDAGetFieldName — https://petsc.org/release/manualpages/DMDA/DMDAGetFieldName.html

Source code at petsc4py/PETSc/DMDA.pyx:699 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L699

👑 getGhostCorners() 👑

Returns the lower left corner and the size of the ghosted local region. Two things at once, she's efficient 💅

Not collective ✨

So what actually comes back: the global (x,y,z) indices of the lower left corner as the first tuple, and the size of the local region as the second tuple. Read it carefully, the order matters, don't flip them 🙈

See also: getRanges, getGhostRanges, getOwnershipRanges, getCorners, DMDAGetGhostCorners — https://petsc.org/release/manualpages/DMDA/DMDAGetGhostCorners.html

Source code at petsc4py/PETSc/DMDA.pyx:651 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L651

Return type — tuple[tuple[int, ...], tuple[int, ...]] https://docs.python.org/3/builtins/stdtypes.html#tuple

💜 getGhostRanges() 💜

Returns the ranges of the local region in each dimension — ghost nodes included. She's the ranges but with the ghosties invited to the party 👻

Not collective 🫶

See also: getRanges, getOwnershipRanges, getCorners, getGhostCorners, DMDAGetGhostCorners — https://petsc.org/release/manualpages/DMDA/DMDAGetGhostCorners.html

Source code at petsc4py/PETSc/DMDA.pyx:577 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L577

Return type — tuple[tuple[int, int], ...] https://docs.python.org/3/builtins/stdtypes.html#tuple

🌈 getInterpolationType() 🌈

Returns the type of interpolation. Just the type. Iconic, minimal, knows exactly what it is 💅

Not collective ⭐

See also: setInterpolationType, DMDAGetInterpolationType — https://petsc.org/release/manualpages/DMDA/DMDAGetInterpolationType.html

Source code at petsc4py/PETSc/DMDA.pyx:1020 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L1020

Return type — InterpolationType (yes, petsc4py.PETSc.DMDA.InterpolationType, the whole family reunion)

🍓 getOwnershipRanges() 🍓

Returns the ranges of indices in each dimension that are owned by each process. So who owns what, mapped out, no ambiguity, no drama 🌸

Not collective 💖

Heads up, and this is a real one: these numbers are not multiplied by the number of DOFs per node. They're the raw indices, bestie. Don't go doing math on them expecting DOF counts, that's not what she is 😭

See also: getRanges, getGhostRanges, getCorners, getGhostCorners, DMDAGetOwnershipRanges — https://petsc.org/release/manualpages/DMDA/DMDAGetOwnershipRanges.html

Source code at petsc4py/PETSc/DMDA.pyx:597 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L597

Return type — tuple[ArrayInt, ...] where ArrayInt is petsc4py.typing.ArrayInt https://docs.python.org/3/builtins/stdtypes.html#tuple

🧚 getProcSizes() 🧚

Returns how many processes are chilling in each dimension. Simple. Clean. Knows the layout 👑

Not collective ✨

See also: setProcSizes, DMDAGetInfo — https://petsc.org/release/manualpages/DMDA/DMDAGetInfo.html

Source code at petsc4py/PETSc/DMDA.pyx:361 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L361

Return type — tuple[int, ...] https://docs.python.org/3/builtins/stdtypes.html#tuple

💫 getRanges() 💫

Returns the ranges of the owned local region in each dimension. Owned-owned. Yours. 🫶

Not collective 💅

And the key bit: this one is excluding ghost nodes. If you want the ghosties you go to getGhostRanges, this is the clean version 🌸

See also: getGhostRanges, getOwnershipRanges, getCorners, getGhostCorners, DMDAGetCorners — https://petsc.org/release/manualpages/DMDA/DMDAGetCorners.html

Source code at petsc4py/PETSc/DMDA.pyx:555 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L555

Return type — tuple[tuple[int, int], ...] https://docs.python.org/3/builtins/stdtypes.html#tuple

🔥 getRefinementFactor() 🔥

Returns the ratios that the DMDA grid is refined in each dimension. Ratios, plural, per dimension — she's giving variety ⭐

Not collective 🎀

See also: setRefinementFactor, DMDAGetRefinementFactor — https://petsc.org/release/manualpages/DMDA/DMDAGetRefinementFactor.html

Source code at petsc4py/PETSc/DMDA.pyx:981 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L981

Return type — tuple[int, ...] https://docs.python.org/3/builtins/stdtypes.html#tuple

🎁 getScatter() 🎁

Returns the global-to-local and the local-to-local scatter contexts. Two scatters, one call, bundle deal 💖

Collective — okay and this one is collective, everybody's in the group chat for this one 🫶

See also: DMDAGetScatter — https://petsc.org/release/manualpages/DMDA/DMDAGetScatter.html

Source code at petsc4py/PETSc/DMDA.pyx:930 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L930

Return type — tuple[Scatter, Scatter], as in petsc4py.PETSc.Scatter twice https://docs.python.org/3/builtins/stdtypes.html#tuple

🌟 getSizes() 🌟

Returns the number of grid points in each dimension. The what, the how many, the whole picture ✨

Not collective 💅

See also: setSizes, DMDAGetInfo — https://petsc.org/release/manualpages/DMDA/DMDAGetInfo.html

Source code at petsc4py/PETSc/DMDA.pyx:311 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L311

Return type — tuple[int, ...] https://docs.python.org/3/builtins/stdtypes.html#tuple

🫶 getStencil()

bestie this one hands you b o t h the stencil type and the width in one lil tuple, no cap.

Not collective — every rank can just call it whenever, it's giving low-maintenance 💅

  • Returns: tuple[StencilType, int] — the stencil type plus the width.

See also: getStencilType, getStencilWidth

Source: petsc4py/PETSc/DMDA.pyx:532

🌸 getStencilType()

just the stencil type this time, the width is minding its own business.

Not collective. ✨

  • Returns: StencilType — the type, that's it, that's the whole vibe.

See also: setStencilType, DMDAGetInfo

Source: petsc4py/PETSc/DMDA.pyx:448

🎀 getStencilWidth()

and here she is, the width alone, main character energy.

Not collective. 🦋

  • Returns: int — the stencil width.

See also: setStencilWidth

Source: petsc4py/PETSc/DMDA.pyx:486

🔥 getVecArray(vec, readonly=False)

okay so this is the moment you get to actually touch the data — it gives you access to a vector as it's laid out on an N-d grid. iconic.

Logically collective. 🫶

Parameters:

  • vec (Vec) — the vector you're requesting access to.
  • readonly (bool) — set this True if you only want read-only access. defaults to False.
  • Returns: Any

See also: Vec.getArray, DMDAVecGetArray, DMDAVecGetArrayDOF

Source: petsc4py/PETSc/DMDA.pyx:723

🌈 globalToNatural(vg, vn, addv=None)

takes your values and maps them into the "natural" grid ordering. glow-up for your indexing, fr fr.

Neighborwise collective. 🙈

⚠️ bestie, listen: you must call createNaturalVec before you use this routine. no shortcuts, no skipping, the vibes will not save you here.

Parameters:

  • vg (Vec) — the global vector, in a grid ordering.
  • vn (Vec) — the global vector, in a "natural" ordering.
  • addv (InsertMode | None, optional) — the insertion mode.
  • Returns: None

See also: naturalToGlobal, DMDAGlobalToNaturalBegin, DMDAGlobalToNaturalEnd

Source: petsc4py/PETSc/DMDA.pyx:849

💜 naturalToGlobal(vn, vg, addv=None)

the uno reverse 🪞 — maps values back into the grid ordering.

Neighborwise collective.

Parameters:

  • vn (Vec) — the global vector, in a natural ordering.
  • vg (Vec) — the global vector, in a grid ordering.
  • addv (InsertMode | None, optional) — the insertion mode.
  • Returns: None

See also: globalToNatural, DMDANaturalToGlobalBegin, DMDANaturalToGlobalEnd

Source: petsc4py/PETSc/DMDA.pyx:879

💖 setBoundaryType(boundary_type)

sets the type of ghost nodes on your domain boundaries 👻 — yes ghosts, they're part of the grid, they're invited.

Not collective.

Parameters:

  • boundary_type (tuple[BoundaryType | int | str | bool, ...]) — the boundary type, given in (x), (x, y), or (x, y, z) dimensions. so one, two or three of em depending on your dim 💅
  • Returns: None

See also: getBoundaryType, DMDASetBoundaryType

Source: petsc4py/PETSc/DMDA.pyx:384

🦋 setCoordinateName(index, name)

gives a coordinate dimension an actual name instead of just being "the third one". personal branding, honestly.

Logically collective.

Parameters:

  • index (int) — the coordinate number for the DMDA, i.e. 0, 1, ..., dim-1.
  • name (str) — the name of the coordinate.
  • Returns: None

See also: getCoordinateName, DMDASetCoordinateName

Source: petsc4py/PETSc/DMDA.pyx:788

👑 setDim(dim)

sets the topological dimension. big structural moment.

Collective.

Parameters:

  • dim (int) — topological dimension.
  • Returns: None

See also: getDim, DMSetDimension

Source: petsc4py/PETSc/DMDA.pyx:217

✨ setDof(dof)

sets how many degrees of freedom live at every single vertex. the whole crowd, per node.

Not collective.

Parameters:

  • dof (int) — the number of degrees of freedom.
  • Returns: None

See also: getDof, DMDASetDof

Source: petsc4py/PETSc/DMDA.pyx:246

🎀 setElementType(elem_type)

sets which element type getElements is gonna hand back to you. dress code for your elements basically 🧚

Not collective.

See also: getElementType, DMDASetElementType

Source: petsc4py/PETSc/DMDA.pyx:1036

Parameters:

  • elem_type (ElementType | str)

Returns: None

🌸 setFieldName(field, name)

sets the name of individual field components ✨ — naming each one instead of referring to them as "field 0", because they deserve better.

Logically collective.

Parameters:

  • field (int) — the field number for the DMDA (0, 1, ..., dof-1), where dof indicates the number of degrees of freedom per node within the DMDA.
  • name (str) — the name of the field (component). 🏷️

Return type: None (yep, nothing comes back — it just does the thing 💅)

See also: getFieldName, DMDASetFieldName (https://petsc.org/release/manualpages/DMDA/DMDASetFieldName.html)

Source code at: petsc4py/PETSc/DMDA.pyx:675 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L675)

✨ setInterpolationType(interp_type) ✨

Set the type of interpolation. the glow-up your grid needed, fr fr 🦋

Logically collective. (everyone's in on it, no solo missions 🫶)

You should call this on the coarser of the two DMDAs you pass to DM.createInterpolation. coarse one is the main character here, no cap 👑

Parameters

  • interp_type (InterpolationType) — the interpolation type.

Return type: None

See also: getInterpolationType, DMDASetInterpolationType (https://petsc.org/release/manualpages/DMDA/DMDASetInterpolationType.html)

Source code at: petsc4py/PETSc/DMDA.pyx:999 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L999)

🌸 setProcSizes(proc_sizes) 🌸

Set the number of processes in each dimension. splitting the work like a group project where everyone actually shows up 😭

Logically collective.

Parameters

  • proc_sizes (DimsSpec) — the number of processes in (x,), (x, y), or (x, y, z) dimensions.

Return type: None

See also: getProcSizes, DMDASetNumProcs (https://petsc.org/release/manualpages/DMDA/DMDASetNumProcs.html)

Source code at: petsc4py/PETSc/DMDA.pyx:334 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L334)

🦋 setRefinementFactor(refine_x=2, refine_y=2, refine_z=2) 🦋

Set the ratios for the DMDA grid refinement. zooming in, but make it math ✨

Logically collective.

Parameters

  • refine_x (int) — ratio of fine grid to coarse in x dimension.
  • refine_y (int) — ratio of fine grid to coarse in y dimension.
  • refine_z (int) — ratio of fine grid to coarse in z dimension.

Return type: None

See also: getRefinementFactor, DMDASetRefinementFactor (https://petsc.org/release/manualpages/DMDA/DMDASetRefinementFactor.html)

Source code at: petsc4py/PETSc/DMDA.pyx:949 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L949)

💜 setSizes(sizes) 💜

Set the number of grid points in each dimension. the actual size of your lil universe 🪐

Logically collective.

Parameters

  • sizes (DimsSpec) — the global (x,), (x, y), or (x, y, z) size.

Return type: None

See also: getSizes, DMDASetSizes (https://petsc.org/release/manualpages/DMDA/DMDASetSizes.html)

Source code at: petsc4py/PETSc/DMDA.pyx:284 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L284)

🎀 setStencil(stencil_type, stencil_width) 🎀

Set the stencil type and width. two-for-one, we love a bundle deal 💅

Not collective. (so like, not everyone has to be involved, it's giving solo era)

Parameters

  • stencil_type (StencilType) — the stencil type.
  • stencil_width (int) — the stencil width.

Return type: None

See also: setStencilWidth, setStencilType, DMDASetStencilType (https://petsc.org/release/manualpages/DMDA/DMDASetStencilType.html), DMDASetStencilWidth (https://petsc.org/release/manualpages/DMDA/DMDASetStencilWidth.html)

Source code at: petsc4py/PETSc/DMDA.pyx:506 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L506)

🌈 setStencilType(stencil_type) 🌈

Set the stencil type. just the vibe of the stencil, nothing more 🫶

Logically collective.

Parameters

  • stype — the stencil type.
  • stencil_type (StencilType)

Return type: None

See also: getStencilType, setStencil, DMDASetStencilType (https://petsc.org/release/manualpages/DMDA/DMDASetStencilType.html)

Source code at: petsc4py/PETSc/DMDA.pyx:430 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L430)

⭐ setStencilWidth(stencil_width) ⭐

Set the stencil width. how wide we're going, bestie 📏

Logically collective.

Parameters

  • stencil_width (int) — the stencil width.

Return type: None

See also: getStencilWidth, setStencil, DMDASetStencilWidth (https://petsc.org/release/manualpages/DMDA/DMDASetStencilWidth.html)

Source code at: petsc4py/PETSc/DMDA.pyx:468 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L468)

🍓 setUniformCoordinates(xmin=0, xmax=1, ymin=0, ymax=1, zmin=0, zmax=1) 🍓

Set the DMDA coordinates to be a uniform grid. evenly spaced grid, we stan a balanced queen ✨

Collective.

Parameters

  • xmin (float) — the minimum in the x dimension.
  • xmax (float) — the maximum in the x dimension.
  • ymin (float) — the minimum in the y dimension (value ignored for 1 dimensional problems).
  • ymax (float) — the maximum in the y dimension (value ignored for 1 dimensional problems).
  • zmin (float) — the minimum in the z dimension (value ignored for 1 or 2 dimensional problems).
  • zmax (float) — the maximum in the z dimension (value ignored for 1 or 2 dimensional problems).

Return type: None

See also: DMDASetUniformCoordinates (https://petsc.org/release/manualpages/DMDA/DMDASetUniformCoordinates.html)

Source code at: petsc4py/PETSc/DMDA.pyx:744 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L744)

🎀 Attributes Documentation 🎀

okay now the ✨properties✨ era, aka things you can just reach in and grab 💅

  • boundary_type — boundary types in each dimension. 🌈

Source code at: petsc4py/PETSc/DMDA.pyx:1123 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L1123)

  • corners — the lower left corner and size of local region in each dimension. 📐

Source code at: petsc4py/PETSc/DMDA.pyx:1153 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L1153)

  • dim — the grid dimension. 🧊

Source code at: petsc4py/PETSc/DMDA.pyx:1103 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L1103)

  • dof — the number of DOFs associated with each stratum of the grid. 🔢

Source code at: petsc4py/PETSc/DMDA.pyx:1108 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L1108)

  • ghost_corners — the lower left corner and size of local region in each dimension. 👻
  • stencil — Stencil type and width.

Source code at petsc4py/PETSc/DMDA.pyx:1128 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L1128

  • stencil_type — Stencil type.

Source code at petsc4py/PETSc/DMDA.pyx:1133 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L1133

  • stencil_width — Elementwise stencil width.

Source code at petsc4py/PETSc/DMDA.pyx:1138 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMDA.pyx#L1138

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

🌈 petsc4py.PETSc.DMInterpolation 🌈

class petsc4py.PETSc.DMInterpolation

Bases: object — yes bestie, it literally just inherits from the plain old builtin object at https://docs.python.org/3/builtins/functions.html#object, no secret ancestor, no drama 💅

Interpolation on a mesh. That's the whole vibe of it 🦋

✨ Methods Summary ✨

  • create([comm]) — Create a DMInterpolation context.
  • destroy() — Destroy the DMInterpolation context.
  • evaluate(dm, x[, v]) — Calculate interpolated field values at the interpolation points.
  • getCoordinates() — Return the coordinates of each interpolation point.
  • getDim() — Return the spatial dimension of the interpolation context.
  • getDof() — Return the number of fields interpolated at a point.
  • getVector() — Return a Vec (#petsc4py.PETSc.Vec) which can hold all the interpolated field values.
  • restoreVector(vec) — Restore a Vec which can hold all the interpolated field values.
  • setDim(dim) — Set the spatial dimension for the interpolation context.
  • setDof(dof) — Set the number of fields interpolated at a point.
  • setUp(dm[, redundantPoints, ignoreOutsideDomain]) — Compute spatial indices for point location during interpolation.

💖 Methods Documentation 💖

create(comm=None)

Create a DMInterpolation context. Collective. So like, everybody on the communicator has to show up for this one, no ghosting the group chat 👑

Parameters

Return type

Self — https://docs.python.org/3/library/typing.html#typing.Self

See also: destroy, DMInterpolationCreate — https://petsc.org/release/manualpages/DM/DMInterpolationCreate.html

Source code at petsc4py/PETSc/DMUtils.pyx:13 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMUtils.pyx#L13

destroy()

Destroy the DMInterpolation context. Collective. Everyone says bye together, it's a whole moment 😭

See also: create, DMInterpolationDestroy — https://petsc.org/release/manualpages/DM/DMInterpolationDestroy.html

Source code at petsc4py/PETSc/DMUtils.pyx:35 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMUtils.pyx#L35

Return type

Self — https://docs.python.org/3/library/typing.html#typing.Self

evaluate(dm, x, v=None)

Calculate interpolated field values at the interpolation points. Collective. Everybody computes, everybody eats 🔥

Parameters

  • dm ( DM (#petsc4py.PETSc.DM) ) — The DM (#petsc4py.PETSc.DM).
  • x ( Vec (#petsc4py.PETSc.Vec) ) — The local vector containing the field to be interpolated.
  • v ( Vec (#petsc4py.PETSc.Vec) | None at https://docs.python.org/3/builtins/constants.html#None ) — A vector capable of holding the interpolated field values.

Return type

Vec — #petsc4py.PETSc.Vec

See also: DMInterpolationEvaluate — https://petsc.org/release/manualpages/DM/DMInterpolationEvaluate.html

Source code at petsc4py/PETSc/DMUtils.pyx:48 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMUtils.pyx#L48

getCoordinates()

Return the coordinates of each interpolation point. Collective.

The local vector entries correspond to interpolation points lying on this process, according to the associated DM. So like, your slice of the points, your slice of the coords, very "know your lane" of it ✨

See also: DMInterpolationGetCoordinates — https://petsc.org/release/manualpages/DM/DMInterpolationGetCoordinates.html

Source code at petsc4py/PETSc/DMUtils.pyx:74 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMUtils.pyx#L74

Return type

Vec — #petsc4py.PETSc.Vec

getDim()

Return the spatial dimension of the interpolation context. Not collective. You can just ask locally, no group huddle required 🙈

See also: setDim, DMInterpolationGetDim — https://petsc.org/release/manualpages/DM/DMInterpolationGetDim.html

Source code at petsc4py/PETSc/DMUtils.pyx:92 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMUtils.pyx#L92

Return type

int — https://docs.python.org/3/builtins/functions.html#int

getDof()

Return the number of fields interpolated at a point. Not collective. Local question, local answer, we love a low-effort query 💅

See also: setDof, DMInterpolationGetDof — https://petsc.org/release/manualpages/DM/DMInterpolationGetDof.html

Source code at petsc4py/PETSc/DMUtils.pyx:110 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMUtils.pyx#L110

Source code at petsc4py/PETSc/DMUtils.pyx:106 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMUtils.pyx#L106 💅

Return type: int (https://docs.python.org/3/builtins/functions.html#int) — yes bestie, it’s giving whole-number energy, no decimals allowed ✨

✨ getVector() ✨

Return a Vec (#petsc4py.PETSc.Vec) which can hold all the interpolated field values. 🫶

Collective. — all your processes are in the group chat for this one, no cap 🗣️

This vector should be returned using restoreVector. Don’t ghost it, okay? 🙈

See also: restoreVector, DMInterpolationGetVector (https://petsc.org/release/manualpages/DM/DMInterpolationGetVector.html)

Source code at petsc4py/PETSc/DMUtils.pyx:185 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMUtils.pyx#L185

Return type: Vec (#petsc4py.PETSc.Vec)

🦋 restoreVector(vec) 🦋

Restore a Vec which can hold all the interpolated field values. 💖

Collective. — yeah, the whole squad is involved 🌈

Parameters:

  • vec (Vec — #petsc4py.PETSc.Vec) — A vector capable of holding the interpolated field values.

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

See also: getVector, DMInterpolationRestoreVector (https://petsc.org/release/manualpages/DM/DMInterpolationRestoreVector.html)

Source code at petsc4py/PETSc/DMUtils.pyx:201 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMUtils.pyx#L201

🌸 setDim(dim) 🌸

Set the spatial dimension for the interpolation context. 🧚

Not collective. — this one is a solo main-character moment, periodt 💅

Parameters:

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

See also: getDim, DMInterpolationSetDim (https://petsc.org/release/manualpages/DM/DMInterpolationSetDim.html)

Source code at petsc4py/PETSc/DMUtils.pyx:120 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMUtils.pyx#L120

🎀 setDof(dof) 🎀

Set the number of fields interpolated at a point. 🍓

Not collective. — just you and your dof, lowkey iconic 💜

Parameters:

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

See also: getDof, DMInterpolationSetDof (https://petsc.org/release/manualpages/DM/DMInterpolationSetDof.html)

Source code at petsc4py/PETSc/DMUtils.pyx:138 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMUtils.pyx#L138

💫 setUp(dm, redundantPoints=False, ignoreOutsideDomain=False) 💫

Compute spatial indices for point location during interpolation. 🔥

Collective. — the whole crew is needed, fr fr 🌈

Parameters:

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

See also: DMInterpolationSetUp (https://petsc.org/release/manualpages/DM/DMInterpolationSetUp.html)

Source code at petsc4py/PETSc/DMUtils.pyx:156 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMUtils.pyx#L156

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

No extra deets on this page, bestie. Just the bare vibes. 💅

👑 petsc4py.PETSc.DMLabel 👑

class petsc4py.PETSc.DMLabel

Bases: Object (#petsc4py.PETSc.Object)

An object representing a subset of mesh entities from a DM (#petsc4py.PETSc.DM). 🦋

Methods Summary 💅✨

ok so this is the whole roster of stuff a DMLabel can do for you — every single method, in order, no skips. it's giving "multimap but make it fashion." tap in bestie 🫶

  • addStrata(strata) — drops new stratum values into a DMLabel. 🎀
  • addStrataIS(iset) — same energy, also adds new stratum values into a DMLabel.
  • addStratum(value) — adds just one new stratum value into a DMLabel. one. singular. main character. 👑
  • clearStratum(stratum) — yeets a stratum out of existence.
  • clearValue(point, value) — wipes the value a label assigns to a point. 🧹
  • computeIndex() — builds an index structure so you can figure out membership.
  • convertToSection() — hands you back a Section (petsc4py.PETSc.Section) and an IS (petsc4py.PETSc.IS) that encode the label. iconic duo fr. ✨
  • create(name[, comm]) — makes you a DMLabel object, which is a multimap. that's the whole vibe. 💖
  • createIndex(pStart, pEnd) — creates an index structure for membership determination (the deluxe version, with a range).
  • destroy() — destroys the label. bye bestie 💀
  • destroyIndex() — destroys the index structure. also bye.
  • distribute(sf) — creates a new label pushed forward over the SF (petsc4py.PETSc.SF). 🦋
  • duplicate() — duplicates the DMLabel. copy-paste but legal.
  • filter(start, end) — removes all points outside of [start, end). note the half-open interval, she's precise. 💅
  • gather(sf) — gathers all label values from leaves into roots. 🌸
  • getBounds() — returns the smallest and largest point in the label.
  • getDefaultValue() — returns the default value that getValue gives you back.
  • getNonEmptyStratumValuesIS() — returns an IS (petsc4py.PETSc.IS) of all values that the DMLabel takes. yes, all of them. 🌈
  • getNumValues() — returns the number of values that the DMLabel takes. just the count, so you know.
  • getStratumIS(stratum) — returns an IS (petsc4py.PETSc.IS) with the stratum points in it.
  • getStratumSize(stratum) — returns the size of a stratum.
  • getValue(point) — returns the value a label assigns to a point.
  • getValueIS() — returns an IS (petsc4py.PETSc.IS) of all values that the DMLabel takes. twin of the one above, but empties-included behavior differs iykyk. 🙈

wait okay not me editorializing — the page just lists it, so: returns an IS of all values that the DMLabel takes. periodt.

  • hasPoint(point) — determines whether the label contains a point. yes/no, that's it. ⭐
  • hasStratum(value) — determines whether points exist with the given value.
  • hasValue(value) — determines whether a label assigns the value to any point.
  • insertIS(iset, value) — sets every point in the IS (petsc4py.PETSc.IS) to a value. bulk assign, slay. 💜
  • permute(permutation) — creates a new label with permuted points. scramble but make it intentional.
  • reset() — destroys the internal data structures in the DMLabel. soft reboot energy. 🔥
  • setDefaultValue(value) — sets the default value that getValue hands back. 🎀

that's the full methods line-up, nothing skipped, nothing merged. keep scrolling bestie, there's more coming 👇

  • setStratumIS(stratum, iset) — set the stratum points using an IS.
  • setValue(point, value) — set the value a label assigns to a point.
  • stratumHasPoint(value, point) — return whether the stratum contains a point.
  • view([viewer]) — view the label.

🔎 Methods Documentation 💅

✨ addStrata(strata) ✨

okay so this one adds new stratum values in a DMLabel. bestie, note it's not collective — every process does its own thing, no group chat sync required 💖

Parameters

  • strata (Sequence[int]) — the stratum values.

Return type

  • None

See also:

addStrataIS, addStratum, DMLabelAddStrata (https://petsc.org/release/manualpages/DMLabel/DMLabelAddStrata.html)

Source code at petsc4py/PETSc/DMLabel.pyx:238 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L238)

🌸 addStrataIS(iset) 🌸

adds new stratum values in a DMLabel, but this time you're feeding it an index set instead of a plain sequence. still not collective, no cap 💅

Parameters

  • iset (IS) — index set with stratum values.

Return type

  • None

See also:

addStrata, addStratum, DMLabelAddStrataIS (https://petsc.org/release/manualpages/DMLabel/DMLabelAddStrataIS.html)

Source code at petsc4py/PETSc/DMLabel.pyx:258 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L258)

🦋 addStratum(value) 🦋

adds one new stratum value to a DMLabel. just the one, main-character stratum energy ✨

Not collective.

Parameters

  • value (int) — the stratum value.

Return type

  • None

See also:

addStrata, addStrataIS, DMLabelAddStratum (https://petsc.org/release/manualpages/DMLabel/DMLabelAddStratum.html)

Source code at petsc4py/PETSc/DMLabel.pyx:220 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L220)

🎀 clearStratum(stratum) 🎀

remove a stratum. it's giving clean-slate, no drama 🙈

Not collective.

Parameters

  • stratum (int) — the stratum value.

Return type

  • None

See also:

DMLabelClearStratum (https://petsc.org/release/manualpages/DMLabel/DMLabelClearStratum.html)

Source code at petsc4py/PETSc/DMLabel.pyx:406 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L406)

🍓 clearValue(point, value) 🍓

clears the value a label assigns to a point. bye value, you're uninvited from the point's party 💀

Not collective.

Parameters

  • point (int) — the point.
  • value (int) — the point value.

Return type

  • None

See also:

DMLabelClearValue (https://petsc.org/release/manualpages/DMLabel/DMLabelClearValue.html)

Source code at petsc4py/PETSc/DMLabel.pyx:199 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L199)

⭐ computeIndex() ⭐

creates an index structure for membership determination. it automatically determines the bounds, so you don't have to figure them out yourself. iconic behaviour fr fr 👑

Not collective.

See also:

DMLabelComputeIndex (https://petsc.org/release/manualpages/DMLabel/DMLabelComputeIndex.html)

Source code at petsc4py/PETSc/DMLabel.pyx:424 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L424)

Return type

  • None

🦋 convertToSection() 🦋

returns a Section and an IS that encode the label. two-for-one, lowkey a steal 💖

Not collective.

See also:

DMLabelConvertToSection (https://petsc.org/release/manualpages/DMLabel/DMLabelConvertToSection.html)

Source code at petsc4py/PETSc/DMLabel.pyx:607 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L607)

Return type

  • tuple[Section, IS]

🌈 create(name, comm=None) 🌈

creates a DMLabel object, which is a multimap. yes bestie, a multimap — it's giving multiple-values-per-key realness ✨

Collective — so like, everybody on the comm is in on this one 🫶

Parameters

  • name (str) — the label name.
  • comm (Comm | None) — MPI communicator, defaults to COMM_SELF.

Return type

  • Self

See also:

DMLabelCreate (https://petsc.org/release/manualpages/DMLabel/DMLabelCreate.html)

Source code at petsc4py/PETSc/DMLabel.pyx:40 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L40)

💜 createIndex(pStart, pEnd) 💜

creates an index structure for membership determination, but this time you hand it the bounds — no auto-detect, you're in charge 💅

Not collective.

Parameters

  • pStart (int) — the smallest point.
  • pEnd (int) — the largest point + 1. (yes, +1. that's not a typo, that's the vibe 🎀)

Return type

  • None

See also:

destroyIndex, DMLabelCreateIndex (https://petsc.org/release/manualpages/DMLabel/DMLabelCreateIndex.html)

Source code at petsc4py/PETSc/DMLabel.pyx:438 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L438)

🔥 destroy() 🔥

destroy the label. it's over bestie, we're closing the group chat 💀

Collective.

See also:

DMLabelDestroy (https://petsc.org/release/manualpages/DMLabel/DMLabelDestroy.html)

Source code at petsc4py/PETSc/DMLabel.pyx:8 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L8)

Return type

  • Self

🧚 destroyIndex() 🧚

destroys the index structure. poof, gone, we love a clean teardown 🙈

Not collective.

See also:

createIndex, DMLabelDestroyIndex (https://petsc.org/release/manualpages/DMLabel/DMLabelDestroyIndex.html)

Source code at petsc4py/PETSc/DMLabel.pyx:458 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L458)

Return type

  • None

💖 distribute(sf) 💖

creates a new label pushed forward over the SF. it's giving forward-momentum, glow-up distribution 🌟

Collective.

Parameters

  • sf (SF) — the map from old to new distribution.

Return type

  • DMLabel

See also: gather, DMLabelDistribute — https://petsc.org/release/manualpages/DMLabel/DMLabelDistribute.html

Source code at petsc4py/PETSc/DMLabel.pyx:567 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L567

duplicate()

Okay so this one does exactly what it says on the tin bestie — it duplicates the DMLabel, full clone energy, no notes. 👯‍♀️

Collective. (yes, everyone's invited to this party 🎉)

Return type: DMLabel

See also: DMLabelDuplicate — https://petsc.org/release/manualpages/DMLabel/DMLabelDuplicate.html

Source code at petsc4py/PETSc/DMLabel.pyx:65 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L65

filter(start, end)

This one removes all points that fall outside the range [start, end). Like, it's doing a vibe check and only the points in the window stay. ✂️

Not collective. (just you, doing your thing 🙈)

Parameters

  • start (int) — The first point kept.
  • end (int) — One more than the last point kept.

Return type: None

See also: DMLabelFilter — https://petsc.org/release/manualpages/DMLabel/DMLabelFilter.html

Source code at petsc4py/PETSc/DMLabel.pyx:528 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L528

gather(sf)

Gathers all label values from the leaves up into the roots. 🍃➡️🌳

Collective.

This is literally the inverse operation to distribute, so if you know one you know the other. iykyk 🔁

Parameters

  • sf (SF) — The SF communication map.

Return type: DMLabel

See also: distribute, DMLabelGather — https://petsc.org/release/manualpages/DMLabel/DMLabelGather.html

Source code at petsc4py/PETSc/DMLabel.pyx:586 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L586

getBounds()

Returns the smallest and the largest point in the label. 💖

Not collective.

Sneaky detail bestie: the values it hands back are the smallest point and the largest point + 1. Don't get caught off guard by that off-by-one, it's giving very much "read the docs" 😭

Return type: tuple[int, int]

See also: DMLabelGetBounds — https://petsc.org/release/manualpages/DMLabel/DMLabelGetBounds.html

Source code at petsc4py/PETSc/DMLabel.pyx:512 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L512

getDefaultValue()

Returns the default value that getValue hands back. ✨

Not collective.

So like — the default value is what you get when a point hasn't been explicitly given a value. And when a label gets created? It's initialized to -1. That's the starting vibe. 🎀

Return type: int

See also: setDefaultValue, DMLabelGetDefaultValue — https://petsc.org/release/manualpages/DMLabel/DMLabelGetDefaultValue.html

Source code at petsc4py/PETSc/DMLabel.pyx:161 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L161

getNonEmptyStratumValuesIS()

Returns an IS of all the values that the DMLabel takes. 🌈

Not collective.

Return type: IS

See also: DMLabelGetNonEmptyStratumValuesIS — https://petsc.org/release/manualpages/DMLabel/DMLabelGetNonEmptyStratumValuesIS.html

Source code at petsc4py/PETSc/DMLabel.pyx:622 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L622

getNumValues()

Returns the number of values that the DMLabel takes. Just the count, bestie. 🔢

Not collective.

Return type: int

See also: DMLabelGetNumValues — https://petsc.org/release/manualpages/DMLabel/DMLabelGetNumValues.html

Source code at petsc4py/PETSc/DMLabel.pyx:275 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L275

getStratumIS(stratum)

Returns an IS with the stratum points. 🫶

Not collective.

Parameters

  • stratum (int) — The stratum value.

Return type: IS

See also: setStratumIS, DMLabelGetStratumIS — https://petsc.org/release/manualpages/DMLabel/DMLabelGetStratumIS.html

Source code at petsc4py/PETSc/DMLabel.pyx:366 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L366

getStratumSize(stratum)

Returns the size of a stratum. 📏

Not collective.

Parameters

  • stratum (int) — The stratum value.

Return type: int

See also: DMLabelGetStratumSize — https://petsc.org/release/manualpages/DMLabel/DMLabelGetStratumSize.html

Source code at petsc4py/PETSc/DMLabel.pyx:346 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L346

getValue(point)

Returns the value a label assigns to a point. 💅

Not collective.

If no value was assigned, you get the default value. That default is initially -1, and you can change it with setDefaultValue. So it's not a mystery box, it's just the default, periodt. ✨

Parameters

  • point (int) — The point.

Return type: int

See also: setValue, setDefaultValue, DMLabelGetValue — https://petsc.org/release/manualpages/DMLabel/DMLabelGetValue.html

Source code at petsc4py/PETSc/DMLabel.pyx:137 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L137

getValueIS()

Returns an IS of all the values that the DMLabel takes. 🦋

Not collective.

Return type: IS

See also: DMLabelGetValueIS — https://petsc.org/release/manualpages/DMLabel/DMLabelGetValueIS.html

Source code at petsc4py/PETSc/DMLabel.pyx:289 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L289

hasPoint(point)

Figures out whether the label actually contains a given point. 🕵️‍♀️

Not collective.

Heads up bestie: the user must call createIndex before this function. No createIndex, no hasPoint. That's the rule. 😭

Parameters

  • point (int) — The point.

Return type: bool

See also: hasValue, DMLabelHasPoint — https://petsc.org/release/manualpages/DMLabel/DMLabelHasPoint.html

Source code at petsc4py/PETSc/DMLabel.pyx:490 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L490

hasStratum(value)

Figures out whether points exist with the given value. 👑

Not collective.

Parameters

  • value (int) — The stratum value.

Return type: bool

See also: DMLabelHasStratum — https://petsc.org/release/manualpages/DMLabel/DMLabelHasStratum.html

Source code at petsc4py/PETSc/DMLabel.pyx:326 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L326

hasValue(value)

Figures out whether a label assigns the value to any point at all. 🔥

Not collective.

Parameters

  • value (int) — The value.

Return type: bool

See also: —

See also: hasPoint, DMLabelHasValue — https://petsc.org/release/manualpages/DMLabel/DMLabelHasValue.html

Source code at petsc4py/PETSc/DMLabel.pyx:470 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L470

insertIS(iset, value)

okay so this one sets every single point inside an IS to a value. That's the whole job. Simple, clean, iconic ✨

Not collective. No MPI group chat needed, bestie 💅

Parameters

  • iset (IS) — the point IS 🎀
  • value (int) — the point value

Return type: Self — it hands the label right back to you, chaining girlie 🫶

See also: DMLabelInsertIS — https://petsc.org/release/manualpages/DMLabel/DMLabelInsertIS.html

Source code at petsc4py/PETSc/DMLabel.pyx:91 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L91

permute(permutation)

It makes you a brand new label whose points have been permuted. Fresh label, same energy, different ordering 💖

Not collective. 🦋

Parameters

  • permutation (IS) — the point permutation

Return type: DMLabel — a shiny new one, not a mutated old one 👑

See also: DMLabelPermute — https://petsc.org/release/manualpages/DMLabel/DMLabelPermute.html

Source code at petsc4py/PETSc/DMLabel.pyx:548 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L548

reset()

Nukes the internal data structures inside the DMLabel. Lowkey a glow-up wipe, highkey a full clear-out 🌸

Not collective. 🎀

See also: DMLabelReset — https://petsc.org/release/manualpages/DMLabel/DMLabelReset.html

Source code at petsc4py/PETSc/DMLabel.pyx:79 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L79

Return type: None — https://docs.python.org/3/builtins/constants.html#None

setDefaultValue(value)

Sets the default value that getValue is gonna hand back to you. Think of it as the fallback vibe for any point that never got an explicit value 💜

Not collective.

The value is used if a point has not been explicitly given a value. When a label is created, the default value is initialized to -1. Noted, bestie, -1 is the factory setting 📝

Parameters

  • value (int) — the default value

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: getDefaultValue, DMLabelSetDefaultValue — https://petsc.org/release/manualpages/DMLabel/DMLabelSetDefaultValue.html

Source code at petsc4py/PETSc/DMLabel.pyx:178 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L178

setStratumIS(stratum, iset)

Sets the stratum points, and you're doing it with an IS because that's just the move 💅

Not collective. 🦋

Parameters

  • stratum (int) — the stratum value
  • iset (IS) — the stratum points

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: getStratumIS, DMLabelSetStratumIS — https://petsc.org/release/manualpages/DMLabel/DMLabelSetStratumIS.html

Source code at petsc4py/PETSc/DMLabel.pyx:386 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L386

setValue(point, value)

Sets the value that a label assigns to a point. Core function energy, truly the main character of this class 👑

Not collective.

heads up bestie: if the value you pass is the same as the label's default value (which starts at -1, and can be changed with setDefaultValue), this function will do nothing. Like, literally nothing. No cap. 💀

Parameters

  • point (int) — the point
  • value (int) — the point value

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: getValue, setDefaultValue, DMLabelSetValue — https://petsc.org/release/manualpages/DMLabel/DMLabelSetValue.html

Source code at petsc4py/PETSc/DMLabel.pyx:112 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L112

stratumHasPoint(value, point)

Returns whether the stratum contains a point. A <cyan>yes or no</cyan> moment, very satisfying 🌈

Not collective.

Parameters

  • value (int) — the stratum value
  • point (int) — the point

Return type: bool — https://docs.python.org/3/builtins/functions.html#bool — true or false, iconic, periodt ✨

See also: DMLabelStratumHasPoint — https://petsc.org/release/manualpages/DMLabel/DMLabelStratumHasPoint.html

Source code at petsc4py/PETSc/DMLabel.pyx:303 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L303

view(viewer=None)

Shows you the label. Peek at it, screenshot it, send it to the group chat 📸

Collective. yes bestie, everybody in the communicator has to show up for this one 🙈

Parameters

  • viewer (Viewer | None) — a Viewer to display the graph

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: DMLabelView — https://petsc.org/release/manualpages/DMLabel/DMLabelView.html

Source code at petsc4py/PETSc/DMLabel.pyx:21 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMLabel.pyx#L21

__init__()

classmethod __new__(*args, **kwargs)

^^ that's the whole entry, no extra lore attached 💀

petsc4py.PETSc.DMPlex

class petsc4py.PETSc.DMPlex

Bases: DM

Encapsulate an unstructured mesh. 🕸️✨

DMPlex encapsulates both topology and geometry. It is capable of parallel refinement and coarsening (using Pragmatic or ParMmg) and parallel redistribution for load balancing. Like, it does the whole glow-up and the whole finesse pass, in parallel, and then balances the load so nobody's carrying too much. Queen behaviour fr fr 👑

🫶 Methods Summary 🫶

okay bestie, this is the menu — every method the DMPlex class hands you, one line each. Full deets live further down (keep scrolling, it's giving encyclopedia), but here's the vibe check on all of them:

  • computeCellGeometryFVM(cell) — Compute the volume for a given cell.
  • computeGradientClementInterpolant(locX, locC) — Return the L2 projection of the cellwise gradient of a function onto P1.
  • constructGhostCells([labelName]) — Construct ghost cells which connect to every boundary face.
  • coordinatesLoad(viewer, sfxc) — Load coordinates into this DMPlex object.
  • coordinatesView(viewer) — Save DMPlex coordinates into a file.
  • create([comm]) — Create a DMPlex object, which encapsulates an unstructured mesh.
  • createBoxMesh(faces[, lower, upper, ...]) — Create a mesh on the tensor product of intervals.
  • createBoxSurfaceMesh(faces[, lower, upper, ...]) — Create a mesh on the surface of a box mesh using tensor cells.
  • createCGNS(cgid[, interpolate, comm]) — Create a DMPlex mesh from a CGNS file.
  • createCGNSFromFile(filename[, interpolate, comm]) — "Create a DMPlex mesh from a CGNS file.
  • createClosureIndex(sec) — Calculate an index for sec for the closure operation.
  • createCoarsePointIS() — Create an IS <#petsc4py.PETSc.IS> covering the coarse DMPlex chart with the fine points as data.
  • createCohesiveSubmesh(hasLagrange, value) — Extract the hypersurface defined by one face of the cohesive cells.
  • createColoring([depth, distance]) — Return the coloring of the connectivity graph of entities in the DMPlex.
  • createCoordinateSpace(degree, localized, project) — Create a finite element space for the coordinates.
  • createExodus(exoid[, interpolate, comm]) — Create a DMPlex mesh from an ExodusII file ID.
  • createExodusFromFile(filename[, ...]) — Create a DMPlex mesh from an ExodusII file.
  • createFromCellList(dim, cells, coords[, ...]) — Create a DMPlex from a list of vertices for each cell on process 0.
  • createFromFile(filename[, plexname, ...]) — Create DMPlex from a file.
  • createGlobalToNaturalSF(section, sfMigration) — Create the SF <#petsc4py.PETSc.SF> for mapping Global Vec <#petsc4py.PETSc.Vec> to the Natural Vec <#petsc4py.PETSc.Vec>.
  • createGmsh(viewer[, interpolate, comm]) — Create a DMPlex mesh from a Gmsh file viewer.
  • createNaturalVec() — Return a natural vector.
  • createPointNumbering() — Create a global numbering for all points.
  • createSection(numComp, numDof[, bcField, ...]) — Create a Section <#petsc4py.PETSc.Section> based upon the DOF layout specification provided.
  • distribute([overlap]) — Distribute the mesh and any associated sections.

few things before you spiral, queen:

  • The square brackets mean optional, and the ... means "bestie there's more, that's just the first couple." Not me skipping anything — that's literally what the doc says, fr fr. 💅
  • On createCGNSFromFile — yes, that description starts with an unclosed quotation mark. That's canon. The manpage said it, I'm reporting it, we do not question the elders. 😭
  • Those <#petsc4py.PETSc.…> bits are cross-reference links to other classes, so like, clickable in the fancy render. The IS, SF, Vec and Section ones all point at their own pages. 🦋
  • createCoarsePointIS() and createNaturalVec() and createPointNumbering() take zero arguments — no self-ish drama, they just do the thing. ✨

and we are SO not done, there's a whole pile more of these coming 🌈

  • distributeField(sf, sec, vec[, newsec, newvec]) — hand off your field data using a given SF (petsc4py.PETSc.SF). it's giving "here's the data, you know what to do" ✨
  • distributeGetDefault() — returns a flag telling you whether the DM (petsc4py.PETSc.DM) is, like, supposed to be distributed by default. just a lil yes/no vibe check 💅
  • distributeOverlap([overlap]) — adds partition overlap to a distributed non-overlapping DMPlex. no overlap? not on my watch 🫶
  • distributeSetDefault(flag) — sets that flag yourself, telling the DMPlex whether it should be distributed by default. you're the main character here 👑
  • distributionGetName() — gets the name of that specific parallel distribution. iykyk 📛
  • distributionSetName(name) — sets the name of the specific parallel distribution. name it something cute ✨
  • filter([label, value, ignoreHalo, ...]) — extracts a subset of mesh cells (defined by a label) and gives you back a whole separate mesh. yes bestie, a filter but for geometry 🎀
  • generate(boundary[, name, interpolate]) — generates a mesh. it just… makes one. iconic behaviour fr fr 🌈
  • getAdjacency(p) — returns every point that's adjacent to the point you passed in. it's the point's whole social circle 💖
  • getAdjacencyUseAnchors() — queries whether adjacency in the mesh uses the point-to-point constraints. anchor girlies stay winning ⚓
  • getCellNumbering() — returns a global cell numbering for all the cells on this process. numbered, organised, slaying 🧚
  • getCellType(p) — returns the polytope type of a given cell. what kind of shape are you, bestie? 🔍
  • getCellTypeLabel() — returns the DMLabel (petsc4py.PETSc.DMLabel) that records the polytope type of each cell. receipts for every single cell 📋
  • getChart() — returns the interval covering all mesh points, written [pStart, pEnd). left in, right out — classic 💀
  • getCone(p) — returns the points on the in-edges for this point in the DAG. the point's incoming entourage 🎀
  • getConeOrientation(p) — returns the orientations on the in-edges for this point in the DAG. same edges, but now with ✨direction✨
  • getConeSize(p) — returns the number of in-edges for this point in the DAG. how many? that many 🧮
  • getDepth() — returns the depth of the DAG representing this mesh. how deep does it go? very 🕳️
  • getDepthStratum(svalue) — returns the bounds [start, end) for all points at a certain depth. one depth level, fully contained 🎯
  • getFullJoin(points) — returns an array for the join of the set of points. the full join, no crumbs left 😌
  • getHeightStratum(svalue) — returns the bounds [start, end) for all points at a certain height. depth's little sibling, doing great 💜
  • getJoin(points) — returns an array for the join of the set of points. like getFullJoin, but the regular version 🔥
  • getMaxSizes() — returns the maximum number of in-edges and out-edges of the DAG. peak capacity, no cap 💅
  • getMeet(points) — returns an array for the meet of the set of points. the overlap, the shared moment, the meet-cute 🌸
  • getMigrationSF() — hands you the SF <#petsc4py.PETSc.SF> that migrates data from a parent DM <#petsc4py.PETSc.DM> into this DM <#petsc4py.PETSc.DM>. moving-day energy fr 🚚✨
  • getMinRadius() — the smallest distance from any cell centroid to a face. that's the measurement, periodt 📏
  • getOrdering(otype) — calculates a reordering of the mesh, using the ordering type you pass in. reorganizing the whole grid's vibe 💅
  • getPartitioner() — returns the mesh partitioner. who's doing the splitting-up duties 🧩
  • getPointDepth(point) — returns the depth of a given point. how deep in the hierarchy it sits 🌊
  • getPointGlobal(point) — gives you the location of point data inside a global Vec <#petsc4py.PETSc.Vec>. 🌍
  • getPointGlobalField(point, field) — same idea but for a point field's data, located in a global Vec <#petsc4py.PETSc.Vec>. two args: point and field 🎯
  • getPointHeight(point) — returns the height of a given point. yes bestie, height, not depth, stay with me 🙈
  • getPointLocal(point) — location of point data inside a local Vec <#petsc4py.PETSc.Vec>. 🏠
  • getPointLocalField(point, field) — the field-flavoured version, local Vec <#petsc4py.PETSc.Vec>, takes point and field. 🍓
  • getRefinementLimit() — retrieves the max cell volume that's allowed for refinement. no cell bigger than this gets the glow-up 🌸
  • getRefinementUniform() — retrieves the flag that says whether refinement is uniform. tfw everyone gets refined equally 👑
  • getSubpointIS() — returns an IS <#petsc4py.PETSc.IS> that covers the entire subdm chart. the whole thing, no crumbs 🎀
  • getSubpointMap() — returns a DMLabel <#petsc4py.PETSc.DMLabel> where the point dimension is stored as the values. 📛
  • getSupport(p) — returns the points sitting on the out-edges for this point in the DAG. who's downstream of you, bestie 🌈
  • getSupportSize(p) — just the count of those out-edges for this point in the DAG. lowkey the same question, numerically 🔢
  • getTransitiveClosure(p[, useCone]) — returns the points and orientations on the transitive closure of this point. optional useCone arg if you want the cone flavour. 🌟
  • getVecClosure(sec, vec, point) — returns an array of the values on the closure of a point. takes a sec, a vec, and a point. 📦
  • getVertexNumbering() — returns a global vertex numbering covering all the vertices on this process. everybody gets a name 🔥
  • globalToNaturalBegin(gv, nv) — rearranges a Vec <#petsc4py.PETSc.Vec> from Global order into natural order. args: gv, nv. 🔄
  • globalToNaturalEnd(gv, nv) — yep, same deal: rearranges a Vec <#petsc4py.PETSc.Vec> from the Global order into the natural order, with gv and nv. the begin/end pair, together forever 🫶
  • globalVectorLoad(viewer, sectiondm, sf, vec) — loads on-disk vector data into a global vector. inputs are viewer, sectiondm, sf, vec. 💾
  • globalVectorView(viewer, sectiondm, vec) — saves a global vector. takes viewer, sectiondm, vec. 💖
  • insertCone(p, conePos, conePoint) — DMPlexInsertCone - Insert

… a point into the in-edges for the point p in the DAG. 💅

  • insertConeOrientation(p, conePos, ...) — Inserts a point orientation for the in-edge for the point p in the DAG. 🦋
  • interpolate() — Converts to a mesh with all intermediate faces, edges, etc. 😭
  • isDistributed() — Returns the flag indicating if the mesh is distributed. 🌈
  • isSimplex() — Returns the flag indicating if the first cell is a simplex. 👑
  • labelCohesiveComplete(label, bdlabel, ...) — Adds all other mesh pieces to complete the surface. 💖
  • labelComplete(label) — Adds the transitive closure to the surface. ✨
  • labelsLoad(viewer, sfxc) — Loads labels into this DMPlex object. 🎀
  • labelsView(viewer) — Saves DMPlex labels into a file. 🦋
  • localVectorLoad(viewer, sectiondm, sf, vec) — Loads on-disk vector data into a local vector. 🌸
  • localVectorView(viewer, sectiondm, vec) — Saves a local vector. 💅
  • markBoundaryFaces(label[, value]) — Marks all faces on the boundary. 🔥
  • metricAverage2(metric1, metric2, metricAvg) — Computes and returns the unweighted average of two metrics. 💜
  • metricAverage3(metric1, metric2, metric3, ...) — Computes and returns the unweighted average of three metrics. 💀
  • metricCreate([field]) — Creates a Riemannian metric field. 🙈
  • metricCreateIsotropic(indicator[, field]) — Constructs an isotropic metric from an error indicator. 🍓
  • metricCreateUniform(alpha[, field]) — Constructs a uniform isotropic metric. 🧚
  • metricDeterminantCreate([field]) — Creates the determinant field for a Riemannian metric. 💜
  • metricEnforceSPD(metric, ometric, determinant) — Enforces symmetric positive-definiteness of a metric. ⭐
  • metricGetGradationFactor() — Returns the metric gradation factor. 🌈
  • metricGetHausdorffNumber() — Returns the metric Hausdorff number. 👑
  • metricGetMaximumAnisotropy() — Returns the maximum tolerated metric anisotropy. 💅
  • metricGetMaximumMagnitude() — Returns the maximum tolerated metric magnitude. 🔥
  • metricGetMinimumMagnitude() — Returns the minimum tolerated metric magnitude. 💖
  • metricGetNormalizationOrder() — Returns the order p for L-p normalization. ✨
  • metricGetNumIterations() — Returns the number of parallel adaptation iterations. 🦋
  • metricGetTargetComplexity() — hands you back the target metric complexity 🎯 that's the number the adaptation is chasing, no cap.
  • metricGetVerbosity() — returns how chatty the mesh adaptation package is feeling, i.e. its verbosity level 🗣️
  • metricIntersection2(metric1, metric2, metricInt) — does the math AND returns the intersection of metric1 and metric2, dropping the result into metricInt ✨
  • metricIntersection3(metric1, metric2, ...) — same energy but for three metrics at once, the ellipsis is doing heavy lifting bestie 💅
  • metricIsIsotropic() — returns the flag that says whether the metric is isotropic or not 🧭
  • metricIsUniform() — returns the flag that says whether the metric is uniform or not 🌈
  • metricNoInsertion() — returns the flag telling you whether node insertion and deletion are turned off 🙅 both of them, together, periodt.
  • metricNoMovement() — returns the flag for whether node movement is turned off 🚫
  • metricNoSurf() — returns the flag for whether surface modification is turned off 🌊
  • metricNoSwapping() — returns the flag for whether facet swapping is turned off 🔄
  • metricNormalize(metric, ometric, determinant) — applies L-p normalization to a metric 📐
  • metricRestrictAnisotropyFirst() — returns true if anisotropy gets restricted before normalization, order matters bestie 👑
  • metricSetFromOptions() — configures the object straight from the options database, very set-up-and-go of it ⚙️
  • metricSetGradationFactor(beta) — sets the metric gradation factor, that's beta 🍓
  • metricSetHausdorffNumber(hausd) — sets the metric Hausdorff number, aka hausd 📏
  • metricSetIsotropic(isotropic) — records whether the metric is isotropic or not, you're the one telling it 📝
  • metricSetMaximumAnisotropy(a_max) — sets the maximum tolerated metric anisotropy, cap it at a_max 🔥
  • metricSetMaximumMagnitude(h_max) — sets the maximum tolerated metric magnitude, that's h_max ⬆️
  • metricSetMinimumMagnitude(h_min) — sets the minimum tolerated metric magnitude, that's h_min ⬇️
  • metricSetNoInsertion(noInsert) — sets the flag for whether node insertion should be turned off, via noInsert 🙈
  • metricSetNoMovement(noMove) — sets the flag for whether node movement should be turned off, via noMove 🛑
  • metricSetNoSurf(noSurf) — sets the flag for whether surface modification should be turned off, via noSurf 🏝️
  • metricSetNoSwapping(noSwap) — sets the flag for whether facet swapping should be turned off, via noSwap 🔁
  • metricSetNormalizationOrder(p) — sets the order p used for L-p normalization 🧮
  • metricSetNumIterations(numIter) — sets the number of parallel adaptation iterations, that's numIter 🔂
  • metricSetRestrictAnisotropyFirst(...) — notes down whether the anisotropy gets restricted before normalization or after. just so the mesh adaptation package knows the order of operations, bestie 💅
  • metricSetTargetComplexity(targetComplexity) — sets the target metric complexity. that's the number you're aiming for, periodt ✨
  • metricSetUniform(uniform) — records whether the metric is uniform or not. simple as 🎀
  • metricSetVerbosity(verbosity) — sets how chatty the mesh adaptation package is allowed to be. yes, you can make it quieter 🔇
  • migrateGlobalToNaturalSF(dmOld, ...) — creates the SF for mapping a Global Vec over to the Natural Vec inside the new DM. it's giving glow-up-but-for-index-orderings 🦋
  • naturalToGlobalBegin(nv, gv) — rearranges a Vec from natural order into Global order. this is the begin half, so it's asynchronous — pair it with the End call like the iconic duo they are 👑
  • naturalToGlobalEnd(nv, gv) — the other half. finishes rearranging a Vec from natural order into Global order. no cap, you need both 🫶
  • orient() — gives the input mesh a consistent orientation. everything pointing the same way, as it should 🌈
  • orientLabel(label) — same energy, but for the hypersurface that's marked by a label. that label is the VIP list 💜
  • orientPoint(p, o) — acts on this mesh point with the given orientation. one point at a time, main character energy ⭐
  • permute(perm) — reorders the mesh according to the input permutation. you hand it the order, it does the shuffle 🔥
  • rebalanceSharedPoints([entityDepth, ...]) — redistributes shared points so the whole thing balances better. load balancing is self-care fr fr 😌
  • reorderGetDefault() — returns a flag telling you whether the DMPlex should be reordered by default. it's a question-asker, not a doer 🌸
  • reorderSetDefault(flag) — sets that flag, but this one's about whether the DM should be reordered by default. yes the wording differs between the get and the set, and yes that's just how it is 💀
  • sectionLoad(viewer, sectiondm, sfxc) — loads a section into a DM. 📥
  • sectionView(viewer, sectiondm) — saves the section associated with a DMPlex. 📤 (one loads, one saves — do not mix them up bestie, i'm begging 🙈)
  • setAdjacencyUseAnchors([useAnchors]) — defines adjacency in the mesh using the point-to-point constraints. anchors: the vibe, lowkey 🎀
  • setCellType(p, ctype) — sets the polytope type of a given cell. name the shape, so it can be the shape ✨
  • setChart(pStart, pEnd) — sets the interval for all mesh points, [pStart, pEnd). note the open bracket on the right — pEnd itself is not included, that's a half-open interval and it matters 💅
  • setCone(p, cone[, orientation]) — sets the points on the in-edges for this point in the DAG. orientation is optional here 🦋
  • setConeOrientation(p, orientation) — sets the orientations on the in-edges for this point in the DAG. the orientation-only version, in case the cones are already set ⭐
  • setConeSize(p, size) — sets the number of in-edges for this point in the DAG. gotta declare how many before you start filling them in 📐
  • setMatClosure(sec, gsec, mat, point, values) — sets an array of the values on the closure of point. peak "grab the whole neighborhood" behaviour 👑
  • setMigrationSF(sf) — sets the SF for migrating from a parent DM.
  • setPartitioner(part) — Set the mesh partitioner. 🧩
  • setRefinementLimit(refinementLimit) — Set the maximum cell volume for refinement.
  • setRefinementUniform([refinementUniform]) — Set the flag for uniform refinement.
  • setSupport(p, supp) — Set the points on the out-edges for this point in the DAG.
  • setSupportSize(p, size) — Set the number of out-edges for this point in the DAG.
  • setTetGenOptions(opts) — Set the options used for the Tetgen mesh generator.
  • setTriangleOptions(opts) — Set the options used for the Triangle mesh generator.
  • setVecClosure(sec, vec, point, values[, addv]) — Set an array of the values on the closure of point.
  • stratify() — Calculate the strata of DAG.
  • symmetrize() — Create support (out-edge) information from cone (in-edge) information.
  • topologyLoad(viewer) — Load a topology into this DMPlex object.
  • topologyView(viewer) — Save a DMPlex topology into a file.
  • uninterpolate() — Convert to a mesh with only cells and vertices.
  • vecGetClosure(sec, vec, p) — Return an array of values on the closure of p.

(and for the record, bestie, the tail end of that one row that got cut off right before this part said: into this DM 💫 no cap)

Methods Documentation 📚✨

computeCellGeometryFVM(cell)

Compute the volume for a given cell. It's giving geometry queen.

Not collective. Not a group activity, she works alone on this one.

Parameters

  • cell (int) — The cell. 🎯

Returns

  • volume (float) — The cell volume.
  • centroid (ArrayReal) — The cell centroid.
  • normal (ArrayReal) — The cell normal, if appropriate.

Return type

tuple[float, ArrayReal, ArrayReal]

See also: DMPlex, DM.getCoordinateSection, DM.getCoordinates, DMPlexComputeCellGeometryFVM

Source code at petsc4py/PETSc/DMPlex.pyx:2350

computeGradientClementInterpolant(locX, locC)

Return the L2 projection of the cellwise gradient of a function onto P1. 🌈 Math but make it fashion.

Collective. Everybody's involved, we all up in this together fr fr.

Parameters

  • locX (Vec) — The coefficient vector of the function.
  • locC (Vec) — The output Vec which holds the Clement interpolant of the gradient.

Return type

Vec

See also: DM, DMPlex, DMPlexComputeGradientClementInterpolant

Source code at petsc4py/PETSc/DMPlex.pyx:3284

constructGhostCells(labelName=None)

Construct ghost cells which connect to every boundary face. 👻 iconic behaviour honestly.

Collective.

Parameters

  • labelName (str | None) — The name of the label specifying the boundary faces. Defaults to "Face Sets". (the default is literally right there, use it)

Returns

  • numGhostCells — The number of ghost cells added to the DMPlex.

Return type

int

See also: DM, DMPlex, DM.create, DMPlexConstructGhostCells

Source code at petsc4py/PETSc/DMPlex.pyx:2382

coordinatesLoad(viewer, sfxc)

Load coordinates into this DMPlex object. 📍 feeding her the info she needs.

Collective.

Parameters

  • viewer (Viewer) — The Viewer for the saved coordinates.
  • sfxc (SF) — The SF returned by topologyLoad.

Return type

None

…and that's the end of that one, no source line on the menu for this method, we move 💅

See also: DM, DMPlex, DM.load, DMPlex.topologyLoad, DMPlex.labelsLoad, DM.view, SF, Viewer, DMPlexCoordinatesLoad — the PETSc manual page for it lives at https://petsc.org/release/manualpages/DMPlex/DMPlexCoordinatesLoad.html

Source fr fr: petsc4py/PETSc/DMPlex.pyx:3457 — peep it at https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L3457

coordinatesView(viewer) 💾

Save DMPlex coordinates into a file. Yes bestie, we're writing the mesh coords out to disk. Glow up and all that. 🌸

Collective. (The whole crew has to be in on it, no ducking out. 💅)

Parameters

  • viewer (Viewer) — the Viewer that does the saving. It's the one holding the pen. 🖊️

Return type: None

See also: DM, DMPlex, DM.view, DMPlex.topologyView, DMPlex.labelsView, DMPlex.coordinatesLoad, Viewer, DMPlexCoordinatesView — docs at https://petsc.org/release/manualpages/DMPlex/DMPlexCoordinatesView.html

Source: petsc4py/PETSc/DMPlex.pyx:3324 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L3324

create(comm=None) 🦋

Create a DMPlex object, which encapsulates an unstructured mesh. That's the whole vibe — it's the thing that holds your unstructured mesh together like a cute little tote bag. 👜

Collective.

Parameters

  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm. Leave it empty and it picks for you, bestie, it's giving thoughtful. 🫶

Return type: Self

See also: DM, DMPlex, DM.create, DM.setType, DMPlexCreate — https://petsc.org/release/manualpages/DMPlex/DMPlexCreate.html

Source: petsc4py/PETSc/DMPlex.pyx:14 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L14

createBoxMesh(faces, lower=(0, 0, 0), upper=(1, 1, 1), simplex=True, periodic=False, interpolate=True, localizationHeight=0, sparseLocalize=True, comm=None) 📦

Create a mesh on the tensor product of intervals. It's a box, it's a mesh, it's iconic. 🔥

Collective.

Parameters

  • faces (Sequence[int]) — number of faces per dimension, or None for the default. Count 'em up. ✨
  • lower (Sequence[float] | None) — the lower left corner. Where the box starts, lowkey.
  • upper (Sequence[float] | None) — the upper right corner. Where it ends, highkey.
  • simplex (bool | None) — True for simplices, False for tensor cells. Pick your fighter. 💅
  • periodic (Sequence | str | int | bool | None) — the boundary type for the X, Y, Z direction, or None for DM.BoundaryType.NONE. Wrap around like your fave song on repeat. 🔁
  • interpolate (bool | None) — flag to create intermediate mesh entities (edges, faces). The in-between girlies.
  • localizationHeight (int | None) — flag to localize edges and faces in addition to cells; only significant for periodic meshes. (Only matters when things are periodic, periodt.)
  • sparseLocalize (bool | None) — flag to localize coordinates only for cells near the periodic boundary; only significant for periodic meshes. (Again: periodic only. Don't @ me.)
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type: Self

See also: DM, DMPlex, DM.setFromOptions, DMPlex.createFromFile, DM.setType, DM.create, DMPlexCreateBoxMesh — https://petsc.org/release/manualpages/DMPlex/DMPlexCreateBoxMesh.html

Source: petsc4py/PETSc/DMPlex.pyx:90 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L90

createBoxSurfaceMesh(faces, lower=(0, 0, 0), upper=(1, 1, 1), interpolate=True, comm=None) 🎀

Create a mesh on the surface of a box mesh using tensor cells. It's the skin of the box, the outer layer, the ~aesthetic~. ✨

Collective.

Parameters

  • faces (Sequence[int]) — number of faces per dimension, or None for the default.
  • lower (Sequence[float] | None) — the lower left corner.
  • upper (Sequence[float] | None) — the upper right corner.
  • interpolate (bool | None) — flag to create intermediate mesh pieces (edges, faces). Yes bestie, this one says pieces, not entities. Write it down, it's different from the other one. 😭
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type: Self

See also: DM, DMPlex, DM.setFromOptions, DMPlex.createBoxMesh, DMPlex.createFromFile, DM.setType, DM.create, DMPlexCreateBoxSurfaceMesh — https://petsc.org/release/manualpages/DMPlex/DMPlexCreateBoxSurfaceMesh.html

Source: petsc4py/PETSc/DMPlex.pyx:149 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L149

createCGNS(cgid, interpolate=True, comm=None) 🌈

Create a DMPlex mesh from a CGNS file. CFD girlies, this one's for you. 👑

Collective.

Parameters

  • cgid (int) — the CG id associated with a file and obtained using cg_open. It's the lil ticket number that says "yeah, I opened that file". 🎫

(...and the rest of the parameters are right around the corner in the next part — hold on, don't scroll away yet 💖)

  • interpolate (bool | None) — create faces and edges in the mesh, bestie 🦋
  • comm (Comm | None) — the MPI communicator, defaults to Sys.getDefaultComm

Return type — Self

See also: DM, DMPlex, DMPlex.create, DMPlex.createCGNSFromFile, DMPlex.createExodus, DMPlexCreateCGNS

Source code at petsc4py/PETSc/DMPlex.pyx:226

🌈 createCGNSFromFile(filename, interpolate=True, comm=None)

"Create a DMPlex mesh from a CGNS file." — literally reads your CGNS file and hands you a whole DMPlex mesh, no cap 💅

Collective, so everybody in the communicator comes along for the ride.

Parameters

  • filename (str) — the name of the CGNS file 📁
  • interpolate (bool | None) — create faces and edges in the mesh
  • comm (Comm | None) — the MPI communicator, defaults to Sys.getDefaultComm

Return type — Self

See also: DM, DMPlex, DMPlex.create, DMPlex.createCGNS, DMPlex.createExodus, DMPlexCreateCGNS

Source code at petsc4py/PETSc/DMPlex.pyx:254

🎀 createClosureIndex(sec)

Calculate an index for sec for the closure operation. It's giving "I build you an index so closure lookups don't crawl" ✨

Not collective — just you, doing your own thing.

Parameters

  • sec (Section) — the Section describing the layout in the local vector, or None to use the default section 🙈

Return type — None

See also: DM, DMPlex, Section, DMPlex.vecGetClosure, DMPlexCreateClosureIndex

Source code at petsc4py/PETSc/DMPlex.pyx:2164

🫶 createCoarsePointIS()

Create an IS covering the coarse DMPlex chart with the fine points as data. That's the whole vibe: coarse mesh chart, fine points riding shotgun 💜

Collective.

Returns

  • fpointIS — the IS of all the fine points which exist in the original coarse mesh

Return type — IS

See also: DM, DMPlex, IS, DM.refine, DMPlex.setRefinementUniform, DMPlexCreateCoarsePointIS

Source code at petsc4py/PETSc/DMPlex.pyx:1950

🦋 createCohesiveSubmesh(hasLagrange, value)

Extract the hypersurface defined by one face of the cohesive cells. Yes, you're peeling one face off and turning it into its own little submesh 🌸

Collective.

Parameters

  • hasLagrange (bool) — flag indicating whether the mesh has Lagrange dofs in the cohesive cells
  • value (int) — a label value

Return type — DMPlex

See also: DM, DMPlex, DMPlexCreateCohesiveSubmesh

Source code at petsc4py/PETSc/DMPlex.pyx:401

🔥 createColoring(depth=0, distance=1)

Return the coloring of the connectivity graph of entities in the DMPlex. Bestie, it's graph coloring — and yes, we do it in parallel 👑

Collective.

Parameters

  • depth (int) — the entity dimension of nodes in the connectivity graph
  • distance (int) — the distance of the coloring (either 1 or 2)

Return type — list

Heads up: distance is only allowed to be 1 or 2. Anything else is not it. 💀

See also: DM, DMPlex, DMPlexCreateColoring

Source code at petsc4py/PETSc/DMPlex.pyx:424

✨ createCoordinateSpace(degree, localized, project)

Create a finite element space for the coordinates. Coordinates are getting their own whole FE space, main character energy for real 🎀

Collective.

Parameters

  • degree (int) — the degree of the finite element
  • localized (bool) — flag to create a localized (DG) coordinate space
  • project (bool) — flag to project current coordinates into the space

Return type — None

See also: DM, DMPlex, DMPlexCreateCoordinateSpace

Source code at petsc4py/PETSc/DMPlex.pyx:377

🌈 createExodus(exoid, interpolate=True, comm=None)

Create a DMPlex mesh from an ExodusII file ID. You already have the id, hand it over and get a mesh back 💖

Collective.

Parameters

  • exoid (int) — the ExodusII id associated with a file obtained using ex_open
  • interpolate (bool | None) — create faces and edges in the mesh,
  • comm (Comm | None) — the MPI communicator, defaults to Sys.getDefaultComm

Return type — Self

See also: DM, DMPlex, DM.create, DMPlexCreateExodus

Source code at petsc4py/PETSc/DMPlex.pyx:312

🍓 createExodusFromFile(filename, interpolate=True, comm=None)

Create a DMPlex mesh from an ExodusII file. Same slay as above but you pass the name of the file instead of a raw exoid ✨

Collective.

Parameters

  • filename (str) — the name of the ExodusII file 📁
  • interpolate (bool | None) — create faces and edges in the mesh.
  • comm (Comm | None) — the MPI communicator, bestie. Defaults to Sys.getDefaultComm. 💌

Return type: Self

See also: DM, DMPlex, DM.create, DMPlex.createExodus, DMPlexCreateExodusFromFile

Source code at petsc4py/PETSc/DMPlex.pyx:283

🧩 createFromCellList(dim, cells, coords, interpolate=True, comm=None)

Okay so this one creates a DMPlex from a list of vertices for each cell — and it does it all on process 0. No cap. 👑

Collective. (everyone's in the group chat for this one 🫶)

Parameters

  • dim (int) — the topological dimension of the mesh. like, how many dimensions are we dimensioning here.
  • cells (Sequence[int]) — an array of number of cells times number of vertices on each cell.
  • coords (Sequence[float]) — an array of number of vertices times spatial dimension for coordinates.
  • interpolate (bool | None) — flag to interpolate the mesh.
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type: Self

See also: DM, DMPlex, DMPlex.create, DMPlex.interpolate, DMPlexCreateFromCellListPetsc

Source code at petsc4py/PETSc/DMPlex.pyx:35

📂 createFromFile(filename, plexname='unnamed', interpolate=True, comm=None)

the way this just... pulls a whole DMPlex out of a file?? iconic behavior honestly. 📁✨

Collective.

Parameters

  • filename (str) — a file name. yes bestie, it's literally just the name of your file.
  • plexname (str | None) — the name of the resulting DMPlex, also used for intra-datafile lookup by some formats. so some formats will go looking for it inside the file. noted. 📝
  • interpolate (bool | None) — flag to create intermediate mesh pieces (edges, faces).
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type: Self

See also: DM, DMPlex, DMPlex.createFromCellList, DMPlex.create, Object.setName, DM.view, DM.load, Working with PETSc options, DMPlexCreateFromFile

Source code at petsc4py/PETSc/DMPlex.pyx:192

🌉 createGlobalToNaturalSF(section, sfMigration)

Creates the SF for mapping Global Vec to the Natural Vec. it's giving translator energy, it's giving bridges between two worlds. 💫

Collective.

See also: DMPlexCreateGlobalToNaturalSF

Source code at petsc4py/PETSc/DMPlex.pyx:3673

Parameters

  • section (Section)
  • sfMigration (SF)

Return type: SF

🐟 createGmsh(viewer, interpolate=True, comm=None)

Creates a DMPlex mesh from a Gmsh file viewer. slay. 🦋

Collective.

Parameters

  • viewer (Viewer) — the Viewer associated with a Gmsh file.
  • interpolate (bool | None) — create faces and edges in the mesh.
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type: Self

Notes

  • -dm_plex_gmsh_hybrid forces triangular prisms to use tensor order.
  • -dm_plex_gmsh_periodic allows for reading Gmsh periodic section.
  • -dm_plex_gmsh_highorder allows for generating high-order coordinates.
  • -dm_plex_gmsh_project projects high-order coordinates to a different space, use the prefix -dm_plex_gmsh_project_ to define the space.
  • -dm_plex_gmsh_use_regions generates labels with region names.
  • -dm_plex_gmsh_mark_vertices adds vertices to generated labels.
  • -dm_plex_gmsh_multiple_tags allows multiple tags for default labels.
  • -dm_plex_gmsh_spacedim <d> embedding space dimension.

See also: DM, DMPlex, DM.create, Working with PETSc options, DMPlexCreateGmsh

Source code at petsc4py/PETSc/DMPlex.pyx:339

🍃 createNaturalVec()

Returns a natural vector. that's it, that's the whole vibe. natural. organic. free-range. no additives. 🌱

Collective.

See also: DMPlexCreateNaturalVector

Source code at petsc4py/PETSc/DMPlex.pyx:3584

Return type: Vec

🔢 createPointNumbering()

Creates a global numbering for all points. every point gets its own little assigned name tag, fr fr. 🏷️

Collective.

See also: DM, DMPlex, DMPlex.getCellNumbering, DMPlexCreatePointNumbering

Source code at petsc4py/PETSc/DMPlex.pyx:1048

Return type: IS

🎀 createSection(numComp, numDof, bcField=None, bcComps=None, bcPoints=None, perm=None)

Creates a Section based upon the DOF layout specification provided. build-a-section workshop, bestie. 🛠️

Not collective. (this one you do solo, main character energy, no group project 💅)

Parameters

  • numComp (Sequence[int]) — an array of size numFields holding the number of components per field.
  • numDof (Sequence[int]) — an array of size numFields*(dim+1) holding how many DOFs live on each field, for a mesh piece of dimension dim. 🧮
    • bcField (Sequence[int] or None) — an array of size numBC giving the field number for each boundary condition, where numBC is (you guessed it) the number of boundary conditions. 🎯
    • bcComps (Sequence[IS] or None) — an array of size numBC where each entry is an IS holding the field components that each boundary condition applies to. 🌸
    • bcPoints (Sequence[IS] or None) — an array of size numBC where each entry is an IS holding the DMPlex points that each boundary condition applies to. 📍
    • perm (IS or None) — a permutation of the chart. 🔀

Return type: Section

See also: DM, DMPlex, DMPlex.create, Section.create, Section.setPermutation, DMPlexCreateSection

Source code at petsc4py/PETSc/DMPlex.pyx:1970

distribute(overlap=0) 🚚

Distribute the mesh, plus any sections that are tagging along for the ride.

Collective — everybody's in this together, bestie. 🫶

Parameters

  • overlap (int or None) — the overlap of the partitions.

Returns

  • sf — the SF used for point distribution, or None if it did not get distributed.

Return type: SF or None

See also: DM, DMPlex, DMPlex.create, DMPlexDistribute

Source code at petsc4py/PETSc/DMPlex.pyx:1694

distributeField(sf, sec, vec, newsec=None, newvec=None) 📦✨

Distribute field data using a given SF.

Collective.

Parameters

  • sf (SF) — the SF describing the communication pattern. 📡
  • sec (Section) — the Section for the existing data layout.
  • vec (Vec) — the existing data, sitting in a local vector.
  • newsec (Section or None) — the SF describing the new data layout. (yes, the page really calls it an SF there, I'm just the messenger 🙈)
  • newvec (Vec or None) — the new data, in a local vector.

Returns

  • newSection (Section) — the SF describing the new data layout.
  • newVec (Vec) — the new data in a local vector.

Return type: tuple[Section, Vec]

See also: DMPlex, DMPlex.distribute, DMPlexDistributeField

Source code at petsc4py/PETSc/DMPlex.pyx:1891

distributeGetDefault() 🔍

Return a flag telling you whether the DM should be distributed by default.

Not collective.

Returns

  • dist — the flag saying whether the DMPlex should be distributed by default.

Return type: bool

See also: DM, DMPlex, DMPlex.distributeSetDefault, DMPlex.distribute, DMPlexDistributeGetDefault

Source code at petsc4py/PETSc/DMPlex.pyx:1780

distributeOverlap(overlap=0) 🫂

Add partition overlap to a distributed non-overlapping DMPlex. It's giving "let's make the neighbors gossip". 💅

Collective.

Parameters

  • overlap (int or None) — the overlap of the partitions (the same on all ranks, no favoritism ✋).

Returns

  • sf — the SF used for point distribution.

Return type: SF

See also: DM, DMPlex, SF, DMPlex.create, DMPlex.distribute, DMPlexDistributeOverlap

Source code at petsc4py/PETSc/DMPlex.pyx:1722

distributeSetDefault(flag) 🎚️

Set that flag indicating whether the DMPlex should be distributed by default.

Logically collective.

Parameters

  • flag (bool) — the flag indicating whether the DMPlex should be distributed by default.

Return type: None

See also: DMPlex, DMPlex.distributeGetDefault, DMPlex.distribute, DMPlexDistributeSetDefault

Source code at petsc4py/PETSc/DMPlex.pyx:1800

distributionGetName() 🏷️

Retrieve the name of the specific parallel distribution.

Not collective.

Returns

  • name — the name of the specific parallel distribution.

Return type: str

See also: DMPlex, DMPlex.distributionSetName, DMPlex.topologyView, DMPlex.topologyLoad, DMPlexDistributionGetName

Source code at petsc4py/PETSc/DMPlex.pyx:1841

distributionSetName(name) ✍️

Set the name of the specific parallel distribution.

Logically collective.

Parameters

  • name (str) — the name of the specific parallel distribution.

Return type: None

See also: DMPlex, DMPlex.distributionGetName, DMPlex.topologyView, DMPlex.topologyLoad, DMPlexDistributionSetName

Source code at petsc4py/PETSc/DMPlex.pyx:1837

petsc4py/PETSc/DMPlex.pyx:1820 — that's the source line for the one we were just on, for the record keepers 🧾. anyway. NEXT.

🔪 filter(label=None, value=None, ignoreHalo=False, sanitizeSubMesh=False, comm=None)

Stop everything, this one is giving surgical 💅. It takes a subset of mesh cells that you've tagged up with a label and pulls them out as their own whole separate mesh. Iconic. It is Collective, so no ghosting your buddies — everybody's in the group chat or nobody is.

Parameters — read them, bestie, don't skim:

  • cellLabel — label marking the cells that get to be in the new mesh
  • value (int | None) — label value to use
  • ignoreHalo (bool) — Flag indicating if labeled points that are in the halo are ignored
  • sanitizeSubmesh — Flag indicating if a subpoint is forced to be owned by a rank that owns a subcell that contains that point in its closure
  • comm (Comm | None) — The communicator you want the mesh on
  • label (DMLabel | None)
  • sanitizeSubMesh (bool)

Return type: tuple[DMPlex, SF]

Yeah, you get back a two-for-one — a DMPlex and an SF. Two besties in one bag 🫶

See also: DM, DMPlex, DMPlexFilter

Source: petsc4py/PETSc/DMPlex.pyx:453

🏗️ generate(boundary, name=None, interpolate=True)

Make a mesh. That's it, that's the whole vibe ✨. It is Not collective, so you can do this one solo, no phone call needed.

Parameters:

  • boundary (DMPlex) — The DMPlex boundary object.
  • name (str | None) — The mesh generation package name.
  • interpolate (bool | None) — Flag to create intermediate mesh elements. (default is True, in case you were wondering why your mesh looks so thorough 🌸)

Return type: Self

See also: DM, DMPlex, DMPlex.create, DM.refine, Working with PETSc options, DMPlexGenerate

Source: petsc4py/PETSc/DMPlex.pyx:1417

🕸️ getAdjacency(p)

Hands you back every point that's adjacent to the point you passed in. Basically "who's in this point's circle?" 💅 Not collective.

Parameters:

  • p (int) — The point.

Return type: ArrayInt

See also: DMPlex, DMPlex.distribute, DMPlexGetAdjacency

Source: petsc4py/PETSc/DMPlex.pyx:1600

🎯 getAdjacencyUseAnchors()

A little yes/no check-in: does adjacency in this mesh use the point-to-point constraints or not? Not collective — you can just ask, nobody has to convene.

See also: DMPlex, DMPlex.getAdjacency, DMPlex.distribute, DMPlexGetAdjacencyUseAnchors

Source: petsc4py/PETSc/DMPlex.pyx:1585

Return type: bool

🔢 getCellNumbering()

Gives you a global cell numbering for all the cells on this process — your own little numbered stack, immaculate 📚. It is Collective the first time it is called, and then it chills. That first call is the group project; after that it's just you.

See also: DM, DMPlex, DMPlex.getVertexNumbering, DMPlexGetCellNumbering

Source: petsc4py/PETSc/DMPlex.pyx:1018

Return type: IS

🔷 getCellType(p)

Tells you the polytope type of a given cell — like, what shape are you actually 🔺. Not collective.

Parameters:

  • p (int) — The cell.

Return type: PolytopeType

See also: DM, DMPlex, DM.PolytopeType, DMPlex.getCellTypeLabel, DMPlex.getDepth, DMPlexGetCellType

Source: petsc4py/PETSc/DMPlex.pyx:780

🏷️ getCellTypeLabel()

Returns the DMLabel that records the polytope type of every single cell — it's the receipts file for shapes 🧾✨. Not collective.

See also: DM, DMPlex, DMPlex.getCellType, DM.createLabel, DMPlexGetCellTypeLabel

Source: petsc4py/PETSc/DMPlex.pyx:801

Return type: DMLabel

📏 getChart()

Gives you the interval holding all your mesh points, written as [pStart, pEnd) — and yes it's the half-open one, pEnd is not included, don't come for me 🙈. Not collective.

Returns:

  • pStart (int) — The first mesh point.
  • pEnd (int) — The upper bound for mesh points.

Return type: tuple[int, int]

See also: DM, DMPlex, DMPlex.create, DMPlex.setChart, DMPlexGetChart

Source: petsc4py/PETSc/DMPlex.pyx:495

🧺 getCone(p)

Returns the points on the in-edges for this point in the DAG — the whole incoming squad 🫂. Not collective.

Parameters:

  • p (int) — The point, which must lie in the chart set with DMPlex.setChart.

Return type: ArrayInt

See also: DM, DMPlex, DMPlex.getConeSize, DMPlex.setCone, DMPlex.setChart, DMPlexGetCone

Source: petsc4py/PETSc/DMPlex.pyx:586

🔄 getConeOrientation(p)

Same energy as getCone but it's handing you the orientations on those in-edges for this point in the DAG. Direction matters, bestie 🧭. Not collective.

Parameters:

  • p (int) — The point, which must lie in the chart set with DMPlex.setChart.

Return type: ArrayInt

See also: DM, DMPlex, DMPlex.create, DMPlex.getCone, DMPlex.setCone, DMPlex.setChart, DMPlexGetConeOrientation

lil housekeeping bestie — that Source code at petsc4py/PETSc/DMPlex.pyx:701 hanging at the top belongs to the method right above this one, not to any of the stuff below. carry on 💖

🌸 getConeSize(p)

"How many in-edges does this point have in the DAG?" — that's the whole question, and this method is the whole answer. in-edges = the cone. 🦋

Not collective.

Parameters

  • p (int) — the point you're asking about. It has to be inside the chart you set with DMPlex.setChart, no stray points allowed.

Return type: int

See also: DM, DMPlex, DMPlex.create, DMPlex.setConeSize, DMPlex.setChart, DMPlexGetConeSize

Source: petsc4py/PETSc/DMPlex.pyx:537

🎀 getDepth()

Returns the depth of the DAG that's representing this mesh. that's the vibe. 👑

Not collective.

See also: DM, DMPlex, DMPlex.getDepthStratum, DMPlex.symmetrize, DMPlexGetDepth

Return type: int

Source: petsc4py/PETSc/DMPlex.pyx:1062

✨ getDepthStratum(svalue)

Hands you back the bounds [start, end) covering every point at a certain depth. note the half-open interval, we don't do closed intervals here 💅

Not collective.

Parameters

  • svalue (int) — the depth you're requesting.

Returns

  • pStart (int) — the first stratum point.
  • pEnd (int) — the upper bound for stratum points.

Return type: tuple[int, int]

See also: DM, DMPlex, DMPlex.getHeightStratum, DMPlex.getDepth, DMPlex.symmetrize, DMPlex.interpolate, DMPlexGetDepthStratum

Source: petsc4py/PETSc/DMPlex.pyx:1077

🦋 getFullJoin(points)

Gives you an array for the join of a set of points. yes, the full one. the deluxe edition. 🌈

Not collective.

Parameters

  • points (Sequence[int]) — the input points.

Return type: ArrayInt

See also: DM, DMPlex, DMPlex.getJoin, DMPlex.getMeet, DMPlexGetFullJoin

Source: petsc4py/PETSc/DMPlex.pyx:1225

🍓 getHeightStratum(svalue)

Same energy as the depth one, but for height. returns the bounds [start, end) for all the points at a certain height. ✨

Not collective.

Parameters

  • svalue (int) — the height you're requesting.

Returns

  • pStart (int) — the first stratum point.
  • pEnd (int) — the upper bound for stratum points.

Return type: tuple[int, int]

See also: DM, DMPlex, DMPlex.getDepthStratum, DMPlex.getDepth, DMPlexGetHeightStratum

Source: petsc4py/PETSc/DMPlex.pyx:1104

💫 getJoin(points)

Returns an array for the join of the set of points you hand it. it's giving set-theory-but-make-it-mesh. 🧚

Not collective.

Parameters

  • points (Sequence[int]) — the input points.

Return type: ArrayInt

See also: DM, DMPlex, DMPlex.getMeet, DMPlexGetJoin

Source: petsc4py/PETSc/DMPlex.pyx:1199

👑 getMaxSizes()

"What's the biggest cone and the biggest support in this DAG?" — answered, in one call. the maximum in-edges and out-edges, no cap. 🔥

Not collective.

Returns

  • maxConeSize (int) — the maximum number of in-edges.
  • maxSupportSize (int) — the maximum number of out-edges.

Return type: tuple[int, int]

See also: DM, DMPlex, DMPlex.create, DMPlex.setConeSize, DMPlex.setChart, DMPlexGetMaxSizes

Source: petsc4py/PETSc/DMPlex.pyx:921

🌸 getMeet(points)

The meet of your set of points, as an array. join's little sibling, equally iconic. 🫶

Not collective.

Parameters

  • points (Sequence[int]) — the input points.

Return type: ArrayInt

See also: DM, DMPlex, DMPlex.getJoin, DMPlexGetMeet

Source: petsc4py/PETSc/DMPlex.pyx:1173

💜 getMigrationSF()

Gets you the SF for migrating from a parent DM into this DM. it's literally the moving van for your mesh data. 🚚✨

Not collective.

See also: DMPlexGetMigrationSF

Source: petsc4py/PETSc/DMPlex.pyx:3658

Return type: SF

🎀 getMinRadius()

Returns the minimum distance from any cell centroid to a face. tiny number, big importance. ⭐

Not collective.

See also: DMPlex, DM.getCoordinates, DMPlexGetMinRadius

Source: petsc4py/PETSc/DMPlex.pyx:1936

Return type: float

🦋 getOrdering(otype)

Calculates a reordering of the mesh. yes bestie, we're shuffling the points and it's on purpose. 👑

Collective.

Parameters

  • otype (OrderingType) — the type of reordering you want, see Mat.OrderingType.

Returns

  • perm — the point permutation.

Return type: IS

Source: petsc4py/PETSc/DMPlex.pyx:1417

getPartitioner()

Give me the mesh partitioner bestie, literally just hands it over 💅

Not collective — everyone has their own, no group huddle required.

See also: DM, DMPlex, Partitioner, Section, DMPlex.distribute, DMPlex.setPartitioner, Partitioner.create, PetscPartitionerDMPlexPartition (https://petsc.org/release/manualpages/DMPlex/PetscPartitionerDMPlexPartition.html), DMPlexGetPartitioner (https://petsc.org/release/manualpages/DMPlex/DMPlexGetPartitioner.html)

Source code at petsc4py/PETSc/DMPlex.pyx:1643 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L1643

Return type: Partitioner

getPointDepth(point)

How deep is this point, bestie? Sends you back the depth of a given point ✨

Not collective.

Parameters

  • point (int) — The point.

Return type: int

See also: DM, DMPlex, DMPlex.getDepthStratum, DMPlex.getDepth, DMPlexGetPointDepth (https://petsc.org/release/manualpages/DMPlex/DMPlexGetPointDepth.html)

Source code at petsc4py/PETSc/DMPlex.pyx:1131 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L1131

getPointGlobal(point)

Where does this point's data live in the global Vec? Global address reveal, no cap 🌍💖

Not collective.

Parameters

  • point (int) — The topological point.

Returns

  • start (int) — Start of point data; returns -(globalStart+1) if point is not owned.
  • end (int) — End of point data; returns -(globalEnd+1) if point is not owned.
heads up: if the point isn't yours, you don't get a normal number back — you get that negative encoded thing. iykyk.

Return type: tuple[int, int]

See also: DM, DMPlex, DMPlex.getPointGlobalField, Section.getOffset, Section.getDof, DMPlex.getPointLocal, DMPlexGetPointGlobal (https://petsc.org/release/manualpages/DMPlex/DMPlexGetPointGlobal.html)

Source code at petsc4py/PETSc/DMPlex.pyx:2105 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L2105

getPointGlobalField(point, field)

Same energy as getPointGlobal but for one specific field — global address of that field's data in the global Vec 🎀

Not collective.

Parameters

  • point (int) — The topological point.
  • field (int) — The field number.

Returns

  • start (int) — Start of point data; returns -(globalStart+1) if point is not owned.
  • end (int) — End of point data; returns -(globalEnd+1) if point is not owned.

Return type: tuple[int, int]

See also: DM, DMPlex, DMPlex.getPointGlobal, Section.getOffset, Section.getDof, DMPlex.getPointLocal, DMPlexGetPointGlobalField (https://petsc.org/release/manualpages/DMPlex/DMPlexGetPointGlobalField.html)

Source code at petsc4py/PETSc/DMPlex.pyx:2133 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L2133

getPointHeight(point)

How tall is this point? Returns the height of a given point 🌸

Not collective.

Parameters

  • point (int) — The point.

Return type: int

See also: DM, DMPlex, DMPlex.getHeightStratum, DMPlexGetPointHeight (https://petsc.org/release/manualpages/DMPlex/DMPlexGetPointHeight.html)

Source code at petsc4py/PETSc/DMPlex.pyx:1152 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L1152

getPointLocal(point)

local Vec address check-in for this point's data, bestie 💜

Not collective.

Parameters

  • point (int) — The topological point.

Returns

  • start (int) — Start of point data.
  • end (int) — End of point data.
no encoded-negatives drama here — local is local, you get real numbers.

Return type: tuple[int, int]

See also: DM, DMPlex, DMPlex.getPointLocalField, Section.getOffset, Section.getDof, DMPlexGetPointLocal (https://petsc.org/release/manualpages/DMPlex/DMPlexGetPointLocal.html)

Source code at petsc4py/PETSc/DMPlex.pyx:2046 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L2046

getPointLocalField(point, field)

local Vec address, but you pick the field 🦋

Not collective.

Parameters

  • point (int) — The topological point.
  • field (int) — The field number.

Returns

  • start (int) — Start of point data.
  • end (int) — End of point data.

Return type: tuple[int, int]

See also: DM, DMPlex, DMPlex.getPointLocal, Section.getOffset, DMPlexGetPointLocalField (https://petsc.org/release/manualpages/DMPlex/DMPlexGetPointLocalField.html)

Source code at petsc4py/PETSc/DMPlex.pyx:2074 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L2074

getRefinementLimit()

Pulls up the maximum cell volume used for refinement, fr fr 🔥

Not collective.

See also: DM, DMPlex, DM.refine, DMPlex.setRefinementLimit, DMPlex.getRefinementUniform, DMPlex.setRefinementUniform, DMPlexGetRefinementLimit (https://petsc.org/release/manualpages/DMPlex/DMPlexGetRefinementLimit.html)

Source code at petsc4py/PETSc/DMPlex.pyx:2247 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L2247

Return type: float

part 61 of 380 and we're still cooking 👑 the method list continues next, don't go anywhere

🦋 getRefinementUniform() 🦋

okay so this is the lil guy that tells you whether your refinement is set to uniform or not, like a vibe check for your refinement settings 💅

Not collective — every process reads its own answer, no gossip required 🫶

Returns: refinementUniform — the flag for uniform refinement.

Return type: bool

See also: DM, DMPlex, DM.refine, DMPlex.setRefinementUniform, DMPlex.getRefinementLimit, DMPlex.setRefinementLimit, DMPlexGetRefinementUniform

Source code: petsc4py/PETSc/DMPlex.pyx:2206

🎀 getSubpointIS() 🎀

this one serves you a whole IS that covers the entire subdm chart, no crumbs left behind ✨

Not collective — do it yourself bestie, no committee meeting 😌

Returns: iset — the IS containing subdm's parent's points.

Return type: IS

See also: DM, DMPlex, DMPlexGetSubpointIS

Source code: petsc4py/PETSc/DMPlex.pyx:2411

🌸 getSubpointMap() 🌸

she gives you back a DMLabel where the values are literally just your point dimensions. lowkey iconic ngl 💖

Not collective — solo mission, go off 👑

Returns: label — the DMLabel whose values are subdm's point dimensions.

Return type: DMLabel

See also: DM, DMPlex, DMPlexGetSubpointMap

Source code: petsc4py/PETSc/DMPlex.pyx:2431

💫 getSupport(p) 💫

returns the points sitting on the out-edges for this point in the DAG. it's giving "who comes after me in the graph" energy 🦋

Not collective — you're on your own and that's fine 💅

Parameters:

  • p (int) — the point, which must lie in the chart set with DMPlex.setChart.

Return type: ArrayInt

See also: DM, DMPlex, DMPlex.getSupportSize, DMPlex.setSupport, DMPlex.getCone, DMPlex.setChart, DMPlexGetSupport

Source code: petsc4py/PETSc/DMPlex.pyx:866

🌈 getSupportSize(p) 🌈

bestie this one just counts the out-edges for your point in the DAG. that's it. that's the whole function. slay 💅

Not collective — no gather, no broadcast, just numbers ✨

Parameters:

  • p (int) — the point, which must lie in the chart set with DMPlex.setChart.

Return type: int

See also: DM, DMPlex, DMPlex.create, DMPlex.setConeSize, DMPlex.setChart, DMPlex.getConeSize, DMPlexGetSupportSize

Source code: petsc4py/PETSc/DMPlex.pyx:817

🧚 getTransitiveClosure(p, useCone=True) 🧚

okay so this returns BOTH the points AND the orientations on the transitive closure of your point. two for the price of one, we love a bundle deal 💖

Not collective — everybody computes their own, no sharing required 😤

Parameters:

  • p (int) — the mesh point.
  • useCone (bool | None) — True for the closure, otherwise return the star.

Returns:

  • points (ArrayInt) — the points.
  • orientations (ArrayInt) — the orientations.

Return type: tuple[ArrayInt, ArrayInt]

See also: DM, DMPlex, DMPlex.create, DMPlex.setCone, DMPlex.setChart, DMPlex.getCone, DMPlexGetTransitiveClosure

Source code: petsc4py/PETSc/DMPlex.pyx:1251

🍓 getVecClosure(sec, vec, point) 🍓

gives you back an array of all the values living on the closure of a point. it's the "zoom in on this one spot" of vector land 🔍✨

Not collective — your point, your values, your business 🫶

Parameters:

  • sec (Section) — the Section describing the layout in vec, or None to use the default section.
  • vec (Vec) — the local vector.
  • point (int) — the point in the DMPlex.

Return type: ArrayScalar

See also: DM, DMPlex, DMPlexVecRestoreClosure

Source code: petsc4py/PETSc/DMPlex.pyx:1318

👑 getVertexNumbering() 👑

hands you a global vertex numbering covering all the vertices on this process. main character numbering energy fr fr 🌟

Collective the first time it is called — so the FIRST time you hit her, everybody has to talk it out. after that she's chill 😌

See also: DM, DMPlex, DMPlex.getCellNumbering, DMPlexGetVertexNumbering

Source code: petsc4py/PETSc/DMPlex.pyx:1033

Return type: IS

💜 globalToNaturalBegin(gv, nv) 💜

rearranges a Vec from the Global order into the natural order. glow-up for your vector's layout 💅

Collective — everybody's in on this one, no stragglers 🫂

See also: DMPlexGlobalToNaturalBegin

Source code: petsc4py/PETSc/DMPlex.pyx:3622

Parameters:

  • gv (Vec)
  • nv (Vec)

Return type: None

💜 globalToNaturalEnd(gv, nv) 💜

the closing act of the global → natural rearrangement of your Vec. we love a begin/end pair, very demure, very mindful 🎀

Collective — group project, everyone participates 💖

See also: DMPlexGlobalToNaturalEnd

Source code: petsc4py/PETSc/DMPlex.pyx:3634

Parameters:

  • gv (Vec)
  • nv (Vec)

Return type: None

⭐ globalVectorLoad(viewer, sectiondm, sf, vec) ⭐

she loads on-disk vector data INTO a global vector. it's giving "import my data bestie" 💾✨

Collective — yes, the whole squad is needed here 😌

Parameters:

  • viewer (Viewer) — the Viewer that represents the on-disk vector data.
  • sectiondm (DM) — the DM that contains the global section on which vec is defined.
  • sf (SF) — the SF that migrates the on-disk vector data into vec.
  • vec (Vec) — the global vector to set values of.

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

See also: DM, DMPlex, DMPlex.topologyLoad, DMPlex.sectionLoad, DMPlex.localVectorLoad, DMPlex.globalVectorView, DMPlex.localVectorView, SF, Viewer, DMPlexGlobalVectorLoad (https://petsc.org/release/manualpages/DMPlex/DMPlexGlobalVectorLoad.html)

Source code at petsc4py/PETSc/DMPlex.pyx:3534 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L3534)

✨ globalVectorView(viewer, sectiondm, vec) ✨

Okay bestie, this one is literally just "save a global vector" 🫶 like it drops your global vector into a Viewer so you can go look at it later. Iconic behavior.

Collective. Yes queen, everybody shows up for this one, all ranks gotta be in the group chat 💅

Parameters:

  • viewer (Viewer) — the Viewer you wanna save the data with. That's the destination, the vibe, the spot 📁
  • sectiondm (DM) — the DM holding the global section that vec is defined on. Lowkey note: it may be the same as this DMPlex object. No pressure either way 🦋
  • vec (Vec) — the global vector that's getting saved. Say bye, you're going to the Viewer ✨

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

See also: DM, DMPlex, DMPlex.topologyView, DMPlex.sectionView, DMPlex.localVectorView, DMPlex.globalVectorLoad, DMPlex.localVectorLoad, DMPlexGlobalVectorView (https://petsc.org/release/manualpages/DMPlex/DMPlexGlobalVectorView.html)

Source code at petsc4py/PETSc/DMPlex.pyx:3381 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L3381)

🔥 insertCone(p, conePos, conePoint) 🔥

DMPlexInsertCone — bestie this inserts a point into the in-edges for the point p in the DAG. It's giving "hand-placing your topology, one edge at a time" energy 🧚

Not collective. Just you, doing your thing, no committee meeting 💅

Parameters:

  • p (int) — the point. And heads up: it must lie in the chart set with DMPlex.setChart. No stray points allowed, miss thing 🚫
  • conePos (int) — the local index in the cone where the point should be put. It's the seat assignment, fr fr 💺
  • conePoint (int) — the mesh point to insert 👑

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

See also: DM, DMPlex, DMPlex.create, DMPlex.getCone, DMPlex.setChart, DMPlex.setConeSize, DM.setUp, DMPlexInsertCone (https://petsc.org/release/manualpages/DMPlex/DMPlexInsertCone.html)

Source code at petsc4py/PETSc/DMPlex.pyx:651 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L651)

🌈 insertConeOrientation(p, conePos, coneOrientation) 🌈

Sis, this one inserts a point orientation for the in-edge for the point p in the DAG. Same energy as insertCone but now we're specifying the direction, and honestly? That's the main character detail 🎀

Not collective. Solo mission, periodt 💅

Parameters:

  • p (int) — the point, which must lie in the chart set with DMPlex.setChart. Rule is the rule 🦋
  • conePos (int) — the local index in the cone where the point should be put 📍
  • coneOrientation (int) — the point orientation to insert. This is the ✨flavor✨ you're adding 🍓

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

See also: DM, DMPlex, DMPlex.create, DMPlex.getCone, DMPlex.setChart, DMPlex.setConeSize, DM.setUp, DMPlexInsertConeOrientation (https://petsc.org/release/manualpages/DMPlex/DMPlexInsertConeOrientation.html)

Source code at petsc4py/PETSc/DMPlex.pyx:676 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L676)

🦋 interpolate() 🦋

Convert to a mesh with all intermediate faces, edges, etc. Basically it fills in all the in-between bits — the faces, the edges, all the little connective tissue that was missing. It's giving glow-up, it's giving completion arc 😭✨

Collective. Everybody's involved, group effort, slay 👑

See also: DMPlex, DMPlex.uninterpolate, DMPlex.createFromCellList, DMPlexInterpolate (https://petsc.org/release/manualpages/DMPlex/DMPlexInterpolate.html)

Source code at petsc4py/PETSc/DMPlex.pyx:1861 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L1861)

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

⭐ isDistributed() ⭐

Return the flag indicating if the mesh is distributed. That's it, that's the whole thing. A little yes/no about whether your mesh is spread across ranks 🌐

Collective. Everyone checks together, no lone wolves 💅

See also: DM, DMPlex, DMPlex.distribute, DMPlexIsDistributed (https://petsc.org/release/manualpages/DMPlex/DMPlexIsDistributed.html)

Source code at petsc4py/PETSc/DMPlex.pyx:1751 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L1751)

Return type: bool (https://docs.python.org/3/builtins/functions.html#bool)

💜 isSimplex() 💜

Return the flag indicating if the first cell is a simplex. Note the emphasis bestie — it's checking the first cell, not doing a whole sweep of your mesh 👀

Not collective. Just a quick local peek, no cap 🙈

See also: DM, DMPlex, DMPlex.getCellType, DMPlex.getHeightStratum, DMPlexIsSimplex (https://petsc.org/release/manualpages/DMPlex/DMPlexIsSimplex.html)

Source code at petsc4py/PETSc/DMPlex.pyx:1765 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L1765)

Return type: bool (https://docs.python.org/3/builtins/functions.html#bool)

🎀 labelCohesiveComplete(label, bdlabel, bdvalue, flip, split, subdm) 🎀

Add all other mesh pieces to complete the surface. It's the "you brought the snacks, I'll bring the rest" of mesh ops 🍓 — you're finishing off the surface by pulling in whatever other pieces it needs.

Not collective. 💅

Parameters:

  • label (DMLabel) — a DMLabel marking the surface. This is the one getting completed ✨
  • bdlabel (DMLabel) — a DMLabel marking the vertices on the boundary which will not be duplicated. These ones stay single, they're taken 🔒
  • bdvalue (int) — value of DMLabel marking the vertices on the boundary 🏷️
  • flip (bool) — flag to flip the submesh normal and replace points on the other side. Flip it, turn it, reverse it 💫
  • split (bool) — flag to split faces incident on the surface boundary, rather than clamping those faces to the boundary. So: split or clamp, pick your fighter 🥊
  • subdm (DMPlex) — the DMPlex associated with the label 🦋

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

See also: DM, DMPlex, DMPlex.labelComplete, DMPlexLabelCohesiveComplete (https://petsc.org/release/manualpages/DMPlex/DMPlexLabelCohesiveComplete.html)

Source code at petsc4py/PETSc/DMPlex.pyx:1529 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L1529)

🌸 labelComplete(label) 🌸

Add the transitive closure to the surface. Translation: it grabs everything that's reachable from the surface points and pulls it all in. It's giving "and everyone they know" energy 😭

Not collective. 🫶

Parameters:

  • label (DMLabel) — a DMLabel marking the surface points 🌟

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

See also: DM, DMPlex, DMPlex.labelCohesiveComplete, DMPlexLabelComplete (https://petsc.org/release/manualpages/DMPlex/DMPlexLabelComplete.html)

Source code at petsc4py/PETSc/DMPlex.pyx:1512 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L1512)

🧚 labelsLoad(viewer, sfxc) 🧚

Load labels into this DMPlex object. Round trip bestie — stuff gets saved, stuff gets loaded back in, the circle of life 🔁

Collective. 💅

Parameters:

  • viewer (Viewer) — the Viewer for the saved labels 📁
  • sfxc (SF) — the SF returned by topologyLoad 🦋

labelsView(viewer)

Okay so this one saves your DMPlex labels into a file 💾 — like, all of them, off to disk. It's Collective, so everybody in the group chat (er, communicator) is doing it together 🫶.

  • viewer (Viewer) — the Viewer that's doing the saving 💅

Return type: None — it just does the thing, no lil gift back 🙈

See also: DM, DMPlex, DM.load, DMPlex.topologyLoad, DMPlex.coordinatesLoad, DM.view, SF, Viewer, DMPlexLabelsLoad

Source code at petsc4py/PETSc/DMPlex.pyx:3477

labelsView... no wait, labelsView again? no bestie — it's labelsView but the other twin:

labelsView(viewer) — okay fr, save DMPlex labels into a file 💾

Collective.

  • viewer (Viewer) — the Viewer for saving 🎀

Return type: None

See also: DM, DMPlex, DM.view, DMPlex.topologyView, DMPlex.coordinatesView, DMPlex.labelsLoad, Viewer, DMPlexLabelsView

Source code at petsc4py/PETSc/DMPlex.pyx:3342

localVectorLoad(viewer, sectiondm, sf, vec)

Loads on-disk vector data straight into a local vector ✨. Collective, obviously, bc teamwork makes the dream work 💖

Parameters

  • viewer (Viewer) — the Viewer that represents the on-disk vector data 📂
  • sectiondm (DM) — the DM that contains the local section on which vec is defined 🌸
  • sf (SF) — the SF that migrates the on-disk vector data into vec 🦋
  • vec (Vec) — the local vector to set values of, like it's getting its glow-up 💅

Return type: None

See also: DM, DMPlex, DMPlex.topologyLoad, DMPlex.sectionLoad, DMPlex.globalVectorLoad, DMPlex.globalVectorView, DMPlex.localVectorView, SF, Viewer, DMPlexLocalVectorLoad

Source code at petsc4py/PETSc/DMPlex.pyx:3559

localVectorView(viewer, sectiondm, vec)

Save a local vector 🫶 Collective — the whole squad is in on it 💜

Parameters

  • viewer (Viewer) — the Viewer to save data with 🎀
  • sectiondm (DM) — the DM that contains the local section on which vec is defined; may be the same as this DMPlex object 👯 (twinning, honestly)
  • vec (Vec) — the local vector to be saved 📥

Return type: None

See also: DM, DMPlex, DMPlex.topologyView, DMPlex.sectionView, DMPlex.globalVectorView, DMPlex.globalVectorLoad, DMPlex.localVectorLoad, DMPlexLocalVectorView

Source code at petsc4py/PETSc/DMPlex.pyx:3405

markBoundaryFaces(label, value=None)

Marks, like, every single face that lives on the boundary 🦋. Not collective — this one's a solo main character moment ✨

Parameters

  • value (int | None) — the marker value, OR DETERMINE, OR None if you want it to use some value in the closure (and it falls back to 1 if none are found — cute lil default, no cap) 🎀
  • label (str) — the label name, as a string 💅

Return type: DMLabel 👑

See also: DM, DMPlex, DMLabel.create, DM.createLabel, DMPlexMarkBoundaryFaces

Source code at petsc4py/PETSc/DMPlex.pyx:1485

metricAverage2(metric1, metric2, metricAvg)

Computes and returns the unweighted average of two metrics 🌈 — two metrics walk in, one averaged metric walks out 😭 Collective.

Parameters

  • metric1 (Vec) — the first metric to be averaged 1️⃣
  • metric2 (Vec) — the second metric to be averaged 2️⃣
  • metricAvg (Vec) — the output averaged metric, the glow-up result 💖

Return type: Vec

See also: DMPlex.metricAverage3, DMPlexMetricAverage2

Source code at petsc4py/PETSc/DMPlex.pyx:3192

metricAverage3(metric1, metric2, metric3, metricAvg)

Same vibe, but make it three 🎀 — computes and returns the unweighted average of three metrics. Collective, bestie 💅

Parameters

  • metric1 (Vec) — the first metric to be averaged 1️⃣
  • metric2 (Vec) — the second metric to be averaged 2️⃣
  • metric3 (Vec) — the third metric to be averaged 3️⃣
  • metricAvg (Vec) — the output averaged metric ✨

Return type: Vec

See also: DMPlex.metricAverage2, DMPlexMetricAverage3

Source code at petsc4py/PETSc/DMPlex.pyx:3214

metricCreate(field=0)

Creates a Riemannian metric field 📐✨ Collective — it's giving geometry, it's giving gradient, iconic honestly.

Parameters

  • field (int | None) — the field number to use 🔢 (defaults to 0 if you can't decide)

Return type: Vec

See also: DMPlex.metricCreateUniform, DMPlex.metricCreateIsotropic, Working with PETSc options, DMPlexMetricCreate

Source code at petsc4py/PETSc/DMPlex.pyx:3023

metricCreateIsotropic(indicator, field=0)

Constructs an isotropic metric out of an error indicator 🦋💙 Collective.

Parameters

  • indicator (Vec) — the error indicator 🚨
  • field (int | None) — the field number to use 🔢

Return type: Vec

See also: DMPlex.metricCreate, DMPlex.metricCreateUniform, DMPlexMetricCreateIsotropic

Source code at petsc4py/PETSc/DMPlex.pyx:3068

metricCreateUniform(alpha, field=0)

Constructs a uniform isotropic metric 🌱✨ Collective, periodt.

Parameters

  • alpha (float) — scaling parameter for the diagonal 📏
  • field (int | None) — which field number to use, bestie 💅

Return type: Vec

See also: DMPlex.metricCreate, DMPlex.metricCreateIsotropic, DMPlexMetricCreateUniform (https://petsc.org/release/manualpages/DMPlex/DMPlexMetricCreateUniform.html)

Source code at petsc4py/PETSc/DMPlex.pyx:3044

metricDeterminantCreate(field=0) 🎀

Makes the determinant field for a Riemannian metric. It's collective, so the whole squad is in on it 🫶

Parameters

  • field (int | None) — the field number to use.

Returns

  • determinant (Vec) — the determinant field 💖
  • dmDet (DM) — the corresponding DM

Return type: tuple[Vec, DM]

See also: DMPlex.metricCreateUniform, DMPlex.metricCreateIsotropic, DMPlex.metricCreate, DMPlexMetricDeterminantCreate (https://petsc.org/release/manualpages/DMPlex/DMPlexMetricDeterminantCreate.html)

Source code at petsc4py/PETSc/DMPlex.pyx:3091

metricEnforceSPD(metric, ometric, determinant, restrictSizes=False, restrictAnisotropy=False) ✨

Enforces symmetric positive-definiteness on a metric. That's the vibe check for your metric honestly — if it's not SPD, it's not slaying. Also: it's collective.

Parameters

  • metric (Vec) — the metric itself.
  • ometric (Vec) — the output metric.
  • determinant (Vec) — the output determinant.
  • restrictSizes (bool | None) — flag saying whether min/max magnitudes should be enforced.
  • restrictAnisotropy (bool | None) — flag saying whether maximum anisotropy should be enforced.

Returns

  • ometric (Vec) — the output metric.
  • determinant (Vec) — the output determinant.

Return type: tuple[Vec, Vec]

See also: DMPlex.metricNormalize, DMPlex.metricIntersection2, DMPlex.metricIntersection3, Working with PETSc options, DMPlexMetricEnforceSPD (https://petsc.org/release/manualpages/DMPlex/DMPlexMetricEnforceSPD.html)

Source code at petsc4py/PETSc/DMPlex.pyx:3120

metricGetGradationFactor() 🌸

Hands you back the metric gradation factor. Not collective — this one's a solo mission, no group chat needed.

See also: DMPlex.metricSetGradationFactor, DMPlex.metricGetHausdorffNumber, DMPlexMetricGetGradationFactor (https://petsc.org/release/manualpages/DMPlex/DMPlexMetricGetGradationFactor.html)

Source code at petsc4py/PETSc/DMPlex.pyx:2974

Return type: float

metricGetHausdorffNumber() 🦋

Returns the metric Hausdorff number. Not collective. She works alone 💜

See also: DMPlex.metricGetGradationFactor, DMPlex.metricSetHausdorffNumber, DMPlexMetricGetHausdorffNumber (https://petsc.org/release/manualpages/DMPlex/DMPlexMetricGetHausdorffNumber.html)

Source code at petsc4py/PETSc/DMPlex.pyx:3008

Return type: float

metricGetMaximumAnisotropy() 🔥

Returns the maximum tolerated metric anisotropy. Not collective, okay?

See also: DMPlex.metricSetMaximumAnisotropy, DMPlex.metricGetMaximumMagnitude, DMPlexMetricGetMaximumAnisotropy (https://petsc.org/release/manualpages/DMPlex/DMPlexMetricGetMaximumAnisotropy.html)

Source code at petsc4py/PETSc/DMPlex.pyx:2872

Return type: float

metricGetMaximumMagnitude() ⭐

Returns the maximum tolerated metric magnitude. Not collective.

See also: DMPlex.metricSetMaximumMagnitude, DMPlex.metricGetMinimumMagnitude, DMPlexMetricGetMaximumMagnitude (https://petsc.org/release/manualpages/DMPlex/DMPlexMetricGetMaximumMagnitude.html)

Source code at petsc4py/PETSc/DMPlex.pyx:2838

Return type: float

metricGetMinimumMagnitude() 🍓

Returns the minimum tolerated metric magnitude. Not collective.

See also: DMPlex.metricSetMinimumMagnitude, DMPlex.metricGetMaximumMagnitude, DMPlexMetricGetMinimumMagnitude (https://petsc.org/release/manualpages/DMPlex/DMPlexMetricGetMinimumMagnitude.html)

Source code at petsc4py/PETSc/DMPlex.pyx:2804

Return type: float

metricGetNormalizationOrder() 💖

Returns the order p for L-p normalization. yes bestie, there's an L-p in this house and it has an order. Not collective.

See also: DMPlex.metricSetNormalizationOrder, DMPlex.metricGetTargetComplexity, DMPlexMetricGetNormalizationOrder (https://petsc.org/release/manualpages/DMPlex/DMPlexMetricGetNormalizationOrder.html)

Source code at petsc4py/PETSc/DMPlex.pyx:2940

Return type: float

metricGetNumIterations() 🌈

Returns how many parallel adaptation iterations we're doing. Not collective.

See also: DMPlex.metricSetNumIterations, DMPlex.metricGetVerbosity, DMPlexMetricGetNumIterations (https://petsc.org/release/manualpages/DMPlex/DMPlexMetricGetNumIterations.html)

Source code at petsc4py/PETSc/DMPlex.pyx:2770

Return type: int

metricGetTargetComplexity() 🧚

Returns the target metric complexity. Not collective.

See also: DMPlex.metricSetTargetComplexity, DMPlex.metricGetNormalizationOrder, DMPlexMetricGetTargetComplexity (https://petsc.org/release/manualpages/DMPlex/DMPlexMetricGetTargetComplexity.html)

Source code at petsc4py/PETSc/DMPlex.pyx:2906

Return type: float

metricGetVerbosity() 🌟

Returns the verbosity of the mesh adaptation package. Not collective — you're just asking, not summoning the whole crew.

Returns

  • verbosity — the verbosity, where -1 is silent 🤫 and 10 is maximum 📢

…and bb the type it hands back is literally just int.

See also: DMPlex.metricSetVerbosity, DMPlex.metricGetNumIterations, DMPlexMetricGetVerbosity.

Source code at petsc4py/PETSc/DMPlex.pyx:2731.

✨ metricIntersection2(metric1, metric2, metricInt)

Okay so this one computes the intersection of two metrics and hands it right back to you. Serving overlap realness 💅

Collective. yes bestie, everybody's in on this one.

Parameters:

  • metric1 (Vec) — the first metric you're intersecting. contender numero uno.
  • metric2 (Vec) — the second metric getting intersected. the other half of the situationship.
  • metricInt (Vec) — the output intersected metric. this is where the glow-up lands.

Return type: Vec

See also: DMPlex.metricIntersection3, DMPlexMetricIntersection2.

Source code at petsc4py/PETSc/DMPlex.pyx:3238.

✨ metricIntersection3(metric1, metric2, metric3, metricInt)

The three-way version. Compute the intersection of three metrics — it's giving polycule of metrics, no cap 🌈

Collective.

Parameters:

  • metric1 (Vec) — the first metric to be intersected.
  • metric2 (Vec) — the second metric to be intersected.
  • metric3 (Vec) — the third metric to be intersected. three's company fr fr.
  • metricInt (Vec) — the output intersected metric.

Return type: Vec

See also: DMPlex.metricIntersection2, DMPlexMetricIntersection3.

Source code at petsc4py/PETSc/DMPlex.pyx:3260.

✨ metricIsIsotropic()

Returns the flag telling you whether the metric is isotropic or not. Just a lil vibe check on your metric ✨

Not collective. do it solo, bestie.

See also: DMPlex.metricSetIsotropic, DMPlex.metricIsUniform, DMPlex.metricRestrictAnisotropyFirst, DMPlexMetricIsIsotropic.

Source code at petsc4py/PETSc/DMPlex.pyx:2519.

Return type: bool

✨ metricIsUniform()

Same energy, different question: returns the flag saying whether the metric is uniform or not. 🎀

Not collective.

See also: DMPlex.metricSetUniform, DMPlex.metricRestrictAnisotropyFirst, DMPlexMetricIsUniform.

Source code at petsc4py/PETSc/DMPlex.pyx:2485.

Return type: bool

✨ metricNoInsertion()

Returns the flag telling you whether node insertion AND deletion are both turned off. like, the mesh is on do-not-disturb 💀

Not collective.

See also: DMPlex.metricSetNoInsertion, DMPlex.metricNoSwapping, DMPlex.metricNoMovement, DMPlex.metricNoSurf, DMPlexMetricNoInsertion.

Source code at petsc4py/PETSc/DMPlex.pyx:2588.

Return type: bool

✨ metricNoMovement()

Returns the flag for whether node movement is turned off. nobody's moving, we're staying put, main character is seated 🪑

Not collective.

See also: DMPlex.metricSetNoMovement, DMPlex.metricNoInsertion, DMPlex.metricNoSwapping, DMPlex.metricNoSurf, DMPlexMetricNoMovement.

Source code at petsc4py/PETSc/DMPlex.pyx:2660.

Return type: bool

✨ metricNoSurf()

Returns the flag for whether surface modification is turned off. the surface said "not today" 🌊

Not collective.

See also: DMPlex.metricSetNoSurf, DMPlex.metricNoMovement, DMPlex.metricNoInsertion, DMPlex.metricNoSwapping, DMPlexMetricNoSurf.

Source code at petsc4py/PETSc/DMPlex.pyx:2696.

Return type: bool

✨ metricNoSurf... jk jk, next one is metricNoSwapping()

Returns the flag telling you whether facet swapping is turned off. no trades, the roster is final 🙅‍♀️

Not collective.

See also: DMPlex.metricSetNoSwapping, DMPlex.metricNoInsertion, DMPlex.metricNoMovement, DMPlex.metricNoSurf, DMPlexMetricNoSwapping.

Source code at petsc4py/PETSc/DMPlex.pyx:2624.

Return type: bool

✨ metricNormalize(metric, ometric, determinant, restrictSizes=True, restrictAnisotropy=True)

Apply L-p normalization to a metric. this is the metric's glow-up arc, obsessed 😌

Collective.

Parameters:

  • metric (Vec) — the metric. the raw material, the before pic.
  • ometric (Vec) — the output metric. the after pic.
  • determinant (Vec) — the output determinant. yes it comes out here too, keep up bestie.
  • restrictSizes (bool | None) — flag saying whether maximum/minimum magnitudes should be enforced. default is True. it's a vibe limit.
  • restrictAnisotropy (bool | None) — flag saying whether maximum anisotropy should be enforced. default is True. also a vibe limit.

Returns:

  • ometric (Vec) — the output normalized metric.
  • determinant (Vec) — the output determinant.

Return type: tuple[Vec, Vec] — yep, a whole tuple, you get two things back 🫶

See also: DMPlex.metricEnforceSPD, DMPlex.metricIntersection2, DMPlex.metricIntersection3, Working with PETSc options, DMPlexMetricNormalize.

Source code at petsc4py/PETSc/DMPlex.pyx:3156.

✨ metricRestrictAnisotropyFirst()

Returns true if anisotropy gets restricted before normalization. order matters, and this is the tea ☕

Not collective.

See also: DMPlex.metricIsIsotropic, DMPlex.metricSetRestrictAnisotropyFirst, DMPlexMetricRestrictAnisotropyFirst.

Source code at petsc4py/PETSc/DMPlex.pyx:2553.

Return type: bool

✨ metricSetFromOptions()

Configure the object from the options database. aka let the command line run your life 🔥

Collective.

See also: Working with PETSc options.

Source code at petsc4py/PETSc/DMPlex.pyx:2453 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L2453

  • Return type: None

…and that's the last one wrapped up 💫 okay bestie we back in the metric-setters, buckle up 🎀

🌸 metricSetGradationFactor(beta)

Sets the metric gradation factor. That's the knob for how much the metric is allowed to graduate, iykyk.

Logically collective (so everybody in the communicator has to show up for this one, no stragglers 🫶).

  • Parameters:
    • beta (float) — The metric gradation factor.
  • Return type: None
See also: DMPlex.metricGetGradationFactor, DMPlex.metricSetHausdorffNumber, DMPlexMetricSetGradationFactor — https://petsc.org/release/manualpages/DMPlex/DMPlexMetricSetGradationFactor.html

📍 Source code at petsc4py/PETSc/DMPlex.pyx:2955 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L2955

🦋 metricSetHausdorffNumber(hausd)

Sets the metric Hausdorff number. yes it's a real thing and yes it's giving very serious geometry energy ✨

Logically collective.

  • Parameters:
    • hausd (float) — The metric Hausdorff number.
  • Return type: None
See also: DMPlex.metricSetGradationFactor, DMPlex.metricGetHausdorffNumber, DMPlexMetricSetHausdorffNumber — https://petsc.org/release/manualpages/DMPlex/DMPlexMetricSetHausdorffNumber.html

📍 Source code at petsc4py/PETSc/DMPlex.pyx:2989 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L2989

💖 metricSetIsotropic(isotropic)

Records whether the metric is isotropic or not — like, is it doing the same thing in every direction or is it anisotropic and extra about it 💅 (this call just records the fact, it doesn't decide for you).

Logically collective.

  • Parameters:
    • isotropic (bool) — Flag indicating whether the metric is isotropic or not.
  • Return type: None
See also: DMPlex.metricIsIsotropic, DMPlex.metricSetUniform, DMPlex.metricSetRestrictAnisotropyFirst, DMPlexMetricSetIsotropic — https://petsc.org/release/manualpages/DMPlex/DMPlexMetricSetIsotropic.html

📍 Source code at petsc4py/PETSc/DMPlex.pyx:2500 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L2500

👑 metricSetMaximumAnisotropy(a_max)

Sets the maximum tolerated metric anisotropy. the cap on how dramatic your metric is allowed to get, periodt 🔥

Logically collective.

  • Parameters:
    • a_max (float) — The maximum tolerated metric anisotropy.
  • Return type: None
See also: DMPlex.metricGetMaximumAnisotropy, DMPlex.metricSetMaximumMagnitude, DMPlexMetricSetMaximumAnisotropy — https://petsc.org/release/manualpages/DMPlex/DMPlexMetricSetMaximumAnisotropy.html

📍 Source code at petsc4py/PETSc/DMPlex.pyx:2853 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L2853

🍓 metricSetMaximumMagnitude(h_max)

Sets the maximum tolerated metric magnitude. the biggest your metric is allowed to be, no cap beyond this cap 😭

Logically collective.

  • Parameters:
    • h_max (float) — The maximum tolerated metric magnitude.
  • Return type: None
See also: DMPlex.metricGetMaximumMagnitude, DMPlex.metricSetMinimumMagnitude, DMPlexMetricSetMaximumMagnitude — https://petsc.org/release/manualpages/DMPlex/DMPlexMetricSetMaximumMagnitude.html

📍 Source code at petsc4py/PETSc/DMPlex.pyx:2819 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L2819

🧚 metricSetMinimumMagnitude(h_min)

Sets the minimum tolerated metric magnitude. the smallest your metric is allowed to be — the little guy protection clause 🫶

Logically collective.

  • Parameters:
    • h_min (float) — The minimum tolerated metric magnitude.
  • Return type: None
See also: DMPlex.metricGetMinimumMagnitude, DMPlex.metricSetMaximumMagnitude, DMPlexMetricSetMinimumMagnitude — https://petsc.org/release/manualpages/DMPlex/DMPlexMetricSetMinimumMagnitude.html

📍 Source code at petsc4py/PETSc/DMPlex.pyx:2785 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L2785

💅 metricSetNoInsertion(noInsert)

Sets the flag for whether node insertion should be turned off. flip it on and the mesh stops adding new nodes, simple as that ✨

Logically collective.

  • Parameters:
    • noInsert (bool) — Flag indicating whether node insertion and deletion should be turned off.
  • Return type: None
See also: DMPlex.metricNoInsertion, DMPlex.metricSetNoSwapping, DMPlex.metricSetNoMovement, DMPlex.metricSetNoSurf, DMPlexMetricSetNoInsertion — https://petsc.org/release/manualpages/DMPlex/DMPlexMetricSetNoInsertion.html

📍 Source code at petsc4py/PETSc/DMPlex.pyx:2568 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L2568

🌈 metricSetNoMovement(noMove)

Sets the flag for whether node movement should be turned off. nodes stay exactly where they are, main character energy but frozen 🧊

Logically collective.

  • Parameters:
    • noMove (bool) — Flag indicating whether node movement should be turned off.
  • Return type: None
See also: DMPlex.metricNoMovement, DMPlex.metricSetNoInsertion, DMPlex.metricSetNoSwapping, DMPlex.metricSetNoSurf, DMPlexMetricSetNoMovement — https://petsc.org/release/manualpages/DMPlex/DMPlexMetricSetNoMovement.html

📍 Source code at petsc4py/PETSc/DMPlex.pyx:2640 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L2640

🎀 metricSetNoSurf(noSurf)

Sets the flag for whether surface modification should be turned off. no touching the boundary, bestie 🙈

Logically collective.

  • Parameters:
    • noSurf (bool) — Flag indicating whether surface modification should be turned off.
  • Return type: None
See also: DMPlex.metricNoSurf, DMPlex.metricSetNoMovement, DMPlex.metricSetNoInsertion, DMPlex.metricSetNoSwapping, DMPlexMetricSetNoSurf — https://petsc.org/release/manualpages/DMPlex/DMPlexMetricSetNoSurf.html

📍 Source code at petsc4py/PETSc/DMPlex.pyx:2676 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L2676

💀 metricSetNoSwapping(noSwap)

Sets the flag for whether facet swapping should be turned off. the flip-flop era ends here, fr fr ✋

Logically collective.

  • Parameters:
    • noSwap (bool) — Flag indicating whether facet swapping should be turned off.
  • Return type: None
See also: DMPlex.metricNoSwapping, DMPlex.metricSetNoInsertion, DMPlex.metricSetNoMovement, DMPlex.metricSetNoSurf, DMPlexMetricSetNoSwapping — https://petsc.org/release/manualpages/DMPlex/DMPlexMetricSetNoSwapping.html

📍 Source code at petsc4py/PETSc/DMPlex.pyx:2604 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L2604

⭐ metricSetNormalizationOrder(p)

Sets the order p for L-p normalization — you know, the normalizing-with-an-exponent situation.

Logically collective.

  • Parameters:
    • p (float) — The normalization order.

Return type: None — like, it gives you nothing back and that's the whole point, it just does the thing 💅

See also: DMPlex.metricGetNormalizationOrder, DMPlex.metricSetTargetComplexity, DMPlexMetricSetNormalizationOrder (https://petsc.org/release/manualpages/DMPlex/DMPlexMetricSetNormalizationOrder.html)

Source code: petsc4py/PETSc/DMPlex.pyx:2921 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L2921)

metricSetNumIterations(numIter)

okay so this one sets how many rounds of parallel adaptation we're doing, bestie. Not one round. Not infinite rounds. Whatever number you tell it. 🌀

Logically collective. (so like, everybody on the crew needs to be on the same page here)

Parameters:

  • numIter (int) — The number of parallel adaptation iterations. That's literally it, that's the number ✨

Return type: None

See also: DMPlex.metricSetVerbosity, DMPlex.metricGetNumIterations, DMPlexMetricSetNumIterations (https://petsc.org/release/manualpages/DMPlex/DMPlexMetricSetNumIterations.html)

Source code: petsc4py/PETSc/DMPlex.pyx:2751 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L2751)

metricSetRestrictAnisotropyFirst(restrictAnisotropyFirst)

this one records whether anisotropy gets restricted before normalization or after it. Order matters, no cap. It's giving "sequencing is everything" 🎀

Logically collective.

Parameters:

  • restrictAnisotropyFirst (bool) — Flag indicating if anisotropy is restricted before normalization or after. Yes, the flag name is the question, lowkey iconic 🦋

Return type: None

See also: DMPlex.metricSetIsotropic, DMPlex.metricRestrictAnisotropyFirst, DMPlexMetricSetRestrictAnisotropyFirst (https://petsc.org/release/manualpages/DMPlex/DMPlexMetricSetRestrictAnisotropyFirst.html)

Source code: petsc4py/PETSc/DMPlex.pyx:2534 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L2534)

metricSetTargetComplexity(targetComplexity)

setting the target metric complexity. that's the goal, that's the dream, that's the main character of your adaptation run 💖

Logically collective.

Parameters:

  • targetComplexity (float) — The target metric complexity. a float bestie, so you can be precise about it ⭐

Return type: None

See also: DMPlex.metricGetTargetComplexity, DMPlex.metricSetNormalizationOrder, DMPlexMetricSetTargetComplexity (https://petsc.org/release/manualpages/DMPlex/DMPlexMetricSetTargetComplexity.html)

Source code: petsc4py/PETSc/DMPlex.pyx:2887 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L2887)

metricSetUniform(uniform)

is the metric uniform or is it not? this method records the answer. that's it. that's the job. 🫶

Logically collective.

Parameters:

  • uniform (bool) — Flag indicating whether the metric is uniform or not. yes it's a yes/no and yes it's that simple 🌸

Return type: None

See also: DMPlex.metricIsUniform, DMPlex.metricSetIsotropic, DMPlex.metricSetRestrictAnisotropyFirst, DMPlexMetricSetUniform (https://petsc.org/release/manualpages/DMPlex/DMPlexMetricSetUniform.html)

Source code: petsc4py/PETSc/DMPlex.pyx:2466 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L2466)

metricSetVerbosity(verbosity)

how loud do you want the mesh adaptation package to be? bestie, this is the volume knob 📢

Logically collective.

Parameters:

  • verbosity (int) — The verbosity, where -1 is silent and 10 is maximum. so like, -1 = ghost mode 👻 and 10 = screaming from the rooftops 🔥

Return type: None

See also: DMPlex.metricGetVerbosity, DMPlex.metricSetNumIterations, DMPlexMetricSetVerbosity (https://petsc.org/release/manualpages/DMPlex/DMPlexMetricSetVerbosity.html)

Source code: petsc4py/PETSc/DMPlex.pyx:2712 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L2712)

migrateGlobalToNaturalSF(dmOld, sfNaturalOld, sfMigration)

bestie this one creates the SF you need to map a Global Vec over to the Natural Vec inside the new DM. it's a whole glow-up pipeline for your vectors ✨🌈

Collective.

Parameters:

  • dmOld (DM)
  • sfNaturalOld (SF)
  • sfMigration (SF)

Return type: SF — yeah, it actually hands you something back, slay 🎀

See also: DMPlexMigrateGlobalToNaturalSF (https://petsc.org/release/manualpages/DMPlex/DMPlexMigrateGlobalToNaturalSF.html)

Source code: petsc4py/PETSc/DMPlex.pyx:3687 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L3687)

naturalToGlobalBegin(nv, gv)

rearranging a Vec from natural order over to Global order — and this is the Begin half of the operation, so it's the "set it up" moment 🧚

Collective.

Parameters:

  • nv (Vec)
  • gv (Vec)

Return type: None

See also: DMPlexNaturalToGlobalBegin (https://petsc.org/release/manualpages/DMPlex/DMPlexNaturalToGlobalBegin.html)

Source code: petsc4py/PETSc/DMPlex.pyx:3598 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L3598)

naturalToGlobalEnd(nv, gv)

same energy as the one above — rearrange a Vec from natural order to Global order — except this is the End half, so this is where it actually finishes up 💅

Collective.

Parameters:

  • nv (Vec)
  • gv (Vec)

Return type: None

See also: DMPlexNaturalToGlobalEnd (https://petsc.org/release/manualpages/DMPlex/DMPlexNaturalToGlobalEnd.html)

Source code: petsc4py/PETSc/DMPlex.pyx:3610 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L3610)

orient()

giving your input mesh a consistent orientation. because chaos is not the vibe, bestie — order is the vibe 👑

Collective.

Return type: None

See also: DM, DMPlex, DM.create, DMPlexOrient (https://petsc.org/release/manualpages/DMPlex/DMPlexOrient.html)

Source code: petsc4py/PETSc/DMPlex.pyx:989 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L989)

orientLabel(label)

same "give it a consistent orientation" fantasy, but this time it's for the hypersurface that's marked by a label. very targeted. very precise. very demure 🎀

Collective.

Parameters:

  • label (DMLabel) — The label marking the hypersurface. 🏷️

Return type: None

See also: DM, DMPlex, DM.create, DMPlexOrientLabel (https://petsc.org/release/manualpages/DMPlex/DMPlexOrientLabel.html)

Source code: petsc4py/PETSc/DMPlex.pyx:1001 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMPlex.pyx#L1001)

orientPoint(p, o)

acting with the given orientation on this specific mesh point. just one point. one point, one orientation, no cap 💫

Not collective. (so no, you don't need the whole squad for this one — it's a solo moment, main character energy fr fr)

Parameters:

  • p (int) — The mesh point. 📍
  • o (int) — The orientation. 🔄

Return type: None

See also: DM, DMPlex, DM.create, DMPlexOrientPoint (https://petsc.org/release/manualpages/DMPlex/DMPlexOrientPoint.html)

<i>Source code at petsc4py/PETSc/DMPlex.pyx:968</i>

permute(perm) 🔄

Okay so bestie, this one takes your whole entire mesh and reorders it according to the permutation you hand it. It's collective — every single process is in the group chat for this one, no lurkers. 👀

Parameters

  • perm (IS) — the point permutation, and the glow-up rule is literally perm[old point number] = new point number, i.e. old point number goes in, new point number comes out. 💅

Returns

  • pdm — the permuted DMPlex. Fresh. Reordered. Iconic. ✨

Return type

DMPlex

See also

DMPlex, Mat.permute, DMPlexPermute

Source code at petsc4py/PETSc/DMPlex.pyx:2291

rebalanceSharedPoints(entityDepth=0, useInitialGuess=True, parallel=True) ⚖️

Not me redistributing the shared points just so everyone gets a fair slice — this one redistributes shared points in order to achieve better balancing. Load-balancing is self-care, fr fr. 🧘

Collective — the whole squad does it together.

Parameters

  • entityDepth (int | None) — depth of the entity to balance, e.g. 0 -> balance vertices. Yes, depth 0 means we're out here balancing vertices, slay.
  • useInitialGuess (bool | None) — whether to use the current distribution as the initial guess. Recycling, we love to see it. ♻️
  • parallel (bool | None) — whether to use ParMETIS and do the partition in parallel, or gather the graph onto a single process (the lone-wolf option 🐺).

Returns

  • success — whether the graph partitioning was successful or not. And no, an unsuccessful result isn't a fail, bestie: unsuccessful simply means no change to the partitioning. Zero drama. 😌

Return type

bool

See also

DM, DMPlex, DMPlex.distribute, Working with PETSc options, DMPlexRebalanceSharedPoints

Source code at petsc4py/PETSc/DMPlex.pyx:1660

reorderGetDefault() 🎀

Returns a flag telling you whether the DMPlex should be reordered by default. That's it, that's the whole vibe check.

Not collective — you can just ask, no group huddle required.

See also

None, DMPlexReorderGetDefault

Source code at petsc4py/PETSc/DMPlex.pyx:2315

Return type

ReorderDefaultFlag

reorderSetDefault(flag) 🔧

Sets the flag saying whether the DM should be reordered by default. Flipping the switch, main character energy. 👑

Logically collective.

Parameters

  • reorder — flag for reordering.
  • flag (ReorderDefaultFlag)

Return type

None

See also

DMPlex.reorderGetDefault, DMPlexReorderSetDefault

Source code at petsc4py/PETSc/DMPlex.pyx:2329

sectionLoad(viewer, sectiondm, sfxc) 📥

Loads a section into a DM. Glow-up delivered. 🦋

Collective.

Parameters

  • viewer (Viewer) — the Viewer that represents the on-disk section (called sectionA).
  • sectiondm (DM) — the DM into which the on-disk section (sectionA) is migrated. Come through, data. 🚚
  • sfxc (SF) — the SF returned by topologyLoad.

Returns

  • gsf (SF) — the SF that migrates any on-disk Vec data associated with sectionA into a global Vec associated with the sectiondm's global section (None if not needed).
  • lsf (SF) — the SF that migrates any on-disk Vec data associated with sectionA into a local Vec associated with the sectiondm's local section (None if not needed).

Return type

tuple[SF, SF]

See also

DM, DMPlex, DM.load, DMPlex.topologyLoad, DMPlex.coordinatesLoad, DMPlex.labelsLoad, DMPlex.globalVectorLoad, DMPlex.localVectorLoad, DMPlex.sectionView, SF, Viewer, DMPlexSectionLoad

Source code at petsc4py/PETSc/DMPlex.pyx:3497

sectionView(viewer, sectiondm) 📤

Saves a section associated with a DMPlex. Same energy as sectionLoad, but make it export. 💾✨

Collective.

Parameters

  • viewer (Viewer) — the Viewer for saving.
  • sectiondm (DM) — the DM that contains the section to be saved.

Return type

None

See also

DM, DMPlex, DM.view, DMPlex.topologyView, DMPlex.coordinatesView, DMPlex.labelsView, DMPlex.globalVectorView, DMPlex.localVectorView, DMPlex.sectionLoad, Viewer, DMPlexSectionView

Source code at petsc4py/PETSc/DMPlex.pyx:3360

setAdjacencyUseAnchors(useAnchors=True) ⚓

Defines adjacency in the mesh using the point-to-point constraints. Anchors are basically the emotional support points of the mesh, and honestly? Relatable. 🫶

Logically collective.

Parameters

  • useAnchors (bool) — flag to use the constraints. If True, then constrained points are omitted from DMPlex.getAdjacency, and their anchor points appear in their place instead. Swap! 💫

Return type

None

See also

DMPlex, DMPlex.getAdjacency, DMPlex.distribute, DMPlexSetAdjacencyUseAnchors

Source code at petsc4py/PETSc/DMPlex.pyx:1564

setCellType(p, ctype) 🔺

Sets the polytope type of a given cell. Giving each cell its own little identity. 🌈

Not collective — solo mission, no group chat needed.

Parameters

  • p (int) — the cell.
  • ctype (PolytopeType) — the polytope type of the cell.

Return type

None

See also: DM, DMPlex, DMPlex.getCellTypeLabel, DMPlex.getDepth, DM.createLabel, DMPlexSetCellType

Source code at petsc4py/PETSc/DMPlex.pyx:758

✨ setChart(pStart, pEnd) ✨

okay so this one sets the interval for all the mesh points, written as [pStart, pEnd) — bestie note the square bracket on the left and the round one on the right, that's a half-open interval, we love a boundary that knows where it stands. 💅

Not collective — no group chat needed, this is a you-and-your-rank thing. 🙈

Parameters

  • pStart (int) — The first mesh point.
  • pEnd (int) — The upper bound for mesh points.

Return type

None

See also: DM, DMPlex, DMPlex.create, DMPlex.getChart, DMPlexSetChart

Source code at petsc4py/PETSc/DMPlex.pyx:516

🦋 setCone(p, cone, orientation=None) 🦋

sets the points sitting on the in-edges for this point in the DAG. it's giving "who's in my cone" energy, and honestly the DAG is the main character here. 👑

Not collective.

Parameters

  • p (int) — The point, which must lie in the chart set with DMPlex.setChart. (so yeah, setChart first, no skipping steps babe 🎀)
  • cone (Sequence[int]) — An array of points which are on the in-edges for point p.
  • orientation (Sequence[int] | None) — An array of orientations, defaults to None.

Return type

None

See also: DM, DMPlex, DMPlex.create, DMPlex.getCone, DMPlex.setChart, DMPlex.setConeSize, DM.setUp, DMPlex.setSupport, DMPlex.setSupportSize, DMPlexSetCone

Source code at petsc4py/PETSc/DMPlex.pyx:612

🌸 setConeOrientation(p, orientation) 🌸

sets the orientations on the in-edges for this point in the DAG. same vibe as setCone but it's the orientation arc, not the point arc. ✨

Not collective.

Parameters

  • p (int) — The point, which must lie in the chart set with DMPlex.setChart.
  • orientation (Sequence[int]) — An array of orientations.

Return type

None

See also: DM, DMPlex, DMPlex.create, DMPlex.getConeOrientation, DMPlex.setCone, DMPlex.setChart, DMPlex.setConeSize, DM.setUp, DMPlexSetConeOrientation

Source code at petsc4py/PETSc/DMPlex.pyx:727

🌈 setConeSize(p, size) 🌈

tells the DAG how many in-edges this point has. like RSVPing for your own cone, and yes you have to do it before setCone fills in the actual guests. 💌

Not collective.

Parameters

  • p (int) — The point, which must lie in the chart set with DMPlex.setChart.
  • size (int) — The cone size for point p.

Return type

None

See also: DM, DMPlex, DMPlex.create, DMPlex.getConeSize, DMPlex.setChart, DMPlexSetConeSize

Source code at petsc4py/PETSc/DMPlex.pyx:561

💫 setMatClosure(sec, gsec, mat, point, values, addv=None) 💫

drops an array of values onto the closure of point. this is the matrix-glow-up moment, bestie. 🔥

Not collective.

Parameters

  • sec (Section) — The section describing the layout in mat, or None to use the default section.
  • gsec (Section) — The section describing the layout in mat, or None to use the default global section.
  • mat (Mat) — The matrix.
  • point (int) — The point in the DMPlex.
  • values (Sequence[Scalar]) — The array of values.
  • mode — The insertion mode.
  • addv (InsertModeSpec | None)

Return type

None

See also: DM, DMPlex, DMPlexMatSetClosure

Source code at petsc4py/PETSc/DMPlex.pyx:1380

💖 setMigrationSF(sf) 💖

sets the SF for migrating from a parent DM into this DM. it's the "moving day" function — you're relocating data from the parent into here and the SF is your little moving truck. 🚚✨

Not collective.

See also: DMPlexSetMigrationSF

Source code at petsc4py/PETSc/DMPlex.pyx:3646

Parameters

  • sf (SF)

Return type

None

🎀 setPartitioner(part) 🎀

sets the mesh partitioner — the thing that decides who gets which piece of the mesh. splitting the workload, sharing is caring, etc etc. 🫶

Logically collective.

Parameters

  • part (Partitioner) — The partitioner.

Return type

None

See also: DM, DMPlex, Partitioner, DMPlex.distribute, DMPlex.getPartitioner, Partitioner.create, DMPlexSetPartitioner

Source code at petsc4py/PETSc/DMPlex.pyx:1625

⭐ setRefinementLimit(refinementLimit) ⭐

sets the maximum cell volume for refinement. so anything chunkier than this number is getting refined, no cap. 🍓

Logically collective.

Parameters

  • refinementLimit (float) — The maximum cell volume in the refined mesh.

Return type

None

See also: DM, DMPlex, DM.refine, DMPlex.getRefinementLimit, DMPlex.getRefinementUniform, DMPlex.setRefinementUniform, DMPlexSetRefinementLimit

Source code at petsc4py/PETSc/DMPlex.pyx:1663

📌 Source code at petsc4py/PETSc/DMPlex.pyx:2227

  • setRefinementUniform(refinementUniform=True) — turns on the flag for uniform refinement ✨ lowkey the switch that says "yeah bestie, refine everything evenly"
    • Collectivity: logically collective — everybody's in on it together, no rogue processes 🫶
    • Parameters:
      • refinementUniform (bool | None) — the flag for uniform refinement.
    • Return type: None
    • See also: DM, DMPlex, DM.refine, DMPlex.getRefinementUniform, DMPlex.getRefinementLimit, DMPlex.setRefinementLimit, DMPlexSetRefinementUniform
    • Source: petsc4py/PETSc/DMPlex.pyx:2186
  • setSupport(p, supp) — sets the points sitting on the out-edges for this point in the DAG 💅
    • Collectivity: not collective — you do you, solo mission, no group chat needed 🙈
    • Parameters:
      • p (int) — the point, which must lie in the chart set with DMPlex.setChart. (fr fr, set your chart first or it's over)
      • supp (Sequence[int]) — an array of points which are on the out-edges for point p.
    • Return type: None
    • See also: DM, DMPlex, DMPlex.setCone, DMPlex.setConeSize, DMPlex.create, DMPlex.getSupport, DMPlex.setChart, DMPlex.setSupportSize, DM.setUp, DMPlexSetSupport
    • Source: petsc4py/PETSc/DMPlex.pyx:892
  • setSupportSize(p, size) — sets how many out-edges this point in the DAG has 🦋 it's giving "count your blessings, but make them edges"
    • Collectivity: not collective — all yours, bestie.
    • Parameters:
      • p (int) — the point, which must lie in the chart set with DMPlex.setChart.
      • size (int) — the support size for point p.
    • Return type: None
    • See also: DM, DMPlex, DMPlex.create, DMPlex.getSupportSize, DMPlex.setChart, DMPlexSetSupportSize
    • Source: petsc4py/PETSc/DMPlex.pyx:841
  • setTetGenOptions(opts) — hands the options over to the Tetgen mesh generator ✨
    • Collectivity: not collective — just you and your mesh generator, main character energy 👑
    • Parameters:
      • opts (str) — the command line options.
    • Return type: None
    • See also: Working with PETSc options, DM, DMPlex, DMPlex.setTriangleOptions, DMPlex.generate, DMPlexTetgenSetOptions
    • Source: petsc4py/PETSc/DMPlex.pyx:1465
  • setTriangleOptions(opts) — same vibe, different generator: hands the options to the Triangle mesh generator 🌸
    • Collectivity: not collective — solo run, no cap.
    • Parameters:
      • opts (str) — the command line options.
    • Return type: None
    • See also: Working with PETSc options, DM, DMPlex, DMPlex.setTetGenOptions, DMPlex.generate, DMPlexTriangleSetOptions
    • Source: petsc4py/PETSc/DMPlex.pyx:1445
  • setVecClosure(sec, vec, point, values, addv=None) — drops an array of values onto the closure of a point 🔥
    • Collectivity: not collective — your vector, your rules.
    • Parameters:
      • sec (Section) — the section describing the layout in vec, or None to use the default section.
      • vec (Vec) — the local vector.
      • point (int) — the point in the DMPlex.
      • values (Sequence[Scalar]) — the array of values.
      • mode — the insertion mode.
      • addv (InsertModeSpec | None)
    • Return type: None
    • See also: DM, DMPlex, DMPlexVecSetClosure
    • Source: petsc4py/PETSc/DMPlex.pyx:1348
  • stratify() — calculates the strata of the DAG 🧚 knowing which layer every point lives in? iconic.
    • Collectivity: collective — we all compute this together, periodt.
    • Return type: None
    • See also: DM, DMPlex, DMPlex.create, DMPlex.symmetrize, DMPlexStratify
    • Source: petsc4py/PETSc/DMPlex.pyx:956
  • symmetrize() — builds the support (out-edge) info from the cone (in-edge) info 🌈 it's giving "flip it and reverse it".
    • Collectivity: not collective — no committee required.
    • Return type: None
    • See also: DM, DMPlex, DMPlex.create, DMPlex.setChart, DMPlex.setConeSize, DMPlex.setCone, DMPlexSymmetrize
    • Source: petsc4py/PETSc/DMPlex.pyx:943
  • topologyLoad(viewer) — loads a topology straight into this DMPlex object 💖 the glow-up from saved file to live mesh.
    • Collectivity: collective — everybody loads together, no stragglers.
    • Parameters:
      • viewer (Viewer) — the Viewer for the saved topology.
    • Returns:
      • sfxc — the SF that pushes points in [0, N) to the associated points in the loaded DMPlex, where N is the global number of points.
    • Return type: SF
    • See also: DM, DMPlex, DM.load, DMPlex.coordinatesLoad, DMPlex.labelsLoad, DM.view, SF, Viewer, DMPlexTopologyLoad
    • Source: petsc4py/PETSc/DMPlex.pyx:3431
  • topologyView(viewer) — saves a DMPlex topology out into a file 📁✨ the reverse glow-up, tucking your mesh away for safekeeping.
    • Collectivity: collective — everyone writes out their piece, together, as a team.
    • Parameters:
      • viewer (Viewer) — the Viewer for saving.
    • Return type: None

See also: DM, DMPlex, DM.view, DMPlex.coordinatesView, DMPlex.labelsView, DMPlex.topologyLoad, Viewer, DMPlexTopologyView

Source code at petsc4py/PETSc/DMPlex.pyx:3306

uninterpolate()

okay so this one takes your mesh and strips it ALL the way back — down to just cells and vertices, nothing in between. no edges, no faces, just the main characters 💅

Collective — everybody in the communicator has to show up for this one, no lurking 🫶

See also: DMPlex, DMPlex.interpolate, DMPlex.createFromCellList, DMPlexUninterpolate

Source code at petsc4py/PETSc/DMPlex.pyx:1876

Return type: None

vecGetClosure(sec, vec, p)

returns you a whole array of values sitting on the closure of p. like, the full glow-up of that point and everything it touches ✨

Not collective — this one's a solo mission, just you and your local data.

Parameters

  • sec (Section) — the section that describes the layout inside vec. it's literally the map, bestie 🗺️
  • vec (Vec) — the local vector. your actual data lives here.
  • p (int) — the point in the DMPlex. the one we're zooming in on 🔍

Return type: ArrayScalar

See also: DM, DMPlex, DMPlexVecRestoreClosure

okay reminder bestie: you asked for that closure array, so be a good citizen and hand it back when you're done 🔥

Source code at petsc4py/PETSc/DMPlex.pyx:1290

__init__()

that's it. that's the whole entry. no description given, so I'm not out here making one up 💀

classmethod __new__(*args, **kwargs)

also no description. same energy. take the args, take the kwargs, move on 🙈

class petsc4py.PETSc.DMPlexTransform

Bases: Object

Mesh transformations. it's giving glow-up machine for your mesh 🦋 — you feed it a DM, it hands you back a different (better) one.

Methods Summary

  • apply(dm) — Apply a mesh transformation.
  • create([comm]) — Create a mesh transformation.
  • destroy() — Destroy a mesh transformation.
  • getType() — Return the transformation type name.
  • setDM(dm) — Set the DM for the transformation.
  • setFromOptions() — Configure the transformation from the options database.
  • setType(tr_type) — Set the transformation type.
  • setUp() — Setup a mesh transformation.
  • view([viewer]) — View the mesh transformation.

Methods Documentation

apply(dm)

apply a mesh transformation. like actually do the thing — the transformation you built and set up finally gets to shine 👑

Collective.

Source code at petsc4py/PETSc/DMPlex.pyx:3725

Parameters

  • dm (DM)

Return type: DM

create(comm=None)

create a mesh transformation. brand new transformation, freshly unboxed 🎀

Collective.

See also: DMPlexTransformCreate

Source code at petsc4py/PETSc/DMPlex.pyx:3736

Parameters

  • comm (Comm | None)

Return type: Self

destroy()

destroy a mesh transformation. we love a clean exit, no lingering objects left in the group chat 🧹

Collective.

See also: DMPlexTransformDestroy

Source code at petsc4py/PETSc/DMPlex.pyx:3753

Return type: Self

getType()

returns the transformation type name. just the name, that's the whole ask 🏷️

Not collective — solo mission again.

See also: DMPlexTransformGetType

Source code at petsc4py/PETSc/DMPlex.pyx:3766

Return type: str

setDM(dm)

sets the DM that this transformation is going to work on. giving your transformation its main character 🫶

Logically collective.

Source code at petsc4py/PETSc/DMPlex.pyx:3804

Parameters

  • dm (DM)

Return type: None

setFromOptions()

configures this transformation straight from the options database. so whatever you passed on the command line gets picked up, no cap 💅

Collective.

See also: Working with PETSc options, DMPlexTransformSetFromOptions

Source code at petsc4py/PETSc/DMPlex.pyx:3813

Return type: None

setType(tr_type)

sets the transformation type. this is you telling it which flavor of transformation you want ✨

Collective.

See also: DMPlexTransformSetType

Source code at petsc4py/PETSc/DMPlex.pyx:3790

Parameters

  • tr_type (DMPlexTransformType | str)

Return type: None

setUp()

setup a mesh transformation. do this before you apply() it, bestie — it's the pre-party prep 🌸

Collective.

Source code at petsc4py/PETSc/DMPlex.pyx:3780

Return type: Self

view(viewer=None)

view the mesh transformation. it's the vibe check, but for your transformation 👀

Collective.

  • viewer — a Viewer instance, or None if you just want the default viewer. Type hint says Viewer | None, so like, either one bestie, no stress 💅
  • Return type — None. It vibes, it shows, it gives nothing back. Iconic behaviour honestly ✨

See also: Viewer, DMPlexTransformView 🫶

Source code lives at petsc4py/PETSc/DMPlex.pyx:3825 — yes bestie you can literally go read it, it's right there 🌸

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

✨ petsc4py.PETSc.DMPlexTransformType ✨

class petsc4py.PETSc.DMPlexTransformType

Bases: object 🦋

Okay so this one is literally just a lil container of transformation types. Like a dress-up box but for meshes. Transformation types. That's the whole job. 💖

🎀 Attributes Summary 🎀

  • EXTRUDE — EXTRUDE, type str ⭐
  • REFINE1D — REFINE1D, type str ⭐
  • REFINEALFELD — REFINEALFELD, type str ⭐
  • REFINEBOUNDARYLAYER — REFINEBOUNDARYLAYER, type str ⭐
  • REFINEPOWELLSABIN — REFINEPOWELLSABIN, type str ⭐
  • REFINEREGULAR — REFINEREGULAR, type str ⭐
  • REFINESBR — REFINESBR, type str ⭐
  • REFINETOBOX — REFINETOBOX, type str ⭐
  • REFINETOSIMPLEX — REFINETOSIMPLEX, type str ⭐
  • TRANSFORMFILTER — TRANSFORMFILTER, type str ⭐

Ten of them. All strings. All lowercase-in-spirit but uppercase in practice. We love a consistent queen. 👑

🌈 Attributes Documentation 🌈

EXTRUDE: str = EXTRUDE

Object EXTRUDE of type str. ✨

REFINE1D: str = REFINE1D

Object REFINE1D of type str. ✨

REFINEALFELD: str = REFINEALFELD

Object REFINEALFELD of type str. ✨

REFINEBOUNDARYLAYER: str = REFINEBOUNDARYLAYER

Object REFINEBOUNDARYLAYER of type str. ✨

REFINEPOWELLSABIN: str = REFINEPOWELLSABIN

Object REFINEPOWELLSABIN of type str. ✨

REFINEREGULAR: str = REFINEREGULAR

Object REFINEREGULAR of type str. ✨

REFINESBR: str = REFINESBR

Object REFINESBR of type str. ✨

REFINETOBOX: str = REFINETOBOX

Object REFINETOBOX of type str. ✨

REFINETOSIMPLEX: str = REFINETOSIMPLEX

Object REFINETOSIMPLEX of type str. ✨

TRANSFORMFILTER: str = TRANSFORMFILTER

Object TRANSFORMFILTER of type str. ✨

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

💜 petsc4py.PETSc.DMShell 💜

class petsc4py.PETSc.DMShell

Bases: DM 🦋

Okay so imagine DM but make it yours. A shell DM object, used to manage user-defined problem data. Basically it's the "bring your own everything" option — you're the main character here, she's just holding the place for you. 👑💅

✨ Methods Summary ✨

okay so here's the whole roster of what a DMShell can do, bestie — every single one of them, no skips 💖

  • create([comm]) — Creates a shell DM object. 🐚
  • setCoarsen(coarsen[, args, kargs]) — Set the routine used to coarsen the DMShell.
  • setCreateDomainDecomposition(decomp[, args, ...]) — Set the routine used to create a domain decomposition.
  • setCreateDomainDecompositionScatters(scatter) — Set the routine used to create the scatter contexts for domain decomposition.
  • setCreateFieldDecomposition(decomp[, args, ...]) — Set the routine used to create a field decomposition.
  • setCreateGlobalVector(create_gvec[, args, kargs]) — Set the routine to create a global vector.
  • setCreateInjection(create_injection[, args, ...]) — Set the routine used to create the injection operator.
  • setCreateInterpolation(create_interpolation) — Set the routine used to create the interpolation operator.
  • setCreateLocalVector(create_lvec[, args, kargs]) — Set the routine to create a local vector.
  • setCreateMatrix(create_matrix[, args, kargs]) — Set the routine to create a matrix.
  • setCreateRestriction(create_restriction[, ...]) — Set the routine used to create the restriction operator.
  • setCreateSubDM(create_subdm[, args, kargs]) — Set the routine used to create a sub DM from the DMShell.
  • setGlobalToLocal(begin, end[, begin_args, ...]) — Set the routines used to perform a global to local scatter.
  • setGlobalToLocalVecScatter(gtol) — Set a Scatter (as in petsc4py.PETSc.Scatter) context for global to local communication.
  • setGlobalVector(gv) — Set a template global vector.
  • setLocalToGlobal(begin, end[, begin_args, ...]) — Set the routines used to perform a local to global scatter.
  • setLocalToGlobalVecScatter(ltog) — Set a Scatter (as in petsc4py.PETSc.Scatter) context for local to global communication.
  • setLocalToLocal(begin, end[, begin_args, ...]) — Set the routines used to perform a local to local scatter.
  • setLocalToLocalVecScatter(ltol) — Set a Scatter context for local to local communication.
  • setLocalVector(lv) — Set a template local vector.
  • setMatrix(mat) — Set a template matrix.
  • setRefine(refine[, args, kargs]) — Set the routine used to refine the DMShell.

🛠️ Methods Documentation 🛠️

👑 create(comm=None)

Creates a shell DM object. 🐚✨ literally manifesting a whole DM out of vibes and a communicator, we love to see it.

Collective. — meaning every single process in the communicator has to show up to this call, periodt. Not me skipping ranks, that's not it. 💅

Parameters

  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm. If you don't hand it one, it just picks up the default communicator for you, so generous of it. 🫶

Return type

  • Self

See also:

  • DMShellCreate

Source code at petsc4py/PETSc/DMShell.pyx:4 🔍

🎀 setCoarsen(coarsen, args=None, kargs=None)

Okay bestie, this one lets you hand the DMShell its very own coarsening routine — like, "here's how you make a smaller version of yourself." Logically collective, so everybody's in on it. ✨

Parameters

  • coarsen (Callable[[DM, Comm], DM] | None) — the routine that actually does the coarsening of the DM. 💅
  • args (tuple[Any, ...] | None) — extra positional args you wanna feed to coarsen.
  • kargs (dict[str, Any] | None) — extra keyword args for coarsen.

Return type

None

See also: setRefine, DMShellSetCoarsen

Source code at petsc4py/PETSc/DMShell.pyx:368

🌸 setCreateDomainDecomposition(decomp, args=None, kargs=None)

Sets the routine in charge of creating a domain decomposition — you know, splitting the whole vibe into pieces so everyone has something to do. 🧚 Logically collective, obviously.

Parameters

  • decomp (Callable[[DM], tuple[list[str] | None, list[IS] | None, list[IS] | None, list[DM] | None]] | None) — the routine that builds the decomposition. It hands back that whole nested tuple: a list of str or None, a list of IS or None, another list of IS or None, and a list of DM or None. 😭 it's giving nested type annotations but we move.
  • args (tuple[Any, ...] | None) — extra positional args for decomp.
  • kargs (dict[str, Any] | None) — extra keyword args for decomp.

Return type

None

See also: DMShellSetCreateDomainDecomposition

Source code at petsc4py/PETSc/DMShell.pyx:560

🦋 setCreateDomainDecompositionScatters(scatter, args=None, kargs=None)

Now for the scatter contexts of your domain decomposition — literally who talks to whom when the data gets shuffled around. Logically collective, periodt.

Parameters

  • scatter (Callable[[DM, list[DM]], tuple[list[Scatter], list[Scatter], list[Scatter]]] | None) — the routine that creates the scatters. Takes a DM and a list of DM, returns a tuple of three list[Scatter]s. 👑
  • args (tuple[Any, ...] | None) — extra positional args for scatter.
  • kargs (dict[str, Any] | None) — extra keyword args for scatter.

Return type

None

See also: DMShellSetCreateDomainDecompositionScatters

Source code at petsc4py/PETSc/DMShell.pyx:592

💜 setCreateFieldDecomposition(decomp, args=None, kargs=None)

Same energy as the domain decomposition one, except this is the field decomposition — grouping your unknowns by field instead of by space. 🔥 Logically collective.

Parameters

  • decomp (Callable[[DM], tuple[list[str] | None, list[IS] | None, list[DM] | None]] | None) — the routine that creates the decomposition. Returns a tuple of a list of str or None, a list of IS or None, and a list of DM or None. (Yeah, no second IS list this time — different routine, different shape. iykyk 💅)
  • args (tuple[Any, ...] | None) — extra positional args for decomp.
  • kargs (dict[str, Any] | None) — extra keyword args for decomp.

Return type

None

See also: DMShellSetCreateFieldDecomposition

Source code at petsc4py/PETSc/DMShell.pyx:528

⭐ setCreateGlobalVector(create_gvec, args=None, kargs=None)

Sets up the routine that creates a global vector — your main character data holder, fr fr. Logically collective.

Parameters

  • create_gvec (Callable[[DM], Vec] | None) — the lil routine that does the creating, bestie 💖
  • args (tuple[Any, ...] | None) — extra positional args you wanna hand off to create_gvec 🎀
  • kargs (dict[str, Any] | None) — extra keyword args for create_gvec, same deal 🌸

Return type: None

See also: setCreateLocalVector, DMShellSetCreateGlobalVector

Source code at petsc4py/PETSc/DMShell.pyx:76

setCreateInjection(create_injection, args=None, kargs=None)

Sets the routine that builds the injection operator — literally handing over the blueprint for how it gets made 💅

Logically collective — everybody's gotta be on the same page, no lone wolves 🙈

Parameters

  • create_injection (Callable[[DM, DM], Mat] | None) — the routine to create the injection ✨
  • args (tuple[Any, ...] | None) — additional positional arguments for create_injection 🎀
  • kargs (dict[str, Any] | None) — additional keyword arguments for create_injection 🌸

Return type: None

See also: DMShellSetCreateInjection

Source code at petsc4py/PETSc/DMShell.pyx:464

setCreateInterpolation(create_interpolation, args=None, kargs=None)

Sets the routine used to create the interpolation operator, the way that it's giving "connect these two worlds for me" 🦋

Logically collective — everyone vibes in sync or not at all 💫

Parameters

  • create_interpolation (Callable[[DM, DM], tuple[Mat, Vec]] | None) — the routine to create the interpolation 👑
  • args (tuple[Any, ...] | None) — additional positional arguments for create_interpolation 🎀
  • kargs (dict[str, Any] | None) — additional keyword arguments for create_interpolation 🌸

Return type: None

See also: DMShellSetCreateInterpolation

Source code at petsc4py/PETSc/DMShell.pyx:432

setCreateLocalVector(create_lvec, args=None, kargs=None)

Sets the routine that creates a local vector — yes bestie, your very own local vector factory 🏭✨

Logically collective — same energy from every process, periodt 💅

Parameters

  • create_lvec (Callable[[DM], Vec] | None) — the creation routine 🎀
  • args (tuple[Any, ...] | None) — additional positional arguments for create_lvec 🌸
  • kargs (dict[str, Any] | None) — additional keyword arguments for create_lvec 🦋

Return type: None

See also: setCreateGlobalVector, DMShellSetCreateLocalVector

Source code at petsc4py/PETSc/DMShell.pyx:108

setCreateMatrix(create_matrix, args=None, kargs=None)

Sets the routine that creates a matrix — the way this is lowkey the main character of so many solves 😭🔥

Logically collective — collective means collective, no skipping 💫

Parameters

  • create_matrix (Callable[[DM], Mat] | None) — the function that creates a matrix 👑
  • args (tuple[Any, ...] | None) — additional positional arguments for create_matrix 🎀
  • kargs (dict[str, Any] | None) — additional keyword arguments for create_matrix 🌸

Return type: None

See also: DMShellSetCreateMatrix

Source code at petsc4py/PETSc/DMShell.pyx:336

setCreateRestriction(create_restriction, args=None, kargs=None)

Sets the routine used to create the restriction operator — going from big world back to small world, the glow-down we absolutely need 🌈

Logically collective 💫

Parameters

  • create_restriction (Callable[[DM, DM], Mat] | None) — the routine to create the restriction 🦋
  • args — extra positional arguments you're handing over to create_restriction, as a tuple[Any, ...] | None. 🫶
  • kargs — extra keyword arguments for create_restriction, as a dict[str, Any] | None. Slay.

Return type: None — she gives you nothing back, and that's correct. 💅

See also: DMShellSetCreateRestriction

Source code at petsc4py/PETSc/DMShell.pyx:496

setCreateSubDM(create_subdm, args=None, kargs=None)

Bestie, this one sets the routine that builds a sub DM out of your DMShell. Like, the DMShell is the parent and this is the little baby DM factory. 🍼✨

Logically collective, so everybody in the pool plays along. 🌊

Parameters

  • subdm — the routine that creates the decomposition. (Yes, that's literally what the original calls it. We keep it.)
  • args — additional positional arguments for subdm, as a tuple[Any, ...] | None. 🎀
  • kargs — additional keyword arguments for subdm, as a dict[str, Any] | None. 🎀
  • create_subdm — typed as Callable[[DM, Sequence[int]], tuple[IS, DM]] | None. So it takes a DM and a Sequence[int], and hands you back a tuple of (IS, DM). Iconic signature, no notes. 👑

Return type: None

See also: DMShellSetCreateSubDM

Source code at petsc4py/PETSc/DMShell.pyx:624

setGlobalToLocal(begin, end, begin_args=None, begin_kargs=None, end_args=None, end_kargs=None)

Okay so THIS one sets up the routines that do a global-to-local scatter. She's got a beginning and an end, because she's extra like that. 💖

Logically collective. Obviously.

Parameters

  • dm — the DMShell. That's the one you're operating on, bestie.
  • begin — the routine that begins the global to local scatter. Typed Callable[[DM, Vec, InsertMode, Vec], None] | None. 🦋
  • end — the routine that ends the global to local scatter. Same type, Callable[[DM, Vec, InsertMode, Vec], None] | None. 🦋
  • begin_args — additional positional arguments for begin, as a tuple[Any, ...] | None. 🌸
  • begin_kargs — additional keyword arguments for begin, as a dict[str, Any] | None. 🌸
  • end_args — additional positional arguments for end, as a tuple[Any, ...] | None. 🌸
  • end_kargs — additional keyword arguments for end, as a dict[str, Any] | None. 🌸

Return type: None

See also: DMShellSetGlobalToLocal

Source code at petsc4py/PETSc/DMShell.pyx:140

setGlobalToLocalVecScatter(gtol)

Sets a Scatter context for global-to-local communication. Lowkey one of the more chill ones — one argument, one job. 😌

Logically collective.

Parameters

  • gtol — the global to local Scatter context. That's a Scatter, in case the name didn't give it away. 💀

Return type: None

See also: DMShellSetGlobalToLocalVecScatter

Source code at petsc4py/PETSc/DMShell.pyx:189

setGlobalVector(gv)

Sets a template global vector. That's it, that's the whole vibe. ⭐

Logically collective.

Parameters

  • gv — the template vector, a Vec. 🎀

Return type: None

See also: setLocalVector, DMShellSetGlobalVector

Source code at petsc4py/PETSc/DMShell.pyx:42

setLocalToGlobal(begin, end, begin_args=None, begin_kargs=None, end_args=None, end_kargs=None)

And NOW we're doing the reverse direction bestie — this sets the routines for a local to global scatter. Same energy as setGlobalToLocal but flipped, and honestly? We love a symmetry moment. 🌈

Logically collective.

Parameters

  • begin — the routine that begins the local to global scatter, typed Callable[[DM, Vec, InsertMode, Vec], None] | None. 🦋
  • end — the routine that ends the local to global scatter, typed Callable[[DM, Vec, InsertMode, Vec], None] | None. 🦋
  • begin_args (tuple[Any, ...] | None) — extra positional args you wanna hand to begin 🎀
    • begin_kargs (dict[str, Any] | None) — extra keyword args for begin
    • end_args (tuple[Any, ...] | None) — extra positional args for end
    • end_kargs (dict[str, Any] | None) — extra keyword args for end

Return type: None

See also: DMShellSetLocalToGlobal

Source code at petsc4py/PETSc/DMShell.pyx:206

setLocalToGlobalVecScatter(ltog)

okay so this one hands over a Scatter context that's in charge of the local → global communication. bestie that's literally the whole vibe 💫

Logically collective — meaning everybody in the group chat has to call it together, no lurking 🙈

Parameters:

  • ltog (Scatter) — the local-to-global Scatter context. that's it, that's the one 🦋

Return type: None

See also: DMShellSetLocalToGlobalVecScatter

Source code at petsc4py/PETSc/DMShell.pyx:253

setLocalToLocal(begin, end, begin_args=None, begin_kargs=None, end_args=None, end_kargs=None)

sets up the routines that do a local → local scatter. two halves, one glow-up ✨

Logically collective.

Parameters:

  • begin (Callable[[DM, Vec, InsertMode, Vec], None] | None) — the routine that kicks off the local-to-local scatter. main character energy, obviously 👑
  • end (Callable[[DM, Vec, InsertMode, Vec], None] | None) — the routine that wraps the local-to-local scatter up. closing the loop, periodt 💅
  • begin_args (tuple[Any, ...] | None) — extra positional args for begin
  • begin_kargs (dict[str, Any] | None) — extra keyword args for begin
  • end_args (tuple[Any, ...] | None) — extra positional args for end
  • end_kargs (dict[str, Any] | None) — extra keyword args for end

Return type: None

See also: DMShellSetLocalToLocal

Source code at petsc4py/PETSc/DMShell.pyx:270

setLocalToLocalVecScatter(ltol)

drops in a Scatter context for the local → local communication. same energy as the local-to-global one but, like, local 🌸

Logically collective.

Parameters:

  • ltol (Scatter) — the local-to-local Scatter context 💖

Return type: None

See also: DMShellSetLocalToLocalVecScatter

Source code at petsc4py/PETSc/DMShell.pyx:319

setLocalVector(lv)

sets a template local vector. a lil blueprint for the local side 🧚

Logically collective.

Parameters:

  • lv (Vec) — template vector 📐

Return type: None

See also: setGlobalVector, DMShellSetLocalVector

Source code at petsc4py/PETSc/DMShell.pyx:59

setMatrix(mat)

sets a template matrix. blueprint but make it matrix-coded 🔥

Collective — yes, collective, not just logically. everyone shows up, no exceptions 💀

Parameters:

  • mat (Mat) — the template matrix ⭐

Return type: None

See also: DMShellSetMatrix

Source code at petsc4py/PETSc/DMShell.pyx:25

setRefine(refine, args=None, kargs=None)

sets the routine used to refine the DMShell. glow-up time, but for your mesh ✨🦋

Logically collective.

Parameters:

  • refine (Callable[[DM, Comm], DM] | None) — the routine that refines the DM. takes a DM and a Comm, gives you a DM back — a whole transformation arc 🌈
  • args (tuple[Any, ...] | None) — extra positional args for refine
  • kargs (dict[str, Any] | None) — extra keyword args for refine

Return type: None

See also: setCoarsen, DMShellSetRefine

📍 where the source actually lives: it's at petsc4py/PETSc/DMShell.pyx:400, like, right there bestie:

https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMShell.pyx#L400
  • __init__() — the constructor. runs when you make one of these bad boys. 💅
  • classmethod __new__(*args, **kwargs) — the classmethod that actually creates the instance before __init__ gets its hands on it. classic Python main-character behavior, it goes first. 👑

🦋 petsc4py.PETSc.DMStag 🦋

class petsc4py.PETSc.DMStag

Bases: DM — yep, it's a DM subclass, that's the whole family tree, iykyk. 🌳

okay so this one is a DM object that represents a "staggered grid" or a structured cell complex. yes bestie, cell complex. we're doing geometry, we're doing structure, we're eating. 🔥

✨ Enumerations ✨

  • StencilLocation (full name: petsc4py.PETSc.DMStag.StencilLocation) — Stencil location types. 📍
  • StencilType (full name: petsc4py.PETSc.DMStag.StencilType) — Stencil types. 🧩

🌸 petsc4py.PETSc.DMStag.StencilLocation 🌸

class petsc4py.PETSc.DMStag.StencilLocation

Bases: object — (that's https://docs.python.org/3/builtins/functions.html#object if you wanted to go read about plain old object, but like, it's object, you know it, you love it, it's giving humble beginnings 💖)

Stencil location types. 💫

✨ Attributes Summary ✨

okay bestie, vibe check time 🫶 this part is the attribute roster — a whole lineup of constants, and every single one of them is a constant of type int. that's it, that's the tea ☕ no objects, no structs, just good ol' int energy.

if you wanna go stare into the abyss of what int even is (fair, honestly), the original points you here: <https://docs.python.org/3/builtins/functions.html#int>

the original lays all of this out in a big chonky table, but tables are giving 2019 spreadsheet core, so here's the same roster as a list. nothing dropped, nothing merged, every name exactly where it should be 💅

  • BACK — a constant named BACK, of type int. iconic name, no notes ✨
  • BACK_DOWN — constant BACK_DOWN, type int. it's giving direction, bestie 🧭
  • BACK_DOWN_LEFT — constant BACK_DOWN_LEFT, type int. three words and a dream 🌸
  • BACK_DOWN_RIGHT — constant BACK_DOWN_RIGHT, type int. the sibling of the one above, no cap 💜
  • BACK_LEFT — constant BACK_LEFT, type int. short, sweet, int 💖
  • BACK_RIGHT — constant BACK_RIGHT, type int. the mirror vibe 🌈
  • BACK_UP — constant BACK_UP, type int. okayyy opposite energy 👑
  • BACK_UP_LEFT — constant BACK_UP_LEFT, type int. the name is doing the most, respectfully 🎀
  • BACK_UP_RIGHT — constant BACK_UP_RIGHT, type int. last of the BACK crew fr fr
  • DOWN — constant DOWN, type int. one word, main character energy 💅
  • DOWN_LEFT — constant DOWN_LEFT, type int. consistently int, as always 🦋
  • DOWN_RIGHT — constant DOWN_RIGHT, type int. yes bestie, still an int 😭
  • ELEMENT — constant ELEMENT, type int. a whole vibe, single int 🌟
  • FRONT — constant FRONT, type int. starting the FRONT era ✨
  • FRONT_DOWN — constant FRONT_DOWN, type int. int, obviously 🍓
  • FRONT_DOWN_LEFT — constant FRONT_DOWN_LEFT, type int. the name got longer, the type did not 💀
  • FRONT_DOWN_RIGHT — constant FRONT_DOWN_RIGHT, type int. pairing up with the one above, cute 🫶
  • FRONT_LEFT — constant FRONT_LEFT, type int. here for it 💜
  • FRONT_RIGHT — constant FRONT_RIGHT, type int. two-word baddie 🔥
  • FRONT_UP — constant FRONT_UP, type int. we love an upward moment 🙈
  • FRONT_UP_LEFT — constant FRONT_UP_LEFT, type int. committed to the bit 🎀
  • FRONT_UP_RIGHT — constant FRONT_UP_RIGHT, type int. closing out the FRONT set 💖
  • LEFT — constant LEFT, type int. minimalist queen 👑
  • NULLLOC — constant NULLLOC, type int. one single word, capital letters only, type int. periodt 💅

so yeah — twenty-four names, twenty-four constants, twenty-four ints, zero shortcuts taken. if you skipped a line, go back, every one of them matters 😤 and there's still more of this page left, so don't you dare close the terminal — we are not done here 🌸

✨ Attributes Documentation ✨

okay bestie, real talk — every single one of these bad boys is an int, like the Python builtin int (https://docs.python.org/3/builtins/functions.html#int), and every one of them equals itself. They're the directional location constants for the DMStag vibe grid, and they're all giving "I am the direction I'm named after" 💅. Here's the full roster, no skips, no cuts:

  • BACK: int = BACK — Constant BACK of type int. It's literally back. Behind. The rear. 🫶
  • BACK_DOWN: int = BACK_DOWN — Constant BACK_DOWN of type int. Back and down, at the same time, unbothered. ✨
  • BACK_DOWN_LEFT: int = BACK_DOWN_LEFT — Constant BACK_DOWN_LEFT of type int. Back, down, left — the triple threat. 👑
  • BACK_DOWN_RIGHT: int = BACK_DOWN_RIGHT — Constant BACK_DOWN_RIGHT of type int. Back, down, right. Slay in three axes. 🔥
  • BACK_LEFT: int = BACK_LEFT — Constant BACK_LEFT of type int. Back and left, iconic duo energy.
  • BACK_RIGHT: int = BACK_RIGHT — Constant BACK_RIGHT of type int. Back and right, no notes.
  • BACK_UP: int = BACK_UP — Constant BACK_UP of type int. Back going up, main character trajectory. 🦋
  • BACK_UP_LEFT: int = BACK_UP_LEFT — Constant BACK_UP_LEFT of type int. Back, up, left — full corner behaviour.
  • BACK_UP_RIGHT: int = BACK_UP_RIGHT — Constant BACK_UP_RIGHT of type int. Back, up, right. Cornered but in a cute way.
  • DOWN: int = DOWN — Constant DOWN of type int. Not up. Hope this helps 💖
  • DOWN_LEFT: int = DOWN_LEFT — Constant DOWN_LEFT of type int. Down and left together, as a treat.
  • DOWN_RIGHT: int = DOWN_RIGHT — Constant DOWN_RIGHT of type int. Down and right. Periodt.
  • ELEMENT: int = ELEMENT — Constant ELEMENT of type int. The center element itself, the it-girl of the stencil. 🌟
  • FRONT: int = FRONT — Constant FRONT of type int. Front. Up front. The face card. ✨
  • FRONT_DOWN: int = FRONT_DOWN — Constant FRONT_DOWN of type int. Front and down, lowkey consistent.
  • FRONT_DOWN_LEFT: int = FRONT_DOWN_LEFT — Constant FRONT_DOWN_LEFT of type int. Front, down, left — very much itself.
  • FRONT_DOWN_RIGHT: int = FRONT_DOWN_RIGHT — Constant FRONT_DOWN_RIGHT of type int. Front, down, right. Highkey precise.
  • FRONT_LEFT: int = FRONT_LEFT — Constant FRONT_LEFT of type int. Front and left, besties fr fr.
  • FRONT_RIGHT: int = FRONT_RIGHT — Constant FRONT_RIGHT of type int. Front and right, no cap.
  • FRONT_UP: int = FRONT_UP — Constant FRONT_UP of type int. Front and up. Ascending, literally. 🧚
  • FRONT_UP_LEFT: int = FRONT_UP_LEFT — Constant FRONT_UP_LEFT of type int. Front, up, left — a whole coordinate situation.
  • FRONT_UP_RIGHT: int = FRONT_UP_RIGHT — Constant FRONT_UP_RIGHT of type int. Front, up, right. Also a whole coordinate situation.
  • LEFT: int = LEFT — Constant LEFT of type int. You guessed it — it's left. 🎀
  • NULLLOC: int = NULLLOC — Constant NULLLOC of type int. The null location. The void. The "no thoughts head empty" of locations 💀
  • RIGHT: int = RIGHT — Constant RIGHT of type int. Right. Correct. Iconic.
  • UP: int = UP — Constant UP of type int. Up. We're going up. 🌈
  • UP_LEFT: int = UP_LEFT — Constant UP_LEFT of type int. Up and left, a classic.
  • UP_RIGHT: int = UP_RIGHT — Constant UP_RIGHT of type int. Up and right, also a classic.

__init__()

classmethod __new__(*args, **kwargs) — yeah bestie, the classmethod constructor, being a construction king as always 👑

💅 petsc4py.PETSc.DMStag.StencilType 💅

class petsc4py.PETSc.DMStag.StencilType

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

Stencil types. That's it, that's the whole description — the stencil types live here. 🎀

✨ Attributes Summary ✨

✨ Attributes Documentation ✨

BOX: int = BOX

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

  • NONE: int = NONE — okay so this is a constant, her name is NONE 💅 and her type is int — and by int we mean Python's builtin int, the actual one, docs live at https://docs.python.org/3/builtins/functions.html#int if you wanna go vibe-check her. Constant NONE of type int, that's the whole tea 🫖
  • STAR: int = STAR — and here's the constant STAR ⭐ type int too, same builtin int as above, same docs link, literally the identical https://docs.python.org/3/builtins/functions.html#int 🎀 Constant STAR of type int. Two iconics, one vibe, no cap.

And then we got the dunder squad, because of course we do 🙈 presenting, in the order they're written:

  • __init__() — the init, listed with no parameters and no extra description. She's here, she's short, she's serving exactly what's written 💀
  • classmethod __new__(*args, **kwargs) — a classmethod ✨ and her whole flex is *args and **kwargs, fr fr that's it, that's the signature, I'm not gonna invent more for you bestie 🦋
ngl these four lines are giving "short but important" energy. Bullet for bullet, that's every single thing the page says right here — nothing added, nothing dropped, we stay factual even when we're being cute 💖
  • VecSplitToDMDA(vec, loc, c) — bestie this one hands you back a DMDA and a Vec, pulled from a subgrid of a DMStag plus its Vec. two-for-one deal, we love to see it 💖
  • create(dim[, dofs, sizes, boundary_types, ...]) — Create a DMDA object. the main character constructor, the way it takes dim and then a lil optional squad of dofs, sizes, boundary_types, and more ✨
  • createCompatibleDMStag(dofs) — Create a compatible DMStag but with different DOFs per stratum. same vibe, different DOF distribution. slay 🦋
  • get1dCoordinatecArrays() — lmao nope, Not implemented. it's giving "coming soon" but fr it's just not there 💀
  • getBoundaryTypes() — Return the boundary types in each dimension. tell me ur edges without telling me ur edges 🌸
  • getCorners() — Return starting element index, width and number of partial elements. corners! those little awkward bits at the edge of the grid 🎀
  • getDim() — Return the number of dimensions. how many D's we working in bestie 🌈
  • getDof() — Get number of DOFs associated with each stratum of the grid. DOFs per stratum, one lil number for each layer 💅
  • getEntriesPerElement() — Return the number of entries per element in the local representation. how chunky is each element, locally 👑
  • getGhostCorners() — Return starting element index and width of the local region. ghost corners = the local region's little bounding info 🫶
  • getGlobalSizes() — Return global element counts in each dimension. the whole entire world's element counts, per dimension 🌍
  • getIsFirstRank() — Return whether this process is first in each dimension in the process grid. are you the first born in each dim? 🧚
  • getIsLastRank() — Return whether this process is last in each dimension in the process grid. or are you the baby of the family in each dim 😭
  • getLocalSizes() — Return local elementwise sizes in each dimension. ur personal slice, elementwise, per dim 🔥
  • getLocationDof(loc) — Return number of DOFs associated with a given point on the grid. feed it a loc, it tells you how many DOFs live at that point ⭐
  • getLocationSlot(loc, c) — Return the index to use in accessing raw local arrays. the secret handshake index for raw local array access 🤫
  • getOwnershipRanges() — Return elements per process in each dimension. who owns what, split up per process per dim 💜
  • getProcSizes() — Return number of processes in each dimension. how many lil workers in each dim 💖
  • getProductCoordinateLocationSlot(loc) — Return the slot for use with local product coordinate arrays. product coordinate arrays have a slot and this is it 🍓
  • getStencilType() — Return elementwise ghost/halo stencil type. ghost slash halo, elementwise, what type is it ✨
  • getStencilWidth() — Return elementwise stencil width. how wide is the stencil, elementwise 🎀
  • getVecArray(vec) — Not implemented. nope, not a thing yet 😭
  • migrateVec(vec, dmTo, vecTo) — Transfer a vector between two DMStag objects. vector, moving houses, from one DMStag to another 🦋
  • setBoundaryTypes(boundary_types) — Set the boundary types. lock in those edge types 💅
  • setCoordinateDMType(dmtype) — Set the type to store coordinates. pick the type that's gonna hold ur coords ✨
  • setDof(dofs) — Set DOFs/stratum. DOFs per stratum, ur call 👑
  • setGlobalSizes(sizes) — Set global element counts in each dimension. lay down the global element counts per dim 🌈
  • setOwnershipRanges(ranges) — Set elements per process in each dimension. assign who owns how many elements, per process, per dim 🫶
  • setProcSizes(sizes) — sets how many processes live in each dimension of the global process grid ✨
  • setStencilType(stenciltype) — picks the elementwise ghost/halo stencil type 🫶
  • setStencilWidth(swidth) — sets the elementwise stencil width, no cap 💅
  • setUniformCoordinates([xmin, xmax, ymin, ...]) — makes the coordinates a uniform grid 💖
  • setUniformCoordinatesExplicit([xmin, xmax, ...]) — same uniform-grid energy, but it literally stores every single value 📝
  • setUniformCoordinatesProduct([xmin, xmax, ...]) — builds uniform coordinates as a product of 1D arrays, the way that math just works 🌈

✨ Attributes Summary ✨

  • boundary_types — the boundary types in each dimension 🚧
  • corners — the lower left corner plus the size of the local region in each dimension 📐
  • dim — the dimension, bestie. that's it 🦋
  • dofs — how many DOFs are attached to each stratum of the grid 🔢
  • entries_per_element — the number of entries per element in the local representation 🎀
  • ghost_corners — the lower left corner and the size of the local region in each dimension (yes, ghost edition, it's giving spectral) 👻
  • global_sizes — global element counts in each dimension 🌍
  • local_sizes — local elementwise sizes in each dimension 🏠
  • proc_sizes — the number of processes in each dimension of the global decomposition ⚙️
  • stencil_type — the stencil type 🔥
  • stencil_width — the elementwise stencil width 💫

📖 Methods Documentation 📖

VecSplitToDMDA(vec, loc, c)

okay so this one hands you back a DMDA and a Vec from a subgrid of a DMStag and its Vec 💖

Collective. so like, everyone's in on it, no solo missions 🫂

Here's the tea on c: if you pass a c value of -k, the first k DOFs for that position get extracted, and it pads with zero values if it needs to 🌸. If you pass a non-negative value instead, then it's just a single DOF getting extracted, periodt ✨

Parameters

  • vec (Vec) — the Vec object 🎀
  • loc (DMStag.StencilLocation) — which subgrid to extract 👀
  • c (int) — which component to extract 🔍

Return type — tuple[DMDA, Vec] 💜

See also: DMStagVecSplitToDMDA 🔗

Source code at petsc4py/PETSc/DMStag.pyx:790 📌

create(dim, dofs=None, sizes=None, boundary_types=None, stencil_type=None, stencil_width=None, proc_sizes=None, ownership_ranges=None, comm=None, setUp=False)

Creates a DMDA object. iconic behaviour, fr fr 👑

Collective. 🫶

What it actually does: it creates an object to manage data living on the elements and vertices / the elements, faces, and vertices / the elements, faces, edges, and vertices of a parallelized regular 1D / 2D / 3D grid 🌈 — yes, all three flavours, she contains multitudes.

Parameters

  • dim (int) — the number of dimensions 📏
  • dofs (tuple[int, ...] | None) — the number of degrees of freedom per vertex, element (1D); vertex, face, element (2D); or vertex, edge, face, element (3D) 🔢
  • sizes (tuple[int, ...] | None) — the number of elements in each dimension 📐
  • boundary_types (tuple[DM.BoundaryType | int | str | bool, ...] | None) — the boundary types 🚧
  • stencil_type (DMStag.StencilType | None) — the ghost/halo stencil type 👻
  • stencil_width (int | None) — the width of the ghost/halo region 💫
  • proc_sizes (tuple[int, ...] | None) — how many processes are chilling in the x, y, z dimensions. 🫶
  • ownership_ranges (tuple[Sequence[int], ...] | None) — the local x, y, z element counts, length equal to proc_sizes, and bestie they gotta sum to sizes.
  • comm (Comm | None) — the MPI communicator, and it defaults to Sys.getDefaultComm.
  • setUp (bool | None) — whether to call the setup routine right after creating the object.

Return type: Self

See also: DMStagCreate1d, DMStagCreate2d, DMStagCreate3d, DMSetUp

Source code at petsc4py/PETSc/DMStag.pyx:50

createCompatibleDMStag(dofs)

Make a compatible DMStag but with different DOFs/stratum, slay. ✨

Collective. (so like, everybody has to show up, no skipping 💅)

Parameters:

  • dofs (tuple[int, ...]) — the number of DOFs on the strata in the new DMStag.

Return type: DM

See also: DMStagCreateCompatibleDMStag

Source code at petsc4py/PETSc/DMStag.pyx:766

get1dCoordinatecArrays()

Not implemented. 🙈 (yeah bestie, it's giving "coming soon" but make it never)

Source code at petsc4py/PETSc/DMStag.pyx:832

Return type: None

getBoundaryTypes()

Return the boundary types in each dimension. 🎀

Not collective.

See also: setBoundaryTypes, DMStagGetBoundaryTypes

Source code at petsc4py/PETSc/DMStag.pyx:478

Return type: tuple[str, ...]

getCorners()

Return the starting element index, the width, and the number of partial elements. ✨

Not collective.

The returned value is calculated excluding ghost points, fyi.

The number of extra partial elements is either 1 or 0. It's 1 on right, top, and front non-periodic domain ("physical") boundaries, in the x, y, and z dimensions respectively, and otherwise 0.

See also: getGhostCorners, DMStagGetCorners, DMGetDimension

Source code at petsc4py/PETSc/DMStag.pyx:363

Return type: tuple[tuple[int, ...], tuple[int, ...], tuple[int, ...]]

getDim()

Return the number of dimensions. 💖

Not collective.

Source code at petsc4py/PETSc/DMStag.pyx:310

Return type: int

getDof()

Get the number of DOFs associated with each stratum of the grid. 🦋

Not collective.

See also: DMStagGetDOF

Source code at petsc4py/PETSc/DMStag.pyx:348

Return type: tuple[int, ...]

getEntriesPerElement()

Return the number of entries per element in the local representation. 🌸

Not collective.

This is the natural block size for most local operations — so lowkey remember it.

See also: DMStagGetEntriesPerElement

Source code at petsc4py/PETSc/DMStag.pyx:318

Return type: int

getGhostCorners()

Return the starting element index and the width of the local region. 👑

Not collective.

See also: getCorners, DMStagGetGhostCorners

Source code at petsc4py/PETSc/DMStag.pyx:385

Return type: tuple[tuple[int, ...], tuple[int, ...]]

getGlobalSizes()

Return the global element counts in each dimension. 🌈

Not collective.

See also: getLocalSizes, DMStagGetGlobalSizes

Source code at petsc4py/PETSc/DMStag.pyx:417

Return type: tuple[int, ...]

getIsFirstRank()

Return whether this process is first in each dimension in the process grid. ⭐

Not collective.

See also: DMStagGetIsFirstRank

Source code at petsc4py/PETSc/DMStag.pyx:496

Return type: tuple[int, ...]

getIsLastRank()

Return whether this process is last in each dimension in the process grid. 💜

Not collective.

See also: DMStagGetIsLastRank

Source code at petsc4py/PETSc/DMStag.pyx:512

Return type: tuple[int, ...]

Return type: tuple[int, ...] — and that's the tail end of the previous one, so carry on bestie 💖

✨ getLocalSizes() ✨

okay so this one hands you back the local elementwise sizes in each dimension 🎀

Not collective — just you and your own little slice, no group chat needed 🙈

Quick heads-up tho: the value you get back is calculated excluding ghost points 👻 so don't come for it expecting the ghosts, they're not invited to this party.

See also: getGlobalSizes, DMStagGetLocalSizes

Source code at petsc4py/PETSc/DMStag.pyx:400

Return type: tuple[int, ...]

💅 getLocationDof(loc) 💅

Returns the number of DOFs chillin' at a given point on the grid 🦋

Not collective.

Parameters:

  • loc (StencilLocation) — The grid point. that's literally it, the spot you're curious about.

Return type: int

See also: DMStagGetLocationDOF

Source code at petsc4py/PETSc/DMStag.pyx:721

🌸 getLocationSlot(loc, c) 🌸

Gives you the index to use when you're digging into raw local arrays — your little VIP pass into the data 💖

Not collective.

Parameters:

  • loc (StencilLocation) — Location relative to an element.
  • c (int) — Component.

Return type: int

See also: DMStagGetLocationSlot

Source code at petsc4py/PETSc/DMStag.pyx:678

🌈 getOwnershipRanges() 🌈

Returns how many elements each process is claiming in each dimension — divvying up the grid like splitting fries among the group 🍟

Not collective.

See also: setOwnershipRanges, DMStagGetOwnershipRanges

Source code at petsc4py/PETSc/DMStag.pyx:461

Return type: tuple[Sequence[int], ...]

⭐ getProcSizes() ⭐

The number of processes in each dimension, periodt 👑

Not collective.

See also: DMStagGetNumRanks

Source code at petsc4py/PETSc/DMStag.pyx:432

Return type: tuple[int, ...]

🧚 getProductCoordinateLocationSlot(loc) 🧚

Returns the slot to use with local product coordinate arrays 🎀

Not collective.

Parameters:

  • loc (StencilLocation) — The grid location.

Return type: None

See also: DMStagGetProductCoordinateLocationSlot

Source code at petsc4py/PETSc/DMStag.pyx:701

🦋 getStencilType() 🦋

Spills the tea on the elementwise ghost/halo stencil type 👻 no cap.

Not collective.

See also: setStencilType, DMStagGetStencilType

Source code at petsc4py/PETSc/DMStag.pyx:447

Return type: str

💜 getStencilWidth() 💜

Returns the elementwise stencil width — how wide your stencil's reach is, lowkey important 📏

Not collective.

See also: DMStagGetStencilWidth

Source code at petsc4py/PETSc/DMStag.pyx:334

Return type: int

💀 getVecArray(vec) 💀

Not implemented. That's it. That's the whole vibe. It's giving "coming soon" but let's be real, it's giving "nope" 😭

Source code at petsc4py/PETSc/DMStag.pyx:828

Parameters:

  • vec (Vec)

Return type: None

🔥 migrateVec(vec, dmTo, vecTo) 🔥

Transfers a vector between two DMStag objects — like moving your whole playlist to a new phone 🎶

Collective — everybody's involved in this one, it's a group activity 🫶

Important caveat bestie: currently only implemented to migrate global vectors to global vectors. So don't get cute trying to send locals through here 💅

Parameters:

  • vec (Vec) — The source vector.
  • dmTo (DM) — The compatible destination object.
  • vecTo (Vec) — The destination vector.

Return type: None

See also: DMStagMigrateVec

Source code at petsc4py/PETSc/DMStag.pyx:743

🎀 setBoundaryTypes(boundary_types) 🎀

Sets the boundary types, iconic behaviour, love that for you ✨

Logically collective.

Parameters:

  • boundary_types (tuple[BoundaryType | int | str | bool, ...]) — Boundary types for one/two/three dimensions.

Return type: None

See also: getBoundaryTypes, DMStagSetBoundaryTypes

Source code at petsc4py/PETSc/DMStag.pyx:201

🌸 setCoordinateDMType(dmtype) 🌸

Sets the type used to store coordinates — picking the main character for your coordinate storage 📍

Logically collective.

Parameters:

  • dmtype (Type) — The type to store coordinates.

Return type: None

See also: DMStagSetCoordinateDMType

Source code at petsc4py/PETSc/DMStag.pyx:657

👑 setDof(dofs) 👑

Sets the DOFs per stratum 💖 assigning how many degrees of freedom live on each piece of the grid, obsessed.

Logically collective.

Parameters:

  • dofs (tuple[int, ...]) — The number of points per 0-cell (vertex/node), 1-cell (element in 1D, edge in 2D and 3D), 2-cell (element in 2D, face in 3D), or 3-cell (element in 3D).

Return type: None

  • ymin (float) — lowest global coordinate value in the y dimension 💜
    • ymax (float) — highest global coordinate value in the y dimension ✨
    • zmin (float) — lowest global coordinate value in the z dimension 🦋
    • zmax (float) — highest global coordinate value in the z dimension 🦋
okay bestie quick vibe check: yes, all six of those got a default of 0 for the mins and 1 for the maxes, so if you just call it with no args you get a nice unit box, no cap 💅

and that's genuinely it for the parameter roll call — this one's very "tell me your box, I'll handle it" 🎀

  • ymin (float) — the smallest global coordinate value along the y axis, bestie 💖
  • ymax (float) — the biggest global coordinate value along the y axis 🔥
  • zmin (float) — the smallest global coordinate value along the z axis, yes we're in 3D now 👑
  • zmax (float) — the biggest global coordinate value along the z axis 🌈

Return type

None — like, it returns nothing, it just did the thing 💅

See also:

  • setUniformCoordinatesExplicit
  • setUniformCoordinates
  • DMStagSetUniformCoordinatesProduct

Source code at petsc4py/PETSc/DMStag.pyx:568

✨ Attributes Documentation ✨

  • boundary_types — boundary types in each dimension, one per dim, no cap 🫶

Source code at petsc4py/PETSc/DMStag.pyx:866

  • corners — the lower left corner and the size of the local region, in each dimension 📐

Source code at petsc4py/PETSc/DMStag.pyx:881

  • dim — the dimension. that's it. that's the whole vibe 🌸

Source code at petsc4py/PETSc/DMStag.pyx:836

  • dofs — the number of DOFs hanging off each stratum of the grid 🎀

Source code at petsc4py/PETSc/DMStag.pyx:841

  • entries_per_element — how many entries per element you get in the local representation 🍓

Source code at petsc4py/PETSc/DMStag.pyx:846

  • ghost_corners — the lower left corner and size of the local region in each dimension (the ghost edition, obviously) 👻✨

Source code at petsc4py/PETSc/DMStag.pyx:886

  • global_sizes — global element counts, in each dimension 🌍

Source code at petsc4py/PETSc/DMStag.pyx:851

  • local_sizes — local elementwise sizes, in each dimension 🏠

Source code at petsc4py/PETSc/DMStag.pyx:856

  • proc_sizes — how many processes live in each dimension of the global decomposition 💀 (parallel girlies rise)

Source code at petsc4py/PETSc/DMStag.pyx:861

  • stencil_type — the stencil type ✨

Source code at petsc4py/PETSc/DMStag.pyx:871

  • stencil_width — the elementwise stencil width 📏

Source code at petsc4py/PETSc/DMStag.pyx:876

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

🦋 petsc4py.PETSc.DMSwarm 🦋

class petsc4py.PETSc.DMSwarm

Bases: DM

A DM object whose whole personality is representing arrays of data (fields) of arbitrary type. it's giving ✨flexible✨ and we love that for it 💜

Enumerations

  • CollectType — Swarm collection types.
  • MigrateType — Swarm migration types.
  • PICLayoutType — Swarm PIC layout types.
  • Type — Swarm types.

🎀 petsc4py.PETSc.DMSwarm.CollectType 🎀

class petsc4py.PETSc.DMSwarm.CollectType

Bases: object

Swarm collection types. the little menu of ways to collect, iykyk 💅

Attributes Summary

  • COLLECT_BASIC — Constant COLLECT_BASIC of type int
  • COLLECT_DMDABOUNDINGBOX — Constant COLLECT_DMDABOUNDINGBOX of type int
  • COLLECT_GENERAL — Constant COLLECT_GENERAL of type int
  • COLLECT_USER — Constant COLLECT_USER of type int

Attributes Documentation

COLLECT_BASIC

COLLECT_BASIC: int = COLLECT_BASIC

Constant COLLECT_BASIC of type int 🫶

COLLECT_DMDABOUNDINGBOX

COLLECT_DMDABOUNDINGBOX: int = COLLECT_DMDABOUNDINGBOX

Constant COLLECT_DMDABOUNDINGBOX of type int 📦 (yes the name is a whole mouthful, we don't make the rules)

COLLECT_GENERAL

COLLECT_GENERAL: int = COLLECT_GENERAL

Constant COLLECT_GENERAL of type int ✨

COLLECT_USER

COLLECT_USER: int = COLLECT_USER

Constant COLLECT_USER of type int — this one's for you, bestie 👑

__init__()

classmethod __new__(*args, **kwargs)

🌈 petsc4py.PETSc.DMSwarm.MigrateType 🌈

class petsc4py.PETSc.DMSwarm.MigrateType

Bases: object

Swarm migration types.

Let's do the attribute summary real quick, bestie — it's giving very "these are all just ints" energy and honestly? Iconic. 💅

✨ Attributes Documentation ✨

MIGRATE_BASIC: int (https://docs.python.org/3/builtins/functions.html#int) = MIGRATE_BASIC

Constant MIGRATE_BASIC of type int (https://docs.python.org/3/builtins/functions.html#int). Yes bestie that's the whole description, it said what it said. 🎀

MIGRATE_DMCELLEXACT: int (https://docs.python.org/3/builtins/functions.html#int) = MIGRATE_DMCELLEXACT

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

MIGRATE_DMCELLNSCATTER: int (https://docs.python.org/3/builtins/functions.html#int) = MIGRATE_DMCELLNSCATTER

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

MIGRATE_USER: int (https://docs.python.org/3/builtins/functions.html#int) = MIGRATE_USER

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

__init__()

__init__()

classmethod __new__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

🦋 petsc4py.PETSc.DMSwarm.PICLayoutType

class petsc4py.PETSc.DMSwarm.PICLayoutType

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

Swarm PIC layout types. That's the vibe, that's the whole job. ✨

Attributes Summary

✨ Attributes Documentation ✨

LAYOUT_GAUSS: int (https://docs.python.org/3/builtins/functions.html#int) = LAYOUT_GAUSS

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

LAYOUT_REGULAR: int (https://docs.python.org/3/builtins/functions.html#int) = LAYOUT_REGULAR

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

LAYOUT_SUBDIVISION: int (https://docs.python.org/3/builtins/functions.html#int) = LAYOUT_SUBDIVISION

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

__init__()

__init__()

classmethod __new__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

🌈 petsc4py.PETSc.DMSwarm.Type

class petsc4py.PETSc.DMSwarm.Type

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

Swarm types. Two of them. That's it, that's the roster. 👑

Attributes Summary

✨ Attributes Documentation ✨

BASIC: int (https://docs.python.org/3/builtins/functions.html#int) = BASIC

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

PIC: int (https://docs.python.org/3/builtins/functions.html#int) = PIC

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

__init__()

__init__()

classmethod __new__(*args, **kwargs)

classmethod __new__(*args, **kwargs)
Not me writing __init__() and __new__(*args, **kwargs) over and over like a little prayer — but bestie, they're literally in every single class and we do not skip a single one. No cap. 💀

And yeah, every one of these constants is just int. Every. Single. One. The docs said int, so I said int, and we move on together. 🫶

✨ Methods Summary ✨

okay bestie, here comes the full roster of DMSwarm methods 💅 every single one, no skipping, let's gooo

  • addCellDM(celldm) — drops a cell DM into the DMSwarm. adding a whole cell, obsessed 🎀
  • addNPoints(npoints) — makes room for npoints brand-new points in the DMSwarm. bulk vibes ✨
  • addPoint() — makes room for exactly one new point in the DMSwarm. just the one, lowkey 💖
  • collectViewCreate() — applies a collection method and gathers up the points sitting in neighbor ranks. it's giving teamwork 🫶
  • collectViewDestroy() — resets the DMSwarm back to the size it had before you called collectViewCreate. put it back the way you found it 🧚
  • computeMoments(coord, weight) — hands you back the moments defined in the active cell DM. math girlies rise 🌸
  • copyPoint(pi, pj) — copies point pi straight over to point pj in the DMSwarm. twin behavior 💀
  • create([comm]) — creates an empty DM object and sets its type to DM.Type.SWARM. baby's first swarm 🔥
  • createGlobalVectorFromField(fieldname) — creates a global Vec object tied to a given field. global queen 👑
  • createGlobalVectorFromFields(fieldnames) — creates a global Vec object tied to a given set of fields. the whole squad 🌈
  • createLocalVectorFromField(fieldname) — creates a local Vec object tied to a given field. staying in your lane, respectfully 💜
  • createLocalVectorFromFields(fieldnames) — creates a local Vec object tied to a given set of fields. local legend ⭐
  • destroyGlobalVectorFromField(fieldname) — destroys the global Vec object tied to a given field. bye bestie 😭
  • destroyGlobalVectorFromFields(fieldnames) — destroys the global Vec object tied to a given set of fields 💅
  • destroyLocalVectorFromField(fieldname) — destroys the local Vec object tied to a given field. clean up after yourself 🙈
  • destroyLocalVectorFromFields(fieldnames) — destroys the local Vec object tied to a given set of fields 🍓
  • finalizeFieldRegister() — finalizes the registration of fields into a DMSwarm. wrap it up, we're done registering 🎀
  • getCellDM() — returns the DM cell attached to the DMSwarm. come get ur DM ✨
  • getCellDMActive() — returns the active cell DM in the DMSwarm. main character energy only 👑
  • getCellDMByName(name) — returns the cell DM with the given name in the DMSwarm. calling it by name, iconic 💖
  • getCellDMNames() — returns the names of all the cell DMs in the DMSwarm. the full guest list 🌸
  • getField(fieldname) — returns arrays storing every entry associated with a field. everything, all of it 🦋
  • getLocalSize() — returns the local length of the registered fields. count 'em locally 💜
  • getSize() — returns the total length of the registered fields. the whole entire count, periodt 🔥

no cap, that's the whole methods summary — every method, every arg, exactly as the manpage says it 💅 more coming, don't go anywhere bestie 🫶

  • initializeFieldRegister() — kicks off the registration of fields over on a DMSwarm 💫
  • insertPointUsingCellDM(layoutType, fill_param) — drops point coordinates inside every single cell 🎯
  • migrate([remove_sent_points]) — relocates the points living in the DMSwarm over to other MPI ranks 🚚
  • projectFields(dm, fieldnames, vecs[, mode]) — projects a whole set of DMSwarm fields onto the cell petsc4py.PETSc.DM ✨
  • registerField(fieldname, blocksize[, dtype]) — registers a field onto a DMSwarm with a native PETSc data type 🏷️
  • removePoint() — yeets the last point off the DMSwarm 👋
  • removePointAtIndex(index) — yeets one specific point off the DMSwarm, by index 💅
  • restoreField(fieldname) — restores the accesses tied to a registered field 🔄
  • setCellDM(dm) — attaches a petsc4py.PETSc.DM to a DMSwarm 🧲
  • setCellDMActive(name) — makes a cell DM active inside the DMSwarm ⚡
  • setLocalSizes(nlocal, buffer) — sets the length of all registered fields on the DMSwarm 📏
  • setPointCoordinates(coordinates[, ...]) — sets point coordinates in a DMSwarm from a user-defined list 📝
  • setPointCoordinatesCellwise(coordinates) — inserts point coordinates within each cell 🧩
  • setPointsUniformCoordinates(min, max, npoints) — sets point coordinates in a DMSwarm on a regular (ijk) grid 🔲
  • setType(dmswarm_type) — sets the particular flavor of DMSwarm 🍦
  • sortGetAccess() — sets up a DMSwarm point sort context 🔧
  • sortGetIsValid() — returns whether the sort context is up-to-date ⏰
  • sortGetNumberOfPointsPerCell(e) — returns how many points are in a cell 🔢
  • sortGetPointsPerCell(e) — builds an array of point indices for all the points in a cell 🗂️
  • sortGetSizes() — returns the sizes associated with a DMSwarm point sorting context 📐
  • sortRestoreAccess() — invalidates the DMSwarm point sorting context 💀
  • vectorDefineField(fieldname) — sets the fields that a petsc4py.PETSc.Vec object gets defined from 🧵
  • viewFieldsXDMF(filename, fieldnames) — writes a selection of DMSwarm fields out to an XDMF3 file 💾
  • viewXDMF(filename) — writes this DMSwarm's fields out to an XDMF3 file 🗃️

📖 Methods Documentation 🔍

addCellDM(celldm)

Adds a cell DM to the DMSwarm, bestie 🫶

Logically collective — so everybody hop in, okay? No solo missions.

Parameters

  • cellDM (CellDM, see petsc4py.PETSc.CellDM) — the cell DM object
  • celldm (CellDM, see petsc4py.PETSc.CellDM)

Return type

None — literally the Python None, documented over at https://docs.python.org/3/builtins/constants.html#None 🙈

See also

DMSwarmAddCellDM — https://petsc.org/release/manualpages/DMSwarm/DMSwarmAddCellDM.html

(and that wraps the entry above — source code at petsc4py/PETSc/DMSwarm.pyx:957 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L957)

addNPoints(npoints)

bestie this one is giving "make room for the whole squad" 💅 it adds space for a number of new points up in the DMSwarm.

Not collective. (so no group chat vibes, everybody does their own thing)

Parameters

  • npoints (int) — the number of new points to add ✨

Return type

None

See also: DMSwarmAddNPoints — https://petsc.org/release/manualpages/DMSwarm/DMSwarmAddNPoints.html

Source code at petsc4py/PETSc/DMSwarm.pyx:444 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L444

addPoint()

the solo version, no cap: adds space for one new point in the DMSwarm 🎀 one little guy. one tiny icon. periodt.

Not collective.

See also: DMSwarmAddPoint — https://petsc.org/release/manualpages/DMSwarm/DMSwarmAddPoint.html

Source code at petsc4py/PETSc/DMSwarm.pyx:432 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L432

Return type

None

collectViewCreate()

applies a collection method and gathers points in neighbor ranks 🫶

Collective. everybody's in the group chat for this one fr fr.

See also: collectViewDestroy, DMSwarmCollectViewCreate — https://petsc.org/release/manualpages/DMSwarm/DMSwarmCollectViewCreate.html

Source code at petsc4py/PETSc/DMSwarm.pyx:560 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L560

Return type

None

collectViewDestroy()

the undo button 🦋 resets the DMSwarm back to the size it had before you called collectViewCreate.

Collective.

See also: collectViewCreate, DMSwarmCollectViewDestroy — https://petsc.org/release/manualpages/DMSwarm/DMSwarmCollectViewDestroy.html

Source code at petsc4py/PETSc/DMSwarm.pyx:572 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L572

Return type

None

computeMoments(coord, weight)

returns the moments defined in the active cell DM 💫

Collective.

Notes

we integrate the given weight field over the given coordinate 🌸 that's the whole vibe.

See also: DMSwarmComputeMoments — https://petsc.org/release/manualpages/DMSwarm/DMSwarmComputeMoments.html

Source code at petsc4py/PETSc/DMSwarm.pyx:1047 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L1047

Parameters

  • coord (str)
  • weight (str)

Return type

list[float]

copyPoint(pi, pj)

copies point pi to point pj in the DMSwarm — it's giving "ctrl+c ctrl+v but make it physics" 😭💅

Not collective.

Parameters

  • pi (int) — the index of the point to copy (source).
  • pj (int) — the point index where the copy should be located (destination).

Return type

None

See also: DMSwarmCopyPoint — https://petsc.org/release/manualpages/DMSwarm/DMSwarmCopyPoint.html

Source code at petsc4py/PETSc/DMSwarm.pyx:492 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L492

create(comm=None)

creates an empty DM object and sets its type to DM.Type.SWARM ✨ iconic behaviour honestly.

Collective.

quick lil reminder bestie: DMs are the abstract objects in PETSc that mediate between meshes and discretizations and the algebraic solvers, time integrators, and optimization algorithms. main character energy, truly 👑

Parameters

  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type

Self

See also: DMCreate — https://petsc.org/release/manualpages/DM/DMCreate.html, DMSetType — https://petsc.org/release/manualpages/DM/DMSetType.html

Source code at petsc4py/PETSc/DMSwarm.pyx:39 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L39

createGlobalVectorFromField(fieldname)

creates a global Vec object associated with a given field 🌈

Collective.

⚠️ heads up: the vector must be returned to the DMSwarm using a matching call to destroyGlobalVectorFromField. like. you borrowed it. give it back 🫶

Parameters

  • fieldname (str) — the textual name given to a registered field.

Return type

Vec

See also: destroyGlobalVectorFromField, DMSwarmCreateGlobalVectorFromField — https://petsc.org/release/manualpages/DMSwarm/DMSwarmCreateGlobalVectorFromField.html

Source code at petsc4py/PETSc/DMSwarm.pyx:65 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L65

createGlobalVectorFromFields(fieldnames)

same energy as above but for a whole set of fields 💖 creates a global Vec object associated with a given set of fields.

Collective.

⚠️ again, bestie: the vector must be returned to the DMSwarm using a matching call to destroyGlobalVectorFromFields. no stealing 🚫

Parameters

  • fieldnames (Sequence[str]) — the textual name given to each registered field.

Return type

Vec

See also: destroyGlobalVectorFromFields, DMSwarmCreateGlobalVectorFromFields — https://petsc.org/release/manualpages/DMSwarm/DMSwarmCreateGlobalVectorFromFields.html

Source code at petsc4py/PETSc/DMSwarm.pyx:109 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L109

createLocalVectorFromField(fieldname)

the local edition 🦋 creates a local Vec object associated with a given field.

Collective.

⚠️ and yes — the vector must be returned to the DMSwarm using a matching call to destroyLocalVectorFromField. it's a library card, not a gift 💅

Parameters

  • fieldname (str) — the textual name given to a registered field.

Return type

Vec

See also: destroyLocalVectorFromField, DMSwarmCreateLocalVectorFromField — https://petsc.org/release/manualpages/DMSwarm/DMSwarmCreateLocalVectorFromField.html

Source code at petsc4py/PETSc/DMSwarm.pyx:165 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L165

createLocalVectorFromFields(fieldnames)

and the local set version 🎀 creates a local Vec object associated with a given set of fields.

Collective.

⚠️ the vector must be returned to the DMSwarm using a matching call to destroyLocalVectorFromFields. returning it is the whole ritual, don't skip it 😭

Parameters

  • fieldnames (Sequence[str]) — the textual name given to each registered field.

Return type

Vec

See also: destroyLocalVectorFromFields, DMSwarmCreateLocalVectorFromFields — https://petsc.org/release/manualpages/DMSwarm/DMSwarmCreateLocalVectorFromFields.html

Source code at petsc4py/PETSc/DMSwarm.pyx:165 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L165 (see also the entry's own line at petsc4py/PETSc/DMSwarm.pyx:165 above — and there's more swarm coming, so stay tuned 💜)

🌸 destroyGlobalVectorFromField(fieldname)

Not me dropping the global Vec for one field 💅 This is the "okay bestie, pack it up" call: it destroys the global Vec object tied to a given field.

Collective. Everyone's in on it, fr fr.

Parameters

  • fieldname (str) — the textual name you gave to a registered field.

Return type: None

See also: createGlobalVectorFromField, DMSwarmDestroyGlobalVectorFromField (petsc.org/release/manualpages/DMSwarm/DMSwarmDestroyGlobalVectorFromField.html)

Source code at petsc4py/PETSc/DMSwarm.pyx:209 (that's gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L209 if you wanna go look at the source, icon behavior honestly 🔥)

🌈 destroyGlobalVectorFromFields(fieldnames)

The plural version, periodt. Destroys the global Vec object associated with a whole set of fields at once.

Collective.

Parameters

  • fieldnames (Sequence[str]) — the textual name you gave to each registered field.

Return type: None

See also: createGlobalVectorFromFields, DMSwarmDestroyGlobalVectorFromFields (petsc.org/release/manualpages/DMSwarm/DMSwarmDestroyGlobalVectorFromFields.html)

Source code at petsc4py/PETSc/DMSwarm.pyx:139 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L139)

🦋 destroyLocalVectorFromField(fieldname)

Same vibe, but local 🫶 Destroys the local Vec object hanging out with a given field.

Collective.

Parameters

  • fieldname (str) — the textual name given to a registered field.

Return type: None

See also: createLocalVectorFromField, DMSwarmDestroyLocalVectorFromField (petsc.org/release/manualpages/DMSwarm/DMSwarmDestroyLocalVectorFromField.html)

Source code at petsc4py/PETSc/DMSwarm.pyx:189 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L189)

💜 destroyLocalVectorFromFields(fieldnames)

And now the local set version, because of course there's one 💀 Destroys the local Vec object associated with a given set of fields.

Collective.

Parameters

  • fieldnames (Sequence[str]) — the textual name given to each registered field.

Return type: None

See also: createLocalVectorFromFields, DMSwarmDestroyLocalVectorFromFields (petsc.org/release/manualpages/DMSwarm/DMSwarmDestroyLocalVectorFromFields.html)

Source code at petsc4py/PETSc/DMSwarm.pyx:239 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L239)

✨ finalizeFieldRegister()

The "we're done, lock it in" step 🔒 Finalizes the registration of fields to a DMSwarm.

Collective.

See also: initializeFieldRegister, DMSwarmFinalizeFieldRegister (petsc.org/release/manualpages/DMSwarm/DMSwarmFinalizeFieldRegister.html)

Source code at petsc4py/PETSc/DMSwarm.pyx:279 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L279)

Return type: None

🎀 getCellDM()

Returns the DM cell that's attached to the DMSwarm — like, the actual cell DM, bestie, not a rumor.

Collective.

See also: setCellDM, DMSwarmGetCellDM (petsc.org/release/manualpages/DMSwarm/DMSwarmGetCellDM.html)

Source code at petsc4py/PETSc/DMSwarm.pyx:601 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L601)

Return type: DM

🧚 getCellDMActive()

Returns the active cell DM in the DMSwarm 👑 lowkey the main character cell.

Not collective.

See also: DMSwarmGetCellDMActive (petsc.org/release/manualpages/DMSwarm/DMSwarmGetCellDMActive.html)

Source code at petsc4py/PETSc/DMSwarm.pyx:993 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L993)

Return type: CellDM

🍓 getCellDMByName(name)

Gimme the cell DM with this specific name in the DMSwarm 🎯 name-based search, no cap.

Not collective.

See also: DMSwarmGetCellDMByName (petsc.org/release/manualpages/DMSwarm/DMSwarmGetCellDMByName.html)

Source code at petsc4py/PETSc/DMSwarm.pyx:1010 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L1010)

Parameters

  • name (str)

Return type: CellDM

🌟 getCellDMNames()

Returns the names of all the cell DMs in the DMSwarm — the full roster 📋✨

Not collective.

See also: DMSwarmGetCellDMNames (petsc.org/release/manualpages/DMSwarm/DMSwarmGetCellDMNames.html)

Source code at petsc4py/PETSc/DMSwarm.pyx:1029 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L1029)

Return type: list[str]

💖 getField(fieldname)

Bestie this one is important, listen up 🙈 It returns arrays storing all the entries associated with a field.

Not collective.

The returned array contains the underlying values of the field — like, the actual data, not a copy vibe.

⚠️ The array must be returned to the DMSwarm using a matching call to restoreField. Don't just hold onto it, okay? Give it back.

Parameters

  • fieldname (str) — the textual name that identifies this field.

Returns: the type of the entries in the array will match the type of the field. The array is two dimensional with shape (num_points, blocksize).

Return type: numpy.ndarray

See also: restoreField, DMSwarmGetField (petsc.org/release/manualpages/DMSwarm/DMSwarmGetField.html)

Source code at petsc4py/PETSc/DMSwarm.pyx:343 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L343)

🌸 getLocalSize()

Returns the local length of the fields that are registered. Just the local slice, iykyk 🍰

Not collective.

See also: DMSwarmGetLocalSize (petsc.org/release/manualpages/DMSwarm/DMSwarmGetLocalSize.html)

Source code at petsc4py/PETSc/DMSwarm.pyx:513 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L513)

Return type: int

⭐ getSize()

Returns the total length of the fields registered — the whole squad, not just your corner of it 🌍

Collective.

See also: DMSwarmGetSize (petsc.org/release/manualpages/DMSwarm/DMSwarmGetSize.html)

Source code at petsc4py/PETSc/DMSwarm.pyx:527 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L527)

Return type: int

🎀 initializeFieldRegister()

Kicks off the whole registration of fields to a DMSwarm — the opening number of the field-registration musical 💅

Collective.

🫶 After all the fields have been registered, you must call finalizeFieldRegister. You can't just leave it hanging.

See also: finalizeFieldRegister, DMSwarmInitializeFieldRegister (petsc.org/release/manualpages/DMSwarm/DMSwarmInitializeFieldRegister.html)

Source code at petsc4py/PETSc/DMSwarm.pyx:265 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L265)

insertPointUsingCellDM(layoutType, fill_param)

Not collective. 💅

Drop point coordinates inside every single cell — yes, all of them.

Params:

  • layout_type — the method that fills each cell with the cell DM.
  • fill_param (int) — controls how many points per cell get added. Heads up bestie: what this number means totally depends on the layout type. ⚠️
  • layoutType (PICLayoutType)

Return type: None

See also: DMSwarmInsertPointsUsingCellDM

Source code at petsc4py/PETSc/DMSwarm.pyx:716

migrate(remove_sent_points=False)

Collective. 🦋

Relocate points that live in the DMSwarm so they hop over to other MPI ranks. It's giving ✨annual migration✨ but for points.

Params:

  • remove_sent_points (bool) — flag saying whether points that got sent should be deleted from the MPI rank they came from.

Return type: None

See also: DMSwarmMigrate

Source code at petsc4py/PETSc/DMSwarm.pyx:541

projectFields(dm, fieldnames, vecs, mode=None)

Collective. 💖

Project a set of DMSwarm fields onto the cell DM. Glow-up pipeline: swarm data → continuum DM.

Params:

  • dm (DM) — the continuum DM.
  • fieldnames (Sequence[str]) — the textual names of the swarm fields you're projecting.
  • vecs (Sequence[Vec])
  • mode (ScatterModeSpec)

Return type: None

See also: DMSwarmProjectFields

Source code at petsc4py/PETSc/DMSwarm.pyx:925

registerField(fieldname, blocksize, dtype=ScalarType)

Collective. 🎀

Register a field onto a DMSwarm using a native PETSc data type. Making it official, no cap.

Params:

  • fieldname (str) — the textual name that identifies this field.
  • blocksize (int) — how many of each data type.
  • dtype (petsc4py.PETSc.Device.type | numpy.dtype) — a valid PETSc data type.

Return type: None

See also: DMSwarmRegisterPetscDatatypeField

Source code at petsc4py/PETSc/DMSwarm.pyx:313

removePoint()

Not collective. 💀

Yeet the last point off the DMSwarm. Bye bestie 🫶

See also: DMSwarmRemovePoint

Source code at petsc4py/PETSc/DMSwarm.pyx:462

Return type: None

removePointAtIndex(index)

Not collective. 💀

Remove one specific point from the DMSwarm — surgical, targeted, iconic.

Params:

  • index (int) — index of the point to remove.

Return type: None

See also: DMSwarmRemovePointAtIndex

Source code at petsc4py/PETSc/DMSwarm.pyx:474

restoreField(fieldname)

Not collective. 🌸

Restore the accesses tied to a registered field. Like, put it back the way you found it, periodt.

Params:

  • fieldname (str) — the textual name that identifies this field.

Return type: None

See also: getField, DMSwarmRestoreField

Source code at petsc4py/PETSc/DMSwarm.pyx:389

setCellDM(dm)

Collective. ✨

Attach a DM to a DMSwarm. They're officially together now 💜

Params:

  • dm (DM) — the DM to attach to the DMSwarm.

Return type: None

See also: getCellDM, DMSwarmSetCellDM

Source code at petsc4py/PETSc/DMSwarm.pyx:584

setCellDMActive(name)

Logically collective. 🌈

Activate a cell DM inside the DMSwarm. Waking it up, main character energy only.

Params:

  • name (str) — the name of the cell DM to activate.

Return type: None

See also: DMSwarmSetCellDMActive

Source code at petsc4py/PETSc/DMSwarm.pyx:974

setLocalSizes(nlocal, buffer)

Not collective. 🎀

Set the length of all the registered fields on the DMSwarm. Sizing the whole fit at once.

Params:

  • nlocal (int) — the length of each registered field.
  • buffer (int) — the length of the buffer used for efficient dynamic resizing.

Return type: Self

See also: DMSwarmSetLocalSizes

Source code at petsc4py/PETSc/DMSwarm.pyx:291

setPointCoordinates(coordinates, redundant=False, mode=None)

Collective. 🦋

Set the point coordinates in a DMSwarm from a list you made yourself. Your points, your coords, your rules.

Params:

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

See also: DMSwarmSetPointCoordinates <https://petsc.org/release/manualpages/DMSwarm/DMSwarmSetPointCoordinates.html>

Source code at petsc4py/PETSc/DMSwarm.pyx:680 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L680>

✨ setPointCoordinatesCellwise(coordinates) ✨

Insert point coordinates within each cell. Obsessed with the per-cell energy honestly 💖

Not collective. (So like, each rank just does its own thing, no group chat required 🫶)

Point coordinates are defined over the reference cell.

Parameters

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

See also: DMSwarmSetPointCoordinatesCellwise <https://petsc.org/release/manualpages/DMSwarm/DMSwarmSetPointCoordinatesCellwise.html>

Source code at petsc4py/PETSc/DMSwarm.pyx:738 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L738>

👑 setPointsUniformCoordinates(min, max, npoints, mode=None) 👑

Set point coordinates in a DMSwarm on a regular (ijk) grid. Grid go brrr, it's giving structured ✨

Collective.

Parameters

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

See also: DMSwarmSetPointsUniformCoordinates <https://petsc.org/release/manualpages/DMSwarm/DMSwarmSetPointsUniformCoordinates.html>

Source code at petsc4py/PETSc/DMSwarm.pyx:636 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L636>

🦋 setType(dmswarm_type) 🦋

Set the particular flavor of DMSwarm. Pick your fighter ✨

Collective.

Parameters

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

See also: DMSwarmSetType <https://petsc.org/release/manualpages/DMSwarm/DMSwarmSetType.html>

Source code at petsc4py/PETSc/DMSwarm.pyx:618 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L618>

🎀 sortGetAccess() 🎀

Set up a DMSwarm point sort context. Glow-up for your point traversal 💅

Not collective.

The point sort context is what you use for efficient traversal of points within a cell. Very main character, very optimized 🦋

Important bestie: you must call sortRestoreAccess when you no longer need access to the sort context. Don't leave it hanging 😭

See also: sortRestoreAccess, DMSwarmSortGetAccess <https://petsc.org/release/manualpages/DMSwarm/DMSwarmSortGetAccess.html>

Source code at petsc4py/PETSc/DMSwarm.pyx:813 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L813>

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

⭐ sortGetIsValid() ⭐

Return whether the sort context is up-to-date. The vibe check for your sorting context 🫶

Not collective.

Returns the flag associated with a DMSwarm point sorting context.

See also: DMSwarmSortGetIsValid <https://petsc.org/release/manualpages/DMSwarm/DMSwarmSortGetIsValid.html>

Source code at petsc4py/PETSc/DMSwarm.pyx:887 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L887>

Return type: bool <https://docs.python.org/3/builtins/functions.html#bool>

🌸 sortGetNumberOfPointsPerCell(e) 🌸

Return the number of points in a cell. Counting queen behavior 👑

Not collective.

Parameters

Return type: int <https://docs.python.org/3/builtins/functions.html#int>

See also: DMSwarmSortGetNumberOfPointsPerCell <https://petsc.org/release/manualpages/DMSwarm/DMSwarmSortGetNumberOfPointsPerCell.html>

Source code at petsc4py/PETSc/DMSwarm.pyx:867 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L867>

💜 sortGetPointsPerCell(e) 💜

Create an array of point indices for all the points in a cell. Here's your lil roll call, bestie 📋✨

Not collective.

Parameters

Return type: list <https://docs.python.org/3/builtins/stdtypes.html#list>[int <https://docs.python.org/3/builtins/functions.html#int>]

See also: DMSwarmSortGetPointsPerCell <https://petsc.org/release/manualpages/DMSwarm/DMSwarmSortGetPointsPerCell.html>

Source code at petsc4py/PETSc/DMSwarm.pyx:843 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L843>

🌈 sortGetSizes() 🌈

Return the sizes associated with a DMSwarm point sorting context. Receipts time 🧾💖

Not collective.

Returns

Return type: tuple <https://docs.python.org/3/builtins/stdtypes.html#tuple>[int <https://docs.python.org/3/builtins/functions.html#int>, int <https://docs.python.org/3/builtins/functions.html#int>]

See also: DMSwarmSortGetSizes <https://petsc.org/release/manualpages/DMSwarm/DMSwarmSortGetSizes.html>

Source code at petsc4py/PETSc/DMSwarm.pyx:903 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L903>

🫶 sortRestoreAccess() 🫶

Invalidate the DMSwarm point sorting context. Cleanup era, so satisfying ✨

Not collective.

See also: sortGetAccess, DMSwarmSortRestoreAccess <https://petsc.org/release/manualpages/DMSwarm/DMSwarmSortRestoreAccess.html>

Source code at petsc4py/PETSc/DMSwarm.pyx:831 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DMSwarm.pyx#L831>

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

✨ vectorDefineField(fieldname) ✨

bestie this one sets the fields that get used to define a Vec 💫 object, okay so it's lowkey important.

Collective, fr fr — everybody in the communicator has to be on the same page.

The field you name here is the one that gets used when DM.createLocalVec or DM.createGlobalVec gets called. like, that's the whole vibe.

Parameters

  • fieldname (str) — The textual names given to a registered field. ✨

Return type

None

See also:

  • DMSwarmVectorDefineField

Source code at petsc4py/PETSc/DMSwarm.pyx:410

🌸 viewFieldsXDMF(filename, fieldnames) 🌸

okay so this one writes a selection of DMSwarm fields out to an XDMF3 file. slay. 💅

Collective, no cap.

Parameters

  • filename (str) — The file name of the XDMF file (must have the extension .xmf). 🎀
  • fieldnames (Sequence[str]) — Array containing the textual names of fields to write.

Return type

None

See also:

  • DMSwarmViewFieldsXDMF

Source code at petsc4py/PETSc/DMSwarm.pyx:765

🦋 viewXDMF(filename) 🦋

and this one writes this DMSwarm's fields to an XDMF3 file. the whole thing, not a selection. iconic behavior honestly. ⭐

Collective.

Parameters

  • filename (str) — The file name of the XDMF file (must have the extension .xmf).

Return type

None

See also:

  • DMSwarmViewXDMF

Source code at petsc4py/PETSc/DMSwarm.pyx:794

__init__()

(no thoughts, just vibes — she's a constructor 🫶)

classmethod __new__(*args, **kwargs)

petsc4py.PETSc.DS

class petsc4py.PETSc.DS

Bases: Object

Discrete System object. that's the whole assignment bestie 💜

Enumerations

  • Type — The Discrete System types.

petsc4py.PETSc.DS.Type

class petsc4py.PETSc.DS.Type

Bases: object

The Discrete System types. periodt. ✨

Attributes Summary

  • BASIC — Object BASIC of type str

Attributes Documentation

BASIC: str = BASIC

  • Object BASIC of type str

__init__()

classmethod __new__(*args, **kwargs)

🌈 Methods Summary 🌈

  • create([comm]) — Create an empty DS.
  • destroy() — Destroy the discrete system.
  • getComponents() — Return the number of components for each field on an evaluation point.
  • getCoordinateDimension() — Return the coordinate dimension of the DS.
  • getDimensions() — Return the size of the space for each field on an evaluation point.
  • getFieldIndex(disc) — Return the index of the given field.
  • getNumFields() — Return the number of fields in the DS.
  • getSpatialDimension() — Return the spatial dimension of the DS.
  • getTotalComponents() — Return the total number of components in this system.
  • getTotalDimensions() — Return the total size of the approximation space for this system.
  • getType() — Return the type of the discrete system.
  • setDiscretisation(f, disc) — Set the discretization object for the given field.
  • setFromOptions() — Set parameters in a DS from the options database.
  • setType(ds_type) — Build a particular type of a discrete system.
  • setUp() — Construct data structures for the discrete system.
  • view([viewer]) — View a discrete system.

💖 Methods Documentation 💖

create(comm=None)

Create an empty DS. baby DS, brand new, freshly zeroed out 🍼✨

Collective.

The type can then be set with setType.

Parameters

  • comm (Comm | None) — bestie, this is your MPI communicator (iykyk), and if you don't hand one over it lowkey defaults to Sys.getDefaultComm. 🫶

Return type

Self ✨

See also: setType, destroy, PetscDSCreate

Source code at petsc4py/PETSc/DS.pyx:53

💀 destroy()

Okay so this one does exactly what it says on the tin — it destroys the discrete system. Gone. Poof. 🎀

Collective — meaning everybody in the comm gotta show up for this one, no ghosting. 👑

See also: create, PetscDSDestroy

Source code at petsc4py/PETSc/DS.pyx:40

Return type

Self ✨

🌸 getComponents()

Returns the number of components for each field on an evaluation point. Fr fr, it's giving "tell me how many components per field, babe." 🌈

Not collective — this one you can absolutely do solo, no group project energy needed. 💅

See also: PetscDSGetComponents

Source code at petsc4py/PETSc/DS.pyx:246

Return type

ArrayInt

🦋 getCoordinateDimension()

Spits out the coordinate dimension of the DS. The coordinate dimension of the DS is the dimension of the space into which the discretizations are embedded — so like, the outer dimension, the vibe dimension, the one they live inside. 🪩

Not collective. Nope, you're on your own and that's iconic.

See also: PetscDSGetCoordinateDimension

Source code at petsc4py/PETSc/DS.pyx:153

Return type

int

🎀 getDimensions()

Tells you the size of the space for each field on an evaluation point. The math bestie knows the math. ✨

Not collective — no committee meeting required, you got this. 💖

See also: PetscDSGetDimensions

Source code at petsc4py/PETSc/DS.pyx:231

Return type

ArrayInt

🔥 getFieldIndex(disc)

Returns the index of the given field. Like "where in the lineup is this field?" — and you just tell it which one and it's like, oh that one, index number noted. 🫡

Not collective.

Parameters

  • disc (Object) — the discretization object, aka the thing whose index you're tryna find. 👀

Return type

int

See also: PetscDSGetFieldIndex

Source code at petsc4py/PETSc/DS.pyx:184

👑 getNumFields()

Returns the number of fields in the DS. Just the count. Simple. Main character behavior honestly. 💅

Not collective.

See also: PetscDSGetNumFields

Source code at petsc4py/PETSc/DS.pyx:170

Return type

int

🧚 getSpatialDimension()

Returns the spatial dimension of the DS — and ngl, the spatial dimension of the DS is the topological dimension of the discretizations. So like, not the embedding space this time, the actual topological vibe. Trust. 🌸

Not collective.

See also: PetscDSGetSpatialDimension

Source code at petsc4py/PETSc/DS.pyx:136

Return type

int

⭐ getTotalComponents()

Returns the total number of components in this system. The whole system, all the components, summed. Math girlboss moment. 🔥

Not collective.

See also: PetscDSGetTotalComponents

Source code at petsc4py/PETSc/DS.pyx:217

Return type

int

💜 getTotalDimensions()

Returns the total size of the approximation space for this system — big number energy, the whole approximation space measured up. 🫶

Not collective.

See also: PetscDSGetTotalDimension

Source code at petsc4py/PETSc/DS.pyx:203

Return type

int

🍓 getType()

Returns the type of the discrete system — like "what flavour is this DS?" and it'll tell you. 🎀

Not collective.

See also: setType, PetscDSGetType

Source code at petsc4py/PETSc/DS.pyx:95

Return type

str

🌈 setDiscretisation(f, disc)

Sets the discretization object for the given field. You tell it which field (f) and hand it the disc object, and boom — that field's discretization is set, no cap. 💖

Not collective.

Parameters

  • f (int) — the field number, so like which field are we decorating today bestie. 💅
  • disc (Object) — the discretization object itself, the one getting assigned. ✨

Return type

None

See also: PetscDSSetDiscretization

Source code at petsc4py/PETSc/DS.pyx:261

🎀 setFromOptions()

Sets parameters in a DS from the options database. This is the "let the command line decide my fate" moment and honestly it's giving efficiency. 💀

Collective — everybody in the comm, together, one vibe. 👑

See also: Working with PETSc options, PetscDSSetFromOptions

Source code at petsc4py/PETSc/DS.pyx:109

Return type

None

🦋 setType(ds_type)

Builds a particular type of a discrete system — you pick ds_type and it constructs the whole thing for you. Fr fr, that's the move. 🌟

Collective — group chat energy, everybody contributes. ✨

Parameters

  • ds_type (Type | str) — the type of the discrete system. Pass it as a Type or just a plain string, either slays. 💅

Return type

None

See also: getType, PetscDSSetType

Source code at petsc4py/PETSc/DS.pyx:76

🌸 setUp()

Constructs the data structures for the discrete system. Basically: get the scaffolding ready before anything else gets weird. 🧚

Collective — everyone's gotta be on the same page here, besties. 🫶

See also: PetscDSSetUp

Source code at petsc4py/PETSc/DS.pyx:121

Return type

Self ✨

👑 view(viewer=None)

Views a discrete system — aka makes it visible so you can actually look at what you built. Iconic debugging behavior, obsessed. 💖

Collective.

Parameters

  • viewer (Viewer | None) — a Viewer to display the system. Don't hand it one and it does its own thing. 👀

Return type

None

✨ and that's a wrap on the DS methods, besties ✨

Source code at petsc4py/PETSc/DS.pyx:21 ([gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DS.pyx#L21](https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DS.pyx#L21))

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

petsc4py.PETSc.Device 💻✨

class petsc4py.PETSc.Device

Bases: object ([docs.python.org/3/builtins/functions.html#object](https://docs.python.org/3/builtins/functions.html#object))

okay so this is the device object, bestie 🎀

It's literally a handle to an accelerator — and yes, sometimes the host counts as one of those, no cap. So like, think of it as your lil' backstage pass to whichever compute thing is doing the actual work. 💅

See also:

Enumerations 🌈

  • Type — the type of device. ([#petsc4py.PETSc.Device.Type](#petsc4py.PETSc.Device.Type))

petsc4py.PETSc.Device.Type 🦋

class petsc4py.PETSc.Device.Type

Bases: object ([docs.python.org/3/builtins/functions.html#object](https://docs.python.org/3/builtins/functions.html#object))

the type of device, periodt 🔥

See also:

  • Device ([#petsc4py.PETSc.Device](#petsc4py.PETSc.Device))
  • Device.create ([#petsc4py.PETSc.Device.create](#petsc4py.PETSc.Device.create))
  • Device.getDeviceType ([#petsc4py.PETSc.Device.getDeviceType](#petsc4py.PETSc.Device.getDeviceType))
  • Device.type ([#petsc4py.PETSc.Device.type](#petsc4py.PETSc.Device.type))
  • PetscDeviceType ([petsc.org/release/manualpages/Sys/PetscDeviceType.html](https://petsc.org/release/manualpages/Sys/PetscDeviceType.html))

Attributes Summary 🎀

Attributes Documentation 📝

CUDA: int = CUDA — Constant CUDA of type int ([docs.python.org/3/builtins/functions.html#int](https://docs.python.org/3/builtins/functions.html#int))

DEFAULT: int = DEFAULT — Constant DEFAULT of type int ([docs.python.org/3/builtins/functions.html#int](https://docs.python.org/3/builtins/functions.html#int))

HIP: int = HIP — Constant HIP of type int ([docs.python.org/3/builtins/functions.html#int](https://docs.python.org/3/builtins/functions.html#int))

HOST: int = HOST — Constant HOST of type int ([docs.python.org/3/builtins/functions.html#int](https://docs.python.org/3/builtins/functions.html#int))

SYCL: int = SYCL — Constant SYCL of type int ([docs.python.org/3/builtins/functions.html#int](https://docs.python.org/3/builtins/functions.html#int))

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

Methods Summary 💖

  • configure() — Configure and setup a device object.
  • create([dtype, device_id]) — Create a device object.
  • destroy() — Destroy a device object.
  • getDeviceId() — Return the device id.
  • getDeviceType() — Return the type of the device.
  • setDefaultType(device_type) — Set the device type to be used as the default in subsequent calls to create.
  • view([viewer]) — View a device object.

Attributes Summary ✨

  • device_id — The device id.
  • type — The device type.

Methods Documentation 🌸

configure()

Configure and setup a device object, bestie 🔧

Not collective.

See also:

Source code at petsc4py/PETSc/Device.pyx:132 ([gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Device.pyx#L132](https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Device.pyx#L132))

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

classmethod create(dtype=None, device_id=DECIDE)

Create a device object, slay 💅

Not collective.

Parameters:

Return type: Device ([#petsc4py.PETSc.Device](#petsc4py.PETSc.Device))

See also:

Source code at petsc4py/PETSc/Device.pyx:94 ([gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Device.pyx#L94](https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Device.pyx#L94))

destroy()

Destroy a device object, bye boo 👋

Not collective.

See also:

Source code at petsc4py/PETSc/Device.pyx:120 ([gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Device.pyx#L120](https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Device.pyx#L120))

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

getDeviceId()

Return the device id, no cap 🔢

Not collective.

See also:

Source code at petsc4py/PETSc/Device.pyx:180 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Device.pyx#L180

Return type: int → https://docs.python.org/3/builtins/functions.html#int

getDeviceType()

Bestie. It returns the type of the device. That's the whole thing. So simple, so clean, so iconic. 💅

Not collective. (so like, just your little corner of the universe, no group chat needed)

See also: type, PetscDeviceGetType → https://petsc.org/release/manualpages/Device/PetscDeviceGetType.html

Source code at petsc4py/PETSc/Device.pyx:165 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Device.pyx#L165

Return type: str → https://docs.python.org/3/builtins/stdtypes.html#str

static setDefaultType(device_type)

Okay so this one sets the device type to be used as the default in subsequent calls to create. It's giving "set it and forget it" energy fr fr. ✨

Not collective.

See also: create, PetscDeviceSetDefaultDeviceType → https://petsc.org/release/manualpages/Device/PetscDeviceSetDefaultDeviceType.html

Source code at petsc4py/PETSc/Device.pyx:195 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Device.pyx#L195

Parameters:

Return type: None → https://docs.python.org/3/builtins/constants.html#None

view(viewer=None)

View a device object. It's the "show me what you got" of device methods. 👀

Collective. (so everybody has to show up to this one, no ghosting)

Parameters:

Return type: None → https://docs.python.org/3/builtins/constants.html#None

See also: PetscDeviceView → https://petsc.org/release/manualpages/Device/PetscDeviceView.html

Source code at petsc4py/PETSc/Device.pyx:144 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Device.pyx#L144

Attributes Documentation 🫶

petsc4py.PETSc.DeviceContext

class petsc4py.PETSc.DeviceContext

Bases: Object

DeviceContext object. 🌈

Represents an abstract handle to a device context. It's abstract in the sense that it's a handle, not a vibe — but you already knew that. iykyk.

See also: Device, PetscDeviceContext → https://petsc.org/release/manualpages/Sys/PetscDeviceContext.html

Enumerations:

  • JoinMode — The type of join to perform.
  • StreamType — The type of stream.

petsc4py.PETSc.DeviceContext.JoinMode

class petsc4py.PETSc.DeviceContext.JoinMode

Bases: object → https://docs.python.org/3/builtins/functions.html#object

The type of join to perform. Not a Discord join, bestie — this is the compute kind. 💀

See also: DeviceContext, DeviceContext.join, DeviceContext.fork, PetscDeviceContextJoinMode → https://petsc.org/release/manualpages/Sys/PetscDeviceContextJoinMode.html

Attributes Summary:

Attributes Documentation:

petsc4py.PETSc.DeviceContext.StreamType

class petsc4py.PETSc.DeviceContext.StreamType

Bases: object → https://docs.python.org/3/builtins/functions.html#object

The type of stream. No cap, this is about streams the compute way, not the "watch me play games" way. 🎮

See also: DeviceContext, DeviceContext.getStreamType, DeviceContext.setStreamType, PetscStreamType → https://petsc.org/release/manualpages/Sys/PetscStreamType.html

Attributes Summary:

Attributes Documentation:

and the last few constants on this enum are literally just ints that equal themselves, no notes needed, we love a self-referential king:

  • DEFAULT_WITH_BARRIER: int = DEFAULT_WITH_BARRIER — constant DEFAULT_WITH_BARRIER of type int ✨
  • NONBLOCKING: int = NONBLOCKING — constant NONBLOCKING of type int 💫
  • NONBLOCKING_WITH_BARRIER: int = NONBLOCKING_WITH_BARRIER — constant NONBLOCKING_WITH_BARRIER of type int 🦋

and also chilling on this class:

  • __init__() — the init, doing exactly what an init does 🙈
  • classmethod __new__(*args, **kwargs) — the classmethod constructor, accepts whatever *args and **kwargs you hand it, no questions asked 👑

✨ Methods Summary ✨

okay bestie here's the menu, every method on this class, no skips, we're eating today:

  • create() — create an empty DeviceContext 🎀
  • destroy() — destroy a device context 💥
  • duplicate() — duplicate the device context 💅
  • fork(n[, stream_type]) — create multiple device contexts which are all logically dependent on this one 🌱
  • getCurrent() — return the current device context 🫶
  • getDevice() — get the Device which this instance is attached to 🔌
  • getStreamType() — return the StreamType 🌊
  • idle() — return whether the underlying stream for the device context is idle 😴
  • join(join_mode, py_sub_ctxs) — join a set of device contexts on this one 🧲
  • setCurrent(dctx) — set the current device context 📌
  • setDevice(device) — set the Device which this DeviceContext is attached to 🔗
  • setFromOptions([comm]) — configure the DeviceContext from the options database ⚙️
  • setStreamType(stream_type) — set the StreamType 🌊
  • setUp() — set up the internal data structures for using the device context 🛠️
  • synchronize() — synchronize a device context 🔄
  • waitFor(other) — make this instance wait for other ⏳

🌸 Attributes Summary 🌸

these are the properties, the vibes you can read off the object:

  • current — the current global device context 🌍
  • device — the device associated to the device context 💻
  • stream_type — the stream type 🌊

💖 Methods Documentation 💖

create()

create an empty DeviceContext. that's it. that's the whole job. 🎀

Not collective.

See also: destroy, Device, PetscDeviceContextCreate

Source code at petsc4py/PETSc/Device.pyx:240

Return type: Self — returns itself because of course it does, main character energy 👑

destroy()

destroy a device context. bye bestie, thanks for the memories 💀

Not collective.

See also: create, PetscDeviceContextDestroy

Source code at petsc4py/PETSc/Device.pyx:255

Return type: Self

duplicate()

duplicate the device context. (the original docs say "Duplicate a the device context" and honestly? iconic. we keep the typo, we respect the typo, no cap 🙈)

Not collective.

See also: create, PetscDeviceContextDuplicate

Source code at petsc4py/PETSc/Device.pyx:348

Return type: DeviceContext

fork(n, stream_type=None)

create multiple device contexts which are all logically dependent on this one. like, they're family, they're linked, they know each other 🫶

Not collective.

Parameters:

  • n (int) — the number of device contexts to create 🔢
  • stream_type (StreamType | str | None) — the type of stream of the forked device context 🌊

Returns — list[DeviceContext] 💖 (it's giving "here's your whole lil family of contexts")

Examples ✨

The device contexts you create this way must be destroyed using join. No skipping that step, bestie, or they just vibe there forever 😭

>>> dctx = PETSc.DeviceContext().getCurrent()
>>> dctxs = dctx.fork(4)
>>> ... # perform computations
>>> # we can mix various join modes
>>> dctx.join(PETSc.DeviceContext.JoinMode.SYNC, dctxs[0:2])
>>> dctx.join(PETSc.DeviceContext.JoinMode.SYNC, dctxs[2:])
>>> ... # some more computations and joins
>>> # dctxs must be all destroyed with joinMode.DESTROY
>>> dctx.join(PETSc.DeviceContext.JoinMode.DESTROY, dctxs)

See also: join, waitFor, PetscDeviceContextFork 🔗

📍 source: petsc4py/PETSc/Device.pyx:399

static getCurrent() 🌈

Hands you back the current device context. That's it. That's the whole function.

Not collective — every process just grabs its own, no group chat required 🫶

See also: current, setCurrent, PetscDeviceContextGetCurrentContext

📍 source: petsc4py/PETSc/Device.pyx:519

Returns — DeviceContext ✨

getDevice()

Tells you which Device this instance is attached to. Like, whose GPU is this even, bestie?

Not collective.

See also: setDevice, device, Device, PetscDeviceContextGetDevice

📍 source: petsc4py/PETSc/Device.pyx:302

Returns — Device 🎀

getStreamType()

Returns the StreamType — so you know exactly what flavour of stream we're working with 💅

Not collective.

See also: stream_type, setStreamType, PetscDeviceContextGetStreamType

📍 source: petsc4py/PETSc/Device.pyx:268

Returns — str 🌸

idle()

Answers the question: is the underlying stream for this device context idle? Yes/no, iconic, no notes.

Not collective.

See also: synchronize, PetscDeviceContextQueryIdle

📍 source: petsc4py/PETSc/Device.pyx:363

Returns — bool (so like... True or False, bestie, it's not that deep) 💜

join(join_mode, py_sub_ctxs)

Joins a whole set of device contexts onto this one. The way that this is literally the cleanup crew for your fork — you cannot skip it, periodt 🔥

Not collective.

Parameters

  • join_mode (JoinMode | str) — the type of join to perform.
  • py_sub_ctxs (list[DeviceContext]) — the list of device contexts to join.

Returns — None

See also: fork, waitFor, PetscDeviceContextJoin

📍 source: petsc4py/PETSc/Device.pyx:448

static setCurrent(dctx)

Sets the current device context. You're the main character now, dctx 💅

Not collective.

Parameters

  • dctx (DeviceContext | None) — the DeviceContext to set as current (or None to use the default context). Yep, you can pass None and get the default one back, no drama 🫶

Returns — None

See also: current, getCurrent, PetscDeviceContextSetCurrentContext

📍 source: petsc4py/PETSc/Device.pyx:535

setDevice(device)

Attaches this DeviceContext to a Device. Pick your device, claim it, make it yours ✨

Collective — so everybody's gotta be on the same page here, fr fr. No rogue processes deciding their own device.

Parameters

  • device (Device) — the Device to which this instance is attached to.

Returns — None

See also: getDevice, device, Device, PetscDeviceContextSetDevice

📍 source: petsc4py/PETSc/Device.pyx:317

setFromOptions(comm=None)

Configures the DeviceContext from the options database. So all those -options you sprinkled into your command line actually do something 🎀

Collective.

Parameters

  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm. Leave it blank and it'll just pick the default, lowkey convenient.

Returns — None

See also: Sys.getDefaultComm, PetscDeviceContextSetFromOptions

📍 source: petsc4py/PETSc/Device.pyx:500

setStreamType(stream_type)

Sets the StreamType. Declare your stream type and commit to it, bestie 💅

Not collective.

Parameters

  • stream_type (StreamType | str) — the type of stream to set.

Returns — None

See also: stream_type, getStreamType, PetscDeviceContextSetStreamType

📍 source: petsc4py/PETSc/Device.pyx:283

setUp()

Builds out the internal data structures so the device context can actually do stuff. The behind-the-scenes glow-up before the performance 🌟

Not collective.

See also: create, PetscDeviceContextSetUp

📍 source: petsc4py/PETSc/Device.pyx:336

Returns — None

synchronize()

Synchronizes a device context. Everything catches up, nobody's left behind 🧚

Not collective.

Notes 📝

Once this routine returns, the underlying stream is considered idle — meaning idle will return True. So if you were wondering, yes, that's the vibe check passing ✔️

See also: idle, PetscDeviceContextSynchronize

📍 source: petsc4py/PETSc/Device.pyx:483

Returns — None

  • waitFor(other) — makes this instance sit patiently and wait for other to catch up. 💅

Not collective, bestie — no group project energy here, it's just your two contexts doing their thing. 🙈

Parameters

  • other (DeviceContext | None) — the other DeviceContext that we're waiting on. Yes, None is allowed, no I will not be explaining why, that's just what the type says. 😭

Return type

  • None

See also: fork, join, PetscDeviceContextWaitForContext

Source code at petsc4py/PETSc/Device.pyx:378 ✨

Attributes Documentation 🌸

  • current — the current global device context. Like. THE one. The main character of device contexts. 👑

Source code at petsc4py/PETSc/Device.pyx:574

  • device — the device associated to the device context. It's giving "which device am I even on" but make it an attribute. 🦋

Source code at petsc4py/PETSc/Device.pyx:566

  • stream_type — the stream type. That's it, that's the descriptor. Short and iconic. 💅

Source code at petsc4py/PETSc/Device.pyx:558

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

🧚 petsc4py.PETSc.DualSpace 🧚

class petsc4py.PETSc.DualSpace

Bases: Object

Bestie. It's literally the dual space to a linear space. Math said "what if we did it again but dual" and here we are. 🌈

Enumerations

  • Type — the dual space types.

🌟 petsc4py.PETSc.DualSpace.Type 🌟

class petsc4py.PETSc.DualSpace.Type

Bases: object

The dual space types. The whole menu, if you will. 🎀

Attributes Summary 🍓

  • BDM — object BDM of type str
  • LAGRANGE — object LAGRANGE of type str
  • REFINED — object REFINED of type str
  • SIMPLE — object SIMPLE of type str

Attributes Documentation 💖

  • BDM: str = BDM — object BDM of type str
  • LAGRANGE: str = LAGRANGE — object LAGRANGE of type str
  • REFINED: str = REFINED — object REFINED of type str
  • SIMPLE: str = SIMPLE — object SIMPLE of type str
  • __init__()
  • classmethod __new__(*args, **kwargs)

✨ Methods Summary ✨

okay bestie, here's the whole menu of what you can do with a DualSpace — no cap, every single one is listed 💅

  • create([comm]) — spin up a brand new, totally empty DualSpace object ✨
  • destroy() — yeet that DualSpace into the void 💀
  • duplicate() — make a copy of a DualSpace, but it's not set up yet, so it's just a vibe 🦋
  • getDM() — hand you the DM that represents the reference cell of a DualSpace 🎀
  • getDimension() — tell you how big the dual space is, dimension-wise 📏
  • getFunctional(i) — give you the i-th basis functional in the dual space, like it's a lil collectible 🌸
  • getInteriorDimension() — reveal the interior dimension of the dual space, the inside scoop 🕵️‍♀️
  • getLagrangeContinuity() — say whether the element is continuous or not, yes or no bestie 💖
  • getLagrangeTensor() — spill the tensor nature of the dual space, is it tensor-y? 🔥
  • getLagrangeTrimmed() — tell you if the dual space is trimmed, like a lil haircut ✂️
  • getNumComponents() — how many components does this space have? let's count 👑
  • getNumDof() — number of degrees of freedom for each spatial dimension, the freedom count 🌈
  • getOrder() — what's the order of the dual space? ranking time ⭐
  • getType() — what type is this dual space object? identity check 💅
  • setDM(dm) — set the DM that represents the reference cell, you're in charge 🫶
  • setLagrangeContinuity(continuous) — tell it whether the element is continuous, set the vibe 😭
  • setLagrangeTensor(tensor) — set the tensor nature of the dual space, make it tensor or not 🔥
  • setLagrangeTrimmed(trimmed) — set the trimmed nature, trim it up ✂️
  • setNumComponents(nc) — set how many components this space has, you decide 👑
  • setOrder(order) — set the order of the dual space, level up 🌈
  • setSimpleDimension(dim) — set the number of functionals in the dual space basis, simple as that ⭐
  • setSimpleFunctional(func, functional) — set the given basis element for this dual space, plug it in 💅
  • setType(dualspace_type) — build a particular type of dual space, choose your fighter 🎀
  • setUp() — construct a basis for a DualSpace, get it ready 🌸
  • view([viewer]) — view a DualSpace, take a lil look 👀

💖 Methods Documentation 💖

create(comm=None)

okay so this one creates an empty DualSpace object, bestie. it's giving blank canvas ✨

Collective.

after you make it, you can set its type with setType, periodt.

Parameters

  • comm (Comm or None) — MPI communicator, defaults to Sys.getDefaultComm. like, if you don't pass one, it'll use the default comm, no biggie 🫶

Return type

  • Self — it returns itself, main character energy 👑

See also:

Source code at petsc4py/PETSc/Space.pyx:594 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L594>

destroy()

this one destroys the DualSpace object. bye bye, it's over 💀

Collective.

See also:

(…this next little bit is the tail end of the method from the last part, bestie — it's already mid-sentence so just vibe with it ✨)

Source code at petsc4py/PETSc/Space.pyx:636: https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L636

Return type : Self (https://docs.python.org/3/library/typing.html#typing.Self)

duplicate()

Create a duplicate DualSpace object that is not set up. Like, it exists, it's cute, but it's not ready yet 🫶

Collective. (so everybody has to show up for it, no lurking)

See also:

Source code at petsc4py/PETSc/Space.pyx:649: https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L649

Return type : DualSpace (see #petsc4py.PETSc.DualSpace)

getDM()

Hands you back the DM (see #petsc4py.PETSc.DM) that represents the reference cell of a DualSpace. It's giving "here's the blueprint of your cell" 💅

Not collective. (just you, bestie)

See also:

Source code at petsc4py/PETSc/Space.pyx:662: https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L662

Return type : DM (see #petsc4py.PETSc.DM)

getDimension()

Returns the dimension of the dual space. No cap, that's literally just the number of basis functionals 🔢✨

Not collective.

The dimension of the dual space, i.e. the number of basis functionals.

See also:

Source code at petsc4py/PETSc/Space.pyx:696: https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L696

Return type : int (https://docs.python.org/3/builtins/functions.html#int)

getFunctional(i)

Gives you the i-th basis functional chillin' in the dual space — main character of index i 👑

Not collective.

Parameters

Return type : Quad (see #petsc4py.PETSc.Quad)

See also:

Source code at petsc4py/PETSc/Space.pyx:826: https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L826

getInteriorDimension()

The interior dimension of the dual space, bestie. That's the number of basis functionals assigned to the interior of the reference domain — the ones that live inside the vibe, not on the edges 🦋

Not collective.

See also:

Source code at petsc4py/PETSc/Space.pyx:847: https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L847

Return type : int (https://docs.python.org/3/builtins/functions.html#int)

getLagrangeContinuity()

Tells you whether the element is continuous or not. Yes/no, icon or not-icon 💖

Not collective.

See also:

Source code at petsc4py/PETSc/Space.pyx:864: https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L864

Return type : bool (https://docs.python.org/3/builtins/functions.html#bool)

getLagrangeTensor()

Returns the tensor nature of the dual space. Is it tensoring? Find out ✨

Not collective.

See also:

Source code at petsc4py/PETSc/Space.pyx:896: https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L896

Return type : bool (https://docs.python.org/3/builtins/functions.html#bool)

getLagrangeTrimmed()

Returns the trimmed nature of the dual space. Trimmed, like a perfectly edited fit 🎀

Not collective.

See also:

Source code at petsc4py/PETSc/Space.pyx:928: https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L928

Return type : bool (https://docs.python.org/3/builtins/functions.html#bool)

getNumComponents()

How many components does this space have? Counting them like they're friendship bracelets 🍓

Not collective.

See also:

Source code at petsc4py/PETSc/Space.pyx:712: https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L712

Return type : int (https://docs.python.org/3/builtins/functions.html#int)

getNumDof()

Sends back the number of degrees of freedom for each spatial dimension. Multiple numbers, one per dimension, as an array — she's versatile 💅

Not collective.

See also:

Source code at petsc4py/PETSc/Space.pyx:810: https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L810

Return type : ArrayInt (see #petsc4py.typing.ArrayInt)

getOrder()

Returns the order of the dual space. Yes, order, as in the polynomial order — not the order you'd place at the drive-thru 🌸

Not collective.

See also:

Source code at petsc4py/PETSc/Space.pyx:778: https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L778

Return type : int (https://docs.python.org/3/builtins/functions.html#int)

getType()

Returns the type of the dual space object, as a string. Name-drop it 📛✨

Not collective.

See also:

Source code at petsc4py/PETSc/Space.pyx:744: https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L744

Return type : str (https://docs.python.org/3/builtins/stdtypes.html#str)

setDM(dm)

Sets the DM (see #petsc4py.PETSc.DM) that represents the reference cell. You're handing over the reference cell, that's the whole assignment 🫡

Not collective.

Parameters

  • dm (DM, see #petsc4py.PETSc.DM) — The reference cell.

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

See also:

Source code at petsc4py/PETSc/Space.pyx:679: https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L679

setLagrangeContinuity(continuous)

Marks whether the element is continuous. You're the one deciding the continuity flag, so use your power wisely 😌

Not collective.

Parameters

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

See also:

Source code at petsc4py/PETSc/Space.pyx:878: https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L878

setLagrangeTensor(tensor)

Sets the tensor nature of the dual space. It's a whole toggle, okay, and you're flipping it 🌈

Not collective.

Parameters

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

See also:

Source code at petsc4py/PETSc/Space.pyx:910 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L910 ✨

setLagrangeTrimmed(trimmed) 🎀

Okay so this one sets the trimmed nature of the dual space. Iconic behavior.

Not collective — no group chat needed.

Parameters

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

See also: getLagrangeTrimmed, PetscDualSpaceLagrangeSetTrimmed (https://petsc.org/release/manualpages/DUALSPACE/PetscDualSpaceLagrangeSetTrimmed.html)

Source code at petsc4py/PETSc/Space.pyx:942 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L942 💖

setNumComponents(nc) 🧚

Set the number of components for this space. Component era fr fr.

Logically collective — everyone’s on the same page bestie.

Parameters

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

See also: getNumComponents, PetscDualSpaceSetNumComponents (https://petsc.org/release/manualpages/DUALSPACE/PetscDualSpaceSetNumComponents.html)

Source code at petsc4py/PETSc/Space.pyx:726 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L726 🌸

setOrder(order) 🦋

Set the order of the dual space. Order up, no cap.

Not collective — no group chat needed.

Parameters

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

See also: getOrder, PetscDualSpaceSetOrder (https://petsc.org/release/manualpages/DUALSPACE/PetscDualSpaceSetOrder.html)

Source code at petsc4py/PETSc/Space.pyx:792 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L792 ✨

setSimpleDimension(dim) 💅

Set the number of functionals in the dual space basis. Functional queen energy.

Logically collective — everyone’s on the same page bestie.

Parameters

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

See also: PetscDualSpaceSimpleSetDimension (https://petsc.org/release/manualpages/DUALSPACE/PetscDualSpaceSimpleSetDimension.html)

Source code at petsc4py/PETSc/Space.pyx:962 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L962 🎀

setSimpleFunctional(func, functional) 🔥

Set the given basis element for this dual space. Basis baddie moment.

Not collective — no group chat needed.

Parameters

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

See also: PetscDualSpaceSimpleSetFunctional (https://petsc.org/release/manualpages/DUALSPACE/PetscDualSpaceSimpleSetFunctional.html)

Source code at petsc4py/PETSc/Space.pyx:980 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L980 💜

setType(dualspace_type) 🌈

Build a particular type of dual space. Type reveal, main character energy.

Collective — whole squad assembly required.

Parameters

Return type: Self

See also: getType, PetscDualSpaceSetType (https://petsc.org/release/manualpages/DUALSPACE/PetscDualSpaceSetType.html)

Source code at petsc4py/PETSc/Space.pyx:758 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L758 ⭐

setUp() 🫶

Construct a basis for a DualSpace. Basis construction era.

Collective — whole squad assembly required.

See also: PetscDualSpaceSetUp (https://petsc.org/release/manualpages/DUALSPACE/PetscDualSpaceSetUp.html)

Source code at petsc4py/PETSc/Space.pyx:582 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L582 💖

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

view(viewer=None) 🌸

View a DualSpace. Show it off, you know you want to.

Collective — whole squad assembly required.

Parameters

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

See also: PetscDualSpaceView (https://petsc.org/release/manualpages/DUALSPACE/PetscDualSpaceView.html)

Source code at petsc4py/PETSc/Space.pyx:617 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L617 🦋

__init__() 🎀

classmethod __new__(*args, **kwargs) 💫

petsc4py.PETSc.FE 👑

class petsc4py.PETSc.FE

Bases: Object (#petsc4py.PETSc.Object)

A PETSc object that manages a finite element space. Lowkey iconic.

Enumerations

  • Type (petsc4py.PETSc.FE.Type) — The finite element types.

petsc4py.PETSc.FE.Type 🧚

class petsc4py.PETSc.FE.Type

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

The finite element types. Type taxonomy slay.

Attributes Summary

Attributes Documentation

BASIC: str (https://docs.python.org/3/builtins/stdtypes.html#str) = BASIC : Object BASIC of type str (https://docs.python.org/3/builtins/stdtypes.html#str)

COMPOSITE: str (https://docs.python.org/3/builtins/stdtypes.html#str) = COMPOSITE : Object COMPOSITE of type str (https://docs.python.org/3/builtins/stdtypes.html#str)

OPENCL: str (https://docs.python.org/3/builtins/stdtypes.html#str) = OPENCL : Object OPENCL of type str (https://docs.python.org/3/builtins/stdtypes.html#str)

__init__() 💅

classmethod __new__(*args, **kwargs) ✨

💅 Methods Summary (the whole lineup, bestie)

So this is literally every method you can call on an FE object, and yes I'm listing all of them because we don't skip here. 💖

  • create([comm]) — Create an empty FE object.
  • createByCell(dim, nc, ctype[, qorder, ...]) — Create a FE for basic FEM computation.
  • createDefault(dim, nc, isSimplex[, qorder, ...]) — Create a FE for basic FEM computation.
  • createLagrange(dim, nc, isSimplex, k[, ...]) — Create a FE for the basic Lagrange space of degree k.
  • destroy() — Destroy the FE object.
  • getBasisSpace() — Return the Space used for the approximation of the FE solution.
  • getDimension() — Return the dimension of the finite element space on a cell.
  • getDualSpace() — Return the DualSpace used to define the inner product for the FE.
  • getFaceQuadrature() — Return the Quad used to calculate inner products on faces.
  • getNumComponents() — Return the number of components in the element.
  • getNumDof() — Return the number of DOFs.
  • getQuadrature() — Return the Quad used to calculate inner products.
  • getSpatialDimension() — Return the spatial dimension of the element.
  • getTileSizes() — Return the tile sizes for evaluation.
  • setBasisSpace(sp) — Set the Space used for the approximation of the solution.
  • setDualSpace(dspace) — Set the DualSpace used to define the inner product.
  • setFaceQuadrature(quad) — Set the Quad used to calculate inner products on faces.
  • setFromOptions() — Set parameters in a FE from the options database.
  • setNumComponents(comp) — Set the number of field components in the element.
  • setQuadrature(quad) — Set the Quad used to calculate inner products.
  • setTileSizes(blockSize, numBlocks, ...) — Set the tile sizes for evaluation.
  • setType(fe_type) — Build a particular FE.
  • setUp() — Construct data structures for the FE after the Type has been set.
  • view([viewer]) — View a FE object.

📖 Methods Documentation 📖 (the receipts, one by one)

🌸 create(comm=None)

Create an empty FE object.

Collective. 👑 (yes bestie, everybody in the MPI gang has to show up for this one)

The type can then be set with setType.

Parameters

  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type

  • Self

See also:

setType, PetscFECreate

Source code at petsc4py/PETSc/FE.pyx:53

https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/FE.pyx#L53

🦋 createByCell(dim, nc, ctype, qorder=DETERMINE, prefix=None, comm=None)

Create a FE for basic FEM computation.

Collective. ✨ (we move as a team, periodt)

Parameters

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

See also: PetscFECreateByCell <https://petsc.org/release/manualpages/FE/PetscFECreateByCell.html>

Source code at petsc4py/PETSc/FE.pyx:122 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/FE.pyx#L122>

✨ createDefault(dim, nc, isSimplex, qorder=DETERMINE, prefix=None, comm=None) ✨

Okay so this one is literally the main-character builder 🎀 — it creates a FE for basic FEM computation. That's the whole vibe.

Collective. (everyone's invited, no solo runs 💅)

Parameters

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

See also: PetscFECreateDefault <https://petsc.org/release/manualpages/FE/PetscFECreateDefault.html>

Source code at petsc4py/PETSc/FE.pyx:76 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/FE.pyx#L76>

🌸 createLagrange(dim, nc, isSimplex, k, qorder=DETERMINE, comm=None) 🌸

Not to be dramatic but this creates a FE for the basic Lagrange space of degree k and it ate. 💅

Collective.

Parameters

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

See also: PetscFECreateLagrange <https://petsc.org/release/manualpages/FE/PetscFECreateLagrange.html>

Source code at petsc4py/PETSc/FE.pyx:168 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/FE.pyx#L168>

💀 destroy() 💀

Bestie this is the goodbye button 😭 — it destroys the FE object. It served its purpose, we're letting it go.

Collective.

See also: PetscFEDestroy <https://petsc.org/release/manualpages/FE/PetscFEDestroy.html>

Source code at petsc4py/PETSc/FE.pyx:40 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/FE.pyx#L40>

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

🦋 getBasisSpace() 🦋

Hands you back the Space <#petsc4py.PETSc.Space> that's used to approximate the FE solution. That's it. That's the vibe.

Not collective.

See also: setBasisSpace, PetscFEGetBasisSpace <https://petsc.org/release/manualpages/FE/PetscFEGetBasisSpace.html>

Source code at petsc4py/PETSc/FE.pyx:433 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/FE.pyx#L433>

Return type: Space <#petsc4py.PETSc.Space>

✨ getDimension() ✨

Spits out the dimension of the finite element space on a cell. No notes. 👑

Not collective.

See also: PetscFEGetDimension <https://petsc.org/release/manualpages/FE/PetscFEGetDimension.html>

Source code at petsc4py/PETSc/FE.pyx:227 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/FE.pyx#L227>

Return type: int <https://docs.python.org/3/builtins/functions.html#int>

🌈 getDualSpace() 🌈

Returns the DualSpace <#petsc4py.PETSc.DualSpace> that's used to define the inner product for the FE. Fragile, important, iconic.

Not collective.

See also: setDualSpace, DualSpace <#petsc4py.PETSc.DualSpace>, PetscFEGetDualSpace <https://petsc.org/release/manualpages/FE/PetscFEGetDualSpace.html>

Source code at petsc4py/PETSc/FE.pyx:489 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/FE.pyx#L489>

Return type: DualSpace <#petsc4py.PETSc.DualSpace>

🎀 getFaceQuadrature() 🎀

Gives you the Quad <#petsc4py.PETSc.Quad> that's used to calculate inner products on faces, aka the face routine. ✨

Not collective.

See also: setFaceQuadrature, PetscFEGetFaceQuadrature <https://petsc.org/release/manualpages/FE/PetscFEGetFaceQuadrature.html>

Source code at petsc4py/PETSc/FE.pyx:362 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/FE.pyx#L362>

Return type: Quad <#petsc4py.PETSc.Quad>

💖 getNumComponents() 💖

Tells you how many components are chillin' in the element. Short, sweet, slays.

Not collective.

See also: setNumComponents, PetscFEGetNumComponents <https://petsc.org/release/manualpages/FE/PetscFEGetNumComponents.html>

Source code at petsc4py/PETSc/FE.pyx:255 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/FE.pyx#L255>

Return type: int <https://docs.python.org/3/builtins/functions.html#int>

🌸 getNumDof() 🌸

Returns the number of DOFs. Not the whole story though — it's the number of DOFs (dual basis vectors) associated with mesh points on the reference cell of a given dimension. Lowkey specific but okay bestie we respect it. 💅

Not collective.

See also: PetscFEGetNumDof <https://petsc.org/release/manualpages/FE/PetscFEGetNumDof.html>

Source code at petsc4py/PETSc/FE.pyx:287 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/FE.pyx#L287>

Return type: ndarray <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray>

💜 getQuadrature() 💜

Hands back the Quad <#petsc4py.PETSc.Quad> that's used to calculate inner products. The origin story. 🫶

Not collective.

See also: setQuadrature, PetscFEGetQuadrature <https://petsc.org/release/manualpages/FE/PetscFEGetQuadrature.html>

Source code at petsc4py/PETSc/FE.pyx:212 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/FE.pyx#L212>

Return type: Quad <#petsc4py.PETSc.Quad>

⭐ getSpatialDimension() ⭐

Returns the spatial dimension of the element. Yes bestie, just the dimension. No cap.

Not collective.

See also: PetscFEGetSpatialDimension <https://petsc.org/release/manualpages/FE/PetscFEGetSpatialDimension.html>

Return type is just a lil int. Cute. Source lives at petsc4py/PETSc/FE.pyx:241.

getTileSizes()

Grab those tile sizes for evaluation. So satisfying when you get them right. 💅

Not collective bestie — one lil process does its own thing here, no group chat required.

Returns a whole lil tuple of ints:

  • blockSize (int) — how many elements are chillin' in a block
  • numBlocks (int) — how many blocks are stacked in a batch
  • batchSize (int) — how many elements are in a batch
  • numBatches (int) — how many batches make up a chunk

Return type: tuple[int, int, int, int] — yes all four, slay 🦋

See also: setTileSizes, PetscFEGetTileSizes

Source code at petsc4py/PETSc/FE.pyx:306

setBasisSpace(sp)

Set the Space used for approximating the solution. Iconic.

Not collective.

Parameters:

  • sp (Space) — the Space object you're handing over

Return type: None

See also: getBasisSpace, PetscFESetBasisSpace

Source code at petsc4py/PETSc/FE.pyx:448

setDualSpace(dspace)

Set the DualSpace that defines the inner product. The way it just... does that. Obsessed 💖

Not collective.

Parameters:

  • dspace (DualSpace) — the DualSpace object

Return type: None

See also: getDualSpace, DualSpace, PetscFESetDualSpace

Source code at petsc4py/PETSc/FE.pyx:504

setFaceQuadrature(quad)

Set the Quad used to calculate inner products on faces. Face-coded, literally. ✨

Not collective.

Parameters:

  • quad (Quad) — the Quad object

Return type: Quad

See also: getFaceQuadrature, PetscFESetFaceQuadrature

Source code at petsc4py/PETSc/FE.pyx:395

setFromOptions()

Set parameters in a FE straight from the options database. Pulling the vibes from config.

Collective. So like, everyone has to be here for it, no ghosting. 👑

See also: Working with PETSc options, PetscFESetFromOptions

Source code at petsc4py/PETSc/FE.pyx:465

Return type: None

setNumComponents(comp)

Set how many field components live in the element. A whole squad.

Not collective.

Parameters:

  • comp (int) — the number of field components

Return type: None

See also: getNumComponents, PetscFESetNumComponents

Source code at petsc4py/PETSc/FE.pyx:269

setQuadrature(quad)

Set the Quad used to calculate inner products. Main character Quad. 🌸

Not collective.

Parameters:

  • quad (Quad) — the Quad object

Return type: Self

See also: getQuadrature, PetscFESetQuadrature

Source code at petsc4py/PETSc/FE.pyx:377

setTileSizes(blockSize, numBlocks, batchSize, numBatches)

Set the tile sizes for evaluation. Fiddly but worth it fr fr.

Not collective.

Parameters:

  • blockSize (int) — the number of elements in a block
  • numBlocks (int) — the number of blocks in a batch
  • batchSize (int) — the number of elements in a batch
  • numBatches (int) — the number of batches in a chunk

Return type: None

See also: getTileSizes, PetscFESetTileSizes

Source code at petsc4py/PETSc/FE.pyx:332

setType(fe_type)

Build a particular FE. Make it, bestie. 💅

Collective.

Parameters:

  • fe_type (Type | str) — the kind of FEM space

Return type: Self

See also: PetscFESetType

Source code at petsc4py/PETSc/FE.pyx:413

setUp()

Construct the data structures for the FE — but only after the Type has been set. So like, set your Type first or this is giving nothing.

Collective.

See also: PetscFESetUp

Source code at petsc4py/PETSc/FE.pyx:477

Return type: None

view(viewer=None)

View a FE object. Let it be seen, periodt. ✨

Collective.

Parameters:

  • viewer (Viewer | None) — a Viewer to display the graph

Return type: None

See also: PetscFEView

Source code at petsc4py/PETSc/FE.pyx:21

__init__()

classmethod __new__(*args, **kwargs)

petsc4py.PETSc.IS

class petsc4py.PETSc.IS

Bases: Object

A collection of indices. That's it, that's the whole thing — a lil roster of index numbers. 🎀

IS objects are used to index into vectors and matrices, and to set up vector scatters. So they're like the backstage pass that tells everyone which entries they're allowed to touch. Iconic and lowkey essential. 🦋

See Also 🔗

ok so before we fully dive in, the docs are like "hey bestie, also go look at this":

Enumerations ✨

There's exactly one enum in this little corner of the IS world, and it's serving:

  • Type — literally just The index set types. that's it, that's the whole summary 🫶

petsc4py.PETSc.IS.Type

class petsc4py.PETSc.IS.Type

Bases: object (yes, the plain ol' Python one — https://docs.python.org/3/builtins/functions.html#object)

The index set types. No notes. She's a container of constants and she's thriving 💅

Attributes Summary 🎀

lowkey a tiny list but it's iconic, here's the whole roster:

  • BLOCK — Object BLOCK of type str
  • GENERAL — Object GENERAL of type str
  • STRIDE — Object STRIDE of type str

and yes bestie, every single one of those str types points at the exact same place: https://docs.python.org/3/builtins/stdtypes.html#str 🌸

Attributes Documentation 💖

okay now the receipts, one by one, in order, no skipping:

  • BLOCK
BLOCK: str = BLOCK

Object BLOCK of type str (https://docs.python.org/3/builtins/stdtypes.html#str) — it's a string, it's named BLOCK, the vibes are immaculate, the name matches the value fr fr ✨

  • GENERAL
GENERAL: str = GENERAL

Object GENERAL of type str (https://docs.python.org/3/builtins/stdtypes.html#str) — the most main character energy type of the trio, ngl 👑

  • STRIDE
STRIDE: str = STRIDE

Object STRIDE of type str (https://docs.python.org/3/builtins/stdtypes.html#str) — striding in, saying exactly what it is on the label, we love transparency 🌈

no cap, notice how each one is literally a str and its value is literally the same string as its name — like a little name tag that matches the outfit. that's the pattern, that's the whole pattern ✅

Methods 🦋

and then the two dunder girlies everyone inherits:

__init__()

the classic constructor moment — nothing extra documented here, she just exists, let her live 🙈

classmethod __new__(*args, **kwargs)

a classmethod, called as __new__(*args, **kwargs) — takes whatever *args and **kwargs you throw at her, because she's flexible like that 💜

and that's the IS.Type era, but we are so not done — the IS universe keeps unfolding, so stay tuned bestie, next part's gonna eat too 🍓

and the roster just keeps going, bestie 💖 no skips, no shortcuts, we're listing every single one:

  • allGather() — concatenates index sets that are stored across your processors, so everybody's little pieces get stitched into one. ✨
  • buildTwoSided([toindx]) — creates an index set that describes a global mapping.
  • complement(nmin, nmax) — creates a complement index set. 🌸
  • copy([result]) — copies the contents of the index set into another one.
  • create([comm]) — creates an IS. the origin story 🫶
  • createBlock(bsize, indices[, comm]) — creates a blocked index set.
  • createGeneral(indices[, comm]) — creates an IS with indices.
  • createStride(size[, first, step, comm]) — creates an index set made up of evenly spaced values.
  • destroy() — destroys the index set. it's giving closure 💅
  • difference(iset) — returns the difference between two index sets.
  • duplicate() — creates a copy of the index set.
  • embed(iset, drop) — embeds self into iset.
  • equal(iset) — returns whether the index sets have the same set of indices or not. simple yes/no, no drama 🌈
  • expand(iset) — returns the union of two (possibly unsorted) index sets.
  • getBlockIndices() — returns the indices of an index set with type IS.Type.BLOCK.
  • getBlockSize() — returns the number of elements in a block.
  • getIndices() — returns the indices of the index set. the main character reveal ✨
  • getInfo() — returns stride information for an index set with type IS.Type.STRIDE.
  • getLocalSize() — returns the process-local length of the index set.
  • getSize() — returns the global length of an index set.
  • getSizes() — returns the local and global sizes of the index set. both, because you deserve options 💖
  • getStride() — returns size and stride information.
  • getType() — returns the index set type associated with the IS.
  • intersect(iset) — returns the intersection of two index sets.
  • invertPermutation([nlocal]) — inverts the index set.
  • isIdentity() — returns whether the index set has been declared as an identity.
  • isPermutation() — returns whether an index set has been declared to be a permutation.
  • isSorted() — returns whether the indices have been sorted. vibe check on the ordering 👑
  • load(viewer) — loads a stored index set.
  • partitioningCount([npart]) — returns the number of elements per process after a partitioning.
  • partitioningToNumbering() — returns the new global numbering after a partitioning. 🦋

and yes we're still in the same list, stay with me 💜

  • renumber([mult]) — Renumber the non-negative entries of an index set, starting from 0. 💫
  • setBlockIndices(bsize, indices) — Set the indices for an index set with type IS.Type.BLOCK.
  • setBlockSize(bs) — Set the block size of the index set.
  • setIdentity() — Mark the index set as being an identity. 🪞
  • setIndices(indices) — Set the indices of an index set.
  • setPermutation() — Mark the index set as being a permutation. 🔀
  • setStride(size[, first, step]) — Set the stride information for an index set with type IS.Type.STRIDE.
  • setType(is_type) — Set the type of the index set.
  • sort() — Sort the indices of an index set. 📊
  • sum(iset) — Return the union of two (sorted) index sets.
  • toGeneral() — Convert the index set type to IS.Type.GENERAL.
  • union(iset) — Return the union of two (possibly unsorted) index sets.
  • view([viewer]) — Display the index set. 👀

✨ Attributes Summary ✨

okay bestie this next lil table is literally just the vibes of an index set — all the read-only-ish properties you can peek at. lowkey the best part 🫶

💅 METHODS DOCUMENTATION 💅

and now the main character section: every method, full lore, no skips. 🎀

allGather()

Concatenate index sets stored across processors.

Collective. 🌐 — like, everybody has to show up for this one, no ghosting.

The returned index set will be the same on every processor. slay, consistency. ✨

See also: ISAllGather — https://petsc.org/release/manualpages/IS/ISAllGather.html

Source code at petsc4py/PETSc/IS.pyx:304 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L304

Return type IS

buildTwoSided(toindx=None)

Create an index set describing a global mapping.

Collective. 🌐 — yeah, group project energy, everyone's involved.

This function generates an index set that contains new numbers from remote or local on the index set.

Parameters toindx (IS | None (https://docs.python.org/3/builtins/constants.html#None)) — Index set describing which indices to send, default is to send natural numbering.

Returns New index set containing the new numbers from remote or local.

Return type IS

See also: ISBuildTwoSided — https://petsc.org/release/manualpages/IS/ISBuildTwoSided.html

Source code at petsc4py/PETSc/IS.pyx:333 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L333

complement(nmin, nmax)

Create a complement index set.

Collective. 🌐 — yep, again, everybody in the chat ✋

The complement set of indices is all indices that are not in the provided set (and within the provided bounds). it's giving "the leftovers, but make it math" 💫

Parameters

  • nmin (int) — the minimum index you can find in the local part of the complement index set.
  • nmax (int) — one greater than the maximum index that can be found in the local part of the complement index set. (yes bestie, it's a "one past the end" situation, classic 💅)

Return type IS <#petsc4py.PETSc.IS>

Notes

So for a parallel index set, this generates the local part of the complement on each process. Every process gets its own lil slice 🍰

Want the entire complement on every process instead? First call IS.allGather, then call this method. That's the move. ✨

See also: IS.allGather, ISComplement <https://petsc.org/release/manualpages/IS/ISComplement.html>

Source code at petsc4py/PETSc/IS.pyx:747 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L747>

copy (result=None)

Copy the contents of the index set into another one. Glow-up but it's a duplicate 🦋

Collective. (everyone participates, no lurking 👀)

Parameters

  • result (IS <#petsc4py.PETSc.IS> | None) — the target index set. If it's None, then IS.duplicate gets called first, no cap.

Returns The copied index set. If result is not None, then that is what gets returned here. 🫶

Return type IS

See also: IS.duplicate, ISCopy <https://petsc.org/release/manualpages/IS/ISCopy.html>

Source code at petsc4py/PETSc/IS.pyx:253 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L253>

create (comm=None)

Make a whole new IS. Fresh out the box 🎁

Collective.

Parameters

  • comm (Comm <#petsc4py.PETSc.Comm> | None) — the MPI communicator, and if you don't say anything it just defaults to Sys.getDefaultComm <#petsc4py.PETSc.Sys.getDefaultComm>.

Return type Self

See also: ISCreate <https://petsc.org/release/manualpages/IS/ISCreate.html>

Source code at petsc4py/PETSc/IS.pyx:88 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L88>

createBlock (bsize, indices, comm=None)

Create a blocked index set. It's giving organized. 💅

Collective.

Parameters

  • bsize (int) — block size.
  • indices (Sequence[int]) — integer array of indices.
  • comm (Comm <#petsc4py.PETSc.Comm> | None) — the MPI communicator, defaults to Sys.getDefaultComm <#petsc4py.PETSc.Sys.getDefaultComm> when you don't pass one.

Return type Self

See also: ISCreateBlock <https://petsc.org/release/manualpages/IS/ISCreateBlock.html>

Source code at petsc4py/PETSc/IS.pyx:171 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L171>

createGeneral (indices, comm=None)

Create an IS with indices. The general-population one, no fancy structure ✨

Collective.

Parameters

  • indices (Sequence[int]) — integer array.
  • comm (Comm <#petsc4py.PETSc.Comm> | None) — the MPI communicator, defaults to Sys.getDefaultComm <#petsc4py.PETSc.Sys.getDefaultComm>.

Return type Self

See also: ISCreateGeneral <https://petsc.org/release/manualpages/IS/ISCreateGeneral.html>

Source code at petsc4py/PETSc/IS.pyx:142 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L142>

createStride (size, first=0, step=1, comm=None)

Create an index set made of evenly spaced values. Think: every step-th number, living its best life. 🌈

Collective.

Parameters

  • size (int) — the length of the locally owned portion of the index set.
  • first (int) — the first element of the index set.
  • step (int) — the difference between adjacent indices.
  • comm (Comm <#petsc4py.PETSc.Comm> | None) — the MPI communicator, defaults to Sys.getDefaultComm <#petsc4py.PETSc.Sys.getDefaultComm>.

Return type Self

See also: ISCreateStride <https://petsc.org/release/manualpages/IS/ISCreateStride.html>

Source code at petsc4py/PETSc/IS.pyx:204 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L204>

destroy ()

Destroy the index set. It's over, bestie, say bye 👋💀

Collective.

See also: ISDestroy <https://petsc.org/release/manualpages/IS/ISDestroy.html>

Source code at petsc4py/PETSc/IS.pyx:75 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L75>

Return type Self

difference (iset)

Return the difference between two index sets. Subtract, but make it mathematical ✂️

Collective.

Parameters

  • iset (IS <#petsc4py.PETSc.IS>) — the index set to compute the difference with.

Returns An index set representing the difference between self and iset.

Return type IS

See also: ISDifference <https://petsc.org/release/manualpages/IS/ISDifference.html>

Source code at petsc4py/PETSc/IS.pyx:723 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L723>

duplicate ()

Create a copy of the index set. Two of them. Twins. Iconic behavior 🎀

Collective.

See also: IS.copy, ISDuplicate <https://petsc.org/release/manualpages/IS/ISDuplicate.html>

Source code at petsc4py/PETSc/IS.pyx:239 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L239>

Return type IS <#petsc4py.PETSc.IS>

embed (iset, drop)

Embed self into iset. Squeeze in, find your seat 🪑

Not collective. (this one flies solo)

The embedding works by finding the locations in iset that have the same indices</scyan> as self.

Parameters

  • iset (IS <#petsc4py.PETSc.IS>) — the index set to embed into.
  • drop (bool) — flag saying whether to drop indices from self that aren't in iset.

Returns The embedded index set.

Return type IS

See also: ISEmbed <https://petsc.org/release/manualpages/IS/ISEmbed.html>

Source code at petsc4py/PETSc/IS.pyx:783 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L783>

equal (iset)

Return whether the index sets have the same set of indices or not. Yes/no, are we the same person? 👯

Collective.

Parameters

  • iset (IS <#petsc4py.PETSc.IS>) — the index set to compare indices with.

Return type bool

See also: ISEqual <https://petsc.org/release/manualpages/IS/ISEqual.html>

expand(iset) 🌸

Return the union of two (possibly unsorted) index sets.

Collective. yeah everyone's in the group chat for this one.

To compute the union, expand concatenates the two index sets and removes any duplicates. that's the whole vibe, no cap.

Parameters

  • iset (IS <#petsc4py.PETSc.IS>) — Index set to compute the union with.

Returns

  • The new, combined, index set. 💖

Return type

  • IS

See also:

Source code at petsc4py/PETSc/IS.pyx:599 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L599>

getBlockIndices() 🎀

Return the indices of an index set with type IS.Type.BLOCK <#petsc4py.PETSc.IS.Type.BLOCK>.

Not collective. this one's a solo mission, bestie.

See also:

Source code at petsc4py/PETSc/IS.pyx:906 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L906>

Return type

  • ArrayInt <#petsc4py.typing.ArrayInt>

getBlockSize() ✨

Return the number of elements in a block.

Not collective.

See also:

Source code at petsc4py/PETSc/IS.pyx:486 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L486>

Return type

getIndices() 🌈

Return the indices of the index set.

Not collective.

See also:

Source code at petsc4py/PETSc/IS.pyx:862 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L862>

Return type

  • ArrayInt <#petsc4py.typing.ArrayInt>

getInfo() 🦋

Return stride information for an index set with type IS.Type.STRIDE <#petsc4py.PETSc.IS.Type.STRIDE>.

Not collective.

Returns

Return type

See also:

Source code at petsc4py/PETSc/IS.pyx:976 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L976>

getLocalSize() 💅

Return the process-local length of the index set.

Not collective.

See also:

Source code at petsc4py/PETSc/IS.pyx:450 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L450>

Return type

getSize() 🌟

Return the global length of an index set.

Not collective.

See also:

Source code at petsc4py/PETSc/IS.pyx:436 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L436>

Return type

getSizes() 😌

Return the local and global sizes of the index set. two-for-one deal, we love to see it.

Not collective.

Returns

Return type

See also:

  • IS.getLocalSize, IS.getSize

Source code at petsc4py/PETSc/IS.pyx:464 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L464>

getStride() 🔥

Return size and stride information.

Not collective.

Returns

Return type

See also:

Source code at petsc4py/PETSc/IS.pyx:952 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L952>

getType() 👑

Return the index set type associated with the IS. like, what kind of IS is this, bestie.

Not collective.

See also:

Source code at petsc4py/PETSc/IS.pyx:128 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L128>

Return type

intersect(iset) 🫶

Return the intersection of two index sets. the overlap, the mutuals, the "we both know each other" energy.

Collective.

Parameters

  • iset (IS <#petsc4py.PETSc.IS>) — Index set to compute the intersection with.

Returns

  • Index set representing the intersection of self and iset.

Return type

  • IS

See also:

Source code at petsc4py/PETSc/IS.pyx:699 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L699>

invertPermutation(nlocal=None) 🔄

Invert the index set. flip it, turn it upside down, main character move.

Collective.

⚠️ For this to be correct the index set must be a permutation. no shortcuts, no cheating, bestie — if it's not a permutation this is not gonna be correct.

Parameters

Return type

  • IS <#petsc4py.PETSc.IS>

See also:

Source code at petsc4py/PETSc/IS.pyx:363 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L363>

isIdentity() 💜

Return whether the index set has been declared as an identity.

Collective.

See also:

Source code at petsc4py/PETSc/IS.pyx:585 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L585>

Return type

isPermutation()

Return whether an index set has been declared to be a permutation.

Logically collective.

See also: ISPermutation (https://petsc.org/release/manualpages/IS/ISPermutation.html)

Source code at petsc4py/PETSc/IS.pyx:558 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L558)

Return type: bool (https://docs.python.org/3/builtins/functions.html#bool) — yeah bestie, that's a whole bool, it's giving yes-or-no and nothing else 💅

isSorted()

So this one asks: are the indices already sorted? That's it, that's the whole vibe. ✨

Collective. (meaning everybody in the communicator has to show up, no ghosting your ranks 🙈)

See also: ISSorted (https://petsc.org/release/manualpages/IS/ISSorted.html)

Source code at petsc4py/PETSc/IS.pyx:531 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L531)

Return type: bool (https://docs.python.org/3/builtins/functions.html#bool) — the classic true/false situation 🎀

load(viewer)

Okay so the way this one loads a stored index set, like pulling your saved game back up. Iconic. 👑

Collective.

Parameters:

  • viewer (Viewer) — Binary file viewer, and it's gotta be either Viewer.Type.BINARY or Viewer.Type.HDF5. No other flavors, she's picky. 💅

Return type: Self (https://docs.python.org/3/library/typing.html#typing.Self) — it literally hands you back yourself, main character behavior fr.

See also: ISLoad (https://petsc.org/release/manualpages/IS/ISLoad.html)

Source code at petsc4py/PETSc/IS.pyx:281 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L281)

partitioningCount(npart=None)

Returns the number of elements per process after a partitioning. Lowkey such a useful little number.

Collective.

So the tea is: assuming that the index set represents a partitioning, this determines the number of elements on each (partition) rank. 🫶

Parameters:

Return type: ArrayInt

See also: ISPartitioningCount (https://petsc.org/release/manualpages/IS/ISPartitioningCount.html)

Source code at petsc4py/PETSc/IS.pyx:404 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L404)

partitioningToNumbering()

Return the new global numbering after a partitioning. It's giving glow-up for your indices. ✨

Collective.

Assuming that the index set represents a partitioning, it generates another index set with the new global node number in the new ordering. So basically a whole new you, but make it numbering. 🦋

See also: ISPartitioningToNumbering (https://petsc.org/release/manualpages/IS/ISPartitioningToNumbering.html)

Source code at petsc4py/PETSc/IS.pyx:387 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L387)

Return type: IS

renumber(mult=None)

Renumber the non-negative entries of an index set, starting from 0. Fresh start, clean slate, no cap. 🌸

Collective.

Parameters:

Returns:

Return type: tuple (https://docs.python.org/3/builtins/stdtypes.html#tuple)[int (https://docs.python.org/3/builtins/functions.html#int), IS]

See also: ISRenumber (https://petsc.org/release/manualpages/IS/ISRenumber.html)

Source code at petsc4py/PETSc/IS.pyx:814 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L814)

setBlockIndices(bsize, indices)

Sets the indices for an index set with type IS.Type.BLOCK. Block party but make it indices. 🧱✨

Collective.

Parameters:

Return type: None (https://docs.python.org/3/builtins/constants.html#None) — nothing comes back, it's a pure vibe-setting move 💜

See also: ISBlockSetIndices (https://petsc.org/release/manualpages/IS/ISBlockSetIndices.html)

Source code at petsc4py/PETSc/IS.pyx:883 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L883)

setBlockSize(bs)

Set the block size of the index set. Short, sweet, does exactly what it says on the tin. 💅

Logically collective.

Parameters:

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

See also: ISSetBlockSize (https://petsc.org/release/manualpages/IS/ISSetBlockSize.html)

Source code at petsc4py/PETSc/IS.pyx:500 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L500)

setIdentity()

Mark the index set as being an identity. She's her, she knows who she is. 👑

Logically collective.

See also: ISSetIdentity (https://petsc.org/release/manualpages/IS/ISSetIdentity.html)

Source code at petsc4py/PETSc/IS.pyx:572 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L572)

Return type: Self (https://docs.python.org/3/library/typing.html#typing.Self) — loops right back to you, iconic behaviior 🎀

setIndices(indices)

Set the indices of an index set. The name really said "I'm gonna tell you exactly what I do" and then did it. 💖

Logically collective.

The index set is assumed to be of type IS.Type.GENERAL. So if yours isn't general-type, that's a whole other conversation, bestie. 🌸

See also: ISGeneralSetIndices (https://petsc.org/release/manualpages/IS/ISGeneralSetIndices.html)

Source code at petsc4py/PETSc/IS.pyx:845 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L845)

Parameters:

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

setPermutation()

Mark the index set as being a permutation. Shuffling but make it official. 🃏

Logically collective.

See also: ISSetPermutation (https://petsc.org/release/manualpages/IS/ISSetPermutation.html)

Source code at petsc4py/PETSc/IS.pyx:545 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L545)

Return type: Self (https://docs.python.org/3/library/typing.html#typing.Self)

setStride(size, first=0, step=1)

Set the stride information for an index set with type IS.Type.STRIDE. Stride girlies, this one's for you. 🦋

Logically collective.

Parameters:

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

See also: ISStrideSetStride (https://petsc.org/release/manualpages/IS/ISStrideSetStride.html)

Source code at petsc4py/PETSc/IS.pyx:928 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L928)

setType(is_type)

Set the type of the index set. Type-checking, but for real and for your indices. 💅

Collective.

Parameters:

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

No cap, that's the whole method. Straight to the point, no notes. ✨

See also: ISSetType → https://petsc.org/release/manualpages/IS/ISSetType.html

Source code at petsc4py/PETSc/IS.pyx:109 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L109

🌟 sort() — bestie, we are SORTING

Sort the indices of an index set. Lowkey the glow-up your indices were waiting for. ✨

Collective. (everybody in the communicator pulls up, no cap 🫶)

See also: ISSort → https://petsc.org/release/manualpages/IS/ISSort.html

Source code at petsc4py/PETSc/IS.pyx:518 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L518

Return type

Self → https://docs.python.org/3/library/typing.html#typing.Self

🦋 sum(iset) — union, but make it sorted

Return the union of two (sorted) index sets. Yes bestie, the inputs gotta be sorted — that's the whole vibe of this one. 💅

Collective.

Parameters

  • iset (IS) — The index set to compute the union with.

Return type

IS

See also: ISSum → https://petsc.org/release/manualpages/IS/ISSum.html

Source code at petsc4py/PETSc/IS.pyx:618 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L618

🎀 toGeneral() — the type glow-down (but make it general)

Convert the index set type to IS.Type.GENERAL. She's going mainstream, periodt. 🌈

Collective.

See also: ISToGeneral → https://petsc.org/release/manualpages/IS/ISToGeneral.html, ISType → https://petsc.org/release/manualpages/IS/ISType.html

Source code at petsc4py/PETSc/IS.pyx:320 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L320

Return type

Self → https://docs.python.org/3/library/typing.html#typing.Self

👑 union(iset) — the chill union

Return the union of two (possibly unsorted) index sets. Not your sorted-only fave — this one's more forgiving, she accepts you as you are. 🫶

Collective.

This function will call either ISSum → https://petsc.org/release/manualpages/IS/ISSum.html or ISExpand → https://petsc.org/release/manualpages/IS/ISExpand.html depending on whether or not the input sets are already sorted.

Sequential only (as ISSum → https://petsc.org/release/manualpages/IS/ISSum.html is sequential only). So like… don't try it with your whole MPI squad, bestie. 😭

Parameters

  • iset (IS) — Index set to compute the union with.

Returns

The new, combined, index set.

Return type

IS

See also: IS.expand, IS.sum

Source code at petsc4py/PETSc/IS.pyx:664 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L664

💜 view(viewer=None) — show her off

Display the index set. Main character moment, honestly. ✨

Collective.

Parameters

  • viewer (Viewer | None) — Viewer used to display the IS.

Return type

None → https://docs.python.org/3/builtins/constants.html#None

See also: ISView → https://petsc.org/release/manualpages/IS/ISView.html

Source code at petsc4py/PETSc/IS.pyx:56 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L56

🌸 Attributes Documentation 🌸

okay so these are the lil' properties, and the way they let you peek at the IS without doing a whole ceremony… obsessed. 💅

  • array — View of the index set as an array of integers.

Not collective.

Source code at petsc4py/PETSc/IS.pyx:1105 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L1105

  • block_size — The number of elements in a block.

Not collective.

See also: IS.getBlockSize

Source code at petsc4py/PETSc/IS.pyx:1079 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L1079

Collective.

See also: IS.isIdentity

Source code at petsc4py/PETSc/IS.pyx:1012 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L1012

  • indices — The indices of the index set.

Not collective.

See also: IS.getIndices

Source code at petsc4py/PETSc/IS.pyx:1092 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L1092

  • local_size — The local size of the index set.

Not collective.

See also: IS.getLocalSize

Source code at petsc4py/PETSc/IS.pyx:1066 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L1066

Logically collective.

See also: IS.isPermutation

Source code at petsc4py/PETSc/IS.pyx:999 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L999

  • size — The global size of the index set.

Not collective.

See also: IS.getSize

Source code at petsc4py/PETSc/IS.pyx:1053 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L1053

  • sizes — The local and global sizes of the index set.

Not collective.

See also: IS.getSizes

Source code at petsc4py/PETSc/IS.pyx:1040 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L1040

Collective.

See also: IS.isSorted

Source code at petsc4py/PETSc/IS.pyx:1025 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L1025

🧚 More dunder magic

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

🍓 petsc4py.PETSc.InsertMode

class petsc4py.PETSc.InsertMode

Bases: object → https://docs.python.org/3/builtins/functions.html#object

Insertion mode. It's giving "how do you wanna put these numbers in, bestie?" 🌈✨

Most commonly used insertion modes are:

  • INSERT — Insert provided value/s discarding previous value/s. Out with the old, in with the new, periodt. 💅
  • ADD — Add provided value/s to current value/s. Teamwork, fr fr. 🫶
  • MAX — Insert the maximum of provided value/s and current value/s. Only the biggest energy allowed. 👑

See also: InsertMode → https://petsc.org/release/manualpages/Sys/InsertMode.html

✨ Attributes Summary ✨

okay bestie, so this class is basically one giant vibe check made entirely of constants, and every single one of them is an int at the end of the day 💅 no cap:

like, fifteen constants, all int, all iconic, all giving "I was typed out by an autodoc generator and I'm thriving" 🌸

📖 Attributes Documentation 📖

okay now we do them one by one, because that's the format and we respect the format 🫶

ADD

ADD: int <https://docs.python.org/3/builtins/functions.html#int> = ADD

Constant ADD of type int — docs at https://docs.python.org/3/builtins/functions.html#int

ADD_ALL

ADD_ALL: int <https://docs.python.org/3/builtins/functions.html#int> = ADD_ALL

Constant ADD_ALL of type int — docs at https://docs.python.org/3/builtins/functions.html#int

ADD_ALL_VALUES

ADD_ALL_VALUES: int <https://docs.python.org/3/builtins/functions.html#int> = ADD_ALL_VALUES

Constant ADD_ALL_VALUES of type int — docs at https://docs.python.org/3/builtins/functions.html#int

ADD_BC

ADD_BC: int <https://docs.python.org/3/builtins/functions.html#int> = ADD_BC

Constant ADD_BC of type int — docs at https://docs.python.org/3/builtins/functions.html#int

ADD_BC_VALUES

ADD_BC_VALUES: int <https://docs.python.org/3/builtins/functions.html#int> = ADD_BC_VALUES

Constant ADD_BC_VALUES of type int — docs at https://docs.python.org/3/builtins/functions.html#int

ADD_VALUES

ADD_VALUES: int <https://docs.python.org/3/builtins/functions.html#int> = ADD_VALUES

Constant ADD_VALUES of type int — docs at https://docs.python.org/3/builtins/functions.html#int

INSERT

INSERT: int <https://docs.python.org/3/builtins/functions.html#int> = INSERT

Constant INSERT of type int — docs at https://docs.python.org/3/builtins/functions.html#int

INSERT_ALL

INSERT_ALL: int <https://docs.python.org/3/builtins/functions.html#int> = INSERT_ALL

Constant INSERT_ALL of type int — docs at https://docs.python.org/3/builtins/functions.html#int

INSERT_ALL_VALUES

INSERT_ALL_VALUES: int <https://docs.python.org/3/builtins/functions.html#int> = INSERT_ALL_VALUES

Constant INSERT_ALL_VALUES of type int — docs at https://docs.python.org/3/builtins/functions.html#int

INSERT_BC

INSERT_BC: int <https://docs.python.org/3/builtins/functions.html#int> = INSERT_BC

Constant INSERT_BC of type int — docs at https://docs.python.org/3/builtins/functions.html#int

INSERT_BC_VALUES

INSERT_BC_VALUES: int <https://docs.python.org/3/builtins/functions.html#int> = INSERT_BC_VALUES

Constant INSERT_BC_VALUES of type int — docs at https://docs.python.org/3/builtins/functions.html#int

INSERT_VALUES

INSERT_VALUES: int <https://docs.python.org/3/builtins/functions.html#int> = INSERT_VALUES

Constant INSERT_VALUES of type int — docs at https://docs.python.org/3/builtins/functions.html#int

MAX

MAX: int <https://docs.python.org/3/builtins/functions.html#int> = MAX

Constant MAX of type int — docs at https://docs.python.org/3/builtins/functions.html#int

MAX_VALUES

MAX_VALUES: int <https://docs.python.org/3/builtins/functions.html#int> = MAX_VALUES

Constant MAX_VALUES of type int — docs at https://docs.python.org/3/builtins/functions.html#int

NOT_SET_VALUES

NOT_SET_VALUES: int <https://docs.python.org/3/builtins/functions.html#int> = NOT_SET_VALUES

Constant NOT_SET_VALUES of type int — docs at https://docs.python.org/3/builtins/functions.html#int

and then, because of course, two little darlings with literally no documentation attached 😭

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

they're there. they exist. they said nothing. slay, I guess 💀

💖 petsc4py.PETSc.KSP 💖

class petsc4py.PETSc.KSP

Bases: Object (that's petsc4py.PETSc.Object, go look at it if you need the lore)

okay so this one is THE abstract PETSc object that manages all the Krylov methods 👑

like, it's the thing that handles your linear solves in PETSc — and yes, even the ones that are direct solvers and don't use Krylov accelerators at all. everyone's welcome in this house, no gatekeeping 💅

📌 Notes

bestie, listen — when a direct solver is used but there's no Krylov solver in the mix, the KSP object is still the one in play, just with a Type.PREONLY (petsc4py.PETSc.KSP.Type.PREONLY). That means the only thing it's actually doing as the linear solver is applying the preconditioner. no Krylov, just PREONLY, and honestly? it ate. ✨

💫 See also: 💫

okay bestie, before we move on, here are the related icons you might wanna peek at:

✨ Enumerations ✨

these are the enum cuties hanging out under KSP, each one doing its own little job 💅

  • ConvergedReason — KSP Converged Reason.
  • DMActive — Argument to KSPSetDMActive().
  • HPDDMType — The HPDDM Krylov solver type.
  • NormType — KSP norm type.
  • Type — KSP Type.

🫧 class petsc4py.PETSc.KSP.ConvergedReason 🫧

Bases: object — yes, it's giving plain old object energy, docs link right here: https://docs.python.org/3/builtins/functions.html#object

KSP Converged Reason.

  • CONVERGED_ITERATING — Still iterating
  • ITERATING — Still iterating
  • CONVERGED_RTOL_NORMAL_EQUATIONS — Undocumented.
  • CONVERGED_ATOL_NORMAL_EQUATIONS — Undocumented.
  • CONVERGED_RTOL — ∥r∥ <= rtolnorm(b) or rtolnorm(b - Ax₀)
  • CONVERGED_ATOL — ∥r∥ <= atol
  • CONVERGED_ITS — Used by the Type.PREONLY solver after the single iteration of the preconditioner is applied. Also used when the KSPConvergedSkip convergence test routine is set in KSP (https://petsc.org/release/manualpages/KSP/KSPConvergedSkip.html).
  • CONVERGED_NEG_CURVE — Undocumented.
  • CONVERGED_STEP_LENGTH — Undocumented.
  • CONVERGED_HAPPY_BREAKDOWN — Undocumented.
  • DIVERGED_NULL — Undocumented.
  • DIVERGED_MAX_IT — Ran out of iterations before any convergence criteria was reached.
  • DIVERGED_DTOL — norm(r) >= dtol*norm(b)
  • DIVERGED_BREAKDOWN — A breakdown in the Krylov method was detected so the method could not continue to enlarge the Krylov space. Could be due to a singular matrix or preconditioner. In KSPHPDDM, this is also returned when some search directions within a block are collinear.
  • DIVERGED_BREAKDOWN_BICG — A breakdown in the KSPBICG method was detected so the method could not continue to enlarge the Krylov space.
  • DIVERGED_NONSYMMETRIC — It appears the operator or preconditioner is not symmetric and this Krylov method (Type.CG, Type.MINRES, Type.CR) requires symmetry.
  • DIVERGED_INDEFINITE_PC — It appears the preconditioner is indefinite (has both positive and negative eigenvalues) and this Krylov method (Type.CG) requires it to be positive definite.
  • DIVERGED_NANORINF — Undocumented.
  • DIVERGED_INDEFINITE_MAT — Undocumented.
  • DIVERGED_PCSETUP_FAILED — It was not possible to build or use the requested preconditioner. This is usually due to a zero pivot in a factorization. It can also result from a failure in a subpreconditioner inside a nested preconditioner such as PC.Type.FIELDSPLIT.

See also: None — https://docs.python.org/3/builtins/constants.html#None

✨ Attributes Summary ✨

okay bestie so this is the full roster of attribute constants, and the vibe check result is: every single one of them is a plain old int — like, the Python builtin int, <https://docs.python.org/3/builtins/functions.html#int>. That's the whole type situation. Nothing fancy, no cap. Here's the entire list, no skipping, all twenty of them:

  • CONVERGED_ATOL — Constant CONVERGED_ATOL, of type int.
  • CONVERGED_ATOL_NORMAL_EQUATIONS — Constant CONVERGED_ATOL_NORMAL_EQUATIONS, of type int.
  • CONVERGED_HAPPY_BREAKDOWN — Constant CONVERGED_HAPPY_BREAKDOWN, of type int.
  • CONVERGED_ITERATING — Constant CONVERGED_ITERATING, of type int.
  • CONVERGED_ITS — Constant CONVERGED_ITS, of type int.
  • CONVERGED_NEG_CURVE — Constant CONVERGED_NEG_CURVE, of type int.
  • CONVERGED_RTOL — Constant CONVERGED_RTOL, of type int.
  • CONVERGED_RTOL_NORMAL_EQUATIONS — Constant CONVERGED_RTOL_NORMAL_EQUATIONS, of type int.
  • CONVERGED_STEP_LENGTH — Constant CONVERGED_STEP_LENGTH, of type int.
  • DIVERGED_BREAKDOWN — Constant DIVERGED_BREAKDOWN, of type int.
  • DIVERGED_BREAKDOWN_BICG — Constant DIVERGED_BREAKDOWN_BICG, of type int.
  • DIVERGED_DTOL — Constant DIVERGED_DTOL, of type int.
  • DIVERGED_INDEFINITE_MAT — Constant DIVERGED_INDEFINITE_MAT, of type int.
  • DIVERGED_INDEFINITE_PC — Constant DIVERGED_INDEFINITE_PC, of type int.
  • DIVERGED_MAX_IT — Constant DIVERGED_MAX_IT, of type int.
  • DIVERGED_NANORINF — Constant DIVERGED_NANORINF, of type int.
  • DIVERGED_NONSYMMETRIC — Constant DIVERGED_NONSYMMETRIC, of type int.
  • DIVERGED_NULL — Constant DIVERGED_NULL, of type int.
  • DIVERGED_PCSETUP_FAILED — Constant DIVERGED_PCSETUP_FAILED, of type int.
  • ITERATING — Constant ITERATING, of type int.
fr fr, that's it. Twenty constants, twenty ints, zero plot twists. The CONVERGED_ girlies and the DIVERGED_ girlies are all just integer values chillin' in the same type pool 💅

🌸 Attributes Documentation 🌸

and now the part where each one gets her own moment in the spotlight, bestie — the actual per-attribute docs, coming right up ✨

okay bestie, we are BACK in the constant zone and honestly? it goes hard 💅 buckle up, these are all int-typed constants, copying them one by one because that is simply the assignment:

  • CONVERGED_ATOL: int = CONVERGED_ATOL — Constant CONVERGED_ATOL of type int ✨
  • CONVERGED_ATOL_NORMAL_EQUATIONS: int = CONVERGED_ATOL_NORMAL_EQUATIONS — Constant CONVERGED_ATOL_NORMAL_EQUATIONS of type int 🌸
  • CONVERGED_HAPPY_BREAKDOWN: int = CONVERGED_HAPPY_BREAKDOWN — Constant CONVERGED_HAPPY_BREAKDOWN of type int 😭 (the name is giving "we won but at what cost")
  • CONVERGED_ITERATING: int = CONVERGED_ITERATING — Constant CONVERGED_ITERATING of type int 🌀
  • CONVERGED_ITS: int = CONVERGED_ITS — Constant CONVERGED_ITS of type int ⭐
  • CONVERGED_NEG_CURVE: int = CONVERGED_NEG_CURVE — Constant CONVERGED_NEG_CURVE of type int 📉
  • CONVERGED_RTOL: int = CONVERGED_RTOL — Constant CONVERGED_RTOL of type int 💖
  • CONVERGED_RTOL_NORMAL_EQUATIONS: int = CONVERGED_RTOL_NORMAL_EQUATIONS — Constant CONVERGED_RTOL_NORMAL_EQUATIONS of type int 🎀
  • CONVERGED_STEP_LENGTH: int = CONVERGED_STEP_LENGTH — Constant CONVERGED_STEP_LENGTH of type int 📏
  • DIVERGED_BREAKDOWN: int = DIVERGED_BREAKDOWN — Constant DIVERGED_BREAKDOWN of type int 💀
  • DIVERGED_BREAKDOWN_BICG: int = DIVERGED_BREAKDOWN_BICG — Constant DIVERGED_BREAKDOWN_BICG of type int 💀
  • DIVERGED_DTOL: int = DIVERGED_DTOL — Constant DIVERGED_DTOL of type int 🙈
  • DIVERGED_INDEFINITE_MAT: int = DIVERGED_INDEFINITE_MAT — Constant DIVERGED_INDEFINITE_MAT of type int 😵‍💫
  • DIVERGED_INDEFINITE_PC: int = DIVERGED_INDEFINITE_PC — Constant DIVERGED_INDEFINITE_PC of type int 😵‍💫
  • DIVERGED_MAX_IT: int = DIVERGED_MAX_IT — Constant DIVERGED_MAX_IT of type int ⏰
  • DIVERGED_NANORINF: int = DIVERGED_NANORINF — Constant DIVERGED_NANORINF of type int 🌊
  • DIVERGED_NONSYMMETRIC: int = DIVERGED_NONSYMMETRIC — Constant DIVERGED_NONSYMMETRIC of type int 🌈
  • DIVERGED_NULL: int = DIVERGED_NULL — Constant DIVERGED_NULL of type int 🕳️
  • DIVERGED_PCSETUP_FAILED: int = DIVERGED_PCSETUP_FAILED — Constant DIVERGED_PCSETUP_FAILED of type int 🚨
  • ITERATING: int = ITERATING — Constant ITERATING of type int 🔁

and then, closing out the class, we have the two little init guys:

  • __init__() — the constructor, doing constructor things 🫶
  • classmethod __new__(*args, **kwargs) — the classmethod that takes *args, **kwargs, lowkey the actual object-maker 🧚

🦋 petsc4py.PETSc.KSP.DMActive 🦋

class petsc4py.PETSc.KSP.DMActive

Bases: object

the argument you hand to KSPSetDMActive() — that's literally its whole job and it does it beautifully 💅

✨ Attributes Summary ✨

  • ALL — Constant ALL of type int
  • INITIAL_GUESS — Constant INITIAL_GUESS of type int
  • OPERATOR — Constant OPERATOR of type int
  • RHS — Constant RHS of type int

💖 Attributes Documentation 💖

  • ALL: int = ALL — Constant ALL of type int 🌈
  • INITIAL_GUESS: int = INITIAL_GUESS — Constant INITIAL_GUESS of type int 🌱
  • OPERATOR: int = OPERATOR — Constant OPERATOR of type int 🔥
  • RHS: int = RHS — Constant RHS of type int 👑

and, as always, the obligatory duo at the bottom of the class:

  • __init__() — constructor, no notes ✨
  • classmethod __new__(*args, **kwargs) — takes *args, **kwargs and makes you an instance 🎀

💫 petsc4py.PETSc.KSP.HPDDMType 💫

class petsc4py.PETSc.KSP.HPDDMType

Bases: object

the HPDDM Krylov solver type — that's the vibe, that's the whole description, it ate and left no crumbs 😌

✨ Attributes Summary ✨

okay bestie, here's the whole roster of constants living up in here, all of them int typed. Heads up: every single one of these annotations is literally just the Python docs entry for the builtin int — same link, eight times, no cap. Not me typing int eight times 💀 but here we are:

  • BCG — Constant BCG of type int
  • BFBCG — Constant BFBCG of type int
  • BGCRODR — Constant BGCRODR of type int
  • BGMRES — Constant BGMRES of type int
  • CG — Constant CG of type int
  • GCRODR — Constant GCRODR of type int
  • GMRES — Constant GMRES of type int
  • PREONLY — Constant PREONLY of type int

Like... that's it. That's the table. Every one is an int, every one is a constant, and the type annotation is the exact same int link from the Python builtins docs. Slay, honestly.

🌟 Attributes Documentation 🌟

the receipts, one by one 💖 every annotation here points at the Python docs for the builtin int, object — whichever it says.

BCG: int = BCG

Constant BCG of type int. 🫶

BFBCG: int = BFBCG

Constant BFBCG of type int. 🫶

BGCRODR: int = BGCRODR

Constant BGCRODR of type int. 🫶

BGMRES: int = BGMRES

Constant BGMRES of type int. 🫶

CG: int = CG

Constant CG of type int. 🫶

GCRODR: int = GCRODR

Constant GCRODR of type int. 🫶

GMRES: int = GMRES

Constant GMRES of type int. 🫶

PREONLY: int = PREONLY

Constant PREONLY of type int. 🫶

💅 the dunders, obviously

__init__()

classmethod __new__(*args, **kwargs)

yeah the usual constructor energy, nothing spicy to report. moving on bestie 🦋

👑 petsc4py.PETSc.KSP.NormType 👑

class petsc4py.PETSc.KSP.NormType

Bases: object

it's giving KSP norm type. this is the little enum-ish thingie that tells your solver which norm are we even measuring here, and honestly it's a vibe check for your residual.

The available norm types are, in no particular order of chaos:

  • NONE — Skips computing the norm ✨ this should generally only be used if you're running the Krylov method as a smoother with a fixed small number of iterations. It implicitly sets KSPConvergedSkip as the KSP convergence test. BUT — heads up — certain algorithms, like Type.GMRES, ALWAYS require the norm calculation. For those methods the norms still get computed, they're just not used in the convergence test. So like, it's not free lunch, okay? 💀
  • PRECONDITIONED — the default for left preconditioned solves 🎀 uses the l₂ norm of the preconditioned residual P⁻¹(b - Ax).
  • UNPRECONDITIONED — uses the l₂ norm of the true b - Ax residual. the real one. the genuine article. no filter, no cap 👑
  • NATURAL — supported by Type.CG, Type.CR, Type.CGNE, and Type.CGS. if your solver is one of those four, this one's for you bestie 🫶

✨ Attributes Summary ✨

okay so real quick, this whole squad is <pink>constants</pink> and every single one of them is an int — yes, all of them, no cap. Here's the full roster, don't skip a single one:

💖 Attributes Documentation 💖

and now the same eleven icons, but with their whole little glow-up card each, bestie. signature first, then the tea:

DEFAULT

DEFAULT: int = DEFAULT

Constant DEFAULT of type int — https://docs.python.org/3/builtins/functions.html#int

NATURAL

NATURAL: int = NATURAL

Constant NATURAL of type int — https://docs.python.org/3/builtins/functions.html#int

NO

NO: int = NO

Constant NO of type int — https://docs.python.org/3/builtins/functions.html#int

NONE

NONE: int = NONE

Constant NONE of type int — https://docs.python.org/3/builtins/functions.html#int

NORM_DEFAULT

NORM_DEFAULT: int = NORM_DEFAULT

Constant NORM_DEFAULT of type int — https://docs.python.org/3/builtins/functions.html#int

NORM_NATURAL

NORM_NATURAL: int = NORM_NATURAL

Constant NORM_NATURAL of type int — https://docs.python.org/3/builtins/functions.html#int

NORM_NONE

NORM_NONE: int = NORM_NONE

Constant NORM_NONE of type int — https://docs.python.org/3/builtins/functions.html#int

NORM_PRECONDITIONED

NORM_PRECONDITIONED: int = NORM_PRECONDITIONED

Constant NORM_PRECONDITIONED of type int — https://docs.python.org/3/builtins/functions.html#int

NORM_UNPRECONDITIONED

NORM_UNPRECONDITIONED: int = NORM_UNPRECONDITIONED

Constant NORM_UNPRECONDITIONED of type int — https://docs.python.org/3/builtins/functions.html#int

PRECONDITIONED

PRECONDITIONED: int = PRECONDITIONED

Constant PRECONDITIONED of type int — https://docs.python.org/3/builtins/functions.html#int

UNPRECONDITIONED

UNPRECONDITIONED: int = UNPRECONDITIONED

Constant UNPRECONDITIONED of type int — https://docs.python.org/3/builtins/functions.html#int

__init__()

__init__()

yeah that's literally it, that's the whole entry, no description attached, we move 💅

classmethod __new__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

same situation bestie — signature only, nothing else documented here 🌸

👑 petsc4py.PETSc.KSP.Type 👑

class petsc4py.PETSc.KSP.Type

Bases: object — https://docs.python.org/3/builtins/functions.html#object

KSP Type.

The available types are:

👀 See also

✨ Attributes Summary ✨

okay so here's the attributes summary, and it is not a long one at the type level — every single thing on this list is a plain str 💅 and every single one of them points at the exact same Python docs anchor, https://docs.python.org/3/builtins/stdtypes.html#str. no cap. so read this as a roster of names, bestie, and keep scrolling 🌸

okay so that's the whole roster bestie, every single one of them is just a str, no cap — the name of the constant is the name of the thing, and the thing is a string. that's the vibe. 🎀

✨ Attributes Documentation ✨

this is where it gets spelled out one by one, like the docstring is doing a little roll call. each one has a type, a link, and the value it's literally set to. obsessed with the consistency honestly 💅

BCGS

Type + value: BCGS: str https://docs.python.org/3/builtins/stdtypes.html#str = BCGS

Object BCGS of type str https://docs.python.org/3/builtins/stdtypes.html#str

it's giving "the constant holds its own name as a string" and honestly? clean. no notes. ✨

BCGSL

Type + value: BCGSL: str https://docs.python.org/3/builtins/stdtypes.html#str = BCGSL

Object BCGSL of type str https://docs.python.org/3/builtins/stdtypes.html#str

BICG

Type + value: BICG: str https://docs.python.org/3/builtins/stdtypes.html#str = BICG

Object BICG of type str https://docs.python.org/3/builtins/stdtypes.html#str

CG

Type + value: CG: str https://docs.python.org/3/builtins/stdtypes.html#str = CG

Object CG of type str https://docs.python.org/3/builtins/stdtypes.html#str

fr fr, the pattern is the pattern — str in, str out, and the value is just the constant's own name 💖

okay bestie, buckle UP, because this stretch is just… the entire alphabet of solver vibes 💅 Every single one of these is a class attribute hanging off the type, and every single one is a str holding its own name. Yes, it's that girl. No cap, here's the whole roster, exactly as written, and I am not skipping a single one of them:

  • CGLS: str = CGLS — Object CGLS of type str
  • CGNE: str = CGNE — Object CGNE of type str
  • CGS: str = CGS — Object CGS of type str
  • CHEBYSHEV: str = CHEBYSHEV — Object CHEBYSHEV of type str
  • CR: str = CR — Object CR of type str
  • DGMRES: str = DGMRES — Object DGMRES of type str
  • FBCGS: str = FBCGS — Object FBCGS of type str
  • FBCGSR: str = FBCGSR — Object FBCGSR of type str
  • FCG: str = FCG — Object FCG of type str
  • FETIDP: str = FETIDP — Object FETIDP of type str
  • FGMRES: str = FGMRES — Object FGMRES of type str
  • GCR: str = GCR — Object GCR of type str
  • GLTR: str = GLTR — Object GLTR of type str
  • GMRES: str = GMRES — Object GMRES of type str
  • GROPPCG: str = GROPPCG — Object GROPPCG of type str
  • HPDDM: str = HPDDM — Object HPDDM of type str
  • IBCGS: str = IBCGS — Object IBCGS of type str
  • LCD: str = LCD — Object LCD of type str
  • LGMRES: str = LGMRES — Object LGMRES of type str
  • LSQR: str = LSQR — Object LSQR of type str
  • MINRES: str = MINRES — Object MINRES of type str
  • NASH: str = NASH — Object NASH of type str
  • NONE: str = NONE — Object NONE of type str
  • PGMRES: str = PGMRES — Object PGMRES of type str
  • PIPEBCGS: str = PIPEBCGS — Object PIPEBCGS of type str
  • PIPECG: str = PIPECG — Object PIPECG of type str
  • PIPECG2: str = PIPECG2 — Object PIPECG2 of type str
  • PIPECGRR: str = PIPECGRR — Object PIPECGRR of type str
  • PIPECR: str = PIPECR — Object PIPECR of type str
  • PIPEFCG: str = PIPEFCG — Object PIPEFCG of type str
  • PIPEFGMRES: str = PIPEFGMRES — Object PIPEFGMRES of type str
  • PIPEGCR: str = PIPEGCR — Object PIPEGCR of type str
  • PIPELCG: str = PIPELCG — Object PIPELCG of type str
  • PIPEPRCG: str = PIPEPRCG — Object PIPEPRCG of type str
  • PREONLY: str = PREONLY — Object PREONLY of type str
  • PYTHON: str = PYTHON — Object PYTHON of type str
  • QCG: str = QCG — Object QCG of type str
  • QMRCGS: str = QMRCGS — Object QMRCGS of type str
  • RICHARDSON: str = RICHARDSON — Object RICHARDSON of type str
  • STCG: str = STCG — Object STCG of type str
  • SYMMLQ: str = SYMMLQ — Object SYMMLQ of type str
  • TCQMR: str = TCQMR — Object TCQMR of type str
  • TFQMR: str = TFQMR — Object TFQMR of type str
  • TSIRM: str = TSIRM — Object TSIRM of type str

and then the two little darlings that keep the whole class alive, bestie 🫶

  • __init__()
  • classmethod __new__(*args, **kwargs)
not me pointing out that every single one of these is the name of the thing written twice — the attribute holds a str, and that str is literally its own name. it's giving mirror selfie. it's giving "I am my own icon." okay? periodt. 🌈

and if you tried to count them, yes, it's a LOT, and no, none of them got cut 💀 every option, exactly where it was, exactly how it was spelled. slay.

okay bestie, here comes the whole KSP method menu, item by item, no skips no cap 🌸

  • addConvergenceTest(converged[, args, kargs, ...]) — plug in the function that decides whether we're converged yet ✨
  • appendOptionsPrefix(prefix) — tack more onto the prefix that every KSP option in the database lives under 💅
  • buildResidual([r]) — hand back the residual of the linear system 🫶
  • buildSolution([x]) — hand back the solution vector 💖
  • callConvergenceTest(its, rnorm) — actually run the convergence test callback 🎀
  • computeEigenvalues() — compute the extreme eigenvalues of the preconditioned operator 👑
  • computeExtremeSingularValues() — compute the extreme singular values of the preconditioned operator ⭐
  • create([comm]) — spin up the KSP context 🌈
  • createPython([context, comm]) — spin up a linear solver of Python type 🐍
  • destroy() — yeet the KSP context 💀
  • getAppCtx() — get back the user-defined context for the linear solver 🙈
  • getCGObjectiveValue() — get back the CG objective function value 📊
  • getComputeEigenvalues() — get the flag saying whether eigenvalues are gonna get calculated 🔍
  • getComputeSingularValues() — get the flag saying whether singular values are gonna get calculated 🌸
  • getConvergedReason() — use the reason property instead, bestie (this one's the legacy route) 🦋
  • getConvergenceHistory() — get back the array holding the residual history 📜
  • getConvergenceTest() — get back the function used to determine convergence 💅
  • getDM() — get back the DM <#petsc4py.PETSc.DM> that some preconditioners might use 🗺️
  • getErrorIfNotConverged() — get the flag that says the solver will error out if it diverges 😭
  • getHPDDMType() — get back the Krylov solver type 🔥
  • getInitialGuessKnoll() — figure out whether the KSP solver is using the Knoll trick 🧚
  • getInitialGuessNonzero() — figure out whether the KSP solver uses a zero initial guess 🤔
  • getIterationNumber() — use its property instead, periodt 💅
  • getMonitor() — get back the function used to monitor the residual 👀
  • getNormType() — get back the norm used for convergence testing 📏
  • getOperators() — get back the matrix associated with the linear system 🔢
  • getOptionsPrefix() — get back the prefix used for all KSP options in the database 🏷️
  • getPC() — get back the preconditioner 🎀
  • getPCSide() — get back the preconditioning side 🌿
  • getPythonContext() — hands you the instance of the class that's implementing the Python methods. the actual object, bestie 💖
  • getPythonType() — returns the fully qualified Python name of the class your solver is using. full government name vibes ✨
  • getResidualNorm() — lowkey just says use the norm property. that's the whole thing 🎀
  • getRhs() — gives you the right-hand side vector for the linear system. the b in Ax = b, iconic behavior 💅
  • getSolution() — returns the solution for the linear system you're about to solve 🦋
  • getTolerances() — returns the various tolerances that the KSP convergence tests are out here using 🌸
  • getType() — returns the KSP type as a string, straight off the KSP object 👑
  • getWorkVecs([right, left]) — creates working vectors. right and left are optional, no cap 🫶
  • logConvergenceHistory(rnorm) — adds a residual to the convergence history, so the receipt is kept 😭
  • matSolve(B, X) — solves a linear system with multiple right-hand sides. glow up from regular solve ✨
  • matSolveTranspose(B, X) — solves the transpose of a linear system with multiple RHS 🔥
  • monitor(its, rnorm) — runs the user-provided monitor routines, if they exist. if they don't exist, it's giving nothing 💀
  • monitorCancel() — clears all monitors for a KSP object. bye babes 👋
  • reset() — resets a KSP context 🧚
  • setAppCtx(appctx) — sets the optional user-defined context for the linear solver. your lil backpack of extra stuff 🎀
  • setComputeEigenvalues(flag) — sets a flag to compute eigenvalues ⭐
  • setComputeOperators(operators[, args, kargs]) — sets the routine to compute the linear operators. args and kargs are optional extras 💜
  • setComputeRHS(rhs[, args, kargs]) — sets the routine to compute the right-hand side of the linear system. optional args and kargs again, fr fr 🌈
  • setComputeSingularValues(flag) — sets the flag to calculate singular values 🔥
  • setConvergedReason(reason) — literally just use the reason property. periodt 💅
  • setConvergenceHistory([length, reset]) — sets the array used to hold the residual history. length and reset are optional 🌸
  • setConvergenceTest(converged[, args, kargs]) — sets the function used to determine convergence. optional args and kargs, iykyk ✨
  • setDM(dm) — sets the DM <#petsc4py.PETSc.DM> that may be used by some preconditioners 🦋
  • setDMActive(dmactive, flag) — says the DM <#petsc4py.PETSc.DM> should be used to generate the system matrix & RHS vector 👑
  • setErrorIfNotConverged(flag) — makes solve throw an error if it didn't converge. dramatic and valid 💀
  • setFromOptions() — sets KSP options from the options database 🌟
  • setGMRESRestart(restart) — sets the number of iterations at which KSP restarts 🔁
  • setHPDDMType(hpddm_type) — sets the Krylov solver type 💖
  • setInitialGuessKnoll(flag) — tells the solver to use PC.apply <#petsc4py.PETSc.PC.apply> to compute the

initial guess. 💖

(Yeah, we're still deep in the KSP method list, bestie — no heading, no restart, just vibes and more methods. Let's GO. ✨)

  • setInitialGuessNonzero(flag) — tells the iterative solver that the initial guess is nonzero. That's literally the whole thing, no cap. 🫶
  • setIterationNumber(its) — uses the its property. Just that. 🎀
  • setMonitor(monitor[, args, kargs]) — sets an additional function to monitor the residual. 👀 You pass the monitor function, plus optional args and kargs to ride along.
  • setNormType(normtype) — sets the norm that gets used for convergence testing. 📏
  • setOperators([A, P]) — sets the matrix associated with the linear system. 🧮 Both A and P are optional in the signature, fyi.
  • setOptionsPrefix(prefix) — sets the prefix used for all the KSP options in the database. 🏷️
  • setPC(pc) — sets the preconditioner. 👑
  • setPCSide(side) — sets the preconditioning side. 🪞
  • setPostSolve(postsolve[, args, kargs]) — sets the function that gets called at the end of each KSP.solve. 🎀 Optional args and kargs welcome to the party.
  • setPreSolve(presolve[, args, kargs]) — sets the function that gets called at the beginning of each KSP.solve. 🌸 Also takes optional args and kargs.
  • setPythonContext([context]) — sets the instance of the class implementing the Python methods. 🐍 context is optional.
  • setPythonType(py_type) — sets the fully qualified Python name of the class to be used. ✨
  • setResidualNorm(rnorm) — uses the norm property. ⭐
  • setTolerances([rtol, atol, divtol, max_it]) — sets the various tolerances used by the KSP convergence testers. 🎚️ Every single arg is optional: rtol, atol, divtol, max_it.
  • setType(ksp_type) — builds the KSP data structure for a particular Type 🏗️ — the reference for which lives at <#petsc4py.PETSc.KSP.Type>.
  • setUp() — sets up the internal data structures for an iterative solver. 🔧
  • setUpOnBlocks() — sets up the preconditioner for each block in a block method. 🧱
  • setUseFischerGuess(model, size) — uses the Paul Fischer algorithm to compute initial guesses. ✨ Takes model and size.
  • solve(b, x) — solves the linear system. 🎉 Signature args: b and x.
  • solveTranspose(b, x) — solves the transpose of a linear system. 🔄 Signature args: b and x.
  • view([viewer]) — prints the KSP data structure. 🖨️ viewer is optional.

And that's the KSP method table fully served, no crumbs left on the plate. 💅 There's still more where this came from, so don't go anywhere 💜

✨ Attributes Summary ✨

ok so these are the attributes you can just... reach for, bestie. no methods needed, they're right there 💅

  • appctx — the solver application context 🫶
  • atol — the absolute tolerance of the solver
  • divtol — the divergence tolerance of the solver 💀
  • dm — the solver DM
  • guess_knoll — whether the solver uses the Knoll trick ✨
  • guess_nonzero — whether the guess is non-zero
  • history — the convergence history of the solver 📜
  • is_converged — boolean indicating if the solver has converged 🎉
  • is_diverged — boolean indicating if the solver has failed 😭
  • is_iterating — boolean indicating if the solver has not converged yet 🌀
  • its — the current number of iterations the solver has taken
  • mat_op — the system matrix operator
  • mat_pc — the preconditioner operator
  • max_it — the maximum number of iteration the solver may take
  • norm — the norm of the residual at the current iteration
  • norm_type — the norm used by the solver
  • pc — the PC of the solver
  • pc_side — the side on which preconditioning is performed
  • reason — the converged reason 🧐
  • rtol — the relative tolerance of the solver
  • vec_rhs — the right-hand side vector
  • vec_sol — the solution vector 👑

🌸 Methods Documentation 🌸

addConvergenceTest(converged, args=None, kargs=None, prepend=False)

ok so this one? it adds the function that's gonna decide whether you've actually converged. not me handing the solver my own vibe check 🎀

Logically collective, bestie — everybody's in on it together.

Parameters

  • converged (KSPConvergenceTestFunction) — the callback which computes the convergence
  • args (tuple[Any, ...] | None) — positional arguments for the callback function
  • kargs (dict[str, Any] | None) — keyword arguments for the callback function
  • prepend (bool) — whether to prepend this call before the default convergence test or call it after 🌈

Return type

None

Notes

Cannot be mixed with a call to setConvergenceTest. It can only be called once. If called multiple times, it will generate an error. 💀 like literally do not try it twice, it will NOT be cute.

See also: setTolerances, getConvergenceTest, setConvergenceTest, KSPSetConvergenceTest, KSPConvergedDefault

Source code at petsc4py/PETSc/KSP.pyx:1079

appendOptionsPrefix(prefix)

append to the prefix used for all KSP options in the database 🗂️ just tacking more onto your lil name tag.

Logically collective, periodt.

Parameters

  • prefix (str | None) — the options prefix to append

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 like... don't add one yourself, she's already got one on, ok?

See also: KSPAppendOptionsPrefix

Source code at petsc4py/PETSc/KSP.pyx:585

buildResidual(r=None)

return the residual of the linear system ✨ the receipts, basically. proof of how far off we still are 😭

Collective, everyone pitch in.

Parameters

  • r (Vec | None) — optional vector to use for the result

Return type

Vec

See also: buildSolution, KSPBuildResidual

  • buildSolution(x=None) — hands you back the solution vector, bestie. 💖

Collective — everybody in the communicator's doing this together, no stragglers.

Params:

  • x (Vec | None) — optional vector where you wanna stash the solution.

Returns Vec

See also: buildResidual, KSPBuildSolution

Source code at petsc4py/PETSc/KSP.pyx:2055

  • callConvergenceTest(its, rnorm) — calls the convergence test callback. like, pokes it and asks "we done yet?" 🫵

Collective.

Params:

  • its (int) — number of iterations.
  • rnorm (float) — the residual norm.

Returns None

Notes: This functionality is implemented in petsc4py. (yes, it's a petsc4py exclusive, iykyk ✨)

Source code at petsc4py/PETSc/KSP.pyx:1135

  • computeEigenvalues() — computes the extreme eigenvalues for the preconditioned operator. it's giving spectral analysis 💅

Not collective.

See also: KSPComputeEigenvalues

Returns ArrayComplex

Source code at petsc4py/PETSc/KSP.pyx:2099

  • computeExtremeSingularValues() — computes the extreme singular values for the preconditioned operator.

Collective.

Returns:

  • smax (float) — the maximum singular value.
  • smin (float) — the minimum singular value.

Returns tuple[float, float]

See also: KSPComputeExtremeSingularValues

Source code at petsc4py/PETSc/KSP.pyx:2122

  • create(comm=None) — creates the KSP context, slay. this is how you manifest a whole solver into existence ✨

Collective.

See also: KSPCreate

Source code at petsc4py/PETSc/KSP.pyx:467

Params:

  • comm (Comm | None)

Returns Self

  • createPython(context=None, comm=None) — creates a linear solver of Python type. so you can bring your own Python-coded solver to the function, main character energy 👑

Collective.

Params:

  • context (Any) — an instance of the Python class implementing the required methods.
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Returns Self

See also: PETSc Python linear solver type, setType, setPythonContext, Type.PYTHON

Source code at petsc4py/PETSc/KSP.pyx:2168

  • destroy() — destroys the KSP context. rip bestie, we hardly knew ye 💀

Collective.

See also: KSPDestroy

Source code at petsc4py/PETSc/KSP.pyx:454

Returns Self

  • getAppCtx() — returns the user-defined context for the linear solver. your lil' custom blob of data, right back atcha 🎀

Not collective.

See also: setAppCtx

Returns Any

Source code at petsc4py/PETSc/KSP.pyx:650

  • getCGObjectiveValue() — returns the CG objective function value. the number the CG method is lowkey optimizing toward ✨

Not collective.

See also: KSPCGGetObjFcn

Returns float

Source code at petsc4py/PETSc/KSP.pyx:1896

  • getComputeEigenvalues() — returns the flag saying whether eigenvalues are gonna get calculated.

Not collective.

Returns the flag indicating that the extreme eigenvalues values will be calculated via a Lanczos or Arnoldi process as the linear system is solved.

See also: setComputeEigenvalues, KSPSetComputeEigenvalues

Returns bool

Source code at petsc4py/PETSc/KSP.pyx:1444

  • getComputeSingularValues() — returns the flag saying whether singular values are gonna get calculated.

Not collective.

Returns the flag indicating whether the extreme singular values will be calculated via a Lanczos or Arnoldi process as the linear system is solved.

See also: setComputeSingularValues, KSPGetComputeSingularValues

Returns bool

Source code at petsc4py/PETSc/KSP.pyx:1488

  • getConvergedReason() — use the reason property instead. this one's just an alias, not the moment 💅

Returns ConvergedReason

Source code at petsc4py/PETSc/KSP.pyx:1890

  • getConvergenceHistory() — returns an array with the residual history. every step of the glow-up, documented 🌸

Not collective.

See also: setConvergenceHistory, KSPGetResidualHistory

Returns ArrayReal

Source code at petsc4py/PETSc/KSP.pyx:1202

  • getConvergenceTest() — returns the function used to determine convergence. the vibe check that decides "we good" or "keep going" 💅

Logically collective.

See also: setTolerances, setConvergenceTest, KSPGetConvergenceTest, KSPConvergedDefault

Source code at petsc4py/PETSc/KSP.pyx:1122

Return type — KSPConvergenceTestFunction

💖 getDM()

Give back the DM that some preconditioners might be out here using. 🦋

Not collective — everybody keeps their own copy, no group chat needed.

See also: PETSc.KSP, DM, KSPGetDM — https://petsc.org/release/manualpages/KSP/KSPGetDM.html

Source code at petsc4py/PETSc/KSP.pyx:664 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L664

Return type — DM

✨ getErrorIfNotConverged()

Returns the flag that says whether the solver is gonna throw hands (aka error out) when it diverges. 😭

Not collective.

See also: KSPGetErrorIfNotConverged — https://petsc.org/release/manualpages/KSP/KSPGetErrorIfNotConverged.html

Source code at petsc4py/PETSc/KSP.pyx:1960 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1960

Return type — bool

🔥 getHPDDMType()

Tells you which Krylov solver type we're on, bestie.

Not collective.

See also: KSPHPDDMGetType — https://petsc.org/release/manualpages/KSP/KSPHPDDMGetType.html

Source code at petsc4py/PETSc/KSP.pyx:1928 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1928

Return type — HPDDMType

💅 getInitialGuessKnoll()

Checks if the KSP solver is doing the Knoll trick or not. 👑

Not collective.

This one is literally the Knoll trick — it uses PC.apply to compute the initial guess.

See also: KSPGetInitialGuessKnoll — https://petsc.org/release/manualpages/KSP/KSPGetInitialGuessKnoll.html

Source code at petsc4py/PETSc/KSP.pyx:1564 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1564

Return type — bool

🌸 getInitialGuessNonzero()

Says whether the KSP solver is starting from a zero initial guess or not. 🎀

Not collective.

See also: KSPGetInitialGuessNonzero — https://petsc.org/release/manualpages/KSP/KSPGetInitialGuessNonzero.html

Source code at petsc4py/PETSc/KSP.pyx:1530 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1530

Return type — bool

🦋 getIterationNumber()

Lowkey just use its property instead, bestie. 🙈

Source code at petsc4py/PETSc/KSP.pyx:1868 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1868

Return type — int

💜 getMonitor()

Hands you back the function that monitors the residual. 👀

Not collective.

See also: Working with PETSc options, setMonitor, monitor, monitorCancel, KSPGetMonitorContext — https://petsc.org/release/manualpages/KSP/KSPGetMonitorContext.html

Source code at petsc4py/PETSc/KSP.pyx:1280 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1280

Return type — KSPMonitorFunction

⭐ getNormType()

Returns the norm that's being used for convergence testing. 💯

Not collective.

See also: NormType, setNormType, KSPGetNormType — https://petsc.org/release/manualpages/KSP/KSPGetNormType.html, KSPConvergedSkip — https://petsc.org/release/manualpages/KSP/KSPConvergedSkip.html

Source code at petsc4py/PETSc/KSP.pyx:1404 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1404

Return type — NormType

🌈 getOperators()

Returns the matrix tied to the linear system. 🫶

Collective.

Gives you back the matrix that defines the linear system and a (possibly) different one used to build the preconditioner, no cap.

Returns

  • A (Mat) — the Matrix that defines the linear system.
  • P (Mat) — the Matrix used in constructing the preconditioner, usually the same as A.

Return type — tuple[Mat, Mat]

See also: PETSc.KSP, solve, setOperators, KSPGetOperators — https://petsc.org/release/manualpages/KSP/KSPGetOperators.html

Source code at petsc4py/PETSc/KSP.pyx:864 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L864

🎀 getOptionsPrefix()

Returns the prefix used for all the KSP options in the database. The way that everything is namespaced… iconic. ✨

Not collective.

See also: KSPGetOptionsPrefix — https://petsc.org/release/manualpages/KSP/KSPGetOptionsPrefix.html

Source code at petsc4py/PETSc/KSP.pyx:571 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L571

Return type — str

💖 getPC()

Returns the preconditioner, bestie. That's it, that's the whole vibe. 🫧

Not collective.

See also: PETSc.KSP, setPC, KSPGetPC — https://petsc.org/release/manualpages/KSP/KSPGetPC.html

Source code at petsc4py/PETSc/KSP.pyx:911 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L911

Return type — PC

🧚 getPCSide()

Returns the preconditioning side. Which side is eating, fr fr. 🍓

Not collective.

See also: Working with PETSc options, setPCSide, setNormType, getNormType, KSPGetPCSide — https://petsc.org/release/manualpages/KSP/KSPGetPCSide.html

Source code at petsc4py/PETSc/KSP.pyx:1363 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1363

Return type — Side

🐍 getPythonContext()

Returns the instance of the class that's implementing the Python methods. Main character energy, honestly. 👑

Not collective.

See also: PETSc Python linear solver type, setPythonContext

Source code at petsc4py/PETSc/KSP.pyx:2209 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2209

Return type — Any

✨ getPythonType()

Returns the fully qualified Python name of the class the solver is using. 💅

Not collective.

See also: PETSc Python linear solver type, setPythonContext, setPythonType, KSPPythonGetType — https://petsc.org/release/manualpages/KSP/KSPPythonGetType.html

Source code at petsc4py/PETSc/KSP.pyx:2239 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2239

Return type — str

🌸 getResidualNorm()

Just use the norm property, bestie, it's right there. 🙈

Source code at petsc4py/PETSc/KSP.pyx:1879 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1879

Return type — float

💜 getRhs()

Returns the right-hand side vector for the linear system. The b in Ax = b, periodt. 💯

Not collective.

See also: KSPGetRhs — https://petsc.org/release/manualpages/KSP/KSPGetRhs.html

Source code at petsc4py/PETSc/KSP.pyx:1974 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1974

Return type — Vec

🦋 getSolution()

Returns the solution for the linear system that's being solved. 🎉

Not collective.

Heads up bestie: this might not be the solution that's stored during the iterative process. Don't get it twisted. 😭

Source code at petsc4py/PETSc/KSP.pyx:1999 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1999

Return type — Vec

See also: KSPGetSolution — <https://petsc.org/release/manualpages/KSP/KSPGetSolution.html>

Source code at petsc4py/PETSc/KSP.pyx:1989 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1989>

Return type: Vec

getTolerances()

okay bestie, this one hands you the receipts on how the KSP decides it's done. 💅 It returns the various tolerances that the KSP convergence tests actually use. Real talk: it does not do any collective communication, so everybody can call it freely.

What you get back: the relative, absolute, divergence, and maximum iteration tolerances that the default KSP convergence tests are working with.

Returns:

  • rtol (float) — the relative convergence tolerance
  • atol (float) — the absolute convergence tolerance
  • dtol (float) — the divergence tolerance
  • maxits (int) — maximum number of iterations

Return type: tuple[float, float, float, int]

See also: setTolerances, KSPGetTolerances — <https://petsc.org/release/manualpages/KSP/KSPGetTolerances.html>

Source code at petsc4py/PETSc/KSP.pyx:985 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L985>

getType()

slay, this is the "who even are you" moment 💖 It returns the KSP type as a string, straight off the KSP object.

Not collective, so no group chat required, you can just ask. 🫶

See also: KSPGetType — <https://petsc.org/release/manualpages/KSP/KSPGetType.html>

Source code at petsc4py/PETSc/KSP.pyx:519 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L519>

Return type: str

getWorkVecs(right=None, left=None)

time to build the little helper vectors ✨ This one creates working vectors, and yes it's collective — everybody's in on it.

Parameters:

  • right (int | None) — number of right hand vectors to allocate
  • left (int | None) — number of left hand vectors to allocate

Returns:

  • R (list of Vec) — list of correctly allocated right hand vectors
  • L (list of Vec) — list of correctly allocated left hand vectors

Return type: tuple[list[Vec], list[Vec]] | list[Vec] | None

Source code at petsc4py/PETSc/KSP.pyx:2007 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2007>

logConvergenceHistory(rnorm)

Adding your lil residual to the convergence history 📈 Logically collective, iykyk.

Parameters:

  • rnorm (float) — residual norm to be added to convergence history

Return type: None

Source code at petsc4py/PETSc/KSP.pyx:1217 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1217>

matSolve(B, X)

bestie this is the multitasking icon 👑 Solve a linear system with multiple right-hand sides. Collective, obviously.

Heads up: these are stored as a Mat.Type.DENSE. And here's the tea — unlike solve, B and X must be different matrices. No aliasing shenanigans, okay? 😭

Parameters:

  • B (Mat) — block of right-hand sides
  • X (Mat) — block of solutions

Return type: None

See also: solve, KSPMatSolve — <https://petsc.org/release/manualpages/KSP/KSPMatSolve.html>

Source code at petsc4py/PETSc/KSP.pyx:1822 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1822>

matSolveTranspose(B, X)

the transposed version of the multitasking moment 🦋 Solve the transpose of a linear system with multiple RHS. Also collective.

Parameters:

  • B (Mat) — block of right-hand sides
  • X (Mat) — block of solutions

Return type: None

See also: solveTranspose, KSPMatSolve — <https://petsc.org/release/manualpages/KSP/KSPMatSolve.html>

Source code at petsc4py/PETSc/KSP.pyx:1844 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1844>

monitor(its, rnorm)

Run the user provided monitor routines, if they exist 👀 Collective.

Notes:

This routine is called by the KSP implementations. It does not typically need to be called by the user. So like… hands off, bestie, the internals got this 💀

See also: setMonitor, KSPMonitor — <https://petsc.org/release/manualpages/KSP/KSPMonitor.html>

Source code at petsc4py/PETSc/KSP.pyx:1308 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1308>

Parameters:

  • its (int)
  • rnorm (float)

Return type: None

monitorCancel()

Clear all monitors for a KSP object. Clean slate, no survivors, periodt. 💅 Logically collective.

See also: Working with PETSc options, getMonitor, setMonitor, monitor, KSPMonitorCancel — <https://petsc.org/release/manualpages/KSP/KSPMonitorCancel.html>

Source code at petsc4py/PETSc/KSP.pyx:1293 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1293>

Return type: None

reset()

Resets a KSP context. Collective, bestie, everybody's doing it together 🌈

What actually happens: it resets the KSP context back to the kspsetupcalled = 0 state and yeets any allocated Vec s and Mat s. Gone. ✨

See also: KSPReset — <https://petsc.org/release/manualpages/KSP/KSPReset.html>

Source code at petsc4py/PETSc/KSP.pyx:1621 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1621>

Return type: None

setAppCtx(appctx)

Set the optional user-defined context for the linear solver 🎀 Not collective, it's your own lil pocket dimension.

Parameters:

  • appctx (Any) — the user defined context

Return type: None

Notes:

The user context is a way for users to attach any information to the KSP that they may need later when interacting with the solver. It's giving "hold my stuff while I go do solver things" 🫶

See also: getAppCtx

Source code at petsc4py/PETSc/KSP.pyx:627 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L627>

setComputeEigenvalues(flag)

Okay so bestie, this one flips a flag that says "yeah, compute the eigenvalues" 💅

Logically collective — that means everyone in the communicator shows up to call it together, nobody does a solo mission ✨

What it actually does: it sets a flag so that the extreme eigenvalues get calculated via a Lanczos or Arnoldi process as the linear system is being solved. So like, mid-solve, the eigenvalues are being cooked 🔥

Parameters

  • flag (bool) — Boolean whether to compute eigenvalues (or not). True = yes please, False = not today.

Return type: None

Notes

Currently this option is not valid for all iterative methods. 💀 So don't come for me if your solver isn't into it.

See also: getComputeEigenvalues, KSPSetComputeEigenvalues — https://petsc.org/release/manualpages/KSP/KSPSetComputeEigenvalues.html

Source code at petsc4py/PETSc/KSP.pyx:1418 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1418

setComputeOperators(operators, args=None, kargs=None)

Set routine to compute the linear operators 🎀

Logically collective, as always, we do it together.

Parameters

  • operators (KSPOperatorsFunction) — Function which computes the operators. This is your little worker bee 🐝
  • args (tuple[Any, ...] | None) — Positional arguments for callback function operators.
  • kargs (dict[str, Any] | None) — Keyword arguments for callback function operators.

Return type: None

Notes — and listen, this one's important, no cap:

The user provided function Operators and delimiters will be called automatically at the very next call to solve. It will NOT be called at future solve calls unless either setComputeOperators or setOperators is called before that solve is called. So it's giving "one-time thing, no strings attached" 😭 This allows the same system to be solved several times with different right-hand side functions, but it's a confusing API since one might expect it to be called for each solve. Yeah... they said it, not me 🙈

If you want to reuse the same preconditioner for the next solve and not compute a new one based on the most recently computed matrix, call KSPSetReusePreconditioner — https://petsc.org/release/manualpages/KSP/KSPSetReusePreconditioner.html

See also: PETSc.KSP, solve, setOperators, KSPSetComputeOperators (https://petsc.org/release/manualpages/KSP/KSPSetComputeOperators.html), KSPSetReusePreconditioner (https://petsc.org/release/manualpages/KSP/KSPSetReusePreconditioner.html)

Source code at petsc4py/PETSc/KSP.pyx:775 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L775

setComputeRHS(rhs, args=None, kargs=None)

Set routine to compute the right-hand side of the linear system 🌸

Logically collective — group activity, bestie.

Parameters

  • rhs (KSPRHSFunction) — Function which computes the right-hand side. Your RHS plug-in, basically ✨
  • args (tuple[Any, ...] | None) — Positional arguments for callback function rhs.
  • kargs (dict[str, Any] | None) — Keyword arguments for callback function rhs.

Return type: None

Notes

The routine you provide will be called each time you call solve to prepare the new right-hand side for that solve. So unlike its dramatic sibling above... this one keeps showing up every single time 🫶 loyal.

See also: PETSc.KSP, solve, KSPSetComputeRHS — https://petsc.org/release/manualpages/KSP/KSPSetComputeRHS.html

Source code at petsc4py/PETSc/KSP.pyx:741 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L741

setComputeSingularValues(flag)

Set flag to calculate singular values 💜

Logically collective.

Sets a flag so that the extreme singular values will be calculated via a Lanczos or Arnoldi process as the linear system is solved. Singular values getting the main character treatment 👑

Parameters

  • flag (bool) — Boolean whether to compute singular values (or not).

Return type: None

Notes

Currently this option is not valid for all iterative methods. Same disclaimer as before, it's just not universally accepted 😭

See also: getComputeSingularValues, KSPSetComputeSingularValues — https://petsc.org/release/manualpages/KSP/KSPSetComputeSingularValues.html

Source code at petsc4py/PETSc/KSP.pyx:1462 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1462

setConvergedReason(reason)

Use reason property. That's it. That's the whole vibe 💀

Source code at petsc4py/PETSc/KSP.pyx:1885 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1885

Parameters

  • reason (ConvergedReason)

Return type: None

setConvergenceHistory(length=None, reset=False)

Set the array used to hold the residual history 🎀✨

Not collective — this one's a you-thing, do it on your own time.

If set, this array will contain the residual norms computed at each iteration of the solver. Receipts. Evidence. All the tea ☕

Parameters

  • length (int | None) — Length of array to store history in.
  • reset (bool) — True indicates the history counter is reset to zero for each new linear solve.

Return type: None

Notes

If length is not provided or None then a default array of length 10000 is allocated. Big array energy fr fr.

If the array is not long enough then once the iterations is longer than the array length, solve stops recording the history. So it just... gives up on journaling at some point 😭

See also: getConvergenceHistory, KSPSetResidualHistory — https://petsc.org/release/manualpages/KSP/KSPSetResidualHistory.html

Source code at petsc4py/PETSc/KSP.pyx:1158 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1158

setConvergenceTest(converged, args=None, kargs=None)

Set the function to be used to determine convergence 🌈

Logically collective — we all agree on when to stop, besties.

Parameters

  • converged (KSPConvergenceTestFunction) — Callback which computes the convergence. This is the judge, jury, and "are we done yet" committee 💅
  • args (tuple[Any, ...] | None) — Positional arguments for callback function.
  • kargs (dict[str, Any] | None) — Keyword arguments for callback function.

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

Literally the void, bestie — it hands you back nothing and that is the entire point 🫶

Notes 🌸

Must be called after the KSP type has been set, so put this after a call to setType, or setFromOptions.

🎀 The note is dead serious about the ordering, so: setType or setFromOptions first, this after. No skipping.

The default is a combination of relative and absolute tolerances. The residual value that is tested may be an approximation; routines that need exact values should compute them.

See also 💫

Source code at petsc4py/PETSc/KSP.pyx:1014 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1014

setDM(dm) 🦋

Hand the solver a DM (#petsc4py.PETSc.DM) that some preconditioners might wanna use. Not all of them! Just some. It's giving "situationship with your preconditioner" ngl 💅

Logically collective.

Parameters

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

Notes

If this is used then the KSP will attempt to use the DM (#petsc4py.PETSc.DM) to create the matrix and use the routine set with DM.setKSPComputeOperators (#petsc4py.PETSc.DM.setKSPComputeOperators). Use setDMActive(KSP.DMActive.OPERATOR, False) to instead use the matrix you have provided with setOperators.

A DM (#petsc4py.PETSc.DM) can only be used for solving one problem at a time because information about the problem is stored on the DM (#petsc4py.PETSc.DM), even when not using interfaces like DM.setKSPComputeOperators (#petsc4py.PETSc.DM.setKSPComputeOperators). Use DM.clone (#petsc4py.PETSc.DM.clone) to get a distinct DM (#petsc4py.PETSc.DM) when solving different problems using the same function space.

💀 One DM, one problem, no sharing. That's the rule and she does not negotiate.

See also 👑

Source code at petsc4py/PETSc/KSP.pyx:681 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L681

setDMActive(dmactive, flag) ✨

Should the DM (#petsc4py.PETSc.DM) be the one generating the system matrix & RHS vector? That's the whole question. 🔥

Logically collective.

Parameters

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

Notes

By default setDM sets the DM (#petsc4py.PETSc.DM) as active, so call setDMActive(KSP.DMactive.ALL, False) after setDM(dm) to not have the KSP object use the DM (#petsc4py.PETSc.DM) to generate the matrices.

🙈 Yeah, setDM flips it on by default. If that's not the vibe, you go back and turn it off yourself, no notes.

See also 💜

Source code at petsc4py/PETSc/KSP.pyx:715 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L715

setErrorIfNotConverged(flag) 😭

Make the solve throw an error if it doesn't converge. Main character energy: no silent failure, we scream instead. 👑

Logically collective.

Parameters

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

See also 🌈

Source code at petsc4py/PETSc/KSP.pyx:1942 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1942

setFromOptions() ⭐

Pull KSP options straight out of the options database. Collective cute. 🎀

Collective.

This routine must be called before setUp if the user is to be allowed to set the Krylov type.

💅 Translation: options first, setUp second. Flip that order and the Krylov type is already locked in, bestie.

See also 🫶

Source code at petsc4py/PETSc/KSP.pyx:610 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L610

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

setGMRESRestart(restart) 🌀

Set the number of iterations at which KSP restarts. Not a vibe reset, an iteration reset — she's just built different.

Logically collective.

Suitable KSPs are: KSPGMRES, KSPFGMRES and KSPLGMRES.

Parameters

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

See also 💫

Source code at petsc4py/PETSc/KSP.pyx:2146 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2146

setHPDDMType(hpddm_type) 🧚

Set the Krylov solver type. Yeah she said what she said. Collective.

Collective.

Parameters

  • hpddm_type (HPDDMType, #petsc4py.PETSc.KSP.HPDDMType) — The type of Krylov solver to use.

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

See also 🌸

Source code at petsc4py/PETSc/KSP.pyx:1910 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1910

setInitialGuessKnoll(flag) 🔮

Tell the solver to use PC.apply (#petsc4py.PETSc.PC.apply) to compute the initial guess.

Logically collective.

This is the Knoll trick. ✨ Yes it has a name. Yes it's iconic.

Parameters

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

See also 💜

Source code at petsc4py/PETSc/KSP.pyx:1544 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1544

setInitialGuessNonzero(flag) 🙈

Tell the iterative solver that the initial guess is nonzero. This is you telling her "girl, the working array already has data in it, don't touch it."

Logically collective.

Otherwise KSP assumes the initial guess is to be zero (and thus zeros it out before solving).

😭 No fr, if you skip this, your carefully prepared guess gets wiped. Zeroed. Gone. Poof.

Parameters

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

See also 🦋

Source code at petsc4py/PETSc/KSP.pyx:1508 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1508

setIterationNumber(its) ⭐

Use its property. Short, sweet, slays.

Source code at petsc4py/PETSc/KSP.pyx:1863 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1863

Parameters

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

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

Set an additional function to monitor the residual.

Logically collective.

Set an ADDITIONAL function to be called at every iteration to monitor the residual/error etc.

Parameters

  • monitor (KSPMonitorFunction) — the callback that keeps an eye on your convergence 👀 it's giving supervisor energy, honestly.
  • args (tuple[Any, ...] | None) — positional arguments you're handing over to that callback function.
  • kargs (dict[str, Any] | None) — keyword arguments for the callback function, same vibe.

Return type

None 💁

Notes

The default is literally do nothing — no monitor, no thoughts, just vibes 🌸 If you do want the residual printed (or the preconditioned residual, if setNormType(NORM_PRECONDITIONED) got called), then pass monitor as your monitoring routine, with a PETSc.Viewer.ASCII as the context. That's the combo, bestie 🫶

And you are not limited to one, btw!! You can set several different monitoring routines by calling setMonitor multiple times, and every single one gets called, in the exact order you set them in. Stack them like friendship bracelets ✨

See also

Source code at petsc4py/PETSc/KSP.pyx:1233 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1233

setNormType(normtype)

Sets the norm that gets used for convergence testing. Logically collective, so everybody's on the same page 🎀

Parameters

  • normtype (NormType) — the norm type you wanna use (see NormType).

Return type

None

Notes

Not all combinations of preconditioner side (see setPCSide) and norm type are supported by all Krylov methods. That's just how it is 💀 If only one of them is set, PETSc tries to automatically change the other one to find a compatible pair. And if no such combination exists? PETSc will generate an error, periodt.

See also

Source code at petsc4py/PETSc/KSP.pyx:1377 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1377

setOperators(A=None, P=None)

Set the matrix associated with the linear system. Collective, so like, everyone participates 💅

So what it does is: it sets the matrix for your linear system, and a possibly-different one that the preconditioner is gonna get built from. Two matrices, one job.

Parameters

  • A (Mat | None) — the matrix that defines the linear system.
  • P (Mat | None) — the matrix used when constructing the preconditioner — usually the same as A.

Return type

None

Notes

This is equivalent to pc = ksp.getPC(); pc.setOperators(A, P) but it's the preferred approach. Do it the cute way ✨

If you know your operator A has a null space, you can use Mat.setNullSpace and Mat.setTransposeNullSpace to hand that null space over to A, and the KSP solvers will automatically use it as needed during the solution process. Iconic behaviour.

All future calls to setOperators must use the same size matrices! Like, no switching up the size on us mid-run, that's not the move 😭

Passing None for A or P removes the matrix that's currently being used. Yeet 🦋

See also

Source code at petsc4py/PETSc/KSP.pyx:820 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L820

setOptionsPrefix(prefix)

Sets the prefix used for all KSP options in the database. Logically collective 🌈

Parameters

  • prefix (str | None) — the options prefix.

Return type

None

Notes

A hyphen (-) must NOT be given at the beginning of the prefix name!! Literally do not. The first character of all runtime options is AUTOMATICALLY the hyphen. It handles that for you, bestie, have some faith 🙈

So for example, to tell the difference between the runtime options for two different KSP contexts, you could call:

KSPSetOptionsPrefix(ksp1, "sys1_")
KSPSetOptionsPrefix(ksp2, "sys2_")

This would enable the use of different options for each system, like:

-sys1_ksp_type gmres -sys1_ksp_rtol 1.e-3 -sys2_ksp_type bcgs -sys2_ksp_rtol 1.e-4

Two systems, two whole personalities, zero collisions 🔥

See also

Source code at petsc4py/PETSc/KSP.pyx:533 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L533

setPC(pc)

Set the preconditioner. Collective 💖

It sets the preconditioner that's gonna be used to calculate the application of the preconditioner on a vector. That's the whole job description.

Parameters

  • pc (PC) — the preconditioner object.

Return type

None

See also

Source code at petsc4py/PETSc/KSP.pyx:891 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L891

setPCSide(side)

Set the preconditioning side. Logically collective 💫

Parameters

  • side (Side) — the preconditioning side (see PC.Side).

Return type

None

Notes

Left preconditioning is the default for most Krylov methods — except Type.FGMRES, which only supports right preconditioning. So don't come for FGMRES about its choices, okay 😌

For methods, changing the side of the preconditioner changes the norm type that's used — see setNormType.

Symmetric preconditioning is currently available only for the Type.QCG method. Note, though, that symmetric preconditioning can be emulated by using either right or left preconditioning plus a pre or post processing step. So like, you can get the look without the label 💅

Setting the PC side often affects the default norm type. See setNormType for the deets.

See also

Source code at petsc4py/PETSc/KSP.pyx:1329 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1329

setPostSolve(postsolve, args=None, kargs=None)

Sets the function that gets called at the end of every KSP.solve. Logically collective ⭐

Parameters

  • postsolve (KSPPostSolveFunction | None) — the callback function.
  • args — tuple[Any, ...] | None — the positional arguments you're handing to the callback function 🎀
  • kargs — dict[str, Any] | None — the keyword arguments for the callback function, for when you wanna be all "here's the tea, by name" ✨

Return type

None

literally nothing comes back out. it just does the thing. periodt. 💅

See also: solve, KSPSetPreSolve, KSPSetPostSolve

Source code at petsc4py/PETSc/KSP.pyx:1684

✨ setPreSolve(presolve, args=None, kargs=None) ✨

okay so bestie, this one is the setup moment of the vibe. it sets the function that gets called at the beginning of each KSP.solve. like, before the solver even starts cooking, your callback gets tapped in. 🫶

Logically collective.

Parameters

  • presolve — KSPPreSolveFunction | None — The callback function. hand it over here, or pass None if you want nothing happening. 🙈
  • args — tuple[Any, ...] | None — Positional arguments for the callback function.
  • kargs — dict[str, Any] | None — Keyword arguments for the callback function.

Return type

None

See also: solve, KSPSetPreSolve, KSPSetPostSolve

Source code at petsc4py/PETSc/KSP.pyx:1651

🦋 setPythonContext(context=None) 🦋

sets the instance of the class that's implementing your Python methods. it's the "who is doing the python things" slot, and you're filling it with your own fabulous object. 🌸

Not collective. — so like, no group chat on this one, it's a you-and-your-object situation.

See also: PETSc Python linear solver type, getPythonContext

Source code at petsc4py/PETSc/KSP.pyx:2197

Parameters

  • context — Any | None

Return type

None

👑 setPythonType(py_type) 👑

sets the fully qualified Python name of the class to be used. like the full government name, module.ClassName, no nicknames. no cap. 💅

Collective. — everybody in the communicator is in on this decision, we move as a unit. 🫶

See also: PETSc Python linear solver type, setPythonContext, getPythonType, KSPPythonSetType

Source code at petsc4py/PETSc/KSP.pyx:2224

Parameters

  • py_type — str

Return type

None

🌈 setResidualNorm(rnorm) 🌈

short and sweet: Use norm property. that's literally it. the whole instructions. iconic, honestly. 💖

Source code at petsc4py/PETSc/KSP.pyx:1874

Parameters

  • rnorm — float

Return type

None

🎀 setTolerances(rtol=None, atol=None, divtol=None, max_it=None) 🎀

sets various tolerances used by the KSP convergence testers — the lil thresholds that decide "bestie you're done" vs "bestie keep going" vs "bestie what are you doing". 😭

Logically collective.

it sets the relative, absolute, divergence, and maximum iteration tolerances used by the default KSP convergence testers. so basically you're tuning the whole vibe-check apparatus. 🔥

Parameters

  • rtol — float | None — The relative convergence tolerance, relative decrease in the (possibly preconditioned) residual norm. Or DETERMINE to use the value when the object's type was set. ✨
  • atol — float | None — The absolute convergence tolerance, absolute size of the (possibly preconditioned) residual norm. Or DETERMINE to use the value when the object's type was set.
  • dtol — The divergence tolerance, amount the (possibly preconditioned) residual norm can increase before KSPConvergedDefault concludes that the method is diverging. Or DETERMINE to use the value when the object's type was set. 💀 (yes this one shows up without a type annotation in the docs — not me, I'm just the messenger 🙈)
  • max_it — int | None — Maximum number of iterations to use. Or DETERMINE to use the value when the object's type was set.
  • divtol — float | None — (the docs also list it here separately, so here it is, faithfully reproduced, because I do not skip a single crumb 🍓)

Return type

None

Notes

Use None to retain the default value of any of the tolerances. so if you're like "nah, leave that one alone", None and let it be. 🧚

See also: Working with PETSc options, getTolerances, setConvergenceTest, KSPSetTolerances, KSPConvergedDefault

Source code at petsc4py/PETSc/KSP.pyx:928

⭐ setType(ksp_type) ⭐

builds the KSP data structure for a particular Type. this is the "which Krylov method are we actually running" moment. main character energy, honestly. 👑

Logically collective.

Parameters

  • ksp_type — Type | str — KSP Type object.

Return type

None

Notes

See Type for available methods — for instance, Type.CG or Type.GMRES. pick your fighter. 🥊

Normally, it is best to use the setFromOptions command and then set the KSP type from the options database rather than by using this routine. Using the options database provides the user with maximum flexibility in evaluating the many different Krylov methods.

This method is provided for those situations where it is necessary to set the iterative solver independently of the command line or options database. This might be the case, for example, when the choice of iterative solver changes during the execution of the program, and the user's application is taking responsibility for choosing the appropriate method.

In other words, this routine is not for beginners. she said it, not me!! 😭 but fr fr, if you're new here, go through the options database and let it cook. 💅

See also: KSPSetType — https://petsc.org/release/manualpages/KSP/KSPSetType.html

Source code at petsc4py/PETSc/KSP.pyx:483 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L483

setUp() 💅

Set up internal data structures for an iterative solver. Yes bestie, this is the "get your solver ready to actually do something" move.

Collective. (which means everybody in the communicator has to call it, no skipping, fr fr.)

See also: KSPSetUp — https://petsc.org/release/manualpages/KSP/KSPSetUp.html

Source code at petsc4py/PETSc/KSP.pyx:1609 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1609

Return type: None — https://docs.python.org/3/builtins/constants.html#None

setUpOnBlocks() 🧱

Set up the preconditioner for each block in a block method. It's giving "I do the prep work block by block so the solve doesn't fall apart."

Collective.

The methods this cares about include: block Jacobi, block Gauss-Seidel, and overlapping Schwarz methods. That trio, specifically. 🌈

See also: KSPSetUpOnBlocks — https://petsc.org/release/manualpages/KSP/KSPSetUpOnBlocks.html

Source code at petsc4py/PETSc/KSP.pyx:1636 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1636

Return type: None — https://docs.python.org/3/builtins/constants.html#None

setUseFischerGuess(model, size) 🧚

Use the Paul Fischer algorithm to compute initial guesses. Lowkey iconic — you're not starting from zero, you're starting from vibes informed by past solves.

Logically collective.

Use the Paul Fischer algorithm or its variants to compute initial guesses for a set of solves with related right hand sides. (Read that again — related right hand sides. That's the whole point, bestie.)

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: KSPSetUseFischerGuess — https://petsc.org/release/manualpages/KSP/KSPSetUseFischerGuess.html

Source code at petsc4py/PETSc/KSP.pyx:1581 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1581

solve(b, x) 🔥

Solve the linear system. This is the main character moment of the whole module, obviously. 💅

Collective.

Parameters

  • b (Vec — #petsc4py.PETSc.Vec) — Right hand side vector.
  • x (Vec — #petsc4py.PETSc.Vec) — Solution vector.

Return type: None — https://docs.python.org/3/builtins/constants.html#None

Notes 📝

If one uses setDM then x or b need not be passed. Use getSolution to access the solution in this case. (So like, you can be hands-off about it if you want.)

The operator is specified with setOperators.

⚠️ Okay this is the important bit, bestie, listen up: solve will normally return without generating an error regardless of whether the linear system was solved or if constructing the preconditioner failed. It's just gonna vibe there, looking innocent. 😭 Call getConvergedReason to determine if the solver converged or failed and why. The option -ksp_error_if_not_converged or function setErrorIfNotConverged will cause solve to error as soon as an error occurs in the linear solver. In inner solves, DIVERGED_MAX_IT is not treated as an error because when using nested solvers it may be fine that inner solvers in the preconditioner do not converge during the solution process. (Translation: inner solvers get a pass. They're not flaky, they're doing their best.)

The number of iterations can be obtained from its.

If you provide a matrix that has a Mat.setNullSpace (#petsc4py.PETSc.Mat.setNullSpace) and Mat.setTransposeNullSpace (#petsc4py.PETSc.Mat.setTransposeNullSpace) this will use that information to solve singular systems in the least squares sense with a norm minimizing solution. Slay.

Ax = b where b = bₚ + bₜ where bₜ is not in the range of A (and hence by the fundamental theorem of linear algebra is in the nullspace(Aᵀ), see Mat.setNullSpace (#petsc4py.PETSc.Mat.setNullSpace).

KSP first removes bₜ producing the linear system Ax = bₚ (which has multiple solutions) and solves this to find the ∥x∥ minimizing solution (and hence it finds the solution x orthogonal to the nullspace(A). The algorithm is simply in each iteration of the Krylov method we remove the nullspace(A) from the search direction thus the solution which is a linear combination of the search directions has no component in the nullspace(A).

We recommend always using Type.GMRES (#petsc4py.PETSc.KSP.Type.GMRES) for such singular systems. Always. GMRES. Bestie, trust. If nullspace(A) = nullspace(Aᵀ) (note symmetric matrices always satisfy this property) then both left and right preconditioning will work. If nullspace(A) != nullspace(Aᵀ) then left preconditioning will work but right preconditioning may not work (or it may). 🙈 Yeah. It's giving "unspecified."

If using a direct method (e.g., via the KSP solver Type.PREONLY (#petsc4py.PETSc.KSP.Type.PREONLY) and a preconditioner such as PC.Type.LU (#petsc4py.PETSc.PC.Type.LU) or PC.Type.ILU (#petsc4py.PETSc.PC.Type.ILU), then its=1. See setTolerances for more details.

Understanding Convergence 🧠

The routines setMonitor and computeEigenvalues provide information on additional options to monitor convergence and print eigenvalue information. Use them if you're nosy about how it's converging, not just that it converged. 👑

See also: create, setUp, destroy, setTolerances, is_converged, solveTranspose, its, Mat.setNullSpace (#petsc4py.PETSc.Mat.setNullSpace), Mat.setTransposeNullSpace (#petsc4py.PETSc.Mat.setTransposeNullSpace), Type (#petsc4py.PETSc.KSP.Type), setErrorIfNotConverged, KSPSolve — https://petsc.org/release/manualpages/KSP/KSPSolve.html

Source code at petsc4py/PETSc/KSP.pyx:1717 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1717

solveTranspose(b, x) 🔄

Solve the transpose of a linear system. Same energy as solve, just flipped. 🦋

Collective.

Parameters

  • b (Vec — #petsc4py.PETSc.Vec) — Right hand side vector.
  • x (Vec — #petsc4py.PETSc.Vec) — Solution vector.

Return type: None — https://docs.python.org/3/builtins/constants.html#None

Notes 📝

For complex numbers this solve the non-Hermitian transpose system. (Not the Hermitian one. The other one. Don't mix them up, iykyk.)

See also: solve, KSPSolveTranspose — https://petsc.org/release/manualpages/KSP/KSPSolveTranspose.html

Source code at petsc4py/PETSc/KSP.pyx:1798 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L1798

view(viewer=None) 👀

Print the KSP data structure. Sometimes you just gotta look at it, bestie.

Collective.

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: KSPView — https://petsc.org/release/manualpages/KSP/KSPView.html

Source code at petsc4py/PETSc/KSP.pyx:435 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L435

✨ Attributes Documentation ✨

Okay so these are the attributes, and they're all just little handles to the solver's internal state. Grab them like properties, that's the vibe. 💖

appctx 🎀

The solver application context.

Source code at petsc4py/PETSc/KSP.pyx:2256 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2256

atol 🎯

The absolute tolerance of the solver.

Source code at petsc4py/PETSc/KSP.pyx:2349 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2349

divtol 💀

The divergence tolerance of the solver.

Source code at petsc4py/PETSc/KSP.pyx:2357 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2357

dm 🗺️

The solver DM (#petsc4py.PETSc.DM).

Source code at petsc4py/PETSc/KSP.pyx:2266 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2266

guess_knoll 🧙

Whether solver uses Knoll trick.

Source code at petsc4py/PETSc/KSP.pyx:2308 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2308

guess_nonzero 🙈

Whether guess is non-zero.

Source code at petsc4py/PETSc/KSP.pyx:2300 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2300

history 📈

The convergence history of the solver.

Source code at petsc4py/PETSc/KSP.pyx:2391 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2391

  • is_converged — bool moment fr: is the solver converged or not. Asking is_converged is the vibe check of a lifetime.

Source code at petsc4py/PETSc/KSP.pyx:2411 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2411>

  • is_diverged — bool telling you if the solver straight up failed. not the slay we wanted, but okay.

Source code at petsc4py/PETSc/KSP.pyx:2416 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2416>

  • is_iterating — bool saying the solver has not converged yet. It's still cooking. Gives "we're not there yet bestie" energy.

Source code at petsc4py/PETSc/KSP.pyx:2406 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2406>

  • its — the current number of iterations the solver has taken. Its iteration count, lowkey the plot of the whole story.

Source code at petsc4py/PETSc/KSP.pyx:2375 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2375>

  • mat_op — the system matrix operator. the main character matrix.

Source code at petsc4py/PETSc/KSP.pyx:2288 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2288>

  • mat_pc — the preconditioner operator. the matrix that preps you before the real work. ✨

Source code at petsc4py/PETSc/KSP.pyx:2293 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2293>

  • max_it — the maximum number of iterations the solver may take. its hard limit. it's giving "you get this many tries, bestie."

Source code at petsc4py/PETSc/KSP.pyx:2365 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2365>

  • norm — the norm of the residual at the current iteration. how big is the oopsie right now.

Source code at petsc4py/PETSc/KSP.pyx:2383 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2383>

  • norm_type — the norm the solver uses. which flavour of "measure the vibe" we picked.

Source code at petsc4py/PETSc/KSP.pyx:2331 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2331>

  • pc — the PC <#petsc4py.PETSc.PC> of the solver. its personal pregame routine.

Source code at petsc4py/PETSc/KSP.pyx:2318 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2318>

  • pc_side — the side on which preconditioning is performed. left? right? it's a whole orientation thing. 💅

Source code at petsc4py/PETSc/KSP.pyx:2323 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2323>

  • reason — the converged reason. the "why are we here" of the solver's arc.

Source code at petsc4py/PETSc/KSP.pyx:2398 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2398>

  • rtol — the relative tolerance of the solver. how picky it is. 🔍

Source code at petsc4py/PETSc/KSP.pyx:2341 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2341>

  • vec_rhs — the right-hand side vector. the homework we got handed.

Source code at petsc4py/PETSc/KSP.pyx:2281 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2281>

  • vec_sol — the solution vector. the answer. the glow-up. the finale. 🎀

Source code at petsc4py/PETSc/KSP.pyx:2276 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/KSP.pyx#L2276>

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

petsc4py.PETSc.KSPDMActive

class petsc4py.PETSc.KSPDMActive Bases: object — <https://docs.python.org/3/builtins/functions.html#object>

Okay so this one is literally just an argument pass-along for KSPSetDMActive(). That's the whole job description. Iconic, honestly.

Attributes Summary

Attributes Documentation

petsc4py.PETSc.LGMap

class petsc4py.PETSc.LGMap Bases: Object <#petsc4py.PETSc.Object>

A mapping from a local ordering to a global ordering. Like, "this is what I call it, this is what the world calls it." Translating between your little local world and the big global one. 🦋

See also:

Enumerations

  • MapMode <#petsc4py.PETSc.LGMap.MapMode> — Enum describing mapping behavior when global indices are missing.
  • Type <#petsc4py.PETSc.LGMap.Type> — Local to global map types.

petsc4py.PETSc.LGMap.MapMode

class petsc4py.PETSc.LGMap.MapMode Bases: object — <https://docs.python.org/3/builtins/functions.html#object>

An enum that says what happens when global indices go missing. like, they didn't show up to the function. rude. so what do we do about it?

  • MASK — give missing global indices a local index of -1.
  • DROP — drop missing global indices. gone. ghosted. 👻

See also:

Attributes Summary

Attributes Documentation

petsc4py.PETSc.LGMap.Type

class petsc4py.PETSc.LGMap.Type Bases: object — <https://docs.python.org/3/builtins/functions.html#object>

Local to global map types. the flavours of map you can have. stay tuned bestie, there's more coming 💖

❤️ Attributes Summary ❤️

okay so before we get to the actual methods, bestie, LGMap has two class-level attributes and they're both just plain old str. no drama, no spice, just strings 💅

📖 Attributes Documentation 📖

BASIC: str — https://docs.python.org/3/builtins/stdtypes.html#str = BASIC

Object BASIC of type str — https://docs.python.org/3/builtins/stdtypes.html#str

it's literally just the string BASIC, serving as the value. iconic, unbothered, simple 🎀

HASH: str — https://docs.python.org/3/builtins/stdtypes.html#str = HASH

Object HASH of type str — https://docs.python.org/3/builtins/stdtypes.html#str

and this one is just the string HASH. two whole attributes, both vibes, both strings. periodt ✨

__init__()

classmethod __new__(*args, **kwargs)

so like, the classic two-step — __init__() takes no documented arguments here, and __new__ is a classmethod that takes *args, **kwargs and does the actual object-making moment. main character energy fr fr 🫶

⭐ Methods Summary ⭐

here's the whole menu of what LGMap can do for you, bestie. every single one, no skips:

  • apply(indices[, result]) — Convert a locally numbered list of integers to a global numbering.
  • applyBlock(indices[, result]) — Convert a local block numbering to a global block numbering.
  • applyBlockInverse(indices[, mode]) — Compute blocked local numbering from blocked global numbering.
  • applyIS(iset) — Create an index set with global numbering from a local numbering.
  • applyInverse(indices[, mode]) — Compute local numbering from global numbering.
  • create(indices[, bsize, comm]) — Create a local-to-global mapping.
  • createIS(iset) — Create a local-to-global mapping from an index set.
  • createSF(sf, start) — Create a local-to-global mapping from a star forest.
  • destroy() — Destroy the local-to-global mapping.
  • getBlockIndices() — Return the global indices for each local block.
  • getBlockInfo() — Determine the block indices shared with neighboring processes.
  • getBlockSize() — Return the block size of the local-to-global mapping.
  • getIndices() — Return the global indices for each local point in the mapping.
  • getInfo() — Determine the indices shared with neighboring processes.
  • getSize() — Return the local size of the local-to-global mapping.
  • load(viewer) — Load a local-to-global mapping.
  • setFromOptions() — Set mapping options from the options database.
  • setType(lgmap_type) — Set the type of the local-to-global map.
  • view([viewer]) — View the local-to-global mapping.

okay like, the range of this class?? create it, apply it, block it, un-block it, inverse it, load it, view it, yeet it with destroy() 😭 truly the full lifecycle of a local-to-global mapping. obsessed.

🦋 Attributes Summary 🦋

and now the instance attributes — these are the lil properties you get to read off a live LGMap object. six of them, every one accounted for:

  • block_indices — The global indices for each local block in the mapping.
  • block_info — Mapping describing block indices shared with neighboring processes.
  • block_size — The block size.
  • indices — The global indices for each local point in the mapping.
  • info — Mapping describing indices shared with neighboring processes.
  • size — The local size.

see how indices/block_indices, info/block_info, and size/block_size come in lil pairs? it's giving symmetry 🌈 and every single one maps to a getter method you're about to meet. iykyk ✨

🔥 Methods Documentation 🔥

and babe, this is where it gets juicy — the full, method-by-method documentation is next. strap in, grab a snack, we're going deep 💖

apply(indices, result=None)

okay so this one takes a locally numbered list of integers and turns it into a global numbering 💫

Not collective — every process does its own lil thing, no group chat required.

Parameters

  • indices (Sequence[int]) — the input indices, in local numbering, bestie.
  • result (ArrayInt | None) — the array where the global numbering gets written. If it's None, a brand-new array gets allocated for you ✨

Returns — the indices in global numbering. If result wasn't None, then it gets returned right there instead 🫶

Return type — ArrayInt

See also: LGMap.applyBlock, ISLocalToGlobalMappingApply

Source code at petsc4py/PETSc/IS.pyx:1495

applyBlock(indices, result=None)

same energy as apply but make it block numbering 💅 it converts a local block numbering into a global block numbering.

Not collective.

Parameters

  • indices (Sequence[int]) — input block indices in local numbering.
  • result (ArrayInt | None) — array to write the global numbering into. None means a fresh array gets allocated 🎀

Returns — block indices in global numbering. If result is not None, it's returned here instead.

Return type — ArrayInt

See also: LGMap.apply, ISLocalToGlobalMappingApplyBlock

Source code at petsc4py/PETSc/IS.pyx:1532

applyBlockInverse(indices, mode=None)

the reverse girlies rise 🦋 this computes a blocked local numbering from a blocked global numbering.

Not collective.

Parameters

  • indices (Sequence[int]) — indices that have a global block numbering.
  • mode (MapMode | str | None) — a flag telling us what to do with indices that have no local value. defaults to "mask".

Returns — indices with a local block numbering.

Return type — ArrayInt

See also: ISGlobalToLocalMappingApplyBlock

Source code at petsc4py/PETSc/IS.pyx:1633

applyIS(iset)

makes you a whole index set with global numbering, starting from a local numbering. so iconic 💖

Collective — yes bestie, everybody's involved here.

Parameters

  • iset (IS) — index set with local numbering.

Returns — index set with global numbering.

Return type — IS

See also: ISLocalToGlobalMappingApplyIS

Source code at petsc4py/PETSc/IS.pyx:1569

applyInverse(indices, mode=None)

the flip side 🔄 computes the local numbering from a global numbering.

Not collective.

Parameters

  • indices (Sequence[int]) — indices with a global numbering.
  • mode (MapMode | str | None) — flag for what to do with indices that have no local value. defaults to "mask".

Returns — indices with a local numbering.

Return type — ArrayInt

See also: ISGlobalToLocalMappingApply

Source code at petsc4py/PETSc/IS.pyx:1594

create(indices, bsize=None, comm=None)

this one creates a local-to-global mapping. main character constructor energy 👑

Not collective.

Parameters

  • indices (Sequence[int]) — the global index for each local element.
  • bsize (int | None) — block size. defaults to 1.
  • comm (Comm | None) — MPI communicator. defaults to Sys.getDefaultComm.

Return type — Self

See also: ISLocalToGlobalMappingCreate

Source code at petsc4py/PETSc/IS.pyx:1278

createIS(iset)

builds a local-to-global mapping straight out of an index set 🌸

Not collective.

Parameters

  • iset (IS) — index set holding the global numbers for each local number.

Return type — Self

See also: ISLocalToGlobalMappingCreateIS

Source code at petsc4py/PETSc/IS.pyx:1313

createSF(sf, start)

mapping from a star forest ✨ (yes that's really the name, and honestly? slay) builds a local-to-global mapping out of one.

Collective.

Parameters

  • sf (SF) — star forest mapping contiguous local indices to (rank, offset).
  • start (int) — first global index on this process.

Return type — Self

See also: ISLocalToGlobalMappingCreateSF

Source code at petsc4py/PETSc/IS.pyx:1334

destroy()

and when you're done with the local-to-global mapping... you destroy it 💀 clean up after yourself bestie, it's giving responsible.

Not collective.

See also: ISLocalToGlobalMappingDestroy

Source code at petsc4py/PETSc/IS.pyx:1265

Return type: Self (that's the typing.Self vibe, check it: https://docs.python.org/3/library/typing.html#typing.Self) ✨

getBlockIndices()

So this one is giving you the global indices for each local block. 💅 It's not collective, so it's just you and your local data, bestie. No need to sync with the squad.

See also: ISLocalToGlobalMappingGetBlockIndices (https://petsc.org/release/manualpages/IS/ISLocalToGlobalMappingGetBlockIndices.html)

Source code: petsc4py/PETSc/IS.pyx:1409 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L1409)

Return type: ArrayInt

getBlockInfo()

Bestie, this one figures out the block indices that are shared with neighboring processes. 🌐 It's collective, so everyone's involved.

Returns: a mapping from neighboring processor number to an array of shared block indices (in local numbering).

Return type: dict

See also: ISLocalToGlobalMappingGetBlockInfo (https://petsc.org/release/manualpages/IS/ISLocalToGlobalMappingGetBlockInfo.html)

Source code: petsc4py/PETSc/IS.pyx:1464 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L1464)

getBlockSize()

Returns the block size of the local-to-global mapping. It's not collective, so you're good on your own. 🧚

See also: ISLocalToGlobalMappingGetBlockSize (https://petsc.org/release/manualpages/IS/ISLocalToGlobalMappingGetBlockSize.html)

Source code: petsc4py/PETSc/IS.pyx:1371 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L1371)

Return type: int

getIndices()

Gives you the global indices for each local point in the mapping. 💖 Not collective, so no group chat needed.

See also: ISLocalToGlobalMappingGetIndices (https://petsc.org/release/manualpages/IS/ISLocalToGlobalMappingGetIndices.html)

Source code: petsc4py/PETSc/IS.pyx:1385 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L1385)

Return type: ArrayInt

getInfo()

This one figures out the indices shared with neighboring processes. 🌈 Collective, so everybody's in the mix.

Returns: a mapping from neighboring processor number to an array of shared indices (in local numbering).

Return type: dict

See also: ISLocalToGlobalMappingGetInfo (https://petsc.org/release/manualpages/IS/ISLocalToGlobalMappingGetInfo.html)

Source code: petsc4py/PETSc/IS.pyx:1435 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L1435)

getSize()

Returns the local size of the local-to-global mapping. 📏 Not collective, so it's just your local size.

See also: ISLocalToGlobalMappingGetSize (https://petsc.org/release/manualpages/IS/ISLocalToGlobalMappingGetSize.html)

Source code: petsc4py/PETSc/IS.pyx:1357 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L1357)

Return type: int

load(viewer)

Loads a local-to-global mapping from a viewer. 🎀 Collective, so everyone's involved.

See also: view, ISLocalToGlobalMappingLoad (https://petsc.org/release/manualpages/IS/ISLocalToGlobalMappingLoad.html)

Source code: petsc4py/PETSc/IS.pyx:1247 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L1247)

Parameters:

  • viewer (Viewer) — the viewer to load from.

Return type: Self

setFromOptions()

Sets mapping options from the options database. 🛠️ Not collective, so it's just you configuring your own stuff.

See also: Working with PETSc options, ISLocalToGlobalMappingSetFromOptions (https://petsc.org/release/manualpages/IS/ISLocalToGlobalMappingSetFromOptions.html)

Source code: petsc4py/PETSc/IS.pyx:1216 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L1216)

Return type: None

setType(lgmap_type)

Sets the type of the local-to-global map. 🌟 Logically collective, so it's like everyone agrees on the vibe.

Parameters:

  • lgmap_type (Type | str) — The type of the local-to-global mapping.

Return type: None

Notes:

Use -islocaltoglobalmapping_type to set the type in the options database. 💁‍♀️

See also: Working with PETSc options, ISLocalToGlobalMappingSetType (https://petsc.org/release/manualpages/IS/ISLocalToGlobalMappingSetType.html)

Source code: petsc4py/PETSc/IS.pyx:1192 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L1192)

view(viewer=None)

Views the local-to-global mapping. 👀 Not collective, so you can peek at your own mapping.

Parameters:

  • viewer (Viewer | None) — Viewer instance, defaults to an instance of Viewer.Type.ASCII.

Return type: None

See also: load, ISLocalToGlobalMappingView (https://petsc.org/release/manualpages/IS/ISLocalToGlobalMappingView.html)

Source code: petsc4py/PETSc/IS.pyx:1228 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/IS.pyx#L1228)

Attributes Documentation

__init__()

No description, just the init. You know how it is. 💁‍♀️

classmethod __new__(*args, **kwargs)

The new-style classmethod. ✨

isActive()</p> 💫

Return whether logging is currently in progress.

Like, is the whole logging apparatus on right now or are we just sitting here in the dark bestie 😭 That's the entire vibe check this one does.

and that's where this part of the tea ends, no cap 🌸

Not collective, bestie — this one's a solo vibe, no group chat required. 💅

See also: PetscLogIsActive — https://petsc.org/release/manualpages/Log/PetscLogIsActive.html

Source code at: petsc4py/PETSc/Log.pyx:255 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L255

Return type: bool — https://docs.python.org/3/builtins/functions.html#bool

✨ classmethod logFlops(flops) ✨

Okay so this one adds floating point operations to the current event. It's giving “math but make it loggable.” 🔥

Not collective — again, solo mission, no group chat.

Parameters:

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: PetscLogFlops — https://petsc.org/release/manualpages/Log/PetscLogFlops.html

Source code at: petsc4py/PETSc/Log.pyx:151 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L151

🖨️ classmethod view(viewer=None) 🖨️

Prints the log. Yep, it's the “show me the receipts” method. 🧾

Collective — everyone hop in the group chat for this one.

Parameters:

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: Working with PETSc options — #petsc-options, PetscLogView — https://petsc.org/release/manualpages/Log/PetscLogView.html

Source code at: petsc4py/PETSc/Log.pyx:130 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L130

__init__()

classmethod __new__(*args, **kwargs)

🧵 petsc4py.PETSc.LogClass 🧵

class petsc4py.PETSc.LogClass

Bases: object — https://docs.python.org/3/builtins/functions.html#object

Logging support. 💖

📋 Methods Summary

  • activate() — Activate the log class.
  • deactivate() — Deactivate the log class.
  • getActive() — Not implemented.
  • getName() — Return the log class name.
  • setActive(flag) — Activate or deactivate the log class.

🏷️ Attributes Summary

  • active — Log class activation.
  • id — The log class identifier.
  • name — The log class name.

📚 Methods Documentation

activate()

Activate the log class. It's giving “turn it on.” ✨

deactivate()

Deactivate the log class. Opposite vibe. 🙈

getActive()

Not implemented. Yeah, it's a no. 💀

getName()

Returns the log class name. So you can call it by name, literally. 💅

setActive(flag)

Activates or deactivates the log class. Flip the switch, bestie. 🔘

🏷️ Attributes Documentation

active

Log class activation. It's giving “are you on?” vibe.

id

The log class identifier. Your log class's little ID card. 🪪

name

The log class name. The government name, if you will. 📛

__init__()

classmethod __new__(*args, **kwargs)

🎉 petsc4py.PETSc.LogEvent 🎉

class petsc4py.PETSc.LogEvent

Bases: object — https://docs.python.org/3/builtins/functions.html#object

Logging support. 💖

✨ Methods Summary ✨

okay bestie, here's the whole roster of what a log event can do, no gatekeeping 💅

  • activate() — Indicate that the event should be logged. (green light, go off 👑)
  • begin(*objs) — Log the beginning of a user event.
  • deactivate() — Indicate that the event should not be logged. (not today 💀)
  • end(*objs) — Log the end of a user event.
  • getActive() — Not implemented. 😭
  • getActiveAll() — Not implemented. 😭
  • getName() — The current event name.
  • getPerfInfo([stage]) — Get the performance information about the given event in the given event.
  • setActive(flag) — Indicate whether or not the event should be logged.
  • setActiveAll(flag) — Turn on logging of all events.

🎀 Attributes Summary 🎀

  • active — Event activation.
  • active_all — All events activation.
  • id — The log event identifier.
  • name — The current event name.

📝 Methods Documentation 📝

activate()

Indicate that the event should be logged. 💖

Logically collective. (so everybody in the crew has to be on the same page, no solo missions 🫶)

See also: PetscLogEventActivate (https://petsc.org/release/manualpages/Log/PetscLogEventActivate.html)

Source code at petsc4py/PETSc/Log.pyx:614 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L614)

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

begin(*objs)

Log the beginning of a user event. 🌸 this is you hitting start on the timer, bestie.

Collective. (everyone's doing it together ✨)

Parameters

  • *objs — objects associated with the event

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

See also: PetscLogEventBegin (https://petsc.org/release/manualpages/Log/PetscLogEventBegin.html)

Source code at petsc4py/PETSc/Log.pyx:558 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L558)

deactivate()

Indicate that the event should not be logged. 🙈 it's giving "we don't talk about this one".

Logically collective.

See also: PetscLogEventDeactivate (https://petsc.org/release/manualpages/Log/PetscLogEventDeactivate.html)

Source code at petsc4py/PETSc/Log.pyx:626 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L626)

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

end(*objs)

Log the end of a user event. 🌈 the stop button, the closing of the loop, the periodt.

Collective.

Parameters

  • *objs — Objects associated with the event.

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

See also: PetscLogEventEnd (https://petsc.org/release/manualpages/Log/PetscLogEventEnd.html)

Source code at petsc4py/PETSc/Log.pyx:577 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L577)

getActive()

Not implemented. 😭 that's it, that's the whole vibe.

Source code at petsc4py/PETSc/Log.pyx:638 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L638)

Return type: bool (https://docs.python.org/3/builtins/functions.html#bool)

getActiveAll()

Not implemented. 💀 not me expecting this one to work.

Source code at petsc4py/PETSc/Log.pyx:671 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L671)

Return type: bool (https://docs.python.org/3/builtins/functions.html#bool)

getName()

The current event name. 🏷️ just hands you the name, no drama, no cap.

Source code at petsc4py/PETSc/Log.pyx:597 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L597)

Return type: str (https://docs.python.org/3/builtins/stdtypes.html#str)

getPerfInfo(stage=None)

Get the performance information about the given event in the given event. 📊 yes bestie, it really does say "in the given event", I'm not making this up, I'm just the messenger 🧚

Not collective. (this one's a solo mission, you do you)

Parameters

Returns

  • info — This structure is filled with the performance information.

Return type: dict (https://docs.python.org/3/builtins/stdtypes.html#dict)

See also: PetscLogEventGetPerfInfo (https://petsc.org/release/manualpages/Log/PetscLogEventGetPerfInfo.html)

Source code at petsc4py/PETSc/Log.pyx:705 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L705)

setActive(flag)

Indicate whether or not the event should be logged. ✨ the general "you in or you out?" switch.

Logically collective.

Parameters

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

See also: PetscLogEventDeactivate (https://petsc.org/release/manualpages/Log/PetscLogEventDeactivate.html), PetscLogEventActivate (https://petsc.org/release/manualpages/Log/PetscLogEventActivate.html)

Source code at petsc4py/PETSc/Log.pyx:643 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L643)

setActiveAll(flag)

Turn on logging of all events. 👑 the "activate everyone, I want the whole group chat in here" button. main character energy, fr fr.

Logically collective.

Parameters

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

See also: PetscLogEventSetActiveAll (https://petsc.org/release/manualpages/Log/PetscLogEventSetActiveAll.html)

ok so heads up bestie: getActive() and getActiveAll() are literally just Not implemented. Don't come for me, I'm reporting the facts 💜 — the docs say what they say and the docs said nothing.

Source code at petsc4py/PETSc/Log.pyx:676 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L676

🦋 Attributes Documentation 🦋

okay so these are the attributes our LogEvent gives you, and bestie they're literally all just little handles into the logging machinery. no cap, here's the rundown 🫶

  • active — whether this event is activated. the vibe check on your event. 💅

Source code at petsc4py/PETSc/Log.pyx:663 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L663

  • active_all — the all-events activation switch. clocking the whole roster, not just one. 👑

Source code at petsc4py/PETSc/Log.pyx:695 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L695

  • id — the log event's identifier. its little ID card. 🎀

Source code at petsc4py/PETSc/Log.pyx:540 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L540

  • name — the current event's name. yes it says its own name out loud. main character behavior honestly. ✨

Source code at petsc4py/PETSc/Log.pyx:603 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L603

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

🌈 petsc4py.PETSc.LogStage 🌈

class petsc4py.PETSc.LogStage

Bases: object — https://docs.python.org/3/builtins/functions.html#object

Logging support for different stages. 🎭✨

like, if your program has Acts One, Two and Three, and you want the timers to know which act they're in — that's this. obsessed. 💖

🌸 Methods Summary 🌸

  • activate() — turn the stage ON. 💚
  • deactivate() — turn the stage OFF. 🙈
  • getActive() — peek whether the stage is activated. 👀
  • getName() — hand over the current stage name. 🏷️
  • getVisible() — tell you if the stage is visible. 🫣
  • pop() — pop a stage off the logging stack. 📤
  • push() — push a stage onto the logging stack. 📥
  • setActive(flag) — flip the current stage on or off. 🎚️
  • setVisible(flag) — set whether the stage is visible. ✨

🎀 Attributes Summary 🎀

  • active — whether the stage is activate. 💅
  • id — the log stage identifier. 🆔
  • name — the current stage name. 🏷️
  • visible — whether the stage is visible. 👁️

📖 Methods Documentation 📖

activate() — ACTIVATE THE STAGE 💚

okay so you're turning this stage on. that's it, that's the whole job, and it's a slay.

Logically collective — meaning every rank in the MPI crew has to agree on this, no freelancing. 🫂

See also:

Source code at petsc4py/PETSc/Log.pyx:341 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L341

Return type

deactivate() — DEACTIVATE THE STAGE 🙈

and this one turns the stage off. closing time, lights out, go home bestie. 😴

Logically collective. again — the whole MPI squad needs to be on the same page. 📖

See also:

Source code at petsc4py/PETSc/Log.pyx:353 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L353

Return type

getActive() — is this stage activated rn? 👀

just checks whether the stage is currently activated and tells you. no drama, no side effects.

Not collective — so this one you can just do on your own, it's giving independent queen energy. 💁‍♀️

See also:

Source code at petsc4py/PETSc/Log.pyx:365 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L365

Return type

getName() — what's this stage called? 🏷️

returns the current stage's name. yup. literally that. introducing… ✨the stage✨.

Source code at petsc4py/PETSc/Log.pyx:324 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L324

Return type

getVisible() — is this stage visible?? 🫣

returns whether the stage is visible. invisible stages are lowkey the wallflowers of logging. 👻

Not collective — solo mission, go off. 💃

See also:

Source code at petsc4py/PETSc/Log.pyx:403 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L403

Return type

pop() — pop a stage from the logging stack 📤

takes a stage off the top of the logging stack. like popping a filter, but for stages. 🧚

Logically collective, bestie — everyone's popping together, synchronized. 🎶

See also:

Source code at petsc4py/PETSc/Log.pyx:309 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L309

Return type

push() — push a stage onto the logging stack 📥

the inverse glowup of pop() — you're stacking a stage on top so everything after it gets logged to that stage. the way it just works. 💅

Logically collective, so mind your timing with the crew. 🫶

See also:

Source code at petsc4py/PETSc/Log.pyx:297 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L297

Return type

setActive(flag) — flip the current stage on/off 🎚️

sets whether the current stage is activated. you're the DJ, this is your switch. 🎧

Logically collective. everyone in the collective has to be vibing on the same setting. 🌈

See also:

Source code at petsc4py/PETSc/Log.pyx:379 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L379

Parameters

Return type

setVisible(flag) — make the stage visible or nah ✨

sets the visibility of the stage. spotlight on, or spotlight off. either way you're still iconic. 🌟

Logically collective, so the whole team sees it (or doesn't) together. 👑

Parameters

Return type

See also:

…and that last one's source code lives at petsc4py/PETSc/Log.pyx:417, full URL for the nosy girlies: https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Log.pyx#L417

🎀 Attributes Documentation 🎀

okay bestie, here's the whole lil' attribute roster for that stage thing 💅

And the dunder-y bits:

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

🦋 petsc4py.PETSc.Mat 🦋

class petsc4py.PETSc.Mat

Bases: Object — a.k.a. petsc4py.PETSc.Object, if you wanna trace the family tree 🌳

So this is the Matrix object. Yes bestie, THE matrix. The one that ate 💅

Mat is described in the PETSc manual → https://petsc.org/release/manual/mat.html

See also:

⭐ Enumerations ⭐

okay so Mat comes with a whole squad of enums, and here's the roster, each with its one-line lore:

  • AssemblyType — matrix assembly type.
  • DuplicateOption — matrix duplicate option.
  • FactorShiftType — factored matrix shift type.
  • InfoType — matrix info type.
  • Option — matrix option.
  • OrderingType — factored matrix ordering type.
  • SORType — matrix SOR type.
  • SolverType — factored matrix solver type.
  • Stencil — associate structured grid coordinates with matrix indices.
  • Structure — matrix modification structure.
  • Type — matrix type.

🌸 petsc4py.PETSc.Mat.AssemblyType 🌸

class petsc4py.PETSc.Mat.AssemblyType

Bases: object → https://docs.python.org/3/builtins/functions.html#object

Matrix assembly type. Yeah, it's literally about how you assemble the matrix, no cap.

See also:

🎀 Attributes Summary 🎀

Four lil' constants, all of them straight-up int, here's the lineup:

💖 Attributes Documentation 💖

And the obligatory dunders:

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

🍓 petsc4py.PETSc.Mat.DuplicateOption 🍓

class petsc4py.PETSc.Mat.DuplicateOption

Bases: object → https://docs.python.org/3/builtins/functions.html#object

Matrix duplicate option. Yep, exactly what it sounds like — the options you got when you're duplicating a matrix. Copy-paste but make it PETSc ✨

See also:

✨ Attributes Summary ✨

okay so this class has three constants on it and literally all three are plain Python ints, no cap:

💅 Attributes Documentation 💅

and also:

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

💜 petsc4py.PETSc.Mat.FactorShiftType 💜

class petsc4py.PETSc.Mat.FactorShiftType

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

Factored matrix shift type. That's the whole vibe — it's the shift you apply to a matrix that's already been factored. 🧚

See also:

🎀 Attributes Summary 🎀

six constants, all ints, all iconic:

✨ Attributes Documentation ✨

and also:

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

🦋 petsc4py.PETSc.Mat.InfoType 🦋

class petsc4py.PETSc.Mat.InfoType

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

Matrix info type. It's the "what kind of info do you want about this matrix" enum situation 🍓

💖 Attributes Summary 💖

🌈 Attributes Documentation 🌈

and also:

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

🌸 petsc4py.PETSc.Mat.Option 🌸

class petsc4py.PETSc.Mat.Option

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

Matrix option. Bestie it's literally just called Option 💀

See also:

✨ Attributes Summary 💅

okay bestie, this is the master list of every constant this module hands you — like, the whole squad 🫶. every single one of them is an int, no cap, and they exist so you can pass them around as flags/tags instead of remembering weird mystic numbers. vibe check below 👇

  • ERROR_LOWER_TRIANGULAR — a constant, type int. that's the whole lore 🦋
  • FORCE_DIAGONAL_ENTRIES — a constant, type int. periodt ✨
  • GETROW_UPPERTRIANGULAR — a constant, type int. yes it's giving very specific, she's still iconic 🌸
  • HERMITIAN — a constant, type int. literally just an int bestie 💜
  • IGNORE_LOWER_TRIANGULAR — a constant, type int. no thoughts, just int 😭
  • IGNORE_OFF_PROC_ENTRIES — a constant, type int. obsessed with how consistent this is 🎀
  • IGNORE_ZERO_ENTRIES — a constant, type int. slay 💅
  • KEEP_NONZERO_PATTERN — a constant, type int. she's an int, that's it, that's the tweet 🌈
  • NEW_NONZERO_ALLOCATION_ERR — a constant, type int. main character energy 🔥
  • NEW_NONZERO_LOCATIONS — a constant, type int. lowkey just an int 🦋
  • NEW_NONZERO_LOCATION_ERR — a constant, type int. yes it's a different constant from the last one, read the name twice bestie 👑
  • NO_OFF_PROC_ENTRIES — a constant, type int. ate ✨
  • NO_OFF_PROC_ZERO_ROWS — a constant, type int. iykyk 🌸
  • OPTION_MAX — a constant, type int. fr fr 💖
  • OPTION_MIN — a constant, type int. the twin of the one above, they're matching 🎀
  • ROW_ORIENTED — a constant, type int. it's giving int 💅
  • SORTED_FULL — a constant, type int. sorted, full, iconic 💜
  • SPD — a constant, type int. short king, still an int 😌
  • STRUCTURALLY_SYMMETRIC — a constant, type int. symmetric in spirit, int in type 🦋
  • STRUCTURE_ONLY — a constant, type int. 🫶
  • SUBMAT_SINGLEIS — Constant SUBMAT_SINGLEIS of type int (https://docs.python.org/3/builtins/functions.html#int) 🎀
  • SUBSET_OFF_PROC_ENTRIES — Constant SUBSET_OFF_PROC_ENTRIES of type int (https://docs.python.org/3/builtins/functions.html#int) ✨
  • SYMMETRIC — Constant SYMMETRIC of type int (https://docs.python.org/3/builtins/functions.html#int) 💖
  • SYMMETRY_ETERNAL — Constant SYMMETRY_ETERNAL of type int (https://docs.python.org/3/builtins/functions.html#int) 🦋
  • UNUSED_NONZERO_LOCATION_ERR — Constant UNUSED_NONZERO_LOCATION_ERR of type int (https://docs.python.org/3/builtins/functions.html#int) 👑
  • USE_HASH_TABLE — Constant USE_HASH_TABLE of type int (https://docs.python.org/3/builtins/functions.html#int) 🌸
  • USE_INODES — Constant USE_INODES of type int (https://docs.python.org/3/builtins/functions.html#int) 🔥

🌈 Attributes Documentation 🌈

okay bestie, this is the part where the docs just. list everything again. same constants, now alphabetised with their signatures spelled out. no cap, it's lowkey satisfying once you clock the pattern 💅

bestie yes, every single one of these is just int. the type URL is the same forever. that's not me being lazy, that's literally what the docs say 🫶

and we're still not done — the constants keep coming, keep scrolling 💅

  • UNUSED_NONZERO_LOCATION_ERR — int, and its value is literally UNUSED_NONZERO_LOCATION_ERR. It's a constant of type int, bestie, that's the whole lore 💅
  • USE_HASH_TABLE — int = USE_HASH_TABLE. Constant of type int, iconic, no notes ✨
  • USE_INODES — int = USE_INODES. Constant of type int. That's it, that's the whole vibe 🦋
  • __init__() 🎀
  • classmethod __new__(*args, **kwargs)

🦋 petsc4py.PETSc.Mat.OrderingType

class petsc4py.PETSc.Mat.OrderingType

Bases: object — yeah she inherits from plain old object, we love a minimal queen 👑

So this one is the factored matrix ordering type. It's giving "how do we rearrange this matrix so the math behaves" energy, and honestly? Obsessed 😭

See also: MatOrderingType

✨ Attributes Summary ✨

okay so here's the whole roster, every single one of them, and they're all str typed, periodt:

  • AMD — Object AMD of type str 🌸
  • METISND — Object METISND of type str 🌸
  • NATURAL — Object NATURAL of type str 🌸
  • ND — Object ND of type str 🌸
  • OWD — Object OWD of type str 🌸
  • QMD — Object QMD of type str 🌸
  • RCM — Object RCM of type str 🌸
  • ROWLENGTH — Object ROWLENGTH of type str 🌸
  • SPECTRAL — Object SPECTRAL of type str 🌸
  • WBM — Object WBM of type str 🌸

📖 Attributes Documentation 📖

hiii okay so now the long-form, one entry per attribute, all str, all the same shape — but we're doing them all because every detail matters 💜

  • AMD: str = AMD — Object AMD of type str. Fr fr, that's the documentation. 💖
  • METISND: str = METISND — Object METISND of type str. ✨
  • NATURAL: str = NATURAL — Object NATURAL of type str. 🌸
  • ND: str = ND — Object ND of type str. 🦋
  • OWD: str = OWD — Object OWD of type str. 🎀
  • QMD: str = QMD — Object QMD of type str. ⭐
  • RCM: str = RCM — Object RCM of type str. 🌈
  • ROWLENGTH: str = ROWLENGTH — Object ROWLENGTH of type str. 💅
  • SPECTRAL: str = SPECTRAL — Object SPECTRAL of type str. 🔥
  • WBM: str = WBM — Object WBM of type str. 👑
  • __init__() 🫶
  • classmethod __new__(*args, **kwargs)

🌸 petsc4py.PETSc.Mat.SORType

class petsc4py.PETSc.Mat.SORType

Bases: object — again, straight off the base object, lowkey elegant 🙈

Matrix SOR type. That's the summary the docs give you, and we're not embellishing the facts, just serving them with flavor ✨

See also: MatSORType

okay bestie so this chunk is literally the ✨constant girlies✨ section — all the class attributes this thing puts on display, and the plot twist is that every single one of them is just a plain ol' int 💅 no cap, they're all the same type, we love consistency.

Every single one is a Constant of type int, and "type int" is literally Python's own builtin int — here's the receipts link in case you wanna vibe with the docs: https://docs.python.org/3/builtins/functions.html#int 🫶

✨ Attributes Summary ✨

  • APPLY_LOWER — Constant APPLY_LOWER of type int. 🌸
  • APPLY_UPPER — Constant APPLY_UPPER of type int. 🌸
  • BACKWARD_SWEEP — Constant BACKWARD_SWEEP of type int. 🦋
  • EISENSTAT — Constant EISENSTAT of type int. 🦋
  • FORWARD_SWEEP — Constant FORWARD_SWEEP of type int. 🦋
  • LOCAL_BACKWARD_SWEEP — Constant LOCAL_BACKWARD_SWEEP of type int. 💜
  • LOCAL_FORWARD_SWEEP — Constant LOCAL_FORWARD_SWEEP of type int. 💜
  • LOCAL_SYMMETRIC_SWEEP — Constant LOCAL_SYMMETRIC_SWEEP of type int. 💜
  • SYMMETRY_SWEEP — Constant SYMMETRY_SWEEP of type int. ⭐
  • ZERO_INITIAL_GUESS — Constant ZERO_INITIAL_GUESS of type int. ⭐

like, that's the whole table, just vibes and ints fr fr 🙈

🎀 Attributes Documentation 🎀

now the full receipts, one by one, zero skipping, we're thorough here 🫡

notice how each one's value is just… itself? yeah, that's the bit. APPLY_LOWER equals APPLY_LOWER, iconic, no further questions 💅

__init__()

the classic constructor moment — nothing fancy, it's just __init__() doing its lil thang 🎀

classmethod __new__(*args, **kwargs)

and here's the classmethod that flexes on you: __new__(*args, **kwargs) — takes whatever args and kwargs you throw at it, catches them all, main character energy fr.

👑 petsc4py.PETSc.Mat.SolverType 👑

okay next up, the headliner:

class petsc4py.PETSc.Mat.SolverType

Bases: object (https://docs.python.org/3/builtins/functions.html#object) — yeah she inherits straight from object, simple, clean, no drama. 🌈

It's a Factored matrix solver type. boom. that's what it is. 🧚

See also:

✨ Attributes Summary ✨

okay so before we get into the long version, here is the whole roster at a glance 💅 every single one of these is a plain old string — and not just any string, the Python built-in str (you know her: https://docs.python.org/3/builtins/stdtypes.html#str) — and each one's value is literally its own name. no cap. alphabetically sorted and everything, we love an organized bestie 🎀

  • BAS — a str, value BAS
  • CHOLMOD — a str, value CHOLMOD
  • CUDA — a str, value CUDA
  • CUSPARSE — a str, value CUSPARSE
  • ELEMENTAL — a str, value ELEMENTAL
  • ESSL — a str, value ESSL
  • KLU — a str, value KLU
  • LUSOL — a str, value LUSOL
  • MATLAB — a str, value MATLAB
  • MKL_CPARDISO — a str, value MKL_CPARDISO
  • MKL_PARDISO — a str, value MKL_PARDISO
  • MUMPS — a str, value MUMPS
  • PASTIX — a str, value PASTIX
  • PETSC — a str, value PETSC
  • SCALAPACK — a str, value SCALAPACK
  • SPQR — a str, value SPQR
  • STRUMPACK — a str, value STRUMPACK
  • SUPERLU — a str, value SUPERLU
  • SUPERLU_DIST — a str, value SUPERLU_DIST
  • UMFPACK — a str, value UMFPACK

✨ Attributes Documentation ✨

now the full receipts for each one 🧾 same info, just expanded out and dressed up a lil. every entry below is type str and equals itself, which is honestly the most self-actualized group of constants I've ever seen 😭✨

🌟 BAS

BAS: str <https://docs.python.org/3/builtins/stdtypes.html#str> = BAS

Object BAS of type str <https://docs.python.org/3/builtins/stdtypes.html#str>

🌟 CHOLMOD

CHOLMOD: str <https://docs.python.org/3/builtins/stdtypes.html#str> = CHOLMOD

Object CHOLMOD of type str <https://docs.python.org/3/builtins/stdtypes.html#str>

🌟 CUDA

CUDA: str <https://docs.python.org/3/builtins/stdtypes.html#str> = CUDA

Object CUDA of type str <https://docs.python.org/3/builtins/stdtypes.html#str>

🌟 CUSPARSE

CUSPARSE: str <https://docs.python.org/3/builtins/stdtypes.html#str> = CUSPARSE

Object CUSPARSE of type str <https://docs.python.org/3/builtins/stdtypes.html#str>

🌟 ELEMENTAL

ELEMENTAL: str <https://docs.python.org/3/builtins/stdtypes.html#str> = ELEMENTAL

Object ELEMENTAL of type str <https://docs.python.org/3/builtins/stdtypes.html#str>

🌟 ESSL

ESSL: str <https://docs.python.org/3/builtins/stdtypes.html#str> = ESSL

Object ESSL of type str <https://docs.python.org/3/builtins/stdtypes.html#str>

🌟 KLU

KLU: str <https://docs.python.org/3/builtins/stdtypes.html#str> = KLU

Object KLU of type str <https://docs.python.org/3/builtins/stdtypes.html#str>

🌟 LUSOL

LUSOL: str <https://docs.python.org/3/builtins/stdtypes.html#str> = LUSOL

Object LUSOL of type str <https://docs.python.org/3/builtins/stdtypes.html#str>

bestie we are not done, there's a whole queue of these still waiting their turn 🙈 the next one up is MATLAB and it keeps going from there, so stay with me 💖
  • MATLAB: str = MATLAB — okay so this is an Object named MATLAB, and its type is literally just str 💅 no cap, that's the whole vibe.
  • MKL_CPARDISO: str = MKL_CPARDISO — Object MKL_CPARDISO, type str 🎀 yeah bestie, same energy.
  • MKL_PARDISO: str = MKL_PARDISO — Object MKL_PARDISO, type str ✨
  • MUMPS: str = MUMPS — Object MUMPS, type str 🦋
  • PASTIX: str = PASTIX — Object PASTIX, type str 🌸
  • PETSC: str = PETSC — Object PETSC, type str 👑 the main character one, obviously.
  • SCALAPACK: str = SCALAPACK — Object SCALAPACK, type str 💖
  • SPQR: str = SPQR — Object SPQR, type str 🌈
  • STRUMPACK: str = STRUMPACK — Object STRUMPACK, type str ⭐
  • SUPERLU: str = SUPERLU — Object SUPERLU, type str 🔥
  • SUPERLU_DIST: str = SUPERLU_DIST — Object SUPERLU_DIST, type str 💀
  • UMFPACK: str = UMFPACK — Object UMFPACK, type str 🍓
  • __init__() — the init hook, sitting right here in the docs with zero extra commentary 🙈
  • classmethod __new__(*args, **kwargs) — the new-instance hook, also just… there, taking *args, **kwargs and saying nothing else 🫶

🦋 class petsc4py.PETSc.Mat.Stencil 🦋

class petsc4py.PETSc.Mat.Stencil

Bases: object 🎀 (yes, the plain builtin object, nothing fancy here)

Okay so real talk, this one does something genuinely iconic: it associates structured grid coordinates with matrix indices ✨ like it's the matchmaker between your grid brain and your matrix brain and honestly? obsessed.

See also:

  • MatStencil 👑

💖 Attributes Summary 💖

  • c — Field component.
  • field — Field component.
  • i — First logical grid coordinate.
  • index — Logical grid coordinates (i, j, k).
  • j — Second logical grid coordinate.
  • k — Third logical grid coordinate.

📝 Attributes Documentation 📝

  • c — Field component.

Source code at petsc4py/PETSc/Mat.pyx:321 🔍

  • field — Field component.

Source code at petsc4py/PETSc/Mat.pyx:340 🔍

  • i — First logical grid coordinate.

Source code at petsc4py/PETSc/Mat.pyx:297 🔍

  • index — Logical grid coordinates (i, j, k).

Source code at petsc4py/PETSc/Mat.pyx:329 🔍

  • j — Second logical grid coordinate.

Source code at petsc4py/PETSc/Mat.pyx:305 🔍

  • k — Third logical grid coordinate.

Source code at petsc4py/PETSc/Mat.pyx:313 🔍

ngl the docstrings for c and field are the exact same sentence and that's just how it is, no notes 💀
  • __init__() — constructor hook, no further description in the docs 🙈
  • classmethod __new__(*args, **kwargs) — new-instance hook, also undescribed, also taking *args, **kwargs 🫶

🌸 class petsc4py.PETSc.Mat.Structure 🌸

class petsc4py.PETSc.Mat.Structure

Bases: object 🌈

So this one is the Matrix modification structure 💅 it's literally the thing that tells PETSc how your matrix's nonzero structure is behaving — iykyk.

See also:

  • MatStructure 👑

🌈 Attributes Summary 🌈

okay so these are the integer flags this class is serving you, bestie — every single one is typed as plain old int:

  • DIFFERENT — constant DIFFERENT of type int
  • DIFFERENT_NONZERO_PATTERN — constant DIFFERENT_NONZERO_PATTERN of type int
  • DIFFERENT_NZ — constant DIFFERENT_NZ of type int
  • SAME — constant SAME of type int
  • SAME_NONZERO_PATTERN — constant SAME_NONZERO_PATTERN of type int
  • SAME_NZ — constant SAME_NZ of type int
  • SUBSET — constant SUBSET of type int
  • SUBSET_NONZERO_PATTERN — constant SUBSET_NONZERO_PATTERN of type int
  • SUBSET_NZ — constant SUBSET_NZ of type int
  • UNKNOWN — constant UNKNOWN of type int
  • UNKNOWN_NONZERO_PATTERN — constant UNKNOWN_NONZERO_PATTERN of type int
  • UNKNOWN_NZ — constant UNKNOWN_NZ of type int

like, twelve little int baddies, all built different. 💅

🎀 Attributes Documentation 🎀

DIFFERENT: int = DIFFERENT

Constant DIFFERENT of type int. periodt.

DIFFERENT_NONZERO_PATTERN: int = DIFFERENT_NONZERO_PATTERN

Constant DIFFERENT_NONZERO_PATTERN of type int. the full-name version, no abbreviations, she's thorough. ✨

DIFFERENT_NZ: int = DIFFERENT_NZ

Constant DIFFERENT_NZ of type int.

SAME: int = SAME

Constant SAME of type int.

SAME_NONZERO_PATTERN: int = SAME_NONZERO_PATTERN

Constant SAME_NONZERO_PATTERN of type int.

SAME_NZ: int = SAME_NZ

Constant SAME_NZ of type int.

SUBSET: int = SUBSET

Constant SUBSET of type int.

SUBSET_NONZERO_PATTERN: int = SUBSET_NONZERO_PATTERN

Constant SUBSET_NONZERO_PATTERN of type int.

SUBSET_NZ: int = SUBSET_NZ

Constant SUBSET_NZ of type int.

UNKNOWN: int = UNKNOWN

Constant UNKNOWN of type int.

UNKNOWN_NONZERO_PATTERN: int = UNKNOWN_NONZERO_PATTERN

Constant UNKNOWN_NONZERO_PATTERN of type int.

UNKNOWN_NZ: int = UNKNOWN_NZ

Constant UNKNOWN_NZ of type int.

and then, obvi, the standard class machinery shows up too:

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

so you can construct and instance-ify like any well-behaved Python class. 🫶

👑 petsc4py.PETSc.Mat.Type 👑

class petsc4py.PETSc.Mat.Type

Bases: object

oh she's simple, she's clean, she inherits straight from object. Matrix type. that's the whole vibe — this little class is where matrix types live. 💖

See also:

MatType 🦋

bestie reminder: the MatType reference points at the upstream PETSc manual page for MatType, so if you ever need the full tea on matrix types, that's your portal. 🌸

✨ Attributes Summary ✨

okay so bestie, here's the whole squad 🫶 and the tea is genuinely so simple: every single one of these is an object of type str. That's it, that's the plot. And each one points at the Python docs for str, at https://docs.python.org/3/builtins/stdtypes.html#str. No cap 💅

and bestie we are SO not done here, do not close the tab on me 💀

okay bestie the list keeps going, we are so not done yet 💅 — the vibe is exactly the same for every single one of these: they're all str objects, all documented the same way, all living in the same section of the lore. Nothing new to learn, just more names to collect like little Pokémon. 🎀

so bestie, the rest of this table is literally just names mapped to the string they hold, and here's the tea: every single one of them is of type str and every single one carries the exact same doc link — https://docs.python.org/3/builtins/stdtypes.html#str — so I'm saying it once up front instead of twenty times, you're welcome 💅

  • SEQAIJ — object SEQAIJ, type str.
  • SEQAIJCRL — object SEQAIJCRL, type str.
  • SEQAIJCUSPARSE — object SEQAIJCUSPARSE, type str.
  • SEQAIJMKL — object SEQAIJMKL, type str.
  • SEQAIJPERM — object SEQAIJPERM, type str.
  • SEQAIJSELL — object SEQAIJSELL, type str.
  • SEQAIJVIENNACL — object SEQAIJVIENNACL, type str.
  • SEQBAIJ — object SEQBAIJ, type str.
  • SEQBAIJMKL — object SEQBAIJMKL, type str.
  • SEQCUFFT — object SEQCUFFT, type str.
  • SEQDENSE — object SEQDENSE, type str.
  • SEQDENSECUDA — object SEQDENSECUDA, type str.
  • SEQDENSEHIP — object SEQDENSEHIP, type str.
  • SEQKAIJ — object SEQKAIJ, type str.
  • SEQMAIJ — object SEQMAIJ, type str.
  • SEQSBAIJ — object SEQSBAIJ, type str.
  • SEQSELL — object SEQSELL, type str.
  • SHELL — object SHELL, type str.
  • SUBMATRIX — object SUBMATRIX, type str.
  • TRANSPOSE — object TRANSPOSE, type str.

like, that's the whole vibe. a wall of strings that all say their own name back to you. main character energy, truly 👑

✨ Attributes Documentation ✨

and now the receipts 🧾 — each of these attributes documents its own declared type and its value, and (say it with me) the type link is https://docs.python.org/3/builtins/stdtypes.html#str on every single one of them.

  • AIJ: str = AIJ — object AIJ of type str.
  • AIJCRL: str = AIJCRL — object AIJCRL of type str.
  • AIJCUSPARSE: str = AIJCUSPARSE — object AIJCUSPARSE of type str.
  • AIJMKL: str = AIJMKL — object AIJMKL of type str.
  • AIJPERM: str = AIJPERM — object AIJPERM of type str.

ngl the pattern is giving "the docs generator was on autopilot and honestly? respect." 😭 every attribute is a str, every attribute equals itself, and there is nothing else to report periodt 💖

so yeah — that's this chunk: one long string table and five self-titled attributes, all squeaky clean, no defaults hidden, no surprises tucked away. and there's still more where that came from, so keep scrolling bestie 🦋

  • AIJSELL — it's a str, and its value is literally AIJSELL. So: an object named AIJSELL, of type str. self-titled icon behavior 💅
  • AIJVIENNACL — str, value AIJVIENNACL. An object named AIJVIENNACL, of type str. ✨
  • BAIJ — str, value BAIJ. An object named BAIJ, of type str. 🎀
  • BAIJMKL — str, value BAIJMKL. An object named BAIJMKL, of type str. 🦋
  • BLOCKMAT — str, value BLOCKMAT. An object named BLOCKMAT, of type str. 🌸
  • COMPOSITE — str, value COMPOSITE. An object named COMPOSITE, of type str. 💖
  • CONSTANTDIAGONAL — str, value CONSTANTDIAGONAL. An object named CONSTANTDIAGONAL, of type str. 💅
  • DENSE — str, value DENSE. An object named DENSE, of type str. ✨
  • DENSECUDA — str, value DENSECUDA. An object named DENSECUDA, of type str. 🎀
  • DENSEHIP — str, value DENSEHIP. An object named DENSEHIP, of type str. 🦋
  • DIAGONAL — str, value DIAGONAL. An object named DIAGONAL, of type str. 🌸
  • DUMMY — str, value DUMMY. An object named DUMMY, of type str. 🙈
  • ELEMENTAL — str, value ELEMENTAL. An object named ELEMENTAL, of type str. 🔥
  • FFT — str, value FFT. An object named FFT, of type str. ✨
  • FFTW — str, value FFTW. An object named FFTW, of type str. ✨
  • H2OPUS — str, value H2OPUS. An object named H2OPUS, of type str. 🌊
  • HERMITIANTRANSPOSE — str, value HERMITIANTRANSPOSE. An object named HERMITIANTRANSPOSE, of type str. 💜
  • HTOOL — str, value HTOOL. An object named HTOOL, of type str. 🧚
  • HYPRE — str, value HYPRE. An object named HYPRE, of type str. 🔥
  • HYPRESSTRUCT — str, value HYPRESSTRUCT. An object named HYPRESSTRUCT, of type str. 🎀
  • HYPRESTRUCT — str, value HYPRESTRUCT. An object named HYPRESTRUCT, of type str. 🎀
  • IS — str, value IS. An object named IS, of type str. 💅
  • KAIJ — str, value KAIJ. An object named KAIJ, of type str. 🌸
  • LMVM — str, value LMVM. An object named LMVM, of type str. 🦋
  • LMVMBADBROYDEN — str, value LMVMBADBROYDEN. An object named LMVMBADBROYDEN, of type str. ✨
  • LMVMBFGS — str, value LMVMBFGS. An object named LMVMBFGS, of type str. ✨
  • LMVMBROYDEN — str, value LMVMBROYDEN. An object named LMVMBROYDEN, of type str. ✨
  • LMVMDBFGS — str, value LMVMDBFGS. An object named LMVMDBFGS, of type str. ✨
  • LMVMDDFP — str, value LMVMDDFP. An object named LMVMDDFP, of type str. ✨
  • LMVMDFP — str, value LMVMDFP. An object named LMVMDFP, of type str. ✨
  • LMVMDIAGBBROYDEN — str, value LMVMDIAGBBROYDEN. An object named LMVMDIAGBBROYDEN, of type str. ✨
  • LMVMDQN — str, value LMVMDQN. An object named LMVMDQN, of type str. ✨
  • LMVMSR1 — str, value LMVMSR1. An object named LMVMSR1, of type str. ✨
  • LMVMSYMBADBROYDEN — str, value LMVMSYMBADBROYDEN. An object named LMVMSYMBADBROYDEN, of type str. ✨
  • LMVMSYMBROYDEN — str, value LMVMSYMBROYDEN. An object named LMVMSYMBROYDEN, of type str. ✨
  • LOCALREF — str, value LOCALREF. An object named LOCALREF, of type str. 🎀
  • LRC — str, value LRC. An object named LRC, of type str. 🦋
  • MAIJ — str, value MAIJ. An object named MAIJ, of type str. 🌸
  • MFFD — str, value MFFD. An object named MFFD, of type str. 💖
  • MPIADJ — str, value MPIADJ. An object named MPIADJ, of type str. 💅
  • MPIAIJ — str, value MPIAIJ. An object named MPIAIJ, of type str. ✨
  • MPIAIJCRL — str, value MPIAIJCRL. An object named MPIAIJCRL, of type str. 🎀
  • MPIAIJCUSPARSE — str, value MPIAIJCUSPARSE. An object named MPIAIJCUSPARSE, of type str. 🦋
  • MPIAIJMKL — str, value MPIAIJMKL. An object named MPIAIJMKL, of type str. 🌸
  • MPIAIJPERM — str, value MPIAIJPERM. An object named MPIAIJPERM, of type str. 💜
  • MPIAIJSELL: str = MPIAIJSELL — object MPIAIJSELL of type str 💖
  • MPIAIJVIENNACL: str = MPIAIJVIENNACL — object MPIAIJVIENNACL of type str ✨
  • MPIBAIJ: str = MPIBAIJ — object MPIBAIJ of type str 🎀
  • MPIBAIJMKL: str = MPIBAIJMKL — object MPIBAIJMKL of type str 🦋
  • MPIDENSE: str = MPIDENSE — object MPIDENSE of type str 🌸
  • MPIDENSECUDA: str = MPIDENSECUDA — object MPIDENSECUDA of type str 💅
  • MPIDENSEHIP: str = MPIDENSEHIP — object MPIDENSEHIP of type str 🫶
  • MPIKAIJ: str = MPIKAIJ — object MPIKAIJ of type str 😭
  • MPIMAIJ: str = MPIMAIJ — object MPIMAIJ of type str 🔥
  • MPISBAIJ: str = MPISBAIJ — object MPISBAIJ of type str 👑
  • MPISELL: str = MPISELL — object MPISELL of type str 🌈
  • NEST: str = NEST — object NEST of type str ⭐
  • NORMAL: str = NORMAL — object NORMAL of type str 💀
  • NORMALHERMITIAN: str = NORMALHERMITIAN — object NORMALHERMITIAN of type str 🙈
  • PREALLOCATOR: str = PREALLOCATOR — object PREALLOCATOR of type str 🍓
  • PYTHON: str = PYTHON — object PYTHON of type str 🧚
  • SAME: str = SAME — object SAME of type str 💜
  • SBAIJ: str = SBAIJ — object SBAIJ of type str 💖
  • SCATTER: str = SCATTER — object SCATTER of type str ✨
  • SCHURCOMPLEMENT: str = SCHURCOMPLEMENT — object SCHURCOMPLEMENT of type str 🎀
  • SELL: str = SELL — object SELL of type str 🦋
  • SEQAIJ: str = SEQAIJ — object SEQAIJ of type str 🌸
  • SEQAIJCRL: str = SEQAIJCRL — object SEQAIJCRL of type str 💅
  • SEQAIJCUSPARSE: str = SEQAIJCUSPARSE — object SEQAIJCUSPARSE of type str 🫶
  • SEQAIJMKL: str = SEQAIJMKL — object SEQAIJMKL of type str 😭
  • SEQAIJPERM: str = SEQAIJPERM — object SEQAIJPERM of type str 🔥
  • SEQAIJSELL: str = SEQAIJSELL — object SEQAIJSELL of type str 👑
  • SEQAIJVIENNACL: str = SEQAIJVIENNACL — object SEQAIJVIENNACL of type str 🌈
  • SEQBAIJ: str = SEQBAIJ — object SEQBAIJ of type str ⭐
  • SEQBAIJMKL: str = SEQBAIJMKL — object SEQBAIJMKL of type str 💀
  • SEQCUFFT: str = SEQCUFFT — object SEQCUFFT of type str 🙈
  • SEQDENSE: str = SEQDENSE — object SEQDENSE of type str 🍓
  • SEQDENSECUDA: str = SEQDENSECUDA — object SEQDENSECUDA of type str 🧚
  • SEQDENSEHIP: str = SEQDENSEHIP — object SEQDENSEHIP of type str 💜
  • SEQKAIJ: str = SEQKAIJ — object SEQKAIJ of type str 💖
  • SEQMAIJ: str = SEQMAIJ — object SEQMAIJ of type str ✨
  • SEQSBAIJ: str = SEQSBAIJ — object SEQSBAIJ of type str 🎀
  • SEQSELL: str = SEQSELL — object SEQSELL of type str 🦋
  • SHELL: str = SHELL — object SHELL of type str 🌸
  • SUBMATRIX: str = SUBMATRIX — object SUBMATRIX of type str 💅
  • TRANSPOSE: str = TRANSPOSE — object TRANSPOSE of type str 🫶

okay and then the two methods that live right at the end of this roster, bestie, and yes they are exactly as short as they look:

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

that's the whole crowd — every name, every <pink>str</pink> type, every value, all of it still object <name> of type str energy, no cap 💜

  • H2OpusCompress(tol) — Compress a hierarchical matrix 🗜️✨ like it's been holding its breath and finally exhales.
  • H2OpusLowRankUpdate(U[, V, s]) — Do a low-rank update of the form self += sUVᵀ 🫶 lowkey the glow-up your matrix asked for.
  • H2OpusOrthogonalize() — Orthogonalize the basis tree of a hierarchical matrix 🌈 tidy branches, immaculate vibes.
  • HtoolGetPermutationSource() — Get the permutation of source (column) indices that Htool computed 🎀
  • HtoolGetPermutationTarget() — Get the permutation of target (row) indices that Htool computed 💫
  • HtoolUsePermutation(use) — Set whether to actually use the permutation Htool computed 👑
  • HtoolUseRecompression(use) — Set whether to recompress the matrix after assembly 🧚
  • SOR(b, x[, omega, sortype, shift, its, lits]) — Compute relaxation (SOR, Gauss-Seidel) sweeps 🔥 one sweep at a time, no cap.
  • allocateLMVM(x, f) — Allocate all the common memory the LMVM matrix needs 🍓 setting up the whole situation before anything goes down.
  • appendOptionsPrefix([prefix]) — Append to the prefix used for searching for options in the database 🌸
  • assemble([assembly]) — Assemble the matrix 🛠️ like, actually commit to the bit.
  • assemblyBegin([assembly]) — Begin an assembling stage of the matrix 🏁 it's giving "starting something."
  • assemblyEnd([assembly]) — Complete an assembling stage of the matrix that you initiated with assemblyBegin ✅ the other half of that duo, inseparable fr fr.
  • axpy(alpha, X[, structure]) — Perform the matrix summation self + = ɑ·X 💅
  • aypx(alpha, X[, structure]) — Perform the matrix summation self = ɑ·self + X 💜
  • bindToCPU(flg) — Mark a matrix to temporarily stay on the CPU 🖥️ stay home bestie, you're not traveling today.
  • boundToCPU() — Query if a matrix is bound to the CPU ❓ just checking in, are you staying home or not.
  • chop(tol) — Set entries smallest of tol (in absolute values) to zero ✂️ tiny numbers, be gone.
  • conjugate([out]) — Return the conjugate matrix 🦋
  • convert([mat_type, out]) — Convert the matrix type 🔄 little transformation moment.
  • copy([result, structure]) — Return a copy of the matrix 🎀 twin energy.
  • create([comm]) — Create the matrix ✨
  • createAIJ(size[, bsize, nnz, csr, comm]) — Create a sparse Type.AIJ matrix, optionally preallocating 🧚
  • createAIJCRL(size[, bsize, nnz, csr, comm]) — Create a sparse Type.AIJCRL matrix 🌈
  • createAIJWithArrays(size, csr[, bsize, comm]) — Create a sparse Type.AIJ matrix with data in CSR format 💫
  • createBAIJ(size, bsize[, nnz, csr, comm]) — Create a sparse blocked Type.BAIJ matrix, optionally preallocating 🔥
  • createConstantDiagonal(size, diag[, comm]) — Create a diagonal matrix of type Type.CONSTANTDIAGONAL 👑
  • createDense(size[, bsize, array, comm]) — bestie this is the glow-up moment, it makes you a Type.DENSE matrix (petsc4py.PETSc.Mat.Type.DENSE) 💖
  • createDenseCUDA(size[, bsize, array, ...]) — same dense energy but GPU-flavored: builds a Type.DENSECUDA matrix (petsc4py.PETSc.Mat.Type.DENSECUDA) and you can hand it optional host data and device data ✨
  • createDiagonal(diag) — takes your diag and hands back a diagonal matrix of type Type.DIAGONAL (petsc4py.PETSc.Mat.Type.DIAGONAL) — simple, iconic, no notes 🎀
  • createH2OpusFromMat(A[, coordinates, dist, ...]) — creates a hierarchical Type.H2OPUS matrix (petsc4py.PETSc.Mat.Type.H2OPUS) by sampling from an operator you already have, which is genuinely so smart 🦋
  • createHermitianTranspose(mat) — builds a Type.HERMITIANTRANSPOSE matrix (petsc4py.PETSc.Mat.Type.HERMITIANTRANSPOSE) that behaves like (A*)ᵀ, no cap 🌸
  • createHtoolFromKernel(size, spacedim, ...[, ...]) — makes a Type.HTOOL matrix (petsc4py.PETSc.Mat.Type.HTOOL) using a kernel function you define in Python — yes you, in your own Python, main character energy 💅
  • createIS(size[, bsize, lgmapr, lgmapc, comm]) — creates a Type.IS matrix (petsc4py.PETSc.Mat.Type.IS) representing globally unassembled operators, iykyk 🫶
  • createLRC(A, U, c, V) — the low-rank correction queen: builds a Type.LRC matrix (petsc4py.PETSc.Mat.Type.LRC) representing A + UCVᵀ 😭🔥
  • createNest(mats[, isrows, iscols, comm]) — creates a Type.NEST matrix (petsc4py.PETSc.Mat.Type.NEST) stuffed with multiple submatrices, like a little matryoshka doll but for linear algebra 🪆
  • createNormal(mat) — creates a Type.NORMAL matrix (petsc4py.PETSc.Mat.Type.NORMAL) representing AᵀA ⭐
  • createNormalHermitian(mat) — creates a Type.NORMALHERMITIAN matrix (petsc4py.PETSc.Mat.Type.NORMALHERMITIAN) representing (A*)ᵀA 💜
  • createPython(size[, context, comm]) — creates a Type.PYTHON matrix (petsc4py.PETSc.Mat.Type.PYTHON), aka your Python code runs the show 🌈
  • createSBAIJ(size, bsize[, nnz, csr, comm]) — creates a sparse Type.SBAIJ matrix (petsc4py.PETSc.Mat.Type.SBAIJ) in symmetric block format 🧚
  • createScatter(scatter[, comm]) — creates a Type.SCATTER matrix (petsc4py.PETSc.Mat.Type.SCATTER) out of a vector scatter 🍓
  • createSchurComplement(A00, Ap00, A01, A10[, A11]) — creates a Type.SCHURCOMPLEMENT matrix (petsc4py.PETSc.Mat.Type.SCHURCOMPLEMENT) — look at all those arguments, she's thorough 👑
  • createSubMatrices(isrows[, iscols, submats]) — returns several sequential submatrices at once, a whole squad 🙈
  • createSubMatrix(isrow[, iscol, submat]) — returns a submatrix, just the one, keeping it lowkey 💖
  • createSubMatrixVirtual(A, isrow[, iscol]) — creates a Type.SUBMATRIX matrix (petsc4py.PETSc.Mat.Type.SUBMATRIX) that acts as a submatrix — virtual, theatrical, ate 💅
  • createTranspose(mat) — creates a Type.TRANSPOSE matrix (petsc4py.PETSc.Mat.Type.TRANSPOSE) that behaves like Aᵀ ✨
  • createVecLeft() — returns a left vector, i.e. a vector that the matrix vector product can be stored in 🎀
  • createVecRight() — returns a right vector, i.e. a vector that the matrix can be multiplied against 🦋
  • createVecs([side]) — hands you back vectors you can actually use in matrix-vector products 🫶 no cap, that's the whole vibe.
  • destroy() — yeets the matrix into the void. gone. bye bestie 💅
  • diagonalScale([L, R]) — does left and/or right diagonal scaling of the matrix. pick a side, or both, we don't gatekeep ✨
  • duplicate([copy]) — returns a clone of the matrix. same energy, new object 🪞
  • equal(mat) — returns the result of comparing two matrices. are y'all the same or nah 👀
  • factorCholesky(isperm[, options]) — does an in-place Cholesky factorization. in-place means it's literally rearranging its own house 🏠
  • factorICC(isperm[, options]) — does an in-place incomplete Cholesky factorization. ICC girlies rise, it's giving approximation 💜
  • factorILU(isrow, iscol[, options]) — does an in-place ILU factorization. incomplete LU, the moment 🔥
  • factorLU(isrow, iscol[, options]) — does an in-place LU factorization. full send, the classic 🎀
  • factorNumericCholesky(mat[, options]) — not implemented. it's not a bug bestie, it's just… not there 😭
  • factorNumericLU(mat[, options]) — not implemented. also ghosting us fr fr 💀
  • factorSymbolicCholesky(isperm[, options]) — not implemented. the symbolic part said "not today" 🙈
  • factorSymbolicICC(isperm[, options]) — not implemented. no cap, not implemented.
  • factorSymbolicILU(isrow, iscol[, options]) — not implemented. same story, iconic absence 💀
  • factorSymbolicLU(mat, isrow, iscol[, options]) — not implemented. yeah bestie, this one's also just… nope 🙈
  • findZeroRows() — returns the index set of the empty rows. we're hunting for the rows that contribute literally nothing ✨ zero rows, zero drama.
  • fixISLocalEmpty([fix]) — compresses out zero local rows from the local matrices. cleanup era 🧹 so satisfying.
  • getBlockSize() — returns the matrix block size. how chunky is it 🧐
  • getBlockSizes() — returns the row AND column block sizes. both dimensions, we're thorough like that 👑
  • getColumnIJ([symmetric, compressed]) — returns the CSC representation of the local sparsity pattern. compressed sparse column, iykyk 🌈
  • getColumnVector(column[, result]) — returns the columnᵗʰ column vector of the matrix. yes, the superscript is doing its job 💅
  • getDM() — returns the DM defining the data layout of the matrix. the DM is the blueprint bestie 🗺️
  • getDenseArray([readonly]) — returns the array where the data is stored. raw data access, main character energy 🔥
  • getDenseColumnVec(i[, mode]) — returns the iᵗʰ column vector of the dense matrix. dense and unbothered ✨
  • getDenseLDA() — returns the leading dimension of the array used by the dense matrix. the LDA, extremely "trust the layout" 💜
  • getDenseLocalMatrix() — returns the local part of the dense matrix. just your slice, not the whole cake 🍓
  • getDenseSubMatrix([rbegin, rend, cbegin, cend]) — get access to a submatrix of a Type.DENSE matrix. rows rbegin→rend, cols cbegin→cend, pick your window 🪟
  • getDiagonal([result]) — returns the diagonal of the matrix. the ✨main diagonal✨, the moment, the line everyone's watching 💅
  • getDiagonalBlock() — returns the part of the matrix associated with the on-process coupling. your local corner of the universe 🌸
  • getISAllowRepeated() — get the flag for repeated… (and yeah bestie, we're picking that thought right back up next part, don't you worry 🫶)
  • getISLocalMat() — returns the local matrix that's chillin' inside a Type.IS matrix ✨ (that's petsc4py.PETSc.Mat.Type.IS if you're being fancy about it). Yes bestie, a matrix hiding inside a matrix. It's giving inception 💅
  • getInertia() — hands you the inertia from a factored matrix. That's the inertia bestie, the whole positive/negative/zero eigenvalue count situation 👑
  • getInfo([info]) — returns the summary info. info is optional, so you can pass it in or let it do its thing 🫶
  • getLGMap() — returns the local-to-global mappings. All your maps in one place, no cap 🗺️
  • getLMVMJ0() — gets you the initial Jacobian of the LMVM matrix. The original one, before everything got all iterative and complicated 🌸
  • getLMVMJ0KSP() — and this one grabs the KSP of that LMVM matrix. J0's solver bestie, right there 🔥
  • getLRCMats() — returns the constituents of a Type.LRC matrix (aka petsc4py.PETSc.Mat.Type.LRC). Low-rank correction gang, assemble 🧚
  • getLocalSize() — return the local number of rows and columns. Your little slice of the matrix universe 💖
  • getLocalSubMatrix(isrow, iscol[, submat]) — returns a reference to a submatrix, specified in local numbering. Note: it's a reference, not a copy — so don't go renaming and expect the original to stay cute. submat is optional ☝️
  • getMumpsCntl(icntl) — returns the MUMPS parameter, CNTL[icntl]. Straight from the MUMPS vault 🔐
  • getMumpsIcntl(icntl) — returns the MUMPS parameter, ICNTL[icntl]. The integer control bestie 💜
  • getMumpsInfo(icntl) — returns the MUMPS parameter, INFO[icntl] 🌈
  • getMumpsInfog(icntl) — returns the MUMPS parameter, INFOG[icntl]. Yes there's an extra g, it's global, we love her ⭐
  • getMumpsRinfo(icntl) — returns the MUMPS parameter, RINFO[icntl]. Real numbers this time 🍓
  • getMumpsRinfog(icntl) — returns the MUMPS parameter, RINFOG[icntl]. Global and real, iconic 😭
  • getNearNullSpace() — returns the near-nullspace. Not the nullspace, the near one. Close enough to zero, still doing damage 💀
  • getNestISs() — returns the index sets representing the row and column spaces for a nest matrix. Nested matrices are just matrices of matrices, and honestly? Main character energy 👑
  • getNestLocalISs() — same vibe, but local index sets for the row and column spaces. Your process's very own slices 🎀
  • getNestSize() — returns the number of rows and columns of the matrix. The whole nest's dimensions, periodt ✨
  • getNestSubMatrix(i, j) — returns a single submatrix. You say which one with i for the row block and j for the column block, and boom, there it is 🔥
  • getNullSpace() — returns the nullspace. The actual one, no "near" about it 💅
  • getOption(option) — returns the option value. You hand it the option, it hands you back the value, transactional queen 🛍️
  • getOptionsPrefix() — returns the prefix used for searching for options in the database. It's how your object knows which options are even talking to it 🫶
  • getOrdering(ord_type) — returns a reordering for a matrix to improve a LU factorization. You pick the ord_type, it picks the permutation, everyone wins 🌸
  • getOwnershipIS() — returns the ranges of rows and columns owned by each process, packaged up as index sets. Who owns what, formally documented 💖
  • getOwnershipRange() — returns the locally owned range of rows. Just yours. Your row territory 👑
  • getOwnershipRangeColumn() — returns the locally owned range of columns. Same deal but for columns, because columns deserve attention too 💜
  • getOwnershipRanges() — returns the range of rows owned by each process. The full roster of who's got which rows 🌈
  • getOwnershipRangesColumn() — returns the range of columns owned by each process. Column edition of the group chat roster 🎀
  • getPythonContext() — hands you back the instance of the class that implements all the required Python methods. it's giving "here's the real one behind the curtain" 🎭
  • getPythonType() — gives you the fully qualified Python name of the class your matrix is actually using. it's giving "government name, not nickname" 💅
  • getRedundantMatrix(nsubcomm[, subcomm, out]) — returns redundant matrices on subcommunicators. nsubcomm says how many you want, and subcomm/out are optional lil extras you can pass in 🫶
  • getRow(row) — returns the column indices and the values for whichever row you asked for. no cap, the whole row, both halves 🌸
  • getRowIJ([symmetric, compressed]) — returns the CSR representation of the local sparsity pattern. optional symmetric and compressed flags if you're feeling specific ✨
  • getRowSum([result]) — returns the row-sum vector. pass result if you've already got a place for it to live 💖
  • getSchurComplementSubMatrices() — returns Schur complement sub-matrices. that's it, that's the whole job, matriarchy behavior 👑
  • getSize() — returns the global number of rows and columns. global, bestie, not just your lil corner of the world 🌈
  • getSizes() — returns the tuple of matrix layouts. plural, because there's a whole tuple of them 🎀
  • getTransposeMat() — returns the internal matrix hiding inside a Type.TRANSPOSE matrix, i.e. petsc4py.PETSc.Mat.Type.TRANSPOSE. the inner workings, exposed 🔍
  • getTransposeNullSpace() — returns the transpose nullspace. yes it's a real thing and yes it's iconic ⭐
  • getType() — returns the type of the matrix. the vibe check of what you're actually holding 🦋
  • getValue(row, col) — returns the value sitting in the (row, col) position. one number, one spot, precisely 🍓
  • getValues(rows, cols[, values]) — returns the values at all the zip(rows, cols) positions. pairs, matched up, cute 🧚 pass values if you want them stashed somewhere specific.
  • getValuesCSR() — returns the CSR representation of the local part of the matrix. local only, don't get it twisted 💀
  • getVecType() — returns the vector type your matrix uses. the matching set, if you will 🎀
  • hermitianTranspose([out]) — returns the transposed Hermitian matrix. out is optional, drop one in if you're organized ✨
  • imagPart([out]) — returns the imaginary part of the matrix. the imaginary bestie, separated out 💜
  • increaseOverlap(iset[, overlap]) — increases the overlap of an index set. pass an overlap value and it'll use that 🫶
  • invertBlockDiagonal() — returns the inverse of the block-diagonal entries. invert, but make it block-wise 💅
  • isAssembled() — the boolean flag telling you whether the matrix is assembled. true/false, no games 💖
  • isHermitian([tol]) — returns the boolean saying whether the matrix is Hermitian. optional tol for how strict you wanna be ⭐
  • isHermitianKnown() — returns the 2-tuple telling you if the matrix is known to be Hermitian. two values, one lil truth bomb 🔍
  • isLinear([n]) — returns whether the Mat is a linear operator. optional n in there too 🌸
  • isStructurallySymmetric() — returns the boolean saying whether the matrix is structurally symmetric. keyword: structurally 👀
  • isSymmetric([tol]) — returns the boolean saying whether the matrix is symmetric. tol optional, tolerance girlies rise 🎀
  • isSymmetricKnown() — returns the 2-tuple telling you if the matrix is known to be symmetric. again: two things, a tuple 🦋
  • isTranspose([mat, tol]) — returns the result of comparing a matrix against a transposed version. optional mat and tol to fine-tune the drama 🧚
  • kron(mat[, result]) — Compute C, the Kronecker product of A and B. Bestie this one is lowkey a bop for tensor things ✨
  • load(viewer) — Load a matrix. Just like, pull it in. Vibes restored 🫶
  • matMatMult(B, C[, result, fill]) — Perform matrix-matrix-matrix multiplication D=ABC. Three matrices, one slay 🔥
  • matMult(mat[, result, fill]) — Perform matrix-matrix multiplication C=AB. The classic, the icon, the moment 💅
  • matSolve(B, X) — Solve AX=B, given a factored matrix A. Heads up bestie: A has to already be factored, no cap 🔑
  • matTransposeMult(mat[, result, fill]) — Perform matrix-matrix multiplication C=ABᵀ. Transpose the second one and we're so back 🦋
  • mult(x, y) — Perform the matrix vector product y = A @ x. Matvec time, get into it ⭐
  • multAdd(x, v, y) — Perform the matrix vector product with addition y = A @ x + v. Same energy, but we're adding v on top 👑
  • multHermitian(x, y) — Perform the Hermitian matrix vector product y = A^H @ x. Conjugate transpose core 🎀
  • multHermitianAdd(x, v, y) — Perform the Hermitian matrix vector product with addition y = A^H @ x + v. Hermitian and adding, she does it all 🌸
  • multTranspose(x, y) — Perform the transposed matrix vector product y = A^T @ x. Flip it and reverse it 😭
  • multTransposeAdd(x, v, y) — Perform the transposed matrix vector product with addition y = A^T @ x + v. Transposed plus v, periodt 💜
  • norm([norm_type]) — Compute the requested matrix norm. Rick to your Morty, norm to your matrix, iykyk 🌈
  • permute(row, col) — Return the permuted matrix. Reorder the whole situation 🔄
  • preallocatorPreallocate(A[, fill]) — Preallocate memory for a matrix using a preallocator matrix. Get the space sorted before you need it, main character planning energy 🧚
  • ptap(P[, result, fill]) — Creates the matrix product C = PᵀAP. Say the letters, do the math, slay ✨
  • rart(R[, result, fill]) — Create the matrix product C = RARᵀ. The rart sibling to ptap, obsessed 🫶
  • realPart([out]) — Return the real part of the matrix. Drop the imaginary, keep it grounded 💖
  • reorderForNonzeroDiagonal(isrow, iscol[, atol]) — Change a matrix ordering to remove zeros from the diagonal. Zero-free diagonal era, we love to see it 🔥
  • resetLMVM([destructive]) — Flushes all of the accumulated updates out of the LMVM matrix. Clean slate bestie, all of them, gone 💀
  • restoreDenseColumnVec(i[, mode, V]) — Restore the iᵗʰ column vector of the dense matrix. Give it back, gently 🎀
  • restoreDenseSubMatrix(mat) — Restore access to a submatrix of a Type.DENSE <#petsc4py.PETSc.Mat.Type.DENSE> matrix. Dense submatrix access, returned to sender 📦
  • restoreISLocalMat(local) — Restore the local matrix obtained with getISLocalMat. Put it back where it came from 🌸
  • restoreLocalSubMatrix(isrow, iscol, submat) — Restore a reference to a submatrix obtained with getLocalSubMatrix. Reference returned, no leaks, we're responsible 💅
  • retrieveValues() — Retrieve a copy of the matrix values previously stored with storeValues. A little copy, a little nostalgia ✨
  • scale(alpha) — Scale the matrix. Multiply the whole thing by alpha and let it shine ⭐
  • setBlockSize(bsize) — Set the matrix block size (same for rows and columns). One number, both directions, efficient 💖
  • setBlockSizes(row_bsize, col_bsize) — Set the row and column block sizes. Two numbers this time, because rows and columns don't always match 🦋
  • setDM(dm) — hands your matrix the DM that defines how its data is laid out ✨ like "here's the blueprint bestie, build yourself from this."
  • setDenseLDA(lda) — sets the leading dimension of the array that the dense matrix is using 💅 it's giving "tell me how wide your rows really are."
  • setDiagonal(diag[, addv]) — drops the diagonal values of the matrix in 🎀 the optional addv is the lil extra you can pass along.
  • setFromOptions() — configures the matrix straight from the options database, no cap 🙈 it just goes and reads what you already set up.
  • setISAllowRepeated([allow]) — lets repeated entries chill in the local-to-global map 💖 pass allow to control it.
  • setISLocalMat(local) — sets the local matrix living inside a Type.IS matrix, aka petsc4py.PETSc.Mat.Type.IS 👑
  • setISPreallocation(nnz, onnz) — preallocates memory for a Type.IS parallel matrix, petsc4py.PETSc.Mat.Type.IS style 🌸 nnz and onnz are the numbers it needs.
  • setLGMap(rmap[, cmap]) — sets the local-to-global mappings 🦋 rmap for the rows, and cmap if you wanna do the columns too.
  • setLMVMJ0(J0) — sets the initial Jacobian of the LMVM matrix ⭐ it's literally the J0.
  • setLMVMJ0KSP(ksp) — sets the KSP of the LMVM matrix 🔥 hand it your solver and let it cook.
  • setLRCMats(A, U[, c, V]) — sets the constituents of a Type.LRC matrix, aka petsc4py.PETSc.Mat.Type.LRC 💫 you got A, U, and optionally c and V.
  • setMumpsCntl(icntl, val) — sets a MUMPS parameter, and it's exactly this: CNTL[icntl] = val 🧚
  • setMumpsIcntl(icntl, ival) — sets a MUMPS parameter, same vibe: ICNTL[icntl] = ival 💜
  • setNearNullSpace(nsp) — sets the near-nullspace 🎀 your nsp goes in, and the matrix now knows its almost-kinda-nothing direction.
  • setNestVecType(vec_type) — sets the vector type for a Type.NEST matrix, petsc4py.PETSc.Mat.Type.NEST 🌈 tell it what kind of vectors the nest should hold.
  • setNullSpace(nsp) — sets the nullspace 💖 the actual one, not the near one. Iconic distinction honestly.
  • setOption(option, flag) — sets option 🙈 option plus its flag, and you're done.
  • setOptionsPrefix([prefix]) — sets the prefix that gets used when hunting for options in the database ✨ that lil string is how the matrix finds its own settings.
  • setPreallocationCOO(coo_i, coo_j) — sets preallocation using coordinate format with global indices 🌍 coo_i and coo_j are your coordinates.
  • setPreallocationCOOLocal(coo_i, coo_j) — same coordinate-format preallocation energy but with local indices 🏠 coo_i and coo_j again, just locally scoped.
  • setPreallocationCSR(csr) — preallocates memory for the matrix with a CSR layout 💅 hand it the csr and let it allocate.
  • setPreallocationDense(array) — sets the array used for storing matrix elements, for a dense matrix 🎀 dense girlies get their own storage array.
  • setPreallocationNNZ(nnz) — preallocates memory for the matrix using a non-zero pattern ⭐ nnz tells it how sparse you're being.
  • setPythonContext(context) — sets the instance of the class that implements the required Python methods 🐍 your context object is now in the building.
  • setPythonType(py_type) — sets the fully qualified Python name of the class to be used 🌸 py_type is the string, make it the full dotted path.
  • setRandom([random]) — sets random values in the matrix 🙈 optional random to steer the vibes.
  • setSizes(size[, bsize]) — sets the local, global and block sizes 💜 size carries the sizes and bsize is the optional block size.
  • setStencil(dims[, starts, dof]) — sets the matrix stencil 🦋 dims is required, with starts and dof as the optional extras.
  • setTransposeNullSpace(nsp) — sets the transpose nullspace 🔥 the nullspace but transposed, as the name literally says.
  • setTransposePrecursor(out) — Set transpose precursor. yes bestie, the transpose has a precursor, it's giving lore drop 💅
  • setType(mat_type) — Set the matrix type. mat_type is the whole personality of your matrix, choose wisely 🌈
  • setUnfactored() — Set a factored matrix to be treated as unfactored. it's giving "no thoughts, head empty" for a matrix that already did the work 😭
  • setUp() — Set up the internal data structures for using the matrix. the getting-ready montage moment ✨
  • setValue(row, col, value[, addv]) — Set a value to the (row, col) entry of the matrix. one lil cell, one lil vibe 🎀
  • setValueBlockedStagStencil(row, col, value) — Not implemented. ik it looks cute in the docs but nope, not a thing, not implemented 💀
  • setValueBlockedStencil(row, col, value[, addv]) — Set a block of values to row and col stencil. block party, stencil edition 🔥
  • setValueLocal(row, col, value[, addv]) — Set a value to the (row, col) entry of the matrix in local ordering. same energy as setValue but make it local 🏡
  • setValueStagStencil(row, col, value[, addv]) — Not implemented. stencil said "stag" and honestly it stayed home 🙈
  • setValueStencil(row, col, value[, addv]) — Set a value to row and col stencil. one value, placed with stencil precision ✨
  • setValues(rows, cols, values[, addv]) — Set values to the rows ⊗ cols entries of the matrix. plural era, we're doing a whole grid of them 🫶
  • setValuesBlocked(rows, cols, values[, addv]) — Set values to the rows ⊗ col block entries of the matrix. blocked = chunky, in the best way 🧚
  • setValuesBlockedCSR(I, J, V[, addv]) — Set values stored in block CSR format. give her the block CSR and she'll eat, no cap 💖
  • setValuesBlockedIJV(I, J, V[, addv, rowmap]) — Set a subset of values stored in block CSR format. a subset, a curated selection, a mood 🦋
  • setValuesBlockedLocal(rows, cols, values[, addv]) — Set values to the rows ⊗ col block entries of the matrix in local ordering. blocked but local, keep it in the neighborhood 🌸
  • setValuesBlockedLocalCSR(I, J, V[, addv]) — Set values stored in block CSR format. local ordering, block CSR, zero notes 💅
  • setValuesBlockedLocalIJV(I, J, V[, addv, rowmap]) — Set a subset of values stored in block CSR format. subset + local + block, she contains multitudes 😭
  • setValuesBlockedLocalRCV(R, C, V[, addv]) — Undocumented. the docs simply did not show up to work today 🤷
  • setValuesBlockedRCV(R, C, V[, addv]) — Undocumented. same as above bestie, we tell it like it is 💀
  • setValuesCOO(coo_v[, addv]) — Set values after preallocation with coordinate format. coordinate format girlies, this one's for you 📍
  • setValuesCSR(I, J, V[, addv]) — Set values stored in CSR format. classic, iconic, never not relevant 👑
  • setValuesIJV(I, J, V[, addv, rowmap]) — Set a subset of values stored in CSR format. yes the docs say CSR here, we don't question the docs, we archive them 🎀
  • setValuesLocal(rows, cols, values[, addv]) — Set values to the rows ⊗ col entries of the matrix in local ordering. local ordering, global slay 🌈
  • setValuesLocalCSR(I, J, V[, addv]) — Set values stored in CSR format. local CSR, keeping it close to home 🏡
  • setValuesLocalIJV(I, J, V[, addv, rowmap]) — Set a subset of values stored in CSR format. a subset, a lil taste, a sampler plate 🍓
  • setValuesLocalRCV(R, C, V[, addv]) — Undocumented. we simply do not know her story 🙈
  • `setValuesRCV(R, C, V[, addv]) — Undocumented. no lore available, moving on ✨
  • setVariableBlockSizes(blocks) — Set diagonal point-blocks of the matrix. every matrix deserves a custom fit 🔥
  • setVecType(vec_type) — Set the vector type. vec_type is the lewk your vectors are serving 💖
  • shift(alpha) — Shift the matrix. she moved, respectfully 💅
  • solve(b, x) — Solve Ax=b, given a factored matrix. 💅
  • solveAdd(b, y, x) — Solve x=y+A⁻¹b, given a factored matrix.
  • solveBackward(b, x) — Solve Ux=b, given a factored matrix A=LU.
  • solveForward(b, x) — Solve Lx = b, given a factored matrix A = LU.
  • solveTranspose(b, x) — Solve Aᵀx=b, given a factored matrix.
  • solveTransposeAdd(b, y, x) — Solve x=y+A⁻ᵀb, given a factored matrix.
  • storeValues() — Stash a copy of the matrix values. like a little save point bestie 🎀
  • toDLPack([mode]) — Return a DLPack PyCapsule wrapping the vector data. the capsule docs live at https://docs.python.org/3/c-api/capsule.html#c.PyCapsule if you wanna peek 👀
  • transpose([out]) — Return the transposed matrix.
  • transposeMatMult(mat[, result, fill]) — Perform matrix-matrix multiplication C=AᵀB.
  • updateLMVM(x, f) — Adds (X-Xprev) and (F-Fprev) updates to LMVM matrix.
  • view([viewer]) — View the matrix.
  • zeroEntries() — Zero the entries of the matrix. poof, gone 💀
  • zeroRows(rows[, diag, x, b]) — Zero selected rows of the matrix.
  • zeroRowsColumns(rows[, diag, x, b]) — Zero selected rows and columns of the matrix.
  • zeroRowsColumnsLocal(rows[, diag, x, b]) — Zero selected rows and columns of the matrix in local ordering.
  • zeroRowsColumnsStencil(rows[, diag, x, b]) — Zero selected rows and columns of the matrix.
  • `zeroRowsLocal(rows[, diag, x, b]) — Zero selected rows of the matrix in local ordering.

✨ Attributes Summary ✨

okay so these are the lil properties you can just. read off the matrix. no call, no parentheses, just vibes 🦋

  • assembled — The boolean flag indicating if the matrix is assembled.
  • block_size — Matrix block size.
  • block_sizes — Matrix row and column block sizes.
  • hermitian — The boolean flag indicating if the matrix is Hermitian.
  • local_size — Matrix local size.
  • owner_range — Matrix local row range.
  • owner_ranges — Matrix row ranges.
  • size — Matrix global size.
  • sizes — Matrix local and global sizes.
  • structsymm — The boolean flag indicating if the matrix is structurally symmetric.
  • symmetric — The boolean flag indicating if the matrix is symmetric.

📓 Methods Documentation 📓

H2OpusCompress(tol)

Compress a hierarchical matrix. 🧚✨

Collective.

like, the whole squad has to be in on this one, no cap — every process calls it together.

Parameters

Return type

See also:

Source code at petsc4py/PETSc/Mat.pyx:5239 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L5239 👑

  • H2OpusLowRankUpdate(U, V=None, s=1.0) — bestie, this does a low-rank update of the form self += sUVᵀ. That's it, that's the whole vibe. 💅

Collective. (So like, all your processes are in the group chat for this one.)

Parameters

  • U (Mat) — The dense low-rank update matrix.
  • V (Mat | None) — The dense low-rank update matrix. And if it's None? Then V = U, periodt. 🫶
  • s (float) — The scaling factor.

Return type: Self

See also: MatH2OpusLowRankUpdate

Source code at petsc4py/PETSc/Mat.pyx:5258

  • H2OpusOrthogonalize() — Orthogonalizes the basis tree of a hierarchical matrix. Iconic behavior honestly. ✨

Collective.

See also: MatH2OpusOrthogonalize

Return type: Self

Source code at petsc4py/PETSc/Mat.pyx:5226

  • HtoolGetPermutationSource() — Grabs the permutation of source (column) indices that Htool computed. 🎀

Not collective. (Solo mission, no group chat needed.)

Returns: The permutation index set for source indices.

Return type: IS

See also: HtoolGetPermutationTarget, MatHtoolGetPermutationSource

Source code at petsc4py/PETSc/Mat.pyx:5286

  • HtoolGetPermutationTarget() — Same energy as above but for the permutation of target (row) indices computed by Htool. 🌸

Not collective.

Returns: The permutation index set for target indices.

Return type: IS

See also: HtoolGetPermutationSource, MatHtoolGetPermutationTarget

Source code at petsc4py/PETSc/Mat.pyx:5305

  • HtoolUsePermutation(use) — Sets whether to actually use the permutation that Htool computed. Yay or nay, bestie. 💖

Logically collective.

Parameters

  • use (bool) — Whether to use the permutation.

Return type: Self

See also: MatHtoolUsePermutation

Source code at petsc4py/PETSc/Mat.pyx:5324

  • HtoolUseRecompression(use) — Sets whether to recompress the matrix after assembly. Like tidying up your room after the chaos of getting ready. 🧚

Logically collective.

Parameters

  • use (bool) — Whether to use recompression.

Return type: Self

See also: MatHtoolUseRecompression

Source code at petsc4py/PETSc/Mat.pyx:5343

  • SOR(b, x, omega=1.0, sortype=None, shift=0.0, its=1, lits=1) — Computes relaxation (SOR, Gauss-Seidel) sweeps. The classic little iterative glow-up. 🔥

Neighborwise collective. (iykyk)

See also: MatSOR

Source code at petsc4py/PETSc/Mat.pyx:4072

Parameters

  • b (Vec)
  • x (Vec)
  • omega (float)
  • sortype (SORType | None)
  • shift (float)
  • its (int)
  • lits (int)

Return type: None

  • allocateLMVM(x, f) — Allocates all the necessary common memory LMVM matrix. Getting all set up before the real work, no cap. ✨

Logically collective.

Parameters

  • x (Vec) — Solution vector.
  • f (Vec) — Function vector.

Return type: None

See also: MatLMVMAllocate

Source code at petsc4py/PETSc/Mat.pyx:5426

  • appendOptionsPrefix(prefix=None) — Tacks more onto the prefix that gets used when searching for options in the database. Like adding more emojis to your display name tbh. 🎀

Logically collective.

See also: Working with PETSc options, setOptionsPrefix, MatAppendOptionsPrefix

Source code at petsc4py/PETSc/Mat.pyx:1960

Parameters

  • prefix (str | None)

Return type: None

  • assemble(assembly=None) — Assembles the matrix. The big moment, the main character era, everything comes together. 👑

Collective.

Parameters

  • assembly (MatAssemblySpec) — The assembly type.

Return type: None

See also: assemblyBegin, assemblyEnd

Source code at petsc4py/PETSc/Mat.pyx:3585

  • assemblyBegin(assembly=None) — Kicks off an assembling stage of the matrix. The "getting ready" phase. 💅

Collective.

Parameters

  • assembly (MatAssemblySpec) — The assembly type.

Return type: None

See also: assemblyEnd, assemble, MatAssemblyBegin

Source code at petsc4py/PETSc/Mat.pyx:3549

  • assemblyEnd(assembly=None) — Wraps up an assembling stage of the matrix that you started with assemblyBegin. The reveal moment. ✨

Collective.

Parameters

  • assembly (MatAssemblySpec) — The assembly type.

Return type: None

See also: assemblyBegin, assemble, MatAssemblyEnd

Source code at petsc4py/PETSc/Mat.pyx:3567

  • axpy(alpha, X, structure=None) — Performs the matrix summation self + = ɑ·X. Math but make it glow. 🦋

Collective.

Parameters

  • alpha (Scalar) — The scalar.
  • X (Mat) — the matrix you're adding in, bestie 💖
    • structure (Structure | None) — the structure of the operation.

Return type: None

See also: MatAXPY (petsc.org/release/manualpages/Mat/MatAXPY.html)

Source code at petsc4py/PETSc/Mat.pyx:4400

aypx(alpha, X, structure=None)

Perform the matrix summation self = ɑ·self + X. okay this one is a whole vibe ✨

Collective.

Parameters:

  • alpha (Scalar) — the scalar 🎀
  • X (Mat) — the matrix to be added.
  • structure (Structure | None) — the structure of the operation.

Return type: None

See also: MatAYPX (petsc.org/release/manualpages/Mat/MatAYPX.html)

Source code at petsc4py/PETSc/Mat.pyx:4423

bindToCPU(flg)

Mark a matrix to temporarily stay on the CPU. it's giving "please just chill on the CPU for a sec" 💅

Collective.

Once marked, perform computations on the CPU. Like, that's the whole point, no cap.

Parameters:

  • flg (bool) — bind to the CPU if True.

Return type: None

See also: MatBindToCPU (petsc.org/release/manualpages/Mat/MatBindToCPU.html)

Source code at petsc4py/PETSc/Mat.pyx:4767

boundToCPU()

Query if a matrix is bound to the CPU. 🔍 just asking, minding my own business

Not collective.

See also: MatBoundToCPU (petsc.org/release/manualpages/Mat/MatBoundToCPU.html)

Source code at petsc4py/PETSc/Mat.pyx:4787

Return type: bool

chop(tol)

Set entries smallest of tol (in absolute values) to zero. bye bye tiny numbers, we don't know them 👋 🌸

Collective.

See also: MatFilter (petsc.org/release/manualpages/Mat/MatFilter.html)

Source code at petsc4py/PETSc/Mat.pyx:4368

Parameters:

  • tol (float)

Return type: None

conjugate(out=None)

Return the conjugate matrix. 💫

Collective.

Parameters:

  • out (Mat | None) — optional return matrix. If None, the operation is performed in-place. Otherwise, the operation is performed on out.

Return type: Mat

See also: realPart, imagPart, MatConjugate (petsc.org/release/manualpages/Mat/MatConjugate.html)

Source code at petsc4py/PETSc/Mat.pyx:2422

convert(mat_type=None, out=None)

Convert the matrix type. 🦋 glow-up but for matrices

Collective.

Parameters:

  • mat_type (Type | str | None) — the type of the new matrix. If None, uses Type.SAME.
  • out (Mat | None) — optional return matrix. If None, inplace conversion is performed. Otherwise, the matrix is reused.

Return type: Mat

See also: MatConvert (petsc.org/release/manualpages/Mat/MatConvert.html)

Source code at petsc4py/PETSc/Mat.pyx:2278

copy(result=None, structure=None)

Return a copy of the matrix. 🎀 twin energy fr fr

Collective.

Parameters:

  • result (Mat | None) — optional return matrix. If None, it is internally created.
  • structure (Structure | None) — the copy structure. Only relevant if result is not None.

Return type: Mat

See also: MatCopy (petsc.org/release/manualpages/Mat/MatCopy.html), MatDuplicate (petsc.org/release/manualpages/Mat/MatDuplicate.html)

Source code at petsc4py/PETSc/Mat.pyx:2233

create(comm=None)

Create the matrix. ✨

Collective.

Once created, the user should call setType or setFromOptions before using the matrix. Alternatively, specific creation routines such as createAIJ or createBAIJ can be used. pick your fighter 👑

Parameters:

  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type: Self

See also: destroy, MatCreate (petsc.org/release/manualpages/Mat/MatCreate.html)

Source code at petsc4py/PETSc/Mat.pyx:516

createAIJ(size, bsize=None, nnz=None, csr=None, comm=None)

Create a sparse Type.AIJ matrix, optionally preallocating. 🌈

Collective.

To preallocate the matrix the user can either pass nnz or csr describing the sparsity. If neither is set then preallocation will not occur. Consult the PETSc manual (petsc.org/release/manual/mat.html#sec-matsparse) for more information. 📚

Parameters:

  • size (MatSizeSpec) — matrix size.
  • bsize (MatBlockSizeSpec | None) — matrix block size. If None, a block size of 1 is set.
  • nnz (NNZSpec | None) — optional non-zeros preallocation pattern.
  • csr (CSRSpec | CSRIndicesSpec | None) — optional compressed sparse row layout information. If provided, it takes precedence on nnz.
  • comm (Comm | None) — the MPI communicator bestie, defaults to Sys.getDefaultComm. 💫

Return type: Self

See also: setSizes, createBAIJ, MATAIJ, MATSEQAIJ, MATMPIAIJ, MatCreateAIJ, MatSeqAIJSetPreallocation, MatSeqAIJSetPreallocationCSR

Source code at petsc4py/PETSc/Mat.pyx:721

✨ createAIJCRL(size, bsize=None, nnz=None, csr=None, comm=None)

Bestie, this one creates a sparse Type.AIJCRL matrix. 🔥

Collective. (yes, every proc has to show up, it's giving group project energy 💅)

It's literally the same vibe as Type.AIJ matrices except it stashes some extra info that makes the matrix-vector product vectorize better. Slay.

To preallocate, you either pass nnz or csr describing the sparsity. If you pass neither then preallocation just… doesn't happen. That's it, that's the tea. Consult the PETSc manual for more on that.

Parameters

  • size (MatSizeSpec) — matrix size.
  • bsize (MatBlockSizeSpec | None) — matrix block size. If it's None, a block size of 1 gets set. default behaviour, no cap.
  • nnz (NNZSpec | None) — optional non-zeros preallocation pattern.
  • csr (CSRSpec | CSRIndicesSpec | None) — optional compressed sparse row layout info. Heads up: if you give it, it takes precedence over nnz. csr said main character. 👑
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type: Self

See also: createAIJ, createBAIJ, MatCreateSeqAIJCRL, MatCreateMPIAIJCRL

Source code at petsc4py/PETSc/Mat.pyx:854

✨ createAIJWithArrays(size, csr, bsize=None, comm=None)

Creates a sparse Type.AIJ matrix with the data already sitting there in CSR format. 🧚

Collective.

Parameters

  • size (MatSizeSpec) — matrix size.
  • csr (CSRSpec | tuple[CSRSpec, CSRSpec]) — local matrix data, in compressed sparse row format.
  • bsize (MatBlockSizeSpec | None) — matrix block size. If it's None, a block size of 1 gets set.
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type: Self

Notes

ok so listen 🫶 for Type.SEQAIJ matrices, the csr data is not copied. For Type.MPIAIJ matrices, the csr data is not copied only in the case where it represents on-process and off-process information. So like, careful who you hand your arrays to.

See also: createAIJ, MatCreateSeqAIJWithArrays, MatCreateMPIAIJWithArrays, MatCreateMPIAIJWithSplitArrays

Source code at petsc4py/PETSc/Mat.pyx:1048

✨ createBAIJ(size, bsize, nnz=None, csr=None, comm=None)

Creates a sparse blocked Type.BAIJ matrix, optionally preallocating. 💖

Collective.

To preallocate you either pass nnz or csr describing the sparsity. Neither? Then preallocation will not occur, periodt. Consult the PETSc manual for more.

Parameters

  • size (MatSizeSpec) — matrix size.
  • bsize (MatBlockSizeSpec) — matrix block size. (this one is required, no default, it's the whole point bestie 🎀)
  • nnz (NNZSpec | None) — optional non-zeros preallocation pattern for block rows.
  • csr (CSRSpec | CSRIndicesSpec | None) — optional block-compressed sparse row layout info. If you provide it, it takes precedence over nnz. 👑
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type: Self

See also: setSizes, createAIJ, MATBAIJ, MATSEQBAIJ, MATMPIBAIJ, MatCreateBAIJ

Source code at petsc4py/PETSc/Mat.pyx:766

✨ createConstantDiagonal(size, diag, comm=None)

Creates a diagonal matrix of type Type.CONSTANTDIAGONAL. so clean, so simple, we love her 🌸

Collective.

Parameters

  • size (MatSizeSpec) — matrix size.
  • diag (float) — the diagonal value.
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type: Self

See also: createDiagonal

Source code at petsc4py/PETSc/Mat.pyx:1770

✨ createDense(size, bsize=None, array=None, comm=None)

Creates a Type.DENSE matrix. 🌈

Collective.

Parameters

  • comm (Comm | None) — the MPI communicator, bestie 🫶 If you don't hand one over, it just defaults to Sys.getDefaultComm and moves on with its life.

Return type

Self

See also:

createDenseCUDA, MATDENSE, MatCreateDense. If you wanna peek at the receipts, they live at petsc.org/release/manualpages/Mat/MATDENSE.html and petsc.org/release/manualpages/Mat/MatCreateDense.html.

Source code at petsc4py/PETSc/Mat.pyx:1139

✨ createDenseCUDA(size, bsize=None, array=None, cudahandle=None, comm=None)

Okay so this one is the GPU girlie of the family 💅 It creates a Type.DENSECUDA matrix, and you can optionally feed it data on the host and data on the device. So extra of it.

Collective. — meaning everybody in the communicator has to show up, no ghosting 🫂

Parameters

  • size (MatSizeSpec) — Matrix size. That's the vibe.
  • bsize (MatBlockSizeSpec | None) — Matrix block size. If None, a block size of 1 is set. Simple as that.
  • array (Sequence[Scalar] | None) — Host data. It gets lazily allocated if you pass None — so it's not ignoring you, it's just doing it later 🦋
  • cudahandle (int | None) — Address of the array on the GPU. Also lazily allocated if None.
Heads up bestie: if cudahandle is provided, array will be ignored. Fully ignored. Not even a little bit used 🙈
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type

Self

See also:

createDense, MatCreateDenseCUDA — more deets at petsc.org/release/manualpages/Mat/MatCreateDenseCUDA.html.

Source code at petsc4py/PETSc/Mat.pyx:1175

✨ createDiagonal(diag)

Makes a diagonal matrix of type Type.DIAGONAL. That's it, that's the whole personality, and honestly? Iconic minimalist behavior 👑

Collective.

Parameters

  • diag (Vec) — The vector holding diagonal values. Like, the actual diagonal, in Vec form.

Return type

Self

See also:

createConstantDiagonal

Source code at petsc4py/PETSc/Mat.pyx:1803

✨ createH2OpusFromMat(A, coordinates=None, dist=None, eta=None, leafsize=None, maxrank=None, bs=None, rtol=None)

Create a hierarchical Type.H2OPUS matrix by sampling from an operator you already have. It's giving "I learned your matrix by watching it" 👀

Collective.

Parameters

  • A (Mat) — Matrix to be sampled. The source of truth, the moment.
  • coordinates (Sequence[Scalar] | None) — Coordinates of the points.
  • dist (bool | None) — Whether or not coordinates are distributed, defaults to False.
  • eta (float | None) — Admissibility condition tolerance, defaults to DECIDE.
  • leafsize (int | None) — Leaf size in cluster tree, defaults to DECIDE.
  • maxrank (int | None) — Maximum rank permitted, defaults to DECIDE.
  • bs (int | None) — Maximum number of samples to take concurrently, defaults to DECIDE.
  • rtol (float | None) — Relative tolerance for construction, defaults to DECIDE.

Return type

Self

Notes

See MatCreateH2OpusFromMat for the appropriate database options. All the DECIDE defaults mean PETSc itself decides, so don't come for me about the numbers 😌

See also:

Working with PETSc options, MatCreateH2OpusFromMat — full page at petsc.org/release/manualpages/Mat/MatCreateH2OpusFromMat.html.

Source code at petsc4py/PETSc/Mat.pyx:1546

✨ createHermitianTranspose(mat)

createHermitianTranspose(mat)

Creates a Type.HERMITIANTRANSPOSE matrix that behaves like (A*)ᵀ. It behaves like it. It does not become it 😭

Collective.

Parameters

  • mat (Mat) — Matrix A to represent the Hermitian transpose of.

Return type

Self

Notes

The Hermitian transpose is never actually formed. It's virtual, it's an illusion, it's main character energy with no physical form ✨

See also:

createNormal, createNormalHermitian, MATHERMITIANTRANSPOSEVIRTUAL, MatCreateHermitianTranspose. Links for the curious: petsc.org/release/manualpages/Mat/MATHERMITIANTRANSPOSEVIRTUAL.html and petsc.org/release/manualpages/Mat/MatCreateHermitianTranspose.html.

Source code at petsc4py/PETSc/Mat.pyx:1375

✨ createHtoolFromKernel(size, spacedim, coords_target, coords_source, kernel, kernelctx=None, comm=None)

Creates a Type.HTOOL matrix using a kernel function you define in Python 🐍🔥 Yes bestie, actual Python callbacks driving a matrix. We love to see it.

Collective.

Parameters

  • size (MatSizeSpec) — Matrix size.
  • spacedim (int) — Dimension of the coordinate space.
  • coords_target (Sequence[Scalar]) — Local target (row) coordinates, shape (m, spacedim).
  • coords_source (Sequence[Scalar]) — the local source (a.k.a. column) coordinates bestie, shaped (n, spacedim). 💅
  • kernel (MatHtoolKernelFunction) — a Python callable looking like kernel(sdim, M, N, rows, cols, v, ctx) that fills in the submatrix v[i, j] for target index rows[i] and source index cols[j]. Heads up: v has shape (M, N) and it's in column-major order. 👑
  • kernelctx (Any) — optional context, passed along as the very last argument to kernel.
  • comm (Comm | None) — MPI communicator, and if you ghost it, it defaults to Sys.getDefaultComm. ✨

Return type

Self

Notes

Okay so real talk: this function gets called while the Python Global Interpreter Lock (GIL) is held. 💀 Which means pure Python implementations are not gonna scale with multithreading, periodt. For better performance, bestie, you should delegate the heavy computations to compiled code that releases the GIL — that lets things run in parallel inside threaded regions. And for maximum performance? Consider implementing the generator directly in C or C++ instead of using the Python interface. Like, actually. Also peep MatCreateHtoolFromKernel for the appropriate database options. 🔥

See also: Working with PETSc options, MatCreateHtoolFromKernel, HtoolGetPermutationSource, HtoolGetPermutationTarget, HtoolUsePermutation, HtoolUseRecompression

Source code at petsc4py/PETSc/Mat.pyx:1627 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L1627

createIS(size, bsize=None, lgmapr=None, lgmapc=None, comm=None)

Create a Type.IS matrix that represents globally unassembled operators. 🌸

Collective.

Parameters

  • size (MatSizeSpec) — Matrix size, babe.
  • bsize (MatBlockSizeSpec | None) — Matrix block size. And if it's None, a block size of 1 gets set. Simple as that.
  • lgmapr (LGMap | None) — Optional local-to-global mapping for the rows. If it's None, the local row space just matches the global row space. 🦋
  • lgmapc (LGMap | None) — Optional local-to-global mapping for the columns. If it's None, the local column space matches the global column space.
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm when you don't pass one. 💜

Return type

Self

See also: MATIS

Source code at petsc4py/PETSc/Mat.pyx:1717 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L1717

createLRC(A, U, c, V)

Create a low-rank correction Type.LRC matrix representing A + UCVᵀ. It's giving ✨math✨.

Collective.

Parameters

  • A (Mat | None) — a sparse matrix, and yes it can be None.
  • U (Mat) — dense rectangular matrix.
  • c (Vec | None) — a vector holding the diagonal of C. Can be None, no stress.
  • V (Mat | None) — dense rectangular matrix, and it can be set to U or 'None'.

Return type

Self

Notes

The matrix A + UCVᵀ is never actually formed — it's all vibes and lazy evaluation, iykyk. 🙈

C is a diagonal matrix (represented as a vector) of order k, where k is the number of columns of both U and V.

If A is None, then the new object behaves like a low-rank matrix UCVᵀ.

Use the same matrix for V and U (or set V=None) for a symmetric low-rank correction, aka A + UCUᵀ. 🎀

If c is None, then the low-rank correction is just U*Vᵀ. And if a sequential c vector is used for a parallel matrix, PETSc assumes that the values of the vector are consistently set across processors. No cap.

See also: MATLRC, MatCreateLRC

Source code at petsc4py/PETSc/Mat.pyx:1400 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L1400

createNest(mats, isrows=None, iscols=None, comm=None)

Create a Type.NEST matrix holding a whole lil family of submatrices. Nesting rights: slay. 🪺✨

Collective.

Parameters

  • mats (Sequence[Sequence[Mat]]) — an iterable of matrix block rows with size len(isrows). And every single matrix block row has to be of size len(iscols). Oh, and empty submatrices can be set with None. 🫶
  • isrows (Sequence[IS] | None) — index set for each nested row block; defaults to contiguous ordering.
  • iscols (Sequence[IS] | None) — index set for each nested column block; defaults to contiguous ordering.
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm. ⭐

Return type

Self

See also: MatCreateNest, MATNEST

Source code at petsc4py/PETSc/Mat.pyx:1479 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L1479

createNormal(mat)

Create a Type.NORMAL matrix representing AᵀA. Normal matrix? More like iconic matrix. 👑

Collective.

Parameters

  • mat (Mat) — the (possibly rectangular) matrix A.

Return type

Self

Notes

The product AᵀA is never actually formed. Instead A and Aᵀ get used during mult and various other matrix operations. Que eficiente, bestie. 💅

See also: MATNORMAL (https://petsc.org/release/manualpages/Mat/MATNORMAL.html) and MatCreateNormal (https://petsc.org/release/manualpages/Mat/MatCreateNormal.html)

Source code at petsc4py/PETSc/Mat.pyx:1280 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L1280

createNormalHermitian(mat)

okay so this one hands you a Type.NORMALHERMITIAN matrix that represents (A*)ᵀA, like a stand-in, a stunt double, main character energy without actually doing the work. ✨

Collective — everybody in the communicator has to show up, no ghosting allowed. 💅

Parameters

  • mat (Mat) — the (possibly rectangular) matrix A. Rectangular? She can be whatever shape she wants, we don't judge. 🫶

Return type

Self (https://docs.python.org/3/library/typing.html#typing.Self)

Notes

the product (A*)ᵀA is never actually formed. not once. never. it's giving imaginary-friend energy — the matrix acts like the product while the product itself stays unmanifested. 💀 iconic honestly.

See also: createHermitianTranspose, MATNORMAL (https://petsc.org/release/manualpages/Mat/MATNORMAL.html), MATNORMALHERMITIAN (https://petsc.org/release/manualpages/Mat/MATNORMALHERMITIAN.html), MatCreateNormalHermitian (https://petsc.org/release/manualpages/Mat/MatCreateNormalHermitian.html)

Source code at petsc4py/PETSc/Mat.pyx:1350 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L1350

createPython(size, context=None, comm=None)

bestie, this is the one where you bring your OWN matrix — it creates a Type.PYTHON matrix, i.e. a matrix that's secretly a Python class wearing a trench coat. 🧚

Collective. obviously.

Parameters

Return type

Self (https://docs.python.org/3/library/typing.html#typing.Self)

See also: PETSc Python matrix type, setType, setPythonContext, Type.PYTHON

Source code at petsc4py/PETSc/Mat.pyx:1826 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L1826

createSBAIJ(size, bsize, nnz=None, csr=None, comm=None)

sparse matrix time!! 🎀 this makes a Type.SBAIJ sparse matrix in symmetric block format — the S stands for symmetric, the B for block, and the AIJ is doing its own thing, iykyk.

Collective.

so to preallocate you've got options: pass nnz or pass csr describing the sparsity. If neither is set then preallocation will not occur — she'll just grow on her own, chaotically. Consult the PETSc manual (https://petsc.org/release/manual/mat.html#sec-matsparse) for more info. 📖

Parameters

Return type

Self (https://docs.python.org/3/library/typing.html#typing.Self)

See also: createAIJ, createBAIJ, MatCreateSBAIJ (https://petsc.org/release/manualpages/Mat/MatCreateSBAIJ.html)

Source code at petsc4py/PETSc/Mat.pyx:810 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L810

createScatter(scatter, comm=None)

new matrix just dropped, and it's literally a Type.SCATTER matrix built out of a vector scatter. yes, a matrix whose whole personality is moving data around. it's the group-chat-forwarder of linear algebra. 😭

Collective.

Parameters

Return type

Self (https://docs.python.org/3/library/typing.html#typing.Self)

See also: MATSCATTER (https://petsc.org/release/manualpages/Mat/MATSCATTER.html), MatCreateScatter (https://petsc.org/release/manualpages/Mat/MatCreateScatter.html)

Source code at petsc4py/PETSc/Mat.pyx:1256 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L1256

createSchurComplement(A00, Ap00, A01, A10, A11=None)

Schur complement girlies rise 🦋 this one creates a Type.SCHURCOMPLEMENT matrix. it's all about carving up a big block matrix into little pieces and then doing math on the pieces.

Collective.

Parameters

  • A00 (Mat) — the upper-left block of the original matrix A = [A00 A01; A10 A11].
  • Ap00 (Mat) — used to construct the preconditioner used in ksp(A00,Ap00) to approximate the action of A00^{-1}. it's the approximation bestie, not the real thing. 🫶
  • A01 (Mat) — the upper-right block of the original matrix A = [A00 A01; A10 A11].
  • A10 (Mat) — the lower-left block of the original matrix A = [A00 A01; A10 A11].
  • A11 (Mat | None (https://docs.python.org/3/builtins/constants.html#None)) — optional lower-right block of the original matrix A = [A00 A01; A10 A11].

Return type

Self (https://docs.python.org/3/library/typing.html#typing.Self)

See also: MatCreateSchurComplement (https://petsc.org/release/manualpages/KSP/MatCreateSchurComplement.html)

Source code at petsc4py/PETSc/Mat.pyx:4216 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L4216

createSubMatrices(isrows, iscols=None, submats=None)

returns a whole bunch of sequential submatrices, like a little squad of smaller matrices extracted from one big one. 🔥

Collective.

Parameters

Return type

Sequence (https://docs.python.org/3/library/typing.html#typing.Sequence)[Mat]

See also: MatCreateSubMatrices (https://petsc.org/release/manualpages/Mat/MatCreateSubMatrices.html)

Source code at petsc4py/PETSc/Mat.pyx:4159 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L4159

createSubMatrix(isrow, iscol=None, submat=None)

just one submatrix this time. no crowd, no squad, a single little matrix pulled out of the big one. 🌸

Collective.

Parameters

  • isrow (IS) — row index set.
  • iscol (IS | None) — the Column index set, bestie 💅 — if it's None, then iscol = isrow.
  • submat (Mat | None) — optional resultant matrix 🫶. When it's None, a fresh new matrix gets created, and MAT_INITIAL_MATRIX is used. When it's not None, the matrix gets reused with MAT_REUSE_MATRIX.

Return type — Mat

See also: MatCreateSubMatrix

Source code at petsc4py/PETSc/Mat.pyx:4129

createSubMatrixVirtual(A, isrow, iscol=None)

Create a Type.SUBMATRIX matrix that acts as a submatrix ✨

Collective.

Parameters

  • A (Mat) — the Matrix to extract the submatrix from.
  • isrow (IS) — the Rows present in the submatrix.
  • iscol (IS | None) — the Columns present in the submatrix, defaults to isrow.

Return type — Self

See also: MatCreateSubMatrixVirtual

Source code at petsc4py/PETSc/Mat.pyx:1454

createTranspose(mat)

Create a Type.TRANSPOSE matrix that behaves like Aᵀ 🔄

Collective.

Parameters

  • mat (Mat) — the Matrix A to represent the transpose of.

Return type — Self

Notes

The transpose is never actually formed 🫢. Instead multTranspose is called whenever the matrix-vector product is computed. It's giving lazy-but-efficient, and honestly? iconic.

See also: createNormal, MatCreateTranspose

Source code at petsc4py/PETSc/Mat.pyx:1305

createVecLeft()

Return a left vector — a vector that the matrix vector product can be stored in 💖

Collective.

See also: createVecs, createVecRight, MatCreateVecs

Source code at petsc4py/PETSc/Mat.pyx:3685

Return type — Vec

createVecRight()

Return a right vector — a vector that the matrix can be multiplied against 🌸

Collective.

See also: createVecs, createVecLeft, MatCreateVecs

Source code at petsc4py/PETSc/Mat.pyx:3671

Return type — Vec

createVecs(side=None)

Return vectors that can be used in matrix vector products 🌈

Collective.

Parameters

  • side (Literal['r', 'R', 'right', 'Right', 'RIGHT', 'l', 'L', 'left', 'Left', 'LEFT'] | None) — if it's None, you get a 2-tuple of vectors (right, left) 🎀. Otherwise it just returns a left or right vector.

Return type — Vec | tuple[Vec, Vec]

Notes

right is a vector that the matrix can be multiplied against. left is a vector that the matrix-vector product can be stored in. no cap, that's the whole vibe 🦋

See also: createVecLeft, createVecRight, MatCreateVecs

Source code at petsc4py/PETSc/Mat.pyx:3632

destroy()

Destroy the matrix 💀 — it's over, bestie.

Collective.

See also: create, MatDestroy

Source code at petsc4py/PETSc/Mat.pyx:503

Return type — Self

diagonalScale(L=None, R=None)

Perform left and/or right diagonal scaling of the matrix ⚖️

Collective.

Parameters

  • L (Vec | None) — optional left scaling vector.
  • R (Vec | None) — optional right scaling vector.

Return type — None

See also: MatDiagonalScale

Source code at petsc4py/PETSc/Mat.pyx:3824

duplicate(copy=False)

Return a clone of the matrix 👯‍♀️✨

Collective.

Parameters

  • copy (DuplicateOption | bool) — if it's True, it also copies the values. lowkey important detail, don't skip it.

Return type — Mat

See also: MatDuplicate

Source code at petsc4py/PETSc/Mat.pyx:2213

equal(mat)

Return the result of matrix comparison 🧐

Collective.

See also: MatEqual

Source code at petsc4py/PETSc/Mat.pyx:2466

Parameters

  • mat (Mat)

Return type — bool

factorCholesky(isperm, options=None)

Perform an in-place Cholesky factorization 🔥

Collective.

Parameters

  • isperm (IS) — the row and column permutations.
  • options (dict[str, Any] | None) — an optional dictionary of options for the factorization 💅. These include fill, the expected fill as a ratio of the original fill.

Return type — None

See also: factorLU, MatCholeskyFactor

Source code at petsc4py/PETSc/Mat.pyx:4931

okay that's this chunk, and there's literally so much more coming — stay with me bestie, we're not even close to done 🫶🌸

factorICC(isperm, options=None)</p>

Performs an in-place incomplete Cholesky factorization, bestie. ✨

Collective. (so everybody has to show up to this party, no lurking)

Parameters

  • isperm (IS) — the row and column permutations.
  • options (dict[str, Any] | None) — an optional dictionary of options for the factorization. These include fill, the expected fill as a ratio of the original fill.

Return type

None

See also:

factorILU, MatICCFactor (petsc.org/release/manualpages/Mat/MatICCFactor.html)

Source code at petsc4py/PETSc/Mat.pyx:4964 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L4964)

factorILU(isrow, iscol, options=None)</p>

Performs an in-place ILU factorization. 💅

Collective.

Parameters

  • isrow (IS) — the row permutation.
  • iscol (IS) — the column permutation.
  • options (dict[str, Any] | None) — an optional dictionary of options for the factorization. These include levels, the number of levels of fill, fill, the expected fill as a ratio of the original fill, and dtcol, the pivot tolerance where 0 indicates no pivot and 1 indicates full column pivoting.

Return type

None

See also:

MatILUFactor (petsc.org/release/manualpages/Mat/MatILUFactor.html)

Source code at petsc4py/PETSc/Mat.pyx:4897 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L4897)

factorLU(isrow, iscol, options=None)</p>

Performs an in-place LU factorization. 🦋

Collective.

Parameters

  • isrow (IS) — the row permutation.
  • iscol (IS) — the column permutation.
  • options (dict[str, Any] | None) — an optional dictionary of options for the factorization. These include fill, the expected fill as a ratio of the original fill and dtcol, the pivot tolerance where 0 indicates no pivot and 1 indicates full column pivoting.

Return type

None

See also:

MatLUFactor (petsc.org/release/manualpages/Mat/MatLUFactor.html)

Source code at petsc4py/PETSc/Mat.pyx:4859 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L4859)

factorNumericCholesky(mat, options=None)</p>

Not implemented. 💀 like bestie we didn't build this one, don't come for me.

Source code at petsc4py/PETSc/Mat.pyx:4960 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L4960)

Parameters

  • mat (Mat)

Return type

None

factorNumericLU(mat, options=None)</p>

Not implemented. 🙈

Source code at petsc4py/PETSc/Mat.pyx:4893 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L4893)

Parameters

  • mat (Mat)

Return type

None

factorSymbolicCholesky(isperm, options=None)</p>

Not implemented. 😭

Source code at petsc4py/PETSc/Mat.pyx:4956 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L4956)

Parameters

  • isperm (IS)

Return type

None

factorSymbolicICC(isperm, options=None)</p>

Not implemented. 🌸

Source code at petsc4py/PETSc/Mat.pyx:4989 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L4989)

Parameters

  • isperm (IS)

Return type

None

factorSymbolicILU(isrow, iscol, options=None)</p>

Not implemented. 🎀

Source code at petsc4py/PETSc/Mat.pyx:4927 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L4927)

Parameters

  • isrow (IS)
  • iscol (IS)

Return type

None

factorSymbolicLU(mat, isrow, iscol, options=None)</p>

Not implemented. 💜

Source code at petsc4py/PETSc/Mat.pyx:4889 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L4889)

Parameters

  • mat (Mat)
  • isrow (IS)
  • iscol (IS)

Return type

None

findZeroRows()</p>

Returns the index set of empty rows. 👑

Collective.

See also:

MatFindZeroRows (petsc.org/release/manualpages/Mat/MatFindZeroRows.html)

Source code at petsc4py/PETSc/Mat.pyx:3618 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3618)

Return type

IS

fixISLocalEmpty(fix=True)</p>

Compresses out zero local rows from the local matrices. the way it just cleans up for you ✨

Collective.

Parameters

  • fix (bool) — when True, new local matrices and local to global maps are generated during the final assembly process.

Return type

None

See also:

MatISFixLocalEmpty (petsc.org/release/manualpages/Mat/MatISFixLocalEmpty.html)

Source code at petsc4py/PETSc/Mat.pyx:5064 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L5064)

getBlockSize()</p>

Returns the matrix block size. 🧚

Not collective. (so it's a solo mission, she does it alone)

See also:

getBlockSize, MatGetBlockSize (petsc.org/release/manualpages/Mat/MatGetBlockSize.html)

Source code at petsc4py/PETSc/Mat.pyx:2083 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2083)

Return type

int

getBlockSizes()</p>

Returns the row and column block sizes — both of them, a little duo 🫶

Not collective.

See also:

getBlockSize, MatGetBlockSizes (petsc.org/release/manualpages/Mat/MatGetBlockSizes.html)

Source code at petsc4py/PETSc/Mat.pyx:2097 (gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2097)

Return type

tuple[int, int]

getColumnIJ(symmetric=False, compressed=False)</p>

Returns the CSC representation of the local sparsity pattern. 🌈

okay so this one is Collective 🫶 — like, everybody on the communicator shows up for this, no skipping 💅

Parameters

  • symmetric (bool) — if it's True, hand back the symmetrized graph ✨
  • compressed (bool) — if it's True, hand back the compressed graph 🎀

Return type

tuple[ArrayInt, ArrayInt] — a whole duo of arrays, bestie, iconic 🫶

See also: MatGetRowIJ

Source code at petsc4py/PETSc/Mat.pyx:2744

getColumnVector(column, result=None)

Gives you back the *column*ᵗʰ column vector of the matrix, literally the whole vibe of one column 🌸

Collective — everyone's in it together 💖

Parameters

  • column (int) — which column, index-style.
  • result (Vec | None) — optional vector to stash the result in, if you already have one and don't want a fresh one 🙈

Return type

Vec

See also: MatGetColumnVector

Source code at petsc4py/PETSc/Mat.pyx:3705

getDM()

Returns the DM that defines the data layout of the matrix 💅 like, the matrix's blueprint, its little floor plan.

Not collective — this one stays on your process, no group chat needed 🧚

See also: MatGetDM

Source code at petsc4py/PETSc/Mat.pyx:6079

Return type

DM

getDenseArray(readonly=False)

Returns the array where the data is actually stored — the real raw data location, no cap 💀

Not collective — just you, bestie.

Parameters

  • readonly (bool) — set it to get a read only array, so nobody (including you 👀) can mess with it.

Return type

ArrayScalar

See also: MatDenseGetArrayRead, MatDenseGetArray

Source code at petsc4py/PETSc/Mat.pyx:5821

getDenseColumnVec(i, mode='rw')

Returns the iᵗʰ column vector of the dense matrix 🔥 column-vector energy, but make it dense.

Collective — yes queen, all together 💖

Parameters

  • i (int) — the column index you're tryna access.
  • mode (AccessModeSpec) — the access type of the vector you get back (read? write? read-write? it's giving options ✨).

Return type

Vec

See also: restoreDenseColumnVec, MatDenseGetColumnVec, MatDenseGetColumnVecRead, MatDenseGetColumnVecWrite

Source code at petsc4py/PETSc/Mat.pyx:5930

getDenseLDA()

Returns the leading dimension of the array that the dense matrix is using — the LDA, the stride situation, the ✨math✨ behind the storage 🌈

Not collective — solo mission, babe.

See also: MatDenseGetLDA

Source code at petsc4py/PETSc/Mat.pyx:5807

Return type

int

getDenseLocalMatrix()

Returns the local part of the dense matrix — just your slice of the pie, the part that's yours 🍓

Not collective — your process, your business 💅

See also: MatDenseGetLocalMatrix

Source code at petsc4py/PETSc/Mat.pyx:5862

Return type

Mat

getDenseSubMatrix(rbegin=DECIDE, rend=DECIDE, cbegin=DECIDE, cend=DECIDE)

Gets you access to a submatrix of a Type.DENSE matrix 👑 like zooming into a little rectangle of the whole thing.

Collective — group effort, always 🫶

Parameters

  • rbegin (int) — the first global row index.
  • rend (int) — the global row index just past the last one (exclusive, bestie, mind the gap 🙈).
  • cbegin (int) — the first global column index.
  • cend (int) — the global column index just past the last one.

Return type

Mat

See also: restoreDenseSubMatrix, MatDenseGetSubMatrix

Source code at petsc4py/PETSc/Mat.pyx:5877

getDiagonal(result=None)

Returns the diagonal of the matrix 🎀 the main-character line, the one everybody looks at first.

Collective — all of us, together ✨

Parameters

  • result (Vec | None) — optional vector to store the result in, if you've got one lying around and wanna reuse it 💜

Return type

Vec

See also: setDiagonal, MatGetDiagonal

Source code at petsc4py/PETSc/Mat.pyx:3760

getDiagonalBlock()

Returns the part of the matrix that's associated with the on-process coupling — a.k.a. the block that belongs to you, no cross-process situations happening here 💅

Not collective — strictly local, periodt.

See also: MatGetDiagonalBlock

Source code at petsc4py/PETSc/Mat.pyx:4101

Return type

Mat

getISAllowRepeated()

Gets the flag for repeated entries in the local-to-global map 🙈 like, is this map allowed to have the same thing twice? This tells you.

Not collective — your process only, bestie.

See also: setISAllowRepeated, MatISGetAllowRepeated

Source code at petsc4py/PETSc/Mat.pyx:5050

Return type

bool

getISLocalMat()

Returns the local matrix that's stored inside a Type.IS matrix ✨ the little matrix tucked inside the bigger IS matrix situation.

Not collective — local business only 💖

See also: MatISGetLocalMat

Source code at petsc4py/PETSc/Mat.pyx:5083

Return type

Mat

getInertia()

Returns the inertia from a factored matrix 🧚 iconic factorization behavior.

Collective — everyone's needed, no solo runs 🫶

Heads up bestie: the matrix must have been factored by calling factorCholesky first, otherwise this is not giving what it's supposed to give 🌸

Returns

  • n (int) — the number of negative eigenvalues.
  • z (int) — the number of zero eigenvalues.
  • p (int) — the number of positive eigenvalues. 🫶

Return type: tuple[int, int, int] ✨

See also: MatGetInertia — https://petsc.org/release/manualpages/Mat/MatGetInertia.html

Source code at petsc4py/PETSc/Mat.pyx:4993 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L4993

✨ getInfo(info=None)

Return summary information. 💅

Collective. (yes bestie, everybody's in on this one)

Parameters:

  • info (InfoType | None) — if it's None, it just uses InfoType.GLOBAL_SUM for you. Defaults are a gift. 🎀

Return type: dict[str, float] a whole lil dictionary, slay

See also: MatInfo, MatGetInfo — https://petsc.org/release/manualpages/Mat/MatInfo.html , https://petsc.org/release/manualpages/Mat/MatGetInfo.html

Source code at petsc4py/PETSc/Mat.pyx:2193 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2193

🦋 getLGMap()

Return the local-to-global mappings. like, the map from here to everywhere. 🗺️

Not collective.

See also: setLGMap, MatGetLocalToGlobalMapping — https://petsc.org/release/manualpages/Mat/MatGetLocalToGlobalMapping.html

Source code at petsc4py/PETSc/Mat.pyx:3031 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3031

Return type: tuple[LGMap, LGMap] — two of them, because of course 💖

🌸 getLMVMJ0()

Get the initial Jacobian of the LMVM matrix. the original one, the blueprint, the main character reveal. 👑

Not collective.

See also: setLMVMJ0, MatLMVMGetJ0 — https://petsc.org/release/manualpages/KSP/MatLMVMGetJ0.html

Source code at petsc4py/PETSc/Mat.pyx:5364 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L5364

Return type: Mat

💜 getLMVMJ0KSP()

Get the KSP of the LMVM matrix. handing you back the solver that lives inside. 🔥

Not collective.

See also: setLMVMJ0KSP, MatLMVMGetJ0KSP — https://petsc.org/release/manualpages/KSP/MatLMVMGetJ0KSP.html

Source code at petsc4py/PETSc/Mat.pyx:5395 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L5395

Return type: Mat

🎀 getLRCMats()

Return the constituents of a Type.LRC matrix. it's giving "unpack the whole thing" — every piece of the low-rank-correction situation, laid out. 💅

Not collective.

Returns:

  • A (Mat) — the A matrix. the foundation, the base layer. 🌈
  • U (Mat) — the first dense rectangular matrix.
  • c (Vec) — the sequential vector containing the diagonal of C. 🍓
  • V (Mat) — the second dense rectangular matrix.

Return type: tuple[Mat, Mat, Vec, Mat]

See also: MatLRCGetMats — https://petsc.org/release/manualpages/Mat/MatLRCGetMats.html

Source code at petsc4py/PETSc/Mat.pyx:5165 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L5165

⭐ getLocalSize()

Return the local number of rows and columns. local bestie, not the whole entire world, just your slice. 🍰

Not collective.

See also: getSize, MatGetLocalSize — https://petsc.org/release/manualpages/Mat/MatGetLocalSize.html

Source code at petsc4py/PETSc/Mat.pyx:2053 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2053

Return type: tuple[int, int]

🧚 getLocalSubMatrix(isrow, iscol, submat=None)

Return a reference to a submatrix specified in local numbering. a lil window into the bigger picture. 🔭

Collective. (everyone has to agree on this one, no cap)

Parameters:

  • isrow (IS) — row index set.
  • iscol (IS) — column index set.
  • submat (Mat | None) — optional resultant matrix. when it's None, a new matrix gets created. when it's not None, the matrix is first destroyed and then recreated. so heads up — passing one in means the old one is GONE, gone gone 💀

Return type: Mat

See also: restoreLocalSubMatrix, MatGetLocalSubMatrix — https://petsc.org/release/manualpages/Mat/MatGetLocalSubMatrix.html

Source code at petsc4py/PETSc/Mat.pyx:4271 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L4271

🌸 getMumpsCntl(icntl)

Return the MUMPS parameter, CNTL[icntl].

Logically collective.

See also: Working with PETSc options (see the petsc-options page), MatMumpsGetCntl — https://petsc.org/release/manualpages/Mat/MatMumpsGetCntl.html

Source code at petsc4py/PETSc/Mat.pyx:5542 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L5542

Parameters: icntl (int)

Return type: float ✨

💙 getMumpsIcntl(icntl)

Return the MUMPS parameter, ICNTL[icntl]. the integer sibling of the CNTL one, iykyk. 🔢

Logically collective.

See also: Working with PETSc options (see the petsc-options page), MatMumpsGetIcntl — https://petsc.org/release/manualpages/Mat/MatMumpsGetIcntl.html

Source code at petsc4py/PETSc/Mat.pyx:5506 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L5506

Parameters: icntl (int)

Return type: int

🌈 getMumpsInfo(icntl)

Return the MUMPS parameter, INFO[icntl].

Logically collective.

Parameters:

  • icntl (int) — the index of the MUMPS INFO array. 👑

Return type: int

See also: MatMumpsGetInfo — https://petsc.org/release/manualpages/Mat/MatMumpsGetInfo.html

Source code at petsc4py/PETSc/Mat.pyx:5557 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L5557

🦋 getMumpsInfog(icntl)

Return the MUMPS parameter, INFOG[icntl]. the global-flavoured INFO, periodt. 💅

Logically collective.

Parameters:

  • icntl (int) — the index of the MUMPS INFOG array.

Return type: int

See also: MatMumpsGetInfog — https://petsc.org/release/manualpages/Mat/MatMumpsGetInfog.html

Source code at petsc4py/PETSc/Mat.pyx:5577 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L5577

💜 getMumpsRinfo(icntl)

Return the MUMPS parameter, RINFO[icntl]. real numbers this time, we love variety. 🍓

Logically collective.

Parameters:

  • icntl (int) — the index of the MUMPS RINFO array.

getMumpsRinfog(icntl)

okay so this one gives you the MUMPS parameter, RINFOG[icntl]. 💖

Logically collective — so like, everyone on the communicator has to be in on this together, no cutting the line bestie.

Parameters

  • icntl (int) — The index of the MUMPS RINFOG array.

Return type

float

See also: MatMumpsGetRinfog

Source code at petsc4py/PETSc/Mat.pyx:5617

getNearNullSpace()

hands you the near-nullspace, bestie 🦋

Not collective — just you and your local self, no group chat needed.

See also: getNullSpace, setNearNullSpace, MatSetNearNullSpace

Source code at petsc4py/PETSc/Mat.pyx:3933

Return type

NullSpace

getNestISs()

gives you back the index sets that represent the row and column spaces. nesting era 💅

Not collective.

See also: MatNestGetISs

Source code at petsc4py/PETSc/Mat.pyx:6011

Return type

tuple[list[IS], list[IS]]

getNestLocalISs()

returns the local index sets for the row and column spaces. same vibe as above but make it local ✨

Not collective.

See also: MatNestGetLocalISs

Source code at petsc4py/PETSc/Mat.pyx:6032

Return type

tuple[list[IS], list[IS]]

getNestSize()

how many rows and columns does this matrix have? it tells you. the way that it just... knows 🎀

Not collective.

See also: MatNestGetSize

Source code at petsc4py/PETSc/Mat.pyx:5997

Return type

tuple[int, int]

getNestSubMatrix(i, j)

returns one single submatrix, like picking one specific thing out of the nesting situation 🫶

Not collective.

Parameters

  • i (int) — The first index of the matrix within the nesting.
  • j (int) — The second index of the matrix within the nesting.

Return type

Mat

See also: MatNestGetSubMat

Source code at petsc4py/PETSc/Mat.pyx:6053

getNullSpace()

returns the nullspace. that's it, that's the whole job 💖

Not collective.

See also: setNullSpace, MatGetNullSpace

Source code at petsc4py/PETSc/Mat.pyx:3879

Return type

NullSpace

getOption(option)

returns the option value. peek at the setting, bestie 👀

Not collective.

See also: setOption, MatGetOption

Source code at petsc4py/PETSc/Mat.pyx:2011

Parameters

  • option (Option)

Return type

bool

getOptionsPrefix()

returns the prefix that's used for searching for options in the database. it's giving "where's my options at" 🔍

Not collective.

See also: Working with PETSc options, setOptionsPrefix, MatGetOptionsPrefix

Source code at petsc4py/PETSc/Mat.pyx:1946

Return type

str

getOrdering(ord_type)

returns a reordering for a matrix so the LU factorization gets better. glow-up for your factorization, fr fr 🔥

Collective — whole squad involved, no exceptions.

Parameters

  • ord_type (OrderingType) — The type of reordering.

Returns

  • rp (IS) — The row permutation indices.
  • cp (IS) — The column permutation indices.

Return type

tuple[IS, IS]

See also: MatGetOrdering

Source code at petsc4py/PETSc/Mat.pyx:4803

getOwnershipIS()

returns the ranges of rows and columns that each process owns, but as index sets. who owns what, but make it IS 🏠

Not collective.

See also: getOwnershipRanges, getOwnershipRangesColumn, MatGetOwnershipIS

Source code at petsc4py/PETSc/Mat.pyx:2178

Return type

tuple[IS, IS]

getOwnershipRange()

returns the locally owned range of rows. what rows are yours, bestie 💅

Not collective.

See also: getOwnershipRanges, getOwnershipRangeColumn, MatGetOwnershipRange

Source code at petsc4py/PETSc/Mat.pyx:2111

Return type

tuple[int, int]

getOwnershipRangeColumn()

returns the locally owned range of columns. same energy as the row one, but it's columns this time 🌸

Not collective.

See also: getOwnershipRangesColumn, getOwnershipRange, MatGetOwnershipRangeColumn

Source code at petsc4py/PETSc/Mat.pyx:2145

getOwnershipRanges()

Gives you back the range of rows that each process is out here owning. 👑

Not collective — nobody's gossiping across processes for this one.

The returned array is literally just the result of an exclusive scan of the local sizes. Math but make it cute.

Returns: ArrayInt

See also: getOwnershipRange, MatGetOwnershipRanges — https://petsc.org/release/manualpages/Mat/MatGetOwnershipRanges.html

Source code at petsc4py/PETSc/Mat.pyx:2125 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2125

getOwnershipRangesColumn()

Same energy as above but for columns 💅 — the range of columns each process owns.

Not collective.

Returns: ArrayInt

See also: getOwnershipRangeColumn, MatGetOwnershipRangesColumn — https://petsc.org/release/manualpages/Mat/MatGetOwnershipRangesColumn.html

Source code at petsc4py/PETSc/Mat.pyx:2160 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2160

getPythonContext()

Returns the instance of the class that's implementing the required Python methods. That's the actual object doing the work behind the scenes, bestie. 🐍

Not collective.

Returns: Any

See also: PETSc Python matrix type, setPythonContext

Source code at petsc4py/PETSc/Mat.pyx:1880 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L1880

getPythonType()

Returns the fully qualified Python name of the class this matrix is using. Like, the whole government name, not the nickname. ✨

Not collective.

Returns: str

See also: PETSc Python matrix type, setPythonContext, setPythonType, MatPythonGetType — https://petsc.org/release/manualpages/Mat/MatPythonGetType.html

Source code at petsc4py/PETSc/Mat.pyx:1915 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L1915

getRedundantMatrix(nsubcomm, subcomm=None, out=None)

Returns redundant matrices living on the subcommunicators. Collective — everyone's in the group chat for this one. 💬

Parameters:

  • nsubcomm (int) — the number of subcommunicators.
  • subcomm (Comm or None) — the communicator split, or None for the null communicator.
  • out (Mat or None) — optional resultant matrix. When it's None, a brand-new matrix gets created and MAT_INITIAL_MATRIX is used. When it's not None, the matrix gets reused with MAT_REUSE_MATRIX. 🔁

Returns: Mat

See also: MatCreateRedundantMatrix — https://petsc.org/release/manualpages/Mat/MatCreateRedundantMatrix.html

Source code at petsc4py/PETSc/Mat.pyx:3730 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3730

getRow(row)

Hands you the column indices and the values for whichever row you asked about. Give it a row, get the tea back. 🍓

Not collective.

Parameters:

  • row (int)

Returns: tuple[ArrayInt, ArrayScalar]

See also: MatGetRow — https://petsc.org/release/manualpages/Mat/MatGetRow.html

Source code at petsc4py/PETSc/Mat.pyx:2693 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2693

getRowIJ(symmetric=False, compressed=False)

Returns the CSR representation of the local sparsity pattern. This is giving serious data-structure main character energy. 🧚

Collective.

Parameters:

  • symmetric (bool) — if True, return the symmetrized graph.
  • compressed (bool) — if True, return the compressed graph.

Returns: tuple[ArrayInt, ArrayInt]

See also: MatGetRowIJ — https://petsc.org/release/manualpages/Mat/MatGetRowIJ.html

Source code at petsc4py/PETSc/Mat.pyx:2713 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2713

getRowSum(result=None)

Returns the row-sum vector, i.e. every row summed up into one adorable little vector. ➕

Collective.

Parameters:

  • result (Vec or None) — optional vector to store the result in.

Returns: Vec

See also: MatGetRowSum — https://petsc.org/release/manualpages/Mat/MatGetRowSum.html

Source code at petsc4py/PETSc/Mat.pyx:3782 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3782

getSchurComplementSubMatrices()

Returns the Schur complement sub-matrices. Yeah we said complement, and we meant it. 💜

Collective.

Returns: tuple[Mat, Mat, Mat, Mat, Mat] — yes bestie, five of them.

See also: MatSchurComplementGetSubMatrices — https://petsc.org/release/manualpages/KSP/MatSchurComplementGetSubMatrices.html

Source code at petsc4py/PETSc/Mat.pyx:4250 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L4250

getSize()

Returns the global number of rows and columns. The whole picture, not just your lil slice. 🌈

Not collective.

Returns: tuple[int, int]

See also: getLocalSize, getSizes, MatGetSize — https://petsc.org/release/manualpages/Mat/MatGetSize.html

Source code at petsc4py/PETSc/Mat.pyx:2039 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2039

getSizes()

Returns the tuple of matrix layouts. Layouts!! Plural!! 💅

Not collective.

Returns: tuple[LayoutSizeSpec, LayoutSizeSpec]

See also: getLocalSize, getSize

Source code at petsc4py/PETSc/Mat.pyx:2067 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2067

getTransposeMat()

Returns the internal matrix of a Type.TRANSPOSE matrix. Peek behind the curtain, no cap. 🎭

Not collective.

Parameters:

  • mat — Matrix A of type Type.TRANSPOSE.

Returns: Mat

See also: MatTransposeGetMat — https://petsc.org/release/manualpages/Mat/MatTransposeGetMat.html

Source code at petsc4py/PETSc/Mat.pyx:1330 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L1330

getTransposeNullSpace()

Returns the transpose nullspace. 🦋

Not collective.

getType()

Okay bestie, this one hands you back the type of the matrix. That's it. That's the whole job. 💅

Not collective — so no group chat needed, she answers solo.

getValue(row, col)

Give her a (row, col) and she gives you the value sitting right there. ✨

Not collective, she's doing this on her own.

getValues(rows, cols, values=None)

Return the values at the zip(rows, cols) positions — like, pair them up and pull the value at each pair. 🫶

Not collective.

Parameters

getValuesCSR()

Return the CSR representation of the local part of the matrix. 🎀

Not collective, she's only giving you what's hers.

getVecType()

Return the vector type that this matrix uses. 🌸

Not collective.

hermitianTranspose(out=None)

Return the transposed Hermitian matrix. ✨

Collective — everybody's in on this one.

Parameters

imagPart(out=None)

Return the imaginary part of the matrix. 💜

Collective.

Parameters

increaseOverlap(iset, overlap=1)

Increase the overlap of an index set. 🦋

Collective, so everybody gotta sync up.

Parameters

invertBlockDiagonal()

Return the inverse of the block-diagonal entries. 🔥

Collective.

isAssembled()

The boolean flag telling you whether the matrix is assembled or not. 👑

Not collective.

isHermitian(tol=0)

Return the boolean saying whether the matrix is Hermitian. 💖

Collective.

Parameters

isHermitianKnown()

Return the 2-tuple telling you whether the matrix is known to be Hermitian. 🌈

Not collective.

isLinear(n=1)

Return whether the Mat is a linear operator. ⭐

Collective.

Parameters

isStructurallySymmetric()

Returns the boolean that tells you whether the matrix is structurally symmetric. 💖

Not collective — this one's just a local question, no group chat needed.

Return type: bool

See also: MatIsStructurallySymmetric

Source code at petsc4py/PETSc/Mat.pyx:2573

isSymmetric(tol=0)

Returns the boolean that tells you whether the matrix is symmetric. ✨

Collective — everybody's in on this one, bestie.

Parameters

  • tol (float) — tolerance for the comparison.

Return type: bool

See also: MatIsSymmetric

Source code at petsc4py/PETSc/Mat.pyx:2503

isSymmetricKnown()

Returns the 2-tuple that tells you whether the matrix is known to be symmetric. 👑

Not collective.

Return type: tuple[bool, bool]

See also: MatIsSymmetricKnown

Source code at petsc4py/PETSc/Mat.pyx:2523

isTranspose(mat=None, tol=0)

Returns the result of comparing matrices, but with a transposition in the mix. 🔥

Collective.

Parameters

  • mat (Mat | None) — the matrix to compare against. Uses self when it's None.
  • tol (float) — tolerance for the comparison.

Return type: bool

See also: MatIsTranspose

Source code at petsc4py/PETSc/Mat.pyx:2480

kron(mat, result=None)

Computes C, the Kronecker product of A and B. It's giving tensor energy fr fr. 💅

Collective.

Parameters

  • mat (Mat) — the right hand matrix B.
  • result (Mat | None) — the optional resultant matrix. When it's None, a brand new matrix gets created and MAT_INITIAL_MATRIX is used. When it's not None, the matrix is reused with MAT_REUSE_MATRIX. ✨

Returns: result — the resultant matrix C, aka the Kronecker product of A and B.

Return type: Mat

See also: MatSeqAIJKron, MatReuse

Source code at petsc4py/PETSc/Mat.pyx:4732

load(viewer)

Loads a matrix. That's it, that's the vibe. 📥

Collective.

Parameters

  • viewer (Viewer)

Return type: Self

See also: MatLoad

Source code at petsc4py/PETSc/Mat.pyx:2260

matMatMult(B, C, result=None, fill=None)

Performs the matrix-matrix-matrix multiplication D=ABC. Three matrices walk in, one walks out. 😭💖

Neighborwise collective — so it's collective, but only with your neighbors, iykyk.

Parameters

  • B (Mat) — the middle matrix B.
  • C (Mat) — the right hand matrix C.
  • result (Mat | None) — the optional resultant matrix D. When it's None, a new matrix is created and MAT_INITIAL_MATRIX is used. When D is not None, the matrix is reused with MAT_REUSE_MATRIX.
  • fill (float | None) — expected fill as the ratio of nnz(C)/nnz(A). Use None if you do not have a good estimate. If the result is a dense matrix this is irrelevant.

Returns: result — the resultant product matrix D.

Return type: Mat

See also: MatMatMatMult, MatReuse

Source code at petsc4py/PETSc/Mat.pyx:4687

matMult(mat, result=None, fill=None)

Performs the matrix-matrix multiplication C=AB. The classic. The blueprint. The moment. ✨

Neighborwise collective.

Parameters

  • mat (Mat) — the right hand matrix B.
  • result (Mat | None) — the optional resultant matrix C. When it's None, a new matrix is created and MAT_INITIAL_MATRIX is used. When C is not None, the matrix is reused with MAT_REUSE_MATRIX.
  • fill (float | None) — expected fill as the ratio of nnz(C)/(nnz(A) + nnz(B)). Use None if you do not have a good estimate. If the result is a dense matrix this is irrelevant.

Returns: result — the resultant product matrix C.

Return type: Mat

Notes

To determine the correct fill value, run with -info and search for the string "Fill ratio" to see the value actually needed. 🕵️‍♀️ no cap, that's literally how you find it.

See also: MatMatMult, MatReuse

Source code at petsc4py/PETSc/Mat.pyx:4448

matSolve(B, X)

Solves AX=B, given a factored matrix A. 🧮

Neighborwise collective.

Parameters

  • B (Mat) — the right-hand side matrix of type Type.DENSE. Can be of type Type.AIJ if using MUMPS.
  • X (Mat) — the output solution matrix, and it must be different than B. Like, genuinely different, bestie, don't try to be cute. 💀

Return type: None

See also: KSP.create, MatMatSolve

matTransposeMult(mat, result=None, fill=None)

Perform matrix-matrix multiplication C=ABᵀ. 💅

Neighborwise collective. (Yes bestie, that's the actual term, write it down.)

Parameters

  • mat (Mat) — The right hand matrix B. 🫶
  • result (Mat | None) — The optional resultant matrix C. When it's None, a new matrix gets created and MAT_INITIAL_MATRIX is used. When C is not None, the matrix is reused with MAT_REUSE_MATRIX. No cap.
  • fill (float | None) — Expected fill as ratio of nnz(C)/(nnz(A) + nnz(B)). Use None if you do not have a good estimate, fr fr. If the result is a dense matrix this is irrelevant (so don't stress, bestie 🌸).

Returns

result — The resultant product matrix C. ✨

Return type

Mat

Notes

To determine the correct fill value, run with -info and search for the string "Fill ratio" to see the value actually needed. 👑

See also:

MatMatTransposeMult, MatReuse

Source code at petsc4py/PETSc/Mat.pyx:4495

mult(x, y)

Perform the matrix vector product y = A @ x.

Collective. Like, everybody's in on this one.

Parameters

  • x (Vec) — The input vector.
  • y (Vec) — The output vector.

Return type

None

See also:

MatMult

Source code at petsc4py/PETSc/Mat.pyx:3950

multAdd(x, v, y)

Perform the matrix vector product with addition y = A @ x + v. ➕✨

Collective.

Parameters

  • x (Vec) — The input vector for the matrix-vector product.
  • v (Vec) — The input vector to be added to.
  • y (Vec) — The output vector.

Return type

None

See also:

MatMultAdd

Source code at petsc4py/PETSc/Mat.pyx:3969

multHermitian(x, y)

Perform the Hermitian matrix vector product y = A^H @ x. 💜

Collective.

Parameters

  • x (Vec) — The input vector for the Hermitian matrix-vector product.
  • y (Vec) — The output vector.

Return type

None

See also:

MatMultHermitianTranspose

Source code at petsc4py/PETSc/Mat.pyx:4030

multHermitianAdd(x, v, y)

Perform the Hermitian matrix vector product with addition y = A^H @ x + v. 🦋

Collective.

Parameters

  • x (Vec) — The input vector for the Hermitian matrix-vector product.
  • v (Vec) — The input vector to be added to.
  • y (Vec) — The output vector.

Return type

None

See also:

MatMultHermitianTransposeAdd

Source code at petsc4py/PETSc/Mat.pyx:4049

multTranspose(x, y)

Perform the transposed matrix vector product y = A^T @ x. 🔄

Collective.

Parameters

  • x (Vec) — The input vector.
  • y (Vec) — The output vector.

Return type

None

See also:

MatMultTranspose

Source code at petsc4py/PETSc/Mat.pyx:3990

multTransposeAdd(x, v, y)

Perform the transposed matrix vector product with addition y = A^T @ x + v. 🎀

Collective.

Parameters

  • x (Vec) — The input vector for the transposed matrix-vector product.
  • v (Vec) — The input vector to be added to.
  • y (Vec) — The output vector.

Return type

None

See also:

MatMultTransposeAdd

Source code at petsc4py/PETSc/Mat.pyx:4009

norm(norm_type=None)

Compute the requested matrix norm. 📏✨

Collective.

A 2-tuple is returned if NormType.NORM_1_AND_2 is specified. (Two numbers, one vibe. 😌)

See also:

MatNorm, NormType

Source code at petsc4py/PETSc/Mat.pyx:4320

Parameters

  • norm_type (NormTypeSpec)

Return type

float | tuple[float, float]

permute(row, col)

Return the permuted matrix. 🔀

Collective.

Parameters

  • row (IS) — Row permutation.
  • col (IS) — Column permutation.

Return type

Mat

See also:

MatPermute

Source code at petsc4py/PETSc/Mat.pyx:2445

preallocatorPreallocate(A, fill=True)

Preallocate memory for a matrix using a preallocator matrix. 🧚

Collective.

The current matrix (self) must be of type Type.PREALLOCATOR. No exceptions bestie, that's the rule.

Heads up: if self isn't Type.PREALLOCATOR, this is not the move. 💀

Parameters

  • A (Mat) — The matrix to be preallocated.
  • fill (bool) — Flag indicating whether or not to insert zeros into the newly allocated matrix, defaults to True.

🫶 ptap(P, result=None, fill=None)

okay so this one literally builds you the matrix product C = PᵀAP. iconic behavior ✨

Neighborwise collective. (yes bestie, everybody's involved, no skipping)

Parameters

  • P (Mat) — the matrix P. that's it, that's the girl 💅
  • result (Mat | None) — the optional resultant matrix C. when it's None, a brand-new matrix gets created and MAT_INITIAL_MATRIX is used. when C is not None, the matrix is reused with MAT_REUSE_MATRIX. choose your fighter 🎀
  • fill (float | None) — expected fill as ratio of nnz(C)/(nnz(A) + nnz(P)). use None if you don't have a good estimate, no shame. if the result is a dense matrix this is irrelevant 🌸

Returns

  • result — the resultant product matrix C.

Return type: Mat

Notes

to figure out the correct fill value, run with -info and search for the string "Fill ratio" to see the value actually needed. iykyk 🔍

an alternative approach to this function is to use MatProductCreate and set the desired options before the computation is done. main character energy, different entrance ✨

See also: MatPtAP (https://petsc.org/release/manualpages/Mat/MatPtAP.html), MatReuse (https://petsc.org/release/manualpages/Mat/MatReuse.html)

Source code at petsc4py/PETSc/Mat.pyx:4589 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L4589)

🌈 rart(R, result=None, fill=None)

create the matrix product C = RARᵀ. yes it's ptap's cousin, they're both serving 💖

Neighborwise collective.

Parameters

  • R (Mat) — the projection matrix. lowkey doing the most but that's the job 🦋
  • result (Mat | None) — the optional resultant matrix C. when None, a new matrix is created and MAT_INITIAL_MATRIX is used. when C is not None, the matrix is reused with MAT_REUSE_MATRIX.
  • fill (float | None) — expected fill as ratio of nnz(C)/nnz(A). pass None if you don't have a good estimate. if the result is a dense matrix this is irrelevant, periodt 🎀

Returns

  • result — the resultant product matrix C.

Return type: Mat

Notes

to nail the correct fill value, run with -info and search for the string "Fill ratio" to see the value actually needed. the manpage said what it said 💀

See also: MatRARt (https://petsc.org/release/manualpages/Mat/MatRARt.html), MatReuse (https://petsc.org/release/manualpages/Mat/MatReuse.html)

Source code at petsc4py/PETSc/Mat.pyx:4640 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L4640)

✨ realPart(out=None)

return the real part of the matrix. the imaginary part? not invited to this function, sorry bestie 🙈

Collective.

Parameters

  • out (Mat | None) — optional return matrix. if it's None, the operation is performed in-place. otherwise, the operation is performed on out. your choice, both are valid 👑

Return type: Mat

See also: imagPart, conjugate, MatRealPart (https://petsc.org/release/manualpages/Mat/MatRealPart.html)

Source code at petsc4py/PETSc/Mat.pyx:2376 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2376)

💜 reorderForNonzeroDiagonal(isrow, iscol, atol=0)

change a matrix ordering so those pesky zeros get off the diagonal. it's giving glow-up but for sparsity 🌟

Collective.

Parameters

  • isrow (IS) — the row reordering.
  • iscol (IS) — the column reordering.
  • atol (float) — the absolute tolerance. values along the diagonal whose absolute value are smaller than this tolerance are moved off the diagonal. tiny values? evicted 💅

Return type: None

See also: getOrdering, MatReorderForNonzeroDiagonal (https://petsc.org/release/manualpages/Mat/MatReorderForNonzeroDiagonal.html)

Source code at petsc4py/PETSc/Mat.pyx:4831 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L4831)

🎀 resetLMVM(destructive=False)

flushes all of the accumulated updates out of the LMVM matrix. out with the old, literally 🧹✨

Logically collective.

Parameters

  • destructive (bool) — flag for enabling destruction of data structures. dramatic much? but honestly valid 💀

Return type: None

See also: MatLMVMReset (https://petsc.org/release/manualpages/KSP/MatLMVMReset.html)

Source code at petsc4py/PETSc/Mat.pyx:5466 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L5466)

🦋 restoreDenseColumnVec(i, mode='rw', V=None)

restore the iᵗʰ column vector of the dense matrix. you borrowed it, now give it back, be polite 💖

Collective.

Parameters

  • i (int) — the column index to be restored.
  • mode (AccessModeSpec) — the access type of the vector to be restored. defaults to 'rw'.
  • V (Vec | None) — the vector obtained from calling getDenseColumnVec. yes, the exact one. no substitutions 🙅‍♀️

Return type: None

See also: getDenseColumnVec, MatDenseRestoreColumnVec (https://petsc.org/release/manualpages/Mat/MatDenseRestoreColumnVec.html), MatDenseRestoreColumnVecRead (https://petsc.org/release/manualpages/Mat/MatDenseRestoreColumnVecRead.html), MatDenseRestoreColumnVecWrite (https://petsc.org/release/manualpages/Mat/MatDenseRestoreColumnVecWrite.html)

Source code at petsc4py/PETSc/Mat.pyx:5962 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L5962)

🌸 restoreDenseSubMatrix(mat)

restore access to a submatrix of a Type.DENSE matrix. we love a tidy handback 🫶

Collective.

Parameters

  • mat (Mat) — the matrix obtained from getDenseSubMatrix. the one you borrowed, bestie, remember?

Return type: None

See also: getDenseSubMatrix, MatDenseRestoreSubMatrix (https://petsc.org/release/manualpages/Mat/MatDenseRestoreSubMatrix.html)

Source code at petsc4py/PETSc/Mat.pyx:5911 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L5911)

💅 restoreISLocalMat(local)

restore the local matrix you got with getISLocalMat. returning borrowed things is the bare minimum and we stan 🌟

Not collective. (just you, solo, do your thing)

local (Mat) — the local matrix, bestie. That's the one that goes in. 🫶

Return type: None 💅

See also: MatISRestoreLocalMat (the PETSc manual page lives at petsc.org/release/manualpages/Mat/MatISRestoreLocalMat.html)

Source code at petsc4py/PETSc/Mat.pyx:5098 — full link gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L5098 🧚

💫 restoreLocalSubMatrix(isrow, iscol, submat)

Give back a reference to a submatrix you got earlier with getLocalSubMatrix. no cap, you gotta hand it back or it just sits there. 🙈

Collective. Everyone in the communicator has to show up. 🎀

Parameters

  • isrow (IS) — row index set. 👑
  • iscol (IS) — column index set. 👑
  • submat (Mat) — the submatrix.

Return type: None ✨

See also: getLocalSubMatrix, MatRestoreLocalSubMatrix (petsc.org/release/manualpages/Mat/MatRestoreLocalSubMatrix.html)

Source code at petsc4py/PETSc/Mat.pyx:4297 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L4297 🌸

🌈 retrieveValues()

Get yourself a copy of the matrix values you stashed earlier with storeValues. it's giving "grab it back out of the metaphorical pocket". 💖

Collective.

See also: storeValues, MatRetrieveValues (petsc.org/release/manualpages/Mat/MatRetrieveValues.html)

Source code at petsc4py/PETSc/Mat.pyx:3537 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3537 🦋

Return type: None ⭐

✨ scale(alpha)

Scale the matrix. that's it, that's the whole job. multiply-and-slay. 💅

Collective.

See also: MatScale (petsc.org/release/manualpages/Mat/MatScale.html)

Source code at petsc4py/PETSc/Mat.pyx:4342 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L4342 🔥

Parameters

  • alpha (Scalar) — the thing you're scaling by.

Return type: None 🌸

🎀 setBlockSize(bsize)

Set the matrix block size — and bestie, that's the same block size for rows and columns. equal treatment, iconic. 👑

Logically collective.

Parameters

  • bsize (int) — block size.

Return type: None 💜

See also: setBlockSizes, setSizes, MatSetBlockSize (petsc.org/release/manualpages/Mat/MatSetBlockSize.html)

Source code at petsc4py/PETSc/Mat.pyx:614 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L614 🧚

🦋 setBlockSizes(row_bsize, col_bsize)

Set the row block size and the column block size. two separate numbers, two separate vibes. no forcing them to match. ✌️

Logically collective.

Parameters

  • row_bsize (int) — row block size.
  • col_bsize (int) — column block size.

Return type: None 💖

See also: setBlockSize, setSizes, MatSetBlockSizes (petsc.org/release/manualpages/Mat/MatSetBlockSizes.html)

Source code at petsc4py/PETSc/Mat.pyx:632 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L632 ⭐

💫 setDM(dm)

Set the DM that defines the data layout of the matrix. it's the blueprint, she's the builder. 🏗️

Not collective. (yes bestie, this one's a solo act 💅)

Parameters

  • dm (DM) — the DM.

Return type: None 🌈

See also: MatSetDM (petsc.org/release/manualpages/DM/MatSetDM.html)

Source code at petsc4py/PETSc/Mat.pyx:6096 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6096 🍓

🌸 setDenseLDA(lda)

Set the leading dimension of the array that the dense matrix is using. yeah, the LDA, the layout one, you know the one. iykyk. 🙈

Not collective.

Parameters

  • lda (int) — the leading dimension.

Return type: None ✨

See also: MatDenseSetLDA (petsc.org/release/manualpages/Mat/MatDenseSetLDA.html)

Source code at petsc4py/PETSc/Mat.pyx:5789 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L5789 💜

👑 setDiagonal(diag, addv=None)

Set the diagonal values of the matrix. the main character diagonal, the one everyone looks at. 😭

Collective.

Parameters

  • diag (Vec) — vector storing diagonal values.
  • addv (InsertModeSpec) — insertion mode.

Return type: None 💅

See also: getDiagonal, MatDiagonalSet (petsc.org/release/manualpages/Mat/MatDiagonalSet.html)

Source code at petsc4py/PETSc/Mat.pyx:3804 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3804 🔥

⭐ setFromOptions()

Configure the matrix straight from the options database. yes girl, let the CLI do the talking. 🗣️

Collective.

See also: Working with PETSc options (#petsc-options), MatSetFromOptions (petsc.org/release/manualpages/Mat/MatSetFromOptions.html)

Source code at petsc4py/PETSc/Mat.pyx:1974 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L1974 🌸

Return type: None 🦋

🧚 setISAllowRepeated(allow=True)

Allow repeated entries in the local-to-global map. default is True, so she's permissive out of the box. 🫶

Logically collective.

Parameters

  • allow (bool) — when True, local dofs are allowed to map to the same global dof.

Return type: None 💖

See also: getISAllowRepeated, MatISSetAllowRepeated (petsc.org/release/manualpages/Mat/MatISSetAllowRepeated.html)

Source code at petsc4py/PETSc/Mat.pyx:5032 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L5032 🌈

🌟 setISLocalMat(local)

Set the local matrix that's stored inside a Type.IS (petsc4py.PETSc.Mat.Type.IS). nesting, but make it slay. 💅

Not collective.

Parameters

  • local (Mat) — the local matrix.

Return type: None ✨

See also: MatISSetLocalMat (petsc.org/release/manualpages/Mat/MatISSetLocalMat.html)

Source code at petsc4py/PETSc/Mat.pyx:5115 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L5115 🎀

🦋 setISPreallocation(nnz, onnz)

Preallocate memory for a Type.IS (petsc4py.PETSc.Mat.Type.IS) parallel matrix. do it before you fill her up, bestie, she does not enjoy growing on the fly. 😭

Collective.

Parameters

  • nnz (Sequence[int]) — the sequence whose length corresponds to the number of local rows, and whose values represent the number of nonzeros in the various rows of the diagonal of the local submatrix.
  • onnz (Sequence[int]) — the sequence whose length corresponds to the number of local rows, and whose values represent the number of nonzeros in the various rows of the off-diagonal of the local submatrix.

Return type: Self

setLGMap(rmap, cmap=None) 💅

Ok so this one sets the local-to-global mappings. Collective. (yes bestie, everybody's gotta be in the group chat for this one 🫶)

Parameters:

  • rmap (LGMap) — the row mapping. that's the one that matters most, obvi.
  • cmap (LGMap | None) — the column mapping. and if it's None, then cmap = rmap. one mapping, two jobs, she's versatile ✨

Return type: None

setLMVMJ0(J0) 🔥

Sets the initial Jacobian of the LMVM matrix. Logically collective.

Parameters:

  • J0 (Mat) — the initial Jacobian matrix. the ✨before✨ picture, if you will.

Return type: None

setLMVMJ0KSP(ksp) 🎀

Sets the KSP of the LMVM matrix. Logically collective.

Parameters:

  • ksp (KSP) — the KSP. yeah bestie, just hand her the whole KSP, she knows what to do with it.

Return type: None

setLRCMats(A, U, c=None, V=None) 🌸

Sets the constituents of a Type.LRC matrix. like, all the lil pieces that add up to the whole vibe. Logically collective.

Parameters:

  • A (Mat) — the A matrix, or None to omit A. yeah she's optional, we love a flexible queen.
  • U (Mat) — the first dense rectangular matrix.
  • c (Vec) — the sequential vector containing the diagonal of C, or None for all ones. default behavior is just... ones. slay.
  • V (Mat) — the second dense rectangular matrix, or None for a copy of U. if you don't bring a V, she'll just clone the U for you 💖

Return type: None

setMumpsCntl(icntl, val) 🧚

Sets a MUMPS parameter, and the way this works is literally CNTL[icntl] = val. that's it, that's the whole thing. Logically collective.

Parameters:

  • icntl (int) — the index of the MUMPS parameter array. so like, which slot.
  • val (float) — the value to set. and here's the value, it's a float bestie, don't come at her with an int and expect zero drama.

Return type: None

setMumpsIcntl(icntl, ival) 🧚

Sets a MUMPS parameter — and this time it's ICNTL[icntl] = ival. notice the I? that's the whole plot twist: integer edition. Logically collective.

Parameters:

  • icntl (int) — the index of the MUMPS parameter array.
  • ival (int) — the value to set. yes it's an int this time. read the method name, bestie, it's right there 😭

Return type: None

setNearNullSpace(nsp) 🦋

Sets the near-nullspace. Collective. not the nullspace — the near one. close enough counts in horseshoes and in multigrid, iykyk 👑

Parameters:

  • nsp (NullSpace)

Return type: None

setNestVecType(vec_type) 🌈

Sets the vector type for a Type.NEST matrix. Collective. nested matrix? she wants to know what kinda vectors she's gonna be spawning.

Parameters:

  • vec_type (Type | str) — the vector type used when creating vectors with createVecs. so it's future-you's problem, but current-you decides it.

Return type: None

setNullSpace(nsp) 💜

Sets the nullspace. the real one, not the near one. Collective.

Parameters:

  • nsp (NullSpace)

Return type: None

setOption(option, flag) ⭐

Sets an option. short king of a method name, huge energy. Collective.

Parameters:

  • option (Option)
  • flag (bool)

Return type: None

setOptionsPrefix(prefix=None) 🎀

Sets the prefix used for searching for options in the database. Logically collective. she's basically giving your matrix a name tag so PETSc can find her stuff in the options database.

Parameters:

  • prefix (str | None)

Return type: None

setPreallocationCOO(coo_i, coo_j) 🍓

Sets preallocation using coordinate format with global indices. Collective. so instead of you guessing how much space she needs, you just hand her the coordinates and she does the math. main character energy, honestly.

Parameters:

  • coo_i
  • coo_j

and bestie the page cuts off RIGHT there mid-parameter-list 😭 like the printer ran out of ink in 1997. no cap, we're picking this one back up in the next chunk 💖

  • coo_i (Sequence[int]) — the row indices, COO style 💫
  • coo_j (Sequence[int]) — the column indices, COO style 💫

Return type Self

See also: setValuesCOO, setPreallocationNNZ, setPreallocationCSR, MatSetPreallocationCOO

Source code at petsc4py/PETSc/Mat.pyx:927

setPreallocationCOOLocal(coo_i, coo_j) 🎀

Set preallocation using coordinate format with local indices.

Collective.

Parameters

  • coo_i (Sequence[int]) — the row indices, COO style.
  • coo_j (Sequence[int]) — the column indices, COO style.

Return type Self

See also: setPreallocationCOO, setValuesCOO, setLGMap, MatSetPreallocationCOOLocal, MatSetPreallocationCOOLocal

Source code at petsc4py/PETSc/Mat.pyx:959

setPreallocationCSR(csr) ✨

Preallocate memory for the matrix with a CSR layout, bestie.

Collective.

Okay so real talk: doing your preallocation correctly can cause a dramatic reduction in matrix assembly time. It's giving glow-up for your runtime. 👑

Parameters

  • csr (CSRSpec | CSRIndicesSpec) — local matrix data, in compressed sparse row layout format.

Return type Self

Notes

You must use the block-compressed form when your type is Type.BAIJ or Type.SBAIJ. No exceptions, fr fr. 🙈

See also: setPreallocationNNZ, createAIJ, createBAIJ, createSBAIJ, MatSeqAIJSetPreallocationCSR, MatMPIAIJSetPreallocationCSR, MatSeqBAIJSetPreallocationCSR, MatMPIBAIJSetPreallocationCSR, MatSeqSBAIJSetPreallocationCSR, MatMPISBAIJSetPreallocationCSR

Source code at petsc4py/PETSc/Mat.pyx:991

setPreallocationDense(array) 💖

Hand over the array that will store the elements of a dense matrix. Iconic behaviour, honestly.

Collective.

Parameters

  • array (Sequence[Scalar]) — the array that will be used to store matrix data.

Return type Self

See also: MatSeqDenseSetPreallocation, MatMPIDenseSetPreallocation

Source code at petsc4py/PETSc/Mat.pyx:1232

setPreallocationNNZ(nnz) 🦋

Preallocate memory for the matrix using a non-zero pattern.

Collective.

And again because it matters: correct preallocation = dramatic reduction in matrix assembly time. The way that slaps. 🔥

Parameters

  • nnz (NNZSpec) — the number of non-zeros per row for the local portion of the matrix, or a 2-tuple covering the on-process and the off-process part of the matrix.

Return type Self

See also: setPreallocationCSR, createAIJ, MatSeqAIJSetPreallocation, MatMPIAIJSetPreallocation

Source code at petsc4py/PETSc/Mat.pyx:901

setPythonContext(context) 🌸

Set the instance of the class that implements the Python methods you need. Main character energy, fr.

Logically collective.

Notes

To actually use the matrix, you have to call Mat.setUp after you've set the context. And if you want to reset the matrix back to its initial state, pass None. Just None. Clean slate, no cap. 🫶

See also: PETSc Python matrix type, getPythonContext, setPythonType

Source code at petsc4py/PETSc/Mat.pyx:1863

Parameters

  • context (Any)

Return type None

setPythonType(py_type) 💜

Set the fully qualified Python name of the class you want to use. Fully qualified — like government name, not nickname. 📛

Collective.

Notes

To use the matrix, Mat.setUp must be called after you've set the type. Order matters, bestie. 💅

See also: PETSc Python matrix type, setPythonContext, getPythonType, MatPythonSetType

Source code at petsc4py/PETSc/Mat.pyx:1895

Parameters

  • py_type (str)

Return type None

setRandom(random=None) 🎲✨

Fill the matrix with random values. Chaos, but make it mathematical.

Collective.

Parameters

  • random (Random | None) — the random number generator object, or None if you want the default one.

Return type None

See also: MatSetRandom

Source code at petsc4py/PETSc/Mat.pyx:4381

setSizes(size, bsize=None) 🧚

Set the local, global and block sizes. All three. Overachiever behaviour.

Collective.

Parameters

  • size (MatSizeSpec) — matrix size.
  • bsize (MatBlockSizeSpec | None) — matrix block size. If you pass None, a block size of 1 gets set.

Return type None

Examples

Give a Mat n rows and n columns where local sizes match global sizes:

>>> mat = PETSc.Mat().create()
>>> mat.setFromOptions()
>>> mat.setSizes(n)

Or hand it nr rows and nc columns, again with local == global:

>>> mat = PETSc.Mat().create()
>>> mat.setFromOptions()
>>> mat.setSizes([nr, nc])

Or go full control-freak mode: nrl local rows, nrg global rows, ncl local columns, ncg global columns:

>>> mat = PETSc.Mat().create()
>>> mat.setFromOptions()
>>> mat.setSizes([[nrl, nrg], [ncl, ncg]])

See also 💜 setBlockSize, setBlockSizes, MatSetSizes (https://petsc.org/release/manualpages/Mat/MatSetSizes.html), MatSetBlockSize (https://petsc.org/release/manualpages/Mat/MatSetBlockSize.html), MatSetBlockSizes (https://petsc.org/release/manualpages/Mat/MatSetBlockSizes.html)

📍 Source code at petsc4py/PETSc/Mat.pyx:561 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L561

✨ setStencil(dims, starts=None, dof=1)

Set the matrix stencil. So iconic. 🎀

Not collective — every process does its own thing, no gossiping required, bestie.

See also 💜 MatSetStencil (https://petsc.org/release/manualpages/Mat/MatSetStencil.html)

📍 Source code at petsc4py/PETSc/Mat.pyx:3269 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3269

Parameters

  • dims (DimsSpec)
  • starts (DimsSpec | None)
  • dof (int)

Return type: None

🦋 setTransposeNullSpace(nsp)

Set the transpose nullspace. 💫

Collective — the whole crew has to be in on this one, no cap.

See also 💜 setNullSpace, getTransposeNullSpace, MatSetTransposeNullSpace (https://petsc.org/release/manualpages/Mat/MatSetTransposeNullSpace.html)

📍 Source code at petsc4py/PETSc/Mat.pyx:3894 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3894

Parameters

  • nsp (NullSpace)

Return type: None

🌸 setTransposePrecursor(out)

Set transpose precursor. lowkey setting up the vibe for a transpose later. ✨

Logically collective — everyone's gotta agree it's collective, even if the code doesn't strictly enforce it.

See also 💜 MatTransposeSetPrecursor (https://petsc.org/release/manualpages/Mat/MatTransposeSetPrecursor.html)

📍 Source code at petsc4py/PETSc/Mat.pyx:2337 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2337

Parameters

  • out (Mat)

Return type: None

👑 setType(mat_type)

Set the matrix type. This is the "what IS this matrix, actually" moment, bestie. 🔥

Collective.

Parameters

  • mat_type (Type | str) — The matrix type.

Return type: None

See also 💜 create, getType, MatSetType (https://petsc.org/release/manualpages/Mat/MatSetType.html)

📍 Source code at petsc4py/PETSc/Mat.pyx:542 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L542

💀 setUnfactored()

Set a factored matrix to be treated as unfactored. Like un-factoring your factorization, bestie, we love a decommitment era. 🦋

Logically collective.

See also 💜 MatSetUnfactored (https://petsc.org/release/manualpages/Mat/MatSetUnfactored.html)

📍 Source code at petsc4py/PETSc/Mat.pyx:5018 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L5018

Return type: None

🎀 setUp()

Set up the internal data structures for using the matrix. Basically the getting-ready montage scene before the matrix hits the runway. 💅

Collective.

See also 💜 MatSetUp (https://petsc.org/release/manualpages/Mat/MatSetUp.html)

📍 Source code at petsc4py/PETSc/Mat.pyx:1986 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L1986

Return type: Self

🌈 setValue(row, col, value, addv=None)

Set a value to the (row, col) entry of the matrix. Tiny lil single-entry slay. ✨

Not collective.

Parameters

  • row (int) — Row index.
  • col (int) — Column index.
  • value (Scalar) — The scalar value.
  • addv (InsertModeSpec) — Insertion mode.

Return type: None

See also 💜 MatSetValues (https://petsc.org/release/manualpages/Mat/MatSetValues.html)

📍 Source code at petsc4py/PETSc/Mat.pyx:2774 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2774

🙈 setValueBlockedStagStencil(row, col, value, addv=None)

Not implemented. Yeah bestie, this one's just sitting there looking pretty. 💀

📍 Source code at petsc4py/PETSc/Mat.pyx:3353 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3353

Return type: None

🧚 setValueBlockedStencil(row, col, value, addv=None)

Set a block of values to row and col stencil. The whole crew gets inserted at once, periodt. 💖

Not collective.

Parameters

  • row (Stencil) — Row stencil.
  • col (Stencil) — Column stencil.
  • value (Sequence[Scalar]) — The scalar values.
  • addv (InsertModeSpec) — Insertion mode.

Return type: None

See also 💜 MatSetValuesBlockedStencil (https://petsc.org/release/manualpages/Mat/MatSetValuesBlockedStencil.html)

📍 Source code at petsc4py/PETSc/Mat.pyx:3323 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3323

🌟 setValueLocal(row, col, value, addv=None)

Set a value to the (row, col) entry of the matrix — but in local ordering this time, so like, use your process's own little coordinate system. 🍓

Not collective.

Parameters

  • row (int) — Local row index.
  • col (int) — Local column index.
  • value (Scalar) — The scalar value.
  • addv (InsertModeSpec) — Insertion mode.

Return type: None

See also 💜 MatSetValuesLocal (https://petsc.org/release/manualpages/Mat/MatSetValuesLocal.html)

📍 Source code at petsc4py/PETSc/Mat.pyx:3048 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3048

😭 setValueStagStencil(row, col, value, addv=None)

Not implemented. Another decorative stub, bestie — it's giving "placeholder", not giving "functionality". 💀

📍 Source code at petsc4py/PETSc/Mat.pyx:3319 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3319

Return type: None

💜 setValueStencil(row, col, value, addv=None)

Set a value to row and col stencil. Stencil-coded value insertion, iykyk. ⭐

Not collective.

Parameters

  • row (Stencil) — Row stencil.
  • col (Stencil) — Column stencil.
  • value (Sequence[Scalar]) — The scalar values.
  • addv (InsertModeSpec) — Insertion mode.

Return type: None 💖

See also: MatSetValuesStencil — the PETSc manual page lives at petsc.org/release/manualpages/Mat/MatSetValuesStencil.html

Source code at petsc4py/PETSc/Mat.pyx:3289 — like, the actual file is gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3289 if you wanna go stare at it 👀

setValues(rows, cols, values, addv=None)

Okay bestie, this one sets values to the rows ⊗ cols entries of the matrix. That's the whole vibe. ✨

Not collective. 🫶

Parameters

  • rows (Sequence[int]) — Row indices. Just the rows, babe.
  • cols (Sequence[int]) — Column indices. And the columns.
  • values (Sequence[Scalar]) — The scalar values. A sequence of length at least len(rows) * len(cols). Yes, she does math. 😌
  • addv (InsertModeSpec) — Insertion mode. That's petsc4py.typing.InsertModeSpec for the record.

Return type: None

See also: MatSetValues — petsc.org/release/manualpages/Mat/MatSetValues.html

Source code at petsc4py/PETSc/Mat.pyx:2806 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2806

setValuesBlocked(rows, cols, values, addv=None)

Same energy as setValues but for block entries, okay? She sets values to the rows ⊗ col block entries of the matrix. Blocked, iconic, periodt. 💅

Not collective.

Parameters

  • rows (Sequence[int]) — Block row indices.
  • cols (Sequence[int]) — Block column indices.
  • values (Sequence[Scalar]) — The scalar values. A sequence of length at least len(rows) * len(cols) * bs * bs, where bs is the block size of the matrix. Yeah she multiplied by bs twice, it's giving squared block energy 🔥
  • addv (InsertModeSpec) — Insertion mode.

Return type: None

See also: MatSetValuesBlocked — petsc.org/release/manualpages/Mat/MatSetValuesBlocked.html

Source code at petsc4py/PETSc/Mat.pyx:2918 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2918

setValuesBlockedCSR(I, J, V, addv=None)

Sets values stored in block CSR format. CSR girlies rise up 🌸

Not collective.

Parameters

  • I (Sequence[int]) — Block row pointers.
  • J (Sequence[int]) — Block column indices.
  • V (Sequence[Scalar]) — The scalar values.
  • addv (InsertModeSpec) — Insertion mode.

Return type: None

See also: MatSetValuesBlocked — petsc.org/release/manualpages/Mat/MatSetValuesBlocked.html

Source code at petsc4py/PETSc/Mat.pyx:2983 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2983

setValuesBlockedIJV(I, J, V, addv=None, rowmap=None)

Sets a subset of values stored in block CSR format. Not the whole thing, just the subset. Lowkey selective, highkey slay. 💖

Not collective.

Parameters

  • I (Sequence[int]) — Block row pointers.
  • J (Sequence[int]) — Block column indices.
  • V (Sequence[Scalar]) — The scalar values.
  • addv (InsertModeSpec) — Insertion mode.
  • rowmap (Sequence[int] | None) — Optional iterable indicating which block row to insert. Optional, so you can just not, if you don't vibe with it. 🦋

Return type: None

See also: MatSetValuesBlocked — petsc.org/release/manualpages/Mat/MatSetValuesBlocked.html

Source code at petsc4py/PETSc/Mat.pyx:2952 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2952

setValuesBlockedLocal(rows, cols, values, addv=None)

Sets values to the rows ⊗ col block entries of the matrix in local ordering. Local. Not global. Important distinction bestie, don't get it twisted. 👑

Not collective.

Parameters

  • rows (Sequence[int]) — Local block row indices.
  • cols (Sequence[int]) — Local block column indices.
  • values (Sequence[Scalar]) — The scalar values. A sequence of length at least len(rows) * len(cols) * bs * bs, where bs is the block size of the matrix.
  • addv (InsertModeSpec) — Insertion mode.

Return type: None

See also: MatSetValuesBlockedLocal — petsc.org/release/manualpages/Mat/MatSetValuesBlockedLocal.html

Source code at petsc4py/PETSc/Mat.pyx:3172 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3172

setValuesBlockedLocalCSR(I, J, V, addv=None)

Sets values stored in block CSR format — but local this time. Same girl, different address. 🎀

Not collective.

Parameters

  • I (Sequence[int]) — Block row pointers.
  • J (Sequence[int]) — Local block column indices.
  • V (Sequence[Scalar]) — The scalar values.
  • addv (InsertModeSpec) — Insertion mode.

Return type: None

See also: MatSetValuesBlockedLocal — petsc.org/release/manualpages/Mat/MatSetValuesBlockedLocal.html

Source code at petsc4py/PETSc/Mat.pyx:3237 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3237

setValuesBlockedLocalIJV(I, J, V, addv=None, rowmap=None)

Sets a subset of values stored in block CSR format. Local subset edition. 🌈

Not collective.

Parameters

Return type: None (https://docs.python.org/3/builtins/constants.html#None) — she returns nothing and that's the whole vibe.

See also: MatSetValuesBlockedLocal (https://petsc.org/release/manualpages/Mat/MatSetValuesBlockedLocal.html)

Source code at petsc4py/PETSc/Mat.pyx:3206 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3206)

setValuesBlockedLocalRCV(R, C, V, addv=None)

Undocumented. Yeah bestie, the docs said no comment 💀

Source code at petsc4py/PETSc/Mat.pyx:3202 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3202)

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

setValuesBlockedRCV(R, C, V, addv=None)

Undocumented. Same energy, different line number. 🙈

Source code at petsc4py/PETSc/Mat.pyx:2948 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2948)

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

setValuesCOO(coo_v, addv=None)

Okay so this one sets values after preallocation with coordinate format.

Collective. 🫶 Everybody's in on it, no solo missions.

Parameters:

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

See also: setPreallocationCOO, MatSetValuesCOO (https://petsc.org/release/manualpages/Mat/MatSetValuesCOO.html)

Source code at petsc4py/PETSc/Mat.pyx:2869 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2869)

setValuesCSR(I, J, V, addv=None)

Set values stored in CSR format. 📓

Not collective. This one stays local, she's lowkey an introvert.

Parameters:

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

See also: MatSetValues (https://petsc.org/release/manualpages/Mat/MatSetValues.html)

Source code at petsc4py/PETSc/Mat.pyx:2890 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2890)

setValuesIJV(I, J, V, addv=None, rowmap=None)

Set a subset of values stored in CSR format. Yes, a subset, she's selective like that 💅

Not collective.

Parameters:

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

See also: MatSetValues (https://petsc.org/release/manualpages/Mat/MatSetValues.html)

Source code at petsc4py/PETSc/Mat.pyx:2838 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2838)

setValuesLocal(rows, cols, values, addv=None)

Set values to the rows ⊗ col entries of the matrix in local ordering. 🦋

Not collective.

Parameters:

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

See also: MatSetValuesLocal (https://petsc.org/release/manualpages/Mat/MatSetValuesLocal.html)

Source code at petsc4py/PETSc/Mat.pyx:3081 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3081)

setValuesLocalCSR(I, J, V, addv=None)

Set values stored in CSR format. Same crowd, local girlie edition. 🍓

Not collective.

Parameters:

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

See also: MatSetValuesLocal (https://petsc.org/release/manualpages/Mat/MatSetValuesLocal.html)

Source code at petsc4py/PETSc/Mat.pyx:3144 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3144)

setValuesLocalIJV(I, J, V, addv=None, rowmap=None)

Set a subset of values stored in CSR format. Subset queen stays subsetting 👑

Not collective.

Parameters:

Return type: None

See also: MatSetValuesLocal

Source code: petsc4py/PETSc/Mat.pyx:3113

setValuesLocalRCV(R, C, V, addv=None)

Undocumented. Yeah bestie, it's giving mystery. 🙈

Source code: petsc4py/PETSc/Mat.pyx:3109

Return type: None

setValuesRCV(R, C, V, addv=None)

Also undocumented. We simply do not know her lore. 💀

Source code: petsc4py/PETSc/Mat.pyx:2834

Return type: None

setVariableBlockSizes(blocks)

Okay so this one sets the diagonal point-blocks of the matrix. Very specific, very intentional. ✨

Not collective. So like, it's a one-girl show — everybody calls it on their own, no group chat needed.

See also: setBlockSize, MatSetVariableBlockSizes

Source code: petsc4py/PETSc/Mat.pyx:653

Parameters

  • blocks (Sequence[int])

Return type: None

setVecType(vec_type)

Sets the vector type. Slay. 🦋

Collective. Yeah bestie, group project energy — everyone's gotta be on the same page.

Parameters

  • vec_type (Type | str) — the vector type used when creating vectors with createVecs.

Return type: None

See also: getVecType, MatSetVecType

Source code: petsc4py/PETSc/Mat.pyx:667

shift(alpha)

Shifts the matrix. Literally just a shift, no cap. 💅

Collective.

See also: MatShift

Source code: petsc4py/PETSc/Mat.pyx:4355

Parameters

  • alpha (Scalar)

Return type: None

solve(b, x)

Solves Ax=b, given a factored matrix. Iconic linear algebra behavior. 🔥

Neighborwise collective.

⚠️ The vectors b and x cannot be the same. Like, they're two different girlies, do not merge them.

And ngl, most users should just use the KSP interface for linear solvers instead of working directly with matrix algebra routines. That's the vibe check: use KSP, bestie.

Parameters

  • b (Vec) — the right-hand side vector.
  • x (Vec) — the output solution vector, must be different than b.

Return type: None

See also: KSP.create, solveTranspose, MatSolve

Source code: petsc4py/PETSc/Mat.pyx:5677

solveAdd(b, y, x)

Solves x=y+A⁻¹b, given a factored matrix. Yes the superscript inverse is doing a lot and yes she's serving. 👑

Neighborwise collective.

⚠️ The vectors b and x cannot be the same.

Parameters

  • b (Vec) — the right-hand side vector.
  • y (Vec) — the vector to be added
  • x (Vec) — the output solution vector, must be different than b.

Return type: None

See also: KSP.create, MatSolve, MatSolveAdd

Source code: petsc4py/PETSc/Mat.pyx:5721

solveBackward(b, x)

Solves Ux=b, given a factored matrix A=LU. Backwards solve era. 🌸

Neighborwise collective.

Parameters

  • b (Vec) — the right-hand side vector.
  • x (Vec) — the output solution vector.

Return type: None

See also: MatBackwardSolve

Source code: petsc4py/PETSc/Mat.pyx:5658

solveForward(b, x)

Solves Lx = b, given a factored matrix A = LU. Forward solve, the prequel. ✨

Neighborwise collective.

Parameters

  • b (Vec) — the right-hand side vector.
  • x (Vec) — the output solution vector.

Return type: None

See also: MatForwardSolve

Source code: petsc4py/PETSc/Mat.pyx:5639

solveTranspose(b, x)

Solves Aᵀx=b, given a factored matrix. Transpose girlies rise. 🦋

Neighborwise collective.

⚠️ The vectors b and x cannot be the same.

Parameters

  • b (Vec) — the right-hand side vector.
  • x (Vec) — the output solution vector, must be different than b.

Return type: None

See also: KSP.create, MatSolve, MatSolveTranspose

Source code: petsc4py/PETSc/Mat.pyx:5700

solveTransposeAdd(b, y, x)

Solves x=y+A⁻ᵀb, given a factored matrix. Transpose and add — she's multitasking, she's the moment. 💜

Neighborwise collective.

⚠️ The vectors b and x cannot be the same.

Parameters

  • b (Vec) — the right-hand side vector.
  • y (Vec) — the vector to be added
  • x (Vec) — the output solution vector, must be different than b.

Return type: None

See also: KSP.create, MatSolve, MatSolveTransposeAdd

Source code: petsc4py/PETSc/Mat.pyx:5744

✨ storeValues() ✨

Stash a copy of the matrix values, bestie — like a lil screenshot but for numbers. 📸

Collective — everyone chips in, no solo missions here.

See also: retrieveValues, MatStoreValues — https://petsc.org/release/manualpages/Mat/MatStoreValues.html

Source code at petsc4py/PETSc/Mat.pyx:3525 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3525

Return type: None — https://docs.python.org/3/builtins/constants.html#None

🫶 toDLPack(mode='rw') 🫶

Hands you back a DLPack PyCapsule 💊 wrapping the vector data. Fancy little export moment, we love to see it.

Source code at petsc4py/PETSc/Mat.pyx:6184 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6184

Parameters:

  • mode (AccessModeSpec) — the access mode you want, iykyk.

Return type: Any — https://docs.python.org/3/library/typing.html#typing.Any

🦋 transpose(out=None) 🦋

Gives you the transposed matrix. Flip it and reverse it, that's the vibe. 🔄

Collective — whole squad participates.

Parameters:

Return type: Mat — https://docs.python.org/3/petsc4py.PETSc.Mat

See also: MatTranspose — https://petsc.org/release/manualpages/Mat/MatTranspose.html

Source code at petsc4py/PETSc/Mat.pyx:2310 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2310

🔥 transposeMatMult(mat, result=None, fill=None) 🔥

Does the matrix-matrix multiplication C=AᵀB. Like, A gets transposed AND multiplied at the same time, main character behavior honestly. 👑

Neighborwise collective.

Parameters:

Returns: result — the resultant product matrix C.

Return type: Mat

Notes

To figure out the correct fill value, run with -info and search for the string "Fill ratio" to see the value you actually needed. Detective work but make it ✨matrix✨.

See also: MatTransposeMatMult — https://petsc.org/release/manualpages/Mat/MatTransposeMatMult.html, MatReuse — https://petsc.org/release/manualpages/Mat/MatReuse.html

Source code at petsc4py/PETSc/Mat.pyx:4542 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L4542

💜 updateLMVM(x, f) 💜

Adds (X-Xprev) and (F-Fprev) updates to the LMVM matrix. It's giving "keep the previous you in the group chat" energy. 💬

Logically collective.

Parameters:

  • x (Vec) — solution vector.
  • f (Vec) — function vector.

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: MatLMVMUpdate — https://petsc.org/release/manualpages/KSP/MatLMVMUpdate.html

Source code at petsc4py/PETSc/Mat.pyx:5446 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L5446

👑 view(viewer=None) 👑

Views the matrix. Gives it a little moment in the spotlight. 🌟

Collective.

Parameters:

Return type: None — https://docs.python.org/3/builtins/constants.html#None

Notes

Viewers with type Viewer.Type.ASCII are only recommended for small matrices on small numbers of processes. Larger matrices should use a binary format like Viewer.Type.BINARY, fr fr. 💀 ASCII on a huge matrix is not the move.

See also: load, Viewer, MatView — https://petsc.org/release/manualpages/Mat/MatView.html

Source code at petsc4py/PETSc/Mat.pyx:478 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L478

🧚 zeroEntries() 🧚

Zeros out the entries of the matrix. Everything → 0, poof, clean slate. 🫧

Collective.

See also: MatZeroEntries — https://petsc.org/release/manualpages/Mat/MatZeroEntries.html

Source code at petsc4py/PETSc/Mat.pyx:2606 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L2606

Return type: None — https://docs.python.org/3/builtins/constants.html#None

🌸 zeroRows(rows, diag=1.0, x=None, b=None) 🌸

Zeros out selected rows of the matrix. Pick your rows, cancel them, iconic. ✂️

Collective.

Parameters:

  • rows (IS | Sequence[int]) — the row indices to be zeroed.
  • diag (Scalar) — the scalar value to be inserted into the diagonal.
  • x (Vec | None) — optional solution vector, gets modified for the zeroed rows.
  • b (Vec | None) — optional right-hand side vector to be modified. It'll be adjusted with the solution entries you provided.

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: zeroRowsLocal, MatZeroRows — https://petsc.org/release/manualpages/Mat/MatZeroRows.html, MatZeroRowsIS — https://petsc.org/release/manualpages/Mat/MatZeroRowsIS.html

Source code at petsc4py/PETSc/Mat.pyx:3357 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3357

🌈 zeroRowsColumns(rows, diag=1.0, x=None, b=None) 🌈

Zeros out selected rows AND columns at the same time. Double the zeroing, double the slay. 💅

Collective.

Parameters:

  • rows (IS | Sequence[int]) — the row/column indices to be zeroed.
  • diag (Scalar) — the scalar value to be inserted into the diagonal.
  • x (Vec | None) — optional solution vector, gets modified for the zeroed rows.
  • b (Vec | None) — optional right-hand side vector to be modified. It'll be adjusted with the solution entries you provided.

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: zeroRowsColumnsLocal, zeroRows, MatZeroRowsColumns — https://petsc.org/release/manualpages/Mat/MatZeroRowsColumns.html, MatZeroRowsColumnsIS — https://petsc.org/release/manualpages/Mat/MatZeroRowsColumnsIS.html

Source code at petsc4py/PETSc/Mat.pyx:3423 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3423

zeroRowsColumnsLocal(rows, diag=1.0, x=None, b=None)

zeroRowsColumnsLocal(rows, diag=1.0, x=None, b=None)

Zero selected rows and columns of the matrix, but in local ordering bestie, ok so like the indices you hand in are the ones this process owns 💅

Collective. (everyone on the communicator has to show up for this one, no ghosting 🫶)

Parameters

  • rows (IS | Sequence[int]) — Local row/column indices to be zeroed. ✨
  • diag (Scalar) — Scalar value to be inserted into the diagonal. 🎀
  • x (Vec | None) — Optional solution vector to be modified for zeroed rows.
  • b (Vec | None) — Optional right-hand side vector to be modified. It will be adjusted with provided solution entries.

Return type

None 🫠

See also:

Source code at petsc4py/PETSc/Mat.pyx:3457 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3457

zeroRowsColumnsStencil(rows, diag=1.0, x=None, b=None)

zeroRowsColumnsStencil(rows, diag=1.0, x=None, b=None)

Zero selected rows and columns of the matrix — and instead of index lists you're feeding it stencils 🧚 the way that it just takes a whole neighborhood and wipes it, iconic.

Collective.

Parameters

  • rows (Sequence[Stencil]) — Iterable of stencil rows and columns.
  • diag (Scalar) — Scalar value to be inserted into the diagonal.
  • x (Vec | None) — Optional solution vector to be modified for zeroed rows.
  • b (Vec | None) — Optional right-hand side vector to be modified. It will be adjusted with provided solution entries.

Return type

None 🌸

See also:

Source code at petsc4py/PETSc/Mat.pyx:3491 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3491

zeroRowsLocal(rows, diag=1.0, x=None, b=None)

zeroRowsLocal(rows, diag=1.0, x=None, b=None)

Zero selected rows of the matrix, local ordering edition ✨ rows only bestie, we're not touching the columns here, that's a whole different function's job 💅

Collective.

Parameters

  • rows (IS | Sequence[int]) — Local row indices to be zeroed.
  • diag (Scalar) — Scalar value to be inserted into the diagonal.
  • x (Vec | None) — Optional solution vector to be modified for zeroed rows.
  • b (Vec | None) — Optional right-hand side vector to be modified. It will be adjusted with provided solution entries.

Return type

None 😭

See also:

Source code at petsc4py/PETSc/Mat.pyx:3390 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L3390

📖 Attributes Documentation 📖

The properties of a Mat, all lined up like a lil roster 🎀 each one's got a source line so you can go peek at the real thing if you want iykyk

assembled

The boolean flag indicating if the matrix is assembled. 🧩

Source code at petsc4py/PETSc/Mat.pyx:6159 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6159

block_size

Matrix block size. 🍓

Source code at petsc4py/PETSc/Mat.pyx:6137 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6137

block_sizes

Matrix row and column block sizes. 🌈

Source code at petsc4py/PETSc/Mat.pyx:6142 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6142

hermitian

The boolean flag indicating if the matrix is Hermitian. 👑

Source code at petsc4py/PETSc/Mat.pyx:6167 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6167

local_size

Matrix local size. 🦋

Source code at petsc4py/PETSc/Mat.pyx:6132 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6132

owner_range

Matrix local row range. 📏

Source code at petsc4py/PETSc/Mat.pyx:6147 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6147

owner_ranges

Matrix row ranges. 📐

Source code at petsc4py/PETSc/Mat.pyx:6152 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6152

size

Matrix global size. 🌍

Source code at petsc4py/PETSc/Mat.pyx:6127 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6127

sizes

Matrix local and global sizes. 💫

Source code at petsc4py/PETSc/Mat.pyx:6119 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6119

structsymm

The boolean flag indicating if the matrix is structurally symmetric. 🕸️

Source code at petsc4py/PETSc/Mat.pyx:6171 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6171

symmetric

The boolean flag indicating if the matrix is symmetric. 🪞

Source code at petsc4py/PETSc/Mat.pyx:6163 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6163

__init__()

__init__()

classmethod __new__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

🦋 petsc4py.PETSc.MatPartitioning 🦋

class petsc4py.PETSc.MatPartitioning

Bases: Object

Object for managing the partitioning of a matrix or graph. — like, it's the lil manager that decides how your matrix/graph gets chopped up and handed around the crew 💅 she's got main character energy for real.

Enumerations

  • Type — The partitioning types. ✨

🎀 petsc4py.PETSc.MatPartitioning.Type 🎀

class petsc4py.PETSc.MatPartitioning.Type

Bases: object

The partitioning types. 🌸

✨ Attributes Summary ✨

okay bestie, this class ships with a whole lil squad of string constants 💅 every single one of them is an object of type str (the full type link, since the original is obsessed with it, is https://docs.python.org/3/builtins/stdtypes.html#str). Here they all are, no cap, none skipped:

💖 Attributes Documentation 💖

like, the receipts, one by one 🧚

PARTITIONINGAVERAGE

PARTITIONINGAVERAGE: str = PARTITIONINGAVERAGE

Object PARTITIONINGAVERAGE of type str (https://docs.python.org/3/builtins/stdtypes.html#str).

PARTITIONINGCHACO

PARTITIONINGCHACO: str = PARTITIONINGCHACO

Object PARTITIONINGCHACO of type str (https://docs.python.org/3/builtins/stdtypes.html#str).

PARTITIONINGCURRENT

PARTITIONINGCURRENT: str = PARTITIONINGCURRENT

Object PARTITIONINGCURRENT of type str (https://docs.python.org/3/builtins/stdtypes.html#str).

PARTITIONINGHIERARCH

PARTITIONINGHIERARCH: str = PARTITIONINGHIERARCH

Object PARTITIONINGHIERARCH of type str (https://docs.python.org/3/builtins/stdtypes.html#str).

PARTITIONINGPARMETIS

PARTITIONINGPARMETIS: str = PARTITIONINGPARMETIS

Object PARTITIONINGPARMETIS of type str (https://docs.python.org/3/builtins/stdtypes.html#str).

PARTITIONINGPARTY

PARTITIONINGPARTY: str = PARTITIONINGPARTY

Object PARTITIONINGPARTY of type str (https://docs.python.org/3/builtins/stdtypes.html#str).

PARTITIONINGPTSCOTCH

PARTITIONINGPTSCOTCH: str = PARTITIONINGPTSCOTCH

Object PARTITIONINGPTSCOTCH of type str (https://docs.python.org/3/builtins/stdtypes.html#str).

PARTITIONINGSQUARE

PARTITIONINGSQUARE: str = PARTITIONINGSQUARE

Object PARTITIONINGSQUARE of type str (https://docs.python.org/3/builtins/stdtypes.html#str).

and then the dunder girlypops 🌸

__init__()

classmethod __new__(*args, **kwargs)

🌈 Methods Summary 🌈

the whole roster, vibe-checked, nothing hidden:

  • apply(partitioning) — Return a partitioning for the graph represented by a sparse matrix.
  • create([comm]) — Create a partitioning context.
  • destroy() — Destroy the partitioning context.
  • getType() — Return the partitioning method.
  • setAdjacency(adj) — Set the adjacency graph (matrix) of the thing to be partitioned.
  • setFromOptions() — Set parameters in the partitioner from the options database.
  • setType(matpartitioning_type) — Set the type of the partitioner to use.
  • view([viewer]) — View the partitioning data structure.

🌸 Methods Documentation 🌸

apply(partitioning)

Return a partitioning for the graph represented by a sparse matrix.

Collective. (yes queen, everybody has to show up for this one 🫶)

For each local node this tells the processor number that that node is assigned to.

See also:

Source code at petsc4py/PETSc/MatPartitioning.pyx:144 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/MatPartitioning.pyx#L144

Parameters

  • partitioning (IS, link target #petsc4py.PETSc.IS)

Return type

create(comm=None)

Create a partitioning context.

Collective.

Parameters ✨

  • comm (Comm | None) — the MPI communicator bb, and if you just don't pass one it lowkey defaults to Sys.getDefaultComm 🫶

Return type: Self

See also: destroy, MatPartitioningCreate — https://petsc.org/release/manualpages/MatGraphOperations/MatPartitioningCreate.html

Source code at petsc4py/PETSc/MatPartitioning.pyx:62 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/MatPartitioning.pyx#L62

destroy() 💀

okay so this one just destroys the partitioning context, like it's over, it's done, we're closing the tab on this whole situation 😭

It's collective — so every process in the communicator has to show up for it, no ghosting 🚫👻

See also: create, MatPartitioningDestroy — https://petsc.org/release/manualpages/MatGraphOperations/MatPartitioningDestroy.html

Source code at petsc4py/PETSc/MatPartitioning.pyx:49 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/MatPartitioning.pyx#L49

Return type: Self

getType() 🎀

Returns the partitioning method — like, which partitioner is this thing even being, bestie? who is she?

Not collective. So she can just tell you, no committee meeting required 💁‍♀️

See also: setType, MatPartitioningGetType — https://petsc.org/release/manualpages/MatGraphOperations/MatPartitioningGetType.html

Source code at petsc4py/PETSc/MatPartitioning.pyx:100 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/MatPartitioning.pyx#L100

Return type: str

setAdjacency(adj) 🦋

Sets the adjacency graph (matrix) of the thing you're about to partition. It's giving "here's the map of who knows who, now go split the friend group" 🗺️

Collective — everyone in on this together, fr fr.

Parameters

  • adj (Mat) — the adjacency matrix. Technically it can be any Mat.Type, but the natural, ideal, main-character representation is Mat.Type.MPIADJ 👑

Return type: None

See also: MatPartitioningSetAdjacency — https://petsc.org/release/manualpages/MatGraphOperations/MatPartitioningSetAdjacency.html

Source code at petsc4py/PETSc/MatPartitioning.pyx:126 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/MatPartitioning.pyx#L126

setFromOptions() ⚙️✨

Pulls the partitioner's parameters straight out of the options database — so instead of hardcoding anything you just vibe with CLI flags and she reads them all in for you 🎀

Collective, periodt.

See also: Working with PETSc options, MatPartitioningSetFromOptions — https://petsc.org/release/manualpages/MatGraphOperations/MatPartitioningSetFromOptions.html

Source code at petsc4py/PETSc/MatPartitioning.pyx:114 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/MatPartitioning.pyx#L114

Return type: None

setType(matpartitioning_type) 💅

Sets which type of partitioner to use. Pick your fighter, bestie 🔥

Collective.

Parameters

  • matpartitioning_type (Type | str) — the partitioner type. Give it the enum or just the string name, she's flexible like that 💖

Return type: None

See also: getType, MatPartitioningSetType — https://petsc.org/release/manualpages/MatGraphOperations/MatPartitioningSetType.html

Source code at petsc4py/PETSc/MatPartitioning.pyx:81 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/MatPartitioning.pyx#L81

view(viewer=None) 👀

Views the partitioning data structure — aka lets you actually look at the graph instead of just trusting that it exists 🙈

Collective.

Parameters

  • viewer (Viewer | None) — a Viewer to display the graph. Pass nothing and it does its default thing 🌸

Return type: None

See also: MatPartitioningView — https://petsc.org/release/manualpages/MatGraphOperations/MatPartitioningView.html

Source code at petsc4py/PETSc/MatPartitioning.pyx:29 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/MatPartitioning.pyx#L29

__init__()

classmethod __new__(*args, **kwargs)

🌈 petsc4py.PETSc.NormType 🌈

class petsc4py.PETSc.NormType

Bases: object

It's the norm type enum, bestie — the menu of ways to measure how big a thing is 📏

Commonly used norm types:

  • N1 — the one norm.
  • N2 — the two norm.
  • FROBENIUS — the Frobenius norm.
  • INFINITY — the infinity norm.

See also: NormType — https://petsc.org/release/manualpages/Vec/NormType.html

🎀 Attributes Summary 🎀

okay so this is the constant roster, bestie 💖 every single one of these is a plain old int — the docs point the exact same Python builtin link at all of them, no cap: https://docs.python.org/3/builtins/functions.html#int

that's the whole squad, fourteen of them, all int, zero drama 💅

🦋 Attributes Documentation 🦋

same crew as above, but now you get the actual assignment spellings, because yes the attribute name is also its own value and honestly? iconic ✨

and then there's the constructor situation for this class, which the docs list like this 🌸

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

so yeah — __init__() takes literally nothing, and the __new__ is blessed as a classmethod and just hoovers up *args and **kwargs, periodt. it's giving "we pass everything through and let the C layer sort it out" 💀

🧚 petsc4py.PETSc.NullSpace

class petsc4py.PETSc.NullSpace

Bases: Object — as in petsc4py.PETSc.Object (the anchor's literally #petsc4py.PETSc.Object, iykyk)

it's a Nullspace object, bestie. that's the whole description — short, sweet, main character energy. it's the wrapper for the whole "the vectors that this operator sends straight to zero" situation. 🫶

See also:

like if you want the deep lore instead of the pretty wrapper, that's where the C-side manual page lives, go drink from the source 🍓

and that's the norm constants and the NullSpace intro wrapped 💖 next stretch of the reference has even more of this class-attribute buffet, so stay seated, we're not done yet 💅

✨ Methods Summary ✨

okay bestie, here's the whole roster at a glance — every method this thing ships with, so you know what's on the menu before we get into the deets 💅

  • create([constant, vectors, comm]) — Create the null space.
  • createRigidBody(coords) — Create rigid body modes from coordinates.
  • destroy() — Destroy the null space.
  • getFunction() — Return the callback to remove the nullspace.
  • getVecs() — Return the vectors defining the null space.
  • hasConstant() — Return whether the null space contains the constant.
  • remove(vec) — Remove all components of a null space from a vector.
  • setFunction(function[, args, kargs]) — Set the callback to remove the nullspace.
  • test(mat) — Return if the claimed null space is valid for a matrix.
  • view([viewer]) — View the null space.

✨ Methods Documentation ✨

create(constant=False, vectors=(), comm=None)</p>

Create the null space, bestie. This one's the whole personality of the class fr 💖

Collective — so like, everybody in the communicator has to show up. No ghosting. 👑

Parameters

  • constant (bool) — A flag to indicate the null space contains the constant vector.
  • vectors (Sequence[Vec]) — The sequence of vectors that span the null space.
  • comm — MPI communicator, defaults to Sys.getDefaultComm.

Return type

Self

See also:

Source code at petsc4py/PETSc/Mat.pyx:6308 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6308

createRigidBody(coords)</p>

Create rigid body modes from coordinates 🌸 so like, it builds you the rigid-body vibes straight out of the geometry. Slay.

Collective — group chat rules apply, everyone participates 💫

Parameters

  • coords (Vec) — The block coordinates of each node. Requires the block size to have been set.
⚠️ okay this is the important bit — it requires the block size to have been set first. Don't skip that step, bestie, it's giving prerequisite 💀

Return type

Self

See also:

Source code at petsc4py/PETSc/Mat.pyx:6344 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6344

destroy()</p>

Destroy the null space. Clean up after yourself, it's the polite thing to do 🎀

Collective

See also:

Source code at petsc4py/PETSc/Mat.pyx:6295 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6295

Return type

Self

getFunction()</p>

Return the callback to remove the nullspace. Gimme the function back, I need it 🔥

Not collective — this one's a solo mission, no need to loop in the whole communicator 🦋

See also:

  • setFunction

Source code at petsc4py/PETSc/Mat.pyx:6435 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6435

Return type

MatNullFunction

getVecs()</p>

Return the vectors defining the null space. The receipts, basically ✨

Not collective

See also:

Source code at petsc4py/PETSc/Mat.pyx:6413 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6413

Return type

list[Vec]

hasConstant()</p>

Return whether the null space contains the constant. Yes/no, does it have the constant or not — quick vibe check 👀

Not collective

See also:

Source code at petsc4py/PETSc/Mat.pyx:6399 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6399

Return type

bool

remove(vec)</p>

Remove all components of a null space from a vector. Yeeting the nullspace contributions out of your vector, respectfully 💅

Collective

Parameters

  • vec (Vec) — The vector from which the null space is removed.

Return type

None

See also:

Source code at petsc4py/PETSc/Mat.pyx:6449 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6449

setFunction(function, args=None, kargs=None)</p>

Set the callback to remove the nullspace. Hand it the function and it'll handle the removal for you 🫶

Logically collective — like, logically babe, not actually collective. iykyk 😌

Parameters

  • function (MatNullFunction) — The callback.
  • args (tuple[Any, ...] | None) — Positional arguments for the callback.
  • kargs (dict[str, Any] | None) — Keyword arguments for the callback.

Return type

None

See also:

Source code at petsc4py/PETSc/Mat.pyx:6365 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6365

test(mat)</p>

Return if the claimed null space is valid for a matrix. Like, is this null space actually legit for this matrix or are we lying to ourselves 😭 it'll tell you.

Collective

Parameters

  • mat (Mat) — The matrix to check.

Return type

bool

…and that's where this chunk runs out — <rainbow>view` is up next, so hold that thought bestie 💖

See also: MatNullSpaceTest — the whole page is sitting at https://petsc.org/release/manualpages/Mat/MatNullSpaceTest.html if you feel like a lil' field trip 🧚

Source code at petsc4py/PETSc/Mat.pyx:6466 — like, the real actual Cython, here: https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6466 👀

view(viewer=None) 💅

Okay so this one shows you your null space. That's it, that's the function. It is collective, bestie — meaning every single process in your communicator has to show up for it, no ghosting your MPI ranks, fr fr. 😭

Parameters

  • viewer (Viewer | None) — hand it a Viewer instance, or pass None (the default, viewer=None) and it'll just use the default viewer for you. No thoughts, head empty, default behavior. 🫶

Return type

None — it returns literally nothing. The whole point is the side effect, periodt. ✨

See also: Viewer, MatNullSpaceView — docs live at https://petsc.org/release/manualpages/Mat/MatNullSpaceView.html

Source code at petsc4py/PETSc/Mat.pyx:6276 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Mat.pyx#L6276 🔥

__init__()

(no notes here, it just does its little init thing, iconic behavior, we love a constructor that minds its business) 🎀

classmethod __new__(*args, **kwargs)

It's a classmethod and it takes *args and **kwargs. That's the whole vibe check. Nothing else to report. 💀

🌈 petsc4py.PETSc.Object 🌈

class petsc4py.PETSc.Object

Bases: object — yes, that object, the one from https://docs.python.org/3/builtins/functions.html#object 🦋

This is the base class that wraps a PETSc object. Like, everything PETSc-y in here descends from this queen. It's the blueprint, the origin story, the main character energy at the root of the tree. 👑

See also: PetscObject — the C-level ancestor, docs at https://petsc.org/release/manualpages/Sys/PetscObject.html 💜

✨ Methods Summary ✨

okay bestie, here's the full roster of methods on the base PETSc object — every single one, no skipping 💖

  • appendOptionsPrefix(prefix) — glues more stuff onto the prefix that gets used when it goes looking for options in the database ✨
  • compose(name, obj) — hooks up a PETSc object to this one using a key string 🎀
  • decRef() — drops the object's reference count by one 💅
  • destroy() — destroys the object 💀
  • destroyOptionsHandlers() — wipes out every single option handler, all of them, gone 🧹
  • getAttr(name) — hands you back the attribute that's chillin' under a given name 🦋
  • getClassId() — returns the class identifier of the object 👑
  • getClassName() — returns the class name of the object 🌸
  • getComm() — returns the communicator the object is riding with 🌈
  • getDict() — returns the dictionary of attributes 📚
  • getId() — returns the object's unique identifier, its one-of-a-kind lil fingerprint ⭐
  • getName() — returns the name of the object 💜
  • getOptionsPrefix() — returns the prefix it uses when searching for options in the database 🔍
  • getRefCount() — returns the object's reference count 🧮
  • getTabLevel() — returns the PETSc object tab level 🗂️
  • getType() — returns the object type name 💫
  • incRef() — bumps the object's reference count up by one 🔥
  • incrementTabLevel(tab[, parent]) — increments the PETSc object tab level, optionally handing it a parent too 🫶
  • query(name) — asks around for the PETSc object tied to a key string 🙈
  • setAttr(name, attr) — sets an the attribute associated with a given name ✨ (yes the double "an the" is in the original, we do not touch it, we respect it 💅)
  • setFromOptions() — configures the object using the options database 🎛️
  • setName(name) — gives the object a name to go by 🌸
  • setOptionsHandler(handler) — sets the callback that handles the extra options 🪄
  • setOptionsPrefix(prefix) — sets the prefix used when searching for options in the database 🔑
  • setTabLevel(level) — sets the PETSc object tab level 📐
  • stateGet() — returns the PETSc object state 👀
  • stateIncrease() — increments the PETSc object state ⏫
  • stateSet(state) — sets the PETSc object state 🎯
  • view([viewer]) — displays the object, optionally through a viewer 🖼️
  • viewFromOptions(name[, objpre]) — views the object via command line options, with an optional objpre 🎬

that's the whole methods menu, every last one accounted for 💖 keep scrolling bestie, there's more where this came from 🦋

✨ Attributes Summary ✨

okay so every Object comes with these built-in attributes, and here's the whole squad 💅

  • classid — The class identifier.
  • comm — The object communicator.
  • fortran — Fortran handle.
  • handle — Handle for ctypes support.
  • id — The object identifier.
  • klass — The class name.
  • name — The object name.
  • prefix — Options prefix.
  • refcount — Reference count.
  • type — Object type.

✨ Methods Documentation ✨

💫 appendOptionsPrefix(prefix)

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

Logically collective.

See also: Working with PETSc options, setOptionsPrefix, PetscObjectAppendOptionsPrefix (https://petsc.org/release/manualpages/Sys/PetscObjectAppendOptionsPrefix.html)

Source code at petsc4py/PETSc/Object.pyx:138 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L138)

Parameters

  • prefix (str | None)

Return type

  • None

💫 compose(name, obj)

Associate a PETSc object using a key string. it's giving "tag it so you can find it later" energy 🎀

Logically collective.

Parameters

  • name (str | None) — The string identifying the object to be composed.
  • obj (Object) — The object to be composed.

Return type

  • None

See also: query, PetscObjectCompose (https://petsc.org/release/manualpages/Sys/PetscObjectCompose.html)

Source code at petsc4py/PETSc/Object.pyx:329 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L329)

💫 decRef()

Decrement the object reference count. bye bestie, one less person holding on 😭

Logically collective.

See also: getRefCount, PetscObjectDereference (https://petsc.org/release/manualpages/Sys/PetscObjectDereference.html)

Source code at petsc4py/PETSc/Object.pyx:389 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L389)

Return type

  • int

💫 destroy()

Destroy the object. literally the end of an era ✨

Collective.

See also: PetscObjectDestroy (https://petsc.org/release/manualpages/Sys/PetscObjectDestroy.html)

Source code at petsc4py/PETSc/Object.pyx:81 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L81)

Return type

  • Self

💫 destroyOptionsHandlers()

Clear all the option handlers. clearing the roster, no survivors 🫶

Collective.

See also: Working with PETSc options, setOptionsHandler, PetscObjectDestroyOptionsHandlers (https://petsc.org/release/manualpages/Sys/PetscObjectDestroyOptionsHandlers.html)

Source code at petsc4py/PETSc/Object.pyx:213 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L213)

Return type

  • None

💫 getAttr(name)

Return the attribute associated with a given name. ngl this is the little lookup that always comes through 💖

Not collective.

See also: setAttr, getDict

Source code at petsc4py/PETSc/Object.pyx:408 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L408)

Parameters

  • name (str)

Return type

  • object

💫 getClassId()

Return the class identifier of the object.

Not collective.

See also: PetscObjectGetClassId (https://petsc.org/release/manualpages/Sys/PetscObjectGetClassId.html)

Source code at petsc4py/PETSc/Object.pyx:270 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L270)

Return type

  • int

💫 getClassName()

Return the class name of the object.

Not collective.

See also: PetscObjectGetClassName (https://petsc.org/release/manualpages/Sys/PetscObjectGetClassName.html)

Source code at petsc4py/PETSc/Object.pyx:284 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L284)

Return type

  • str

💫 getComm()

Return the communicator of the object. the group chat it belongs to, basically 🦋

Not collective.

See also: PetscObjectGetComm (https://petsc.org/release/manualpages/Sys/PetscObjectGetComm.html)

Source code at petsc4py/PETSc/Object.pyx:228 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L228)

Return type

  • Comm

💫 getDict()

Return the dictionary of attributes. the whole notes app of vibes, all at once 📝

Not collective.

See also: setAttr, getAttr

Source code at petsc4py/PETSc/Object.pyx:436 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L436)

Return type

  • dict

💫 getId()

Return the unique identifier of the object. nobody else has this one, it's iconic like that 👑

Not collective.

See also: PetscObjectGetId (https://petsc.org/release/manualpages/Sys/PetscObjectGetId.html)

Source code at petsc4py/PETSc/Object.pyx:313 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L313)

Return type

  • int

💫 getName()

Return the name of the object.

Not collective.

See also: PetscObjectGetName (https://petsc.org/release/manualpages/Sys/PetscObjectGetName.html)

Source code at petsc4py/PETSc/Object.pyx:242 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L242)

Return type

  • str

💫 getOptionsPrefix()

Return the prefix used for searching for options in the database.

Not collective.

See also: Working with PETSc options, setOptionsPrefix, PetscObjectGetOptionsPrefix (https://petsc.org/release/manualpages/Sys/PetscObjectGetOptionsPrefix.html)

getRefCount() 💖

Return the reference count of the object — basically how many peeps are holding a lil handle on it rn.

Not collective.

See also: PetscObjectGetReference — https://petsc.org/release/manualpages/Sys/PetscObjectGetReference.html

Source code at petsc4py/PETSc/Object.pyx:298 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L298

Return type: int — https://docs.python.org/3/builtins/functions.html#int

getTabLevel() ✨

Return the PETSc object tab level, bestie.

Not collective.

See also: setTabLevel, incrementTabLevel, PetscObjectGetTabLevel — https://petsc.org/release/manualpages/Sys/PetscObjectGetTabLevel.html

Source code at petsc4py/PETSc/Object.pyx:518 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L518

Return type: None — https://docs.python.org/3/builtins/constants.html#None

getType() 🎀

Return the object type name. That's the vibe check on what kind of object you got.

Not collective.

See also: PetscObjectGetType — https://petsc.org/release/manualpages/Sys/PetscObjectGetType.html

Source code at petsc4py/PETSc/Object.pyx:94 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L94

Return type: str — https://docs.python.org/3/builtins/stdtypes.html#str

incRef() 🔥

Increment the object reference count. Like hitting follow — now one more person's got it.

Logically collective.

See also: getRefCount, PetscObjectReference — https://petsc.org/release/manualpages/Sys/PetscObjectReference.html

Source code at petsc4py/PETSc/Object.pyx:372 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L372

Return type: int — https://docs.python.org/3/builtins/functions.html#int

incrementTabLevel(tab, parent=None) 🦋

Increment the PETSc object tab level. Yes, the tab level, lowkey important for pretty logs.

Logically collective.

See also: setTabLevel, getTabLevel, PetscObjectIncrementTabLevel — https://petsc.org/release/manualpages/Sys/PetscObjectIncrementTabLevel.html

Source code at petsc4py/PETSc/Object.pyx:491 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L491

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

query(name) 🌸

Query for the PETSc object associated with a key string. Sliding into the object's lil key→object dict, yk?

Not collective.

See also: compose, PetscObjectQuery — https://petsc.org/release/manualpages/Sys/PetscObjectQuery.html

Source code at petsc4py/PETSc/Object.pyx:352 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L352

Parameters

Return type: Object — <#petsc4py.PETSc.Object>

setAttr(name, attr) 💅

Set an the attribute associated with a given name. (Yes, the original really says "Set an the" — iconic, no notes, we keep it fr fr.)

Not collective.

See also: getAttr, getDict

Source code at petsc4py/PETSc/Object.pyx:422 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L422

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

setFromOptions() 👑

Configure the object from the options database. The main character move: let the options db decide your settings.

Collective.

Classes that don't implement setFromOptions use this method instead, and that one, in turn, calls PetscObjectSetFromOptions — https://petsc.org/release/manualpages/Sys/PetscObjectSetFromOptions.html.

See also: Working with PETSc options — <#petsc-options>, PetscObjectSetFromOptions — https://petsc.org/release/manualpages/Sys/PetscObjectSetFromOptions.html

Source code at petsc4py/PETSc/Object.pyx:152 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L152

Return type: None — https://docs.python.org/3/builtins/constants.html#None

setName(name) 🫶

Associate a name to the object. Give it a lil identity moment.

Not collective.

See also: PetscObjectSetName — https://petsc.org/release/manualpages/Sys/PetscObjectSetName.html

Source code at petsc4py/PETSc/Object.pyx:256 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L256

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

setOptionsHandler(handler) 💜

Set the callback for processing extra options. Like adding your own lil bonus rounds to the options party.

Logically collective.

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: Working with PETSc options — <#petsc-options>, Mat.setFromOptions — <#petsc4py.PETSc.Mat.setFromOptions>, KSP.setFromOptions — <#petsc4py.PETSc.KSP.setFromOptions>, PetscObjectAddOptionsHandler — https://petsc.org/release/manualpages/Sys/PetscObjectAddOptionsHandler.html

Source code at petsc4py/PETSc/Object.pyx:190 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L190

setOptionsPrefix(prefix) ⭐

Set the prefix used for searching for options in the database. It's giving "namespace but make it options".

Logically collective.

See also: Working with PETSc options — <#petsc-options>, getOptionsPrefix, PetscObjectSetOptionsPrefix — https://petsc.org/release/manualpages/Sys/PetscObjectSetOptionsPrefix.html

Source code at petsc4py/PETSc/Object.pyx:110 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L110

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

setTabLevel(level) 🌈

Set the PETSc object tab level. Yes bestie, you can just decide the tab level now.

Logically collective.

See also: incrementTabLevel, getTabLevel, PetscObjectSetTabLevel — https://petsc.org/release/manualpages/Sys/PetscObjectSetTabLevel.html

Source code at petsc4py/PETSc/Object.pyx:505 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L505

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

stateGet() 🍓

Return the PETSc object state — the lil counter that tells you if anything changed.

Not collective.

See also: stateSet, stateIncrease, PetscObjectStateGet — https://petsc.org/release/manualpages/Sys/PetscObjectStateGet.html

Source code at petsc4py/PETSc/Object.pyx:462 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Object.pyx#L462

Return type: int — https://docs.python.org/3/builtins/functions.html#int

stateIncrease() ⭐

Increment the PETSc object state.

  • Logically collective. 💫 (everyone in the gang shows up for this one, no stragglers)
  • See also: stateGet, stateSet, PetscObjectStateIncrease
  • Source code at petsc4py/PETSc/Object.pyx:450 📍
  • Return type: None

✨ stateSet(state) ✨

Okay so this one does the thing the last one does, but like… the other direction. It sets the PETSc object state. 🎀

Logically collective. (yes babes, we're all doing it together, as a treat)

  • See also: stateIncrease, stateGet, PetscObjectStateSet
  • Source code at petsc4py/PETSc/Object.pyx:476 📍

Parameters

  • state (int) — the shiny new state, bestie 💜

Return type: None

💖 view(viewer=None) 💖

Display the object. ✨ It's giving show-and-tell, it's giving main character energy, it's giving look at my object.

Collective. — the whole squad participates 🫶

Parameters

  • viewer (Viewer | None) — a Viewer instance, or None if you want the default viewer to handle it (the "I don't wanna pick, you pick" option, and honestly? valid 💅)

Return type: None

  • See also: PetscObjectView
  • Source code at petsc4py/PETSc/Object.pyx:62 📍

🌸 viewFromOptions(name, objpre=None) 🌸

View the object via command line options. 🔥 no cap, this is the "let the terminal decide for me" pipeline and it absolutely ate.

Collective. — same deal, everyone's in 🦋

Parameters

  • name (str) — The command line option. 👑 this is your golden ticket
  • objpre (Object | None) — Optional object that provides prefix. like, a little helper object that hands over the prefix. Optional though! No pressure 🎀

Return type: None

  • See also: the Working with PETSc options section, PetscObjectViewFromOptions
  • Source code at petsc4py/PETSc/Object.pyx:167 📍

🎀 Attributes Documentation 🎀

Bestie. Bestie bestie bestie. The attributes. The little properties that live on the object and just exist there, minding their own business. Obsessed tbh 💖

  • classid — The class identifier. 🆔 (source code at petsc4py/PETSc/Object.pyx:563)
  • comm — The object communicator. 📡 (source code at petsc4py/PETSc/Object.pyx:550)
  • fortran — Fortran handle. 🏰 (source code at petsc4py/PETSc/Object.pyx:593)
  • handle — Handle for ctypes support. 🛠️ (source code at petsc4py/PETSc/Object.pyx:585)
  • id — The object identifier. 🔖 (source code at petsc4py/PETSc/Object.pyx:568)
  • klass — The class name. ✨ (source code at petsc4py/PETSc/Object.pyx:573) — yes it's spelled klass, and no, we do not question it 💅
  • name — The object name. 🏷️ (source code at petsc4py/PETSc/Object.pyx:555)
  • prefix — Options prefix. 🎀 (source code at petsc4py/PETSc/Object.pyx:542)
  • refcount — Reference count. 🔢 (source code at petsc4py/PETSc/Object.pyx:578)
  • type — Object type. 🌟 (source code at petsc4py/PETSc/Object.pyx:534)

__init__()

classmethod __new__(*args, **kwargs)

🦋 petsc4py.PETSc.Options 🦋

class petsc4py.PETSc.Options

Bases: object

The options database object. 🎊

A dictionary-like object to store and operate with command line options. Fr fr. It's a dict but make it PETSc. It's a dict but it's ✨ethereal✨. You get the vibe, iykyk 🔥

Parameters

  • prefix (str, optional) — Optional string to prepend to all the options. 🫶 Like a little name tag for every single option you ever set. Cute. Iconic.

Examples

Create an option database and operate with it. 🍓

>>> from petsc4py import PETSc
>>> opts = PETSc.Options()
>>> opts['a'] = 1 # insert the command-line option '-a 1'
>>> if 'a' in opts: # if the option is present
>>>     val = opts['a'] # return the option value as 'str'
>>> a_int = opts.getInt('a') # return the option value as 'int'
>>> a_bool = opts.getBool('a') # return the option value as 'bool'

Read command line and use default values. 💜

>>> from petsc4py import PETSc
>>> opts = PETSc.Options()
>>> b_float = opts.getReal('b', 1) # return the value or 1.0 if not present

Read command line options prepended with a prefix. 🧚

>>> from petsc4py import PETSc
>>> opts = PETSc.Options('prefix_')
>>> opts.getString('b', 'some_default_string') # read -prefix_b xxx

See also: the Working with PETSc options section 💖

Methods Summary ✨

okay bestie, here's the whole squad of methods for the Options class — every single one, no skips, no cap 💅

  • clear() — Clear an options database.
  • create() — Create an options database.
  • delValue(name) — Delete an option from the database.
  • destroy() — Destroy an options database.
  • getAll() — Return all the options and their values.
  • getBool(name[, default]) — Return the boolean value associated with the option.
  • getBoolArray(name[, default]) — Return the boolean values associated with the option.
  • getInt(name[, default]) — Return the integer value associated with the option.
  • getIntArray(name[, default]) — Return the integer array associated with the option.
  • getReal(name[, default]) — Return the real value associated with the option.
  • getRealArray(name[, default]) — Return the real array associated with the option.
  • getScalar(name[, default]) — Return the scalar value associated with the option.
  • getScalarArray(name[, default]) — Return the scalar array associated with the option.
  • getString(name[, default]) — Return the string associated with the option.
  • hasName(name) — Return the boolean indicating if the option is in the database.
  • insertString(string) — Insert a string in the options database.
  • prefixPop() — Pop a prefix for the options database.
  • prefixPush(prefix) — Push a prefix for the options database.
  • setValue(name, value) — Set a value for an option.
  • used(name) — Return the boolean indicating if the option was queried from the database.
  • view([viewer]) — View the options database.

Attributes Summary 🦋

just one attribute, but she's iconic:

  • prefix — Prefix for options.

Methods Documentation 💅

now the deep dives, fr fr. every detail is here, no cap.

✨ clear() ✨

Clear an options database.

Source code at petsc4py/PETSc/Options.pyx:91 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Options.pyx#L91

Return type: Self — https://docs.python.org/3/library/typing.html#typing.Self

✨ create() ✨

Create an options database.

Source code at petsc4py/PETSc/Options.pyx:79 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Options.pyx#L79

Return type: Self — https://docs.python.org/3/library/typing.html#typing.Self

✨ delValue(name) ✨

Delete an option from the database.

Logically collective.

See also: setValue, PetscOptionsClearValue — https://petsc.org/release/manualpages/Sys/PetscOptionsClearValue.html

Source code at petsc4py/PETSc/Options.pyx:203 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Options.pyx#L203

Parameters:

Return type: None — https://docs.python.org/3/builtins/constants.html#None

✨ destroy() ✨

Destroy an options database.

Source code at petsc4py/PETSc/Options.pyx:85 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Options.pyx#L85

Return type: Self — https://docs.python.org/3/library/typing.html#typing.Self

✨ getAll() ✨

Return all the options and their values.

Not collective.

See also: PetscOptionsGetAll — https://petsc.org/release/manualpages/Sys/PetscOptionsGetAll.html

Source code at petsc4py/PETSc/Options.pyx:422 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Options.pyx#L422

Return type: dict[str, str] — dict: https://docs.python.org/3/builtins/stdtypes.html#dict, str: https://docs.python.org/3/builtins/stdtypes.html#str

getBool(name, default=None)

Hands you back the boolean value that's chillin' in the options database under that name. Bestie, it's right there. 💖

Not collective. (no group chat needed, this is a solo activity 🫶)

Parameters:

Return type: bool (https://docs.python.org/3/builtins/functions.html#bool)

See also: getBoolArray, PetscOptionsGetBool (https://petsc.org/release/manualpages/Sys/PetscOptionsGetBool.html)

Source code at petsc4py/PETSc/Options.pyx:226 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Options.pyx#L226)

getBoolArray(name, default=None)

Same energy as getBool but it's giving a whole array of booleans. Not one (1) boolean — a collection of them. Slay. ✨

Not collective.

Parameters:

Return type: ArrayBool (#petsc4py.typing.ArrayBool)

See also: getBool, PetscOptionsGetBoolArray (https://petsc.org/release/manualpages/Sys/PetscOptionsGetBoolArray.html)

Source code at petsc4py/PETSc/Options.pyx:246 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Options.pyx#L246)

getInt(name, default=None)

Gives you the integer value tied to that option name. Wholesome, numeric, iconic. 👑

Not collective.

Parameters:

Return type: int (https://docs.python.org/3/builtins/functions.html#int)

See also: getIntArray, PetscOptionsGetInt (https://petsc.org/release/manualpages/Sys/PetscOptionsGetInt.html)

Source code at petsc4py/PETSc/Options.pyx:266 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Options.pyx#L266)

getIntArray(name, default=None)

The integer array version. Yes bestie, plural numbers. We love a data structure with main character energy. 💅

Not collective.

Parameters:

Return type: ArrayInt (#petsc4py.typing.ArrayInt)

See also: getInt, PetscOptionsGetIntArray (https://petsc.org/release/manualpages/Sys/PetscOptionsGetIntArray.html)

Source code at petsc4py/PETSc/Options.pyx:286 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Options.pyx#L286)

getReal(name, default=None)

Returns the real value for that option. Floating point, but make it fashion. 🌸

Not collective.

Parameters:

Return type: float (https://docs.python.org/3/builtins/functions.html#float)

See also: getRealArray, PetscOptionsGetReal (https://petsc.org/release/manualpages/Sys/PetscOptionsGetReal.html)

Source code at petsc4py/PETSc/Options.pyx:306 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Options.pyx#L306)

getRealArray(name, default=None)

The real array counterpart. A lil squad of floats. So real of them. 🦋

Not collective.

Parameters:

Return type: ArrayReal (#petsc4py.typing.ArrayReal)

See also: getReal, PetscOptionsGetRealArray (https://petsc.org/release/manualpages/Sys/PetscOptionsGetRealArray.html)

Source code at petsc4py/PETSc/Options.pyx:326 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Options.pyx#L326)

getScalar(name, default=None)

Grabs the scalar value for the option. Scalar as in the PETSc sense, so depending on how things are configured it could be real or complex — the docs just call it a scalar and honestly, respect the mystery. 🔮

Not collective.

Parameters:

Return type: Scalar (#petsc4py.typing.Scalar)

See also: getScalarArray, PetscOptionsGetScalar (https://petsc.org/release/manualpages/Sys/PetscOptionsGetScalar.html)

Source code at petsc4py/PETSc/Options.pyx:346 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Options.pyx#L346)

getScalarArray(name, default=None)

The scalar array. Many scalars. Immaculate group-chat-of-numbers behavior. 🫶

Not collective.

Parameters:

Return type: ArrayScalar (#petsc4py.typing.ArrayScalar)

See also: getScalar, PetscOptionsGetScalarArray (https://petsc.org/release/manualpages/Sys/PetscOptionsGetScalarArray.html)

Source code at petsc4py/PETSc/Options.pyx:366 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Options.pyx#L366)

getString(name, default=None)

Returns the string associated with the option. Text! Words! The absolute moment. 🎀

Not collective.

Parameters:

Return type: str (https://docs.python.org/3/builtins/stdtypes.html#str)

See also: PetscOptionsGetString (https://petsc.org/release/manualpages/Sys/PetscOptionsGetString.html)

Source code at petsc4py/PETSc/Options.pyx:386 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Options.pyx#L386)

hasName(name)

Returns the boolean that tells you whether the option is actually in the database or not. A vibe check for your option names, fr fr. 🌈

Source code at petsc4py/PETSc/Options.pyx:144 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Options.pyx#L144)

Parameters:

Return type: bool (https://docs.python.org/3/builtins/functions.html#bool)

insertString(string)

Puts a string into the options database. Like sliding a note into the group chat, except the group chat is PETSc. 💌

Logically collective. (so everybody's on the same page about it, bestie)

Heads up: the original page cuts off right here mid-entry. More of this method is coming in the next part, so don't close the tab. 😭

See also:

  • PetscOptionsInsertString — petsc.org/release/manualpages/Sys/PetscOptionsInsertString.html

Source code at petsc4py/PETSc/Options.pyx:408 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Options.pyx#L408

Parameters

  • string (str)

Return type

None

prefixPop() 🫧

Pops a prefix off the options database. Like undoing your last layer of aesthetic, bestie. 💅

Logically collective.

See also:

  • prefixPush
  • PetscOptionsPrefixPop — petsc.org/release/manualpages/Sys/PetscOptionsPrefixPop.html

Source code at petsc4py/PETSc/Options.pyx:131 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Options.pyx#L131

Return type

None

prefixPush(prefix) 🎀

Pushes a prefix onto the options database. Stack it up, queen. 👑

Logically collective.

See also:

  • prefixPop
  • PetscOptionsPrefixPush — petsc.org/release/manualpages/Sys/PetscOptionsPrefixPush.html

Source code at petsc4py/PETSc/Options.pyx:116 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Options.pyx#L116

Parameters

  • prefix (str | Options | Object | None)

Return type

None

setValue(name, value) ✨

Sets a value for an option. You're literally assigning a personality trait to an option rn. 🦋

Logically collective.

Parameters

  • name (str) — The string identifying the option.
  • value (bool | int | float | Scalar | Sequence[bool] | Sequence[int] | Sequence[float] | Sequence[Scalar] | str) — The option value.

Return type

None

See also:

  • delValue
  • PetscOptionsSetValue — petsc.org/release/manualpages/Sys/PetscOptionsSetValue.html

Source code at petsc4py/PETSc/Options.pyx:161 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Options.pyx#L161

used(name) 🍓

Returns the boolean telling you whether the option was ever queried from the database. Like, did anyone actually ask about it, or is it just sitting there unread in the group chat? 😭

Source code at petsc4py/PETSc/Options.pyx:153 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Options.pyx#L153

Parameters

  • name (str)

Return type

bool

view(viewer=None) 🔥

Views the options database. Main character moment for your whole config. 👑

Collective.

Parameters

  • viewer (Viewer | None) — A Viewer instance, or None for the default viewer.

Return type

None

See also:

  • Viewer
  • PetscOptionsView — petsc.org/release/manualpages/Sys/PetscOptionsView.html

Source code at petsc4py/PETSc/Options.pyx:97 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Options.pyx#L97

Attributes Documentation 📝

prefix

Prefix for options.

Source code at petsc4py/PETSc/Options.pyx:67 — gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Options.pyx#L67

__init__()

classmethod __new__(*args, **kwargs)

petsc4py.PETSc.PC 🧚💖

class petsc4py.PETSc.PC

Bases: Object

Preconditioners. Yes bestie, the thing that makes your solver actually converge instead of spiralling. 🌀

PC is described in the PETSc manual: petsc.org/release/manual/ksp.html#sec-ksppc Calling the PC with a vector as an argument will apply the preconditioner, exactly like the example below shows. No cap. 💅

Examples ✨

>>> from petsc4py import PETSc
>>> v = PETSc.Vec().createWithArray([1, 2])
>>> m = PETSc.Mat().createDense(2, array=[[1, 0], [0, 1]])
>>> pc = PETSc.PC().create()
>>> pc.setOperators(m)
>>> u = pc(v) # u is created internally
>>> pc.apply(v, u) # u can also be passed as second argument

See also:

  • PC — petsc.org/release/manualpages/PC/PC.html
  • ASMType — The ASM subtype.
  • CompositeType — The composite type.
  • DeflationSpaceType — The deflation space subtype.
  • FailedReason — The reason the PC has failed.
  • FieldSplitSchurFactType — The field split Schur factorization type.
  • FieldSplitSchurPreType — The field split Schur subtype.
  • GAMGType — The GAMG subtype.
  • GASMType — The GASM subtype.
  • HPDDMCoarseCorrectionType — The HPDDM coarse correction type.
  • MGCycleType — The MG cycle type.
  • MGType — The MG subtype.
  • PatchConstructType — The patch construction type.
  • Side — The manner in which the preconditioner is applied.
  • Type — The preconditioner method.

✨ petsc4py.PETSc.PC.ASMType ✨

class petsc4py.PETSc.PC.ASMType

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

The ASM subtype. 🫶 that's it, that's the whole vibe.

🌸 Attributes Summary 🌸

💅 Attributes Documentation 💅

__init__()

__init__()

classmethod __new__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

🦋 petsc4py.PETSc.PC.CompositeType 🦋

class petsc4py.PETSc.PC.CompositeType

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

The composite type. 👑

okay so before we even get to the new classes, this one is still out here serving a whole tray of constants, and honestly? we're gonna show them all their flowers 💐

✨ Attributes Summary ✨

every single one of these is a constant of type int — and yes, the type links out to the Python builtins docs at https://docs.python.org/3/builtins/functions.html#int, absolutely no cap:

🌸 Attributes Documentation 🌸

now the same five, but with their whole identity laid out, type annotation and all:

and then the two lil' darlings that every class in here carries around:

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

that's it, that's the whole thing bestie, the docs are giving minimal and we respect it 🎀

👑 petsc4py.PETSc.PC.DeflationSpaceType 👑

class petsc4py.PETSc.PC.DeflationSpaceType

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

the deflation space subtype. that's the whole vibe of this class, and she knows it 💅

✨ Attributes Summary ✨

nine constants, all of them type int, all of them linking to https://docs.python.org/3/builtins/functions.html#int, presented in the cutest possible alphabetical order:

🦋 Attributes Documentation 🦋

and the duo again, because every class in this family has them:

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

💜 petsc4py.PETSc.PC.FailedReason 💜

class petsc4py.PETSc.PC.FailedReason

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

the reason the preconditioner has failed.

ngl that one line is lowkey the most dramatic description in this entire section — like, she doesn't explain, she just announces 💀 and the docs literally stop right there, so we're gonna sit with that for a sec because the rest of this class is coming up in the next part…

✨ Attributes Summary ✨

okay so this class is just carrying a whole lil squad of int constants, no cap. Here's the full roster 💅

🎀 Attributes Documentation 🎀

Every single one of them, documented to the letter. Yes bestie, they all say the same shape of thing, that's just how the docs vibe is here:

and then the dunders, because of course there are dunders, it wouldn't be Python without them 🙈

__init__()

classmethod __new__(*args, **kwargs)

🦋 petsc4py.PETSc.PC.FieldSplitSchurFactType

class petsc4py.PETSc.PC.FieldSplitSchurFactType

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

The field split Schur factorization type. yeah that's the whole description and honestly? iconic of it.

⭐ Attributes Summary ⭐

four constants, all int, all here:

🌈 Attributes Documentation 🌈

and the mandatory dunder moment 💅

__init__()

classmethod __new__(*args, **kwargs)

🌸 petsc4py.PETSc.PC.FieldSplitSchurPreType

class petsc4py.PETSc.PC.FieldSplitSchurPreType

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

The field split Schur subtype.

  • A11 — Constant A11 of type int (yes bestie, the builtin int, living its best life)
  • FULL — Constant FULL of type int
  • SELF — Constant SELF of type int
  • SELFP — Constant SELFP of type int
  • USER — Constant USER of type int

✨ Attributes Documentation ✨

A11: int = A11 — Constant A11 of type int. It's giving builtin int energy 💅

FULL: int = FULL — Constant FULL of type int.

SELF: int = SELF — Constant SELF of type int.

SELFP: int = SELFP — Constant SELFP of type int.

USER: int = USER — Constant USER of type int.

__init__()

classmethod __new__(*args, **kwargs)

🦋 class petsc4py.PETSc.PC.GAMGType

Bases: object (the builtin object, the origin of all things 💜)

The GAMG subtype. Say it with me: GAMG.

Attributes Summary

  • AGG — Object AGG of type str
  • CLASSICAL — Object CLASSICAL of type str
  • GEO — Object GEO of type str

Attributes Documentation

AGG: str = AGG — Object AGG of type str.

CLASSICAL: str = CLASSICAL — Object CLASSICAL of type str.

GEO: str = GEO — Object GEO of type str.

__init__()

classmethod __new__(*args, **kwargs)

🎀 class petsc4py.PETSc.PC.GASMType

Bases: object

The GASM subtype. subtype era, we love to see it ✨

Attributes Summary

  • BASIC — Constant BASIC of type int
  • INTERPOLATE — Constant INTERPOLATE of type int
  • NONE — Constant NONE of type int
  • RESTRICT — Constant RESTRICT of type int

Attributes Documentation

BASIC: int = BASIC — Constant BASIC of type int.

INTERPOLATE: int = INTERPOLATE — Constant INTERPOLATE of type int.

NONE: int = NONE — Constant NONE of type int.

RESTRICT: int = RESTRICT — Constant RESTRICT of type int.

__init__()

classmethod __new__(*args, **kwargs)

💜 class petsc4py.PETSc.PC.HPDDMCoarseCorrectionType

Bases: object

The HPDDM coarse correction type. the coarse correction of it all 😭 iconic

✨ Attributes Summary ✨ (yes bestie we're still here, mid-table, hold on)

Attributes Documentation

Constant ADDITIVE of type int (https://docs.python.org/3/builtins/functions.html#int). it's giving "a number, and that number is called ADDITIVE" 💖

Constant BALANCED of type int (https://docs.python.org/3/builtins/functions.html#int). icon behaviour, honestly 🌸

Constant DEFLATED of type int (https://docs.python.org/3/builtins/functions.html#int). no cap 🦋

Constant NONE of type int (https://docs.python.org/3/builtins/functions.html#int). the classic "nothing to see here" but make it an int 😭

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

petsc4py.PETSc.PC.MGCycleType 👑

class petsc4py.PETSc.PC.MGCycleType

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

The MG cycle type. that's it, that's the whole vibe check 🌈

Attributes Summary

Attributes Documentation

Constant V of type int (https://docs.python.org/3/builtins/functions.html#int). yes bestie, the letter is literally the value ⭐

Constant W of type int (https://docs.python.org/3/builtins/functions.html#int). two letters, two constants, zero drama 🧚

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

petsc4py.PETSc.PC.MGType 👑

class petsc4py.PETSc.PC.MGType

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

The MG subtype. lowkey the sibling of the cycle type, highkey its own whole thing 🔥

Attributes Summary

Attributes Documentation

Constant ADDITIVE of type int (https://docs.python.org/3/builtins/functions.html#int). it's giving "add it up" ✨

Constant FULL of type int (https://docs.python.org/3/builtins/functions.html#int). the whole thing, no crumbs left 💅

Constant KASKADE of type int (https://docs.python.org/3/builtins/functions.html#int). yes it's spelled exactly like that, do not "fix" it, i'm begging 🙈

Constant MULTIPLICATIVE of type int (https://docs.python.org/3/builtins/functions.html#int). the main character of the arithmetic operations ngl 👑

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

petsc4py.PETSc.PC.PatchConstructType 👑

class petsc4py.PETSc.PC.PatchConstructType

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

The patch construction type. patch girlie behaviour, we love her 🧵💜

Attributes Summary

Attributes Documentation

Constant PARDECOMP of type int (https://docs.python.org/3/builtins/functions.html#int). fr fr, it's just that 🫶

Okay continuing the constant crew, same energy, no skips: 👑

  • PYTHON : int = PYTHON — a constant, type int 💅
  • STAR : int = STAR — constant, type int ✨
  • USER : int = USER — constant, type int 🫶
  • VANKA : int = VANKA — constant, type int 🌸

And the lil methods that come with them:

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

Periodt. Those four constants eat every time, no notes. 💖

petsc4py.PETSc.PC.Side 🦋

class petsc4py.PETSc.PC.Side

Bases: object

okay so bestie, this one is literally the whole vibe of the manner in which the preconditioner is applied. That's the description, verbatim, that's what it is. No cap.

✨ Attributes Summary ✨

  • L — Constant L of type int
  • LEFT — Constant LEFT of type int
  • R — Constant R of type int
  • RIGHT — Constant RIGHT of type int
  • S — Constant S of type int
  • SYMMETRIC — Constant SYMMETRIC of type int

That's the full roster, all six of them, every single one is an int. Iconic behaviour honestly. 🌈

📖 Attributes Documentation 📖

  • L : int = L — Constant L of type int 💅
  • LEFT : int = LEFT — Constant LEFT of type int ✨
  • R : int = R — Constant R of type int 🎀
  • RIGHT : int = RIGHT — Constant RIGHT of type int 🫶
  • S : int = S — Constant S of type int 🌸
  • SYMMETRIC : int = SYMMETRIC — Constant SYMMETRIC of type int 👑

Then, as always, the little duo tagging along:

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

Lowkey the __new__ is the one doing the actual heavy lifting while __init__ is just standing there looking pretty. Main character energy fr fr. 💀

petsc4py.PETSc.PC.Type 🔥

class petsc4py.PETSc.PC.Type

Bases: object

And this one is the the preconditioner method. That's the whole description and honestly? It understood the assignment. ✨

okay so we're still deep in the Attributes Summary of PETSc.PC, and bestie... it is giving alphabet wall. 💀 Every single entry here is an object of type str — the Python builtin str, docs sitting at https://docs.python.org/3/builtins/stdtypes.html#str — so I'm writing them all out in order, exactly as they appear, one bullet each, no skipping, no summarising, no "etc." shenanigans. Periodt. ✨

like, we are nowhere near the end of this list and I am already out of breath, bestie 😭 every one of them a str, every one of them pointing at the exact same type page — consistency queen, honestly 👑

ok so quick lil vibe check before we keep scrolling — every single one of these is just an honest-to-god str, like the plainest stringy string that ever strung. Python's own docs for it live at https://docs.python.org/3/builtins/stdtypes.html#str and ngl you will not need to go there, bestie, they're all the same vibe. 💅

  • LSC — object of type str, same docs link as above ✨
  • LU — object of type str, same docs link as above ✨
  • MAT — object of type str, same docs link as above ✨
  • MG — object of type str, same docs link as above ✨
  • ML — object of type str, same docs link as above ✨
  • NN — object of type str, same docs link as above ✨
  • NONE — object of type str, same docs link as above ✨
  • PARMS — object of type str, same docs link as above ✨
  • PATCH — object of type str, same docs link as above ✨
  • PBJACOBI — object of type str, same docs link as above ✨
  • PFMG — object of type str, same docs link as above ✨
  • PYTHON — object of type str, same docs link as above ✨
  • QR — object of type str, same docs link as above ✨
  • REDISTRIBUTE — object of type str, same docs link as above ✨
  • REDUNDANT — object of type str, same docs link as above ✨
  • ROWSCALINGVIENNACL — object of type str, same docs link as above ✨
  • SAVIENNACL — object of type str, same docs link as above ✨
  • SHELL — object of type str, same docs link as above ✨
  • SOR — object of type str, same docs link as above ✨
  • SPAI — object of type str, same docs link as above ✨
  • SVD — object of type str, same docs link as above ✨
  • SYSPFMG — object of type str, same docs link as above ✨
  • TELESCOPE — object of type str, same docs link as above ✨

and the way that this is literally just a long roster of strings, no weird types, no cursed custom classes, nothing to be scared of?? it's giving "controlled, organised, alphabetically-adjacent catalog of constants" and we love that for us. 🎀 every one of them is a str, every one of them points at that exact same stdtypes page like they all share one brain cell, and honestly? iconic. 👑

if you're grepping through these later, remember: not a single one of them is an int, a tuple, a mystery object from the shadow realm, or anything spicy. just str. no cap. 💖

  • TFS 🦋 — object of type str, value TFS. Same type link as literally every other entry on this page: https://docs.python.org/3/builtins/stdtypes.html#str.
  • VPBJACOBI 🫶 — object of type str, value VPBJACOBI. Also carries that same str link. and yes bestie, the table says VPBJACOBI — that is not the same thing as PBJACOBI, which also shows up later on this page, so do not go merging them in your head 🙈 they are two whole separate entries.

✨ Attributes Documentation ✨

okay so this entire section is a vibe. Every single thing listed here is an attribute that's a plain old str, and Sphinx pastes the exact same type link onto all of them: https://docs.python.org/3/builtins/stdtypes.html#str — that's just Python's own str docs, it is not that deep, no cap. 💅

And the description for each one? "Object NAME of type str". that's it. that's the whole description. The name is baked in as the value, so like, ASM equals the string ASM. every. single. time. Same energy, forty-one times in a row. Periodt. 💖

  • ASM 💖 — str = ASM. An object of type str whose value is the string ASM. The name is the value, that's the entire bit.
  • BDDC 🎀 — str = BDDC. Object of type str, value BDDC. Say it with your chest.
  • BJACOBI ⭐ — str = BJACOBI. Object of type str, value BJACOBI.
  • CHOLESKY 🌸 — str = CHOLESKY. Object of type str, value CHOLESKY.
  • CHOWILUVIENNACL 🔥 — str = CHOWILUVIENNACL. Object of type str, value CHOWILUVIENNACL. yes the whole mouthful, spelled exactly like that, don't you dare abbreviate it.
  • COMPOSITE 🧚 — str = COMPOSITE. Object of type str, value COMPOSITE.
  • CP 💀 — str = CP. Object of type str, value CP. two letters, maximum chaos.
  • DEFLATION 🌈 — str = DEFLATION. Object of type str, value DEFLATION.
  • EISENSTAT 👑 — str = EISENSTAT. Object of type str, value EISENSTAT. main character name energy fr fr.
  • EXOTIC 🦋 — str = EXOTIC. Object of type str, value EXOTIC. it's giving exactly what it says.
  • FIELDSPLIT ✨ — str = FIELDSPLIT. Object of type str, value FIELDSPLIT.
  • GALERKIN 💜 — str = GALERKIN. Object of type str, value GALERKIN.
  • GAMG 🍓 — str = GAMG. Object of type str, value GAMG.
  • GASM 🎀 — str = GASM. Object of type str, value GASM. one letter away from its sibling ASM up there and it knows it.
  • H2OPUS 💖 — str = H2OPUS. Object of type str, value H2OPUS. the 2 is load-bearing, keep it.
  • HMG ⭐ — str = HMG. Object of type str, value HMG.
  • HPDDM 🌸 — str = HPDDM. Object of type str, value HPDDM.
  • HYPRE 🔥 — str = HYPRE. Object of type str, value HYPRE.
  • ICC 🫶 — str = ICC. Object of type str, value ICC.
  • ILU 🧚 — str = ILU. Object of type str, value ILU.
  • JACOBI 💅 — str = JACOBI. Object of type str, value JACOBI.
  • KACZMARZ 🌈 — str = KACZMARZ. Object of type str, value KACZMARZ.
  • KSP 💀 — str = KSP. Object of type str, value KSP. yes, the same letters as a whole other PETSc concept, and no, nothing here explains that, it's just a string bestie 💜.
  • LMVM 👑 — str = LMVM. Object of type str, value LMVM.
  • LSC 🦋 — str = LSC. Object of type str, value LSC.
  • LU ✨ — str = LU. Object of type str, value LU.
  • MAT 🎀 — str = MAT. Object of type str, value MAT.
  • MG 🍓 — str = MG. Object of type str, value MG.
  • ML ⭐ — str = ML. Object of type str, value ML.
  • NN 🌸 — str = NN. Object of type str, value NN.
  • NONE 🔥 — str = NONE. Object of type str, value NONE. and no, it is not Python's None 🙈 it's the four-letter string "NONE". do not mix them up, I am begging.
  • PARMS 🫶 — str = PARMS. Object of type str, value PARMS. spelled PARMS, not PARAMS, look at it twice.
  • PATCH 🧚 — str = PATCH. Object of type str, value PATCH.
  • PBJACOBI 💅 — str = PBJACOBI. Object of type str, value PBJACOBI. yep, the P-having sibling of VPBJACOBI from the table earlier — different entry, different string, iykyk.
  • PFMG 🌈 — str = PFMG. Object of type str, value PFMG.
  • PYTHON 💀 — str = PYTHON. Object of type str, value PYTHON.
  • QR 👑 — str = QR. Object of type str, value QR.
  • REDISTRIBUTE 🦋 — str = REDISTRIBUTE. Object of type str, value REDISTRIBUTE.
  • REDUNDANT ✨ — str = REDUNDANT. Object of type str, value REDUNDANT.
  • ROWSCALINGVIENNACL 💜 — str = ROWSCALINGVIENNACL. Object of type str, value ROWSCALINGVIENNACL. whole entire word, no spaces, no mercy.
  • SAVIENNACL 🍓 — str = SAVIENNACL. Object of type str, value SAVIENNACL.

and that's the run, bestie — every one of them an object of type str, every one of them happily equal to its own name, every one of them pointing back at the same Python docs link. obsessed, honestly. 💅

…and we're still rolling through the constants, bestie, so hold my hand and let's go 🫶 Every single one of these is a str (https://docs.python.org/3/builtins/stdtypes.html#str) — same type, different name, zero drama. Here's the whole lineup, no skips, no cap 💅

and then, the actual methods — because a class can't just be vibes and string constants forever 🙈

  • __init__() — the page hands you __init__() and literally nothing else. No blurb, no extra signature bits, just that. That's the entry, bestie 💀
  • classmethod __new__(*args, **kwargs) — and this one's a classmethod that takes *args and **kwargs. Yup, that's the entire flex: classmethod, *args, **kwargs. Write it down exactly like that when you need it 📝
  • addCompositePCType(pc_type) — bestie, this drops a PC of the given pc_type into the composite PC. building the squad, one preconditioner at a time 🫶
  • appendOptionsPrefix(prefix) — appends to the prefix that every single PC option hangs off of. ✨
  • apply(x, y) — apply the PC to a vector. that's it, that's the whole vibe 💅
  • applySymmetricLeft(x, y) — apply the left part of a symmetric PC to a vector. 🎀
  • applySymmetricRight(x, y) — and this one applies the right part of a symmetric PC to a vector. matching set fr fr 🦋
  • applyTranspose(x, y) — apply the transpose of the PC to a vector. not me flipping the whole thing 😭
  • create([comm]) — spin up an empty PC. optional comm, zero drama, blank slate energy 💖
  • createPython([context, comm]) — create a preconditioner of Python type. optional context and comm. yes she's custom, yes she serves 👑
  • destroy() — destroy the PC that was created with create. it's giving cleanup era 🧹
  • getASMSubKSP() — returns the local KSP object for all the blocks on this process. every block got a glow-up 🌈
  • getBJacobiSubKSP() — same energy, different solver: returns the local KSP object for all the blocks on this process. 🔥
  • getCompositePC(n) — hand over component n of the composite PC. unboxing the stack, one layer at a time 🎁
  • getDM() — returns the DM associated with the PC. your data's main character moment 🌟
  • getDeflationCoarseKSP() — returns the coarse problem KSP. lowkey the boss level of deflation 👑
  • getDeflationPC() — returns the additional preconditioner. yes, bonus PC, we love a sequel 💜
  • getFactorMatrix() — returns the factored matrix. the receipts, but factored 🧾
  • getFactorSolverType() — returns the solver package that did the factorization. credit where credit is due, periodt 💅
  • getFailedReason() — returns the reason the PC terminated. the drama report, we need the details 😭
  • getFieldSplitSchurGetSubKSP() — returns the KSP for the Schur complement based splits. schur thing, she's iconic 💖
  • getFieldSplitSubIS(splitname) — returns the IS associated with a given splitname. name it and she'll find it 🔍
  • getFieldSplitSubKSP() — returns the KSP for all the splits. every single one, no skips ✨
  • getHPDDMCoarseCorrectionType() — returns the coarse correction type. 🎀
  • getHPDDMComplexities() — computes the grid and operator complexities. math girlies rise 🦋
  • getHPDDMSTShareSubKSP() — returns true if the KSP in SLEPc ST</> and the subdomain solver is shared. sharing is caring, iykyk 💜
  • getHYPREType() — returns the Type.HYPRE type. hypre hive, stand up 🔥
  • getKSP() — hands you the KSP <#petsc4py.PETSc.KSP> if this PC is a Type.KSP <#petsc4py.PETSc.PC.Type.KSP> 💅
  • getMGCoarseSolve() — the KSP <#petsc4py.PETSc.KSP> that does the solving down on the coarse grid, bestie 🎀
  • getMGInterpolation(level) — the interpolation operator for level, no cap ✨
  • getMGLevels() — how many MG <#petsc4py.PETSc.PC.Type.MG> levels we're running, periodt 🌈
  • getMGRScale(level) — the pointwise scaling for the restriction operator on level, fr fr 💖
  • getMGRestriction(level) — restriction operator for level, here for it 🌸
  • getMGSmoother(level) — the KSP <#petsc4py.PETSc.KSP> that's getting used as a smoother 💅
  • getMGSmootherDown(level) — the KSP <#petsc4py.PETSc.KSP> smoothing before the coarse grid correction ✨
  • getMGSmootherUp(level) — the KSP <#petsc4py.PETSc.KSP> smoothing after the coarse grid correction 🦋
  • getMGType() — tells you the form of multigrid in play 👑
  • getOperators() — the matrices chillin' with a linear system 📚
  • getOptionsPrefix() — the prefix that all the PC options are riding under 🏷️
  • getPatchSubKSP() — the local KSP <#petsc4py.PETSc.KSP> object for every block on this process 💫
  • getPythonContext() — the instance of the class that implements the required Python methods 🐍
  • getPythonType() — the fully qualified Python name of the class the preconditioner is using, iykyk 🌟
  • getType() — the preconditioner type, as requested 🔍
  • getUseAmat() — the flag telling you whether the PC is applied to A or to P 🤔
  • matApply(x, y) — applies the PC to a whole crowd of vectors stored as Mat.Type.DENSE <#petsc4py.PETSc.Mat.Type.DENSE> 🎯
  • matApplyTranspose(x, y) — same energy, but it applies the transpose of the PC to many vectors stored as Mat.Type.DENSE <#petsc4py.PETSc.Mat.Type.DENSE> 🔄
  • reset() — resets the PC, yeeting any allocated vectors and matrices right out 🧹
  • setASMLocalSubdomains(nsd[, is_sub, is_local]) — sets the local subdomains 🏡
  • setASMOverlap(overlap) — sets the overlap between a pair of subdomains 🫂

okay bestie we're still deep in the table, mid-scroll, mid-sliving 💅 nothing's changed, it's still the same big pile of setter methods — we just pick up exactly where the last part stopped. no re-introductions, let's go:

  • setASMSortIndices(dosort) — flips on sorting of the subdomain indices. yes, an actual sort toggle, iconic ✨
  • setASMTotalSubdomains(nsd[, is_sub, is_local]) — sets the subdomains for all the processes. everybody gets one 🌈
  • setASMType(asmtype) — picks the type of restriction and interpolation. this is the flavour knob 🎀
  • setBDDCChangeOfBasisMat(T[, interior]) — hands over a user defined change of basis for the degrees of freedom.
  • setBDDCCoarseningRatio(cratio) — the coarsening ratio used in the multilevel version. multilevel girlies rise 🦋
  • setBDDCDirichletBoundaries(bndr) — sets the IS <#petsc4py.PETSc.IS> that defines the Dirichlet boundaries for the global problem.
  • setBDDCDirichletBoundariesLocal(bndr) — same Dirichlet boundaries, except this one's IS <#petsc4py.PETSc.IS> lives in local ordering.
  • setBDDCDiscreteGradient(G[, order, field, ...]) — sets the discrete gradient. straightforward, no notes 💖
  • setBDDCDivergenceMat(div[, trans, l2l]) — sets the linear operator representing ∫ div(u)•p dx. look at us doing actual math, obsessed 😭
  • setBDDCDofsSplitting(isfields) — sets the index set(s) that define the fields of the global matrix.
  • setBDDCDofsSplittingLocal(isfields) — same deal, index set(s) defining fields, except it's the local subdomain matrix this time.
  • setBDDCLevels(levels) — sets the max number of additional levels allowed. cap it, bestie 👑
  • setBDDCLocalAdjacency(csr) — you get to hand in a custom connectivity graph for the local dofs. bespoke, custom-made, main character energy 🎀
  • setBDDCNeumannBoundaries(bndr) — sets the IS <#petsc4py.PETSc.IS> defining the Neumann boundaries for the global problem.
  • setBDDCNeumannBoundariesLocal(bndr) — Neumann boundaries again, but the IS <#petsc4py.PETSc.IS> is in local ordering.
  • setBDDCPrimalVerticesIS(primv) — sets additional user defined primal vertices.
  • setBDDCPrimalVerticesLocalIS(primv) — also additional user defined primal vertices, same energy, different day 🌸
  • setCompositeType(ctype) — sets the type of composite preconditioner.
  • setCoordinates(coordinates) — sets the coordinates for the nodes on the local process. know where you are fr fr 📍
  • setDM(dm) — sets the DM <#petsc4py.PETSc.DM> that some preconditioners might wanna use.
  • setDeflationCoarseMat(mat) — sets the coarse problem matrix.
  • setDeflationCorrectionFactor(fact) — sets the coarse problem correction factor.
  • setDeflationInitOnly(flg) — flip this and it only performs the initialization. init only, no extra steps, minimal queen 💅
  • setDeflationLevels(levels) — sets the maximum level of

…and that's literally where this part of the page cuts off, mid-sentence, not even done with the row. cliffhanger behaviour 💀 next part picks it right back up.

okay so we're still deep in the PC method list, mid-table, no biggie 💅 quick heads-up: the row right above got its name column clipped and all we can see is the tail end of its description, so:

  • … — deflation nesting. 💀 (that's genuinely all the table gave us, bestie, no cap)

and now, the rest of them, in order, zero skips:

  • setDeflationProjectionNullSpaceMat(mat) — hands the PC its projection null space matrix, <italic>mat</italic> 💖
  • setDeflationReductionFactor(red) — sets the reduction factor for the preconditioner — that's the <italic>red</italic> you pass in ✨
  • setDeflationSpace(W, transpose) — sets the deflation space matrix, <italic>W</italic>, or its (Hermitian) transpose 🌸 that's literally the whole job, pick one
  • setDeflationSpaceToCompute(space_type, size) — sets the deflation space type, using <italic>space_type</italic> and <italic>size</italic> 🦋
  • setFactorLevels(levels) — sets the number of levels of fill, aka <italic>levels</italic>, fill levels not vibes 😌
  • setFactorOrdering([ord_type, nzdiag, reuse]) — sets options for the matrix factorization reordering 🔁 all three args are optional, so you can pass none, some, or all
  • setFactorPivot([zeropivot, inblocks]) — sets options for matrix factorization pivoting, and yeah both args are optional too
  • setFactorSetUpSolverType() — sets up the factorization solver 🛠️ takes no args, it just does the thing
  • setFactorShift([shift_type, amount]) — sets options for shifting diagonal entries of a matrix ✨ optional args, <italic>shift_type</italic> and <italic>amount</italic>
  • setFactorSolverType(solver) — sets the solver package used to perform the factorization 👑
  • setFailedReason(reason) — sets the reason the PC terminated 💀 important lil receipt, fr
  • setFieldSplitFields(bsize, *fields) — sets the elements for the field split — you give it <italic>bsize</italic> plus a varargs pile of <italic>*fields</italic>
  • setFieldSplitIS(*fields) — sets the elements for the field split by IS, which is the <italic>petsc4py.PETSc.IS</italic> situation 🌈 (yep, the IS class from the reference section, iykyk)
  • setFieldSplitSchurFactType(ctype) — sets the type of approximate block factorization 🧚
  • setFieldSplitSchurPreType(ptype[, pre]) — sets from what operator the PC is constructed — <italic>pre</italic> is optional 🫶
  • setFieldSplitType(ctype) — sets the type of composition of a field split preconditioner ⭐
  • setFromOptions() — sets various PC parameters from user options, no args, classic 👑
  • setGAMGLevels(levels) — sets the maximum number of levels 💜
  • setGAMGSmooths(smooths) — sets the number of smoothing steps used on all levels — all of them, every single one ✨
  • setGAMGType(gamgtype) — sets the type of algorithm 🎀
  • setGASMOverlap(overlap) — sets the overlap between a pair of subdomains 🌸
  • setGASMType(gasmtype) — sets the type of restriction and interpolation 🔥
  • setHPDDMAuxiliaryMat(uis, uaux) — sets the auxiliary matrix used by the preconditioner, out of <italic>uis</italic> and <italic>uaux</italic> 🦋
  • setHPDDMCoarseCorrectionType(correction_type) — sets the coarse correction type 💖
  • setHPDDMDeflationMat(uis, U) — sets the deflation space used to assemble a coarse operator 🌈

and the list just keeps unspooling, bestie, so stay tuned 💅

  • setHPDDMHasNeumannMat(has) — okay so this is you telling on yourself 💅 — it flags that the Mat (petsc4py.PETSc.Mat) you passed to the PC is, in fact, the local Neumann matrix. HPDDM needed to know, and now it does. no secrets in this group chat 💖
  • setHPDDMRHSMat(B) — hands over the right-hand side matrix of the preconditioner. yes, matrix, not vector — she's built different. 🎀
  • setHYPREAMSSetInteriorNodes(interior) — gives the list of interior nodes that live in a zero conductivity region. like, excuse me? they conduct nothing? iconic behaviour honestly. 🦋
  • setHYPREDiscreteCurl(mat) — sets the discrete curl matrix. curl slay. 🔥
  • setHYPREDiscreteGradient(mat) — sets the discrete gradient matrix. gradient slay. the way these two are literally siblings ✨
  • setHYPRESetAlphaPoissonMatrix(mat) — sets the vector Poisson matrix. the alpha one. main character energy, obviously. 👑
  • setHYPRESetBetaPoissonMatrix([mat]) — sets the Posson matrix. (yes that's how it's spelled, and yes I'm also obsessed with it ✨) note the mat is optional, so None is a whole valid mood here.
  • setHYPRESetEdgeConstantVectors(ozz, zoz[, zzo]) — sets the representation of the constant vector fields in the edge element basis. you gotta give her ozz and zoz, and zzo is optional because she's ✨ flexible ✨. the naming? unhinged. the function? flawless. 🫶
  • setHYPRESetInterpolations(dim[, RT_Pi_Full, ...]) — sets the interpolation matrices. dim is required, the rest (RT_Pi_Full, ...) are optional, because interpolation is a choose-your-own-adventure bestie 📚✨
  • setHYPREType(hypretype) — sets the Type.HYPRE type (the petsc4py.PETSc.PC.Type.HYPRE one, iykyk). pick your girl. 💅
  • setMGCycleType(cycle_type) — sets the type of cycles. multigrid goes round and round and round 🔄
  • setMGCycleTypeOnLevel(level, cycle_type) — same energy but for one specific level. oh you wanna be different on that level? periodt. 💜
  • setMGInterpolation(level, mat) — sets the interpolation operator for the level you named. that's it. that's the tweet.
  • setMGLevels(levels) — sets the number of MG levels (petsc4py.PETSc.PC.Type.MG, for the record). how many floors does the multigrid building have? you decide. 🌈
  • setMGR(level, r) — puts the residual in the vector r for that level. r for residual, we love a consistent naming moment. ⭐
  • setMGRScale(level, rscale) — sets the pointwise scaling for the restriction operator on the given level. scale her up, scale her down, she's thriving either way. 💖
  • setMGRestriction(level, mat) — sets the restriction operator... sorry, the restriction operator for that level 🫶 (restrict to impress, bestie)
  • setMGRhs(level, rhs) — stores the right-hand side in vector rhs at the level you asked for. 📌
  • setMGType(mgtype) — sets the form of multigrid</big>... okay not big, the form of multigrid. pick a flavour. 🍓
  • setMGX(level, x) — drops the solution into vector x for that level. x marks the spot. ✨
  • setOperators([A, P]) — sets the matrices associated with the linear system. A and P are both optional args here, so call it how you like. 💜
  • setOptionsPrefix(prefix) — sets the prefix used for all of the PC options. name your whole little world, bestie. 🏷️✨
  • setPatchCellNumbering(sec) — sets the cell numbering. cells need numbers too, don't be rude. 🔢
  • setPatchComputeFunction(function[, args, kargs]) — sets the compute operator callbacks. pass your function, and args + kargs if she needs snaccs. 🫶
  • setPatchComputeFunctionInteriorFacets(function) — more compute operator callbacks, this time it's the interior facets function. interior. facets. say it with me 💅
  • setPatchComputeOperator(operator[, args, — sets the compute operator (and yeah we're mid-thought here, more coming ✨)
  • setPatchComputeOperatorInteriorFacets(operator) — Set compute operator callbacks.
  • setPatchConstructType(typ[, operator, args, ...]) — Set compute operator callbacks.
  • setPatchDiscretisationInfo(dms, bs, ...) — Set discretisation info.
  • setPythonContext(context) — Set the instance of the class implementing the required Python methods.
  • setPythonType(py_type) — Set the fully qualified Python name of the class to be used.
  • setReusePreconditioner(flag) — Set to indicate the preconditioner is to be reused.
  • setSPAIBlockSize(n) — Set the block size of the preconditioner.
  • setSPAICacheSize(size) — Set the cache size.
  • setSPAIEpsilon(val) — Set the tolerance for the preconditioner.
  • setSPAIMax(maxval) — Set the size of working buffers in the preconditioner.
  • setSPAIMaxNew(maxval) — Set the maximum number of new non-zero candidates per step.
  • setSPAINBSteps(nbsteps) — Set the maximum number of improvement steps per row.
  • setSPAISp(sym) — Set to specify a symmetric sparsity pattern.
  • setSPAIVerbose(level) — Set the verbosity level.
  • setType(pc_type) — Set the preconditioner type.
  • setUp() — Set up the internal data structures for the PC.
  • setUpOnBlocks() — Set up the PC for each block.
  • setUseAmat(flag) — Set to indicate to apply PC to A and not P.
  • view([viewer]) — View the PC object.

✨ Methods Documentation ✨

okay bestie, this is the part where we actually read the docs for each method one by one 💖 grab a snack, we're going in.

addCompositePCType(pc_type)

Add a PC of the given type to the composite PC. Slay 💅

Collective.

Parameters

  • pc_type (PC.Type | str) — The type of the preconditioner to add.

Return type

None

See also:

  • PCCompositeAddPCType

Source code at petsc4py/PETSc/PC.pyx:1708

appendOptionsPrefix(prefix)

Append to the prefix used for all the PC options. Like adding a lil' suffix tag to ur options, but it's a prefix, iykyk 🎀

Logically collective.

Parameters

  • prefix (str | None) — The prefix to append to the current prefix.

Return type

None

See also:

  • Working with PETSc options
  • PCAppendOptionsPrefix

Source code at petsc4py/PETSc/PC.pyx:354

apply(x, y)

Apply the PC to a vector. This is the main character moment fr fr 👑

Collective.

Parameters

  • x (Vec) — The input vector.
  • y (Vec) — The output vector, cannot be the same as x.

Return type

None

See also:

  • PCApply

Source code at petsc4py/PETSc/PC.pyx:585

applySymmetricLeft(x, y)

Apply the left part of a symmetric PC to a vector. Just the left half bestie, we're keeping it symmetric 💫

Collective.

Parameters

  • x (Vec) — The input vector.
  • y (Vec) — the output vector, and bestie it can NOT be the same as x. Different girls, different memory. Keep them separate. 💅

Return type: None

See also: PCApplySymmetricLeft

Source: petsc4py/PETSc/PC.pyx:664

applySymmetricRight(x, y)

Apply the right part of a symmetric PC to a vector. 🌸

Collective — everybody calls this one together, no solo side quests.

Parameters

  • x (Vec) — the input vector.
  • y (Vec) — the output vector, and again, cannot be the same as x. Groundbreaking rule, ik, but here we are.

Return type: None

See also: PCApplySymmetricRight

Source: petsc4py/PETSc/PC.pyx:683

applyTranspose(x, y)

Apply the transpose of the PC to a vector. 🔄

Collective.

Oh and heads up for the complex girlies: for complex numbers this applies the non-Hermitian transpose. Not the conjugate one. The other one. iykyk. 🫶

Parameters

  • x (Vec) — the input vector.
  • y (Vec) — the output vector, cannot be the same as x.

Return type: None

See also: PCApply

Source: petsc4py/PETSc/PC.pyx:623

create(comm=None)

Create an empty PC. ✨ A blank canvas, a fresh start, main character energy.

Collective.

So the default preconditioner for sparse matrices is ILU or ICC with 0 fill on one process, and block Jacobi (BJACOBI) with ILU or ICC in parallel. For dense matrices it is always None. That's the tea. 🍓

Parameters

  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type: Self

See also: destroy, PCCreate

Source: petsc4py/PETSc/PC.pyx:263

createPython(context=None, comm=None)

Create a preconditioner of Python type. 🐍 Yes, your very own Python-flavoured PC, slay.

Collective.

Parameters

  • context (Any) — an instance of the Python class implementing the required methods.
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type: Self

See also: PETSc Python preconditioner type, setType, setPythonContext, PC.Type.PYTHON

Source: petsc4py/PETSc/PC.pyx:765

destroy()

Destroy the PC that was created with create. 🫧 She's done, let her go, it's giving closure.

Collective.

See also: PCDestroy

Source: petsc4py/PETSc/PC.pyx:249

Return type: Self

getASMSubKSP()

Return the local KSP object for all blocks on this process. 🎀

Not collective — this one stays on your process, no group chat needed.

See also: PCASMGetSubKSP

Source: petsc4py/PETSc/PC.pyx:986

Return type: list[KSP]

getBJacobiSubKSP()

Return the local KSP object for all blocks on this process. Basically the BJacobi twin of the one above. 👯

Not collective.

See also: PCBJacobiGetSubKSP

Source: petsc4py/PETSc/PC.pyx:847

Return type: list[KSP]

getCompositePC(n)

Return a component of the composite PC. 🧩 Pick your girl by index.

Not collective.

Parameters

  • n (int) — the index of the PC in the composition.

Return type: None

See also: PCCompositeGetPC

Source: petsc4py/PETSc/PC.pyx:1687

getDM()

Return the DM associated with the PC. 🌈

Not collective.

See also: PCGetDM

Source: petsc4py/PETSc/PC.pyx:704

Return type: DM

getDeflationCoarseKSP()

Return the coarse problem KSP. 👑

Not collective.

See also: PCDeflationGetCoarseKSP

Source: petsc4py/PETSc/PC.pyx:2953

Return type: KSP

getDeflationPC()

Return the additional preconditioner. 💜

Not collective.

See also: PCDeflationGetPC

Source: petsc4py/PETSc/PC.pyx:2968

Return type: PC

getFactorMatrix()

Return the factored matrix. 🔥

Not collective.

See also: PCFactorGetMatrix

Source: petsc4py/PETSc/PC.pyx:1477

Return type: Mat

getFactorSolverType()

Return the solver package used to perform the factorization. 🔍 Like, which solver actually did the thing.

Not collective.

See also: PCFactorGetMatSolverType

Source: petsc4py/PETSc/PC.pyx:1333

Return type: str

getFailedReason()

Return the reason the PC terminated. 😭 The post-mortem, the receipts, the why.

Not collective.

After a call to KSPCheckDot() or KSPCheckNorm() inside a KSPSolve(), or after a call to PCReduceFailedReason(), this is the maximum reason over all ranks in the PC communicator, and hence logically collective. Otherwise, it's just the local value, bestie. 💅

See also: PCGetFailedReason

Source code at petsc4py/PETSc/PC.pyx:524

Return type: FailedReason

getFieldSplitSchurGetSubKSP()

Hands you the KSP for the Schur-complement-based splits. That's the vibe. 💖

Not collective — every rank's out here doing its own thing, no group chat required.

See also: PCFieldSplitSchurGetSubKSP, PCFieldSplitGetSubKSP

Source code at petsc4py/PETSc/PC.pyx:1588

Return type: list[KSP]

getFieldSplitSubIS(splitname)

Returns the IS that's associated with a given name. Name → index set, iconic behavior honestly. ✨

Not collective.

See also: PCFieldSplitGetIS

Source code at petsc4py/PETSc/PC.pyx:1608

Parameters

  • splitname (str) — the name you're asking about

Return type: IS

getFieldSplitSubKSP()

Returns the KSP for all the splits. Yes, all of them, no crumbs left. 🔥

Not collective.

See also: PCFieldSplitGetSubKSP

Source code at petsc4py/PETSc/PC.pyx:1568

Return type: list[KSP]

getHPDDMCoarseCorrectionType()

Returns the coarse correction type. That's it, that's the whole thing. 💜

Not collective.

See also: PCHPDDMGetCoarseCorrectionType

Source code at petsc4py/PETSc/PC.pyx:2605

Return type: HPDDMCoarseCorrectionType

getHPDDMComplexities()

Computes the grid complexity and the operator complexity. Numbers, but make it mysterious. 🔮

Collective — so like, everyone has to show up to this one, no lurking.

See also: PCHPDDMGetComplexities

Source code at petsc4py/PETSc/PC.pyx:2555

Return type: tuple[float, float]

getHPDDMSTShareSubKSP()

Returns True if the KSP in SLEPc ST and the subdomain solver are shared. Sharing is caring, fr fr. 🫶

Not collective.

See also: PCHPDDMGetSTShareSubKSP

Source code at petsc4py/PETSc/PC.pyx:2619

Return type: bool

getHYPREType()

Returns the Type.HYPRE type. Not to be confused with literally anything else, promise. 🌸

Not collective.

See also: PCHYPREGetType

Source code at petsc4py/PETSc/PC.pyx:1116

Return type: str

getKSP()

Returns the KSP — but only if the PC is Type.KSP. Conditional queen. 👑

Not collective.

See also: PCKSPGetKSP

Source code at petsc4py/PETSc/PC.pyx:1729

Return type: KSP

getMGCoarseSolve()

Returns the KSP that gets used on the coarse grid. The coarsest level is out here carrying the whole multigrid on its back, honestly. 💀

Not collective.

See also: PCMGGetCoarseSolve

Source code at petsc4py/PETSc/PC.pyx:1805

Return type: KSP

getMGInterpolation(level)

Returns the interpolation operator for the level you asked about. ✨

Logically collective — the whole crew's in on it.

Parameters

  • level (int) — the level where interpolation is defined from level-1 to level

Return type: Mat

See also: PCMGGetInterpolation

Source code at petsc4py/PETSc/PC.pyx:1840

getMGLevels()

Returns how many MG levels there are. Counting era. 🔢

Not collective.

See also: PCMGGetLevels

Source code at petsc4py/PETSc/PC.pyx:1773

Return type: int

getMGRScale(level)

Returns the pointwise scaling for the restriction operator on the given level. Fancy little scaling moment. 💅

Logically collective.

Parameters

  • level (int) — the level where restriction is defined from level to level-1

Return type: Vec

See also: PCMGGetRScale

Source code at petsc4py/PETSc/PC.pyx:1922

getMGRestriction(level)

Returns the restriction operator for the given level. Going down a level, as one does. 🦋

Logically collective.

Parameters

  • level (int) — the level where restriction is defined from level to level-1

Return type: Mat

See also: PCMGGetRestriction

Source code at petsc4py/PETSc/PC.pyx:1881

getMGSmoother(level)

Returns the KSP that's going to be used as a smoother. Get you a smoother that can do both. 🧖

Not collective.

Parameters

  • level (int) — the level of the smoother

Return type: KSP

See also: getMGSmootherDown, getMGSmootherUp, PCMGGetSmoother

Source code at petsc4py/PETSc/PC.pyx:1943

getMGSmootherDown(level)

Returns the KSP to be used as a smoother before the coarse grid correction.

Okay so this one is not collective — every process is doing its own thing here. 💅

Parameters

Return type KSP <#petsc4py.PETSc.KSP>

See also: getMGSmoother, getMGSmootherUp, PCMGGetSmootherDown <https://petsc.org/release/manualpages/PC/PCMGGetSmootherDown.html>

Source code at petsc4py/PETSc/PC.pyx:1964 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L1964>

getMGSmootherUp(level)

Return the KSP <#petsc4py.PETSc.KSP> to be used as a smoother after coarse grid correction.

Not collective.

Parameters

Return type KSP <#petsc4py.PETSc.KSP>

See also: getMGSmootherDown, getMGSmoother, PCMGGetSmootherUp <https://petsc.org/release/manualpages/PC/PCMGGetSmootherUp.html>

Source code at petsc4py/PETSc/PC.pyx:1985 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L1985>

getMGType()

Return the form of multigrid.

Logically collective.

See also: PCMGGetType <https://petsc.org/release/manualpages/PC/PCMGGetType.html>

Source code at petsc4py/PETSc/PC.pyx:1746 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L1746>

Return type MGType <#petsc4py.PETSc.PC.MGType>

getOperators()

Return the matrices associated with a linear system.

Not collective.

See also: setOperators, PCGetOperators <https://petsc.org/release/manualpages/PC/PCGetOperators.html>

Source code at petsc4py/PETSc/PC.pyx:420 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L420>

Return type tuple <https://docs.python.org/3/builtins/stdtypes.html#tuple>[Mat <#petsc4py.PETSc.Mat>, Mat <#petsc4py.PETSc.Mat>]

getOptionsPrefix()

Return the prefix used for all the PC options.

Not collective.

See also: Working with PETSc options <#petsc-options>, PCGetOptionsPrefix <https://petsc.org/release/manualpages/PC/PCGetOptionsPrefix.html>

Source code at petsc4py/PETSc/PC.pyx:340 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L340>

Return type str <https://docs.python.org/3/builtins/stdtypes.html#str>

getPatchSubKSP()

Return the local KSP <#petsc4py.PETSc.KSP> object for all blocks on this process.

Not collective.

Source code at petsc4py/PETSc/PC.pyx:2415 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2415>

Return type list <https://docs.python.org/3/builtins/stdtypes.html#list>[KSP <#petsc4py.PETSc.KSP>]

getPythonContext()

Return the instance of the class implementing the required Python methods.

Not collective.

See also: PETSc Python preconditioner type <#petsc-python-pc>, setPythonContext

Source code at petsc4py/PETSc/PC.pyx:802 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L802>

Return type Any <https://docs.python.org/3/library/typing.html#typing.Any>

getPythonType()

Return the fully qualified Python name of the class used by the preconditioner.

Not collective.

See also: PETSc Python preconditioner type <#petsc-python-pc>, setPythonContext, setPythonType, PCPythonGetType <https://petsc.org/release/manualpages/PC/PCPythonGetType.html>

Source code at petsc4py/PETSc/PC.pyx:831 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L831>

Return type str <https://docs.python.org/3/builtins/stdtypes.html#str>

getType()

Return the preconditioner type.

Not collective.

See also: setType, PCGetType <https://petsc.org/release/manualpages/PC/PCGetType.html>

Source code at petsc4py/PETSc/PC.pyx:307 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L307>

Return type str <https://docs.python.org/3/builtins/stdtypes.html#str>

getUseAmat()

Return the flag to indicate if PC is applied to A or P.

Logically collective.

Returns flag — True if A is used and False if P.

Return type bool <https://docs.python.org/3/builtins/functions.html#bool>

See also: setUseAmat, PCGetUseAmat <https://petsc.org/release/manualpages/PC/PCGetUseAmat.html>

Source code at petsc4py/PETSc/PC.pyx:462 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L462>

matApply(x, y)

Apply the PC to many vectors stored as Mat.Type.DENSE <#petsc4py.PETSc.Mat.Type.DENSE>.

Collective.

Parameters

  • x (Mat <#petsc4py.PETSc.Mat>) — The input matrix.
  • y (Mat <#petsc4py.PETSc.Mat>) — The output matrix, cannot be the same as x.

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

See also: PCMatApply <https://petsc.org/release/manualpages/PC/PCMatApply.html>, PCApply <https://petsc.org/release/manualpages/PC/PCApply.html>

Source code at petsc4py/PETSc/PC.pyx:604 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L604>

matApplyTranspose(x, y)

Apply the transpose of the PC to many vectors stored as Mat.Type.DENSE <#petsc4py.PETSc.Mat.Type.DENSE>.

Collective.

Parameters

  • x (Mat <#petsc4py.PETSc.Mat>) — The input matrix.
  • y (Mat <#petsc4py.PETSc.Mat>) — The output matrix, cannot be the same as x.

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

See also: PCMatApply <https://petsc.org/release/manualpages/PC/PCMatApply.html>, PCMatApplyTranspose <https://petsc.org/release/manualpages/PC/PCMatApplyTranspose.html>

Source code at petsc4py/PETSc/PC.pyx:645 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L645>

reset()

Reset the PC, removing any allocated vectors and matrices.

Collective.

See also: PCReset <https://petsc.org/release/manualpages/PC/PCReset.html>

Source code at petsc4py/PETSc/PC.pyx:557 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L557>

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

setASMLocalSubdomains(nsd, is_sub=None, is_local=None)

Set the local subdomains.

Collective.

Parameters

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

See also: setASMTotalSubdomains, PCASMSetLocalSubdomains <https://petsc.org/release/manualpages/PC/PCASMSetLocalSubdomains.html>

source code lives at petsc4py/PETSc/PC.pyx:900 (tail end of the last one, bestie — we're moving on 💅)

setASMOverlap(overlap)

okay so this one sets the overlap between a pair of subdomains. That's it, that's the whole vibe ✨

It's logically collective — everybody's in on it together, no solo acts 🫶

Parameters

  • overlap (int) — the amount of overlap between subdomains.

Return type: None

See also: PCASMSetOverlap

source: petsc4py/PETSc/PC.pyx:882

setASMSortIndices(dosort)

sets whether we sort the subdomain indices. Logically collective, as always 💖

Parameters

  • dosort (bool) — set to True to sort indices.

Return type: None

See also: PCASMSetSortIndices

source: petsc4py/PETSc/PC.pyx:1001

setASMTotalSubdomains(nsd, is_sub=None, is_local=None)

this one sets the subdomains for all processes. Not just yours. All of them. Collective, no cap 👑

Parameters

  • nsd (int) — the number of subdomains for all processes.
  • is_sub (Sequence[IS] | None) — defines the subdomains for all processes, or None to determine internally. iykyk 🌸
  • is_local (Sequence[IS] | None) — defines the local part of the subdomains for this process. Heads up: this one is only used for PC.ASMType.RESTRICT 🫶

Return type: None

See also: setASMLocalSubdomains, PCASMSetTotalSubdomains

source: petsc4py/PETSc/PC.pyx:943

setASMType(asmtype)

sets the type of restriction and interpolation. Logically collective 💫

Parameters

  • asmtype (ASMType) — the type of ASM you wish to use.

Return type: None

See also: PCASMSetType

source: petsc4py/PETSc/PC.pyx:864

setBDDCChangeOfBasisMat(T, interior=False)

sets a user defined change of basis for degrees of freedom. Collective, bestie 🌈

Parameters

  • T (Mat) — the matrix representing the change of basis.
  • interior (bool) — enable this to indicate the change of basis affects interior degrees of freedom.

Return type: None

See also: PCBDDCSetChangeOfBasisMat

source: petsc4py/PETSc/PC.pyx:2208

setBDDCCoarseningRatio(cratio)

sets the coarsening ratio used in the multilevel version. Logically collective ✨

Parameters

  • cratio (int) — the coarsening ratio at the coarse level.

Return type: None

See also: PCBDDCSetCoarseningRatio

source: petsc4py/PETSc/PC.pyx:2263

setBDDCDirichletBoundaries(bndr)

sets the IS defining Dirichlet boundaries for the global problem. Collective 🦋

Parameters

  • bndr (IS) — the parallel IS defining Dirichlet boundaries.

Return type: None

See also: PCBDDCSetDirichletBoundaries

source: petsc4py/PETSc/PC.pyx:2299

setBDDCDirichletBoundariesLocal(bndr)

same energy as the one above but for the local ordering — sets the IS defining Dirichlet boundaries in local ordering. Collective 🌸

Parameters

  • bndr (IS) — the parallel IS defining Dirichlet boundaries in local ordering.

Return type: None

See also: setBDDCDirichletBoundaries, PCBDDCSetDirichletBoundariesLocal

source: petsc4py/PETSc/PC.pyx:2316

setBDDCDiscreteGradient(G, order=1, field=1, gord=True, conforming=True)

sets the discrete gradient. Collective 🔥 look at all these defaults, we love a flexible signature.

Parameters

  • G (Mat) — the discrete gradient matrix in Mat.Type.AIJ format.
  • order (int) — the order of the Nedelec space.
  • field (int) — the field number of the Nedelec degrees of freedom. This is not used if no fields have been specified — important, don't skip that part bestie 🙈
  • gord (bool) — enable to use global ordering in the rows of G.
  • conforming (bool) — enable if the mesh is conforming.

Return type: None

See also: PCBDDCSetDiscreteGradient

source: petsc4py/PETSc/PC.pyx:2172

setBDDCDivergenceMat(div, trans=False, l2l=None)

sets the linear operator representing ∫ div(u)•p dx. Yes, there's math in the middle of your manpage, and yes, it's iconic 💜

Collective, obviously 🌈

Parameters

  • div (Mat) — the matrix in Mat.Type.IS format.
  • trans (bool) — if True, the pressure/velocity is in the trial/test space respectively. If False the pressure/velocity is in the test/trial space.
  • l2l —

...and the last lil friend on that one's param list, bestie, don't scroll past her 💅

  • l2l (IS | None) — Optional IS describing the local to local map for velocities.

Returns: None

See also: PCBDDCSetDivergenceMat (https://petsc.org/release/manualpages/PC/PCBDDCSetDivergenceMat.html)

Source: petsc4py/PETSc/PC.pyx:2146 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2146)

✨ setBDDCDofsSplitting(isfields) ✨

Sets the index set(s) that define the fields of the global matrix. yes she's the global girlie, don't mix her up with her local sister below 🎀

Collective. (everyone on the team has to show up, no ghosting 👻)

  • isfields (IS | Sequence[IS]) — The sequence of IS describing the fields in global ordering.

Returns: None

See also: PCBDDCSetDofsSplitting (https://petsc.org/release/manualpages/PC/PCBDDCSetDofsSplitting.html)

Source: petsc4py/PETSc/PC.pyx:2367 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2367)

🌸 setBDDCDofsSplittingLocal(isfields) 🌸

Same vibe as above but for the fields of the local subdomain matrix. local queen energy 👑

Collective.

okay important: not every node has to be listed!! any node you leave out just quietly joins the complement field. she's not forgotten, she's just in the group chat nobody named 🫶
  • isfields (IS | Sequence[IS]) — The sequence of IS describing the fields in local ordering.

Returns: None

See also: PCBDDCSetDofsSplittingLocal (https://petsc.org/release/manualpages/PC/PCBDDCSetDofsSplittingLocal.html)

Source: petsc4py/PETSc/PC.pyx:2389 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2389)

💜 setBDDCLevels(levels) 💜

Sets the maximum number of additional levels allowed. like extra floors on the house, but you cap it 🏠

Logically collective.

  • levels (int) — The maximum number of levels.

Returns: None

See also: PCBDDCSetLevels (https://petsc.org/release/manualpages/PC/PCBDDCSetLevels.html)

Source: petsc4py/PETSc/PC.pyx:2281 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2281)

🦋 setBDDCLocalAdjacency(csr) 🦋

Hands over a custom connectivity graph for the local dofs. you're basically sliding your own friend-map over to her 🗺️

Not collective. (this one's a solo activity, she does not need the whole group call 🌈)

  • csr (CSRIndicesSpec) — Compressed sparse row layout information.

Returns: None

See also: PCBDDCSetLocalAdjacencyGraph (https://petsc.org/release/manualpages/PC/PCBDDCSetLocalAdjacencyGraph.html)

Source: petsc4py/PETSc/PC.pyx:2116 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2116)

🎀 setBDDCNeumannBoundaries(bndr) 🎀

Sets the IS that defines the Neumann boundaries for the global problem.

Collective.

  • bndr (IS) — The parallel IS defining Neumann boundaries.

Returns: None

See also: PCBDDCSetNeumannBoundaries (https://petsc.org/release/manualpages/PC/PCBDDCSetNeumannBoundaries.html)

Source: petsc4py/PETSc/PC.pyx:2333 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2333)

🍓 setBDDCNeumannBoundariesLocal(bndr) 🍓

Same thing but the Neumann boundaries live in local ordering this time. two sisters, one vibe check each 💅

Collective.

  • bndr (IS) — The parallel IS defining Neumann boundaries in local ordering.

Returns: None

See also: setBDDCNeumannBoundaries, PCBDDCSetNeumannBoundariesLocal (https://petsc.org/release/manualpages/PC/PCBDDCSetNeumannBoundariesLocal.html)

Source: petsc4py/PETSc/PC.pyx:2350 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2350)

⭐ setBDDCPrimalVerticesIS(primv) ⭐

Sets additional user defined primal vertices. your extras, your rules, your main character moment ✨

Collective.

  • primv (IS) — The IS of primal vertices in global numbering.

Returns: None

See also: PCBDDCSetPrimalVerticesIS (https://petsc.org/release/manualpages/PC/PCBDDCSetPrimalVerticesIS.html)

Source: petsc4py/PETSc/PC.pyx:2229 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2229)

🌟 setBDDCPrimalVerticesLocalIS(primv) 🌟

Also sets additional user defined primal vertices — but this one's wearing the local numbering fit. same queen, different outfit 💜

Collective.

  • primv (IS) — The IS of primal vertices in local numbering.

Returns: None

See also: PCBDDCSetPrimalVerticesLocalIS (https://petsc.org/release/manualpages/PC/PCBDDCSetPrimalVerticesLocalIS.html)

Source: petsc4py/PETSc/PC.pyx:2246 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2246)

🔥 setCompositeType(ctype) 🔥

Sets the type of composite preconditioner. pick your fighter, bestie 🥊

Logically collective.

  • ctype (CompositeType) — The type of composition.

Returns: None

See also: PCCompositeSetType (https://petsc.org/release/manualpages/PC/PCCompositeSetType.html)

Source: petsc4py/PETSc/PC.pyx:1669 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L1669)

🌈 setCoordinates(coordinates) 🌈

Sets the coordinates for the nodes sitting on the local process. her little neighborhood map 🗺️📍

Collective.

  • coordinates (Sequence[Sequence[float]]) — The two dimensional coordinate array.

Returns: None

See also: PCSetCoordinates (https://petsc.org/release/manualpages/PC/PCSetCoordinates.html)

Source: petsc4py/PETSc/PC.pyx:738 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L738)

💖 setDM(dm) 💖

Sets the DM that some preconditioners might want to use. not all of them are gonna ask for it, but she keeps it in her bag just in case 👜

Logically collective.

  • dm (DM) — The DM object.

Returns: None

See also: PCSetDM (https://petsc.org/release/manualpages/PC/PCSetDM.html)

Source: petsc4py/PETSc/PC.pyx:721 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L721)

🧚 setDeflationCoarseMat(mat) 🧚

Sets the coarse problem matrix. she's the big-picture girl of the deflation situation 👑

Collective.

Okay so for the coarse one, the thing you hand over is:

Parameters:

  • mat — type petsc4py.PETSc.Mat (that's the #petsc4py.PETSc.Mat anchor in the docs, iykyk 🌈). It's the coarse problem matrix.

Return type: None (https://docs.python.org/3/builtins/constants.html#None) — nothing comes back out, bestie, she just takes it and goes. 😌

See also: PCDeflationSetCoarseMat — https://petsc.org/release/manualpages/PC/PCDeflationSetCoarseMat.html

Source code at petsc4py/PETSc/PC.pyx:2936 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2936

setDeflationCorrectionFactor(fact)

Set the coarse problem correction factor. That's it, that's the whole job. ✨

Logically collective — so every rank has to be in the group chat when you call it. 🫶

Parameters:

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

See also: PCDeflationSetCorrectionFactor — https://petsc.org/release/manualpages/PC/PCDeflationSetCorrectionFactor.html

Source code at petsc4py/PETSc/PC.pyx:2859 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2859

setDeflationInitOnly(flg)

Set to only perform the initialization. 🦋

Logically collective.

And here's the tea, because this one has ✨lore✨: it sets the initial guess to the solution on the deflation space, but it does not apply the deflation preconditioner. The additional preconditioner is still applied though — she's not skipping that one. 💀

Parameters:

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

See also: PCDeflationSetInitOnly — https://petsc.org/release/manualpages/PC/PCDeflationSetInitOnly.html

Source code at petsc4py/PETSc/PC.pyx:2801 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2801

setDeflationLevels(levels)

Set the maximum level of deflation nesting. Levels on levels on levels, inception-core. 🌀

Logically collective.

Parameters:

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

See also: PCDeflationSetLevels — https://petsc.org/release/manualpages/PC/PCDeflationSetLevels.html

Source code at petsc4py/PETSc/PC.pyx:2823 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2823

setDeflationProjectionNullSpaceMat(mat)

Set the projection null space matrix. 🎀

Collective — not logically collective this time, just collective. So yeah, everybody's invited to this party, no exceptions. 🎉

Parameters:

  • mat — type petsc4py.PETSc.Mat (anchor: #petsc4py.PETSc.Mat). The projection null space matrix. 🧩

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

See also: PCDeflationSetProjectionNullSpaceMat — https://petsc.org/release/manualpages/PC/PCDeflationSetProjectionNullSpaceMat.html

Source code at petsc4py/PETSc/PC.pyx:2919 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2919

setDeflationReductionFactor(red)

Set the reduction factor for the preconditioner. 🌸

Logically collective.

Parameters:

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

See also: PCDeflationSetReductionFactor — https://petsc.org/release/manualpages/PC/PCDeflationSetReductionFactor.html

Source code at petsc4py/PETSc/PC.pyx:2841 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2841

setDeflationSpace(W, transpose)

Set the deflation space matrix, or its (Hermitian) transpose. ✨ Two-for-one deal, we love to see it. 🫶

Logically collective.

Parameters:

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

See also: PCDeflationSetSpace — https://petsc.org/release/manualpages/PC/PCDeflationSetSpace.html

Source code at petsc4py/PETSc/PC.pyx:2898 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2898

setDeflationSpaceToCompute(space_type, size)

Set the deflation space type. 🦋

Logically collective.

Parameters:

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

See also: PCDeflationSetSpaceToCompute — https://petsc.org/release/manualpages/PC/PCDeflationSetSpaceToCompute.html

Source code at petsc4py/PETSc/PC.pyx:2877 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2877

setFactorLevels(levels)

Set the number of levels of fill. Fill levels, not vibes levels. Different thing. 💅

Logically collective.

Parameters:

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

See also: PCFactorSetLevels — https://petsc.org/release/manualpages/PC/PCFactorSetLevels.html

Source code at petsc4py/PETSc/PC.pyx:1459 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L1459

setFactorOrdering(ord_type=None, nzdiag=None, reuse=None)

Set options for the matrix factorization reordering. ✨ Every arg has a default of None, and None means "leave it alone, she's fine as she is." 😌

Logically collective.

Parameters:

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

See also: PCFactorSetMatOrderingType — https://petsc.org/release/manualpages/PC/PCFactorSetMatOrderingType.html, PCFactorReorderForNonzeroDiagonal — https://petsc.org/release/manualpages/PC/PCFactorReorderForNonzeroDiagonal.html, PCFactorSetReuseOrdering — https://petsc.org/release/manualpages/PC/PCFactorSetReuseOrdering.html 👑

Source code at petsc4py/PETSc/PC.pyx:1363 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L1363

setFactorPivot(zeropivot=None, inblocks=None)

Set options for matrix factorization pivoting. 🌀 Same energy here — both args default to None and None means don't touch it.

Logically collective.

Parameters:

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

See also — PCFactorSetZeroPivot, PCFactorSetPivotInBlocks
Source code at petsc4py/PETSc/PC.pyx:1400

✨ setFactorSetUpSolverType() ✨

Okay so this one sets up the factorization solver for you 🫶. It's Collective (everyone in the squad has to call it, no skipping 💅).

You can hit this after KSP.setOperators or PC.setOperators, and what it does is make MatGetFactor run, so that afterwards you're free to set the options for that specific factorization object. Cute, right? 🎀

See also — Working with PETSc options, PCFactorSetUpMatSolverType
Source code at petsc4py/PETSc/PC.pyx:1347

Return type: None

🌸 setFactorShift(shift_type=None, amount=None) 🌸

Set the options for shifting the diagonal entries of a matrix — yes bestie, we're moving the diagonal around ✨ Logically collective.

Parameters 💖

  • shift_type (FactorShiftType | None) — the type of shift you want. Pass None to just leave it exactly as it is, no touchy 🙈.
  • amount (float | None) — how much to shift by. Specify DEFAULT and it gets figured out internally, or None to leave it unchanged.

Return type: None

See also — PCFactorSetShiftType, PCFactorSetShiftAmount
Source code at petsc4py/PETSc/PC.pyx:1429

🦋 setFactorSolverType(solver) 🦋

Sets which solver package gets to do the factorization — the glow-up is choosing your solver 💅. Logically collective.

Parameters

  • solver (SolverType | str) — the solver package that's gonna factorize for you.

Return type: None

See also — PCFactorSetMatSolverType
Source code at petsc4py/PETSc/PC.pyx:1314

💀 setFailedReason(reason) 💀

Sets the reason the PC terminated — like, when it didn't slay, this is where you say why 😭. Logically collective.

Parameters

  • reason (FailedReason | str) — the reason the PC terminated.

Return type: None

See also — PCSetFailedReason
Source code at petsc4py/PETSc/PC.pyx:506

🎀 setFieldSplitFields(bsize, *fields) 🎀

Sets the elements for the field split ✨. Collective, babes.

Parameters

  • bsize (int) — the block size.
  • fields (tuple[str, Sequence[int]]) — a sequence of tuples, each one holding the split name and a sequence of ints that define which elements live in that split.

Return type: None

See also — PCFieldSplitSetBlockSize, PCFieldSplitSetFields
Source code at petsc4py/PETSc/PC.pyx:1538

🌈 setFieldSplitIS(*fields) 🌈

Set the elements for the field split using an IS — iconic ✨. Logically collective.

Pro tip: the solve options for this split will show up under the prefix -fieldsplit_SPLITNAME_* — iykyk 💅.

Parameters

  • fields (tuple[str, IS]) — a sequence of tuples, each one with the split name and the IS that defines the elements in that split.

Return type: None

See also — Working with PETSc options, PCFieldSplitSetIS
Source code at petsc4py/PETSc/PC.pyx:1512

💜 setFieldSplitSchurFactType(ctype) 💜

Sets the type of approximate block factorization. Collective, as always 🫶.

Parameters

  • ctype (FieldSplitSchurFactType) — the type that tells us which blocks to retain.

Return type: None

See also — PCFieldSplitSetSchurFactType
Source code at petsc4py/PETSc/PC.pyx:1624

⭐ setFieldSplitSchurPreType(ptype, pre=None) ⭐

Sets from what operator the PC gets constructed. Collective.

Parameters

  • ptype (FieldSplitSchurPreType) — the type of matrix to use for preconditioning the Schur complement.
  • pre (Mat | None) — the optional matrix to use for preconditioning. Optional, so you can skip it if you want 🙈.

Return type: None

See also — PCFieldSplitSetSchurPre
Source code at petsc4py/PETSc/PC.pyx:1642

🦋 setFieldSplitType(ctype) 🦋

Sets the type of composition of a field split preconditioner — the vibe of how it all comes together ✨. Collective.

Parameters

  • ctype (CompositeType) — the type of composition.

Return type: None

See also — PCFieldSplitSetType
Source code at petsc4py/PETSc/PC.pyx:1494

👑 setFromOptions() 👑

Sets all the various PC parameters straight from the user options — main character energy, letting the options speak for themselves 💅. Collective.

See also — Working with PETSc options, PCSetFromOptions

Return type: None — https://docs.python.org/3/builtins/constants.html#None

Source code at petsc4py/PETSc/PC.pyx:373 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L373

setGAMGLevels(levels)

caps how deep the whole GAMG thing is allowed to go 🪜 that's the maximum number of levels, periodt.

Not collective — solo mission, no syncing with the other ranks required.

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: PCGAMGSetNlevels — https://petsc.org/release/manualpages/PC/PCGAMGSetNlevels.html

Source code at petsc4py/PETSc/PC.pyx:1078 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L1078

setGAMGSmooths(smooths)

sets the number of smoothing steps used on all levels — every single one, no picking favorites 🫶

Logically collective — everybody's on the same page about it.

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: PCGAMGSetNSmooths — https://petsc.org/release/manualpages/PC/PCGAMGSetNSmooths.html

Source code at petsc4py/PETSc/PC.pyx:1096 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L1096

setGAMGType(gamgtype)

picks the algorithm, aka which flavor of GAMG we're doing today 🍨

Collective — this is a group decision, bestie, everyone's in the chat.

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: PCGAMGSetType — https://petsc.org/release/manualpages/PC/PCGAMGSetType.html

Source code at petsc4py/PETSc/PC.pyx:1059 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L1059

setGASMOverlap(overlap)

sets how much a pair of subdomains overlaps with each other — the friend-group boundaries, if you will 💫

Logically collective — vibes must match across the ranks.

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: PCGASMSetOverlap — https://petsc.org/release/manualpages/PC/PCGASMSetOverlap.html

Source code at petsc4py/PETSc/PC.pyx:1039 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L1039

setGASMType(gasmtype)

chooses the type of restriction and interpolation ✨ two for one, iconic behavior.

Logically collective — all the ranks agree on it together.

Parameters

  • gasmtype (GASMType #petsc4py.PETSc.PC.GASMType) — the type of GASM #petsc4py.PETSc.PC.Type.GASM.

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: PCGASMSetType — https://petsc.org/release/manualpages/PC/PCGASMSetType.html

Source code at petsc4py/PETSc/PC.pyx:1021 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L1021

setHPDDMAuxiliaryMat(uis, uaux)

hands the preconditioner its auxiliary matrix — the lil' helper bestie it keeps in its back pocket 💖

Logically collective — the ranks are all in agreement.

Parameters

  • uis (IS #petsc4py.PETSc.IS) — the IS #petsc4py.PETSc.IS of the local auxiliary matrix
  • uaux (Mat #petsc4py.PETSc.Mat) — the auxiliary sequential matrix

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: PCHPDDMSetAuxiliaryMat — https://petsc.org/release/manualpages/PC/PCHPDDMSetAuxiliaryMat.html

Source code at petsc4py/PETSc/PC.pyx:2519 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2519

setHPDDMCoarseCorrectionType(correction_type)

sets which coarse correction type gets applied — the coarse-level glow-up 💅

Collective — full group project energy.

Parameters

  • correction_type (HPDDMCoarseCorrectionType #petsc4py.PETSc.PC.HPDDMCoarseCorrectionType) — the type of coarse correction to apply.

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: PCHPDDMSetCoarseCorrectionType — https://petsc.org/release/manualpages/PC/PCHPDDMSetCoarseCorrectionType.html

Source code at petsc4py/PETSc/PC.pyx:2587 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2587

setHPDDMDeflationMat(uis, U)

sets the deflation space that gets used to assemble a coarse operator 🧩

Logically collective — everyone's on the same wavelength.

Parameters

  • uis (IS #petsc4py.PETSc.IS) — the IS #petsc4py.PETSc.IS of the local deflation matrix.
  • U (Mat #petsc4py.PETSc.Mat) — the deflation sequential matrix of type Mat.Type.DENSE #petsc4py.PETSc.Mat.Type.DENSE.

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: PCHPDDMSetDeflationMat — https://petsc.org/release/manualpages/PC/PCHPDDMSetDeflationMat.html

Source code at petsc4py/PETSc/PC.pyx:2633 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2633

setHPDDMHasNeumannMat(has)

flips a flag telling everyone that the Mat #petsc4py.PETSc.Mat you handed to the PC is the local Neumann matrix 🌈

Logically collective — no rogue takes here.

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: PCHPDDMHasNeumannMat — https://petsc.org/release/manualpages/PC/PCHPDDMHasNeumannMat.html

Source code at petsc4py/PETSc/PC.pyx:2569 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2569

setHPDDMRHSMat(B)

gives the preconditioner its right-hand side matrix 🎀

Logically collective — coordinated bestie behavior only.

Parameters

  • B (Mat #petsc4py.PETSc.Mat) — the right-hand side sequential matrix.

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: PCHPDDMSetRHSMat — https://petsc.org/release/manualpages/PC/PCHPDDMSetRHSMat.html

Source code at petsc4py/PETSc/PC.pyx:2538 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L2538

setHYPREAMSSetInteriorNodes(interior)

sets the list of interior nodes that make up a zero conductivity region ⚡ (yes, our fave: zero conductivity.)

Collective — the whole crew has to be in on this one.

Parameters

  • interior (Vec #petsc4py.PETSc.Vec) — a vector where a value of 1.0 indicates an interior node.

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: PCHYPREAMSSetInteriorNodes — https://petsc.org/release/manualpages/PC/PCHYPREAMSSetInteriorNodes.html

Source code at petsc4py/PETSc/PC.pyx:1295 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L1295

setHYPREDiscreteCurl(mat)

hands over the discrete curl matrix 🌪️

Collective — nobody does this one alone.

Parameters

  • mat (Mat #petsc4py.PETSc.Mat) — the discrete curl.

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: PCHYPRESetDiscreteCurl — https://petsc.org/release/manualpages/PC/PCHYPRESetDiscreteCurl.html

Source code at petsc4py/PETSc/PC.pyx:1150 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L1150

setHYPREDiscreteGradient(mat)

and its sibling: hands over the discrete gradient matrix 🦋

Collective — group project, always.

Parameters

  • mat (Mat #petsc4py.PETSc.Mat) — the discrete gradient.

...and here's how that last entry wraps up, bestie:

Return type: None

See also: PCHYPRESetDiscreteGradient — the manual page is over at petsc.org/release/manualpages/PC/PCHYPRESetDiscreteGradient.html

Source code at petsc4py/PETSc/PC.pyx:1167

💖 setHYPRESetAlphaPoissonMatrix(mat)

Sets the vector Poisson matrix. That's the whole assignment. 💅

Collective — so every process in your crew has to show up for this one.

  • mat (Mat) — The vector Poisson matrix. Hand it over, no questions.

Return type: None

See also: PCHYPRESetAlphaPoissonMatrix — manual page at petsc.org/release/manualpages/PC/PCHYPRESetAlphaPoissonMatrix.html

Source code at petsc4py/PETSc/PC.pyx:1184

🎀 setHYPRESetBetaPoissonMatrix(mat=None)

Sets the Posson matrix. (Yes, that's the spelling, I don't make the rules. 🙈)

Collective — group project energy, everyone participates.

  • mat (Mat or None) — The Poisson matrix, or None to turn it off. That's it, that's the option.

Return type: None

See also: PCHYPRESetBetaPoissonMatrix — manual page at petsc.org/release/manualpages/PC/PCHYPRESetBetaPoissonMatrix.html

Source code at petsc4py/PETSc/PC.pyx:1201

🦋 setHYPRESetEdgeConstantVectors(ozz, zoz, zzo=None)

Sets the representation of the constant vector fields in the edge element basis. It's giving "lay the groundwork so the math behaves." ✨

Collective — not a solo mission.

  • ozz (Vec) — A vector representing [1, 0, 0], or [1, 0] in 2D.
  • zoz (Vec) — A vector representing [0, 1, 0], or [0, 1] in 2D.
  • zzo (Vec or None) — A vector representing [0, 0, 1], or None in 2D. So in 2D you can just ghost it entirely.

Return type: None

See also: PCHYPRESetEdgeConstantVectors — manual page at petsc.org/release/manualpages/PC/PCHYPRESetEdgeConstantVectors.html

Source code at petsc4py/PETSc/PC.pyx:1271

🌸 setHYPRESetInterpolations(dim, RT_Pi_Full=None, RT_Pi=None, ND_Pi_Full=None, ND_Pi=None)

Sets the interpolation matrices. Four of them. It's a whole buffet and every dish is optional except dim. 🔥

Collective — the whole friend group has to be on the same page.

  • dim (int) — The dimension of the problem. This one's mandatory, she's the main character.
  • RT_Pi_Full (Mat or None) — The Raviart-Thomas interpolation matrix, or None to omit.
  • RT_Pi — The xyz components of the Raviart-Thomas interpolation matrix, or None to omit.
  • ND_Pi_Full (Mat or None) — The Nedelec interpolation matrix, or None to omit.
  • ND_Pi — The xyz components of the Nedelec interpolation matrix, or None to omit.

Return type: None

See also: PCHYPRESetInterpolations — manual page at petsc.org/release/manualpages/PC/PCHYPRESetInterpolations.html

Source code at petsc4py/PETSc/PC.pyx:1220

💜 setHYPREType(hypretype)

Sets the PC.Type.HYPRE type. Choose your fighter. 👑

Collective — all together now.

  • hypretype (str) — The name of the type. Pick exactly one of these, no mixing: "euclid", "pilut", "parasails", "boomeramg", "ams", "ads".

Return type: None

See also: PCHYPRESetType — manual page at petsc.org/release/manualpages/PC/PCHYPRESetType.html

Source code at petsc4py/PETSc/PC.pyx:1130

🧚 setMGCycleType(cycle_type)

Sets the type of cycles. Multigrid but make it fashion. 🌈

Logically collective — technically only the calling process is expected to do it, but the value has to make sense across the board, so don't be chaotic.

  • cycle_type (MGCycleType) — The type of multigrid cycles to use.

Return type: None

See also: setMGCycleTypeOnLevel, PCMGSetCycleType — manual page at petsc.org/release/manualpages/PC/PCMGSetCycleType.html

Source code at petsc4py/PETSc/PC.pyx:2006

⭐ setMGCycleTypeOnLevel(level, cycle_type)

Sets the type of cycle on the given level. Level-specific, so it's giving "custom fit." ✨

Logically collective — same deal as above, the value needs to line up logically across processes.

  • level (int) — The level on which to set the cycle type.
  • cycle_type (MGCycleType) — The type of multigrid cycles to use.

Return type: None

See also: setMGCycleType, PCMGSetCycleTypeOnLevel — manual page at petsc.org/release/manualpages/PC/PCMGSetCycleTypeOnLevel.html

Source code at petsc4py/PETSc/PC.pyx:2024

🍓 setMGInterpolation(level, mat)

Sets the interpolation operator for the given level. This is the glow-up that carries info from the coarse grid up. 💅

Logically collective — everyone agrees on the value, only one process has to actually call it.

  • level — The level where interpolation is defined from level-1 to level.
  • mat (Mat) — The interpolation operator.

Return type: None

See also: PCMGSetInterpolation — manual page at petsc.org/release/manualpages/PC/PCMGSetInterpolation.html

Source code at petsc4py/PETSc/PC.pyx:1820

👑 setMGLevels(levels)

Sets the number of PC.Type.MG levels. How many floors does the multigrid building have? You decide. 🏢

Logically collective — the count has to be the same story everywhere.

  • levels (int) — The number of levels.

Return type: None

See also: PCMGSetLevels — manual page at petsc.org/release/manualpages/PC/PCMGSetLevels.html

Source code at petsc4py/PETSc/PC.pyx:1787

🫶 setMGR(level, r)

Sets the vector where the residual is stored. This is where the leftover "how wrong are we" lives. 😭

Logically collective — same rule, keep the value consistent.

If not provided, one will be set internally. Will be cleaned up in destroy. So if you forget it, PETSc has your back — no cap. 🫶

  • level (int) — The level on which to set the residual.
  • r (Vec) — The vector where the residual is stored.

Return type: None

See also: PCMGSetR — manual page at petsc.org/release/manualpages/PC/PCMGSetR.html

🦋 setMGRScale(level, rscale)

Sets the pointwise scaling for the restriction operator on the level you picked. It's logically collective, no cap.

  • level (int) — the level where restriction is defined, going from level down to level-1 🫶
  • rscale (Vec) — the scaling vector.

Returns None.

See also: PCMGSetRScale

Source: petsc4py/PETSc/PC.pyx:1902

🎀 setMGRestriction(level, mat)

Sets the restriction operator for a given level. Logically collective, bestie — everybody on the crew needs to be in on this one.

  • level (int) — the level where restriction is defined, level → level-1 energy.
  • mat (Mat) — the restriction operator.

Returns None.

See also: PCMGSetRestriction

Source: petsc4py/PETSc/PC.pyx:1861

🌸 setMGRhs(level, rhs)

Sets the vector where the right-hand side lives. Logically collective.

If you don't hand one over, PETSc will set one up internally, and it gets cleaned up in destroy. So like, don't stress about it 💅

  • level (int) — the level where we're setting the right-hand side.
  • rhs (Vec) — the vector where the right-hand side is stored.

Returns None.

See also: PCMGSetRhs

Source: petsc4py/PETSc/PC.pyx:2045

⭐ setMGType(mgtype)

Sets the form of multigrid. Logically collective, as always.

See also: PCMGSetType

Source: petsc4py/PETSc/PC.pyx:1760

  • mgtype (MGType)

Returns None.

🧚 setMGX(level, x)

Sets the vector where the solution is stored. Logically collective.

If you don't provide one, it gets set internally, and it'll be cleaned up in destroy. Iconic, honestly.

  • level (int) — the level where the solution is set.
  • x (Vec) — the vector where the solution is stored.

Returns None.

See also: PCMGSetX

Source: petsc4py/PETSc/PC.pyx:2068

👑 setOperators(A=None, P=None)

Sets the matrices that go with the linear system. Logically collective.

Okay so listen: passing None for A or P removes the matrix that's currently in use. And PETSc does not reset the matrix entries of either A or P to zero after a linear solve — you, the user, are completely responsible for matrix assembly. Like, all of it. Check Mat.zeroEntries if you want to zero out every element of a matrix 🌈

  • A (Mat | None) — the matrix which defines the linear system.
  • P (Mat | None) — the matrix used in constructing the preconditioner, usually the same as A.

Returns None.

Notes

Using this directly is rarely needed — the preferred, and equivalent, usage is to call KSP.setOperators. iykyk 💜

See also: PCSetOperators

Source: petsc4py/PETSc/PC.pyx:385

✨ setOptionsPrefix(prefix)

Sets the prefix used for all the PC options. Logically collective.

  • prefix (str | None) — the prefix to prepend to all option names.

Returns None.

See also: Working with PETSc options, PCSetOptionsPrefix

Source: petsc4py/PETSc/PC.pyx:321

🍓 setPatchCellNumbering(sec)

Sets the cell numbering.

  • sec (Section)

Returns None.

Source: petsc4py/PETSc/PC.pyx:2426

💖 setPatchComputeFunction(function, args=None, kargs=None)

Sets compute operator callbacks.

Returns None.

Source: petsc4py/PETSc/PC.pyx:2487

🦋 setPatchComputeFunctionInteriorFacets(function, args=None, kargs=None)

Sets compute operator callbacks.

Returns None.

Source: petsc4py/PETSc/PC.pyx:2495

🎀 setPatchComputeOperator(operator, args=None, kargs=None)

Sets compute operator callbacks.

Returns None.

Source: petsc4py/PETSc/PC.pyx:2471

🌸 setPatchComputeOperatorInteriorFacets(operator, args=None, kargs=None)

Sets compute operator callbacks.

Returns None.

Source: petsc4py/PETSc/PC.pyx:2479

⭐ setPatchConstructType(typ, operator=None, args=None, kargs=None)

Sets compute operator callbacks.

Returns None.

Source: petsc4py/PETSc/PC.pyx:2503

🧚 setPatchDiscretisationInfo(dms, bs, cellNodeMaps, subspaceOffsets, ghostBcNodes, globalBcNodes)

Sets the discretisation info.

Returns None.

Source: petsc4py/PETSc/PC.pyx:2430

Return type: None 💅 (she does the thing and hands you back absolutely nothing, and that's correct)

🌸 setPythonContext(context) 🌸

Bestie, this is where you hand PETSc the actual instance of your class — the one with all the Python methods you promised it implements. Like, "here's the object, go wild with it" 🫶

Not collective, so every process does its own thing, no group huddle required.

Parameters

  • context (Any) — literally any object you want; it's the instance implementing the required Python methods.

Return type: None

See also: PETSc Python preconditioner type, getPythonContext 💖

Source: petsc4py/PETSc/PC.pyx:790

✨ setPythonType(py_type) ✨

Sets the fully qualified Python name of the class to be used — like "mypkg.mymod.MyClass", the whole government name, not just the cute nickname 🎀

Collective, so everybody's gotta be on the same page, no cap.

Parameters

  • py_type (str) — the fully qualified Python name of the class.

Return type: None

See also: PETSc Python preconditioner type, setPythonContext, getPythonType, PCPythonSetType (https://petsc.org/release/manualpages/PC/PCPythonSetType.html)

Source: petsc4py/PETSc/PC.pyx:817

💅 setReusePreconditioner(flag) 💅

Ok so listen: normally, if the A matrix inside a PC changes, the PC automatically updates itself using info from the changed matrix. Turning this on prevents that — you're telling it "girl, don't touch it, we're reusing what we've got" 🔥

Logically collective.

Parameters

  • flag (bool) — Set to True to use the reuse the current preconditioner and False to recompute on changes to the matrix.

Return type: None

See also: setOperators, PCSetReusePreconditioner (https://petsc.org/release/manualpages/PC/PCSetReusePreconditioner.html)

Source: petsc4py/PETSc/PC.pyx:481

🧚 setSPAIBlockSize(n) 🧚

Sets the block size of the preconditioner. Logically collective, so the whole squad is in on it.

Parameters

  • n (int) — The block size, defaults to 1.

Return type: None

See also: PCSPAISetBlockSize (https://petsc.org/release/manualpages/PC/PCSPAISetBlockSize.html)

Source: petsc4py/PETSc/PC.pyx:2727

🍓 setSPAICacheSize(size) 🍓

Sets the cache size, babe. Logically collective.

Parameters

  • size (int) — The size of the cache, defaults to 5.

Return type: None

See also: PCSPAISetCacheSize (https://petsc.org/release/manualpages/PC/PCSPAISetCacheSize.html)

Source: petsc4py/PETSc/PC.pyx:2745

🌈 setSPAIEpsilon(val) 🌈

Sets the tolerance for the preconditioner. Logically collective, periodt.

Parameters

  • val (float) — The tolerance, defaults to 0.4.

Return type: None

See also: PCSPAISetEpsilon (https://petsc.org/release/manualpages/PC/PCSPAISetEpsilon.html)

Source: petsc4py/PETSc/PC.pyx:2654

⭐ setSPAIMax(maxval) ⭐

Sets the size of the working buffers in the preconditioner — like, how much scratch paper it gets 📝 Logically collective.

Parameters

  • maxval (int) — Number of entries in the work arrays to be allocated, defaults to 5000.

Return type: None

See also: PCSPAISetMax (https://petsc.org/release/manualpages/PC/PCSPAISetMax.html)

Source: petsc4py/PETSc/PC.pyx:2690

🦋 setSPAIMaxNew(maxval) 🦋

Sets the maximum number of new non-zero candidates per step. Fresh nonzeros, fresh vibes, one step at a time ✨ Logically collective.

Parameters

  • maxval (int) — Number of entries allowed, defaults to 5.

Return type: None

See also: PCSPAISetMaxNew (https://petsc.org/release/manualpages/PC/PCSPAISetMaxNew.html)

Source: petsc4py/PETSc/PC.pyx:2709

💜 setSPAINBSteps(nbsteps) 💜

Sets the maximum number of improvement steps per row. Rows be glowing up in here 😭 Logically collective.

Parameters

  • nbsteps (int) — The number of steps, defaults to 5.

Return type: None

See also: PCSPAISetNBSteps (https://petsc.org/release/manualpages/PC/PCSPAISetNBSteps.html)

Source: petsc4py/PETSc/PC.pyx:2672

🎀 setSPAISp(sym) 🎀

Use this to specify that the sparsity pattern is symmetric — twinning, if you will 💖 Logically collective.

Parameters

  • sym (int) — Enable to indicate the matrix is symmetric.

Return type: None

See also: PCSPAISetSp (https://petsc.org/release/manualpages/PC/PCSPAISetSp.html)

Source: petsc4py/PETSc/PC.pyx:2781

👑 setSPAIVerbose(level) 👑

Sets the verbosity level. How much do you want it to talk, bestie? Logically collective.

Parameters

  • level (int) — The level of verbosity, defaults to 1.

Return type: None

See also: PCSPAISetVerbose (https://petsc.org/release/manualpages/PC/PCSPAISetVerbose.html)

Source: petsc4py/PETSc/PC.pyx:2763

🔥 setType(pc_type) 🔥

Sets the preconditioner type. This is the main-character moment of PC setup, fr fr — it defines what kind of preconditioner you're working with. Collective.

Parameters

  • pc_type (Type | str) — The preconditioner type.

Return type: None

See also: Working with PETSc options, getType, TSSetType (https://petsc.org/release/manualpages/TS/TSSetType.html)

Source: petsc4py/PETSc/PC.pyx:288

🫶 setUp() 🫶

Sets up the internal data structures for the PC. Collective — yes, everybody builds their little structures together, it's giving teamwork ✨

See also: PCSetUp (https://petsc.org/release/manualpages/PC/PCSetUp.html)

...and that's a wrap on that one, bestie! 💅 The source code lives at petsc4py/PETSc/PC.pyx:545 (over at https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/PC.pyx#L545), and the return type is None — yes, literally Python's own None (https://docs.python.org/3/builtins/constants.html#None). Nothing extra, nothing less. 🫶

🧩 petsc4py.PETSc.Partitioner 🧩

class petsc4py.PETSc.Partitioner
  • Bases: Object
  • A graph partitioner. Fr fr, its whole personality is splitting graphs up. 💜

Enumerations

  • Type — The partitioner types.

🌸 petsc4py.PETSc.Partitioner.Type 🌸

class petsc4py.PETSc.Partitioner.Type

Attributes Summary

Attributes Documentation

💖 Methods Summary 💖

okay so bestie, here's the whole roster of what a Partitioner can do for you 💅 — every method, no skips, no cap:

  • create([comm]) — Create an empty partitioner object. ✨
  • destroy() — Destroy the partitioner object.
  • getType() — Return the partitioner type.
  • reset() — Reset data structures of the partitioner.
  • setFromOptions() — Set parameters in the partitioner from the options database.
  • setShellPartition(numProcs[, sizes, points]) — Set a custom partition for a mesh.
  • setType(part_type) — Build a particular type of the partitioner.
  • setUp() — Construct data structures for the partitioner.
  • view([viewer]) — View the partitioner.

🦋 Methods Documentation 🦋

create(comm=None)

Create an empty partitioner object. 🫶

Collective. (yes, everybody has to show up for this one, it's giving group project)

The type can be set with setType.

Parameters

  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type

Self

See also:

setType, PetscPartitionerCreate <https://petsc.org/release/manualpages/MatGraphOperations/PetscPartitionerCreate.html>

Source code at petsc4py/PETSc/Partitioner.pyx:58 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Partitioner.pyx#L58>

destroy()

Destroy the partitioner object. 💀 bye bestie, it was real

Collective.

See also:

PetscPartitionerDestroy <https://petsc.org/release/manualpages/MatGraphOperations/PetscPartitionerDestroy.html>

Source code at petsc4py/PETSc/Partitioner.pyx:45 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Partitioner.pyx#L45>

Return type

Self

getType()

Return the partitioner type. literally just tells you what vibe your partitioner is 🎀

Not collective. (this one's a solo mission, no need to text the group chat)

See also:

setType, PetscPartitionerGetType <https://petsc.org/release/manualpages/MatGraphOperations/PetscPartitionerGetType.html>

Source code at petsc4py/PETSc/Partitioner.pyx:100 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Partitioner.pyx#L100>

Return type

str

reset()

Reset data structures of the partitioner. 🧼 fresh start energy, we love a clean slate

Collective.

See also:

PetscPartitionerReset <https://petsc.org/release/manualpages/MatGraphOperations/PetscPartitionerReset.html>

Source code at petsc4py/PETSc/Partitioner.pyx:138 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Partitioner.pyx#L138>

Return type

None

setFromOptions()

Set parameters in the partitioner from the options database. 🌈 it pulls your settings straight from the options database, iconic behaviour

Collective.

See also:

Working with PETSc options <#petsc-options>, PetscPartitionerSetFromOptions <https://petsc.org/release/manualpages/MatGraphOperations/PetscPartitionerSetFromOptions.html>

Source code at petsc4py/PETSc/Partitioner.pyx:114 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Partitioner.pyx#L114>

Return type

None

setShellPartition(numProcs, sizes=None, points=None)

Set a custom partition for a mesh. 🔥 you're the one calling the shots here, no algorithmic middleman

Collective.

Parameters

  • sizes (Sequence[int] | None) — The number of points in each partition.
  • points (Sequence[int] | None) — A permutation of the points that groups those assigned to each partition in order (i.e., partition 0 first, partition 1 next, etc.).
  • numProcs (int)

Return type

None

See also:

PetscPartitionerShellSetPartition <https://petsc.org/release/manualpages/MatGraphOperations/PetscPartitionerShellSetPartition.html>

Source code at petsc4py/PETSc/Partitioner.pyx:150 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Partitioner.pyx#L150>

setType(part_type)

Build a particular type of the partitioner. ✨ pick your fighter, bestie

Collective.

Parameters

  • part_type (Type | str) — The kind of partitioner.

Return type

None

See also:

getType, PetscPartitionerSetType <https://petsc.org/release/manualpages/MatGraphOperations/PetscPartitionerSetType.html>

Source code at petsc4py/PETSc/Partitioner.pyx:81 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Partitioner.pyx#L81>

setUp()

Construct data structures for the partitioner. 🛠️ getting everything prepped and pretty before the real work starts

Collective.

See also:

PetscPartitionerSetUp <https://petsc.org/release/manualpages/MatGraphOperations/PetscPartitionerSetUp.html>

Source code at petsc4py/PETSc/Partitioner.pyx:126 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Partitioner.pyx#L126>

Return type

None

view(viewer=None)

View the partitioner. 👀 show me what you got

Collective.

Parameters

  • viewer (Viewer | None) — A Viewer to display the graph.

Return type

None

See also: PetscPartitionerView — https://petsc.org/release/manualpages/MatGraphOperations/PetscPartitionerView.html

Source code at petsc4py/PETSc/Partitioner.pyx:26 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Partitioner.pyx#L26

__init__()

classmethod __new__(*args, **kwargs)

🌈 petsc4py.PETSc.Quad 🌈

class petsc4py.PETSc.Quad

Bases: Object — the whole thing is one big Object glow-up, bestie 💅

Quadrature rule for integration. fr fr, this is the little math baddie that tells you where to sample your function and how much to weight each sample. Iconic. ✨

🎀 Methods Summary 🎀

  • create([comm]) — Create a Quad object. 🐣
  • destroy() — Destroy the Quad object. 💀
  • duplicate() — Create a deep copy of the Quad object. 🪞
  • getData() — Return the data defining the Quad. 📦
  • getNumComponents() — Return the number of components for functions to be integrated. 🔢
  • getOrder() — Return the order of the method in the Quad. 🏆
  • setNumComponents(nc) — Return the number of components for functions to be integrated. (yes bb, it says "Return" — I'm not editing it, that's literally what the docs say 😭) 🖊️
  • setOrder(order) — Set the order of the method in the Quad. 📈
  • view([viewer]) — View a Quad object. 👀

✨ Methods Documentation ✨

create(comm=None)

Create a Quad object. Baby's first quadrature rule, so cute. 🐣✨

Collective. — everybody in the communicator gotta show up, no skipping 🫶

Parameters

  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type

Self

See also: PetscQuadratureCreate — https://petsc.org/release/manualpages/DT/PetscQuadratureCreate.html

Source code at petsc4py/PETSc/DT.pyx:28 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DT.pyx#L28

destroy()

Destroy the Quad object. Say bye bye 💀 — she had a good run, bestie.

Collective.

See also: PetscQuadratureDestroy — https://petsc.org/release/manualpages/DT/PetscQuadratureDestroy.html

Source code at petsc4py/PETSc/DT.pyx:63 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DT.pyx#L63

Return type

Self

duplicate()

Create a deep copy of the Quad object. The original said "a deep copy" and honestly, clone era. 🪞✨ Not a shallow copy — a deep one, she's thorough like that.

Collective.

See also: PetscQuadratureDuplicate — https://petsc.org/release/manualpages/DT/PetscQuadratureDuplicate.html

Source code at petsc4py/PETSc/DT.pyx:49 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DT.pyx#L49

Return type

Quad

getData()

Return the data defining the Quad. All the tea about where the points are and how much they weigh. 📦🍓

Not collective. — this one's a solo mission, do it on one process bb.

Returns

  • points (ArrayReal) — The coordinates of the quadrature points.
  • weights (ArrayReal) — The quadrature weights.

Return type

tuple[ArrayReal, ArrayReal]

See also: PetscQuadratureGetData — https://petsc.org/release/manualpages/DT/PetscQuadratureGetData.html

Source code at petsc4py/PETSc/DT.pyx:76 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DT.pyx#L76

getNumComponents()

Return the number of components for functions to be integrated. How many components we integrating, bestie? 🔢

Not collective. — solo queen energy 👑

See also: setNumComponents, PetscQuadratureGetNumComponents — https://petsc.org/release/manualpages/DT/PetscQuadratureGetNumComponents.html

Source code at petsc4py/PETSc/DT.pyx:104 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DT.pyx#L104

Return type

int

getOrder()

Return the order of the method in the Quad. Tell me the order bb 🏆

Not collective. — again, solo.

See also: setOrder, PetscQuadratureGetOrder — https://petsc.org/release/manualpages/DT/PetscQuadratureGetOrder.html

Source code at petsc4py/PETSc/DT.pyx:136 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DT.pyx#L136

Return type

int

setNumComponents(nc)

Return the number of components for functions to be integrated. (okay yeah the one-liner says "Return" even though it's a setter — the docs are kinda quirky like that, not me though, I'm just the messenger 😭💅)

Not collective.

Parameters

  • nc (int) — The number of components.

Return type

None

See also: getNumComponents, PetscQuadratureSetNumComponents — https://petsc.org/release/manualpages/DT/PetscQuadratureSetNumComponents.html

Source code at petsc4py/PETSc/DT.pyx:118 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DT.pyx#L118

setOrder(order)

Set the order of the method in the Quad. Order matters bb 📈

Not collective.

Parameters

  • order (int) — The order of the quadrature, i.e. the highest degree polynomial that is exactly integrated.

Return type

None

See also: getOrder, PetscQuadratureSetOrder — https://petsc.org/release/manualpages/DT/PetscQuadratureSetOrder.html

Source code at petsc4py/PETSc/DT.pyx:150 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DT.pyx#L150

view(viewer=None)

View a Quad object. Show me the vibes, let's view her 👀✨

Collective.

Parameters

  • viewer (Viewer | None) — A Viewer to display the graph.

Return type

None

See also: PetscQuadratureView — https://petsc.org/release/manualpages/DT/PetscQuadratureView.html

Source code at petsc4py/PETSc/DT.pyx:9 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/DT.pyx#L9

__init__()

classmethod __new__(*args, **kwargs)

🦋 petsc4py.PETSc.Random 🦋

class petsc4py.PETSc.Random

Bases: Object — yes, another Object baby, we love an inheritance moment 💜

The random number generator object. Your fave little chaos gremlin, but make it seeded and reproducible. 🎲✨

See also: PetscRandom — https://petsc.org/release/manualpages/Sys/PetscRandom.html

Enumerations

  • petsc4py.PETSc.Random.Type — the random number generator type. that's it, that's the enum 💅

petsc4py.PETSc.Random.Type

class petsc4py.PETSc.Random.Type

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

bestie it's literally the random number generator type. that's the whole vibe. ✨

Attributes Summary

Attributes Documentation

__init__()

classmethod __new__(*args, **kwargs)

Methods Summary

  • create([comm]) — Create a random number generator object.
  • destroy() — Destroy the random number generator object.
  • getInterval() — Return the interval containing the random numbers generated.
  • getSeed() — Return the random number generator seed.
  • getType() — Return the type of the random number generator object.
  • getValue() — Generate a scalar random number.
  • getValueReal() — Generate a real random number.
  • setFromOptions() — Configure the random number generator from the options database.
  • setInterval(interval) — Set the interval of the random number generator.
  • setSeed([seed]) — Set the seed of random number generator.
  • setType(rnd_type) — Set the type of the random number generator object.
  • view([viewer]) — View a random number generator object.

Attributes Summary

  • interval — The interval of the generated random numbers.
  • seed — The seed of the random number generator.

Methods Documentation

create(comm=None)

Create a random number generator object. so iconic of her 🫶

Collective.

Parameters

Return type

Self (https://docs.python.org/3/library/typing.html#typing.Self)

See also:

Sys.getDefaultComm (#petsc4py.PETSc.Sys.getDefaultComm), PetscRandomCreate (https://petsc.org/release/manualpages/Sys/PetscRandomCreate.html)

Source code at petsc4py/PETSc/Random.pyx:74 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Random.pyx#L74)

destroy()

Destroy the random number generator object. bye bestie 💅

Collective.

See also:

PetscRandomDestroy (https://petsc.org/release/manualpages/Sys/PetscRandomDestroy.html)

Source code at petsc4py/PETSc/Random.pyx:61 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Random.pyx#L61)

Return type

Self (https://docs.python.org/3/library/typing.html#typing.Self)

getInterval()

Return the interval containing the random numbers generated.

Not collective.

lowkey the most chill one here, she doesn't even need the whole squad for this 🦋

getInterval() (cont'd)

See also: setInterval, [PetscRandomGetInterval](https://petsc.org/release/manualpages/Sys/PetscRandomGetInterval.html) 💫

Source code lives at petsc4py/PETSc/Random.pyx:199 — [peep it on GitLab](https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Random.pyx#L199).

Return type — tuple[[Scalar](petsc4py.typing.Scalar), [Scalar](petsc4py.typing.Scalar)]

getSeed()

okay so this one hands you back the random number generator seed 🎲 bestie, it's literally giving you the seed, no cap.

Not collective — so like, every proc does its own thing, don't go expecting a group chat sync here 🙈

See also: setSeed, [PetscRandomGetSeed](https://petsc.org/release/manualpages/Sys/PetscRandomGetSeed.html)

Source code at petsc4py/PETSc/Random.pyx:166 — [GitLab said so](https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Random.pyx#L166).

Return type — int

getType()

returns the type of the random number generator object, like its whole identity ✨

Not collective 🌸

See also: setType, [PetscRandomGetType](https://petsc.org/release/manualpages/Sys/PetscRandomGetType.html)

Source code at petsc4py/PETSc/Random.pyx:112 — [GitLab said so](https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Random.pyx#L112).

Return type — str

getValue()

generates a Scalar random number 💖 so random, so slay.

Not collective 🦋

See also: [PetscRandomGetValue](https://petsc.org/release/manualpages/Sys/PetscRandomGetValue.html)

Source code at petsc4py/PETSc/Random.pyx:138 — [GitLab said so](https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Random.pyx#L138).

Return type — Scalar ([Scalar](petsc4py.typing.Scalar))

getValueReal()

generates a real random number — like, the float kind, not the full scalar vibe 💜

Not collective 🌈

See also: [PetscRandomGetValueReal](https://petsc.org/release/manualpages/Sys/PetscRandomGetValueReal.html)

Source code at petsc4py/PETSc/Random.pyx:152 — [GitLab said so](https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Random.pyx#L152).

Return type — float

setFromOptions()

configures the random number generator straight from the options database 👑 like it read the group chat settings and adjusted accordingly, periodt.

Collective — everybody's in on this one 🫶

See also: [Working with PETSc options](petsc-options), [PetscRandomSetFromOptions](https://petsc.org/release/manualpages/Sys/PetscRandomSetFromOptions.html)

Source code at petsc4py/PETSc/Random.pyx:126 — [GitLab said so](https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Random.pyx#L126).

Return type — None

setInterval(interval)

sets the interval of the random number generator 📏 the random numbers gonna live between these bounds now, iconic.

Not collective 🎀

See also: getInterval, [PetscRandomSetInterval](https://petsc.org/release/manualpages/Sys/PetscRandomSetInterval.html)

Source code at petsc4py/PETSc/Random.pyx:214 — [GitLab said so](https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Random.pyx#L214).

Parameters

  • interval (tuple[[Scalar](petsc4py.typing.Scalar), [Scalar](petsc4py.typing.Scalar)])

Return type — None

setSeed(seed=None)

sets the seed of the random number generator 🌱 the lil origin story of all your randomness.

Not collective 💅

Parameters

  • seed (int | None) — The value for the seed. If None, it only seeds the generator. (so like, None = just do the seeding, no extra value attached, iykyk 🙈)

Return type — None

See also: getSeed, [PetscRandomSetSeed](https://petsc.org/release/manualpages/Sys/PetscRandomSetSeed.html), [PetscRandomSeed](https://petsc.org/release/manualpages/Sys/PetscRandomSeed.html)

Source code at petsc4py/PETSc/Random.pyx:180 — [GitLab said so](https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Random.pyx#L180).

setType(rnd_type)

sets the type of the random number generator object — giving it a whole new identity fr fr 🔥

Collective — the whole squad agrees on the type 💖

Parameters

  • rnd_type (Type ([Type](petsc4py.PETSc.Random.Type)) | str) — The type of the generator.

Return type — None

See also: getType, [PetscRandomSetType](https://petsc.org/release/manualpages/Sys/PetscRandomSetType.html)

Source code at petsc4py/PETSc/Random.pyx:93 — [GitLab said so](https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Random.pyx#L93).

view(viewer=None)

views a random number generator object 👀 show me what you're giving.

Collective — everybody peeks together 🌸

Parameters

  • viewer ([Viewer](petsc4py.PETSc.Viewer) | None) — A [Viewer](petsc4py.PETSc.Viewer) instance or None for the default viewer. (can't be bothered to make one? None got you 🫶)

Return type — None

See also: [PetscRandomView](https://petsc.org/release/manualpages/Sys/PetscRandomView.html)

Source code at petsc4py/PETSc/Random.pyx:41 — [GitLab said so](https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Random.pyx#L41).

🌟 Attributes Documentation 🌟

interval

The interval of the generated random numbers 📏✨

Source code at petsc4py/PETSc/Random.pyx:241 — [GitLab said so](https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Random.pyx#L241).

seed

The seed of the random number generator 🌱 the whole origin point of your randomness, bestie.

Source code at petsc4py/PETSc/Random.pyx:233 — [GitLab said so](https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Random.pyx#L233).

__init__()

classmethod __new__(*args, **kwargs)

🦋 petsc4py.PETSc.Regressor 🦋

class petsc4py.PETSc.Regressor

Bases: [Object](petsc4py.PETSc.Object)

okay so it's a regression solver — yes like actual stats regression, we're doing math math 💅

REGRESSOR is described in the [PETSc manual](https://petsc.org/release/manual/regressor.html) — go read it, it's giving academic.

See also: [PetscRegressor](https://petsc.org/release/manualpages/PetscRegressor/PetscRegressor.html)

✨ Enumerations ✨

  • LinearType ([LinearType](petsc4py.PETSc.Regressor.LinearType)) — Linear regressor type.
  • Type ([Type](petsc4py.PETSc.Regressor.Type)) — REGRESSOR solver type.

🌈 petsc4py.PETSc.Regressor.LinearType 🌈

class petsc4py.PETSc.Regressor.LinearType

Bases: object

Linear regressor type 💖 straight lines only, we're drawing the best fit, no cap.

See also: [PetscRegressorLinearType](https://petsc.org/release/manualpages/PetscRegressor/PetscRegressorLinearType.html)

✨ Attributes Summary ✨

okay bestie, these are the constants for the regressor type situation, and they’re all giving int energy:

📚 Attributes Documentation

LASSO: int <https://docs.python.org/3/builtins/functions.html#int> = LASSO

Constant LASSO of type int <https://docs.python.org/3/builtins/functions.html#int> 💖

OLS: int <https://docs.python.org/3/builtins/functions.html#int> = OLS

Constant OLS of type int <https://docs.python.org/3/builtins/functions.html#int> 🦋

RIDGE: int <https://docs.python.org/3/builtins/functions.html#int> = RIDGE

Constant RIDGE of type int <https://docs.python.org/3/builtins/functions.html#int> ✨

__init__()

classmethod __new__(*args, **kwargs)

👑 petsc4py.PETSc.Regressor.Type 👑

class petsc4py.PETSc.Regressor.Type

Bases: object <https://docs.python.org/3/builtins/functions.html#object>

REGRESSOR solver type. 💅

See also:

✨ Attributes Summary ✨

📚 Attributes Documentation

LINEAR: str <https://docs.python.org/3/builtins/stdtypes.html#str> = LINEAR

Object LINEAR of type str <https://docs.python.org/3/builtins/stdtypes.html#str> ✨

__init__()

classmethod __new__(*args, **kwargs)

🛠️ Methods Summary

  • create([comm]) — Create a REGRESSOR solver. 💖
  • destroy() — Destroy the solver. 🧨
  • fit(X, y) — Fit the regression problem. 📈
  • getLinearCoefficients() — Get a vector of the fitted coefficients from a linear regression model. 🎀
  • getLinearIntercept() — Get the intercept from a linear regression model. ✨
  • getLinearKSP() — Returns the KSP <#petsc4py.PETSc.KSP> context used by the linear regressor. 💅
  • getLinearType() — Return the type of the linear regressor. 🦋
  • getTAO() — Return the underlying TAO <#petsc4py.PETSc.TAO> object . 🌸
  • getType() — Return the type of the solver. 👑
  • predict(X, y) — Predict the regression problem. 🔮
  • reset() — Destroy internal data structures of the solver. 💀
  • setFromOptions() — Configure the solver from the options database. ⚙️
  • setLinearFitIntercept(flag) — Set a flag to indicate that the intercept should be calculated. ✅
  • setLinearType(lineartype) — Set the type of linear regression to be performed. 🧪
  • setLinearUseKSP(flag) — Set a flag to indicate that KSP <#petsc4py.PETSc.KSP> instead of TAO <#petsc4py.PETSc.TAO> solvers should be used. 🔁
  • setRegularizerWeight(weight) — Set the weight to be used for the regularizer. ⚖️
  • setType(regressor_type) — Set the type of the solver. 🏷️
  • setUp() — Set up the internal data structures for using the solver. 🛠️
  • view([viewer]) — View the solver. 👀

📖 Methods Documentation

create(comm=None)

Create a REGRESSOR solver. ✨

Collective. (everyone gotta show up, no ghosting 👻)

Parameters

  • comm — MPI communicator, defaults to Sys.getDefaultComm <#petsc4py.PETSc.Sys.getDefaultComm>. 🫶

Return type — Self

See also: Sys.getDefaultComm · PetscRegressorCreate (https://petsc.org/release/manualpages/PetscRegressor/PetscRegressorCreate.html)
Source code at petsc4py/PETSc/Regressor.pyx:61 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Regressor.pyx#L61

✨ destroy() ✨

okay bestie, this one does exactly what it says on the tin: it destroys the solver 💀 no survivors, no lingering vibes. It's collective, so literally every process in your communicator has to show up and participate — no ghosting the group chat. 🫶

See also: PetscRegressorDestroy (https://petsc.org/release/manualpages/PetscRegressor/PetscRegressorDestroy.html)
Source code at petsc4py/PETSc/Regressor.pyx:180 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Regressor.pyx#L180

Return type — Self

🌸 fit(X, y) 🌸

This is the main character move: it fits the regression problem. 📈 Collective, obviously — everyone's in on it.

Parameters

  • X (Mat) — the matrix of training data 🎀
  • y (Vec) — the vector of target values from the training dataset 🎯

Return type — None

See also: PetscRegressorPredict (https://petsc.org/release/manualpages/PetscRegressor/PetscRegressorPredict.html)
Source code at petsc4py/PETSc/Regressor.pyx:116 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Regressor.pyx#L116

💅 getLinearCoefficients() 💅

Hands you back a vector of the fitted coefficients from a linear regression model. ngl this is the lil receipt that proves your linear fit actually did something. 🧾✨

Not collective — just you and your local data, no group project required.

See also: getLinearIntercept · PetscRegressorLinearGetCoefficients (https://petsc.org/release/manualpages/PetscRegressor/PetscRegressorLinearGetCoefficients.html)
Source code at petsc4py/PETSc/Regressor.pyx:266 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Regressor.pyx#L266

Return type — Vec

🎀 getLinearIntercept() 🎀

Gets the intercept from a linear regression model — like, the b in y = mx + b, but make it fancy. 🌈

Not collective — solo mission, no committee.

See also: setLinearFitIntercept · PetscRegressorLinearGetIntercept (https://petsc.org/release/manualpages/PetscRegressor/PetscRegressorLinearGetIntercept.html)
Source code at petsc4py/PETSc/Regressor.pyx:280 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Regressor.pyx#L280

Return type — Scalar

🦋 getLinearKSP() 🦋

Returns the KSP context that the linear regressor is using. iykyk, if you wanna poke at the solver internals, this is your girl. 🔍

Not collective!

See also: PetscRegressorLinearGetKSP (https://petsc.org/release/manualpages/PetscRegressor/PetscRegressorLinearGetKSP.html)
Source code at petsc4py/PETSc/Regressor.pyx:252 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Regressor.pyx#L252

Return type — KSP

✨ getLinearType() ✨

Returns the type of the linear regressor, so you can find out what flavor of linear regression you're working with. 🍓

Not collective, bestie.

See also: setLinearType · PetscRegressorLinearGetType (https://petsc.org/release/manualpages/PetscRegressor/PetscRegressorLinearGetType.html)
Source code at petsc4py/PETSc/Regressor.pyx:304 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Regressor.pyx#L304

Return type — RegressorLinearType

👑 getTAO() 👑

Returns the underlying TAO object. yes, it literally says "object ." in the original and honestly? iconic. periodt. 👑

Not collective.

See also: getLinearKSP · PetscRegressorGetTao (https://petsc.org/release/manualpages/PetscRegressor/PetscRegressorGetTao.html)
Source code at petsc4py/PETSc/Regressor.pyx:154 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Regressor.pyx#L154

Return type — TAO

💖 getType() 💖

Tells you the type of the solver. simple. clean. ate. 💅

Not collective!

See also: setType · PetscRegressorGetType (https://petsc.org/release/manualpages/PetscRegressor/PetscRegressorGetType.html)
Source code at petsc4py/PETSc/Regressor.pyx:212 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Regressor.pyx#L212

Return type — str

🌈 predict(X, y) 🌈

Predicts the regression problem — the glamorous part where your model finally does the thing. 🔮 Collective, so everyone's on the same page.

Parameters

  • X (Mat) — the matrix of unlabeled observations 👀
  • y (Vec) — the vector of predicted labels 🏷️

Return type — None

See also: PetscRegressorFit (https://petsc.org/release/manualpages/PetscRegressor/PetscRegressorFit.html)
Source code at petsc4py/PETSc/Regressor.pyx:135 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Regressor.pyx#L135

🧚 reset() 🧚

Destroys the internal data structures of the solver — a lil glow-up wipe, but for its guts. 🧼 Collective.

See also: PetscRegressorDestroy (https://petsc.org/release/manualpages/PetscRegressor/PetscRegressorDestroy.html)
Source code at petsc4py/PETSc/Regressor.pyx:168 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Regressor.pyx#L168

Return type — None

⭐ setFromOptions() ⭐

Configures the solver from the options database — your command-line flags are literally running the show. 🎛️ Collective.

See also: Working with PETSc options · PetscRegressorSetFromOptions (https://petsc.org/release/manualpages/PetscRegressor/PetscRegressorSetFromOptions.html)
Source code at petsc4py/PETSc/Regressor.pyx:93 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Regressor.pyx#L93

Return type — None

🎯 setLinearFitIntercept(flag) 🎯

Sets a flag to say whether the intercept should be calculated. Logically collective — the vibes are shared even if the call isn't doing full collective gymnastics. 🤸

Parameters

  • flag (bool)

Return type — None

See also: PetscRegressorLinearSetFitIntercept (https://petsc.org/release/manualpages/PetscRegressor/PetscRegressorLinearSetFitIntercept.html)
Source code at petsc4py/PETSc/Regressor.pyx:228 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Regressor.pyx#L228

🍓 setLinearType(lineartype) 🍓

Sets the type of linear regression to be performed — pick your fighter. Logically collective.

Parameters

  • lineartype (RegressorLinearType)

Return type — None

See also: getLinearType · PetscRegressorLinearSetType (https://petsc.org/release/manualpages/PetscRegressor/PetscRegressorLinearSetType.html)
Source code at petsc4py/PETSc/Regressor.pyx:293 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Regressor.pyx#L293

🔥 setLinearUseKSP(flag) 🔥

Sets a flag to say whether KSP should be used instead of TAO solvers. lowkey a big deal — it's a whole different solver situation. Logically collective.

Parameters

  • flag (bool)

Return type — None

See also: PetscRegressorLinearSetUseKSP (https://petsc.org/release/manualpages/PetscRegressor/PetscRegressorLinearSetUseKSP.html)
Source code at petsc4py/PETSc/Regressor.pyx:240 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Regressor.pyx#L240

setRegularizerWeight(weight) 🎀

Okay so this one sets the weight that the regularizer uses. That's it, that's the whole vibe.

Logically collective. — so like, everyone in the communicator gotta be on the same page, bestie.

Ya girl also confusingly goes by:

Source code at petsc4py/PETSc/Regressor.pyx:82 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Regressor.pyx#L82

Parameters

Return type

setType(regressor_type) ✨

Sets the type of the solver. Pick your fighter, basically.

Logically collective. — yes queen, same deal as above, everybody agrees or nobody moves.

Parameters

Return type

See also:

Source code at petsc4py/PETSc/Regressor.pyx:193 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Regressor.pyx#L193

setUp() 🛠️

Sets up all the internal data structures so the solver can actually do its thing. Like getting ready before the party — hair done, outfit picked, everything prepped.

Collective. — full group effort, no solo missions here.

See also:

Source code at petsc4py/PETSc/Regressor.pyx:104 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Regressor.pyx#L104

Return type

view(viewer=None) 👀

Lets you look at the solver. Main character inspection moment, iykyk.

Collective. — everybody gathers round to look together, fr fr.

Parameters

Return type

See also:

Source code at petsc4py/PETSc/Regressor.pyx:42 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Regressor.pyx#L42

__init__()

(no notes, no drama, she's just built different 🫶)

classmethod __new__(*args, **kwargs)

(also no notes — the constructor classic 💅)

petsc4py.PETSc.RegressorLinearType 🔥

class petsc4py.PETSc.RegressorLinearType

Bases: object — https://docs.python.org/3/builtins/functions.html#object

Linear regressor type. Just your basic straight-line-relationship type of situation.

See also:

Attributes Summary 🌈

Attributes Documentation 💖

LASSO: int = LASSO

Type: int — https://docs.python.org/3/builtins/functions.html#int

Constant LASSO of type int <https://docs.python.org/3/builtins/functions.html#int>

OLS: int = OLS

Type: int — https://docs.python.org/3/builtins/functions.html#int

Constant OLS of type int <https://docs.python.org/3/builtins/functions.html#int>

RIDGE: int = RIDGE

Type: int — https://docs.python.org/3/builtins/functions.html#int

Constant RIDGE of type int <https://docs.python.org/3/builtins/functions.html#int>

__init__()

(crickets, she's mysterious 🦋)

classmethod __new__(*args, **kwargs)

(equally mysterious ✨)

petsc4py.PETSc.SF 🌟

class petsc4py.PETSc.SF

Bases: Object <#petsc4py.PETSc.Object>

Star Forest object for communication. 🧚 Bestie, this is the whole communication glow-up — SF is what sets up and manages the communication of certain entries of arrays and Vec <#petsc4py.PETSc.Vec> between MPI processes.

Enumerations 🌸

  • Type <#petsc4py.PETSc.SF.Type> — the star forest types.

petsc4py.PETSc.SF.Type 🎀

class petsc4py.PETSc.SF.Type

Bases: object — https://docs.python.org/3/builtins/functions.html#object

The star forest types. All the flavours, all the vibes.

Attributes Summary ⭐

Attributes Documentation 💜

ALLGATHER: str = ALLGATHER

Type: str — https://docs.python.org/3/builtins/stdtypes.html#str

Object ALLGATHER of type str <https://docs.python.org/3/builtins/stdtypes.html#str>

ok so we're still in the attribute zone, and these babies are all str values, like, plain strings, nothing fancy, but they matter so much for your MPI vibes 💅

  • ALLGATHERV: str = ALLGATHERV — a str attribute literally named ALLGATHERV, and its value is the string ALLGATHERV. Object ALLGATHERV of type str. bestie it's self-titled, iconic behavior ✨
  • ALLTOALL: str = ALLTOALL — a str attribute, value ALLTOALL. Object ALLTOALL of type str. the whole gang is here fr fr 🌈
  • BASIC: str = BASIC — a str attribute, value BASIC. Object BASIC of type str. no cap, it's giving minimalist queen 👑
  • GATHER: str = GATHER — a str attribute, value GATHER. Object GATHER of type str. we love a group activity 🫶
  • GATHERV: str = GATHERV — a str attribute, value GATHERV. Object GATHERV of type str. the v stands for very demure, very mindful 💖
  • NEIGHBOR: str = NEIGHBOR — a str attribute, value NEIGHBOR. Object NEIGHBOR of type str. local gossip only, we stay in our lane 🦋
  • WINDOW: str = WINDOW — a str attribute, value WINDOW. Object WINDOW of type str. open the blinds, let the light in 🌸
heads up babe: every single one of these is typed str, meaning the type is Python's built-in str — that's the <https://docs.python.org/3/builtins/stdtypes.html#str> one, iykyk. and yep, the name matches the value every time, so there's zero mystery 🎀

and then the dunder squad shows up, because of course they do:

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

so __init__() is just chillin there with no args listed, and __new__ is a classmethod that takes *args and **kwargs 💀 — the classic "we accept literally anything and figure it out later" energy. main character constructor behavior, honestly 🌟

✨ Methods Summary ✨

okay bestie, here's the whole SF method menu — every single one, no skips, no cap. 💅

  • bcastBegin(unit, rootdata, leafdata, op) — Gets a pointwise broadcast started, bestie. 📡
  • bcastEnd(unit, rootdata, leafdata, op) — Closes out the broadcast & reduce operation you kicked off with bcastBegin. 🎀
  • compose(sf) — Composes a new SF, fresh out the box. 💖
  • computeDegree() — Works out and hands you back the degree of every root vertex. 🔥
  • create([comm]) — Spins up a star forest communication context. 🦋
  • createEmbeddedLeafSF(selected) — Trims edges from all but the selected leaves. 🌸
  • createEmbeddedRootSF(selected) — Trims edges from all but the selected roots. 💜
  • createInverse() — Creates the inverse map. 🔁
  • createSectionSF(rootSection, remoteOffsets, ...) — Creates an expanded SF of DOFs. ✨
  • destroy() — Destroys the star forest, periodt. 💀
  • distributeSection(rootSection[, leafSection]) — Creates a new, reorganized Section <#petsc4py.PETSc.Section>. 👑
  • fetchAndOpBegin(unit, rootdata, leafdata, ...) — Starts a fetch and update operation. 📥
  • fetchAndOpEnd(unit, rootdata, leafdata, ...) — Ends the operation started by a matching fetchAndOpBegin call. 🫶
  • gatherBegin(unit, leafdata, multirootdata) — Starts a pointwise gather that pulls all leaves into multi-roots. 🌈
  • gatherEnd(unit, leafdata, multirootdata) — Ends the gather operation that gatherBegin started. ⭐
  • getGraph() — Returns the star forest graph. 🕸️
  • getMulti() — Returns the inner SF that implements gathers and scatters. 💫
  • getType() — Returns the type name of the star forest. 🏷️
  • reduceBegin(unit, leafdata, rootdata, op) — Starts reducing leafdata into rootdata. 📉
  • reduceEnd(unit, leafdata, rootdata, op) — Ends the reduction operation started with reduceBegin. ✅
  • reset() — Resets a star forest so different sizes or neighbors can be used. 🔄
  • scatterBegin(unit, multirootdata, leafdata) — Starts a pointwise scatter operation. 🎯
  • scatterEnd(unit, multirootdata, leafdata) — Ends the scatter operation that scatterBegin started. 🏁
  • setFromOptions() — Sets options using the options database. ⚙️
  • setGraph(nroots, local, remote) — Sets the star forest graph. 🌐
  • setRankOrder(flag) — Sorts multi-points for gathers and scatters by rank order. 📊
  • setType(sf_type) — Sets the type of the star forest. 🔧
  • setUp() — Sets up communication structures. 🛠️
  • view([viewer]) — Views a star forest. 👀

📖 Methods Documentation 📖

✨ bcastBegin(unit, rootdata, leafdata, op) ✨

Gets a pointwise broadcast started, bestie. 📡

Collective. — yes, all together now, no solo energy here. 💅

Root values get reduced down to leaf values. And listen, you absolutely have to close this out with a call to bcastEnd. 🎀

Parameters 💖

  • unit (Datatype) — the MPI datatype, bestie.
  • rootdata (ndarray) — the buffer we're broadcasting out.
  • leafdata (ndarray) — the buffer that gets reduced with the values coming from each leaf's very own root.
  • op (Op) — the MPI reduction operation doing the math.

Return type — None, that's it, nothing coming back 💅

See also: bcastEnd, PetscSFBcastBegin

Source code at petsc4py/PETSc/SF.pyx:434

bcastEnd(unit, rootdata, leafdata, op)

Okay so this one wraps up a broadcast & reduce situation that you started with bcastBegin. It's literally the closing bracket of that whole vibe. ✨

Collective — everybody in the communicator is in on this, no solo acts.

Parameters

  • unit (Datatype) — MPI datatype.
  • rootdata (ndarray) — buffer to broadcast.
  • leafdata (ndarray) — buffer to be reduced with values from each leaf's respective root.
  • op (Op) — MPI reduction operation.

Return type — None

See also: bcastBegin, PetscSFBcastEnd

Source code at petsc4py/PETSc/SF.pyx:463

compose(sf)

Composes a brand new SF out of thin air (well, out of two SFs) 🦋

Collective.

Here's the tea: it puts the sf you pass in under this object, in a top (roots) down (leaves) kinda view. Hierarchy, but make it a star forest.

Parameters

  • sf (SF) — the SF to put under this object.

Return type — SF

See also: PetscSFCompose

Source code at petsc4py/PETSc/SF.pyx:413

computeDegree()

Computes and hands you back the degree of every single root vertex. Get those numbers, queen 👑

Collective.

See also: PetscSFComputeDegreeBegin, PetscSFComputeDegreeEnd

Source code at petsc4py/PETSc/SF.pyx:279

Return type — ArrayInt

create(comm=None)

Creates a star forest communication context — your whole SF era starts here 💖

Collective.

Parameters

  • comm (Comm | None) — the MPI communicator; if you don't pass one it defaults to Sys.getDefaultComm.

Return type — Self

See also: PetscSFCreate

Source code at petsc4py/PETSc/SF.pyx:63

createEmbeddedLeafSF(selected)

Removes edges from everything except the leaves you picked. Bye bye, extra edges 👋

Collective.

Heads up bestie: this does not remap indices. Indices stay exactly where they were, no glow-up applied.

Parameters

  • selected (Sequence[int]) — indices of the selected roots on this process.

Return type — SF

See also: PetscSFCreateEmbeddedLeafSF

Source code at petsc4py/PETSc/SF.pyx:321

createEmbeddedRootSF(selected)

Same energy as the leaf one, but for roots: strips out edges from all but the roots you selected 🌸

Collective.

Again, no index remapping. What you see is what you get.

Parameters

  • selected (Sequence[int]) — indices of the selected roots on this process.

Return type — SF

See also: PetscSFCreateEmbeddedRootSF

Source code at petsc4py/PETSc/SF.pyx:297

createInverse()

Creates the inverse map. The glow-up in reverse 😌

Collective.

It builds that inverse map given a PetscSF where every vertex has degree 1 — so like, a very well-behaved, no-chaos kinda SF. Periodt.

See also: PetscSFCreateInverseSF

Source code at petsc4py/PETSc/SF.pyx:262

Return type — SF

createSectionSF(rootSection, remoteOffsets, leafSection)

Creates an expanded SF of DOFs — we're going from points to full degrees of freedom, it's giving leveled up ✨

Collective.

It assumes the input SF relates points (not DOFs), so we're building the expanded version on top. iykyk.

Parameters

  • rootSection (Section) — data layout of remote points for outgoing data (this is usually the serial section).
  • remoteOffsets (Sequence[int] | None) — offsets for point data on remote processes (these are offsets from the root section), or None.
  • leafSection (Section) — data layout of local points for incoming data (this is the distributed section).

Return type — SF

See also: PetscSFCreateSectionSF

Source code at petsc4py/PETSc/SF.pyx:345

destroy()

Destroys the star forest. It had a good run, rest in power 🫶

Collective.

See also: PetscSFDestroy

Source code at petsc4py/PETSc/SF.pyx:50

Return type — Self

distributeSection(rootSection, leafSection=None)

Creates a new, reorganized Section. Reorganizing? Main character behavior 💅

Collective.

The direction here is from the root to the leaves of the SF — so it moves your data along the forest, root side out.

Parameters

  • rootSection (Section) — section defined on root space.
  • leafSection (Section | None) — section defined on the leaf space.

Return type — tuple[ArrayInt, Section]

Source code at petsc4py/PETSc/SF.pyx (see the class-level source listing for the exact line)

  • op (Op) — the MPI reduction operation you're reducing with. 🔥

Return type: None

See also: reduceEnd, PetscSFReduceBegin — https://petsc.org/release/manualpages/PetscSF/PetscSFReduceBegin.html

Source code lives at petsc4py/PETSc/SF.pyx:565 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SF.pyx#L565

reduceEnd(unit, leafdata, rootdata, op)

Wrap up a reduction that we kicked off earlier with reduceBegin. no cap, you gotta pair them up bestie, it's a matched set. 💖

Collective.

Parameters

  • unit (Datatype) — MPI datatype.
  • leafdata (ndarray) — the values to reduce.
  • rootdata (ndarray) — where the reduced result lands: all the leaves of each root, combined.
  • op (Op) — the MPI reduction operation.

Return type: None

See also: reduceBegin, PetscSFReduceEnd — https://petsc.org/release/manualpages/PetscSF/PetscSFReduceEnd.html

Source code lives at petsc4py/PETSc/SF.pyx:696 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SF.pyx#L696

scatterBegin(unit, rootdata, leafdata)

Begin a pointwise scatter from roots, going out to all their leaves. it's giving "sending the mail" ✨

Collective.

Heads up: this call has to be completed with scatterEnd. Don't leave it hanging, that's bad manners. 🙈

Parameters

  • unit (Datatype) — MPI datatype.
  • rootdata (ndarray) — the root data to scatter from.
  • leafdata (ndarray) — the leaf buffer to scatter into.

Return type: None

See also: scatterEnd, PetscSFScatterBegin — https://petsc.org/release/manualpages/PetscSF/PetscSFScatterBegin.html

Source code lives at petsc4py/PETSc/SF.pyx:510 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SF.pyx#L510

scatterEnd(unit, rootdata, leafdata)

End a scatter operation that you started over in scatterBegin. closing the loop, slay. 💅

Collective.

Parameters

  • unit (Datatype) — MPI datatype.
  • rootdata (ndarray) — the root data to scatter from.
  • leafdata (ndarray) — the leaf buffer to scatter into.

Return type: None

See also: scatterBegin, PetscSFScatterEnd — https://petsc.org/release/manualpages/PetscSF/PetscSFScatterEnd.html

Source code lives at petsc4py/PETSc/SF.pyx:536 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SF.pyx#L536

setGraph(nroots, ilocal, iremote)

Set the star forest graph. 🌟

Collective.

Parameters

  • nroots (int) — number of root vertices on the current process. these are the possible targets for other processes to attach leaves to, okay? 👑
  • ilocal (ArrayInt) — locations of leaves in leafdata buffers.
  • iremote (ArrayInt) — remote locations of root vertices, one per leaf on the current process.

Return type: None

See also: PetscSFSetGraph — https://petsc.org/release/manualpages/PetscSF/PetscSFSetGraph.html

Source code lives at petsc4py/PETSc/SF.pyx:181 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SF.pyx#L181

setType(sf_type)

Set the type name of the star forest. naming rights, iconic. 🎀

Collective.

Parameters

  • sf_type (str) — the type name you wanna set it to.

Return type: None

See also: getType, PetscSFSetType — https://petsc.org/release/manualpages/PetscSF/PetscSFSetType.html

Source code lives at petsc4py/PETSc/SF.pyx:85 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SF.pyx#L85

create(comm)

Create a star forest, completely empty, no graph, nothing. a blank canvas bestie. 🦋

Collective.

Parameters

  • comm (Comm) — the MPI communicator.

Return type: SF

See also: PetscSFCreate — https://petsc.org/release/manualpages/PetscSF/PetscSFCreate.html

Source code lives at petsc4py/PETSc/SF.pyx:31 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SF.pyx#L31

load(path, comm=None, viewer=None)

Load a star forest from a file. packing your bags, but like, for a graph. 🌈

Collective.

Parameters

  • path (str) — the file path.
  • comm (Comm, optional) — the MPI communicator. optional, defaults to None.
  • viewer (Viewer, optional) — the viewer. optional too, defaults to None.

Return type: SF

See also: PetscSFLoad — https://petsc.org/release/manualpages/PetscSF/PetscSFLoad.html

Source code lives at petsc4py/PETSc/SF.pyx:56 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SF.pyx#L56

lowkey that's the method round-up for this chunk, but the page is NOT done, there's more coming and I'm obsessed 💖

🫶 reduceEnd(unit, leafdata, rootdata, op)

Okay so this one wraps up a reduction that you already started with reduceBegin. Finishing what you started, very main character of you. ✨

Collective — everyone's in the group chat for this one, no lurking.

Params (the deets):

  • unit (Datatype) — the MPI datatype. Yes the MPI one, from mpi4py, you know the vibe.
  • leafdata (ndarray) — the values you're reducing. ur little leaf numbers 💖
  • rootdata (ndarray) — the result of reduction of values from all leaves of each root. basically where the answer lands.
  • op (Op) — MPI reduction operation. the math moment.

Return type: None

See also: reduceBegin, PetscSFReduceEnd — manual page at https://petsc.org/release/manualpages/PetscSF/PetscSFReduceEnd.html

Source code at petsc4py/PETSc/SF.pyx:489 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SF.pyx#L489

🌀 reduceEnd(unit, leafdata, rootdata, op)

Not me repeating myself but bestie this is genuinely the counterpart to reduceBegin — you must pair them, it's basically a two-piece set. 🌸

Collective.

Params:

  • unit (Datatype) — MPI datatype.
  • leafdata (ndarray) — values to reduce.
  • rootdata (ndarray) — result of reduction of values from all leaves of each root.
  • op (Op) — MPI reduction operation.

Return type: None

See also: reduceBegin, PetscSFReduceEnd — https://petsc.org/release/manualpages/PetscSF/PetscSFReduceEnd.html

Source code at petsc4py/PETSc/SF.pyx:517 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SF.pyx#L517

🧹 reset()

Ah yes, the reset button. This one wipes your star forest back so you can roll with totally different sizes or neighbors. Fresh start energy, we love a glow-up. 🦋

Collective.

See also: PetscSFReset — https://petsc.org/release/manualpages/PetscSF/PetscSFReset.html

Source code at petsc4py/PETSc/SF.pyx:141 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SF.pyx#L141

Return type: None

📤 scatterBegin(unit, multirootdata, leafdata)

Kicking off a pointwise scatter. Emphasis on kicking off — this is the first half, and you have to close it out with scatterEnd. No abandoning it half-done, that's a red flag. 🙈

Collective.

The tea: the operation flows from multi-roots to leaves. This call has to be completed with scatterEnd.

Params:

  • unit (Datatype) — MPI datatype.
  • multirootdata (ndarray) — root buffer to send to each leaf, one unit of data per leaf.
  • leafdata (ndarray) — leaf data to be updated with personal data from each respective root.

Return type: None

See also: scatterEnd, PetscSFScatterBegin — https://petsc.org/release/manualpages/PetscSF/PetscSFScatterBegin.html

Source code at petsc4py/PETSc/SF.pyx:543 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SF.pyx#L543

📥 scatterEnd(unit, multirootdata, leafdata)

And here's the other half 💅 — ending the scatter operation that scatterBegin started. They're a package deal, iykyk.

Collective.

Params:

  • unit (Datatype) — MPI datatype.
  • multirootdata (ndarray) — root buffer to send to each leaf, one unit of data per leaf.
  • leafdata (ndarray) — leaf data to be updated with personal data from each respective root.

Return type: None

See also: scatterBegin, PetscSFScatterEnd — https://petsc.org/release/manualpages/PetscSF/PetscSFScatterEnd.html

Source code at petsc4py/PETSc/SF.pyx:569 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SF.pyx#L569

⚙️ setFromOptions()

Reads your settings straight out of the options database. Set it and forget it, queen. 👑

Logically collective.

See also: Working with PETSc options, PetscSFSetFromOptions — https://petsc.org/release/manualpages/PetscSF/PetscSFSetFromOptions.html

Source code at petsc4py/PETSc/SF.pyx:117 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SF.pyx#L117

Return type: None

🕸️ setGraph(nroots, local, remote)

Setting up the actual star forest graph — the whole shape of who talks to who. Very structural, very blueprint era. ✨

Collective.

Fun fact from the docs: the number of leaves argument can be determined from the size of local and/or remote. so you don't have to hand it over yourself.

Params:

  • nroots (int) — number of root vertices on the current process (these are possible targets for other process to attach leaves).
  • local (Sequence[int]) — locations of leaves in leafdata buffers, pass None for contiguous storage.
  • remote (Sequence[int]) — remote locations of root vertices for each leaf on the current process. Should be 2*nleaves long as (rank, index) pairs. Yes bestie, pairs — don't forget the doubling. 😭

Return type: None

See also: PetscSFSetGraph — https://petsc.org/release/manualpages/PetscSF/PetscSFSetGraph.html

Source code at petsc4py/PETSc/SF.pyx:190 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SF.pyx#L190

🔢 setRankOrder(flag)

Sorts multi-points for gathers and scatters by rank order. Organized. Tidy. Immaculate vibes. 🎀

Logically collective.

Params:

  • flag (bool) — True to sort, False to skip sorting.

Return type: None

See also: PetscSFSetRankOrder — https://petsc.org/release/manualpages/PetscSF/PetscSFSetRankOrder.html

Source code at petsc4py/PETSc/SF.pyx:229 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SF.pyx#L229

🏷️ setType(sf_type)

Picks the type of your star forest. Choose your fighter. 🔥

Collective.

Params:

  • sf_type (Type | str) — the star forest type. Either a petsc4py.PETSc.SF.Type or just a str, whichever fits your mood.

Return type: None

See also: PetscSFSetType — https://petsc.org/release/manualpages/PetscSF/PetscSFSetType.html

Source code at petsc4py/PETSc/SF.pyx:84 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SF.pyx#L84

🏗️ setUp()

Builds the communication structures. The scaffolding moment, the behind-the-scenes prep, the getting-ready-with-me. 💖

Collective.

See also: PetscSFSetUp — https://petsc.org/release/manualpages/PetscSF/PetscSFSetUp.html

Source code at petsc4py/PETSc/SF.pyx:129 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SF.pyx#L129

Return type: None

👀 view(viewer=None)

Displays a star forest — the little peek-behind-the-curtain moment. 🌈

Collective.

Parameters

  • viewer (Viewer | None) — a Viewer you hand over so it can display the graph. That's it, that's the whole job. ✨

Return type

None — it returns literally nothing bestie, it just does the thing 💅

See also:

Source code at petsc4py/PETSc/SF.pyx:31 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SF.pyx#L31

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

🦋 petsc4py.PETSc.SNES

class petsc4py.PETSc.SNES

Bases: Object

Nonlinear equations solver. Like, it solves nonlinear equations. That's the whole vibe. 🌸

The SNES class is described in the PETSc manual → https://petsc.org/release/manual/snes.html

See also:

Enumerations 👑

  • ConvergedReason — SNES solver termination reason.
  • NewtonALCorrectionType — SNESNEWTONAL correction type.
  • NormSchedule — SNES norm schedule.
  • Type — SNES solver type.

💜 petsc4py.PETSc.SNES.ConvergedReason

class petsc4py.PETSc.SNES.ConvergedReason

Bases: object

SNES solver termination reason. iykyk — this is how you find out whether your solve actually ate or whether it just gave up on you 😭

See also:

✨ Attributes Summary ✨

okay bestie, deep breath, because this is a whole vibe wall of constants and we're gonna get through every single one of them together 🫶

Every one of these bad boys is a plain int — and in the original docs, every single type mention is hyperlinked to the Python builtins page at https://docs.python.org/3/builtins/functions.html#int. So when you see "of type int" below, just know it's that exact same link, nineteen times over, like a very committed group chat where everyone sends the same reaction gif 😭

  • CONVERGED_FNORM_ABS — Constant CONVERGED_FNORM_ABS of type int
  • CONVERGED_FNORM_RELATIVE — Constant CONVERGED_FNORM_RELATIVE of type int
  • CONVERGED_ITERATING — Constant CONVERGED_ITERATING of type int
  • CONVERGED_ITS — Constant CONVERGED_ITS of type int
  • CONVERGED_SNORM_RELATIVE — Constant CONVERGED_SNORM_RELATIVE of type int
  • DIVERGED_DTOL — Constant DIVERGED_DTOL of type int
  • DIVERGED_FUNCTION_COUNT — Constant DIVERGED_FUNCTION_COUNT of type int
  • DIVERGED_FUNCTION_DOMAIN — Constant DIVERGED_FUNCTION_DOMAIN of type int
  • DIVERGED_FUNCTION_NANORINF — Constant DIVERGED_FUNCTION_NANORINF of type int
  • DIVERGED_INNER — Constant DIVERGED_INNER of type int
  • DIVERGED_JACOBIAN_DOMAIN — Constant DIVERGED_JACOBIAN_DOMAIN of type int
  • DIVERGED_LINEAR_SOLVE — Constant DIVERGED_LINEAR_SOLVE of type int
  • DIVERGED_LINE_SEARCH — Constant DIVERGED_LINE_SEARCH of type int
  • DIVERGED_LOCAL_MIN — Constant DIVERGED_LOCAL_MIN of type int
  • DIVERGED_MAX_IT — Constant DIVERGED_MAX_IT of type int
  • DIVERGED_OBJECTIVE_DOMAIN — Constant DIVERGED_OBJECTIVE_DOMAIN of type int
  • DIVERGED_OBJECTIVE_NANORINF — Constant DIVERGED_OBJECTIVE_NANORINF of type int
  • DIVERGED_TR_DELTA — Constant DIVERGED_TR_DELTA of type int
  • ITERATING — Constant ITERATING of type int

And that's the full set, no crumbs left behind 💅 not a single one skipped, because we do not do half-finished tables in this house.

lowkey obsessed with how ITERATING is just sitting there at the bottom, alone, no CONVERGED_ prefix, no DIVERGED_ prefix, just ✨ main character energy ✨ — but fr fr, it's a constant of type int too, same as all its siblings.

✨ Attributes Documentation ✨

okay so now that the summary table's done, this is where the docs actually break down each of those constants one by one — the receipts, the lore, the whole backstory 🎀 stay tuned, bestie, we're just getting to the good part 💖

  • CONVERGED_FNORM_ABS — int = CONVERGED_FNORM_ABS. Constant CONVERGED_FNORM_ABS of type int ✨
  • CONVERGED_FNORM_RELATIVE — int = CONVERGED_FNORM_RELATIVE. Constant CONVERGED_FNORM_RELATIVE of type int 💖
  • CONVERGED_ITERATING — int = CONVERGED_ITERATING. Constant CONVERGED_ITERATING of type int 🦋
  • CONVERGED_ITS — int = CONVERGED_ITS. Constant CONVERGED_ITS of type int 🌸
  • CONVERGED_SNORM_RELATIVE — int = CONVERGED_SNORM_RELATIVE. Constant CONVERGED_SNORM_RELATIVE of type int 💅
  • DIVERGED_DTOL — int = DIVERGED_DTOL. Constant DIVERGED_DTOL of type int 😭
  • DIVERGED_FUNCTION_COUNT — int = DIVERGED_FUNCTION_COUNT. Constant DIVERGED_FUNCTION_COUNT of type int 🔥
  • DIVERGED_FUNCTION_DOMAIN — int = DIVERGED_FUNCTION_DOMAIN. Constant DIVERGED_FUNCTION_DOMAIN of type int 👑
  • DIVERGED_FUNCTION_NANORINF — int = DIVERGED_FUNCTION_NANORINF. Constant DIVERGED_FUNCTION_NANORINF of type int 🌈
  • DIVERGED_INNER — int = DIVERGED_INNER. Constant DIVERGED_INNER of type int ⭐
  • DIVERGED_JACOBIAN_DOMAIN — int = DIVERGED_JACOBIAN_DOMAIN. Constant DIVERGED_JACOBIAN_DOMAIN of type int 💀
  • DIVERGED_LINEAR_SOLVE — int = DIVERGED_LINEAR_SOLVE. Constant DIVERGED_LINEAR_SOLVE of type int 🙈
  • DIVERGED_LINE_SEARCH — int = DIVERGED_LINE_SEARCH. Constant DIVERGED_LINE_SEARCH of type int 🍓
  • DIVERGED_LOCAL_MIN — int = DIVERGED_LOCAL_MIN. Constant DIVERGED_LOCAL_MIN of type int 🧚
  • DIVERGED_MAX_IT — int = DIVERGED_MAX_IT. Constant DIVERGED_MAX_IT of type int 💜
  • DIVERGED_OBJECTIVE_DOMAIN — int = DIVERGED_OBJECTIVE_DOMAIN. Constant DIVERGED_OBJECTIVE_DOMAIN of type int 🫶
  • DIVERGED_OBJECTIVE_NANORINF — int = DIVERGED_OBJECTIVE_NANORINF. Constant DIVERGED_OBJECTIVE_NANORINF of type int 🎀
  • DIVERGED_TR_DELTA — int = DIVERGED_TR_DELTA. Constant DIVERGED_TR_DELTA of type int 🌺
  • ITERATING — int = ITERATING. Constant ITERATING of type int 🌟
  • __init__()
  • classmethod __new__(*args, **kwargs)

class petsc4py.PETSc.SNES.NewtonALCorrectionType

Bases: object

SNESNEWTONAL correction type.

See also: SNESNewtonALCorrectionType

Attributes Summary

  • EXACT — Constant EXACT of type int
  • NORMAL — Constant NORMAL of type int

Attributes Documentation

  • EXACT — int = EXACT. Constant EXACT of type int 💫
  • NORMAL — int = NORMAL. Constant NORMAL of type int 💫
  • __init__()
  • classmethod __new__(*args, **kwargs)

class petsc4py.PETSc.SNES.NormSchedule

Bases: object

SNES norm schedule.

See also: SNESNormSchedule

🎀 Attributes Summary 🎀

okay bestie, before we get into the whole taxonomy, here's the lil cheat-sheet of every constant this thing ships with 💖 every single one of them is type int (yep, the regular Python builtin int, no custom wrapper nonsense, periodt).

  • ALWAYS — Constant ALWAYS of type int ✨
  • DEFAULT — Constant DEFAULT of type int 💫
  • FINAL_ONLY — Constant FINAL_ONLY of type int 🎀
  • INITIAL_FINAL_ONLY — Constant INITIAL_FINAL_ONLY of type int 🦋
  • INITIAL_ONLY — Constant INITIAL_ONLY of type int 🌸
  • NONE — Constant NONE of type int 💅
  • NORM_ALWAYS — Constant NORM_ALWAYS of type int 🔥
  • NORM_DEFAULT — Constant NORM_DEFAULT of type int 🌈
  • NORM_FINAL_ONLY — Constant NORM_FINAL_ONLY of type int ⭐
  • NORM_INITIAL_FINAL_ONLY — Constant NORM_INITIAL_FINAL_ONLY of type int 👑
  • NORM_INITIAL_ONLY — Constant NORM_INITIAL_ONLY of type int 💜
  • NORM_NONE — Constant NORM_NONE of type int 🫶

twelve constants, not one of them benched. no cap 💀

📖 Attributes Documentation 📖

and here's the same twelve, one by one, with their full names spelled out — the : int bit means the annotation is int, and the = SOMETHING bit is the value, which is that same name. iconic, honestly. 🎀

  • ALWAYS: int = ALWAYS Constant ALWAYS of type int ✨
  • DEFAULT: int = DEFAULT Constant DEFAULT of type int 💫
  • FINAL_ONLY: int = FINAL_ONLY Constant FINAL_ONLY of type int 🎀
  • INITIAL_FINAL_ONLY: int = INITIAL_FINAL_ONLY Constant INITIAL_FINAL_ONLY of type int 🦋
  • INITIAL_ONLY: int = INITIAL_ONLY Constant INITIAL_ONLY of type int 🌸
  • NONE: int = NONE Constant NONE of type int 💅
  • NORM_ALWAYS: int = NORM_ALWAYS Constant NORM_ALWAYS of type int 🔥
  • NORM_DEFAULT: int = NORM_DEFAULT Constant NORM_DEFAULT of type int 🌈
  • NORM_FINAL_ONLY: int = NORM_FINAL_ONLY Constant NORM_FINAL_ONLY of type int ⭐
  • NORM_INITIAL_FINAL_ONLY: int = NORM_INITIAL_FINAL_ONLY Constant NORM_INITIAL_FINAL_ONLY of type int 👑
  • NORM_INITIAL_ONLY: int = NORM_INITIAL_ONLY Constant NORM_INITIAL_ONLY of type int 💜
  • NORM_NONE: int = NORM_NONE Constant NORM_NONE of type int 🫶
pro tip from ur girl: the int in every one of these annotations is linkified in the original docs to the Python builtins reference page for int. same energy, same type, just no clickable business here 😌

🧚 __init__()

the constructor, sitting there, existing. the docs list it and honestly that's the whole tea — no extra blurb attached, so we're not gonna invent one. respect the source, bestie 🫶

🧚 classmethod __new__(*args, **kwargs)

and the classmethod __new__, taking *args and **kwargs like the flexible lil overachiever it is. again: listed, no further description given. we move. 💖

👑 petsc4py.PETSc.SNES.Type 👑

class petsc4py.PETSc.SNES.Type

Bases: object 🦋

okay so this is literally just the class signature, and it is giving exactly what it says on the tin: this is the SNES solver type ✨ that's the entire description, and honestly? respect the brevity. main character energy, zero filler 💅

See also:

so if you wanna go deeper down the SNES lore, the SNESType manual page is right there in the PETSc docs, and she ate 🍓

and we are still going, because there's more where this came from — do not close the tab, bestie, the next chunk is right behind this one 🌸

That's 21 of them, every single one a str and every single one iconic in its own special way. They're all just the string name of a SNES type, and honestly? The fact that they're plain strings and not some fancy enum is very "we keep it simple here" of PETSc. 🫶

Each one is typed as str — as in <https://docs.python.org/3/builtins/stdtypes.html#str> — because that's what a Python string is, bestie, and we love her for it. ✨

🎀 Attributes Summary 🎀

okay so here's the whole squad, no cap, in the order they show up:

💅 Attributes Documentation 💅

and now the receipts, one by one, with the actual value each one is set to. spoiler: the value is literally just the name again. the way that these are self-referential is giving mirror selfie 🪞✨

ANDERSON: str <https://docs.python.org/3/builtins/stdtypes.html#str> = ANDERSON

Object ANDERSON of type str <https://docs.python.org/3/builtins/stdtypes.html#str>

ASPIN: str <https://docs.python.org/3/builtins/stdtypes.html#str> = ASPIN

Object ASPIN of type str <https://docs.python.org/3/builtins/stdtypes.html#str>

COMPOSITE: str <https://docs.python.org/3/builtins/stdtypes.html#str> = COMPOSITE

Object COMPOSITE of type str <https://docs.python.org/3/builtins/stdtypes.html#str>

FAS: str <https://docs.python.org/3/builtins/stdtypes.html#str> = FAS

Object FAS of type str <https://docs.python.org/3/builtins/stdtypes.html#str>

KSPONLY: str <https://docs.python.org/3/builtins/stdtypes.html#str> = KSPONLY

Object KSPONLY of type str <https://docs.python.org/3/builtins/stdtypes.html#str>

ngl this is the most predictable documentation ever written and I am obsessed. attribute name = value. no notes. 💀

and the pattern just keeps going, babes, because of course it does:

okay so we're still deep in the constants dump, bestie — every single one of these is a class attribute, and every single one is a str. Like, the annotation + the default value are literally the same word, which is giving "I contain myself" energy. Also, heads up: in the docs every one of those str annotations is hyperlinked to https://docs.python.org/3/builtins/stdtypes.html#str, because that's just how Sphinx do. 💅

  • KSPTRANSPOSEONLY: str = KSPTRANSPOSEONLY — object KSPTRANSPOSEONLY of type str. yes babe it's self-named, iconic behaviour honestly 🎀
  • MS: str = MS — object MS of type str. two letters, zero notes, we love a minimal queen ✨
  • NASM: str = NASM — object NASM of type str. still a str, still slaying 🦋
  • NCG: str = NCG — object NCG of type str. lowercase your expectations, it's just a string fr fr 💜
  • NEWTONAL: str = NEWTONAL — object NEWTONAL of type str. no cap, that's the whole description 🌸
  • NEWTONLS: str = NEWTONLS — object NEWTONLS of type str. same vibe, different name 🫶
  • NEWTONTR: str = NEWTONTR — object NEWTONTR of type str. and we keep it moving 💖
  • NGMRES: str = NGMRES — object NGMRES of type str. a str! shocking! groundbreaking! 🔥
  • NGS: str = NGS — object NGS of type str. three characters of pure str realness 👑
  • NRICHARDSON: str = NRICHARDSON — object NRICHARDSON of type str. the name is long, the type is str, that's the tea ☕
  • PATCH: str = PATCH — object PATCH of type str. still typing str, still main character energy 🌈
  • PYTHON: str = PYTHON — object PYTHON of type str. yes, irony noted, it's a str not a module, moving on ⭐
  • QN: str = QN — object QN of type str. no further lore, the lore is str 💅
  • SHELL: str = SHELL — object SHELL of type str. not the shell you're thinking of, just a str bestie 🙈
  • VINEWTONRSLS: str = VINEWTONRSLS — object VINEWTONRSLS of type str. big name, tiny type, balance 🍓
  • VINEWTONSSLS: str = VINEWTONSSLS — object VINEWTONSSLS of type str. and that's the last of the all-caps alphabet gang for now 💀

and then, the two lil darlings that actually do something:

  • __init__() — the initialiser, hanging out right there in the signature with no args listed. it is what it is 🧚
  • classmethod __new__(*args, **kwargs) — a classmethod that takes *args and **kwargs, i.e. the usual "throw whatever at it" energy. note the classmethod bit — it's bound to the class, not an instance, iykyk 💜

✨ Methods Summary ✨

okay bestie, this is the full roster of what a SNES can do — every method, every signature, nothing skipped, no gatekeeping 💅 keep this one bookmarked because you will be scrolling back to it.

  • appendOptionsPrefix(prefix) — glues prefix onto the front of the prefix that gets used when the solver goes digging for options in the database.
  • callConvergenceTest(its, xnorm, ynorm, fnorm) — runs the convergence test. that's it, that's the job.
  • computeFunction(x, f) — computes the function. the whole reason we're here tbh.
  • computeJacobian(x, J[, P]) — computes the Jacobian. note the P chilling in brackets — that one's optional, so you can pass it or not, your call bestie 🫶
  • computeNGS(x[, b]) — computes a nonlinear Gauss-Seidel step. and yeah, b is optional too.
  • computeObjective(x) — hands you back the value of the objective function. 📈
  • converged(its, xnorm, ynorm, fnorm) — runs the convergence test and updates the solver's converged reason. two for one, obsessed.
  • create([comm]) — creates a SNES solver. the birth of a legend ✨ comm optional.
  • createPython([context, comm]) — creates a nonlinear solver of Python type. both context and comm are optional, fancy.
  • destroy() — destroys the solver. rip boo, you served 👑
  • getApplicationContext() — gives you back the application context.
  • getCompositeNumber() — tells you how many solvers are in the composite.
  • getCompositeSNES(n) — gives you the n-th solver in the composite.
  • getConvergedReason() — hands over the termination flag. the "so how did it go" of it all.
  • getConvergenceHistory() — returns the convergence history.
  • getConvergenceTest() — returns the callback that's meant to be used as the convergence test.
  • getDM() — returns the DM <#petsc4py.PETSc.DM> that's associated with the solver.
  • getDivergenceTolerance() — gets the divergence tolerance parameter that the convergence tests use.
  • getErrorIfNotConverged() — returns the flag that says whether to error out on divergence.
  • getFASCoarseSolve() — returns the SNES used at the coarsest level of the FAS hierarchy. the bottom of the pyramid fr fr.
  • getFASCycleSNES(level) — returns the SNES that corresponds to a particular level of the FAS hierarchy.
  • getFASInjection(level) — returns the Mat <#petsc4py.PETSc.Mat> used to apply the injection from level-1 to level.
  • getFASInterpolation(level) — returns the Mat <#petsc4py.PETSc.Mat> used to apply the interpolation from level-1 to level.
  • getFASLevels() — returns how many levels are being used.
  • getFASRestriction(level) — returns the Mat <#petsc4py.PETSc.Mat> used to apply the restriction from level-1 to level.
  • getFASSmoother(level) — returns the smoother used at a given level of the FAS hierarchy.
  • getFASSmootherDown(level) — returns the downsmoother used at a given level of the FAS hierarchy.
  • getFASSmootherUp(level) — returns the upsmoother used at a given level of the FAS hierarchy.

like, look at that list. FAS hierarchy methods get a whole little family reunion in here, injection → interpolation → restriction, the way they all travel from level-1 to level is giving elevator energy 🛗💜

and yes, if you clocked that basically every getFASSomething(level) takes a level argument — correct, that's the vibe check passing ✅ the FAS stuff is layered, so you gotta tell it which layer you're asking about before it'll hand anything over.

…at a given level of the FAS hierarchy. 🦋 (that was the tail end of the FAS one we were mid-sentence on, carry on bestie)

  • getFunction() — hands you back the callback that computes the nonlinear function. that's your whole f(x) situation 🫶
  • getFunctionEvaluations() — returns how many function evaluations have happened so far. the running tally, the receipts, the count 💅
  • getFunctionNorm() — returns the function norm. just the norm. short and sweet, she ate ✨
  • getInitialGuess() — returns the callback you use to compute the initial guess. first impressions matter, periodt 🎀
  • getIterationNumber() — returns the current iteration number, aka how many laps around the track we're on 🏃‍♀️
  • getJacobian() — returns the matrices used to compute the Jacobian and the callback tuple. yes, both, she's giving multitasker 🔥
  • getKSP() — returns the linear solver that the nonlinear solver is using. it's giving collaboration, it's giving teamwork 🌈
  • getKSPFailures() — returns the current number of linear solve failures. we don't talk about those (jk we absolutely do, track them) 😭
  • getLineSearch() — returns the linesearch object that's associated with this SNES. her little sidekick 🧚
  • getLinearSolveIterations() — returns the total number of linear iterations. not current, total, don't get it twisted ⭐
  • getMaxFunctionEvaluations() — returns the maximum allowed number of function evaluations. the cap, the ceiling, the limit 👑
  • getMaxKSPFailures() — returns the maximum allowed number of linear solve failures. how many Ls before we stop taking Ls 💀
  • getMaxStepFailures() — returns the maximum allowed number of step failures. same energy, different counter 💜
  • getMonitor() — returns the callback used to monitor solver convergence. she's watching. always watching 👀 (affectionately)
  • getNASMNumber() — returns the number of solvers in NASM. count them, bestie 🔢
  • getNASMSNES(n) — returns the n-th solver in NASM. zero-indexed chaos, you know how it is 🌸
  • getNGS() — returns the nonlinear Gauss-Seidel callback tuple. tuple alert! 🚨
  • getNPC() — returns the nonlinear preconditioner that's associated with the solver. the NPC of preconditioners, lowkey iconic 💖
  • getNPCSide() — returns the nonlinear preconditioning side. which side? the side. 🦋
  • getNewtonALLoadParameter() — returns the load parameter for SNESNEWTONAL. specific, niche, we love a specialist ✨
  • getNormSchedule() — returns the norm schedule. yes, norms get scheduled, it's very main character energy 📅
  • getObjective() — returns the objective callback tuple. another tuple, another queen 🎀
  • getOptionsPrefix() — returns the prefix used for searching for options in the database. it's giving "where do I look for my settings" 🔍
  • getParamsEW() — gets the parameters of the Eisenstat and Walker trick. that's the name, EW, and no she is not gross, she is very smart 🧠
  • getPythonContext() — returns the instance of the class implementing the required Python methods. your object, back in your hands 🐍
  • getPythonType() — returns the fully qualified Python name of the class the solver is using. full government name, no nicknames 💅
  • getRhs() — returns the vector holding the right-hand side. the RHS of it all, the right hand side is right here 🔥
  • getSolution() — hands you the vector that's holding the solution. ✨
  • getSolutionUpdate() — and this one hands you the vector holding the solution update. little sibling energy fr.
  • getStepFailures() — returns how many step failures the solver has racked up so far. it's giving report card vibes 😭
  • getTRTolerances() — returns the tolerance parameters that the trust region is working with.
  • getTRUpdateParameters() — returns the update parameters the trust region is using.
  • getTolerances() — returns the tolerance parameters used in the solver's convergence tests. the whole pass/fail rubric basically 💅
  • getType() — returns the type of the solver. who is she? now you know.
  • getUpdate() — returns the callback that computes the update at the beginning of each step. 🎀
  • getUseEW() — returns the flag telling you whether the solver uses the Eisenstat-Walker trick.
  • getUseFD() — returns true if the solver uses color finite-differencing for the Jacobian. 🌈
  • getUseKSP() — returns the flag telling you whether the solver uses a linear solver.
  • getUseMF() — returns the flag telling you whether the solver uses matrix-free finite-differencing. no matrices were harmed 🫶
  • getVIInactiveSet() — returns the index set for the inactive set.
  • getVariableBounds() — gets you the vectors for the variable bounds.
  • hasNPC() — returns a boolean, and what it's boole-ing about is whether the solver has a nonlinear preconditioner. 👑
  • logConvergenceHistory(norm[, linear_its]) — logs the residual norm and the linear iterations.
  • monitor(its, rnorm) — monitors the solver. yes bestie, it's watching. 👀
  • monitorCancel() — cancels all the monitors of the solver. ghosting them entirely, and honestly? valid.
  • reset() — resets the solver. clean slate, fresh start, new era ✨
  • setApplicationContext(appctx) — sets the application context.
  • setConvergedReason(reason) — sets the termination flag.
  • setConvergenceHistory([length, reset]) — sets the convergence history.
  • setConvergenceTest(converged[, args, kargs]) — sets the callback to be used as the convergence test.
  • setDM(dm) — associates a DM <#petsc4py.PETSc.DM> with the solver. now they're linked, no cap 🦋
  • setDivergenceTolerance(dtol) — sets the divergence tolerance parameter used in the convergence tests.
  • setErrorIfNotConverged(flag) — immediately generates an error if the solver has not converged. like, no chill whatsoever, it will scream at you the second things go sideways 💀
  • setFASInjection(level, mat) — sets the Mat <#petsc4py.PETSc.Mat> to be used to apply the injection from level-1 to level.
  • setFASInterpolation(level, mat) — feeds in the Mat (<#petsc4py.PETSc.Mat>) that gets used to apply the interpolation going from level-1 up to level. 💫
  • setFASLevels(levels[, comms]) — tells FAS how many levels we're working with. That's it, that's the vibe. 🪜
  • setFASRScale(level, vec) — sets the scaling factor of the restriction operator going from level down to level-1. 🎚️
  • setFASRestriction(level, mat) — hands over the Mat (<#petsc4py.PETSc.Mat>) that applies the restriction from level-1 to level. Yes bestie, interpolation and restriction are different directions, don't mix them up 😭
  • setForceIteration(force) — makes the solve take at least one iteration, no matter what. queen behavior honestly. 👑
  • setFromOptions() — configures the solver straight from the options database. the classic. ✨
  • setFunction(function[, f, args, kargs]) — sets the callback that computes the nonlinear function. 🧮
  • setFunctionNorm(norm) — sets the function norm value. 📏
  • setInitialGuess(initialguess[, args, kargs]) — sets the callback that computes the initial guess. first impressions matter!! 🌸
  • setIterationNumber(its) — sets the current iteration number. 🔢
  • setJacobian(jacobian[, J, P, args, kargs]) — sets the callback that computes the Jacobian. 🧠
  • setKSP(ksp) — sets the linear solver that the nonlinear solver is gonna use. 💅
  • setLineSearch(linesearch) — sets the linesearch object this SNES gets to use. 🔍
  • setLineSearchPreCheck(precheck[, args, kargs]) — sets the callback that gets called before the linesearch is applied. pre-check girlies rise 🫶
  • setMaxFunctionEvaluations(max_funcs) — sets the max number of function evaluations allowed. cap it fr fr 🛑
  • setMaxKSPFailures(max_fails) — sets the max number of linear solve failures allowed. 💀
  • setMaxStepFailures(max_fails) — sets the max number of step failures allowed. 😵
  • setMonitor(monitor[, args, kargs]) — sets the callback used to monitor solver convergence. 👀
  • setNGS(ngs[, args, kargs]) — sets the callback to compute nonlinear Gauss-Seidel. ✨
  • setNPC(snes) — sets the nonlinear preconditioner. 🧩
  • setNPCSide(side) — sets the nonlinear preconditioning side. ◀️▶️
  • setNewtonALCorrectionType(corrtype) — sets the correction type for SNESNEWTONAL. 🔧
  • setNewtonALFunction(function[, args, kargs]) — sets the callback to compute the tangent load vector for SNESNEWTONAL. 📐
  • setNormSchedule(normsched) — sets the norm schedule. 🗓️
  • setObjective(objective[, args, kargs]) — sets the callback to compute the objective function. 🎯
  • setOptionsPrefix(prefix) — sets the prefix used when searching for options in the database. 🔎
  • setParamsEW([version, rtol_0, rtol_max, ...]) — sets the parameters for the Eisenstat and Walker… 🌈
  • setPatchCellNumbering(sec) — sets the cell patch numbering. you pass it sec, it handles the numbering. one job, done. ✨
  • setPatchComputeFunction(function[, args, kargs]) — sets the patch compute function. drop in your function with optional args and kargs and it's yours. 🫶
  • setPatchComputeOperator(operator[, args, kargs]) — same energy, different noun: this one sets the patch compute operator, again with optional args and kargs. 🎀
  • setPatchConstructType(typ[, operator, args, ...]) — sets the patch construct type. you give it typ, and optionally operator, args, and whatever else follows. 🦋
  • setPatchDiscretisationInfo(dms, bs, ...) — sets the patch discretisation information. bring your dms, your bs, and the rest of the party. 🌸
  • setPythonContext(context) — sets the instance of the class that implements all the required Python methods. so like, the actual object doing the work lives here. 💅
  • setPythonType(py_type) — sets the fully qualified Python name of the class you want used. not a nickname, not a vibe — the full name. 📛
  • setResetCounters([reset]) — sets the flag that says whether to reset the counters. flip reset, counters behave accordingly. 🔄
  • setSolution(vec) — sets the vector that stores the solution. that's the vec, that's where the answer chills. 🏠
  • setTRTolerances([delta_min, delta_max, delta_0]) — sets the tolerance parameters used for the trust region: delta_min, delta_max, delta_0. 🤏
  • setTRUpdateParameters([eta1, eta2, eta3, t1, t2]) — sets the update parameters used for the trust region. all five of them: eta1, eta2, eta3, t1, t2. the whole lil squad. 🌈
  • setTolerances([rtol, atol, stol, max_it]) — sets the tolerance parameters used in the solver's convergence tests: rtol, atol, stol, max_it. how close is close enough, bestie. 🎯
  • setType(snes_type) — sets the type of the solver. hand it an snes_type and it becomes that. main character transformation. 👑
  • setUp() — sets up the internal data structures so the solver can actually do its thing. no args, just vibes and preparation. 🛠️
  • setUpMatrices() — ensures that matrices are available for Newton-like methods. it makes sure they're there, so you don't have to worry. ✅
  • setUpdate(update[, args, kargs]) — sets the callback that computes the update at the beginning of each step. update plus optional args and kargs. ⏰
  • setUseEW([flag]) — tells the solver to use the Eisenstat-Walker trick. toggle it with flag. 🔁
  • setUseFD([flag]) — sets the boolean flag for using coloring finite-differencing for Jacobian assembly. true or false, that's the whole deal. 🎨
  • setUseKSP([flag]) — sets the boolean flag indicating to use a linear solver. yes/no energy. linear solver: in or out. 📏
  • setUseMF([flag]) — sets the boolean flag indicating to use matrix-free finite-differencing. again, just a boolean, just a flag. 🪶
  • setVariableBounds(xl, xu) — sets the vector for the variable bounds. lower goes in xl, upper goes in xu. 🚧
  • solve([b, x]) — solves the nonlinear equations. optionally with b and x. this is the moment, the finale, the slay. 🔥
  • view([viewer]) — views the solver. pass a viewer if you've got one, otherwise it does its default thing. 👀

✨ Attributes Summary ✨

okay so before we get into the Methods, here's the lil roster of attributes a SNES object is carrying around 💅 you can peek at all of these, and honestly a bunch of them are legit the most useful things in the whole class:

  • appctx — Application context. your personal lil stash of anything-you-want 🎀
  • atol — Absolute residual tolerance. the "am I close enough in absolute terms" bar.
  • dm — DM (#petsc4py.PETSc.DM). the mesh/data manager bestie.
  • history — Convergence history. receipts of everything the solver did 💀
  • is_converged — Boolean indicating if the solver has converged. slay, it made it 🎉
  • is_diverged — Boolean indicating if the solver has failed. not slay, it's giving sadness 😭
  • is_iterating — Boolean indicating if the solver has not converged yet. still grinding, respect the hustle ✨
  • its — Number of iterations. how many laps did we run.
  • ksp — Linear solver. the inner-solver cutie 🦋
  • linesearch — The linesearch object associated with this SNES. it decides how far to step, lowkey iconic.
  • max_funcs — Maximum number of function evaluations. the eval budget, periodt.
  • max_it — Maximum number of iterations. stop-at-that-many, she's a hard limit.
  • norm — Function norm. the current vibe-check number 📉
  • npc — Nonlinear preconditioner. glow-up juice for hard problems 🔥
  • reason — Converged reason. why it stopped — the gossip you need.
  • rtol — Relative residual tolerance. the "close enough relative to where we started" bar.
  • stol — Solution update tolerance. how tiny an update counts as basically nothing.
  • use_ew — Use the Eisenstat-Walker trick. fancy adaptive tolerance behavior, iykyk.
  • use_fd — Boolean indicating if the solver uses coloring finite-differencing.
  • use_ksp — Boolean indicating if the solver uses a linear solver.
  • use_mf — Boolean indicating if the solver uses matrix-free finite-differencing.
  • vec_rhs — Right-hand side vector. the b in Ax = b, babe 💖
  • vec_sol — Solution vector. the answer, the moment, the main character 👑
  • vec_upd — Update vector. the step we just took.

🌈 Methods Documentation 🌈

okay NOW the good stuff, the actual methods, let's go method by method fr fr no skimming allowed ✨

💫 appendOptionsPrefix(prefix)

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

Logically collective — so everyone's gotta call it together, no sneaking off 🙈

See also: Working with PETSc options (#petsc-options), setOptionsPrefix, SNESAppendOptionsPrefix (https://petsc.org/release/manualpages/SNES/SNESAppendOptionsPrefix.html)

Source code at petsc4py/PETSc/SNES.pyx:243 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L243)

Parameters

Return type

None (https://docs.python.org/3/builtins/constants.html#None)

💫 callConvergenceTest(its, xnorm, ynorm, fnorm)

Compute the convergence test.

Collective. 🫶

Parameters

Return type

ConvergedReason (#petsc4py.PETSc.SNES.ConvergedReason)

See also: setConvergenceTest, getConvergenceTest

Source code at petsc4py/PETSc/SNES.pyx:1342 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1342)

💫 computeFunction(x, f)

Compute the function.

Collective — everybody in the group chat participates 💜

Parameters

  • x (Vec (#petsc4py.PETSc.Vec)) — The input state vector.
  • f (Vec (#petsc4py.PETSc.Vec)) — The output vector.

Return type

None (https://docs.python.org/3/builtins/constants.html#None)

See also: setFunction, SNESComputeFunction (https://petsc.org/release/manualpages/SNES/SNESComputeFunction.html)

Source code at petsc4py/PETSc/SNES.pyx:1043 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1043)

💫 computeJacobian(x, J, P=None)

Compute the Jacobian.

Collective. 🌸

Parameters

  • x (Vec (#petsc4py.PETSc.Vec)) — The input state vector.
  • J (Mat (#petsc4py.PETSc.Mat)) — The output Jacobian matrix.
  • P (Mat (#petsc4py.PETSc.Mat) | None (https://docs.python.org/3/builtins/constants.html#None)) — The output Jacobian matrix used to construct the preconditioner.

Return type

None (https://docs.python.org/3/builtins/constants.html#None)

See also: setJacobian, SNESComputeJacobian (https://petsc.org/release/manualpages/SNES/SNESComputeJacobian.html)

Source code at petsc4py/PETSc/SNES.pyx:1062 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1062)

💫 computeNGS(x, b=None)

Compute a nonlinear Gauss-Seidel step.

Collective. ✨

Parameters

  • x (Vec (#petsc4py.PETSc.Vec)) — The input/output state vector.
  • b (Vec | None) — the input right-hand side vector, aka the thing you're solving against 💖

Return type: None — yeah bestie, you get nothing back, the work happens elsewhere

See also: setNGS, getNGS, SNESComputeNGS

Source code at petsc4py/PETSc/SNES.pyx:1149

computeObjective(x) 👑

Compute the value of the objective function. That's the goal function, the thing your solver is out here trying to minimize, no cap.

Collective — everybody on the comm has to show up for this one, fr fr.

Parameters:

  • x (Vec) — the input state vector, i.e. wherever your solution currently lives 🌸

Return type: float — a plain ol' Python float, iconic

See also: setObjective, SNESComputeObjective

Source code at petsc4py/PETSc/SNES.pyx:1085

converged(its, xnorm, ynorm, fnorm) ✨

Compute the convergence test and update the solver converged reason. This is the vibe check for your whole solve — did we make it or are we still cooking?

Collective, as always 🫶

Parameters:

  • its (int) — iteration number, the count of how many laps we've done
  • xnorm (float) — solution norm
  • ynorm (float) — update norm
  • fnorm (float) — function norm

Return type: None

See also: setConvergenceTest, getConvergenceTest, SNESConverged

Source code at petsc4py/PETSc/SNES.pyx:1372

create(comm=None) 🎀

Create a SNES solver. Brand new, fresh out the box, main character energy.

Collective.

Parameters:

  • comm (Comm | None) — MPI communicator; if you're like "idk bestie you pick", it defaults to Sys.getDefaultComm 💅

Return type: Self

See also: Sys.getDefaultComm, SNESCreate

Source code at petsc4py/PETSc/SNES.pyx:161

createPython(context=None, comm=None) 🐍

Create a nonlinear solver of Python type. Yep, you can write your own solver logic in Python and PETSc will use it, that's the whole flex.

Collective.

Parameters:

  • context (Any) — an instance of the Python class implementing the required methods. Your very own object, living its best life as the solver context 😭
  • comm (Comm | None) — MPI communicator; defaults to Sys.getDefaultComm when you pass nothing

Return type: Self

See also: PETSc Python nonlinear solver type (TODO), setType, setPythonContext, Type.PYTHON

Source code at petsc4py/PETSc/SNES.pyx:2210

destroy() 💀

Destroy the solver. It's giving closure. Release those resources, bestie, we don't leak here.

Collective.

See also: SNESDestroy

Source code at petsc4py/PETSc/SNES.pyx:148

Return type: Self

getApplicationContext()

Return the application context. That's your little bag of custom data you tucked in there earlier 🎀

Source code at petsc4py/PETSc/SNES.pyx:280

Return type: Any

getCompositeNumber()

Return the number of solvers in the composite. Counting the squad members, one by one.

Not collective — you can ask this one on your own, no group chat needed.

See also: getCompositeSNES, SNESCompositeGetNumber, SNESCOMPOSITE

Source code at petsc4py/PETSc/SNES.pyx:2311

Return type: int

getCompositeSNES(n)

Return the n-th solver in the composite. Pick your fighter 🌈

Not collective.

Parameters:

  • n (int) — the index, your ticket number to that specific sub-solver

Return type: SNES

See also: getCompositeNumber, SNESCompositeGetSNES, SNESCOMPOSITE

Source code at petsc4py/PETSc/SNES.pyx:2294

getConvergedReason()

Return the termination flag — the receipts on why your solve ended. Slayed or flopped, this tells you which 👑

Not collective.

See also: setConvergedReason, SNESGetConvergedReason

Source code at petsc4py/PETSc/SNES.pyx:1755

Return type: ConvergedReason

getConvergenceHistory()

Return the convergence history. Every iteration's glow-up, archived 💖

Not collective.

See also: SNESGetConvergenceHistory

Source code at petsc4py/PETSc/SNES.pyx:1423

Return type: tuple[ArrayReal, ArrayInt]

getConvergenceTest()

Return the callback to used as convergence test.

Not collective.

See also: setConvergenceTest, callConvergenceTest

Source code at petsc4py/PETSc/SNES.pyx:1330

Return type: SNESConvergedFunction

getDM()

Return the DM associated with the solver. The DM is the whole data-management bestie that's been riding along with your solve 🦋

Not collective.

See also: setDM, SNESGetDM

Source code at petsc4py/PETSc/SNES.pyx:295

Return type: DM

getDivergenceTolerance()

Get the divergence tolerance parameter used in the convergence tests. The "okay, we're officially spiraling" threshold 😭

Not collective.

See also: setDivergenceTolerance, getTolerances, SNESGetDivergenceTolerance

Source code at petsc4py/PETSc/SNES.pyx:1255

Return type: float

getErrorIfNotConverged()

Return the flag indicating error on divergence.

Not collective.

getFASCoarseSolve() 🧚

okay so this one hands you the SNES that's doing the work at the coarsest level of the FAS hierarchy. the bottom of the ladder, the final boss, the coarsest solve 💅

Not collective.

See also: getFASSmoother, SNESFASGetCoarseSolve <https://petsc.org/release/manualpages/SNESFAS/SNESFASGetCoarseSolve.html>, SNESFAS <https://petsc.org/release/manualpages/SNESFAS/SNESFAS.html>

Source code at petsc4py/PETSc/SNES.pyx:610 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L610>

Return type: SNES

getFASCycleSNES(level) 🌈

gives you the SNES that corresponds to one particular level of the FAS hierarchy. you pick the level, it gives you the solver 🔥

Not collective.

See also: setFASLevels, getFASCoarseSolve, getFASSmoother, SNESFASGetCycleSNES <https://petsc.org/release/manualpages/SNESFAS/SNESFASGetCycleSNES.html>, SNESFAS <https://petsc.org/release/manualpages/SNESFAS/SNESFAS.html>

Source code at petsc4py/PETSc/SNES.pyx:593 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L593>

Parameters

  • level (int) — which level you're asking about, bestie

Return type: SNES

getFASInjection(level) 🎀

returns the Mat used to apply the injection from level-1 to level. yeah, injection, the dramatic name for the transfer operator, it's iconic actually ✨

Not collective.

See also: setFASInjection, SNESFASGetInjection <https://petsc.org/release/manualpages/SNESFAS/SNESFASGetInjection.html>, SNESFAS <https://petsc.org/release/manualpages/SNESFAS/SNESFAS.html>

Source code at petsc4py/PETSc/SNES.pyx:516 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L516>

Parameters

  • level (int) — the level you want the injection for

Return type: Mat

getFASInterpolation(level) 🦋

the Mat that applies the interpolation from level-1 to level. going up the hierarchy, main character energy only 🌸

Not collective.

See also: setFASInterpolation, SNESFASGetInterpolation <https://petsc.org/release/manualpages/SNESFAS/SNESFASGetInterpolation.html>, SNESFAS <https://petsc.org/release/manualpages/SNESFAS/SNESFAS.html>

Source code at petsc4py/PETSc/SNES.pyx:456 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L456>

Parameters

  • level (int) — the level in question

Return type: Mat

getFASLevels() 💖

just tells you how many levels are being used. simple, clean, no notes 💅

Not collective.

See also: setFASLevels, SNESFASGetLevels <https://petsc.org/release/manualpages/SNESFAS/SNESFASGetLevels.html>, SNESFAS <https://petsc.org/release/manualpages/SNESFAS/SNESFAS.html>

Source code at petsc4py/PETSc/SNES.pyx:579 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L579>

Return type: int

getFASRestriction(level) 🍓

the Mat used to apply the restriction from level-1 to level. down we go, bestie, the restriction era 😭

Not collective.

See also: setFASRestriction, SNESFASGetRestriction <https://petsc.org/release/manualpages/SNESFAS/SNESFASGetRestriction.html>, SNESFAS <https://petsc.org/release/manualpages/SNESFAS/SNESFAS.html>

Source code at petsc4py/PETSc/SNES.pyx:486 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L486>

Parameters

  • level (int) — the level whose restriction you want

Return type: Mat

getFASSmoother(level) 🫶

gives you the smoother used at a given level of the FAS hierarchy. smooth, like a fresh manicure ✨

Not collective.

See also: setFASLevels, getFASCoarseSolve, getFASSmootherDown, getFASSmootherUp, SNESFASGetSmoother <https://petsc.org/release/manualpages/SNESFAS/SNESFASGetSmoother.html>, SNESFAS <https://petsc.org/release/manualpages/SNESFAS/SNESFAS.html>

Source code at petsc4py/PETSc/SNES.pyx:625 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L625>

Parameters

  • level (int) — which level's smoother you're after

Return type: SNES

getFASSmootherDown(level) 💜

the downsmoother at a given level of the FAS hierarchy. it's giving descent 💀

Not collective.

See also: setFASLevels, getFASCoarseSolve, getFASSmoother, getFASSmootherUp, SNESFASGetSmootherDown <https://petsc.org/release/manualpages/SNESFAS/SNESFASGetSmootherDown.html>, SNESFAS <https://petsc.org/release/manualpages/SNESFAS/SNESFAS.html>

Source code at petsc4py/PETSc/SNES.pyx:642 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L642>

Parameters

  • level (int) — the level of the downsmoother you want

Return type: SNES

getFASSmootherUp(level) 👑

the upsmoother at a given level of the FAS hierarchy. going up, as she should 💅

Not collective.

See also: setFASLevels, getFASCoarseSolve, getFASSmoother, getFASSmootherDown, SNESFASGetSmootherUp <https://petsc.org/release/manualpages/SNESFAS/SNESFASGetSmootherUp.html>, SNESFAS <https://petsc.org/release/manualpages/SNESFAS/SNESFAS.html>

Source code at petsc4py/PETSc/SNES.pyx:659 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L659>

Parameters

  • level (int) — the level of the upsmoother you want

Return type: SNES

getFunction() 🧚

returns the callback that computes the nonlinear function. yes, the actual function, the whole point of the SNES, no cap 🌟

Not collective.

See also: setFunction, SNESGetFunction <https://petsc.org/release/manualpages/SNES/SNESGetFunction.html>

Source code at petsc4py/PETSc/SNES.pyx:859 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L859>

Return type: SNESFunction

getFunctionEvaluations() 🔥

tells you the current number of function evaluations. keeping count, bestie, we love an informed queen 📊

Not collective.

See also: setMaxFunctionEvaluations, SNESGetNumberFunctionEvals <https://petsc.org/release/manualpages/SNES/SNESGetNumberFunctionEvals.html>

Source code at petsc4py/PETSc/SNES.pyx:1576 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1576>

Return type: int

getFunctionNorm() ⭐

hands you the function norm. that little number that tells you how close (or not 💀) you are.

Not collective.

See also: setFunctionNorm, SNESGetFunctionNorm <https://petsc.org/release/manualpages/SNES/SNESGetFunctionNorm.html>

Source code at petsc4py/PETSc/SNES.pyx:1853 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1853>

Return type: float

getInitialGuess() 🌸

returns the callback that computes the initial guess. the starting vibe, the opening scene, the first impression 💖

Not collective.

See also: setInitialGuess

Source code at petsc4py/PETSc/SNES.pyx:812 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L812>

Return type: SNESGuessFunction

getIterationNumber()

Return the current iteration number.

…and that's the whole vibe, no extra ceremony. 💅

Not collective.

See also: setIterationNumber, SNESGetIterationNumber — https://petsc.org/release/manualpages/SNES/SNESGetIterationNumber.html

Source code: petsc4py/PETSc/SNES.pyx:1811 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1811

Return type: int

getJacobian()

Hands you back the matrices used to compute the Jacobian, plus the callback tuple. Iconic little trio. ✨

Not collective.

Returns:

  • J (Mat) — the matrix where the Jacobian gets stored.
  • P (Mat) — the matrix used to construct the preconditioner.
  • callback (SNESJacobianFunction) — callback, positional and keyword arguments.

Return type: tuple[Mat, Mat, SNESJacobianFunction]

See also: setJacobian, SNESGetJacobian — https://petsc.org/release/manualpages/SNES/SNESGetJacobian.html

Source code: petsc4py/PETSc/SNES.pyx:971 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L971

getKSP()

Gives you the linear solver that your nonlinear solver is using. Bestie behavior, honestly. 💖

Not collective.

See also: setKSP, SNESGetKSP — https://petsc.org/release/manualpages/SNES/SNESGetKSP.html

Source code: petsc4py/PETSc/SNES.pyx:1952 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1952

Return type: KSP

getKSPFailures()

Returns the current number of linear solve failures. Like, the count so far. 🙈

Not collective.

See also: getMaxKSPFailures, SNESGetLinearSolveFailures — https://petsc.org/release/manualpages/SNES/SNESGetLinearSolveFailures.html

Source code: petsc4py/PETSc/SNES.pyx:1658 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1658

Return type: int

getLineSearch()

Returns the linesearch object that's attached to this SNES. She's got her own whole personality, fr. 🦋

Not collective.

See also: setLineSearch, linesearch, SNESGetLineSearch — https://petsc.org/release/manualpages/SNES/SNESGetLineSearch.html

Source code: petsc4py/PETSc/SNES.pyx:2619 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2619

Return type: SNESLineSearch

getLinearSolveIterations()

Returns the total number of linear iterations. Running tally, no cap. 🔥

Not collective.

See also: SNESGetLinearSolveIterations — https://petsc.org/release/manualpages/SNES/SNESGetLinearSolveIterations.html

Source code: petsc4py/PETSc/SNES.pyx:1867 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1867

Return type: int

getMaxFunctionEvaluations()

Returns the maximum allowed number of function evaluations. That's the ceiling, periodt. 👑

Not collective.

See also: setMaxFunctionEvaluations, SNESSetTolerances — https://petsc.org/release/manualpages/SNES/SNESSetTolerances.html

Source code: petsc4py/PETSc/SNES.pyx:1560 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1560

Return type: int

getMaxKSPFailures()

Returns the maximum allowed number of linear solve failures. How many L's your linear solver is permitted before someone has to have a conversation. 💀

Not collective.

See also: setMaxKSPFailures, SNESGetMaxLinearSolveFailures — https://petsc.org/release/manualpages/SNES/SNESGetMaxLinearSolveFailures.html

Source code: petsc4py/PETSc/SNES.pyx:1644 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1644

Return type: int

getMaxStepFailures()

Returns the maximum allowed number of step failures. The step budget, bestie — don't blow it. 🎀

Not collective.

See also: setMaxStepFailures, SNESGetMaxNonlinearStepFailures — https://petsc.org/release/manualpages/SNES/SNESGetMaxNonlinearStepFailures.html

Source code: petsc4py/PETSc/SNES.pyx:1603 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1603

Return type: int

getMonitor()

Returns the callback that's out here monitoring solver convergence. She's watching. Always. 👀

Not collective.

See also: setMonitor

Source code: petsc4py/PETSc/SNES.pyx:1495 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1495

Return type: list[tuple[SNESMonitorFunction, tuple[Any, ...], dict[str, Any]]]

getNASMNumber()

Returns the number of solvers in NASM.

Not collective.

See also: getNASMSNES, SNESNASMGetNumber — https://petsc.org/release/manualpages/SNES/SNESNASMGetNumber.html, SNESNASM — https://petsc.org/release/manualpages/SNES/SNESNASM.html

Source code: petsc4py/PETSc/SNES.pyx:2343 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2343

Return type: int

getNASMSNES(n)

Returns the n-th solver in NASM. Pick your fighter. ⭐

Not collective.

See also: getNASMNumber, SNESNASMGetSNES — https://petsc.org/release/manualpages/SNES/SNESNASMGetSNES.html, SNESNASM — https://petsc.org/release/manualpages/SNES/SNESNASM.html

Source code: petsc4py/PETSc/SNES.pyx:2327 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2327

Parameters:

  • n (int)

Return type: SNES

getNGS()

Returns the nonlinear Gauss-Seidel callback tuple. Yeah, that whole callback bundle. 🫶

Not collective.

See also: setNGS, computeNGS

Source code: petsc4py/PETSc/SNES.pyx:1135 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1135

Return type: SNESNGSFunction

getNPC()

Returns the nonlinear preconditioner that's attached to the solver.

Not collective.

See also: setNPC, hasNPC, setNPCSide, getNPCSide, SNESGetNPC — https://petsc.org/release/manualpages/SNES/SNESGetNPC.html

Source code: petsc4py/PETSc/SNES.pyx:678 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L678

Return type: SNES

getNPCSide()

Returns which side the nonlinear preconditioning is happening on. Left, right — the lore matters. 🌈

Not collective.

See also: setNPC, getNPC, hasNPC, setNPCSide, SNESGetNPCSide — https://petsc.org/release/manualpages/SNES/SNESGetNPCSide.html

Source code: petsc4py/PETSc/SNES.pyx:731 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L731

Return type: Side

getNewtonALLoadParameter()

Returns the load parameter for SNESNEWTONAL.

One last thing about that one, bestie — it is not collective 🫶 (so every proc does its own lil thing, no group chat needed).

See also: setNewtonALFunction, setNewtonALCorrectionType, SNESNewtonALGetLoadParameter

Source code at petsc4py/PETSc/SNES.pyx:2687

Return type: float 💖

getNormSchedule()</p>

Gimme the norm schedule, pls 👑 — this hands you back which norm schedule the solver is vibing with.

Not collective. 🙅‍♀️

See also: setNormSchedule, SNESGetNormSchedule

Source code at petsc4py/PETSc/SNES.pyx:1281

Return type: NormSchedule

getObjective()</p>

Returns the objective callback tuple — like, the whole "what are we even optimizing here" situation 🎯

Not collective.

See also: setObjective

Source code at petsc4py/PETSc/SNES.pyx:1029

Return type: SNESObjFunction

getOptionsPrefix()</p>

Spill the prefix, bestie 💅 — this returns the prefix string that PETSc uses when it goes digging through the options database looking for your settings.

Not collective.

See also: Working with PETSc options, setOptionsPrefix, SNESGetOptionsPrefix

Source code at petsc4py/PETSc/SNES.pyx:229

Return type: str

getParamsEW()</p>

Get the parameters of the Eisenstat and Walker trick ✨ (yes that's really what it's called, it's giving iconic name energy).

Not collective.

See also: setUseEW, setParamsEW, SNESKSPGetParametersEW

Source code at petsc4py/PETSc/SNES.pyx:2056

Return type: dict[str, int | float]

getPythonContext()</p>

Hands you back the instance of the class that's implementing all the required Python methods 🐍 — the actual object doing the work behind the scenes.

Not collective.

See also: PETSc Python nonlinear solver type (TODO), setPythonContext

Source code at petsc4py/PETSc/SNES.pyx:2247

Return type: Any

getPythonType()</p>

The full, fully-qualified Python name of the class your solver is using — the whole "package.module.ClassName" glow-up, no abbreviations 🙈

Not collective.

See also: PETSc Python nonlinear solver type (TODO), setPythonContext, setPythonType, SNESPythonGetType

Source code at petsc4py/PETSc/SNES.pyx:2277

Return type: str

getRhs()</p>

Returns the Vec holding the right-hand side 🌈 — the classic RHS vector, she's right there.

Not collective.

See also: SNESGetRhs

Source code at petsc4py/PETSc/SNES.pyx:1881

Return type: Vec

getSolution()</p>

Returns the Vec holding the solution, i.e. the answer, the moment, the main character 👑

Not collective.

See also: setSolution, SNESGetSolution

Source code at petsc4py/PETSc/SNES.pyx:1896

Return type: Vec

getSolutionUpdate()</p>

Returns the Vec holding the solution update — the lil delta, the "how much are we moving this step" vector 🦋

Not collective.

See also: SNESGetSolutionUpdate

Source code at petsc4py/PETSc/SNES.pyx:1923

Return type: Vec

getStepFailures()</p>

Returns the current number of step failures 💀 (we don't talk about it, but the number is honest).

Not collective.

See also: getMaxStepFailures, SNESGetNonlinearStepFailures

Source code at petsc4py/PETSc/SNES.pyx:1617

Return type: int

getTRTolerances()</p>

Returns the tolerance parameters used for the trust region — the three numbers that define how big this region is allowed to be, no cap 🌸

Not collective.

Returns

  • delta_min (float) — the minimum allowed trust region size.
  • delta_max (float) — the maximum allowed trust region size.
  • delta_0 (float) — the initial trust region size.

Return type: tuple[float, float, float]

See also: setTRTolerances, getTRUpdateParameters, SNESNewtonTRGetTolerances

Source code at petsc4py/PETSc/SNES.pyx:353

getTRUpdateParameters()</p>

Returns the update parameters used for the trust region — i.e. all the eta's and t's that decide whether we accept the step, shrink, or go bigger 🔥

Not collective.

Returns

  • eta1 (float) — the step acceptance tolerance.
  • eta2 (float) — the shrinking tolerance.
  • eta3 (float) — the enlarging tolerance.
  • t1 (float) — the shrinking factor.
  • t2 (float) — the enlarging factor.

Return type: tuple[float, float, float, float, float]

See also: setTRUpdateParameters, getTRTolerances, SNESNewtonTRGetUpdateParameters

Source code at petsc4py/PETSc/SNES.pyx:412

getTolerances()</p>

Returns the tolerance parameters used in the solver convergence tests — like, the actual "are we done yet??" thresholds, the moment the vibe check finally passes 💅

Not collective.

Returns

…and the rest of getTolerances's tuning knobs, for the record:

Return type: tuple[float, float, float, int] — the tuple bits live at https://docs.python.org/3/builtins/stdtypes.html#tuple, and the float / int bits at https://docs.python.org/3/builtins/functions.html#float and https://docs.python.org/3/builtins/functions.html#int. 💅

See also: setTolerances, SNESGetTolerances — https://petsc.org/release/manualpages/SNES/SNESGetTolerances.html

Source code at petsc4py/PETSc/SNES.pyx:1211 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1211

getType()

Returns the type of the solver. like, which SNES flavor are we running, bestie 🎀

Not collective.

See also: setType, SNESGetType — https://petsc.org/release/manualpages/SNES/SNESGetType.html

Source code at petsc4py/PETSc/SNES.pyx:201 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L201

Return type: str — https://docs.python.org/3/builtins/stdtypes.html#str

getUpdate()

Hands you back the callback that computes the update at the beginning of every single step. yeah, beginning of each step, no cap ✨

Not collective.

See also: setUpdate

Source code at petsc4py/PETSc/SNES.pyx:920 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L920

Return type: SNESUpdateFunction — #petsc4py.typing.SNESUpdateFunction

getUseEW()

Returns the flag that says whether the solver is using the Eisenstat-Walker trick. iconic algorithm behavior honestly 🦋

Not collective.

See also: setUseEW, setParamsEW, SNESKSPGetUseEW — https://petsc.org/release/manualpages/SNES/SNESKSPGetUseEW.html

Source code at petsc4py/PETSc/SNES.pyx:1990 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1990

Return type: bool — https://docs.python.org/3/builtins/functions.html#bool

getUseFD()

Returns true if the solver is using color finite-differencing for the Jacobian. 🌈

Not collective.

See also: setUseFD

Source code at petsc4py/PETSc/SNES.pyx:2150 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2150

Return type: bool — https://docs.python.org/3/builtins/functions.html#bool

getUseKSP()

Returns the flag saying whether the solver is using a linear solver at all. yes queen, sometimes we're rawdogging the linear part 💀

Not collective.

See also: setUseKSP

Source code at petsc4py/PETSc/SNES.pyx:2094 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2094

Return type: bool — https://docs.python.org/3/builtins/functions.html#bool

getUseMF()

Returns the flag saying whether the solver is using matrix-free finite-differencing. no actual matrix stored, just vibes and matvecs ✨

Not collective.

See also: setUseMF

Source code at petsc4py/PETSc/SNES.pyx:2123 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2123

Return type: bool — https://docs.python.org/3/builtins/functions.html#bool

getVIInactiveSet()

Returns the index set for the inactive set. (VI girlies know 👑)

Not collective.

See also: SNESVIGetInactiveSet — https://petsc.org/release/manualpages/SNES/SNESVIGetInactiveSet.html

Source code at petsc4py/PETSc/SNES.pyx:2193 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2193

Return type: IS — #petsc4py.PETSc.IS

getVariableBounds()

Gets the vectors holding the variable bounds. 📏

Collective.

See also: setVariableBounds, SNESVIGetVariableBounds — https://petsc.org/release/manualpages/SNES/SNESVIGetVariableBounds.html

Source code at petsc4py/PETSc/SNES.pyx:2178 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2178

Return type: tuple[Vec, Vec] — tuple at https://docs.python.org/3/builtins/stdtypes.html#tuple, and each Vec is a #petsc4py.PETSc.Vec 🫶

hasNPC()

Returns a boolean telling you whether the solver has a nonlinear preconditioner. fr fr, just a yes/no 🎀

Not collective.

See also: setNPC, getNPC, setNPCSide, getNPCSide, SNESHasNPC — https://petsc.org/release/manualpages/SNES/SNESHasNPC.html

Source code at petsc4py/PETSc/SNES.pyx:693 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L693

Return type: bool — https://docs.python.org/3/builtins/functions.html#bool

logConvergenceHistory(norm, linear_its=0)

Logs the residual norm and the linear iterations. 📝

Source code at petsc4py/PETSc/SNES.pyx:1441 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1441

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

monitor(its, rnorm)

Monitors the solver. like a little livestream of your convergence 👀

Collective.

Parameters

  • its — the current number of iterations.
  • rnorm — the current value of the residual norm.

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: setMonitor, SNESMonitor — https://petsc.org/release/manualpages/SNES/SNESMonitor.html

Source code at petsc4py/PETSc/SNES.pyx:1522 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1522

monitorCancel()

Cancels all the monitors of the solver. every last one, periodt 🛑

Logically collective.

See also: setMonitor, SNESMonitorCancel — https://petsc.org/release/manualpages/SNES/SNESMonitorCancel.html

Source code at petsc4py/PETSc/SNES.pyx:1507 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1507

Return type: None — https://docs.python.org/3/builtins/constants.html#None

reset()

Resets the solver. fresh start energy, we love a clean slate ✨

Collective.

See also: SNESReset — https://petsc.org/release/manualpages/SNES/SNESReset.html

Source code at petsc4py/PETSc/SNES.pyx:1707 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1707

Return type: None — https://docs.python.org/3/builtins/constants.html#None

setApplicationContext(appctx)

Sets the application context. your little bag of whatever you want to carry around, bestie 👜

Source code at petsc4py/PETSc/SNES.pyx:271 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L271

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

setConvergedReason(reason)

Sets the termination flag. you're telling SNES why it's done, so be honest 💅

Collective.

See also: getConvergedReason, SNESSetConvergedReason — https://petsc.org/release/manualpages/SNES/SNESSetConvergedReason.html

Source code at petsc4py/PETSc/SNES.pyx:1742 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1742

Parameters

  • reason (ConvergedReason) — #petsc4py.PETSc.SNES.ConvergedReason

setConvergenceHistory(length=None, reset=False)

Sets the convergence history, bestie — the receipts of how your solve went down. 💅

Logically collective.

  • length — defaults to None
  • reset — defaults to False

See also: SNESSetConvergenceHistory

Source code at petsc4py/PETSc/SNES.pyx:1399 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1399

  • Return type: None — nothing comes back, it just does the thing

setConvergenceTest(converged, args=None, kargs=None)

Set the callback to use as convergence test. So instead of letting the solver decide when it's done, you get to be the judge. main character energy fr. 👑

Logically collective.

Parameters

  • converged (SNESConvergedFunction | Literal['skip', 'default']) — The convergence testing callback. So you can hand it a real callable, or the literal strings 'skip' or 'default' if you just wanna vibe with the built-ins.
  • args (tuple[Any, ...] | None) — Positional arguments for the callback.
  • kargs (dict[str, Any] | None) — Keyword arguments for the callback.
  • Return type: None

See also: getConvergenceTest, callConvergenceTest, SNESSetConvergenceTest

Source code at petsc4py/PETSc/SNES.pyx:1295 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1295

setDM(dm)

Associate a DM with the solver. Like, this SNES needs a situationship with a DM now. 😌

Not collective — so every process does its own thing here, no group chat required.

Parameters

  • dm (DM)
  • Return type: None

See also: getDM, SNESSetDM

Source code at petsc4py/PETSc/SNES.pyx:312 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L312

setDivergenceTolerance(dtol)

Set the divergence tolerance parameter used in the convergence tests. This is the "okay bestie you're going off the rails" threshold. 🚩

Logically collective.

Parameters

  • dtol (float) — The divergence tolerance.
  • Return type: None

See also: getDivergenceTolerance, setTolerances, SNESSetDivergenceTolerance

Source code at petsc4py/PETSc/SNES.pyx:1238 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1238

setErrorIfNotConverged(flag)

Immediately generate an error if the solver has not converged. No silent failures, no pretending everything's fine — if it didn't slay, it tells you. 💀

Collective.

Parameters

  • flag (bool)
  • Return type: None

See also: getErrorIfNotConverged, SNESSetErrorIfNotConverged

Source code at petsc4py/PETSc/SNES.pyx:1769 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1769

setFASInjection(level, mat)

Set the Mat to be used to apply the injection from level-1 to level. ✨

Collective.

Parameters

  • level (int)
  • mat (Mat)
  • Return type: None

See also: getFASInjection, setFASInterpolation, setFASRestriction, SNESFASSetInjection, SNESFAS

Source code at petsc4py/PETSc/SNES.pyx:502 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L502

setFASInterpolation(level, mat)

Set the Mat to be used to apply the interpolation from level-1 to level. Same family as injection but the other direction, iykyk. 🦋

Collective.

Parameters

  • level (int)
  • mat (Mat)
  • Return type: None

See also: getFASInterpolation, setFASRestriction, setFASInjection, SNESFASSetInterpolation, SNESFAS

Source code at petsc4py/PETSc/SNES.pyx:442 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L442

setFASLevels(levels, comms=None)

Set the number of levels to use with FAS. More levels, more multigrid flavor. 🌈

Collective.

Parameters

  • levels (int) — The number of levels
  • comms (Sequence[Comm] | None) — An optional sequence of communicators of length Logging Levels, or None for the default communicator Sys.getDefaultComm.
  • Return type: None

See also: getFASLevels, SNESFASSetLevels, SNESFAS

Source code at petsc4py/PETSc/SNES.pyx:545 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L545

setFASRScale(level, vec)

Set the scaling factor of the restriction operator from level to level-1. A lil vector of vibes-scaling, no cap. 🎀

Collective.

Parameters

  • level (int)
  • vec (Vec)
  • Return type: None

See also: setFASRestriction, SNESFASSetRScale, SNESFAS

Source code at petsc4py/PETSc/SNES.pyx:532 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L532

setFASRestriction(level, mat)

Set the Mat to be used to apply the restriction from level-1 to level. 🫶

Collective.

Parameters

  • level (int)
  • mat (Mat)

See also: setFASRScale, getFASRestriction, setFASInterpolation, setFASInjection, SNESFASSetRestriction, SNESFAS

Source code at petsc4py/PETSc/SNES.pyx:472 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L472

setForceIteration(force)

okay so, sometimes the solver is way too eager to call it a day, and you have to tell it no bestie, you're not done yet. This forces the solve to take at least one iteration. No zero-iteration sneaky exits allowed. 💅

Collective.

See also: SNESSetForceIteration <https://petsc.org/release/manualpages/SNES/SNESSetForceIteration.html>

Source code at petsc4py/PETSc/SNES.pyx:1825 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1825>

Parameters

Return type

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

setFromOptions()

The glow-up moment where your solver reads itself in from the options database and configures accordingly. Basically it goes to the options and is like "oh these are my settings?? slay." ✨

Collective.

See also: Working with PETSc options <#petsc-options>, SNESSetFromOptions <https://petsc.org/release/manualpages/SNES/SNESSetFromOptions.html>

Source code at petsc4py/PETSc/SNES.pyx:257 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L257>

Return type

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

setFunction(function, f=None, args=None, kargs=None)

This is where you hand the solver the callback that computes the nonlinear function. main character energy honestly — this is the whole point of your SNES. 🫶

Logically collective.

Parameters

Return type

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

See also: getFunction, SNESSetFunction <https://petsc.org/release/manualpages/SNES/SNESSetFunction.html>

Source code at petsc4py/PETSc/SNES.pyx:824 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L824>

setFunctionNorm(norm)

Sets the function norm value. You're just dropping the number in, that's it. 💀

Collective.

Heads up bestie — this is only of use to implementers of custom SNES types. If you're not out here writing your own SNES type, this is not your moment.

See also: getFunctionNorm, SNESSetFunctionNorm <https://petsc.org/release/manualpages/SNES/SNESSetFunctionNorm.html>

Source code at petsc4py/PETSc/SNES.pyx:1838 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1838>

Parameters

Return type

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

setInitialGuess(initialguess, args=None, kargs=None)

Register the callback that computes the initial guess — you know, the whole "where do we even start" vibe check the solver does before it goes feral. 🌸

Logically collective.

Parameters

Return type

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

See also: getInitialGuess, SNESSetComputeInitialGuess <https://petsc.org/release/manualpages/SNES/SNESSetComputeInitialGuess.html>

Source code at petsc4py/PETSc/SNES.pyx:781 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L781>

setIterationNumber(its)

Sets the current iteration number. Just, like, telling the solver where it is in its journey. 🦋

Collective.

Again bestie — this is only of use to implementers of custom SNES types. Not for the casual girlies.

See also: getIterationNumber, SNESSetIterationNumber <https://petsc.org/release/manualpages/SNES/SNESSetIterationNumber.html>

Source code at petsc4py/PETSc/SNES.pyx:1796 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1796>

Parameters

Return type

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

setJacobian(jacobian, J=None, P=None, args=None, kargs=None)

The Jacobian callback setup ✨. This is the derivative of your nonlinear function, and honestly it's giving math girlboss. You can also hand it the matrix for the Jacobian and the matrix used to build the preconditioner. 🔥

Logically collective.

Parameters

Return type

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

See also: getJacobian, SNESSetJacobian <https://petsc.org/release/manualpages/SNES/SNESSetJacobian.html>

Source code at petsc4py/PETSc/SNES.pyx:932 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L932>

setKSP(ksp)

Hands the nonlinear solver the linear solver it's gonna use. Matchmaking, but make it numerical. 💜

Logically collective.

See also: getKSP, SNESSetKSP <https://petsc.org/release/manualpages/SNES/SNESSetKSP.html>

Source code at petsc4py/PETSc/SNES.pyx:1940 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1940>

Parameters

  • ksp (KSP <#petsc4py.PETSc.KSP>)

Return type

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

setLineSearch(linesearch)

Sets the linesearch object this SNES is gonna use. It's giving strategic step-size decisions, and honestly it ate. 🎀

Logically collective.

See also: getLineSearch, linesearch, SNESSetLineSearch <https://petsc.org/release/manualpages/SNES/SNESSetLineSearch.html>

Source code at petsc4py/PETSc/SNES.pyx:2634 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2634>

Parameters

  • linesearch (SNESLineSearch <#petsc4py.PETSc.SNESLineSearch>)

Return type

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

💫 setLineSearchPreCheck(precheck, args=None, kargs=None)

Bestie, this one's your lil' hook that fires before the linesearch even gets applied. Like a bouncer checking IDs at the door of the line search. Logically collective, no cap.

Parameters

  • precheck — SNESLSPreFunction or None. The callback itself. 🫶
  • args — tuple[Any, ...] or None. Positional arguments you wanna hand to that callback.
  • kargs — dict[str, Any] or None. Keyword arguments for the callback, same energy.

Return type

None

See also: SNESLineSearchSetPreCheck

Source code at petsc4py/PETSc/SNES.pyx:747

🔥 setMaxFunctionEvaluations(max_funcs)

Sets the maximum allowed number of function evaluations. Basically: how many times are we letting this thing try before we're like okay bestie that's enough. Collective.

See also: getMaxFunctionEvaluations, SNESSetTolerances

Source code at petsc4py/PETSc/SNES.pyx:1545

Parameters

  • max_funcs — int 💅

Return type

None

😭 setMaxKSPFailures(max_fails)

Sets the maximum allowed number of linear solve failures. Yes, it's a vibe check for your KSP. Collective.

See also: getMaxKSPFailures, SNESSetMaxLinearSolveFailures

Source code at petsc4py/PETSc/SNES.pyx:1631

Parameters

  • max_fails — int

Return type

None

💀 setMaxStepFailures(max_fails)

Sets the maximum allowed number of step failures. When the steps keep failing, this is the number of Ls we're willing to take before we stop. Collective.

See also: getMaxStepFailures, SNESSetMaxNonlinearStepFailures

Source code at petsc4py/PETSc/SNES.pyx:1590

Parameters

  • max_fails — int

Return type

None

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

Sets the callback used to monitor solver convergence. This is the one that spies on your solver like a nosy friend watching your story views. Logically collective.

Parameters

  • monitor — SNESMonitorFunction or None. The callback.
  • args — tuple[Any, ...] or None. Positional arguments for the callback.
  • kargs — dict[str, Any] or None. Keyword arguments for the callback.

Return type

None

See also: getMonitor, SNESMonitorSet

Source code at petsc4py/PETSc/SNES.pyx:1462

🎀 setNGS(ngs, args=None, kargs=None)

Sets the callback to compute nonlinear Gauss-Seidel. Say it with me: NGS. Iconic behavior. Logically collective.

Parameters

  • ngs — SNESNGSFunction or None. The nonlinear Gauss-Seidel callback.
  • args — tuple[Any, ...] or None. Positional arguments for the callback.
  • kargs — dict[str, Any] or None. Keyword arguments for the callback.

Return type

None

See also: getNGS, computeNGS, SNESSetNGS

Source code at petsc4py/PETSc/SNES.pyx:1104

👑 setNPC(snes)

Sets the nonlinear preconditioner. The NPC — nonlinear preconditioner, not your group chat NPC, though honestly the energy is adjacent. Logically collective.

See also: getNPC, hasNPC, setNPCSide, getNPCSide, SNESSetNPC

Source code at petsc4py/PETSc/SNES.pyx:707

Parameters

  • snes — SNES

Return type

None

💖 setNPCSide(side)

Sets which side the nonlinear preconditioning lives on. Pick a side, bestie. Collective.

See also: setNPC, getNPC, hasNPC, getNPCSide, SNESSetNPCSide

Source code at petsc4py/PETSc/SNES.pyx:719

Parameters

  • side — Side

Return type

None

🌸 setNewtonALCorrectionType(corrtype)

Sets the correction type for SNESNEWTONAL. Like choosing your filter for the photo, but for an algorithm. Logically collective.

See also: getNewtonALLoadParameter, SNESNewtonALSetCorrectionType

Source code at petsc4py/PETSc/SNES.pyx:2702

Parameters

  • corrtype — NewtonALCorrectionType

Return type

None

🌈 setNewtonALFunction(function, args=None, kargs=None)

Sets the callback that computes the tangent load vector for SNESNEWTONAL. Tangent? Load vector? Yes, we're doing both. Logically collective.

Parameters

  • function — SNESFunction or None. The callback.
  • args (tuple[Any, ...] | None) — the positional args you're yeeting at the callback. That's it, that's the whole job. 🫶
    • kargs (dict[str, Any] | None) — keyword args for the callback, same energy, different pocket. 💅

Return type: None

See also: getNewtonALLoadParameter, SNESNewtonALSetFunction ( https://petsc.org/release/manualpages/SNES/SNESNewtonALSetFunction.html )

Source code at petsc4py/PETSc/SNES.pyx:2656 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2656

🌈 setNormSchedule(normsched) 🌈

Sets the norm schedule, bestie. That's the vibe of the whole method.

Collective. 👑

See also: getNormSchedule, SNESSetNormSchedule ( https://petsc.org/release/manualpages/SNES/SNESSetNormSchedule.html )

Source code at petsc4py/PETSc/SNES.pyx:1269 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1269

Parameters:

  • normsched (NormSchedule) — the norm schedule you want, queen. Not optional, not negotiable. 💖

Return type: None

💖 setObjective(objective, args=None, kargs=None) 💖

Wires up the callback that computes the objective function. Do it.

Logically collective. 🧚

Parameters:

  • objective (SNESObjFunction | None) — the Jacobian callback. (Yes, bestie, that is genuinely what it says here. We just report, we don't rewrite the lore.) 😭
  • args (tuple[Any, ...] | None) — positional args for the callback.
  • kargs (dict[str, Any] | None) — keyword args for the callback.

Return type: None

See also: getObjective, SNESSetObjective ( https://petsc.org/release/manualpages/SNES/SNESSetObjective.html )

Source code at petsc4py/PETSc/SNES.pyx:998 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L998

✨ setOptionsPrefix(prefix) ✨

Sets the prefix that gets used when hunting for options in the options database. It's giving "name tag at the function party so your flags know which object they belong to". 🎀

Logically collective. 👑

See also: Working with PETSc options, SNESSetOptionsPrefix ( https://petsc.org/release/manualpages/SNES/SNESSetOptionsPrefix.html )

Source code at petsc4py/PETSc/SNES.pyx:215 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L215

Parameters:

  • prefix (str | None) — the prefix string. That's the whole arg, no notes. 🦋

Return type: None

🔥 setParamsEW(version=None, rtol_0=None, rtol_max=None, gamma=None, alpha=None, alpha2=None, threshold=None) 🔥

Sets the parameters for the Eisenstat and Walker trick. Iconic little trick, honestly.

Logically collective. 💅

Parameters:

  • version (int | None) — the version of the algorithm. Defaults to CURRENT (petsc4py.PETSc.CURRENT).
  • rtol_0 (float | None) — the initial relative residual norm. Defaults to CURRENT (petsc4py.PETSc.CURRENT).
  • rtol_max (float | None) — the maximum relative residual norm. Defaults to CURRENT (petsc4py.PETSc.CURRENT).
  • gamma (float | None) — parameter. Defaults to CURRENT (petsc4py.PETSc.CURRENT).
  • alpha (float | None) — parameter. Defaults to CURRENT (petsc4py.PETSc.CURRENT).
  • alpha2 (float | None) — parameter. Defaults to CURRENT (petsc4py.PETSc.CURRENT).
  • threshold (float | None) — parameter. Defaults to CURRENT (petsc4py.PETSc.CURRENT).

Return type: None

See also: setUseEW, getParamsEW, SNESKSPSetParametersEW ( https://petsc.org/release/manualpages/SNES/SNESKSPSetParametersEW.html )

Source code at petsc4py/PETSc/SNES.pyx:2004 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2004

🌸 setPatchCellNumbering(sec) 🌸

Sets the cell patch numbering. Very patch, very numbering. 💜

Source code at petsc4py/PETSc/SNES.pyx:2359 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2359

Parameters:

  • sec (Section) — the section you're passing in to do the numbering thing. ✅

Return type: None

🎀 setPatchComputeFunction(function, args=None, kargs=None) 🎀

Sets the patch compute function. Simple as that, no cap.

Source code at petsc4py/PETSc/SNES.pyx:2412 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2412

Return type: None

🌈 setPatchComputeOperator(operator, args=None, kargs=None) 🌈

Sets the patch compute operator. Different noun, same energy as the function one above. 🦋

Source code at petsc4py/PETSc/SNES.pyx:2404 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2404

Return type: None

🌟 setPatchConstructType(typ, operator=None, args=None, kargs=None) 🌟

Sets the patch construct type. typ first, the rest optional, we move. 👑

Source code at petsc4py/PETSc/SNES.pyx:2420 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2420

Return type: None

✨ setPatchDiscretisationInfo(dms, bs, cellNodeMaps, subspaceOffsets, ghostBcNodes, globalBcNodes) ✨

Sets the patch discretisation information. Big signature, big responsibilities, bestie. Six args and not one of them is decoration. 💅

Source code at petsc4py/PETSc/SNES.pyx:2363 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2363

Return type: None

🧚 setPythonContext(context) 🧚

Sets the instance of the class that implements the required Python methods. Basically: here's my little object, please let it be the brain of the operation. 🫶

Not collective. 🙈

See also: PETSc Python nonlinear solver type (TODO), getPythonContext

Source code at petsc4py/PETSc/SNES.pyx:2235 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2235

✨ setPythonType(py_type)

okay so this one sets the fully qualified Python name of the class to be used 💅

Collective.

See also:

Source code at petsc4py/PETSc/SNES.pyx:2262 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2262

Parameters:

Return type: None — https://docs.python.org/3/builtins/constants.html#None

✨ setResetCounters(reset=True)

sets the flag to reset the counters, bestie 🎀

Collective.

See also:

Source code at petsc4py/PETSc/SNES.pyx:1447 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1447

Parameters:

Return type: None — https://docs.python.org/3/builtins/constants.html#None

✨ setSolution(vec)

sets the vector that stores the solution, no cap 🌸

Collective.

See also:

Source code at petsc4py/PETSc/SNES.pyx:1911 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1911

Parameters:

  • vec (Vec — anchor #petsc4py.PETSc.Vec)

Return type: None — https://docs.python.org/3/builtins/constants.html#None

✨ setTRTolerances(delta_min=None, delta_max=None, delta_0=None)

this one sets the tolerance parameters used for the trust region 🔥

Logically collective.

Parameters:

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also:

Source code at petsc4py/PETSc/SNES.pyx:326 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L326

✨ setTRUpdateParameters(eta1=None, eta2=None, eta3=None, t1=None, t2=None)

and this one sets the update parameters used for the trust region 💜

Logically collective.

Parameters:

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also:

Source code at petsc4py/PETSc/SNES.pyx:377 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L377

✨ setTolerances(rtol=None, atol=None, stol=None, max_it=None)

the big one, bestie 👑 this sets the tolerance parameters used in the solver convergence tests.

Logically collective.

Parameters:

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also:

Source code at petsc4py/PETSc/SNES.pyx:1172 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1172

✨ setType(snes_type)

sets the type of the solver ✨ (iconic behaviour, honestly)

Logically collective.

Parameters:

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also:

Source code at petsc4py/PETSc/SNES.pyx:182 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L182

✨ setUp()

sets up all the internal data structures so the solver can actually do its thing 🦋

Collective.

See also:

Source code at petsc4py/PETSc/SNES.pyx:1681 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1681

Return type: None

✨ setUpMatrices() ✨

Ensures that matrices are available for Newton-like methods. periodt 💅

Collective.

Bestie, listen — this one is only of use to implementers of custom SNES types. Like, if you're not out here building your own solver type, this is not your business, no shade. 🙈

See also: setUp, SNESSetUpMatrices — https://petsc.org/release/manualpages/SNES/SNESSetUpMatrices.html

Source code at petsc4py/PETSc/SNES.pyx:1693 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1693

Return type: None

🦋 setUpdate(update, args=None, kargs=None) 🦋

Sets the callback that computes the update at the beginning of each step. Literally every step, she's there, she's ready. 👑

Logically collective.

Parameters

  • update (SNESUpdateFunction | None) — The callback. The whole main character of this function, ngl.
  • args (tuple[Any, ...] | None) — Positional arguments for the callback.
  • kargs (dict[str, Any] | None) — Keyword arguments for the callback.

Return type: None

See also: getUpdate, SNESSetUpdate — https://petsc.org/release/manualpages/SNES/SNESSetUpdate.html

Source code at petsc4py/PETSc/SNES.pyx:889 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L889

🍓 setUseEW(flag=True, *targs, **kargs) 🍓

Tells the solver to use the Eisenstat-Walker trick. It's giving "skip some work, stay iconic". ✨

Logically collective.

Parameters

  • flag (bool) — Whether or not to use the Eisenstat-Walker trick.
  • *targs (Any) — Positional arguments for setParamsEW.
  • **kargs (Any) — Keyword arguments for setParamsEW.

Return type: None

See also: getUseEW, setParamsEW, SNESKSPSetUseEW — https://petsc.org/release/manualpages/SNES/SNESKSPSetUseEW.html

Source code at petsc4py/PETSc/SNES.pyx:1967 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1967

🌈 setUseFD(flag=True) 🌈

Sets the boolean flag for using coloring finite-differencing for the Jacobian assembly. Yes bestie, we're approximating, we're thriving. 🧚

Logically collective.

See also: getUseFD

Source code at petsc4py/PETSc/SNES.pyx:2137 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2137

Return type: None

💜 setUseKSP(flag=True) 💜

Sets the boolean flag that says "yes, we're using a linear solver". Linear solver? In this economy? Yes. 😌

Logically collective.

See also: getUseKSP

Source code at petsc4py/PETSc/SNES.pyx:2081 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2081

Return type: None

🎀 setUseMF(flag=True) 🎀

Sets the boolean flag that says we're doing matrix-free finite-differencing. No matrix? No problem. We contain multitudes. 🦋

Logically collective.

See also: getUseMF

Source code at petsc4py/PETSc/SNES.pyx:2110 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2110

Return type: None

🌸 setVariableBounds(xl, xu) 🌸

Sets the vectors for the variable bounds — your lower girlies and your upper girlies. Boundaries are self-care. 💖

Collective.

See also: getVariableBounds, SNESVISetVariableBounds — https://petsc.org/release/manualpages/SNES/SNESVISetVariableBounds.html

Source code at petsc4py/PETSc/SNES.pyx:2166 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2166

Parameters

  • xl (Vec)
  • xu (Vec)

Return type: None

⭐ solve(b=None, x=None) ⭐

Solves the nonlinear equations. This is the moment, the actual solve, the main event. Everybody else in this entire page was just setting the stage. 🔥

Collective.

Parameters

  • b (Vec | None) — The affine right-hand side, or None to use zero.
  • x (Vec | None) — The starting vector, or None to use the vector stored internally.

Return type: None

See also: setSolution, getSolution, SNESSolve — https://petsc.org/release/manualpages/SNES/SNESSolve.html

Source code at petsc4py/PETSc/SNES.pyx:1719 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L1719

💅 view(viewer=None) 💅

Views the solver. Like, let her be seen. She's been working hard. ✨

Collective.

Parameters

  • viewer (Viewer | None) — A Viewer instance, or None for the default viewer.

Return type: None

See also: SNESView — https://petsc.org/release/manualpages/SNES/SNESView.html

Source code at petsc4py/PETSc/SNES.pyx:129 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L129

👑 Attributes Documentation 👑

Okay bestie, plot twist: some of this stuff isn't a method, it's an attribute. You just reach in and grab it like a snack. 🍓 Here's the whole lineup, no gatekeeping, fr fr.

appctx

Application context.

Source code at petsc4py/PETSc/SNES.pyx:2436 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2436

atol

Absolute residual tolerance.

Source code at petsc4py/PETSc/SNES.pyx:2517 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2517

dm

DM.

Source code at petsc4py/PETSc/SNES.pyx:2446 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2446

history

Convergence history. Receipts. 🧾

Source code at petsc4py/PETSc/SNES.pyx:2569 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2569

is_converged

Boolean indicating if the solver has converged. We ate. 💅

Source code at petsc4py/PETSc/SNES.pyx:2589 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2589

is_diverged

Boolean indicating if the solver has failed. 💀 it did not eat. Not me checking this one first every single time.

Source code at petsc4py/PETSc/SNES.pyx:2594 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2594

is_iterating

Boolean indicating if the solver has not converged yet. She's in her journey era, she's still going, don't rush her. 🦋

Source code at petsc4py/PETSc/SNES.pyx:2584 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2584

its

Number of iterations.

  • ksp — the linear solver, bestie 🔥

Source code at petsc4py/PETSc/SNES.pyx:2483 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2483>

  • linesearch — the linesearch object that's vibing with this SNES 💅

Source code at petsc4py/PETSc/SNES.pyx:2646 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2646>

  • max_funcs — the max number of function evaluations, like the ceiling, the limit, the "okay we're done here" 💀

Source code at petsc4py/PETSc/SNES.pyx:2543 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2543>

  • max_it — the max number of iterations, no cap ✨

Source code at petsc4py/PETSc/SNES.pyx:2533 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2533>

  • norm — the function norm 🎀

Source code at petsc4py/PETSc/SNES.pyx:2561 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2561>

  • npc — the nonlinear preconditioner 🌸

Source code at petsc4py/PETSc/SNES.pyx:2456 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2456>

  • reason — the converged reason, i.e. why we're calling it a day 🦋

Source code at petsc4py/PETSc/SNES.pyx:2576 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2576>

  • rtol — relative residual tolerance 💜

Source code at petsc4py/PETSc/SNES.pyx:2509 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2509>

  • stol — solution update tolerance

Source code at petsc4py/PETSc/SNES.pyx:2525 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2525>

  • use_ew — use the Eisenstat-Walker trick, iconic behavior honestly 🌈

Source code at petsc4py/PETSc/SNES.pyx:2499 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2499>

  • use_fd — a boolean, True if the solver uses coloring finite-differencing 👑

Source code at petsc4py/PETSc/SNES.pyx:2609 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2609>

  • use_ksp — a boolean, True if the solver uses a linear solver 💖

Source code at petsc4py/PETSc/SNES.pyx:2491 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2491>

  • use_mf — a boolean, True if the solver uses matrix-free finite-differencing ⭐

Source code at petsc4py/PETSc/SNES.pyx:2601 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2601>

  • vec_rhs — the right-hand side vector 💅

Source code at petsc4py/PETSc/SNES.pyx:2476 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2476>

  • vec_sol — the solution vector, the moment we've all been waiting for 🎀

Source code at petsc4py/PETSc/SNES.pyx:2466 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2466>

  • vec_upd — the update vector

Source code at petsc4py/PETSc/SNES.pyx:2471 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2471>

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

🦋 petsc4py.PETSc.SNESLineSearch

class petsc4py.PETSc.SNESLineSearch

Bases: Object <#petsc4py.PETSc.Object>

okay so this is the Linesearch object that SNES solvers use — she's the one doing the fine-tuning, the little adjustment step, the "let's not overshoot bestie" energy 🫶

See also:

SNESLineSearch — <https://petsc.org/release/manualpages/SNES/SNESLineSearch.html>

Enumerations

  • Type — <#petsc4py.PETSc.SNESLineSearch.Type> — the SNES linesearch type, i.e. which flavor of linesearch are we doing 💅

✨ petsc4py.PETSc.SNESLineSearch.Type

class petsc4py.PETSc.SNESLineSearch.Type

Bases: object — <https://docs.python.org/3/builtins/functions.html#object>

SNES linesearch type 🌸

See also:

SNESLineSearchType — <https://petsc.org/release/manualpages/SNES/SNESLineSearchType.html>

Attributes Summary

Attributes Documentation

Object BASIC of type str — <https://docs.python.org/3/builtins/stdtypes.html#str>

Object BISECTION of type str — <https://docs.python.org/3/builtins/stdtypes.html#str>

Object BT of type str — <https://docs.python.org/3/builtins/stdtypes.html#str>

Object CP of type str — <https://docs.python.org/3/builtins/stdtypes.html#str>

Object NCGLINEAR of type str — <https://docs.python.org/3/builtins/stdtypes.html#str>

Object NLEQERR of type str — <https://docs.python.org/3/builtins/stdtypes.html#str>

__init__()

classmethod __new__(*args, **kwargs)

✨ Methods Summary ✨

  • create([comm]) — Create a new linesearch object. 🐣
  • destroy() — Destroy the linesearch object. 💀
  • getOrder() — Return the order of the linesearch.
  • getTolerances() — Return the tolerance parameters used in the linesearch. 🎚️
  • getType() — Return the type of the linesearch.
  • setFromOptions() — Configure the linesearch from the options database.
  • setOrder(order) — Set the order of the linesearch.
  • setTolerances([minstep, maxstep, rtol, ...]) — Set the tolerance parameters used in the linesearch.
  • setType(ls_type) — Set the type of the linesearch.
  • view([viewer]) — View the linesearch object. 👀

📖 Methods Documentation 📖

create(comm=None)

Create a new linesearch object. It's giving new beginnings ✨

Collective.

Parameters

  • comm (Comm, optional) — MPI communicator, defaults to Sys.getDefaultComm.

Return type

Self (https://docs.python.org/3/library/typing.html#typing.Self)

See also:

Source code at petsc4py/PETSc/SNES.pyx:2751 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2751)

destroy()

Destroy the linesearch object. Cleanup era 💅

Collective.

See also:

Source code at petsc4py/PETSc/SNES.pyx:2925 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2925)

Return type

Self (https://docs.python.org/3/library/typing.html#typing.Self)

getOrder()

Return the order of the linesearch. Just hands you the number, no drama.

Not collective.

See also:

Source code at petsc4py/PETSc/SNES.pyx:2898 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2898)

Return type

int (https://docs.python.org/3/builtins/functions.html#int)

getTolerances()

Return the tolerance parameters used in the linesearch. All the knobs, in one lil tuple 🎚️✨

Not collective.

Returns

Return type

tuple (https://docs.python.org/3/builtins/stdtypes.html#tuple)[float (https://docs.python.org/3/builtins/functions.html#float), float (https://docs.python.org/3/builtins/functions.html#float), float (https://docs.python.org/3/builtins/functions.html#float), float (https://docs.python.org/3/builtins/functions.html#float), float (https://docs.python.org/3/builtins/functions.html#float), int (https://docs.python.org/3/builtins/functions.html#int)]

See also:

Source code at petsc4py/PETSc/SNES.pyx:2831 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2831)

getType()

Return the type of the linesearch. Identity check, but make it computational 💖

Not collective.

See also:

Source code at petsc4py/PETSc/SNES.pyx:2803 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2803)

Return type

str (https://docs.python.org/3/builtins/stdtypes.html#str)

setFromOptions()

Configure the linesearch from the options database. Let the command line be the main character ❇️

Collective.

See also:

Source code at petsc4py/PETSc/SNES.pyx:2772 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2772)

Return type

None (https://docs.python.org/3/builtins/constants.html#None)

setOrder(order)

Set the order of the linesearch. Yes bestie, you're in charge of the order now 👑

Logically collective.

See also:

Source code at petsc4py/PETSc/SNES.pyx:2912 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2912)

Parameters

Return type

None (https://docs.python.org/3/builtins/constants.html#None)

setTolerances(minstep=None, maxstep=None, rtol=None, atol=None, ltol=None, max_its=None)

Set the tolerance parameters used in the linesearch. Dial in every single knob, fr fr 🎛️

Logically collective.

Parameters

okay so the rest of this parameter list is coming right up, bestie — stay tuned 💖

  • minstep (float) — the minimum step length. tiny steps only, bestie 🐜
  • maxstep (float, optional) — the maximum step length. the ceiling, the limit, the "okay that's enough" 🛑
  • rtol (float, optional) — relative tolerance.
  • atol (float, optional) — absolute tolerance.
  • ltol (float, optional) — lambda tolerance.
  • max_its (int, optional) — maximum number of iterations for the linesearch. cap it, queen 👑

Return type

None

See also:

getTolerances, SNESLineSearchSetTolerances — https://petsc.org/release/manualpages/SNES/SNESLineSearchSetTolerances.html

Source code at petsc4py/PETSc/SNES.pyx:2860 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2860

💫 setType(ls_type)

ok so this one sets the type of the linesearch. that's it, that's the whole job ✨

Logically collective. (so like, everybody has to call it together, no solo acts 💅)

See also:

getType, SNESLineSearchSetType — https://petsc.org/release/manualpages/SNES/SNESLineSearchSetType.html

Source code at petsc4py/PETSc/SNES.pyx:2817 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2817

Parameters

  • ls_type (SNESLineSearch.Type | str)

Return type

None

🦋 view(viewer=None)

shows you the linesearch object. like a soft launch but for your solver internals 📸

Collective.

Parameters

  • viewer (Viewer | None) — a Viewer instance, or None for the default viewer.

Return type

None

See also:

SNESLineSearchView — https://petsc.org/release/manualpages/SNES/SNESLineSearchView.html

Source code at petsc4py/PETSc/SNES.pyx:2784 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/SNES.pyx#L2784

__init__()

classmethod __new__(*args, **kwargs)

💖 petsc4py.PETSc.Scatter 💖

  • class petsc4py.PETSc.Scatter
  • Bases: Object

it's the Scatter object, bestie. this is the lil icon whose entire job is moving data between vectors. it's giving post office but for numbers 📬✨ and the PETSc manual explains it here: https://petsc.org/release/manual/vec.html#sec-scatter

See also:

Vec, SF, VecScatter — https://petsc.org/release/manualpages/PetscSF/VecScatter.html

Enumerations

  • Mode — Scatter mode. (it's #petsc4py.PETSc.Scatter.Mode)
  • Type — Scatter type. (it's #petsc4py.PETSc.Scatter.Type)

🔮 petsc4py.PETSc.Scatter.Mode 🔮

  • class petsc4py.PETSc.Scatter.Mode
  • Bases: object

Scatter mode. the vibe check for which direction your data is traveling 🚦

the most commonly used scatter modes are:

  • FORWARD — scatter values in the forward direction.
  • REVERSE — scatter values in the reverse direction.

See also:

Scatter.create, Scatter.begin, Scatter.end, ScatterMode — https://petsc.org/release/manualpages/Vec/ScatterMode.html

📋 Attributes Summary

  • FORWARD — constant FORWARD of type int
  • FORWARD_LOCAL — constant FORWARD_LOCAL of type int
  • REVERSE — constant REVERSE of type int
  • REVERSE_LOCAL — constant REVERSE_LOCAL of type int
  • SCATTER_FORWARD — constant SCATTER_FORWARD of type int
  • SCATTER_FORWARD_LOCAL — constant SCATTER_FORWARD_LOCAL of type int
  • SCATTER_REVERSE — constant SCATTER_REVERSE of type int
  • SCATTER_REVERSE_LOCAL — constant SCATTER_REVERSE_LOCAL of type int

🎀 Attributes Documentation

  • FORWARD: int = FORWARD — constant FORWARD of type int
  • FORWARD_LOCAL: int = FORWARD_LOCAL — constant FORWARD_LOCAL of type int
  • REVERSE: int = REVERSE — constant REVERSE of type int
  • REVERSE_LOCAL: int = REVERSE_LOCAL — constant REVERSE_LOCAL of type int

still going, don't go anywhere — more of this page is loading 💜

  • SCATTER_FORWARD: int = SCATTER_FORWARD — the constant SCATTER_FORWARD, and its type is int. 💅
  • SCATTER_FORWARD_LOCAL: int = SCATTER_FORWARD_LOCAL — the constant SCATTER_FORWARD_LOCAL, type int, no cap.
  • SCATTER_REVERSE: int = SCATTER_REVERSE — the constant SCATTER_REVERSE, also an int. bestie these are just the reverse vibes of the forward ones, iconic.
  • SCATTER_REVERSE_LOCAL: int = SCATTER_REVERSE_LOCAL — the constant SCATTER_REVERSE_LOCAL, type int.

and then the constructor-ish stuff, bestie:

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

🌈 petsc4py.PETSc.Scatter.Type 🌈

class petsc4py.PETSc.Scatter.Type
  • Bases: object 🫶

Scatter type. literally the type-of-scatter label, that's the whole job. simple. elegant. main character energy.

See also:

  • VecScatterType

✨ Attributes Summary ✨

every single one of these is a str, and every single one equals its own name. the format is Object <NAME> of type str. yes it's that kind of party:

  • ALLGATHER — Object ALLGATHER of type str
  • ALLGATHERV — Object ALLGATHERV of type str
  • ALLTOALL — Object ALLTOALL of type str
  • BASIC — Object BASIC of type str
  • GATHER — Object GATHER of type str
  • GATHERV — Object GATHERV of type str
  • NEIGHBOR — Object NEIGHBOR of type str
  • WINDOW — Object WINDOW of type str

💖 Attributes Documentation 💖

okay so here they all are again but with the full documentation glow-up, one at a time, slay:

ALLGATHER</p>

ALLGATHER: str = ALLGATHER

Object ALLGATHER of type str. 🌸

ALLGATHERV</p>

ALLGATHERV: str = ALLGATHERV

Object ALLGATHERV of type str. 🌸

ALLTOALL</p>

ALLTOALL: str = ALLTOALL

Object ALLTOALL of type str. 🌸

BASIC</p>

BASIC: str = BASIC

Object BASIC of type str. 🌸

GATHER</p>

GATHER: str = GATHER

Object GATHER of type str. 🌸

GATHERV</p>

GATHERV: str = GATHERV

Object GATHERV of type str. 🌸

NEIGHBOR</p>

NEIGHBOR: str = NEIGHBOR

Object NEIGHBOR of type str. 🌸

WINDOW</p>

WINDOW: str = WINDOW

Object WINDOW of type str. 🌸

and the good old constructor pair, still here, still doing their thing:

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

periodt 💅✨

🎀 Methods Summary 🎀

okay bestie, before we get into the deep lore, here's the whole squad at a glance — every method you're gonna be texting on this object 💅:

  • begin(vec_from, vec_to[, addv, mode]) — Begin a generalized scatter from one vector into another.
  • copy() — Return a copy of the scatter.
  • create(vec_from, is_from, vec_to, is_to) — Create a scatter object.
  • destroy() — Destroy the scatter.
  • end(vec_from, vec_to[, addv, mode]) — Complete a generalized scatter from one vector into another.
  • getType() — Return the type of the scatter.
  • scatter(vec_from, vec_to[, addv, mode]) — Perform a generalized scatter from one vector into another.
  • setFromOptions() — Configure the scatter from the options database.
  • setType(scatter_type) — Set the type of the scatter.
  • setUp() — Set up the internal data structures for using the scatter.
  • toAll(vec) — Create a scatter that communicates a vector to all sharing processes.
  • toZero(vec) — Create a scatter that communicates a vector to rank zero.
  • view([viewer]) — View the scatter.

🦋 Methods Documentation 🦋

begin(vec_from, vec_to, addv=None, mode=None)

Begin a generalized scatter from one vector into another. ✨

Collective. (yes bestie, everyone in the communicator has to be on the call 📞 no ghosting)

This call has to be concluded with a call to end. For additional details on the Parameters, see scatter.

See also: create, end, VecScatterBegin <https://petsc.org/release/manualpages/Vec/VecScatterBegin.html>

Source code at petsc4py/PETSc/Scatter.pyx:262 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Scatter.pyx#L262

Parameters

  • vec_from (Vec <#petsc4py.PETSc.Vec>)
  • vec_to (Vec <#petsc4py.PETSc.Vec>)
  • addv (InsertModeSpec <#petsc4py.typing.InsertModeSpec>)
  • mode (ScatterModeSpec <#petsc4py.typing.ScatterModeSpec>)

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

copy()

Return a copy of the scatter. 🫶 same vibe, brand new object, no shared drama.

Source code at petsc4py/PETSc/Scatter.pyx:199 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Scatter.pyx#L199

Return type: Scatter <#petsc4py.PETSc.Scatter>

create(vec_from, is_from, vec_to, is_to)

Create a scatter object. 🌸

Collective. (again — everybody's here, nobody's on mute)

Parameters

  • vec_from (Vec <#petsc4py.PETSc.Vec>) — the representative vector you're scattering the data from.
  • is_from (IS <#petsc4py.PETSc.IS>) — the indices of vec_from you wanna scatter. If it's None <https://docs.python.org/3/builtins/constants.html#None>, then bestie, use all the indices 💅
  • vec_to (Vec <#petsc4py.PETSc.Vec>) — the representative vector you're scattering the data to.
  • is_to (IS <#petsc4py.PETSc.IS>) — the indices of vec_to where you receive. If it's None <https://docs.python.org/3/builtins/constants.html#None>, use all the indices, periodt.

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

Examples

The scatter object can be used to repeatedly perform data movement — that's literally its whole thing, it's giving reusable. It is the PETSc equivalent of NumPy-like indexing and slicing, with support for parallel communications 🦋

>>> revmode = PETSc.Scatter.Mode.REVERSE
>>> v1 = PETSc.Vec().createWithArray([1, 2, 3])
>>> v2 = PETSc.Vec().createWithArray([0, 0, 0])
>>> sct = PETSc.Scatter().create(v1,None,v2,None)
>>> sct.scatter(v1,v2) # v2[:] = v1[:]
>>> sct.scatter(v2,v1,mode=revmode) # v1[:] = v2[:]
>>> revmode = PETSc.Scatter.Mode.REVERSE
>>> v1 = PETSc.Vec().createWithArray([1, 2, 3, 4])
>>> v2 = PETSc.Vec().createWithArray([0, 0])
>>> is1 = PETSc.IS().createStride(2, 3, -2)
>>> sct = PETSc.Scatter().create(v1,is1,v2,None)
>>> sct.scatter(v1,v2) # v2[:] = v1[3:0:-2]
>>> sct.scatter(v2,v1,mode=revmode) # v1[3:0:-2] = v2[:]

See also: IS <#petsc4py.PETSc.IS>, VecScatterCreate <https://petsc.org/release/manualpages/Vec/VecScatterCreate.html>

Source code at petsc4py/PETSc/Scatter.pyx:90 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Scatter.pyx#L90

destroy()

Destroy the scatter. 💀 it's over, it's done, no more data movement for this one.

Collective.

See also: VecScatterDestroy <https://petsc.org/release/manualpages/Vec/VecScatterDestroy.html>

Source code at petsc4py/PETSc/Scatter.pyx:77 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Scatter.pyx#L77

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

end(vec_from, vec_to, addv=None, mode=None)

Complete a generalized scatter from one vector into another. ✨ the second half of the glow-up.

Collective. (yep, group activity again 🫶)

This call has to be preceded by a call to begin. For additional details on the Parameters, see scatter.

See also: create, begin, VecScatterEnd <https://petsc.org/release/manualpages/Vec/VecScatterEnd.html>

Source code at petsc4py/PETSc/Scatter.pyx:285 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Scatter.pyx#L285

Parameters

  • vec_from (Vec <#petsc4py.PETSc.Vec>)
  • vec_to (Vec <#petsc4py.PETSc.Vec>)
  • addv (InsertModeSpec <#petsc4py.typing.InsertModeSpec>)
  • mode (ScatterModeSpec <#petsc4py.typing.ScatterModeSpec>)

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

getType()

Return the type of the scatter. 👑

Not collective. (so this one's a solo mission, you do it by yourself, no group chat needed 💅)

See also: setType, VecScatterGetType <https://petsc.org/release/manualpages/Vec/VecScatterGetType.html>

📍 last lil bit of the method from before:

Source code at petsc4py/PETSc/Scatter.pyx:160 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Scatter.pyx#L160>

Return type: str — <https://docs.python.org/3/builtins/stdtypes.html#str>

scatter(vec_from, vec_to, addv=None, mode=None)

Bestie, this one does a generalized scatter from one vector into another. ✨

Collective, so everybody's in on it together. 💅

Parameters

  • vec_from (Vec) — the source vector. where the tea comes from 🍓
  • vec_to (Vec) — the destination vector. where the tea's going 🌸
  • addv (InsertModeSpec) — insertion mode.
  • mode (ScatterModeSpec) — scatter mode.

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

See also: create, begin, end, VecScatterBegin <https://petsc.org/release/manualpages/Vec/VecScatterBegin.html>, VecScatterEnd <https://petsc.org/release/manualpages/Vec/VecScatterEnd.html>

Source code at petsc4py/PETSc/Scatter.pyx:308 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Scatter.pyx#L308>

setFromOptions()

Configures the scatter from the options database. iconic honestly 🎀

Collective.

See also: Working with PETSc options <#petsc-options>, VecScatterSetFromOptions <https://petsc.org/release/manualpages/Vec/VecScatterSetFromOptions.html>

Source code at petsc4py/PETSc/Scatter.pyx:174 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Scatter.pyx#L174>

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

setType(scatter_type)

Sets the type of the scatter. no cap 🧚

Logically collective.

See also: getType, VecScatterSetType <https://petsc.org/release/manualpages/Vec/VecScatterSetType.html>

Source code at petsc4py/PETSc/Scatter.pyx:146 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Scatter.pyx#L146>

Parameters

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

setUp()

Sets up the internal data structures for using the scatter. like, gets all the behind-the-scenes ready so the actual scatter can slay 💖

Collective.

See also: VecScatterSetUp <https://petsc.org/release/manualpages/Vec/VecScatterSetUp.html>

Source code at petsc4py/PETSc/Scatter.pyx:186 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Scatter.pyx#L186>

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

classmethod toAll(vec)

Creates a scatter that communicates a vector to all the sharing processes. everybody gets a copy, we love an inclusive queen 👑

Collective.

Parameters

  • vec (Vec) — the vector to scatter from.

Return type: tuple[Scatter, Vec] — <https://docs.python.org/3/builtins/stdtypes.html#tuple>

Notes

The created scatter will have the same communicator of vec. The method also returns an output vector of appropriate size to contain the result of the operation. 🎀

See also: toZero, VecScatterCreateToAll <https://petsc.org/release/manualpages/Vec/VecScatterCreateToAll.html>

Source code at petsc4py/PETSc/Scatter.pyx:205 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Scatter.pyx#L205>

classmethod toZero(vec)

Creates a scatter that communicates a vector to rank zero. main character energy tbh ⭐

Collective.

Parameters

  • vec (Vec) — the vector to scatter from.

Return type: tuple[Scatter, Vec] — <https://docs.python.org/3/builtins/stdtypes.html#tuple>

Notes

The created scatter will have the same communicator of vec. The method also returns an output vector of appropriate size to contain the result of the operation. 🦋

See also: toAll, VecScatterCreateToZero <https://petsc.org/release/manualpages/Vec/VecScatterCreateToZero.html>

Source code at petsc4py/PETSc/Scatter.pyx:233 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Scatter.pyx#L233>

view(viewer=None)

Views the scatter. the little vibe check for your scatter, fr fr 🔍

Collective.

Parameters

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

See also: VecScatterView <https://petsc.org/release/manualpages/Vec/VecScatterView.html>

Source code at petsc4py/PETSc/Scatter.pyx:58 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Scatter.pyx#L58>

__init__()

classmethod __new__(*args, **kwargs)

petsc4py.PETSc.ScatterMode

class petsc4py.PETSc.ScatterMode

Bases: object — <https://docs.python.org/3/builtins/functions.html#object>

Scatter mode. the direction your values are going, bestie 💫

Most commonly used scatter modes are:

FORWARD Scatter values in the forward direction. ⏩

REVERSE Scatter values in the reverse direction. ⏪

See also: Scatter.create <#petsc4py.PETSc.Scatter.create>, Scatter.begin <#petsc4py.PETSc.Scatter.begin>, Scatter.end <#petsc4py.PETSc.Scatter.end>, ScatterMode <https://petsc.org/release/manualpages/Vec/ScatterMode.html>

📋 Attributes Summary ✨

okay bestie, here's the whole squad of constants this thing ships with 💅 every single one is an int, and they all link back to the Python builtin docs at https://docs.python.org/3/builtins/functions.html#int — yes, all of them, same link, they're not special 😭

🔍 Attributes Documentation 💖

this is the same eight besties again but now they get their own lil spotlight moment, each with the value they hold 👑

FORWARD: int = FORWARD

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

FORWARD_LOCAL: int = FORWARD_LOCAL

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

REVERSE: int = REVERSE

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

REVERSE_LOCAL: int = REVERSE_LOCAL

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

SCATTER_FORWARD: int = SCATTER_FORWARD

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

SCATTER_FORWARD_LOCAL: int = SCATTER_FORWARD_LOCAL

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

SCATTER_REVERSE: int = SCATTER_REVERSE

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

SCATTER_REVERSE_LOCAL: int = SCATTER_REVERSE_LOCAL

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

__init__()

fr fr, there's an __init__ too 🌸

classmethod __new__(*args, **kwargs)

yep, __new__ is a classmethod and it takes *args and **kwargs — classic 🫶

🦋 petsc4py.PETSc.Section 🦋

class petsc4py.PETSc.Section

Bases: Object (that's the petsc4py.PETSc.Object one, iykyk 💜)

Mapping from integers in a range to unstructured set of integers. literally it maps a range of ints onto an unstructured set of ints, and that's the whole vibe ✨

Methods Summary 🎀

okay bestie, gather round 👑 — here's the full methods menu, and every single one is getting its moment. no skips, no cap. 💅

  • addConstraintDof(point, numDof) — increments the number of constrained DOFs for a given point. so like, you're bumping up how many constrained DOFs that point has. ✨
  • addDof(point, numDof) — adds numDof degrees of freedom associated with a given point. more DOFs for the point, periodt. 🦋
  • addFieldConstraintDof(point, field, numDof) — adds numDof constrained DOFs for a given field on a point. yep, constrained DOFs, but field-specific. 💖
  • addFieldDof(point, field, numDof) — adds numDof DOFs associated with a field on a given point. field DOFs go brrr. 🌸
  • clone() — returns a copy of the section. literally a lil duplicate. 👯
  • create([comm]) — allocates a section and sets the map contents to the default. [comm] is right there in the signature, okay? 🫶
  • createGlobalSection(sf) — creates a section describing the global field layout. global vibes only. 🌍
  • destroy() — destroys a section. rip to that section, but we move. 💀
  • getChart() — returns the range in which points (indices) lie for this section. so like, the chart zone. 📊
  • getConstrainedStorageSize() — returns the size capable of holding all unconstrained DOFs in a section. read that again: unconstrained DOFs. no cap. ✨
  • getConstraintDof(point) — returns the number of constrained DOFs associated with a given point. just the count, bestie. 🔢
  • getConstraintIndices(point) — returns the point DOFs numbers which are constrained for a given point. so which DOFs are locked down. 🔒
  • getDof(point) — returns the number of degrees of freedom for a given point. DOF count check. 💅
  • getFieldComponents(field) — returns the number of field components for the given field. components, plural. 🧩
  • getFieldConstraintDof(point, field) — returns the number of constrained DOFs for a given field on a point. field + point = constrained DOF count. 🌈
  • getFieldConstraintIndices(point, field) — returns the field DOFs numbers, in [0, DOFs), which are constrained. keep that range, bestie. ⭐
  • getFieldDof(point, field) — returns the number of DOFs associated with a field on a given point. field DOF count, slay. 🔥
  • getFieldName(field) — returns the name of a field in the section. name drop. 🎀
  • getFieldOffset(point, field) — returns the offset for the field DOFs on the given point. offset for the field, got it. 💜
  • getMaxDof() — returns the maximum number of DOFs for any point in the section. the biggest DOF energy. 👑
  • getNumFields() — returns the number of fields in a section. how many fields we got? 🌻
  • getOffset(point) — returns the offset for the DOFs associated with the given point. offset for that point's DOFs. 🦋
  • getOffsetRange() — returns the full range of offsets, [start, end), for a section. full range, half-open interval, iconic. 💖
  • getPermutation() — returns the permutation that was set with setPermutation. so if you set it, here it is. 🔁
  • getStorageSize() — returns the size capable of holding all the DOFs defined in a section. all the DOFs. storage size. periodt. 💾
  • reset() — frees all section data. clear it out, bestie. bye data. 🧹
  • setChart(pStart, pEnd) — locks in the range where the points (indices) for this section live. 🎯
  • setConstraintDof(point, numDof) — declares how many constrained DOFs are vibing with a given point.
  • setConstraintIndices(point, indices) — sets which point DOF numbers, in [0, DOFs), are the constrained ones.
  • setDof(point, numDof) — sets how many degrees of freedom belong to a given point. bestie it's giving "I own this point" energy ✨
  • setFieldComponents(field, numComp) — sets the number of field components for the given field. 🧩
  • setFieldConstraintDof(point, field, numDof) — sets how many constrained DOFs a given field has on a point.
  • setFieldConstraintIndices(point, field, indices) — sets which field DOF numbers, in [0, DOFs), are constrained. 🎀
  • setFieldDof(point, field, numDof) — sets the number of DOFs for a field on a given point.
  • setFieldName(field, fieldName) — names a field in the section. iconic behavior 💅
  • setFieldOffset(point, field, offset) — sets the offset for the DOFs on the given field at a point.
  • setNumFields(numFields) — sets how many fields the section has. lowkey essential 🫶
  • setOffset(point, offset) — sets the offset for the DOFs tied to a given point.
  • setPermutation(perm) — sets the permutation for [0, pEnd - pStart). 🔁
  • setUp() — calculates offsets. the moment of truth fr fr
  • view([viewer]) — views the section. 👀

🌸 Methods Documentation 🌸

addConstraintDof(point, numDof)

Increments the number of constrained DOFs for a given point, no cap. ➕

Not collective.

Parameters

  • point (int) — The point.
  • numDof (int) — The number of additional DOFs which are fixed by constraints.

Return type None

See also: setConstraintDof, getConstraintDof, PetscSectionAddConstraintDof

Source code at petsc4py/PETSc/Section.pyx:485

addDof(point, numDof)

Adds numDof degrees of freedom associated with a given point. stacking those DOFs bestie 📚

Not collective.

Parameters

  • point (int) — The point.
  • numDof (int) — The number of additional DOFs.

Return type None

See also: setDof, getDof, PetscSectionAddDof

Source code at petsc4py/PETSc/Section.pyx:354

addFieldConstraintDof(point, field, numDof)

Adds numDof constrained DOFs for a given field on a point.

Not collective.

Parameters

  • point (int) — The point.
  • field (int) — The field.
  • numDof (int) — The number of additional DOFs which are fixed by constraints.

Return type None

See also: setFieldConstraintDof, getFieldConstraintDof, PetscSectionAddFieldConstraintDof

Source code at petsc4py/PETSc/Section.pyx:557

addFieldDof(point, field, numDof)

Adds numDof DOFs associated with a field on a given point. yes we're adding MORE ✨

Not collective.

Parameters

  • point (int) — The point.
  • field (int) — The field.
  • numDof (int) — The number of additional DOFs.

Return type None

See also: setFieldDof, getFieldDof, PetscSectionAddFieldDof

Source code at petsc4py/PETSc/Section.pyx:421

clone()

Returns a copy of the section. dupe it, periodt 👑

Collective.

The copy is shallow, if possible.

See also: PetscSectionClone

💅 and finishing up that method from right before this one — its source code sits at petsc4py/PETSc/Section.pyx:80, and the return type is a Section. so if you were mid-reader-blinking, that's the wrap 🎀

create(comm=None)

okay so this one allocates a section and sets the map contents to the default. slay ✨

It's collective bestie — everybody has to show up fr.

The typical calling sequence is literally this vibe, in order:

create - setNumFields - setChart - setDof - setUp - getOffset - destroy

Now the lore: the Section object and its methods are intended to be used in the PETSc Vec and Mat implementations. The indices that come back from the Section are the right flavor for whatever kind of Vec it's attached to. Like, if the vector getting indexed is a local vector, we call the section a local section. If the section is indexing a global vector, we call it a global section 👑. And for parallel vectors — same as global vectors — we use negative indices to flag DOFs that belong to other processes. not yours, bestie, someone else's 💀

Parameters:

  • comm (Comm | None) — the MPI communicator. defaults to Sys.getDefaultComm.

Return type: Self

See also: PetscSectionCreate

Source code: petsc4py/PETSc/Section.pyx:42

createGlobalSection(sf)

this one creates a section describing the global field layout 🌈

It's collective.

The section describes the global field layout using the local section plus an SF that describes the section point overlap.

Here's the tea ☕: if we've got a set of local sections defining the layout of a set of local vectors, and also an SF to figure out which section points are shared and who owns them, we can calculate a global section that defines the parallel data layout — plus the associated global vector. She's doing the math for you 💅

Oh, and heads up: this gives negative sizes and offsets to points not owned by this process.

Also ngl: the includeConstraints and localOffsets parameters of the C API are always set to False. like, no negotiating 🫶

Parameters:

  • sf (SF) — The SF describing the parallel layout of the section points (leaves are unowned local points).

Return type: Section

See also: PetscSectionCreateGlobalSection

Source code: petsc4py/PETSc/Section.pyx:846

destroy()

destroys a section. that's it, that's the whole thing 🦋

It is not collective — she works solo, main character energy fr.

See also: PetscSectionDestroy

Source code: petsc4py/PETSc/Section.pyx:29

Return type: Self

getChart()

returns the range in which points (indices) lie for this section ✨

Not collective.

So the range is [pStart, pEnd) — meaning it goes from the first point up to one past the last point. the classic half-open moment, yk how it is 🎀

See also: PetscSectionGetChart

Source code: petsc4py/PETSc/Section.pyx:238

Return type: tuple[int, int]

getConstrainedStorageSize()

returns the size capable of holding all unconstrained DOFs in a section.

Not collective.

See also: getStorageSize, PetscSectionGetConstrainedStorageSize

Source code: petsc4py/PETSc/Section.pyx:720

Return type: int

getConstraintDof(point)

returns the number of constrained DOFs associated with a given point 🌸

Not collective.

Parameters:

  • point (int) — The point.

Return type: int

See also: setConstraintDof, PetscSectionGetConstraintDof

Source code: petsc4py/PETSc/Section.pyx:445

getConstraintIndices(point)

returns the point DOFs numbers which are constrained for a given point 👑

Not collective.

The range is in [0, DOFs) — so it's chillin' inside that interval, no cap.

Parameters:

  • point (int) — The point.

Return type: ArrayInt

See also: setConstraintIndices, PetscSectionGetConstraintIndices

Source code: petsc4py/PETSc/Section.pyx:586

getDof(point)

returns the number of degrees of freedom for a given point 💅

Not collective.

Important note bestie: in a global section, this value will be negative for points that are not owned by this process. so don't panic if the number looks weird, she's just flagging "not yours" 😭

Parameters:

  • point (int) — The point.

Return type: int

See also: setDof, addDof, PetscSectionGetDof

Source code: petsc4py/PETSc/Section.pyx:311

getFieldComponents(field)

returns the number of field components for the given field ✨

Not collective.

Parameters:

  • field (int) — The field number.

Return type: int

See also: setFieldComponents, PetscSectionGetFieldComponents

Source code: petsc4py/PETSc/Section.pyx:198

getFieldConstraintDof(point, field)

returns the number of constrained DOFs for a given field on a point 🦋

Not collective.

Parameters:

  • point (int) — The point.
  • field (int) — The field.

Return type: int

See also: setFieldConstraintDof, PetscSectionGetFieldConstraintDof

Source code: petsc4py/PETSc/Section.pyx:506

getFieldConstraintIndices(point, field)

returns the field DOFs numbers, in [0, DOFs), which are constrained 🌸

Not collective.

And cute detail: the constrained DOFs are sorted in ascending order. organized queen 👑

Parameters:

…and it's still the Section era, bestie, we're deep in the method list and honestly every single one of these is a lil bop. ✨

Parameters

  • field (int) — the field number.
  • point (int) — the point.

Return type: ArrayInt (yes, that's petsc4py.typing.ArrayInt)

See also: setFieldConstraintIndices, PetscSectionGetFieldConstraintIndices — https://petsc.org/release/manualpages/PetscSection/PetscSectionGetFieldConstraintIndices.html

Source code at petsc4py/PETSc/Section.pyx:634 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L634

getFieldDof(point, field)

Returns the number of DOFs that are chillin' with a field on a given point. 💅

Not collective — so it's just you and your section, no group chat needed.

Parameters

  • point (int) — the point.
  • field (int) — the field.

Return type: int

See also: setFieldDof, PetscSectionGetFieldDof — https://petsc.org/release/manualpages/PetscSection/PetscSectionGetFieldDof.html

Source code at petsc4py/PETSc/Section.pyx:375 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L375

getFieldName(field)

Gives you the name of a field in the section. Like, the field's government name. 🎀

Not collective.

Parameters

  • field (int) — the field number.

Return type: str

See also: setFieldName, PetscSectionGetFieldName — https://petsc.org/release/manualpages/PetscSection/PetscSectionGetFieldName.html

Source code at petsc4py/PETSc/Section.pyx:156 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L156

getFieldOffset(point, field)

Hands you the offset for the field DOFs on the given point. 🦋

Not collective.

Real talk: in a global section, this offset goes negative for points that aren't owned by this process. So a negative number here isn't a glitch, it's the vibe. 😭

Parameters

  • point (int) — the point.
  • field (int) — the field.

Return type: int

See also: setFieldOffset, PetscSectionGetFieldOffset — https://petsc.org/release/manualpages/PetscSection/PetscSectionGetFieldOffset.html

Source code at petsc4py/PETSc/Section.pyx:779 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L779

getMaxDof()

Returns the maximum number of DOFs for any point in the section. The biggest one. The main character of DOF counts. 👑

Not collective.

See also: PetscSectionGetMaxDof — https://petsc.org/release/manualpages/PetscSection/PetscSectionGetMaxDof.html

Source code at petsc4py/PETSc/Section.pyx:692 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L692

Return type: int

getNumFields()

Returns how many fields live in a section. If nobody bothered to define any fields, you get 0 back — no drama, just zero. 💀

Not collective.

See also: setNumFields, PetscSectionGetNumFields — https://petsc.org/release/manualpages/PetscSection/PetscSectionGetNumFields.html

Source code at petsc4py/PETSc/Section.pyx:122 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L122

Return type: int

getOffset(point)

Returns the offset for the DOFs tied to the given point. 🌸

Not collective.

Same warning as its field-flavored sibling: in a global section, this offset is negative for points not owned by this process. Not a bug, bestie, it's a feature of the ownership situation. 🙈

Parameters

  • point (int) — the point.

Return type: int

See also: setOffset, PetscSectionGetOffset — https://petsc.org/release/manualpages/PetscSection/PetscSectionGetOffset.html

Source code at petsc4py/PETSc/Section.pyx:734 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L734

getOffsetRange()

Returns the full range of offsets for a section — written as [start, end). Note the half-open bracket situation, she's giving mathematically correct. 🌈

Not collective.

See also: PetscSectionGetOffsetRange — https://petsc.org/release/manualpages/PetscSection/PetscSectionGetOffsetRange.html

Source code at petsc4py/PETSc/Section.pyx:831 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L831

Return type: tuple[int, int]

getPermutation()

Returns the permutation that was set earlier with setPermutation. Handing back exactly what you gave it, iconic behavior honestly. ✨

Not collective.

See also: setPermutation, PetscSectionGetPermutation — https://petsc.org/release/manualpages/PetscSection/PetscSectionGetPermutation.html

Source code at petsc4py/PETSc/Section.pyx:279 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L279

Return type: IS (that's petsc4py.PETSc.IS)

getStorageSize()

Returns the size that's capable of holding all the DOFs defined in a section. Room for everything, no cramping. 🫶

Not collective.

See also: getConstrainedStorageSize, PetscSectionGetStorageSize — https://petsc.org/release/manualpages/PetscSection/PetscSectionGetStorageSize.html

Source code at petsc4py/PETSc/Section.pyx:706 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L706

Return type: int

reset()

Frees all section data. It's the factory reset, the clean slate, the "we don't talk about that section anymore." 💫

Not collective.

See also: PetscSectionReset — https://petsc.org/release/manualpages/PetscSection/PetscSectionReset.html

Source code at petsc4py/PETSc/Section.pyx:110 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L110

Return type: None

setChart(pStart, pEnd)

Sets the range in which the points (aka indices) live for this section. 📍

Not collective.

The range is [pStart, pEnd) — so from the first point, up to one past the last point. Half-open, as always, she's consistent.

Parameters

  • pStart (int) — the first point.
  • pEnd (int) — one past the last point.

Return type: None

See also: PetscSectionSetChart — https://petsc.org/release/manualpages/PetscSection/PetscSectionSetChart.html

Source code at petsc4py/PETSc/Section.pyx:255 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L255

setConstraintDof(point, numDof)

Sets the number of constrained DOFs attached to a given point. 🔒

Not collective.

Parameters

  • point (int) — the point.
  • numDof (int) — the number of DOFs which are fixed by constraints.

Return type: None

See also: PetscSectionSetConstraintDof — https://petsc.org/release/manualpages/PetscSection/PetscSectionSetConstraintDof.html

Source code at petsc4py/PETSc/Section.pyx:663 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L663

See also: PetscSectionSetConstraintDof — https://petsc.org/release/manualpages/PetscSection/PetscSectionSetConstraintDof.html

Source code at petsc4py/PETSc/Section.pyx:663 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L663

okay and we are still going, the section method list is long like a CVS receipt and I am obsessed 💖 next chunk coming right up —

See also: getConstraintDof, addConstraintDof, PetscSectionSetConstraintDof — the C page lives at https://petsc.org/release/manualpages/PetscSection/PetscSectionSetConstraintDof.html ✨

Source code: petsc4py/PETSc/Section.pyx:464 at https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L464 🫶

setConstraintIndices(point, indices) 🎀

Set the point DOFs numbers, in [0, DOFs), which are constrained. Basically: which dofs at this point are ✨locked down✨ by constraints.

Not collective. So like, run this where you own the point, bestie.

Parameters

  • point (int) — The point. 💅
  • indices (Sequence[int]) — The constrained DOFs.

Return type

None

See also: getConstraintIndices, PetscSectionSetConstraintIndices — https://petsc.org/release/manualpages/PetscSection/PetscSectionSetConstraintIndices.html

Source code: petsc4py/PETSc/Section.pyx:610 at https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L610 🌸

setDof(point, numDof) 🦋

Sets how many degrees of freedom this one little point gets to have. That's it, that's the whole vibe check. 👑

Not collective.

Parameters

  • point (int) — The point.
  • numDof (int) — The number of DOFs.

Return type

None

See also: getDof, addDof, PetscSectionSetDof — https://petsc.org/release/manualpages/PetscSection/PetscSectionSetDof.html

Source code: petsc4py/PETSc/Section.pyx:333 at https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L333 💖

setFieldComponents(field, numComp) 🌈

Set the number of field components for the given field. Yeah, fields can have ✨components✨, it's giving multitasking.

Not collective.

Parameters

  • field (int) — The field number.
  • numComp (int) — The number of field components.

Return type

None

See also: getFieldComponents, PetscSectionSetFieldComponents — https://petsc.org/release/manualpages/PetscSection/PetscSectionSetFieldComponents.html

Source code: petsc4py/PETSc/Section.pyx:217 at https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L217 ⭐

setFieldConstraintDof(point, field, numDof) 🧚

Sets how many constrained DOFs a given field has on a point. Constrained = held down by constraints, no cap. 💀

Not collective.

Parameters

  • point (int) — The point.
  • field (int) — The field.
  • numDof (int) — The number of DOFs which are fixed by constraints.

Return type

None

See also: getFieldConstraintDof, addFieldConstraintDof, PetscSectionSetFieldConstraintDof — https://petsc.org/release/manualpages/PetscSection/PetscSectionSetFieldConstraintDof.html

Source code: petsc4py/PETSc/Section.pyx:528 at https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L528 🍓

setFieldConstraintIndices(point, field, indices) 💜

Set the field DOFs numbers, in [0, DOFs), which are constrained. Same energy as setConstraintIndices but make it field-flavoured. 🎀

Not collective.

Parameters

  • point (int) — The point.
  • field (int) — The field number.
  • indices (Sequence[int]) — The constrained DOFs.

Return type

None

See also: getFieldConstraintIndices, PetscSectionSetFieldConstraintIndices — https://petsc.org/release/manualpages/PetscSection/PetscSectionSetFieldConstraintIndices.html

Source code: petsc4py/PETSc/Section.pyx:661 at https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L661 ✨

setFieldDof(point, field, numDof) 👑

Sets the number of DOFs that hang out with a field on a given point. Main character DOFs only. 💅

Not collective.

Parameters

  • point (int) — The point.
  • field (int) — The field.
  • numDof (int) — The number of DOFs.

Return type

None

See also: getFieldDof, addFieldDof, PetscSectionSetFieldDof — https://petsc.org/release/manualpages/PetscSection/PetscSectionSetFieldDof.html

Source code: petsc4py/PETSc/Section.pyx:397 at https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L397 🔥

setFieldName(field, fieldName) 🌸

Give a field a name, bestie. Name your children. Name your fields. It's called self-care.

Not collective.

Parameters

  • field (int) — The field number.
  • fieldName (str) — The field name.

Return type

None

See also: getFieldName, PetscSectionSetFieldName — https://petsc.org/release/manualpages/PetscSection/PetscSectionSetFieldName.html

Source code: petsc4py/PETSc/Section.pyx:176 at https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L176 🦋

setFieldOffset(point, field, offset) 🌟

Set the offset for the DOFs on the given field at a point.

Lowkey important note: the user usually does not call this function — just use setUp and let it cook. 🍳

Not collective.

Parameters

  • point (int) — The point.
  • field (int) — The field.
  • offset (int) — The offset.

Return type

None

See also: getFieldOffset, PetscSectionSetFieldOffset — https://petsc.org/release/manualpages/PetscSection/PetscSectionSetFieldOffset.html

Source code: petsc4py/PETSc/Section.pyx:805 at https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L805 💖

setNumFields(numFields) 🎀

Set the number of fields in a section. How many fields are we serving today, girlies? ✨

Not collective.

Parameters

  • numFields (int) — The number of fields.

Return type

None

See also: getNumFields, PetscSectionSetNumFields — https://petsc.org/release/manualpages/PetscSection/PetscSectionSetNumFields.html

Source code: petsc4py/PETSc/Section.pyx:138 at https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L138 ⭐

setOffset(point, offset) 💜

Set the offset for the DOFs associated with the given point.

Same tea as above: the user usually does not call this function — setUp handles it, iykyk. 🫶

Not collective.

Parameters

  • point (int) — The point. 💅
  • offset (int) — The offset. 💅

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

See also: getOffset, PetscSectionSetOffset — https://petsc.org/release/manualpages/PetscSection/PetscSectionSetOffset.html

Source code at petsc4py/PETSc/Section.pyx:756 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L756

✨ setPermutation(perm) ✨

Set the permutation for [0, pEnd - pStart). periodt. 🎀

Not collective. 🚫🌐

Parameters

  • perm (IS) — The permutation of points. See #petsc4py.PETSc.IS 👑

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

See also: getPermutation, PetscSectionSetPermutation — https://petsc.org/release/manualpages/PetscSection/PetscSectionSetPermutation.html

Source code at petsc4py/PETSc/Section.pyx:294 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L294

✨ setUp() ✨

Calculate offsets. 💅

Not collective. 🚫🌐

Offsets are based on the number of degrees of freedom for each point.

See also: PetscSectionSetUp — https://petsc.org/release/manualpages/PetscSection/PetscSectionSetUp.html

Source code at petsc4py/PETSc/Section.pyx:96 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L96

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

✨ view(viewer=None) ✨

View the section. 👀

Collective. 🌐

Parameters

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

See also: PetscSectionView — https://petsc.org/release/manualpages/PetscSection/PetscSectionView.html

Source code at petsc4py/PETSc/Section.pyx:10 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Section.pyx#L10

__init__()

classmethod __new__(*args, **kwargs)

✨ class petsc4py.PETSc.Space ✨

class petsc4py.PETSc.Space

Bases: Object (#petsc4py.PETSc.Object) 👑

Function space object. ✨

Enumerations

  • Type — The function space types. See #petsc4py.PETSc.Space.Type 🦋

✨ class petsc4py.PETSc.Space.Type ✨

class petsc4py.PETSc.Space.Type

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

The function space types. 🌈

Attributes Summary

Attributes Documentation

__init__()

classmethod __new__(*args, **kwargs)

✨ Methods Summary ✨

okay bestie, this is the whole menu for the Space object, in order, no skips 💅 every single one of these is a method you can call on your space, and yes we're going through all of them because you deserve the full tea ☕

  • create([comm]) — makes you a brand new, empty Space object ✨ nothing in it yet, it's just vibes and potential 🫶
  • destroy() — yeets the Space object into the void. it's giving closure, periodt 💀
  • getDegree() — hands you back the polynomial degrees that characterize this space 🎀
  • getDimension() — returns the number of basis vectors. the headcount of the basis, fr fr 👑
  • getNumComponents() — how many components this space has 💖
  • getNumVariables() — how many variables this space has 🌸
  • getPTrimmedFormDegree() — returns the form degree of the trimmed polynomials. fancy, iykyk 💅
  • getPointPoints() — returns the evaluation points for the space, delivered as the points of a quad 📐✨
  • getPolynomialTensor() — tells you whether a function space is a space of tensor polynomials 🧚
  • getSumConcatenate() — returns the concatenate flag for this space 🎀
  • getSumNumSubspaces() — how many spaces are chillin' in the sum 💜
  • getSumSubspace(s) — returns a space in the sum. pass it an s and it hands you back that one 🌈
  • getTensorNumSubspaces() — how many spaces are in the tensor product ✨
  • getTensorSubspace(s) — returns a space in the tensor product 🔥
  • getType() — what type of space object is this? main character reveal 🫶
  • setDegree(degree, maxDegree) — sets the degree of approximation for this space. you give it degree and maxDegree, it does the thing 📚
  • setFromOptions() — pulls parameters for Space straight out of the options database. very "let the command line decide" of it 😌
  • setNumComponents(nc) — sets the number of components for this space to nc 💖
  • setNumVariables(n) — sets the number of variables for this space to n 🌸
  • setPTrimmedFormDegree(formDegree) — sets the form degree of the trimmed polynomials to formDegree 🎀
  • setPointPoints(quad) — sets the evaluation points for the space to be based on a quad 📍✨
  • setPolynomialTensor(tensor) — sets whether a function space is a space of tensor polynomials. yes/no energy, tensor in, truth out 🧚
  • setSumConcatenate(concatenate) — sets the concatenate flag for this space 🔥
  • setSumNumSubspaces(numSumSpaces) — sets the number of spaces in the sum 💜
  • setSumSubspace(s, subsp) — sets a space in the sum. s is where it goes, subsp is what goes there 👑
  • setTensorNumSubspaces(numTensSpaces) — sets the number of spaces in the tensor product 🌈
  • setTensorSubspace(s, subsp) — sets a space in the tensor product 💅
  • setType(space_type) — builds a particular type of space. you name the space_type, it manifests it ⭐
  • setUp() — constructs the data structures for the Space. the behind-the-scenes glow-up so everything else actually works 🙈

and notice the pattern bestie: everything with a get pulls info out, everything with a set pushes info in, create/destroy bracket the whole life cycle, and setUp() is the one that makes it all real 🌟 more coming, don't wander off 💖

  • view([viewer]) — View a Space. 🎀

💖 create(comm=None)

Make a brand-new empty Space object. Bestie, it starts empty — you set what it actually is afterwards with setType. ✨

Collective 🫶

Parameters

  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type: Self

See also: PetscSpaceCreate — https://petsc.org/release/manualpages/SPACE/PetscSpaceCreate.html

Source code at petsc4py/PETSc/Space.pyx:36 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L36

🌸 destroy()

Yeet the Space object into the void. Gone, done, no notes. 💅

Collective

See also: PetscSpaceDestroy — https://petsc.org/release/manualpages/SPACE/PetscSpaceDestroy.html

Return type: Self

Source code at petsc4py/PETSc/Space.pyx:59 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L59

🦋 getDegree()

Hands you the polynomial degrees that literally characterize this space. 📐

Not collective

Returns

  • minDegree (int) — The degree of the largest polynomial space contained in the space.
  • maxDegree (int) — The degree of the smallest polynomial space containing the space.

Return type: tuple[int, int]

See also: setDegree, PetscSpaceGetDegree — https://petsc.org/release/manualpages/SPACE/PetscSpaceGetDegree.html

Source code at petsc4py/PETSc/Space.pyx:117 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L117

👑 getDimension()

Tell you how many basis vectors there are. That's it, that's the whole job. ⭐

Not collective

See also: PetscSpaceGetDimension — https://petsc.org/release/manualpages/SPACE/PetscSpaceGetDimension.html

Return type: int

Source code at petsc4py/PETSc/Space.pyx:103 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L103

🌈 getNumComponents()

How many components does this space have? Asking for a friend. 💖

Not collective

See also: setNumComponents, PetscSpaceGetNumComponents — https://petsc.org/release/manualpages/SPACE/PetscSpaceGetNumComponents.html

Return type: int

Source code at petsc4py/PETSc/Space.pyx:195 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L195

🎀 getNumVariables()

How many variables does this space live on? Same vibe, different counter. ✨

Not collective

See also: setNumVariables, PetscSpaceGetNumVariables — https://petsc.org/release/manualpages/SPACE/PetscSpaceGetNumVariables.html

Return type: int

Source code at petsc4py/PETSc/Space.pyx:163 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L163

🧚 getPTrimmedFormDegree()

Return the form degree of the trimmed polynomials. Fancy fancy. 🔥

Not collective

See also: setPTrimmedFormDegree, PetscSpacePTrimmedGetFormDegree — https://petsc.org/release/manualpages/SPACE/PetscSpacePTrimmedGetFormDegree.html

Return type: int

Source code at petsc4py/PETSc/Space.pyx:546 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L546

💜 getPointPoints()

Spill the evaluation points for the space, handed back as the points of a quad. 🫶

Logically collective

See also: setPointPoints, PetscSpacePointGetPoints — https://petsc.org/release/manualpages/SPACE/PetscSpacePointGetPoints.html

Return type: Quad

Source code at petsc4py/PETSc/Space.pyx:513 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L513

🌸 getPolynomialTensor()

Is this function space a space of tensor polynomials? Returns True if a function space is a space of tensor polynomials (the space is spanned by polynomials whose degree in each variable is bounded by the given order), as opposed to polynomials (the space is spanned by polynomials whose total degree—summing over all variables is bounded by the given order). 🧠✨

Not collective

See also: setPolynomialTensor, PetscSpacePolynomialGetTensor — https://petsc.org/release/manualpages/SPACE/PetscSpacePolynomialGetTensor.html

Return type: bool

Source code at petsc4py/PETSc/Space.pyx:448 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L448

🦋 getSumConcatenate()

Return the concatenate flag for this space. Lowkey important for the component math:

A concatenated sum space will have the number of components equal to the sum of the number of components of all subspaces. A non-concatenated, or direct sum space will have the same number of components as its subspaces. 💅

Not collective

See also: setSumConcatenate, PetscSpaceSumGetConcatenate — https://petsc.org/release/manualpages/SPACE/PetscSpaceSumGetConcatenate.html

Return type: bool

Source code at petsc4py/PETSc/Space.pyx:261 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L261

⭐ getSumNumSubspaces()

How many spaces are living in the sum? Counting, bestie. 🔢

Not collective

See also: setSumNumSubspaces, PetscSpaceSumGetNumSubspaces — https://petsc.org/release/manualpages/SPACE/PetscSpaceSumGetNumSubspaces.html

Return type: int

Source code at petsc4py/PETSc/Space.pyx:304 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L304

🫶 getSumSubspace(s)

Grab one specific space out of the sum.

Not collective

Parameters

  • s (int) — The space number.

Return type: Space

See also: setSumSubspace, PetscSpaceSumGetSubspace — https://petsc.org/release/manualpages/SPACE/PetscSpaceSumGetSubspace.html

Source code at petsc4py/PETSc/Space.pyx:318 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L318

🎀 getTensorNumSubspaces()

How many spaces are in the tensor product? Same energy, tensor-flavoured. 🌈

Not collective

See also: setTensorNumSubspaces, PetscSpaceTensorGetNumSubspaces — https://petsc.org/release/manualpages/SPACE/PetscSpaceTensorGetNumSubspaces.html

Return type: int

Source code at petsc4py/PETSc/Space.pyx:376 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L376

getTensorSubspace(s) 🫶

Gives you a space up in the tensor product. 💫

Not collective.

Parameters

  • s (int) — the space number.

Return type

Space

See also: setTensorSubspace, PetscSpaceTensorGetSubspace

Source code at petsc4py/PETSc/Space.pyx:410

getType() ✨

Hands you back the type of the space object, bestie. No cap.

Not collective.

See also: setType, PetscSpaceGetType

Source code at petsc4py/PETSc/Space.pyx:227

Return type

str

setDegree(degree, maxDegree) 💅

Sets the degree of approximation for this space. It's giving precision. 🎀

Logically collective.

One of degree and maxDegree can be None. (Yeah, you read that right — one of them can dip out.)

Parameters

  • degree (int | None) — the degree of the largest polynomial space contained in the space.
  • maxDegree (int | None) — the degree of the largest polynomial space containing the space.

Return type

None

See also: getDegree, PetscSpaceSetDegree

Source code at petsc4py/PETSc/Space.pyx:138

setFromOptions() 🌈

Sets the parameters in Space straight from the options database. Snatched from the CLI, iconic behaviour honestly.

Collective.

See also: Working with PETSc options, PetscSpaceSetFromOptions

Source code at petsc4py/PETSc/Space.pyx:91

Return type

None

setNumComponents(nc) 🦋

Sets the number of components for this space. That's the count, the whole vibe.

Logically collective.

Parameters

  • nc (int) — the number of components.

Return type

None

See also: getNumComponents, PetscSpaceSetNumComponents

Source code at petsc4py/PETSc/Space.pyx:209

setNumVariables(n) 🌸

Sets the number of variables for this space. You know — the x, y, z situation. 📐

Logically collective.

Parameters

  • n (int) — the number of variables (x, y, z etc.).

Return type

None

See also: getNumVariables, PetscSpaceSetNumVariables

Source code at petsc4py/PETSc/Space.pyx:177

setPTrimmedFormDegree(formDegree) 💜

Sets the form degree of the trimmed polynomials. Lowkey fancy, highkey important.

Logically collective.

Parameters

  • formDegree (int) — the form degree.

Return type

None

See also: getPTrimmedFormDegree, PetscSpacePTrimmedSetFormDegree

Source code at petsc4py/PETSc/Space.pyx:528

setPointPoints(quad) ⭐

Sets the evaluation points for the space so they're based on a quad. The way it does this is by making the evaluation points line up exactly with the points of a quadrature rule. Slay. 🎯

Logically collective.

Parameters

  • quad (Quad) — the Quad defining the points.

Return type

None

See also: getPointPoints, PetscSpacePointSetPoints

Source code at petsc4py/PETSc/Space.pyx:493

setPolynomialTensor(tensor) 🔥

Sets whether a function space is a space of tensor polynomials. Honestly kind of the main character choice here.

Logically collective.

Set it to True for a function space that's a space of tensor polynomials — meaning the space is spanned by polynomials whose degree in each variable is bounded by the given order. Set it to False for plain polynomials — meaning the space is spanned by polynomials whose total degree (summing over all variables) is bounded by the given order. Two totally different vibes, ikyk. 👑

Parameters

  • tensor (bool) — True for a tensor polynomial space, False for a polynomial space.

Return type

None

See also: getPolynomialTensor, PetscSpacePolynomialSetTensor

Source code at petsc4py/PETSc/Space.pyx:468

setSumConcatenate(concatenate) 🫧

Sets the concatenate flag for this space. Big decision energy.

Logically collective.

Okay so here's the tea: a concatenated sum space will have the number of components equal to the sum of the number of components of all subspaces. A non-concatenated, a.k.a. direct sum space, will have the same number of components as its subspaces. Two paths, pick your fighter. 💥

Parameters

  • concatenate (bool) — True if subspaces are concatenated components, False if direct summands.

Return type

None

See also: getSumConcatenate, PetscSpaceSumSetConcatenate

Source code at petsc4py/PETSc/Space.pyx:280

setSumNumSubspaces(numSumSpaces) 🍓

Sets the number of spaces in the sum. Just the count, fr fr.

Logically collective.

Parameters

  • numSumSpaces (int) — the number of spaces.

Return type

None

See also: getSumNumSubspaces, PetscSpaceSumSetNumSubspaces

Source code at petsc4py/PETSc/Space.pyx:336

Source code at petsc4py/PETSc/Space.pyx:358 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L358>

setSumSubspace(s, subsp)

Bestie, this one sets a space in the sum. Logically collective — so everyone’s gotta be on the same vibe, no cap.

Parameters

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

See also: getSumSubspace, PetscSpaceSumSetSubspace <https://petsc.org/release/manualpages/SPACE/PetscSpaceSumSetSubspace.html>

Source code at petsc4py/PETSc/Space.pyx:338 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L338>

setTensorNumSubspaces(numTensSpaces)

Sets the number of spaces in the tensor product. Logically collective energy ✨.

Parameters

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

See also: getTensorNumSubspaces, PetscSpaceTensorSetNumSubspaces <https://petsc.org/release/manualpages/SPACE/PetscSpaceTensorSetNumSubspaces.html>

Source code at petsc4py/PETSc/Space.pyx:430 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L430>

setTensorSubspace(s, subsp)

Set a space in the tensor product. Logically collective, bb 🦋.

Parameters

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

See also: getTensorSubspace, PetscSpaceTensorSetSubspace <https://petsc.org/release/manualpages/SPACE/PetscSpaceTensorSetSubspace.html>

Source code at petsc4py/PETSc/Space.pyx:390 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L390>

setType(space_type)

Build a particular type of space. Collective — not just logically, bestie, actually collective.

Parameters

Return type: Self

See also: getType, PetscSpaceSetType <https://petsc.org/release/manualpages/SPACE/PetscSpaceSetType.html>

Source code at petsc4py/PETSc/Space.pyx:241 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L241>

setUp()

Construct data structures for the Space. Collective ✨.

See also: PetscSpaceSetUp <https://petsc.org/release/manualpages/SPACE/PetscSpaceSetUp.html>

Source code at petsc4py/PETSc/Space.pyx:24 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L24>

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

view(viewer=None)

View a Space. Collective 🦋.

Parameters

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

See also: PetscSpaceView <https://petsc.org/release/manualpages/SPACE/PetscSpaceView.html>

Source code at petsc4py/PETSc/Space.pyx:72 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Space.pyx#L72>

__init__()

classmethod __new__(*args, **kwargs)

petsc4py.PETSc.Sys

class petsc4py.PETSc.Sys

Bases: object <https://docs.python.org/3/builtins/functions.html#object>

System utilities. 💖

✨ Methods Summary ✨

okay bestie, here's the vibe check on every method the PETSc class is serving up 💅✨ no cap, this is the full menu:

  • Print(*args[, sep, end, comm]) — Print output from the first processor of a communicator. 🖨️
  • getDefaultComm() — Get the default MPI communicator used to create PETSc objects. 🌐
  • getVersion([devel, date, author]) — Return PETSc version information. 📦
  • getVersionInfo() — Return PETSc version information. 📋
  • hasExternalPackage(package) — Return whether PETSc has support for external package. 📦
  • infoAllow(flag[, filename, mode]) — Enables or disables PETSc info messages. ℹ️
  • isFinalized() — Return whether PETSc has been finalized. 🏁
  • isInitialized() — Return whether PETSc has been initialized. 🚀
  • popErrorHandler() — Remove the current error handler. 🗑️
  • popSignalHandler() — Remove the current signal handler. 📡
  • pushErrorHandler(errhandler) — Set the current error handler. ⚠️
  • registerCitation(citation) — Register BibTeX citation. 📚
  • setDefaultComm(comm) — Set the default MPI communicator used to create PETSc objects. 🌐
  • sleep([seconds]) — Sleep some number of seconds. 😴
  • splitOwnership(size[, bsize, comm]) — Given a global (or local) size determines a local (or global) size. ➗
  • syncFlush([comm]) — Flush output from previous syncPrint calls. 🚽
  • syncPrint(*args[, sep, end, flush, comm]) — Print synchronized output from several processors of a communicator. 📢

✨ Methods Documentation ✨

✨ Print ✨

classmethod Print(*args, sep=' ', end='\n', comm=None, **kwargs)

Print output from the first processor of a communicator. 🖨️ Collective. So like, everybody's in on it, no cap.

Parameters:

  • *args (Any) — Positional arguments. 🎯
  • sep (str) — String inserted between values, by default a space. 🧩
  • end (str) — String appended after the last value, by default a newline. ↩️
  • comm (Comm | None) — MPI communicator, defaults to getDefaultComm. 🌐
  • **kwargs (Any) — Keyword arguments. 🗝️

Return type: None

See also: PetscPrintf — https://petsc.org/release/manualpages/Sys/PetscPrintf.html

Source code at petsc4py/PETSc/Sys.pyx:155 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Sys.pyx#L155

✨ getDefaultComm ✨

classmethod getDefaultComm()

Get the default MPI communicator used to create PETSc objects. 🌐 Not collective. So it's a solo moment, main character energy only.

See also: setDefaultComm

Source code at petsc4py/PETSc/Sys.pyx:116 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Sys.pyx#L116

Return type: Comm

✨ getVersion ✨

classmethod getVersion(devel=False, date=False, author=False)

Return PETSc version information. 📦 Not collective. Just you and your vibe.

Parameters:

  • devel (bool) — Additionally, return whether using an in-development version. 👀
  • 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: PetscGetVersion — https://petsc.org/release/manualpages/Sys/PetscGetVersion.html, PetscGetVersionNumber — https://petsc.org/release/manualpages/Sys/PetscGetVersionNumber.html

Source code at petsc4py/PETSc/Sys.pyx:7 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Sys.pyx#L7

✨ getVersionInfo ✨

classmethod getVersionInfo()

Return PETSc version information. 📋 Not collective. Another solo slay.

Returns: info — Dictionary with version information. 📚

Return type: dict

See also: PetscGetVersion <https://petsc.org/release/manualpages/Sys/PetscGetVersion.html>, PetscGetVersionNumber <https://petsc.org/release/manualpages/Sys/PetscGetVersionNumber.html>

Source code at petsc4py/PETSc/Sys.pyx:62 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Sys.pyx#L62>

💅 classmethod hasExternalPackage(package)

okay bestie, this one tells you if PETSc is out here supporting some external package or not. like does it know that package? does it fw it? this is how you find out. 💖

Not collective. (meaning each process does its own lil thing, no group chat needed 🫶)

Parameters

  • package (str) — the external package name. just the name, that's it. 💫

Return type bool

See also: PetscHasExternalPackage <https://petsc.org/release/manualpages/Sys/PetscHasExternalPackage.html>

Source code at petsc4py/PETSc/Sys.pyx:449 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Sys.pyx#L449>

✨ classmethod infoAllow(flag, filename=None, mode='w')

turns PETSc info messages on or off. like a lil switch for the ✨ commentary ✨ PETSc wants to tell you. not me flipping it for you, that's on you bestie. 🙈

Not collective.

Parameters

  • flag (bool) — whether to enable info messages. True? yapping enabled. False? muzzled. 💀
  • filename (str | None) — name of a file where to dump the output. you know, if you wanna keep the receipts. 🎀
  • mode (str) — write mode for the file, by default "w". yes the classic open-for-writing. ✍️

Return type None

See also: PetscInfoAllow <https://petsc.org/release/manualpages/Log/PetscInfoAllow.html>, PetscInfoSetFile <https://petsc.org/release/manualpages/Log/PetscInfoSetFile.html>

Source code at petsc4py/PETSc/Sys.pyx:392 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Sys.pyx#L392>

🦋 classmethod isFinalized()

returns whether PETSc has been finalized. as in, is it DONE done. closed. goodbye era. 💔

Not collective.

See also: isInitialized

Source code at petsc4py/PETSc/Sys.pyx:101 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Sys.pyx#L101>

Return type bool

🌸 classmethod isInitialized()

returns whether PETSc has been initialized. like, has it woken up yet or is it still in bed. ☀️😴

Not collective.

See also: isFinalized

Source code at petsc4py/PETSc/Sys.pyx:88 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Sys.pyx#L88>

Return type bool

🎀 classmethod popErrorHandler()

removes the current error handler. bye bestie, no more of you handling my errors. 👋 it's giving... cleaning house. 🧹

Logically collective.

See also: PetscPopErrorHandler <https://petsc.org/release/manualpages/Sys/PetscPopErrorHandler.html>

Source code at petsc4py/PETSc/Sys.pyx:366 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Sys.pyx#L366>

Return type None

🦄 classmethod popSignalHandler()

removes the current signal handler. same energy as above but for signals this time. it's gone, we said goodbye, periodt. 💅

Logically collective.

See also: PetscPopSignalHandler <https://petsc.org/release/manualpages/Sys/PetscPopSignalHandler.html>

Source code at petsc4py/PETSc/Sys.pyx:379 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Sys.pyx#L379>

Return type None

🔥 classmethod pushErrorHandler(errhandler)

sets the current error handler. like, "here, YOU deal with the problems now." putting somebody on duty. 🫡

Logically collective.

Parameters

  • errhandler (str) — the name of the error handler. just the name, string-coded. 🎁

Return type None

See also: PetscPushErrorHandler <https://petsc.org/release/manualpages/Sys/PetscPushErrorHandler.html>

Source code at petsc4py/PETSc/Sys.pyx:331 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Sys.pyx#L331>

📚 classmethod registerCitation(citation)

registers a BibTeX citation. yes bestie, you too can have your academic credit moment. ✨ main character energy for your paper. 👑

Not collective.

Parameters

  • citation (str) — the BibTeX citation entry to register. paste the whole entry, exactly how BibTeX wants it. 📝

Return type None

See also: PetscCitationsRegister <https://petsc.org/release/manualpages/Sys/PetscCitationsRegister.html>

Source code at petsc4py/PETSc/Sys.pyx:426 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Sys.pyx#L426>

🌈 classmethod setDefaultComm(comm)

sets THE default MPI communicator that gets used whenever PETSc objects are being created. like picking your main group chat for the whole app. 💬

Logically collective.

Parameters

  • comm (Comm | None) — the MPI communicator. if you set it to None, it just uses COMM_WORLD. no cap. 🌍

Return type None

See also: getDefaultComm

Source code at petsc4py/PETSc/Sys.pyx:131 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Sys.pyx#L131>

😴 classmethod sleep(seconds=1.0)

sleeps for some number of seconds. literally just napping. PETSc hitting snooze. 💤

Not collective.

Parameters

  • seconds (float) — the time to sleep, in seconds. default is 1.0, so a whole one second of slumber. 🛌

Return type None

See also: PetscSleep <https://petsc.org/release/manualpages/Sys/PetscSleep.html>

Source code at petsc4py/PETSc/Sys.pyx:310 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Sys.pyx#L310>

🌟 classmethod splitOwnership(size, bsize=None, comm=None)

given a global (or local) size, this figures out the local (or global) size. it's doing the math so you don't have to bestie. 🤝

Collective.

Parameters

  • size (int | tuple[int, int]) — global size N, or a 2-tuple (n, N) with local and global sizes. either n or N (but not both) can be None. 🙌
  • bsize (int | None) — block size, defaults to 1.
  • comm (Comm | None) — MPI communicator, defaults to getDefaultComm.

Returns

  • n (int) — the local size.
  • N (int) — the global size.

Return type tuple[int, int]

Notes

the size argument corresponds to the full size of the vector. like, an array with 10 blocks and a block size of 3 will have a size of 30, not 10. do not get played by that. ⚠️ 10 × 3 = 30, keep up. 💅

See also: PetscSplitOwnership <https://petsc.org/release/manualpages/Sys/PetscSplitOwnership.html>

Source code at petsc4py/PETSc/Sys.pyx:261 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Sys.pyx#L261>

✨ syncFlush

classmethod syncFlush(comm=None)

Okay bestie, you know how syncPrint queues up your little messages so they don't turn into soup? This is the "okay go, send it all now" button. It flushes out every bit of output sitting around from all your previous syncPrint calls. 💅

Collective. So like, yes, everyone in the communicator has to show up for this one — it's a group hangout, no lurking allowed. 🫶

Parameters

  • comm (Comm | None) — the MPI communicator. If you don't pass one, it defaults to getDefaultComm. Defaults are queen behavior tbh 👑

Return type

  • None — she sends the bytes and gives you nothing back. It's giving generous. 💖

See also:

Source code at petsc4py/PETSc/Sys.pyx:240 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Sys.pyx#L240

🌸 syncPrint

classmethod syncPrint(*args, sep=' ', end='\n', flush=False, comm=None, **kwargs)

This one prints synchronized output from several processors of a communicator — i.e. it stops your parallel processes from all screaming at the terminal at once and making it unreadable. 😭 The way that random interleaved output just ruins your whole day? Not on her watch. ✨

Not collective. For real — this one you can call from just one process if you want. No group chat required. 🙈

Parameters

  • *args (Any) — Positional arguments. All the stuff you wanna print goes here. 🎀
  • sep (str) — String inserted between values, by default a space.
  • end (str) — String appended after the last value, by default a newline.
  • flush (bool) — Whether to flush output with syncFlush. Set it and she'll push everything out for you right away. 🔥
  • comm (Comm | None) — MPI communicator, defaults to getDefaultComm.
  • **kwargs (Any) — Keyword arguments.

Return type

  • None — again, absolutely nothing comes back. Just vibes and output. 💜

See also:

Source code at petsc4py/PETSc/Sys.pyx:197 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Sys.pyx#L197

__init__()

classmethod __new__(*args, **kwargs)

👑 petsc4py.PETSc.TAO

class petsc4py.PETSc.TAO

Bases: Object

Bestie. The optimization solver. Like, this is the whole point of TAO — you hand it a problem, it goes and finds the minimum. Main character energy, no notes. 🌟

TAO is described in the PETSc manual — https://petsc.org/release/manual/tao.html

See also:

Enumerations 🌈

  • ALMMType — TAO Augmented Lagrangian Multiplier method (ALMM) Type.
  • BNCGType — TAO Bound Constrained Conjugate Gradient (BNCG) Update Type.
  • ConvergedReason — TAO solver termination reason.
  • Type — TAO solver type.

💫 petsc4py.PETSc.TAO.ALMMType

class petsc4py.PETSc.TAO.ALMMType

Bases: object

TAO Augmented Lagrangian Multiplier method (ALMM) Type.

Attributes Summary 🦋

  • CLASSIC — Constant CLASSIC of type int
  • PHR — Constant PHR of type int

Attributes Documentation 💖

CLASSIC: int = CLASSIC

Constant CLASSIC of type int

PHR: int = PHR

Constant PHR of type int

__init__()

classmethod __new__(*args, **kwargs)

🧚 petsc4py.PETSc.TAO.BNCGType

class petsc4py.PETSc.TAO.BNCGType

Bases: object

TAO Bound Constrained Conjugate Gradient (BNCG) Update Type.

✨ Attributes Summary ✨

okay bestie, here's the whole roster of constants this thing is holding 💖 every single one of them is an int — like, all of them, no cap — and they all point at the same python int docs page, which is https://docs.python.org/3/builtins/functions.html#int 💅

🎀 Attributes Documentation 🎀

so like, the same thirteen icons again but with their ✨full documentation✨ this time. literally every single one: type int, value equals itself, description says it's a constant of type int. she's consistent, we love that 🙈

then we got the classic dunder duo, and bestie they are exactly as advertised, no extra lore here 😭

  • __init__() — the init ✨ that's the whole entry, nothing else documented for it
  • classmethod __new__(*args, **kwargs) — a classmethod named __new__ that takes *args and **kwargs 💅 periodt

💜 petsc4py.PETSc.TAO.ConvergedReason 💜

class petsc4py.PETSc.TAO.ConvergedReason

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

it's the TAO solver termination reason 🌟 like, why did the TAO solver stop? this is where the answer lives, iykyk. every TAO run ends for a reason and this class is the receipts 🧾

See also:

✨ Attributes Summary ✨

okay bestie, here's the whole squad at a glance 💖 — this is a chonky list of module-level attributes, and literally every single one of them is a constant of type int (the type reference the docs point at is https://docs.python.org/3/builtins/functions.html#int, iykyk). Here's the full roster, no cap:

  • CONTINUE_ITERATING — Constant CONTINUE_ITERATING of type int.
  • CONVERGED_GATOL — Constant CONVERGED_GATOL of type int.
  • CONVERGED_GRTOL — Constant CONVERGED_GRTOL of type int.
  • CONVERGED_GTTOL — Constant CONVERGED_GTTOL of type int.
  • CONVERGED_ITERATING — Constant CONVERGED_ITERATING of type int.
  • CONVERGED_MINF — Constant CONVERGED_MINF of type int.
  • CONVERGED_STEPTOL — Constant CONVERGED_STEPTOL of type int.
  • CONVERGED_USER — Constant CONVERGED_USER of type int.
  • DIVERGED_LS_FAILURE — Constant DIVERGED_LS_FAILURE of type int.
  • DIVERGED_MAXFCN — Constant DIVERGED_MAXFCN of type int.
  • DIVERGED_MAXITS — Constant DIVERGED_MAXITS of type int.
  • DIVERGED_NAN — Constant DIVERGED_NAN of type int.
  • DIVERGED_TR_REDUCTION — Constant DIVERGED_TR_REDUCTION of type int.
  • DIVERGED_USER — Constant DIVERGED_USER of type int.
  • ITERATING — Constant ITERATING of type int.

🌈 Attributes Documentation 🌈

now for the receipts, bestie — each one of these gets its own lil writeup. they're all annotated the same way, NAME: int = NAME, which is the most "I am what I am" energy possible and honestly? iconic 💅.

⭐ CONTINUE_ITERATING: int = CONTINUE_ITERATING

Constant CONTINUE_ITERATING of type int.

⭐ CONVERGED_GATOL: int = CONVERGED_GATOL

Constant CONVERGED_GATOL of type int.

⭐ CONVERGED_GRTOL: int = CONVERGED_GRTOL

Constant CONVERGED_GRTOL of type int.

⭐ CONVERGED_GTTOL: int = CONVERGED_GTTOL

Constant CONVERGED_GTTOL of type int.

⭐ CONVERGED_ITERATING: int = CONVERGED_ITERATING

Constant CONVERGED_ITERATING of type int.

⭐ CONVERGED_MINF: int = CONVERGED_MINF

Constant CONVERGED_MINF of type int.

⭐ CONVERGED_STEPTOL: int = CONVERGED_STEPTOL

Constant CONVERGED_STEPTOL of type int.

⭐ CONVERGED_USER: int = CONVERGED_USER

Constant CONVERGED_USER of type int.

⭐ DIVERGED_LS_FAILURE: int = DIVERGED_LS_FAILURE

Constant DIVERGED_LS_FAILURE of type int.

⭐ DIVERGED_MAXFCN: int = DIVERGED_MAXFCN

Constant DIVERGED_MAXFCN of type int.

⭐ DIVERGED_MAXITS: int = DIVERGED_MAXITS

Constant DIVERGED_MAXITS of type int.

⭐ DIVERGED_NAN: int = DIVERGED_NAN

Constant DIVERGED_NAN of type int.

quick vibe check 🫶 — DIVERGED_TR_REDUCTION and ITERATING showed up in the summary table up top, but they do not get their own entries in this Attributes Documentation list. that's just how the docs are, bestie, don't come for me, I'm only the messenger 🎀
  • DIVERGED_TR_REDUCTION — a constant, type int, value <code>DIVERGED_TR_REDUCTION</code>. bestie it's literally just itself, that's the whole vibe 💅
  • DIVERGED_USER — constant, type int, and yeah, its value is also <code>DIVERGED_USER</code>. iconic self-naming behaviour, we love a constant that knows who she is ✨
  • ITERATING — constant, type int, value <code>ITERATING</code>. no notes, she simply is 🦋

__init__()

the constructor, except there's nothing to say about it here because there are no arguments listed 🙈 she exists, she's present, she's doing her little job.

classmethod __new__(*args, **kwargs)

a classmethod, so it's called on the class itself, and it takes <code>*args</code> and <code>kwargs</code> — the classic "we accept literally whatever you throw at us" signature. the way that <code>*args</code> said "anything" and <code>kwargs</code> said "and also keywords" 🔥 periodt.

💖 petsc4py.PETSc.TAO.Type 💖

class petsc4py.PETSc.TAO.Type

Bases: object

okay so this one is the TAO solver type — like, the label that says which TAO solver you're working with. not the solver itself, not the vibes of the solver, the type of the solver. she's the nametag at the party 🎀

See also:

  • TaoType — the TaoType manual page, if you wanna go read the source of truth yourself, go off queen 👑

ngl, this little cluster of stuff is giving "the supporting cast" energy — constants that hold their own names, a bare constructor, and a type class whose whole personality is telling you which TAO solver is which. small but load-bearing. main character energy in a side-character font 💜

✨ Attributes Summary ✨

okay bestie, before you scroll: literally every single thing in this list is a class attribute, and literally every single one of them is an object of type str (https://docs.python.org/3/builtins/stdtypes.html#str). That's the whole personality — string constants, the entire squad, holding it down together. No objects of other types here, no little structs, just vibes and str. 💅

like, the way every single one of these is just str and nothing else? consistency ate and left no crumbs fr fr 🫶 more of this list is incoming, don't you dare close the tab 💖

🌈 Attributes Documentation 🌈

okay bestie, this is the part where every single solver name just... gets to be itself. They're all str objects, all pointing at the same Python docs page for str (<https://docs.python.org/3/builtins/stdtypes.html#str>), and honestly? iconic. no cap. lowkey they're all twins. 👑

heads up: every one of these is literally an object of type str, and the link is always the same: https://docs.python.org/3/builtins/stdtypes.html#str. I'm not repeating the whole URL paragraph 33 times like a zionist but the info is 100% there, fr fr. 🫶

And then the two little darlings that make the whole thing go brrr:

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

not me ending on __new__ being a classmethod taking *args, **kwargs — it's giving "I accept literally anything, no questions asked" energy and honestly? main character behavior. 💜

mkay continuing the rundown, no skips, every method in the house 💫

  • addTerm(prefix, scale, term[, params, mapmat]) — Adds an objective term to the solver. yes bestie, we're stacking terms now 🎀
  • appendOptionsPrefix(prefix) — Appends to the prefix that gets used when searching for options in the database. suffix energy, but for prefixes, iykyk ✨
  • cancelMonitor() — Cancels all the monitors of the solver. no survivors 💀
  • checkConverged() — Runs the convergence test and hands you back the converged reason.
  • computeConstraints(x, c) — Computes the vector that corresponds to the constraints.
  • computeDualVariables(xl, xu) — Computes the dual vectors that correspond to the variables' bounds.
  • computeGradient(x, g) — Computes the gradient of the objective function.
  • computeHessian(x, H[, P]) — Computes the Hessian of the objective function. optional P standing right there like 👀
  • computeJacobian(x, J[, P]) — Computes the Jacobian.
  • computeObjective(x) — Computes the value of the objective function.
  • computeObjectiveGradient(x, g) — Computes the gradient of the objective function and its value. two for one, ate that 🫶
  • computeResidual(x, f) — Computes the residual.
  • computeVariableBounds(xl, xu) — Computes the vectors that correspond to the variables' bounds.
  • create([comm]) — Creates a TAO solver. main character moment, birth of a legend 👑
  • createPython([context, comm]) — Creates an optimization solver of Python type. slithering into the C world, respectfully 🐍
  • destroy() — Destroys the solver. rip bozo, gone but not forgotten 😭
  • getALMMSubsolver() — Returns the subsolver living inside the ALMM solver. subsolver means subplot and i'm invested 🌸
  • getALMMType() — Returns the type of the ALMM solver.
  • getAppCtx() — Returns the application context. your stuff, back in your hands 🎀
  • getBNCGType() — Returns the type of the BNCG solver.
  • getBRGNDampingVector() — Returns the damping vector.
  • getBRGNSubsolver() — Returns the subsolver living inside the BRGN solver.
  • getConstraintTolerances() — Returns the constraints tolerance parameters that get used in the convergence tests.
  • getConvergedReason() — Returns the reason for the solver convergence. the receipts of whether it worked 💅
  • getConvergenceTest() — Returns the callback used to test for solver convergence.
  • getEqualityConstraints() — Returns a tuple holding the vector and the callback of equality constraints.
  • getGradient() — Returns the vector used to store the gradient, plus the evaluation callback. storage + the callback, a whole duo 🦋

okay the list just keeps going and honestly it's eating 💅 here's the rest of the family:

  • getGradientNorm() — hands you the matrix that's used to compute inner products ✨
  • getHessian() — gives back the matrices where the Hessian lives plus the evaluation callback 💖
  • getInequalityConstraints() — returns a tuple holding the vector and the callback for the inequality constraints 🎀
  • getIterationNumber() — the current iteration number, that's it, that's the whole vibe 🔢
  • getJacobianEquality() — returns the matrix, the preconditioner matrix and the callback of the equality constraints Jacobian 🌸
  • getJacobianInequality() — returns the matrix, precon matrix and callback of ineq. 🦋
ngl that last description cuts off in the original like that — ineq. and then nothing. Iconic of it, lowkey.
  • getKSP() — gives you the linear solver that the nonlinear solver is using 🔥
  • getLMVMH0() — returns the initial Hessian for the quasi-Newton approximation 👑
  • getLMVMH0KSP() — returns the KSP <#petsc4py.PETSc.KSP> for the inverse of that initial Hessian approximation 💜
  • getLMVMMat() — gets you the LMVM matrix, periodt ⭐
  • getLineSearch() — returns the TAO Line Search object 🌈
  • getMaximumFunctionEvaluations() — the max number of objective evaluations allowed within the solver 🙈
  • getMaximumIterations() — the max number of solver iterations, no cap 💀
  • getMonitor() — returns the callback used to monitor solver convergence 👀
  • getObjective() — returns the objective evaluation callback, your main character function fr 💖
  • getObjectiveAndGradient() — returns the vector used to store the gradient and the evaluation callback, a two-for-one 🫶
  • getObjectiveValue() — the current value of the objective function, right now, as it is ✨
  • getOptionsPrefix() — the prefix used when searching for options in the database 🔍
  • getPythonContext() — returns the instance of the class implementing the required Python methods 🐍
  • getPythonType() — the fully qualified Python name of the class the solver is using 💅
  • getSolution() — returns the vector holding the solution, the moment we've all been waiting for 👑
  • getSolutionNorm() — returns the objective function value plus the norms of gradient and constraints 📐
  • getSolutionStatus() — returns the solution status, the vibe check on your answer ✅
  • getTerm() — returns the entire objective term of the solver 🍓

okay and there's still more coming bestie, do not close the tab 😭

  • getTolerances() — hands you back the tolerance parameters the solver uses in its convergence tests 💅
  • getType() — tells you what type of solver you're dealing with, no gatekeeping ✨
  • getUpdate() — returns the callback that computes the update, so you can see the lil function doing the work 🫶
  • getVariableBounds() — gives you the lower and upper bounds vectors, both of them, periodt 🎀
  • monitor([its, f, res, cnorm, step]) — monitor the solver 👀 optional args: its, f, res, cnorm, step — pass whatever you got, bestie
  • setALMMSubsolver(subsolver) — sets the subsolver living inside the ALMM solver, nesting dolls but make it math 🪆
  • setALMMType(tao_almm_type) — sets the ALMM type of the solver, you pick the flavor 🌈
  • setAppCtx(appctx) — sets the application context, i.e. your lil bag of stuff to pass around 🎒
  • setBNCGType(cg_type) — sets the type of the BNCG solver ✨
  • setBRGNDictionaryMatrix(D) — sets the dictionary matrix D, iconic 💅
  • setBRGNRegularizerHessian(hessian[, H, ...]) — sets the callback to compute the regularizer Hessian. optional args: H, and more — it's giving "you do the math" energy 🔥
  • setBRGNRegularizerObjectiveGradient(objgrad) — sets the callback that computes the regularizer objective and the gradient, multitasking queen 👑
  • setBRGNRegularizerWeight(weight) — sets the regularizer weight, simple, clean, slay 💜
  • setBRGNSmoothL1Epsilon(epsilon) — sets the smooth L1 epsilon, one number, no drama 🌸
  • setConstraintTolerances([catol, crtol]) — sets the constraints tolerance parameters used in the solver convergence tests. optional: catol, crtol — pass them or don't 🙈
  • setConstraints(constraints[, C, args, kargs]) — sets the callback that computes constraints. optional args: C, args, kargs 🦋
  • setConvergedReason(reason) — sets the termination flag, like "okay we're done here" 💀
  • setConvergenceTest(converged[, args, kargs]) — sets the callback that tests whether the solver has converged. optional args: args, kargs ⭐
  • setEqualityConstraints(equality_constraints, c) — sets the equality constraints callback, straight up ✨
  • setFromOptions() — configures the solver straight from the options database, zero args, lowkey magical 🎀
  • setGradient(gradient[, g, args, kargs]) — sets the gradient evaluation callback. optional args: g, args, kargs 🌈
  • setGradientNorm(mat) — sets the matrix used to compute inner products 👑
  • setHessian(hessian[, H, P, args, kargs]) — sets the callback that computes the Hessian matrix. optional args: H, P, args, kargs 🔥
  • setInequalityConstraints(...[, args, kargs]) — sets the inequality constraints callback. optional args: args, kargs — yes the ... is really there, she's mysterious like that 💅
  • setInitialTrustRegionRadius(radius) — sets the initial trust region radius, the starting circle of trust 🫶
  • setIterationNumber(its) — sets the current iteration number, its, keep counting bestie 🔢
  • setJacobian(jacobian[, J, P, args, kargs]) — sets the callback that computes the Jacobian. optional args: J, P, args, kargs ✨
  • setJacobianDesign(jacobian_design[, J, ...]) — sets the Jacobian design callback. optional args: J, and more — designer Jacobian, main character energy 💅
  • setJacobianEquality(jacobian_equality[, J, ...]) — bestie, this sets the Jacobian equality constraints callback ✨ like it's giving "here's how you constrain your problem", fr fr 💅
  • setJacobianInequality(jacobian_inequality[, ...]) — and this one? sets the Jacobian inequality constraints callback 🦋 the sibling to the equality one, no cap, they're a matching set 💖
  • setJacobianResidual(jacobian[, J, P, args, ...]) — okay so this sets the callback that computes the least-squares residual Jacobian 🔥 key word: residual, key word: least-squares, you're welcome 😌
  • setJacobianState(jacobian_state[, J, P, I, ...]) — sets the Jacobian state callback 🌸 state callback but make it Jacobian, iconic behavior honestly 🎀
  • setLMVMH0(mat) — sets the initial Hessian for the quasi-Newton approximation ⭐ your H-zero, your starting point, your vibe-setter for the whole LMVM situation ngl
  • setLMVMMat(M) — sets the LMVM matrix 💫 just... the LMVM matrix. we said what we said. periodt 🫶
  • setMaximumFunctionEvaluations(mit) — sets the maximum number of objective evaluations within the solver 😭 so it doesn't just keep evaluating forever like my brain at 3am, boundaries bestie, boundaries 💀
  • setMaximumIterations(mit) — sets the max number of solver iterations ✨ the classic. the icon. every solver has one and TAO is no different 👑
  • setMonitor(monitor[, args, kargs]) — sets the callback used to monitor solver convergence 💖 so you can literally watch it converge, main character energy, obsessed 🌈
  • setObjective(objective[, args, kargs]) — sets the objective function evaluation callback 🍓 the thing you're tryna minimize, the whole point of the operation, iykyk ✨
  • setObjectiveGradient(objgrad[, g, args, kargs]) — sets the objective function and gradient evaluation callback 🔥 combo deal, function AND gradient, two birds, slay 💅
  • setOptionsPrefix(prefix) — sets the prefix used for searching for options in the database 🦋 your little namespace tag so your options don't get mixed up with everyone else's, we love organization 💜
  • setPythonContext(context) — sets the instance of the class implementing the required Python methods 🎀 you're like "here's my object, it does the things" and TAO is like "cool, noted" 🫶
  • setPythonType(py_type) — sets the fully qualified Python name of the class to be used ⭐ fully qualified meaning the whole dotted path bestie, no shortcuts 🙈
  • setResidual(residual, R[, args, kargs]) — sets the residual evaluation callback for least-squares applications 💫 yes this is for the least-squares girlies specifically, if that's you, this is your moment 🌟
  • setSolution(x) — sets the vector used to store the solution 😌 the designated spot for the answer, the VIP section basically 👑
  • setStateDesignIS([state, design]) — sets the index sets indicating state and design variables 🔵 giving your problem structure, separating the state from the design, very organized of you fr fr 💅
  • setTolerances([gatol, grtol, gttol]) — sets the tolerance parameters used in the solver convergence tests ✨ gatol, grtol, gttol, the holy trinity of "how close is close enough" 🙏
  • setType(tao_type) — sets the type of the solver 🍓 like which flavor of TAO you want, pick your fighter bestie 🥊
  • setUp() — sets up the internal data structures for using the solver 🔥 the little pre-game ritual, the stretch before the run, you gotta do it 💪
  • setUpdate(update[, args, kargs]) — sets the callback to compute update at each optimization step 🦋 every step gets a little update, we love consistency 💜
  • setVariableBounds(varbounds[, args, kargs]) — sets the lower and upper bounds for the optimization problem 🎀 keeping your variables in their little lanes, containment, boundaries, healthy limits 🌸
  • solve([x]) — solve the optimization problem 👑 THE moment. the whole reason we're here. do the thing. slay. periodt. 💅✨
  • view([viewer]) — view the solver 🦋 cute little peek at what's going on inside, look at her, she's doing so good 🥹

✨ Attributes Summary ✨

okay bestie, here's the whole vibe check of what a Tao object is carrying around 💖 these are the attributes, one by one, no skipping:

  • appctx — Application context.
  • cnorm — Constraints norm.
  • converged — Boolean indicating if the solver has converged.
  • ctol — Broken.
  • diverged — Boolean indicating if the solver has failed.
  • ftol — Broken.
  • function — Objective value.
  • gnorm — Gradient norm.
  • gradient — Gradient vector.
  • gtol — Broken.
  • iterating — Boolean indicating if the solver has not converged yet.
  • its — Number of iterations.
  • ksp — Linear solver.
  • objective — Objective value.
  • reason — Converged reason.
  • solution — Solution vector.
heads up: ctol, ftol, and gtol are all literally marked Broken in the source. not my words, not a typo, that's just what they are 💀 don't come for me, come for the upstream.

💅 Methods Documentation 💅

addTerm(prefix, scale, term, params=None, mapmat=None)

Add an objective term to the solver.

Logically collective.

Parameters

  • prefix (str | None) — The prefix used for configuring the new term.
  • scale (float) — The scale of the term.
  • term (TAOTerm) — The objective term to be added to the solver.
  • params (Vec | None) — The parameter vector.
  • mapmat (Mat | None) — The mapping matrix.

Return type None

See also: TaoAddTerm https://petsc.org/release/manualpages/Tao/TaoAddTerm.html

Source code at petsc4py/PETSc/TAO.pyx:1762 https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1762

appendOptionsPrefix(prefix)

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

Logically collective.

See also: Working with PETSc options <#petsc-options>, setOptionsPrefix, TaoAppendOptionsPrefix https://petsc.org/release/manualpages/Tao/TaoAppendOptionsPrefix.html

Source code at petsc4py/PETSc/TAO.pyx:220 https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L220

Parameters

  • prefix (str | None)

Return type None

cancelMonitor()

Cancel all the monitors of the solver.

Logically collective.

See also: setMonitor, TaoMonitorCancel https://petsc.org/release/manualpages/Tao/TaoMonitorCancel.html

Source code at petsc4py/PETSc/TAO.pyx:1373 https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1373

Return type None

checkConverged()

Run convergence test and return converged reason.

Collective.

See also: converged

Source code at petsc4py/PETSc/TAO.pyx:1700 https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1700

Return type ConvergedReason

computeConstraints(x, c)

Compute the vector corresponding to the constraints.

Collective.

Parameters

  • x (Vec) — The parameter vector.
  • c (Vec) — The output constraints vector.

Return type None

See also: setVariableBounds, TaoComputeVariableBounds https://petsc.org/release/manualpages/Tao/TaoComputeVariableBounds.html

Source code at petsc4py/PETSc/TAO.pyx:1040 https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1040

computeDualVariables(xl, xu)

Compute the dual vectors corresponding to variables' bounds.

Collective.

See also: TaoComputeDualVariables https://petsc.org/release/manualpages/Tao/TaoComputeDualVariables.html

Source code at petsc4py/PETSc/TAO.pyx:1004 https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1004

Parameters

  • xl (Vec)
  • xu (Vec)

Return type None

computeGradient(x, g)

Compute the gradient of the objective function.

Collective.

Parameters

  • x (Vec) — The parameter vector.
  • g (Vec) — The output gradient vector.

Return type None

See also: setGradient, TaoComputeGradient https://petsc.org/release/manualpages/Tao/TaoComputeGradient.html

Source code at petsc4py/PETSc/TAO.pyx:963 https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L963

computeHessian(x, H, P=None)

Compute the Hessian of the objective function.

Collective.

Parameters

  • x (Vec) — The parameter vector.
  • H (Mat) — The output Hessian matrix.
  • P (Mat | None) — The output Hessian matrix used to construct the preconditioner.

Return type None

See also: setHessian, TaoComputeHessian — https://petsc.org/release/manualpages/Tao/TaoComputeHessian.html

Source code at petsc4py/PETSc/TAO.pyx:1059 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1059

computeJacobian(x, J, P=None)

Compute the Jacobian. Yes queen, the actual Jacobian 💅

Collective. (everyone in the communicator is in on this, no gatekeeping 🫶)

Parameters

  • x (Vec, anchor #petsc4py.PETSc.Vec) — the parameter vector.
  • J (Mat, anchor #petsc4py.PETSc.Mat) — the output Jacobian matrix.
  • P (Mat, anchor #petsc4py.PETSc.Mat | None, https://docs.python.org/3/builtins/constants.html#None) — the output Jacobian matrix used to construct the preconditioner.

Return type: None, https://docs.python.org/3/builtins/constants.html#None

See also: setJacobian, TaoComputeJacobian — https://petsc.org/release/manualpages/Tao/TaoComputeJacobian.html

Source code at petsc4py/PETSc/TAO.pyx:1082 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1082

computeObjective(x)

Compute the value of the objective function. it's giving "how good is this actually" ✨

Collective.

Parameters

  • x (Vec, anchor #petsc4py.PETSc.Vec) — the parameter vector.

Return type: float, https://docs.python.org/3/builtins/functions.html#float

See also: setObjective, TaoComputeObjective — https://petsc.org/release/manualpages/Tao/TaoComputeObjective.html

Source code at petsc4py/PETSc/TAO.pyx:925 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L925

computeObjectiveGradient(x, g)

Compute the gradient of the objective function and its value. two-for-one, bestie 🎀

Collective.

Parameters

  • x (Vec, anchor #petsc4py.PETSc.Vec) — the parameter vector.
  • g (Vec, anchor #petsc4py.PETSc.Vec) — the output gradient vector.

Return type: float, https://docs.python.org/3/builtins/functions.html#float

See also: setObjectiveGradient, setGradient, setObjective, TaoComputeObjectiveAndGradient — https://petsc.org/release/manualpages/Tao/TaoComputeObjectiveAndGradient.html

Source code at petsc4py/PETSc/TAO.pyx:982 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L982

computeResidual(x, f)

Compute the residual. the "how wrong are we rn" check 💀

Collective.

Parameters

  • x (Vec, anchor #petsc4py.PETSc.Vec) — the parameter vector.
  • f (Vec, anchor #petsc4py.PETSc.Vec) — the output vector.

Return type: None, https://docs.python.org/3/builtins/constants.html#None

See also: setResidual, TaoComputeResidual — https://petsc.org/release/manualpages/Tao/TaoComputeResidual.html

Source code at petsc4py/PETSc/TAO.pyx:944 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L944

computeVariableBounds(xl, xu)

Compute the vectors corresponding to variables' bounds. telling every single variable "here's your floor and here's your ceiling" 🦋

Collective.

See also: setVariableBounds, TaoComputeVariableBounds — https://petsc.org/release/manualpages/Tao/TaoComputeVariableBounds.html

Source code at petsc4py/PETSc/TAO.pyx:1016 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1016

Parameters

  • xl (Vec, anchor #petsc4py.PETSc.Vec)
  • xu (Vec, anchor #petsc4py.PETSc.Vec)

Return type: None, https://docs.python.org/3/builtins/constants.html#None

create(comm=None)

Create a TAO solver. brand new solver, fresh out the box 🌸

Collective.

Parameters

Return type: Self, https://docs.python.org/3/library/typing.html#typing.Self

See also: Sys.getDefaultComm (anchor #petsc4py.PETSc.Sys.getDefaultComm), TaoCreate — https://petsc.org/release/manualpages/Tao/TaoCreate.html

Source code at petsc4py/PETSc/TAO.pyx:152 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L152

createPython(context=None, comm=None)

Create an optimization solver of Python type. your own Python class, running the whole optimization, main character energy fr fr 🐍👑

Collective.

Parameters

Return type: Self, https://docs.python.org/3/library/typing.html#typing.Self

See also: PETSc Python optimization solver type (anchor #petsc-python-tao), setType, setPythonContext, Type.PYTHON (anchor #petsc4py.PETSc.TAO.Type.PYTHON)

Source code at petsc4py/PETSc/TAO.pyx:1957 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1957

destroy()

Destroy the solver. okay bye bestie, go home 🫶

Collective.

See also: TaoDestroy — https://petsc.org/release/manualpages/Tao/TaoDestroy.html

Source code at petsc4py/PETSc/TAO.pyx:139 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L139

Return type: Self, https://docs.python.org/3/library/typing.html#typing.Self

getALMMSubsolver()

Return the subsolver inside the ALMM solver. solver-ception, and we're obsessed 🔥

Not collective. (this one's just for you, no group chat needed)

See also: setALMMSubsolver, TaoALMMGetSubsolver — https://petsc.org/release/manualpages/Tao/TaoALMMGetSubsolver.html

Source code at petsc4py/PETSc/TAO.pyx:1797 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1797

Return type: TAO, anchor #petsc4py.PETSc.TAO

getALMMType()

Return the type of the ALMM solver. what flavor of ALMM are we in 💅

Not collective.

See also: setALMMType, TaoALMMGetType — https://petsc.org/release/manualpages/Tao/TaoALMMGetType.html

Source code at petsc4py/PETSc/TAO.pyx:1812 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1812

Return type: ALMMType, anchor #petsc4py.PETSc.TAO.ALMMType

getAppCtx()

Return the application context. yes, your little bag of stuff you attached earlier, it's still there ✨

Source code at petsc4py/PETSc/TAO.pyx:293 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L293

Return type: Any, https://docs.python.org/3/library/typing.html#typing.Any

getBNCGType()

Return the type of the BNCG solver. BNCG but which BNCG 👀

Not collective.

See also: setBNCGType, TaoBNCGGetType — https://petsc.org/release/manualpages/Tao/TaoBNCGGetType.html

Source code at petsc4py/PETSc/TAO.pyx:1569 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1569

Return type: BNCGType, anchor #petsc4py.PETSc.TAO.BNCGType

getBRGNDampingVector()

Return the damping vector. the little "chill out" vector for BRGN 🌈

Not collective.

Source code at petsc4py/PETSc/TAO.pyx:1942 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1942

Return type: Vec, anchor #petsc4py.PETSc.Vec

getBRGNSubsolver()

Return the subsolver inside the BRGN solver. another solver living inside a solver, iconic 🎀

Not collective.

See also: TaoBRGNGetSubsolver — https://petsc.org/release/manualpages/Tao/TaoBRGNGetSubsolver.html

Source code at petsc4py/PETSc/TAO.pyx:1859 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1859

Return type: TAO, anchor #petsc4py.PETSc.TAO

getConstraintTolerances()

Return the constraints tolerance parameters used in the convergence tests. aka "how close to the line are we letting you stand before I call it done" ⭐

Not collective.

Returns

  • catol (float) — the absolute norm of the constraints. like, the raw magnitude, no math gymnastics 💅
    • crtol (float) — the relative norm of the constraints. the scaled one bestie ✨

Return type: tuple[float, float]

See also: setConstraintTolerances, TaoGetConstraintTolerances <https://petsc.org/release/manualpages/Tao/TaoGetConstraintTolerances.html>

Source code at petsc4py/PETSc/TAO.pyx:1244 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1244>

getConvergedReason()

okay so this one hands you back the reason your solver stopped — did it converge, did it tap out, what was the vibe 😭

Not collective.

See also: TaoGetConvergedReason <https://petsc.org/release/manualpages/Tao/TaoGetConvergedReason.html>

Source code at petsc4py/PETSc/TAO.pyx:1626 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1626>

Return type: ConvergedReason

getConvergenceTest()

returns the callback you set up to decide "are we there yet" for the solver 🔥

Not collective.

See also: setConvergenceTest

Source code at petsc4py/PETSc/TAO.pyx:1293 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1293>

Return type: tuple[TAOConvergedFunction, tuple[Any, ...], dict[str, Any]]

getEqualityConstraints()

gives you back a tuple holding both the vector and the callback for the equality constraints 🎀 two-for-one, we love to see it

Not collective.

See also: setEqualityConstraints, TaoGetEqualityConstraintsRoutine <https://petsc.org/release/manualpages/Tao/TaoGetEqualityConstraintsRoutine.html>

Source code at petsc4py/PETSc/TAO.pyx:755 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L755>

Return type: tuple[Vec, tuple[TAOConstraintsFunction, tuple[Any, ...] | None, dict[str, Any] | None]]

getGradient()

returns the vector you're using to stash the gradient, plus the callback that evaluates it ✨

Not collective.

See also: setGradient, setHessian, TaoGetGradient <https://petsc.org/release/manualpages/Tao/TaoGetGradient.html>

Source code at petsc4py/PETSc/TAO.pyx:436 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L436>

Return type: tuple[Vec, TAOGradientFunction]

getGradientNorm()

ngl this one returns the matrix that's used to compute inner products, not a norm number, don't let the name fool you 💀

Not collective.

See also: setGradientNorm, TaoGetGradientNorm <https://petsc.org/release/manualpages/Tao/TaoGetGradientNorm.html>

Source code at petsc4py/PETSc/TAO.pyx:1484 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1484>

Return type: Mat

getHessian()

returns the matrices you keep the Hessian in, plus the evaluation callback 🦋 yes that's matrices, plural, there's two of them

Not collective.

See also: setHessian, TaoGetHessian <https://petsc.org/release/manualpages/Tao/TaoGetHessian.html>

Source code at petsc4py/PETSc/TAO.pyx:598 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L598>

Return type: tuple[Mat, Mat, TAOHessianFunction]

getInequalityConstraints()

same deal as the equality one but for inequality constraints — tuple with the vector and the callback, iconic 🌸

Not collective.

See also: setInequalityConstraints, TaoGetInequalityConstraintsRoutine <https://petsc.org/release/manualpages/Tao/TaoGetInequalityConstraintsRoutine.html>

Source code at petsc4py/PETSc/TAO.pyx:828 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L828>

Return type: tuple[Vec, tuple[TAOConstraintsFunction, tuple[Any, ...] | None, dict[str, Any] | None]]

getIterationNumber()

the current iteration number bestie, how many laps around the loop we're on 🏃‍♀️

Not collective.

See also: setIterationNumber, TaoGetIterationNumber <https://petsc.org/release/manualpages/Tao/TaoGetIterationNumber.html>

Source code at petsc4py/PETSc/TAO.pyx:1596 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1596>

Return type: int

getJacobianEquality()

returns the matrix, the preconditioner matrix, and the callback for the equality constraints Jacobian 👑 the full trio, main character energy fr fr

Not collective.

See also: setJacobianEquality, TaoGetJacobianEqualityRoutine <https://petsc.org/release/manualpages/Tao/TaoGetJacobianEqualityRoutine.html>

Source code at petsc4py/PETSc/TAO.pyx:792 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L792>

Return type: tuple[Mat, Mat, tuple[TAOConstraintsJacobianFunction, tuple[Any, ...] | None, dict[str, Any] | None]]

getJacobianInequality()

and the inequality version of the same thing — matrix, precon matrix, and the callback for the inequality constraints Jacobian 💜

Not collective.

See also: setJacobianInequality, TaoGetJacobianInequalityRoutine <https://petsc.org/release/manualpages/Tao/TaoGetJacobianInequalityRoutine.html>

🎀 getConstraintsJacobian()'s return block, continued

Return type:

tuple[Mat, Mat, tuple[TAOConstraintsJacobianFunction, tuple[Any, ...] | None, dict[str, Any] | None]]
Okay so bestie, that was the tail end of that return type and we are MOVING ON 😌

Source code at petsc4py/PETSc/TAO.pyx:865 — go peek if u want: https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L865

✨ getKSP()

Hands u back the linear solver that the nonlinear solver is using, fr fr.

Not collective — no cap, every rank just gets it, u don't have to coordinate with anyone 🫶

See also: TaoGetKSP — https://petsc.org/release/manualpages/Tao/TaoGetKSP.html

Source code at petsc4py/PETSc/TAO.pyx:1714 💅 https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1714

Return type: KSP

🌸 getLMVMH0()

Gives u the initial Hessian for the quasi-Newton approximation. like, the starting Hessian vibe 💜

Not collective.

See also: setLMVMH0, TaoLMVMGetH0 — https://petsc.org/release/manualpages/Tao/TaoLMVMGetH0.html

Source code at petsc4py/PETSc/TAO.pyx:1511 ⭐ https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1511

Return type: Mat

🦋 getLMVMH0KSP()

Returns the KSP for the inverse of the initial Hessian approximation. yes the inverse, we said what we said 😭

Not collective.

See also: setLMVMH0, TaoLMVMGetH0KSP — https://petsc.org/release/manualpages/Tao/TaoLMVMGetH0KSP.html

Source code at petsc4py/PETSc/TAO.pyx:1526 🌈 https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1526

Return type: KSP

👑 getLMVMMat()

Gets the LMVM matrix. that's it, that's the whole thing, she's simple and iconic 💖

Not collective.

See also: setLMVMMat, TaoGetLMVMMatrix — https://petsc.org/release/manualpages/Tao/TaoGetLMVMMatrix.html

Source code at petsc4py/PETSc/TAO.pyx:709 🍓 https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L709

Return type: Mat

🧚 getLineSearch()

Returns the TAO Line Search object 🎀 like the whole line search bestie, come get her.

Not collective.

See also: TaoGetLineSearch — https://petsc.org/release/manualpages/Tao/TaoGetLineSearch.html

Source code at petsc4py/PETSc/TAO.pyx:2039 ✨ https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L2039

Return type: TAOLineSearch

💜 getMaximumFunctionEvaluations()

Returns the max number of objective evaluations the solver is allowed to do within the solver. it's giving budget, and the budget is int 🔥

Not collective.

See also: setMaximumFunctionEvaluations, TaoGetMaximumFunctionEvaluations — https://petsc.org/release/manualpages/Tao/TaoGetMaximumFunctionEvaluations.html

Source code at petsc4py/PETSc/TAO.pyx:1204 🌸 https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1204

Return type: int

💅 getMaximumIterations()

Returns the maximum number of solver iterations. the cap on the grind, periodt ⭐

Not collective.

See also: setMaximumIterations, TaoGetMaximumIterations — https://petsc.org/release/manualpages/Tao/TaoGetMaximumIterations.html

Source code at petsc4py/PETSc/TAO.pyx:1177 🫶 https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1177

Return type: int

🔥 getMonitor()

Returns the callback that's out here monitoring solver convergence 👀 the little watcher, the vibe checker.

Not collective.

See also: setMonitor

Source code at petsc4py/PETSc/TAO.pyx:1361 💖 https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1361

Return type:

list[tuple[TAOMonitorFunction, tuple[Any, ...], dict[str, Any]]]

🌈 getObjective()

Returns the objective evaluation callback. the main character function, lowkey 🎀

Not collective.

See also: setObjective, TaoGetObjective — https://petsc.org/release/manualpages/Tao/TaoGetObjective.html

Source code at petsc4py/PETSc/TAO.pyx:423 😭 https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L423

Return type: TAOObjectiveFunction

🦋 getObjectiveAndGradient()

Returns both the vector that stores the gradient and the evaluation callback, two for one, a duo, ate 💜

Not collective.

See also: setObjectiveGradient, TaoGetObjectiveAndGradient — https://petsc.org/release/manualpages/Tao/TaoGetObjectiveAndGradient.html

Source code at petsc4py/PETSc/TAO.pyx:482 🍓 https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L482

Return type:

tuple[Vec, TAOObjectiveGradientFunction]

🧚 getObjectiveValue()

Returns the current value of the objective function. like right now, this instant, live numbers ✨

Not collective.

See also: setObjective, TaoGetSolutionStatus — https://petsc.org/release/manualpages/Tao/TaoGetSolutionStatus.html

Source code at petsc4py/PETSc/TAO.pyx:1610 🌸 https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1610

Return type: float

👑 getOptionsPrefix()

Returns the prefix the solver searches for when it's digging through the options database. the little name tag so ur options know which solver they belong to 🎀

Not collective.

See also: Working with PETSc options (#petsc-options), setOptionsPrefix, TaoGetOptionsPrefix — https://petsc.org/release/manualpages/Tao/TaoGetOptionsPrefix.html

Source code at petsc4py/PETSc/TAO.pyx:234 💅 https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L234

Return type: str

🌟 getPythonContext()

Returns the instance of the class that's implementing all the required Python methods. like, the actual object doing the work behind the scenes, iykyk 🫶

Not collective.

See also: PETSc Python optimization solver type (#petsc-python-tao), setPythonContext

Source code at petsc4py/PETSc/TAO.pyx:1994 🦋 https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1994

Return type: Any

💖 getPythonType()

Returns the fully qualified Python name of the class the solver is using. full government name, no nicknames ⭐

Not collective.

See also: PETSc Python optimization solver type (#petsc-python-tao), setPythonContext, setPythonType, TaoPythonGetType — https://petsc.org/release/manualpages/Tao/TaoPythonGetType.html

Source code at petsc4py/PETSc/TAO.pyx:2024 💜 https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L2024

Return type: str

getSolution()

Gives you back the vector holding the solution — the actual answer, bestie. 💖

Not collective — every process doin' its own thing here, no group chat needed.

See also: setSolution, TaoGetSolution — https://petsc.org/release/manualpages/Tao/TaoGetSolution.html

Source code at petsc4py/PETSc/TAO.pyx:1457 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1457

Return type: Vec

getSolutionNorm()

Hands you the objective function value plus the norms of the gradient and constraints. Basically the vibe check on how close you are. ✨

Not collective.

Returns:

  • f (float) — Current value of the objective function.
  • res (float) — Current value of the residual norm.
  • cnorm (float) — Current value of the constrains norm.
Yes, it says "constrains norm" in the original and I am not changing a single character, that's the rule. 🙈

Return type: tuple[float, float, float]

See also: getSolutionStatus, TaoGetSolutionStatus — https://petsc.org/release/manualpages/Tao/TaoGetSolutionStatus.html

Source code at petsc4py/PETSc/TAO.pyx:1640 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1640

getSolutionStatus()

The full status report on your solution — like when your friend asks "how's it going" and you give them the entire rundown. 😭 Six whole things back, bestie.

Not collective.

Returns:

  • its (int) — Current number of iterations.
  • f (float) — Current value of the objective function.
  • res (float) — Current value of the residual norm.
  • cnorm (float) — Current value of the constrains norm.
  • step (float) — Current value of the step.
  • reason (ConvergedReason) — Current value of converged reason.

Return type: tuple[int, float, float, float, float, ConvergedReason]

See also: TaoGetSolutionStatus — https://petsc.org/release/manualpages/Tao/TaoGetSolutionStatus.html

Source code at petsc4py/PETSc/TAO.pyx:1665 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1665

getTerm()

Returns the entire objective term of the solver. The whole thing. Not a fraction, not a snippet, the whole term, periodt. 👑

Not collective.

Returns:

  • scale (float) — The scale of the term.
  • term (TAOTerm) — The term of the whole objective.
  • params (Vec) — The parameters vector.
  • mapmat (Mat) — The mapping matrix of the term.

Return type: tuple[float, TAOTerm, Vec, Mat]

See also: TaoGetTerm — https://petsc.org/release/manualpages/Tao/TaoGetTerm.html

Source code at petsc4py/PETSc/TAO.pyx:1731 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1731

getTolerances()

Pulls up the tolerance parameters the solver is using for its convergence tests. iykyk, tolerances are literally everything. 🎀

Not collective.

Returns:

  • gatol (float) — The absolute norm of the gradient.
  • grtol (float) — The relative norm of the gradient.
  • gttol (float) — The relative norm of the gradient with respect to the initial norm of the gradient.

Return type: tuple[float, float, float]

See also: setTolerances, TaoGetTolerances — https://petsc.org/release/manualpages/Tao/TaoGetTolerances.html

Source code at petsc4py/PETSc/TAO.pyx:1140 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1140

getType()

Tells you which type of solver you're working with. Simple. Iconic. No notes. 💅

Not collective.

See also: setType, TaoGetType — https://petsc.org/release/manualpages/Tao/TaoGetType.html

Source code at petsc4py/PETSc/TAO.pyx:192 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L192

Return type: str

getUpdate()

Returns the callback that computes the update</c>mint> — the little function that does the mathy push forward. 🦋

Not collective.

See also: setUpdate

Source code at petsc4py/PETSc/TAO.pyx:911 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L911

Return type: tuple[TAOUpdateFunction, tuple[Any, ...], dict[str, Any]]

getVariableBounds()

Gives you back the lower and upper bounds vectors</c>cyan> — the lil' fence your variables are chillin' inside of. 🫶

Not collective.

See also: setVariableBounds, TaoGetVariableBounds — https://petsc.org/release/manualpages/Tao/TaoGetVariableBounds.html

Source code at petsc4py/PETSc/TAO.pyx:1541 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1541

Return type: tuple[Vec, Vec]

monitor(its=None, f=None, res=None, cnorm=None, step=None)

Monitors the solver, bestie — the lil "how we doin" check-in. 🌈

Collective — everybody's in on this one, all processes together, no stragglers.

Heads up: this function should be called without arguments, unless users want to modify the values internally stored by the solver. So like... just monitor() and vibe, unless you're deliberately overriding stuff.

Parameters:

  • its (int | None) — Current number of iterations or None to use the value stored internally by the solver.
  • f (float | None) — Current value of the objective function or None to use the value stored internally by the solver.
  • res (float | None) — the residual norm's current value, or None if you want the solver to just use the value it's already holding internally. let it cook.
  • cnorm (float | None) — same deal but for the constraints norm, or None to let the solver's internal value ride.
  • step (float | None) — the current value of the step, or None to defer to whatever the solver stores internally.

Return type: None

See also: setMonitor, TaoMonitor

Source code at petsc4py/PETSc/TAO.pyx:1387

setALMMSubsolver(subsolver)

okay so this one sets the subsolver that lives inside the ALMM solver. nesting era 💅

Logically collective.

See also: getALMMSubsolver, TaoALMMSetSubsolver

Source code at petsc4py/PETSc/TAO.pyx:1826

Parameters

  • subsolver (TAO)

Return type: None

setALMMType(tao_almm_type)

sets the ALMM type of the solver. yes bestie, the type. iconic behavior.

Logically collective.

Parameters

  • tao_almm_type (ALMMType) — the type of the solver.

Return type: None

See also: getALMMType, TaoALMMSetType

Source code at petsc4py/PETSc/TAO.pyx:1839

setAppCtx(appctx)

Set the application context. that's it, that's the whole job, and it slays at it ✨

Source code at petsc4py/PETSc/TAO.pyx:289

Parameters

  • appctx (Any)

Return type: None

setBNCGType(cg_type)

Set the type of the BNCG solver.

Collective.

See also: getBNCGType, TaoBNCGSetType

Source code at petsc4py/PETSc/TAO.pyx:1556

Parameters

  • cg_type (BNCGType)

Return type: None

setBRGNDictionaryMatrix(D)

Set the dictionary matrix. yes ma'am, the dictionary matrix, the whole vocabulary 🎀

Collective.

See also: TaoBRGNSetDictionaryMatrix

Source code at petsc4py/PETSc/TAO.pyx:1930

Parameters

  • D (Mat)

Return type: None

setBRGNRegularizerHessian(hessian, H=None, args=None, kargs=None)

Set the callback to compute the regularizer Hessian. you're handing over a whole function, bestie, so make it count 💖

Logically collective.

See also: TaoBRGNSetRegularizerHessianRoutine

Source code at petsc4py/PETSc/TAO.pyx:1890

Parameters

  • H (Mat | None)
  • args (tuple[Any, ...] | None)
  • kargs (dict[str, Any] | None)

Return type: None

setBRGNRegularizerObjectiveGradient(objgrad, args=None, kargs=None)

Set the callback to compute the regularizer objective and gradient. objective and gradient, both of them, together, as a unit 🫶

Logically collective.

See also: TaoBRGNSetRegularizerObjectiveAndGradientRoutine

Source code at petsc4py/PETSc/TAO.pyx:1874

Parameters

  • args (tuple[Any, ...] | None)
  • kargs (dict[str, Any] | None)

Return type: None

setBRGNRegularizerWeight(weight)

Set the regularizer weight. lowkey important, highkey does not miss.

Collective.

Source code at petsc4py/PETSc/TAO.pyx:1908

Parameters

  • weight (float)

Return type: None

setBRGNSmoothL1Epsilon(epsilon)

Set the smooth L1 epsilon. little epsilon, huge responsibilities 🌸

Collective.

See also: TaoBRGNSetL1SmoothEpsilon

Source code at petsc4py/PETSc/TAO.pyx:1917

Parameters

  • epsilon (float)

Return type: None

setConstraintTolerances(catol=None, crtol=None)

Set the constraints tolerance parameters used in the solver convergence tests. this is the "are we done yet" math, so be nice to it ✨

Collective.

Parameters

  • catol (float | None) — the absolute norm of the constraints, or DETERMINE to use the value from when the object's type was set. it defaults to CURRENT.
  • crtol (float | None) — the relative norm of the constraints, or DETERMINE if you want it to use the value from back when the object's type got set. Defaults to CURRENT. 💖

Return type: None

See also: getConstraintTolerances, TaoSetConstraintTolerances

Source code at petsc4py/PETSc/TAO.pyx:1218

setConstraints

setConstraints(constraints, C=None, args=None, kargs=None)

okay bestie this is the one that tells TAO how to actually compute your constraints ✨

Logically collective.

Parameters

  • constraints (TAOConstraintsFunction) — the callback. the moment of truth. 🫶
  • C (Vec | None) — the vector that's gonna hold the constraints.
  • args (tuple[Any, ...] | None) — positional arguments you're handing to the callback.
  • kargs (dict[str, Any] | None) — keyword arguments for the callback.

Return type: None

See also: TaoSetConstraintsRoutine

Source code at petsc4py/PETSc/TAO.pyx:534

setConvergedReason

setConvergedReason(reason)

sets the termination flag — like, the official "we're done here" announcement 💅

Collective.

See also: getConvergedReason, TaoSetConvergedReason

Source code at petsc4py/PETSc/TAO.pyx:1305

Parameters

  • reason (ConvergedReason)

Return type: None

setConvergenceTest

setConvergenceTest(converged, args=None, kargs=None)

swaps in the callback that decides whether your solver has ~converged~ 🦋

Logically collective.

Parameters

  • converged (TAOConvergedFunction | None) — the callback. and listen, if this is None, it resets everything back to the default convergence test. so ✨ reversible ✨
  • args (tuple[Any, ...] | None) — positional arguments for the callback.
  • kargs (dict[str, Any] | None) — keyword arguments for the callback.

Return type: None

See also: getConvergenceTest, TaoSetConvergenceTest

Source code at petsc4py/PETSc/TAO.pyx:1265

setEqualityConstraints

setEqualityConstraints(equality_constraints, c, args=None, kargs=None)

sets the equality constraints callback. yes, equality. the strict ones. no cap. 😤

Logically collective.

See also: TaoSetEqualityConstraintsRoutine

Source code at petsc4py/PETSc/TAO.pyx:737

Parameters

  • c (Vec)
  • args (tuple[Any, ...] | None)
  • kargs (dict[str, Any] | None)

Return type: None

setFromOptions

setFromOptions()

configures the whole solver straight out of the options database 🎀 the options are just there, bestie, go get them.

Collective.

See also: Working with PETSc options, TaoSetFromOptions

Source code at petsc4py/PETSc/TAO.pyx:248

Return type: None

setGradient

setGradient(gradient, g=None, args=None, kargs=None)

sets the gradient evaluation callback — the ⭐ main character ⭐ of a lot of TAO runs, honestly.

Logically collective.

Parameters

  • gradient (TAOGradientFunction) — the gradient callback.
  • g (Vec | None) — the vector where the gradient gets stored.
  • args (tuple[Any, ...] | None) — positional arguments for the callback.
  • kargs (dict[str, Any] | None) — keyword arguments for the callback.

Return type: None

See also: setObjective, setObjectiveGradient, setHessian, TaoSetGradient

Source code at petsc4py/PETSc/TAO.pyx:394

setGradientNorm

setGradientNorm(mat)

sets the matrix used to compute inner products 🧮💜

Collective.

See also: getGradientNorm, TaoSetGradientNorm

Source code at petsc4py/PETSc/TAO.pyx:1472

Parameters

  • mat (Mat)

Return type: None

setHessian

setHessian(hessian, H=None, P=None, args=None, kargs=None)

sets the callback that computes the Hessian matrix 👑 second derivatives, she's fancy, she's slaying.

Logically collective.

Parameters

  • hessian (TAOHessianFunction) — the Hessian callback. 🍓
  • H (Mat | None) — the matrix where we're stashing the Hessian, bestie 💖
  • P (Mat | None) — the matrix we build the preconditioner out of ✨
  • args (tuple[Any, ...] | None) — positional args you wanna hand off to the callback 🫶
  • kargs (dict[str, Any] | None) — keyword args for the callback, no cap 🎀

Return type None

See also: getHessian, setObjective, setObjectiveGradient, setGradient, TaoSetHessian

Source code at petsc4py/PETSc/TAO.pyx:563 🦋

setInequalityConstraints(inequality_constraints, c, args=None, kargs=None)

okay so this one sets the inequality-constraints callback 💅

Logically collective.

See also: TaoSetInequalityConstraintsRoutine

Source code at petsc4py/PETSc/TAO.pyx:810 🧚

Parameters — like, here's the whole squad:

  • c (Vec) 💜
  • args (tuple[Any, ...] | None)
  • kargs (dict[str, Any] | None)

Return type None

setInitialTrustRegionRadius(radius)

Sets the initial trust region radius 🌸 literally what it says.

Collective.

See also: TaoSetInitialTrustRegionRadius

Source code at petsc4py/PETSc/TAO.pyx:274 😭

Parameters

  • radius (float) — the starting radius, bestie ⭐

Return type None

setIterationNumber(its)

Sets the current iteration number 👑

Collective.

See also: getIterationNumber, TaoSetIterationNumber

Source code at petsc4py/PETSc/TAO.pyx:1583 🔥

Parameters

  • its (int) — how many iterations we're on rn 🌈

Return type None

setJacobian(jacobian, J=None, P=None, args=None, kargs=None)

Sets the callback that computes the Jacobian 💅 this is the moment, fr fr.

Logically collective.

Parameters

  • jacobian (TAOJacobianFunction) — the Jacobian callback itself, the main character ✨
  • J (Mat | None) — the matrix to store the Jacobian 💖
  • P (Mat | None) — the matrix to construct the preconditioner 🎀
  • args (tuple[Any, ...] | None) — positional arguments for the callback 🫶
  • kargs (dict[str, Any] | None) — keyword arguments for the callback 💜

Return type None

See also: TaoSetJacobianRoutine

Source code at petsc4py/PETSc/TAO.pyx:616 🦋

setJacobianDesign(jacobian_design, J=None, args=None, kargs=None)

Sets the Jacobian design callback 🧚 okay work.

Logically collective.

See also: TaoSetJacobianDesignRoutine

Source code at petsc4py/PETSc/TAO.pyx:689 🌸

Parameters

  • J (Mat | None)
  • args (tuple[Any, ...] | None)
  • kargs (dict[str, Any] | None)

Return type None

setJacobianEquality(jacobian_equality, J=None, P=None, args=None, kargs=None)

Sets the Jacobian equality constraints callback 😭 the constraints are constraining.

Logically collective.

See also: TaoSetJacobianEqualityRoutine

Source code at petsc4py/PETSc/TAO.pyx:770 🔥

Parameters

  • J (Mat | None)
  • P (Mat | None)
  • args (tuple[Any, ...] | None)
  • kargs (dict[str, Any] | None)

Return type None

setJacobianInequality(jacobian_inequality, J=None, P=None, args=None, kargs=None)

Sets the Jacobian inequality constraints callback 💅 yes she's different from the equality one, iykyk.

Logically collective.

See also: TaoSetJacobianInequalityRoutine
🔍 Source code at petsc4py/PETSc/TAO.pyx:843 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L843

Parameters 🌸

  • J (Mat | None)
  • P (Mat | None)
  • args (tuple[Any, ...] | None)
  • kargs (dict[str, Any] | None)

Return type 💜

  • None

✨ setJacobianResidual(jacobian, J=None, P=None, args=None, kargs=None)

Okay bestie, this one sets the callback that computes the least-squares residual Jacobian. 👑

Logically collective.

Parameters 🎀

  • jacobian (TAOJacobianResidualFunction) — the Jacobian callback. Like, the actual function that does the math, no cap.
  • J (Mat | None) — the matrix where the Jacobian gets stored.
  • P (Mat | None) — the matrix used to build the preconditioner.
  • args (tuple[Any, ...] | None) — positional arguments you wanna hand off to the callback.
  • kargs (dict[str, Any] | None) — keyword arguments for the callback.

Return type 💜

  • None

See also: setResidual, TaoSetJacobianResidualRoutine → https://petsc.org/release/manualpages/Tao/TaoSetJacobianResidualRoutine.html

🔍 Source code at petsc4py/PETSc/TAO.pyx:361 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L361

✨ setJacobianState(jacobian_state, J=None, P=None, I=None, args=None, kargs=None)

Sets the Jacobian state callback. That's the whole vibe. 🦋

Logically collective.

See also: TaoSetJacobianStateRoutine → https://petsc.org/release/manualpages/Tao/TaoSetJacobianStateRoutine.html

🔍 Source code at petsc4py/PETSc/TAO.pyx:665 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L665

Parameters 🎀

  • J (Mat | None)
  • P (Mat | None)
  • I (Mat | None)
  • args (tuple[Any, ...] | None)
  • kargs (dict[str, Any] | None)

Return type 💜

  • None

✨ setLMVMH0(mat)

Sets the initial Hessian for the quasi-Newton approximation. It's giving "starting point but make it fancy". 💅

Collective.

See also: getLMVMH0, TaoLMVMSetH0 → https://petsc.org/release/manualpages/Tao/TaoLMVMSetH0.html

🔍 Source code at petsc4py/PETSc/TAO.pyx:1499 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1499

Parameters 🎀

  • mat (Mat)

Return type 💜

  • None

✨ setLMVMMat(M)

Sets the LMVM matrix, bestie. That's it, that's the whole job. 🌈

Logically collective.

See also: getLMVMMat, TaoSetLMVMMatrix → https://petsc.org/release/manualpages/Tao/TaoSetLMVMMatrix.html

🔍 Source code at petsc4py/PETSc/TAO.pyx:724 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L724

Parameters 🎀

  • M (Mat)

Return type 💜

  • None

✨ setMaximumFunctionEvaluations(mit)

Sets the max number of objective evaluations the solver is allowed to do. Like a screen-time limit but for your objective function. 😭

Collective.

See also: setMaximumIterations, TaoSetMaximumFunctionEvaluations → https://petsc.org/release/manualpages/Tao/TaoSetMaximumFunctionEvaluations.html

🔍 Source code at petsc4py/PETSc/TAO.pyx:1191 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1191

Parameters 🎀

  • mit (int)

Return type 💜

  • None

✨ setMaximumIterations(mit)

Sets the maximum number of solver iterations. The hard cap. The boundary. The "we're done here" moment. 🫶

Collective.

See also: setTolerances, TaoSetMaximumIterations → https://petsc.org/release/manualpages/Tao/TaoSetMaximumIterations.html

🔍 Source code at petsc4py/PETSc/TAO.pyx:1164 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1164

Parameters 🎀

  • mit (int)

Return type 💜

  • float

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

Sets the callback that monitors solver convergence. This is the one that watches the whole glow-up happen in real time. 👀

Logically collective.

Parameters 🎀

  • monitor (TAOMonitorFunction) — the callback itself.
  • args (tuple[Any, ...] | None) — positional arguments you're passing to the callback.
  • kargs (dict[str, Any] | None) — keyword arguments for the callback.

Return type 💜

  • None

See also: getMonitor, TaoMonitorSet → https://petsc.org/release/manualpages/Tao/TaoMonitorSet.html

🔍 Source code at petsc4py/PETSc/TAO.pyx:1332 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L1332

✨ setObjective(objective, args=None, kargs=None)

Sets the objective function evaluation callback. The main character of the whole optimization, fr fr. 🌟

Logically collective.

Parameters 🎀

  • objective (TAOObjectiveFunction) — the objective function callback.
  • args (tuple[Any, ...] | None) — bestie, these are the positional args you wanna hand off to the callback. Just tuple them up. ✨
    • kargs (dict[str, Any] | None) — and these are the keyword args for the callback. Dict energy, keyed by str, values can be literally Anything. 🎀

Return type — None. Nothing comes back, it just does the thing. 💅

See also: setGradient, setObjectiveGradient, TaoSetObjective.

Source code at petsc4py/PETSc/TAO.pyx:309

✨ setObjectiveGradient(objgrad, g=None, args=None, kargs=None) ✨

Okay so this one sets the objective function and gradient evaluation callback. Two-for-one, icon behavior. 👑

Logically collective — so like, everybody in the communicator should be on the same page. No rogue processes doing their own thing. 🫶

Parameters

  • objgrad (TAOObjectiveGradientFunction) — the objective function and gradient callback. The main character. 💖
  • g (Vec | None) — the vector you're storing the gradient in.
  • args (tuple[Any, ...] | None) — positional arguments for the callback.
  • kargs (dict[str, Any] | None) — keyword arguments for the callback.

Return type — None. As always, no returns, no notes. 😌

See also: setObjective, setGradient, setHessian, getObjectiveAndGradient, TaoSetObjectiveAndGradient.

Source code at petsc4py/PETSc/TAO.pyx:452

✨ setOptionsPrefix(prefix) ✨

Sets the prefix that gets used when searching for options in the database. Basically your little name tag so PETSc knows which options are yours. 🏷️

Logically collective.

See also: Working with PETSc options, TaoSetOptionsPrefix.

Source code at petsc4py/PETSc/TAO.pyx:206

Parameters

  • prefix (str | None)

Return type — None.

✨ setPythonContext(context) ✨

Hand it the instance of your class that implements the required Python methods. This is you dropping your own custom brain into the solver. 🧠✨

Not collective — this one's just you, no group chat required. 🙈

See also: PETSc Python optimization solver type, getPythonContext.

Source code at petsc4py/PETSc/TAO.pyx:1982

Parameters

  • context (Any)

Return type — None.

✨ setPythonType(py_type) ✨

Sets the fully qualified Python name of the class you wanna use. Fully qualified, bestie — that means the whole dotted path, not a nickname. 😭

Collective.

See also: PETSc Python optimization solver type, setPythonContext, getPythonType, TaoPythonSetType.

Source code at petsc4py/PETSc/TAO.pyx:2009

Parameters

  • py_type (str)

Return type — None.

✨ setResidual(residual, R, args=None, kargs=None) ✨

Sets the residual evaluation callback — this one's for least-squares applications specifically, so if that's your vibe, this is your girl. 📐

Logically collective.

Parameters

  • residual (TAOResidualFunction) — the residual callback.
  • R (Vec) — the vector where the residual goes to live.
  • args (tuple[Any, ...] | None) — positional arguments for the callback.
  • kargs (dict[str, Any] | None) — keyword arguments for the callback.

Return type — None.

See also: setJacobianResidual, TaoSetResidualRoutine.

Source code at petsc4py/PETSc/TAO.pyx:334

✨ setSolution(x) ✨

Sets the vector that stores the solution. Home base for your answer. 🏡💖

Collective.

See also: getSolution, TaoSetSolution.

Source code at petsc4py/PETSc/TAO.pyx:297

Parameters

  • x (Vec)

Return type — None.

✨ setStateDesignIS(state=None, design=None) ✨

Sets the index sets that flag which variables are state variables and which ones are design variables. Separating the girls from the girls, respectfully. 💅

Collective.

See also: TaoSetStateDesignIS.

Source code at petsc4py/PETSc/TAO.pyx:650

Parameters

  • state (IS | None)
  • design (IS | None)

Return type — None.

✨ setTolerances(gatol=None, grtol=None, gttol=None) ✨

Sets the tolerance parameters used in the solver convergence tests. This is where you tell it how close is close enough. 🔥

Collective.

Parameters

  • gatol (float | None) — the absolute norm of the gradient, or DETERMINE to use the value from when the object's type was set. Defaults to CURRENT. ✨
  • grtol (float | None) — the relative norm of the gradient compared to the initial norm of the objective, okay? Or pass DETERMINE to just use whatever value was set when the object's type got locked in. Defaults to CURRENT. 💫
  • gttol (float | None) — the relative norm of the gradient compared to the initial norm of the gradient this time (yes it's different, bestie, read it twice 😌), or DETERMINE to grab the value from when the object's type was set. Defaults to CURRENT.

Return type None

See also: getTolerances, TaoSetTolerances <https://petsc.org/release/manualpages/Tao/TaoSetTolerances.html>

Source code at petsc4py/PETSc/TAO.pyx:1107

setType(tao_type)

Sets the type of the solver. That's it, that's the whole vibe. ✨

Logically collective.

Parameters

  • tao_type (Type | str) — the type of the solver.

Return type None

See also: getType, TaoSetType <https://petsc.org/release/manualpages/Tao/TaoSetType.html>

Source code at petsc4py/PETSc/TAO.pyx:173

setUp()

Sets up all the internal data structures so the solver is actually ready to do its thing. 💅

Collective.

See also: TaoSetUp <https://petsc.org/release/manualpages/Tao/TaoSetUp.html>

Source code at petsc4py/PETSc/TAO.pyx:260

Return type None

setUpdate(update, args=None, kargs=None)

Sets the callback that computes the update at every single optimization step. Like a little routine that runs each iteration, no cap.

Logically collective.

Parameters

  • update (TAOUpdateFunction) — the update callback, or None to reset it. 🫶
  • args (tuple[Any, ...] | None) — positional arguments you wanna feed the callback.
  • kargs (dict[str, Any] | None) — keyword arguments for the callback.

Return type None

See also: getUpdate, TaoSetUpdate <https://petsc.org/release/manualpages/Tao/TaoSetUpdate.html>

Source code at petsc4py/PETSc/TAO.pyx:882

setVariableBounds(varbounds, args=None, kargs=None)

Sets the lower and upper bounds for the optimization problem. Gotta keep your variables in their lane, fr fr. 🚧

Logically collective.

Parameters

  • varbounds (tuple[Vec, Vec] | TAOVariableBoundsFunction) — either a tuple of Vec OR a TAOVariableBoundsFunction callback, your pick bestie.
  • args (tuple[Any, ...] | None) — positional arguments for the callback.
  • kargs (dict[str, Any] | None) — keyword arguments for the callback.

Return type None

See also: TaoSetVariableBounds <https://petsc.org/release/manualpages/Tao/TaoSetVariableBounds.html>, TaoSetVariableBoundsRoutine <https://petsc.org/release/manualpages/Tao/TaoSetVariableBoundsRoutine.html>

Source code at petsc4py/PETSc/TAO.pyx:498

solve(x=None)

Solve the optimization problem. The main character moment. 👑

Collective.

Parameters

  • x (Vec | None) — the starting vector, or None to just use the vector stored internally (iykyk).

Return type None

See also: setSolution, getSolution, TaoSolve <https://petsc.org/release/manualpages/Tao/TaoSolve.html>

Source code at petsc4py/PETSc/TAO.pyx:1438

view(viewer=None)

Views the solver. Show me what you're working with. 👀✨

Collective.

Parameters

  • viewer (Viewer | None) — a Viewer instance, or None for the default viewer.

Return type None

See also: TaoView <https://petsc.org/release/manualpages/Tao/TaoView.html>

Source code at petsc4py/PETSc/TAO.pyx:120

🎀 Attributes Documentation 🎀

appctx

Application context.

Source code at petsc4py/PETSc/TAO.pyx:2060

cnorm

Constraints norm.

Source code at petsc4py/PETSc/TAO.pyx:2129

converged

Boolean indicating if the solver has converged. 🎉 (when it's True, we celebrate)

Source code at petsc4py/PETSc/TAO.pyx:2166

ctol

Broken. 💀 (not my words, the docs literally said it, so I'm passing it along)

Source code at petsc4py/PETSc/TAO.pyx:2104

diverged

Boolean indicating if the solver has failed. 😭 sending hugs

Source code at petsc4py/PETSc/TAO.pyx:2171

ftol

Broken. 💀 (again — same energy as ctol)

Source code at petsc4py/PETSc/TAO.pyx:2078

function

Objective value.

Source code at petsc4py/PETSc/TAO.pyx:2144

gnorm

Gradient norm.

  • gradient — the gradient vector, bestie. It's giving "where the slope is at" 🦋

Source code at petsc4py/PETSc/TAO.pyx:2149 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L2149>

  • gtol — Broken. That's literally all it says, no cap 😭 so don't come for me

Source code at petsc4py/PETSc/TAO.pyx:2091 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L2091>

  • iterating — a Boolean that tells you whether the solver has not converged yet. So like, True = still cooking 🍓, False = we ate, periodt.

Source code at petsc4py/PETSc/TAO.pyx:2161 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L2161>

  • its — the number of iterations. The step count, the era count, whatever you wanna call it 💅

Source code at petsc4py/PETSc/TAO.pyx:2119 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L2119>

  • ksp — the linear solver. Your little linear-solve bestie that lives inside the optimizer 🫶

Source code at petsc4py/PETSc/TAO.pyx:2070 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L2070>

  • objective — the objective value. Like, how good is the thing we're optimizing rn? That number 🎀

Source code at petsc4py/PETSc/TAO.pyx:2139 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L2139>

  • reason — the converged reason. Why did this whole saga end? This tells you 🌸

Source code at petsc4py/PETSc/TAO.pyx:2156 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L2156>

  • solution — the solution vector. The main character. The answer we've been waiting for the whole time 👑

Source code at petsc4py/PETSc/TAO.pyx:2134 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L2134>

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

✨ petsc4py.PETSc.TAOLineSearch ✨

class petsc4py.PETSc.TAOLineSearch

Bases: Object <#petsc4py.PETSc.Object>

TAO Line Search. It's the glow-up step ✨ — the part that decides how far to actually move once it knows which way to go.

Enumerations

  • ConvergedReason <#petsc4py.PETSc.TAOLineSearch.ConvergedReason> — TAO Line Search Termination Reasons.
  • Type <#petsc4py.PETSc.TAOLineSearch.Type> — TAO Line Search Types.

💖 petsc4py.PETSc.TAOLineSearch.ConvergedReason 💖</

class petsc4py.PETSc.TAOLineSearch.ConvergedReason

Bases: object <https://docs.python.org/3/builtins/functions.html#object>

TAO Line Search Termination Reasons. Basically the "why did the line search stop" receipts 🧚

Attributes Summary

Attributes Documentation

CONTINUE_SEARCH: int <https://docs.python.org/3/builtins/functions.html#int> = CONTINUE_SEARCH

Constant CONTINUE_SEARCH of type int <https://docs.python.org/3/builtins/functions.html#int>

FAILED_ASCENT: int <https://docs.python.org/3/builtins/functions.html#int> = FAILED_ASCENT

Constant FAILED_ASCENT of type int <https://docs.python.org/3/builtins/functions.html#int>

FAILED_BADPARAMETER: int <https://docs.python.org/3/builtins/functions.html#int> = FAILED_BADPARAMETER

Constant FAILED_BADPARAMETER of type int <https://docs.python.org/3/builtins/functions.html#int>

FAILED_INFORNAN: int <https://docs.python.org/3/builtins/functions.html#int> = FAILED_INFORNAN

Constant FAILED_INFORNAN of type int <https://docs.python.org/3/builtins/functions.html#int>

HALTED_LOWERBOUND: int <https://docs.python.org/3/builtins/functions.html#int> = HALTED_LOWERBOUND

Constant HALTED_LOWERBOUND of type int <https://docs.python.org/3/builtins/functions.html#int>

  • HALTED_MAXFCN: int = HALTED_MAXFCN — fr fr it's just the constant HALTED_MAXFCN, and its type is int 💅
  • HALTED_OTHER: int = HALTED_OTHER — constant HALTED_OTHER, type int, no cap
  • HALTED_RTOL: int = HALTED_RTOL — constant HALTED_RTOL, type int, periodt
  • HALTED_UPPERBOUND: int = HALTED_UPPERBOUND — constant HALTED_UPPERBOUND, type int, iconic
  • HALTED_USER: int = HALTED_USER — constant HALTED_USER, type int, bestie it's an int
  • SUCCESS: int = SUCCESS — constant SUCCESS, type int ✨
  • SUCCESS_USER: int = SUCCESS_USER — constant SUCCESS_USER, type int 🫶
  • __init__()
  • classmethod __new__(*args, **kwargs)

💙 class petsc4py.PETSc.TAOLineSearch.Type 💙

Bases: object

TAO Line Search Types. that's the whole vibe 🌸

✨ Attributes Summary ✨

  • ARMIJO — Object ARMIJO of type str
  • GPCG — Object GPCG of type str
  • IPM — Object IPM of type str
  • MORETHUENTE — Object MORETHUENTE of type str
  • OWARMIJO — Object OWARMIJO of type str
  • UNIT — Object UNIT of type str

📖 Attributes Documentation 📖

  • ARMIJO: str = ARMIJO — Object ARMIJO of type str 🎀
  • GPCG: str = GPCG — Object GPCG of type str 🦋
  • IPM: str = IPM — Object IPM of type str 🌈
  • MORETHUENTE: str = MORETHUENTE — Object MORETHUENTE of type str 🍓
  • OWARMIJO: str = OWARMIJO — Object OWARMIJO of type str ⭐
  • UNIT: str = UNIT — Object UNIT of type str 👑
  • __init__()
  • classmethod __new__(*args, **kwargs)

okay bestie, here's the full rundown of every method this linesearch baddie comes with 💅 — signatures on the left, what they actually do on the right:

  • apply(x, g, s) — Performs a line-search in a given step direction.
  • create([comm]) — Create a TAO linesearch.
  • destroy() — Destroy the linesearch object.
  • getOptionsPrefix() — Return the prefix used for searching for options in the database.
  • getType() — Return the type of the linesearch.
  • setFromOptions() — Configure the linesearch from the options database.
  • setGradient(gradient[, args, kargs]) — Set the gradient evaluation callback.
  • setInitialStepLength(s) — Sets the initial step length of a line search.
  • setObjective(objective[, args, kargs]) — Set the objective function evaluation callback.
  • setObjectiveGradient(objgrad[, args, kargs]) — Set the objective function and gradient evaluation callback.
  • setOptionsPrefix([prefix]) — Set the prefix used for searching for options in the database.
  • setType(ls_type) — Set the type of the linesearch.
  • setUp() — Set up the internal data structures for using the linesearch.
  • useTAORoutine(tao) — Use the objective and gradient evaluation routines from the given Tao object.
  • view([viewer]) — View the linesearch object.

🔥 Methods Documentation 🔥

🦋 apply(x, g, s)

Performs a line-search in a given step direction. Collective. (so like, every single one of your ranks has to show up for this one, no ghosting 🫶)

See also: TaoLineSearchApply — https://petsc.org/release/manualpages/TaoLineSearch/TaoLineSearchApply.html

Source code at petsc4py/PETSc/TAO.pyx:2459 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L2459

Parameters

  • x (Vec)
  • g (Vec)
  • s (Vec)

Return type: tuple[float, float, str]

🎀 create(comm=None)

Create a TAO linesearch. Collective.

Parameters

  • comm — MPI communicator, defaults to Sys.getDefaultComm.

Return type: Self

See also: Sys.getDefaultComm, TaoLineSearchCreate — https://petsc.org/release/manualpages/TaoLineSearch/TaoLineSearchCreate.html

Source code at petsc4py/PETSc/TAO.pyx:2262 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L2262

🌸 destroy()

Destroy the linesearch object. Collective. yes bestie, clean up after yourself, the garbage collector is not your mom 😭

See also: TaoLineSearchDestroy — https://petsc.org/release/manualpages/TaoLineSearch/TaoLineSearchDestroy.html

Source code at petsc4py/PETSc/TAO.pyx:2249 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L2249

Return type: Self

✨ getOptionsPrefix()

Return the prefix used for searching for options in the database. Not collective. (she works solo on this one, main character energy 👑)

See also: Working with PETSc options, setOptionsPrefix, TaoLineSearchGetOptionsPrefix — https://petsc.org/release/manualpages/TaoLineSearch/TaoLineSearchGetOptionsPrefix.html

Source code at petsc4py/PETSc/TAO.pyx:2354 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L2354

Return type: str

🦄 getType()

Return the type of the linesearch. Not collective.

See also: setType, TaoLineSearchGetType — https://petsc.org/release/manualpages/TaoLineSearch/TaoLineSearchGetType.html

Source code at petsc4py/PETSc/TAO.pyx:2302 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L2302

Return type: str

💖 setFromOptions()

Configure the linesearch from the options database. Collective. literally letting the CLI cook 🍳

See also: Working with PETSc options, TaoLineSearchSetFromOptions — https://petsc.org/release/manualpages/TaoLineSearch/TaoLineSearchSetFromOptions.html

Source code at petsc4py/PETSc/TAO.pyx:2316 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L2316

Return type: None

🌈 setGradient(gradient, args=None, kargs=None)

Set the gradient evaluation callback. Logically collective.

Parameters

  • gradient (TAOLSGradientFunction) — The gradient callback.
  • g — The vector to store the gradient.
  • args (tuple[Any, ...] | None) — the positional args you're handing to that callback, bestie.
  • kargs (dict[str, Any] | None) — and the keyword args for the callback. same energy, different bucket 💅

Return type: None

See also: setObjective, setObjectiveGradient, setHessian, TaoLineSearchSetGradientRoutine

Source code at petsc4py/PETSc/TAO.pyx:2393

setInitialStepLength(s)

Sets the initial step length of a line search. Just like, "okay girl, first step, go off" — except the first step length. 🌸

Logically collective, so everyone in the group chat has to be on the same page.

See also: TaoLineSearchSetInitialStepLength

Source code at petsc4py/PETSc/TAO.pyx:2475

Parameters

  • s (float)

Return type: None

setObjective(objective, args=None, kargs=None)

Set the objective function evaluation callback. This is literally the thing your line search is trying to vibe-check — the function it's minimizing. 📉

Logically collective.

Parameters

  • objective (TAOLSObjectiveFunction) — the objective function callback, the main character ✨
  • args (tuple[Any, ...] | None) — positional args for the callback.
  • kargs (dict[str, Any] | None) — keyword args for the callback.

Return type: None

See also: setGradient, setObjectiveGradient, TaoLineSearchSetObjectiveRoutine

Source code at petsc4py/PETSc/TAO.pyx:2368

setObjectiveGradient(objgrad, args=None, kargs=None)

Set the objective function AND gradient evaluation callback. Two jobs, one callback. It's giving efficiency. 💅

Logically collective.

Parameters

  • objgrad (TAOLSObjectiveGradientFunction) — the objective function and gradient callback.
  • g — the vector to store the gradient.
  • args (tuple[Any, ...] | None) — positional args for the callback.
  • kargs (dict[str, Any] | None) — keyword args for the callback.

Return type: None

See also: setObjective, setGradient, setHessian, getObjectiveAndGradient, TaoLineSearchSetObjectiveAndGradientRoutine

Source code at petsc4py/PETSc/TAO.pyx:2420

setOptionsPrefix(prefix=None)

Set the prefix used for searching for options in the database. You know how PETSc options are all namespaced-y? this is you claiming your little corner of the options universe. 🦋

Logically collective.

See also: Working with PETSc options, TaoLineSearchSetOptionsPrefix

Source code at petsc4py/PETSc/TAO.pyx:2340

Parameters

  • prefix (str | None)

Return type: None

setType(ls_type)

Set the type of the linesearch. Pick your flavor, bestie. 🎀

Logically collective.

Parameters

  • ls_type (Type | str) — the type of the solver.

Return type: None

See also: getType, TaoLineSearchSetType

Source code at petsc4py/PETSc/TAO.pyx:2283

setUp()

Set up the internal data structures for using the linesearch. Gotta get yourself together before the real work starts — we call that a pre-game. 🧚

Collective.

See also: TaoLineSearchSetUp

Source code at petsc4py/PETSc/TAO.pyx:2328

Return type: None

useTAORoutine(tao)

Use the objective and gradient evaluation routines from the given Tao object. Basically: "hey, you already set all this up over there, just borrow it." Iconic shortcut. 🔥

Logically collective.

See also: TaoLineSearchUseTaoRoutines

Source code at petsc4py/PETSc/TAO.pyx:2447

Parameters

  • tao (TAO)

Return type: None

view(viewer=None)

View the linesearch object. Peek behind the curtain, see what the line search is actually made of. 👑

Collective.

Parameters

  • viewer (Viewer | None) — a Viewer instance, or None for the default viewer.

Return type: None

See also: TaoLineSearchView

Source code at petsc4py/PETSc/TAO.pyx:2230

__init__()

classmethod __new__(*args, **kwargs)

petsc4py.PETSc.TAOTerm

class petsc4py.PETSc.TAOTerm

Bases: Object

TAO Term. 💜

🦋 ENUMERATIONS 🦋

okay bestie, this is the enum corner of the PETSc house 💖 and this chunk is serving exactly one of them:

  • Type — TAO Term Types. (aka #petsc4py.PETSc.TAOTerm.Type)

💅 petsc4py.PETSc.TAOTerm.Type

class petsc4py.PETSc.TAOTerm.Type

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

TAO Term Types. that's the whole vibe, no cap ✨

🌸 Attributes Summary

📝 Attributes Documentation

and then, the dunder girlies themselves:

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

🛠️ Methods Summary

  • create([comm]) — Create a TAO Term.
  • destroy() — Destroy the term object.
  • getType() — Return the type of the term.
  • setFromOptions() — Configure the term from the options database.
  • setSolutionTemplate(x) — Set the solution vector template.
  • setType(term_type) — Set the type of the term.
  • setUp() — Set up the internal data structures for using the term.
  • view([viewer]) — View the term object.

✨ Methods Documentation

create(comm=None)

Create a TAO Term. 🐣

Collective.

destroy()

Destroy the term object. bye bestie 👋

Collective.

getType()

Return the type of the term. slay, what are you 🔍

Not collective. (so like, every rank already knows, no group chat needed)

setFromOptions()

Configure the term from the options database. it reads the vibes you set and becomes them 💫

Collective.

setSolutionTemplate(x)

Set the solution vector template. give it a little shape to copy later 🫶

Collective.

setType(term_type)

Sets the type of the term, bestie. That's the whole vibe. 💅

Logically collective — meaning everyone in your communicator has gotta be on the same page about this one.

Parameters

  • term_type (Type | str) — the type of the term. Yes you can hand it the enum or just the string, whatever feels right. ✨

Return type

  • None

See also: getType, TaoTermSetType — https://petsc.org/release/manualpages/TaoTerm/TaoTermSetType.html

Source code at petsc4py/PETSc/TAO.pyx:2571 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L2571

setUp()

Sets up the internal data structures so the term can actually, like, function. You know how you can't start your skincare routine until you've laid everything out on the counter? It's giving that. 🧖

Collective.

Return type

  • None

See also: TaoTermSetUp — https://petsc.org/release/manualpages/TaoTerm/TaoTermSetUp.html

Source code at petsc4py/PETSc/TAO.pyx:2616 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L2616

view(viewer=None)

Shows off the term object. Main character moment — let it be perceived. 👑

Collective.

Parameters

  • viewer (Viewer | None) — a Viewer instance, or None if you want the default viewer to do the honors. 🎀

Return type

  • None

See also: TaoTermView — https://petsc.org/release/manualpages/TaoTerm/TaoTermView.html

Source code at petsc4py/PETSc/TAO.pyx:2518 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TAO.pyx#L2518

__init__()

(no extra details, she's just the constructor fr fr)

classmethod __new__(*args, **kwargs)

💖 petsc4py.PETSc.TS 💖

class petsc4py.PETSc.TS

Bases: Object

ODE integrator. Like, it takes your differential equations and ✨steps through time✨. The way that it eats initial value problems for breakfast… obsessed. 😭

TS is described in the PETSc manual — https://petsc.org/release/manual/ts.html

See also:

🌈 Enumerations 🌈

All the lil enum families you can vibe with, iykyk:

  • ARKIMEXType — the ARKIMEX subtype.
  • ConvergedReason — the reason the time step is converging.
  • DIRKType — the DIRK subtype.
  • EquationType — distinguishes among types of explicit and implicit equations.
  • ExactFinalTime — the method for ending time stepping.
  • ProblemType — distinguishes linear and nonlinear problems.
  • RKType — the RK subtype.
  • Type — the time stepping method.

⭐ petsc4py.PETSc.TS.ARKIMEXType ⭐

class petsc4py.PETSc.TS.ARKIMEXType

Bases: object

The ARKIMEX subtype.

✨ Attributes Summary ✨

okay bestie, vibe check time 💖 here's the whole roster of constants hanging out in this namespace. literally every single one of them is an object of type str — yep, the classic Python string, https://docs.python.org/3/builtins/stdtypes.html#str. no cap, that's the whole tea:

🎀 Attributes Documentation 🎀

same squad, but now with the receipts 🧾 type annotations, assigned values, all of it. it's giving "show your work." slay.

💅 __init__()

__init__()

no args, no drama. it does exactly what it says on the tin. periodt.

🦋 __new__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

it's a classmethod, btw — takes *args and **kwargs like a lil flexible icon 👑

👑 petsc4py.PETSc.TS.ConvergedReason

class petsc4py.PETSc.TS.ConvergedReason

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

The reason the time step is converging.

lowkey the most important lil enum in the whole TS situation — when your solver is like "yeah bestie i'm done" or "absolutely not," this is where it tells you why. 🌈

Attributes Summary ✨

okay bestie, vibe check: every single one of these is literally just an int, no cap. Each constant is typed as int (link: https://docs.python.org/3/builtins/functions.html#int), and they're all iconic in their own way. Periodt.

Attributes Documentation 💖

CONVERGED_EVENT

CONVERGED_EVENT: int <https://docs.python.org/3/builtins/functions.html#int> = CONVERGED_EVENT

Constant CONVERGED_EVENT of type int (link: https://docs.python.org/3/builtins/functions.html#int).

CONVERGED_ITERATING

CONVERGED_ITERATING: int <https://docs.python.org/3/builtins/functions.html#int> = CONVERGED_ITERATING

Constant CONVERGED_ITERATING of type int (link: https://docs.python.org/3/builtins/functions.html#int).

CONVERGED_ITS

CONVERGED_ITS: int <https://docs.python.org/3/builtins/functions.html#int> = CONVERGED_ITS

Constant CONVERGED_ITS of type int (link: https://docs.python.org/3/builtins/functions.html#int).

CONVERGED_TIME

CONVERGED_TIME: int <https://docs.python.org/3/builtins/functions.html#int> = CONVERGED_TIME

Constant CONVERGED_TIME of type int (link: https://docs.python.org/3/builtins/functions.html#int).

CONVERGED_USER

CONVERGED_USER: int <https://docs.python.org/3/builtins/functions.html#int> = CONVERGED_USER

Constant CONVERGED_USER of type int (link: https://docs.python.org/3/builtins/functions.html#int).

DIVERGED_NONLINEAR_SOLVE

DIVERGED_NONLINEAR_SOLVE: int <https://docs.python.org/3/builtins/functions.html#int> = DIVERGED_NONLINEAR_SOLVE

Constant DIVERGED_NONLINEAR_SOLVE of type int (link: https://docs.python.org/3/builtins/functions.html#int).

DIVERGED_STEP_REJECTED

DIVERGED_STEP_REJECTED: int <https://docs.python.org/3/builtins/functions.html#int> = DIVERGED_STEP_REJECTED

Constant DIVERGED_STEP_REJECTED of type int (link: https://docs.python.org/3/builtins/functions.html#int).

ITERATING

ITERATING: int <https://docs.python.org/3/builtins/functions.html#int> = ITERATING

Constant ITERATING of type int (link: https://docs.python.org/3/builtins/functions.html#int).

__init__()

__init__()

classmethod __new__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

petsc4py.PETSc.TS.DIRKType 👑

class petsc4py.PETSc.TS.DIRKType

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

The DIRK subtype.

✨ Attributes Summary ✨

okay bestie, vibe check incoming 🦋 this is literally just the full roster of attributes on this thing, no cap. Every single one of them? Same deal — an object whose type is str (you know, the Python string, func fact: https://docs.python.org/3/builtins/stdtypes.html#str). The way that each value is just its own name repeated back at you? iconic behavior, honestly. 👑

📖 Attributes Documentation 📖

and now the receipts, one by one, main character energy for each of them 🌟 same structure every time, so once you get the pattern you're basically done, fr fr.

DIRK657A: str (https://docs.python.org/3/builtins/stdtypes.html#str) = DIRK657A

an object DIRK657A of type str (https://docs.python.org/3/builtins/stdtypes.html#str) 💖

DIRK658A: str (https://docs.python.org/3/builtins/stdtypes.html#str) = DIRK658A

an object DIRK658A of type str (https://docs.python.org/3/builtins/stdtypes.html#str) ✨

DIRK7510SAL: str (https://docs.python.org/3/builtins/stdtypes.html#str) = DIRK7510SAL

an object DIRK7510SAL of type str (https://docs.python.org/3/builtins/stdtypes.html#str) 🎀

DIRK759A: str (https://docs.python.org/3/builtins/stdtypes.html#str) = DIRK759A

an object DIRK759A of type str (https://docs.python.org/3/builtins/stdtypes.html#str) 🌸

DIRK8614A: str (https://docs.python.org/3/builtins/stdtypes.html#str) = DIRK8614A

an object DIRK8614A of type str (https://docs.python.org/3/builtins/stdtypes.html#str) 💅

DIRK8616SAL: str (https://docs.python.org/3/builtins/stdtypes.html#str) = DIRK8616SAL

an object DIRK8616SAL of type str (https://docs.python.org/3/builtins/stdtypes.html#str) 🫶

DIRKES122SAL: str (https://docs.python.org/3/builtins/stdtypes.html#str) = DIRKES122SAL

an object DIRKES122SAL of type str (https://docs.python.org/3/builtins/stdtypes.html#str) 🌈

DIRKES213SAL: str (https://docs.python.org/3/builtins/stdtypes.html#str) = DIRKES213SAL

an object DIRKES213SAL of type str (https://docs.python.org/3/builtins/stdtypes.html#str) ⭐

DIRKES324SAL: str (https://docs.python.org/3/builtins/stdtypes.html#str) = DIRKES324SAL

an object DIRKES324SAL of type str (https://docs.python.org/3/builtins/stdtypes.html#str) 🧚

DIRKES325SAL: str (https://docs.python.org/3/builtins/stdtypes.html#str) = DIRKES325SAL

an object DIRKES325SAL of type str (https://docs.python.org/3/builtins/stdtypes.html#str) 💜

DIRKES648SA: str (https://docs.python.org/3/builtins/stdtypes.html#str) = DIRKES648SA

an object DIRKES648SA of type str (https://docs.python.org/3/builtins/stdtypes.html#str) 🍓

DIRKES7510SA: str (https://docs.python.org/3/builtins/stdtypes.html#str) = DIRKES7510SA

an object DIRKES7510SA of type str (https://docs.python.org/3/builtins/stdtypes.html#str) 🔥

DIRKES8516SAL: str (https://docs.python.org/3/builtins/stdtypes.html#str) = DIRKES8516SAL

an object DIRKES8516SAL of type str (https://docs.python.org/3/builtins/stdtypes.html#str) 👑

DIRKS212: str (https://docs.python.org/3/builtins/stdtypes.html#str) = DIRKS212

an object DIRKS212 of type str (https://docs.python.org/3/builtins/stdtypes.html#str) 🌸

ngl bestie, if you clocked that the pattern never changes, you ate that 💀 every single attribute here is just <name> = <name>, typed str, pointing at the Python string docs. that's the whole tea. ☕

🦋 class petsc4py.PETSc.TS.EquationType

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

okay so this one's whole vibe is: it tells apart the different flavors of explicit and implicit equations. it's giving "label maker for your ODE/DAE problems" ✨

💖 Attributes Summary 💖

🎀 Attributes Documentation 🎀

DAE_IMPLICIT_INDEX1: int (https://docs.python.org/3/builtins/functions.html#int) = DAE_IMPLICIT_INDEX1

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

DAE_IMPLICIT_INDEX2: int (https://docs.python.org/3/builtins/functions.html#int) = DAE_IMPLICIT_INDEX2

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

DAE_IMPLICIT_INDEX3: int (https://docs.python.org/3/builtins/functions.html#int) = DAE_IMPLICIT_INDEX3

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

DAE_IMPLICIT_INDEXHI: int (https://docs.python.org/3/builtins/functions.html#int) = DAE_IMPLICIT_INDEXHI

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

DAE_SEMI_EXPLICIT_INDEX1: int (https://docs.python.org/3/builtins/functions.html#int) = DAE_SEMI_EXPLICIT_INDEX1

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

DAE_SEMI_EXPLICIT_INDEX2: int (https://docs.python.org/3/builtins/functions.html#int) = DAE_SEMI_EXPLICIT_INDEX2

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

DAE_SEMI_EXPLICIT_INDEX3: int (https://docs.python.org/3/builtins/functions.html#int) = DAE_SEMI_EXPLICIT_INDEX3

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

DAE_SEMI_EXPLICIT_INDEXHI: int (https://docs.python.org/3/builtins/functions.html#int) = DAE_SEMI_EXPLICIT_INDEXHI

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

EXPLICIT: int (https://docs.python.org/3/builtins/functions.html#int) = EXPLICIT

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

IMPLICIT: int (https://docs.python.org/3/builtins/functions.html#int) = IMPLICIT

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

  • ODE_EXPLICIT: int = ODE_EXPLICIT — the constant ODE_EXPLICIT, and its type is int (fr, the link https://docs.python.org/3/builtins/functions.html#int is the same one for every single int down here, iykyk 💅).
  • ODE_IMPLICIT: int = ODE_IMPLICIT — the constant ODE_IMPLICIT, type int 💖.
  • UNSPECIFIED: int = UNSPECIFIED — the constant UNSPECIFIED, type int ✨.
  • __init__() — the init, bestie, you know the drill 🎀.
  • classmethod __new__(*args, **kwargs) — a classmethod __new__ that takes *args and **kwargs 🦋.

👑 petsc4py.PETSc.TS.ExactFinalTime

class petsc4py.PETSc.TS.ExactFinalTime

Bases: object (literally https://docs.python.org/3/builtins/functions.html#object, not me being dramatic 🫶)

Okay so this one is all about how you wanna end your time stepping, bestie. The whole method for ending time stepping, that's it, that's the vibe 🌸.

✨ Attributes Summary ✨

💜 Attributes Documentation 💜

🌈 petsc4py.PETSc.TS.ProblemType

class petsc4py.PETSc.TS.ProblemType

Bases: object (again, https://docs.python.org/3/builtins/functions.html#object, we stan 🫶)

Lowkey the whole point of this one? It distinguishes linear and nonlinear problems. That's the assignment, and it ate 💅.

✨ Attributes Summary ✨

💖 Attributes Documentation 💖

🦋 petsc4py.PETSc.TS.RKType

class petsc4py.PETSc.TS.RKType

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

And this one? It's the RK subtype. 👑

✨ Attributes Summary ✨

okay so this is the whole roster of TS.Type attributes, bestie, and every single one of them is just a str. no cap, that's the entire plot twist 💅

🎀 Attributes Documentation 🎀

like, here's each one on its own little pedestal, with its value all spelled out. iconic behaviour honestly ✨

RK1FE: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK1FE

RK1FE: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK1FE

Object RK1FE of type str <https://docs.python.org/3/builtins/stdtypes.html#str> 🌸

RK2A: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK2A

RK2A: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK2A

Object RK2A of type str <https://docs.python.org/3/builtins/stdtypes.html#str> 🌸

RK2B: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK2B

RK2B: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK2B

Object RK2B of type str <https://docs.python.org/3/builtins/stdtypes.html#str> 🌸

RK3: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK3

RK3: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK3

Object RK3 of type str <https://docs.python.org/3/builtins/stdtypes.html#str> 🌸

RK3BS: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK3BS

RK3BS: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK3BS

Object RK3BS of type str <https://docs.python.org/3/builtins/stdtypes.html#str> 🌸

RK4: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK4

RK4: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK4

Object RK4 of type str <https://docs.python.org/3/builtins/stdtypes.html#str> 🌸

RK5BS: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK5BS

RK5BS: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK5BS

Object RK5BS of type str <https://docs.python.org/3/builtins/stdtypes.html#str> 🌸

RK5DP: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK5DP

RK5DP: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK5DP

Object RK5DP of type str <https://docs.python.org/3/builtins/stdtypes.html#str> 🌸

RK5F: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK5F

RK5F: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK5F

Object RK5F of type str <https://docs.python.org/3/builtins/stdtypes.html#str> 🌸

RK6VR: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK6VR

RK6VR: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK6VR

Object RK6VR of type str <https://docs.python.org/3/builtins/stdtypes.html#str> 🌸

RK7VR: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK7VR

RK7VR: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK7VR

Object RK7VR of type str <https://docs.python.org/3/builtins/stdtypes.html#str> 🌸

RK8VR: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK8VR

RK8VR: str <https://docs.python.org/3/builtins/stdtypes.html#str> = RK8VR

Object RK8VR of type str <https://docs.python.org/3/builtins/stdtypes.html#str> 🌸

__init__()

__init__()

classmethod __new__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

🦋 petsc4py.PETSc.TS.Type 🦋

class petsc4py.PETSc.TS.Type

okay so this is the class itself, and she's very demure, very mindful 💅

The time stepping method. ⏱️✨ periodt — that's literally what she is, the whole entire vibe of picking how your solver marches forward in time 🫶

✨ Attributes Summary ✨

okay bestie so this section is a big ol' list of attribute names, and here's the tea: every single one of them is an object whose type is str — that's the Python built-in string type, and the docs for it live at https://docs.python.org/3/builtins/stdtypes.html#str. Fr fr, no cap, they are all that same type. So instead of me typing that identical sentence twenty-four times like a broken bot, just know that every bullet below is "Object <NAME> of type str" and mentally paste that URL after it. Slay. 💖

Anyway here's the whole lineup, in order, no skips, no merges, exactly as listed:

  • ALPHA — an object of type str, named ALPHA, uppercase and unbothered. 💅
  • ALPHA2 — an object of type str. the sequel. the second alpha. the icon, the legend. ✨
  • ARKIMEX — an object of type str, all caps, all vibe. 🎀
  • BASICSYMPLECTIC — an object of type str, and honestly that name is a whole mouthful, but she's valid. 🦋
  • BDF — an object of type str. three letters, maximum presence. 👑
  • BE — an object of type str. just BE. lowercase in spirit, uppercase in fact. 🌸
  • BEULER — an object of type str. different from BE, bestie, don't get it twisted. 🫶
  • CN — an object of type str, short and mysterious, iykyk. 😭
  • CRANK_NICOLSON — an object of type str, and yes it's got a whole underscore in there, she's fancy. 💅
  • DIRK — an object of type str. just a guy's name, sitting in the attribute list, living his truth. 💀
  • DISCGRAD — an object of type str. no space, no problem. 🔥
  • EIMEX — an object of type str, spelling exact, don't you dare "fix" it. ✨
  • EULER — an object of type str. iconic name, iconic type, moving on. ⭐
  • FE — an object of type str. two letters. two. ✨
  • GLEE — an object of type str, and lowkey this one just sounds happy. 🌈
  • GLLE — an object of type str. yes, GLLE, not GLEE. one letter off, completely different attribute, do not confuse them or you will be sad. 🙈
  • MIMEX — an object of type str. 🍓
  • MPRK — an object of type str. 🧚
  • PSEUDO — an object of type str. it's giving mysterious. it's giving fake-but-official. 💜
  • PYTHON — an object of type str. yes, the attribute is literally called PYTHON. we love a self-referential moment. 🐍✨
  • RADAU5 — an object of type str, and that 5 is part of the name, keep it. 💅
  • RK — an object of type str. minimalism. main character energy. 👑
  • ROSW — an object of type str. four letters of pure intrigue. 🎀
  • RUNGE_KUTTA — an object of type str, and she gets a whole underscore and two names, as she deserves. 💖
bestie quick reminder before you scroll on: these are attribute names, exactly as written, and the type is str for every last one of them. every value, every capital letter, every underscore is load-bearing. do not retype them from memory. do not lowercase them. do not "clean them up". copy-paste is self care. 🫶

and we're not done, the table keeps going — do not close this tab, there's more attribute names coming and they're all just as str as these ones. 🌸

✨ Attributes Documentation ✨

okay bestie, this is the part where all those cute little names actually get spelled out for you. every single one of these is a plain old str, no cap — they're basically string constants you hand to PETSc when you're picking how it should step your problem through time. and yes, for each one the value is literally the same as the name, which is honestly so satisfying, it's giving "be your own label" 💅

and then, at the very bottom of this class, the two darlings that make the whole thing go:

__init__()

classmethod __new__(*args, **kwargs)

like, __init__() doing its little setup ritual, and __new__ sitting there as a classmethod catching *args and **kwargs so you can actually construct one of these bad boys without thinking too hard about it. iconic behaviour, honestly. 🎀

🌟 Methods Summary 🌟

okay bestie, here's the full rundown of everything a TS can do 💅 every single method, no skips, no crumbs left behind:

  • adjointReset() — Reset a TS, yeeting any vectors and matrices it allocated 🧹
  • adjointSetSteps(adjoint_steps) — Tell the adjoint solver how many steps it should take backward in time ⏪
  • adjointSetUp() — Set up all the internal data structures so an adjoint solver can be used later 🛠️
  • adjointSolve() — Solve the discrete adjoint problem for an ODE/DAE ✨
  • adjointStep() — Take exactly one time step backward in the adjoint run 👣
  • appendOptionsPrefix(prefix) — Append to the prefix used for all the TS options 🏷️
  • clone() — Return a shallow clone of the TS object (shallow, bestie, don't come for me) 🪞
  • computeI2Function(t, x, xdot, xdotdot, f) — Evaluate the DAE residual in implicit form 🧮
  • computeI2Jacobian(t, x, xdot, xdotdot, v, a, J) — Evaluate the Jacobian of the DAE 📐
  • computeIFunction(t, x, xdot, f[, imex]) — Evaluate the DAE residual written in implicit form 🧮
  • computeIJacobian(t, x, xdot, a, J[, P, imex]) — Evaluate the Jacobian of the DAE 📐
  • computeIJacobianP(t, x, xdot, a, J[, imex]) — Evaluate the Jacobian with respect to parameters 🎛️
  • computeRHSFunction(t, x, f) — Evaluate the right-hand side function ➡️
  • computeRHSFunctionLinear(t, x, f) — Evaluate the right-hand side via the user-provided Jacobian 🔁
  • computeRHSJacobian(t, x, J[, P]) — Compute the Jacobian matrix that has been set with setRHSJacobian 🔧
  • computeRHSJacobianConstant(t, x, J[, P]) — Reuse a Jacobian that is time-independent ⏳
  • computeRHSJacobianP(t, x, J) — Run the user-defined JacobianP function 🏃
  • create([comm]) — Create an empty TS 🐣
  • createPython([context, comm]) — Create an integrator of Python type 🐍
  • createQuadratureTS([forward]) — Create a sub TS that evaluates integrals over time ∫
  • destroy() — Destroy the TS that was created with create 💀
  • getARKIMEXType() — Return the Type.ARKIMEX <#petsc4py.PETSc.TS.Type.ARKIMEX> scheme ✨
  • getAlphaParams() — Return the algorithmic parameters for Type.ALPHA <#petsc4py.PETSc.TS.Type.ALPHA> 🅰️
  • getAppCtx() — Return the application context 📦
  • getConvergedReason() — Return the reason the TS step was stopped 🛑
  • getCostGradients() — Return the cost gradients 📉
  • getCostIntegral() — Return a vector of values of the integral term in the cost functions 🧾
  • getDIRKType() — Return the Type.DIRK <#petsc4py.PETSc.TS.Type.DIRK> scheme 🎯
  • getDM() — Return the DM <#petsc4py
  • ⤴️ (tail end of the previous one, the table wrapped) — the petsc4py.PETSc.DM that's associated with the TS 💫
  • getEquationType() — returns the type of equation your TS is out here solving. what flavour of math are we doing, bestie 🧮
  • getEvaluationSolutions() — hands you back the solutions and the times they got recorded at, as a little duo. no cap, both of them 📝
  • getEvaluationTimes() — just the evaluation points, that's it, that's the whole vibe ✨
  • getI2Function() — returns the vector and the function that computes the residual 🫶
  • getI2Jacobian() — returns the matrices and the function that computes the Jacobian 👑
  • getIFunction() — returns the vector and the function that computes the implicit residual 🌀
  • getIJacobian() — returns the matrices and the function that computes the implicit Jacobian 🌸
  • getKSP() — gives you the KSP (petsc4py.PETSc.KSP) that's associated with the TS 💖
  • getKSPIterations() — the total number of linear iterations the TS has burned through, like a receipt 🧾
  • getMaxSteps() — the maximum number of steps to use, the ceiling, the limit, the "okay that's enough" 🛑
  • getMaxTime() — the maximum (final) time ⏰
  • getMonitor() — returns the monitor 👀
  • getNumEvents() — how many events we got going on 🎟️
  • getOptionsPrefix() — the prefix used for all the TS options, lowkey important 🌈
  • getPostStep() — returns the poststep function, aka the thing that runs after the step 🎀
  • getPreStep() — returns the prestep function, aka the thing that runs before the step 🎀
  • getPrevTime() — the starting time of the previously completed step ⏮️
  • getProblemType() — the type of problem that's about to be solved 🧩
  • getPythonContext() — returns the instance of the class implementing the required Python methods, your lil custom object 🐍
  • getPythonType() — the fully qualified Python name of the class the solver is using 🏷️
  • getQuadratureTS() — returns the sub TS whose whole job is evaluating integrals over time ∫
  • getRHSFunction() — returns the vector where the rhs is stored and the function used to compute it 🌊
  • getRHSJacobian() — returns the Jacobian and the function used to compute them 📐
  • getRKType() — returns the Type.RK scheme (petsc4py.PETSc.TS.Type.RK), iconic 🏃
  • getSNES() — returns the SNES (petsc4py.PETSc.SNES) associated with the TS 🔥
  • getSNESFailures() — the total number of failed SNES (petsc4py.PETSc.SNES) solves inside the TS. we don't talk about those 💀
  • (and there's more coming, hold on bestie)
  • getSNESIterations() — hands you the total number of nonlinear iterations the TS chewed through getting here 🔥
  • getSolution() — the solution at the present timestep. that's it, that's the function ✨
  • getSolution2() — two-for-one: the solution and the time derivative, both at the present timestep 🫶
  • getSolveTime() — the time after a call to solve.
  • getStepLimits() — the minimum and maximum allowed time step sizes, so you know the vibe boundaries 👑
  • getStepNumber() — how many time steps have been completed so far, bestie, count them up 💅
  • getStepRejections() — the total number of rejected steps 💀 yeah. we've all been there.
  • getTheta() — returns the abscissa of the stage in (0, 1] for Type.THETA <#petsc4py.PETSc.TS.Type.THETA>. very specific, very demure ✨
  • getThetaEndpoint() — tells you whether the endpoint variable of Type.THETA <#petsc4py.PETSc.TS.Type.THETA> is being used. yes or no, no gray area 🎀
  • getTime() — the time of the most recently completed step. lowkey the timestamp of your last win ⭐
  • getTimeSpanSolutions() — returns the solutions at the times in the time span. the whole timeline, fr fr 🦋
  • getTimeStep() — the duration of the current timestep.
  • getTolerances() — the tolerances for local truncation error. tune responsibly 💖
  • getType() — returns the TS type. which flavor of solver are we serving today 🌈
  • interpolate(t, u) — interpolate the solution to a given time. yes, we're doing interpolation, it's giving math ✨
  • load(viewer) — load a TS that has been stored in binary with view. it remembers everything 🧠
  • monitor(step, time[, u]) — monitor the solve. optional u if you feel like it, main character energy 👑
  • monitorCancel() — clears all the monitors that have been set. one call, everything gone, periodt 💅
  • removeTrajectory() — removes the internal TS trajectory object. bye bestie 🫶
  • reset() — resets the TS, removing any allocated vectors and matrices. clean slate, fresh start, iconic 🎀
  • restartStep() — flags the solver to restart the next step. do-over, but make it sanctioned 🌸
  • rollBack() — rolls back one time step. hits undo on the timeline 😭
  • setARKIMEXFastSlowSplit(flag) — use ARKIMEX for solving a fast-slow system.
  • setARKIMEXFullyImplicit(flag) — solves both parts of the equation implicitly. no shortcuts, full effort 💪✨
  • setARKIMEXType(ts_type) — sets the type of the Type.ARKIMEX <#petsc4py.PETSc.TS.Type.ARKIMEX> scheme. pick your fighter 🔥
  • setAlphaParams([alpha_m, alpha_f, gamma]) — sets the algorithmic parameters for Type.ALPHA <#petsc4py.PETSc.TS.Type.ALPHA>. the args are optional, the consequences are not 🦋
  • setAlphaRadius(radius) — sets the spectral radius for Type.ALPHA <#petsc4py.PETSc.TS.Type.ALPHA>.
  • setAppCtx(appctx) — sets the application context. your stuff, handed over to the solver, safely stored 🫶
not me knowing exactly which one of these you're about to grep for 💀 it's fine. it's all fine. we move.
  • setConvergedReason(reason) — sets the reason recorded for handling how the solve converged bestie 💅
  • setCostGradients(vl[, vm]) — sets the cost gradients ✨
  • setDIRKType(ts_type) — sets which flavor of Type.DIRK scheme you're running 🎀
  • setDM(dm) — hands over the DM that some nonlinear solvers or preconditioners might wanna use 🦋
  • setEquationType(eqtype) — tells it what kind of equation the TS is out here solving 🌸
  • setErrorIfStepFails([flag]) — flips on straight-up erroring out immediately if no step manages to succeed 😭
  • setEvaluationTimes(tspan) — sets the evaluation points where the solution gets computed and stored, no cap ⭐
  • setEventHandler(direction, terminate, indicator) — sets a function used for detecting events 👀
  • setEventTolerances([tol, vtol]) — sets the tolerances for event zero crossings while you're using an event handler 💜
  • setExactFinalTime(option) — picks the method for computing that final time step, the way it lands matters 🔥
  • setFromOptions() — pulls in all the various TS parameters straight from your user options 🌈
  • setI2Function(function[, f, args, kargs]) — sets the function that computes the 2nd order DAE 🧚
  • setI2Jacobian(jacobian[, J, P, args, kargs]) — sets the function computing the Jacobian of the 2nd order DAE 💖
  • setIFunction(function[, f, args, kargs]) — sets the function representing the DAE you're solving 🫶
  • setIJacobian(jacobian[, J, P, args, kargs]) — sets the function that computes the Jacobian 😌
  • setIJacobianP(jacobian[, J, args, kargs]) — sets the function that computes the Jacobian (the P variant, iykyk) 💅
  • setMaxSNESFailures(n) — sets the max number of SNES solve failures you'll tolerate before it's over 💀
  • setMaxStepRejections(n) — sets the max number of step rejections allowed before a time step just fails 🙈
  • setMaxSteps(max_steps) — sets the maximum number of steps to use 🍓
  • setMaxTime(max_time) — sets the maximum (aka final) time ⏳
  • setMonitor(monitor[, args, kargs]) — adds one more monitor onto the TS, extra eyes on the vibes ✨
  • setOptionsPrefix(prefix) — sets the prefix used for all the TS options 👑
  • setPostStep(poststep[, args, kargs]) — sets a function that gets called at the end of every single time step 🌸
  • setPreStep(prestep[, args, kargs]) — sets a function that gets called at the beginning of every single time step 🦋
  • setProblemType(ptype) — sets the type of problem to be solved 🎀
  • setPythonContext(context) — sets the instance of the class implementing all the required Python methods 💜
  • setPythonType(py_type) — sets the fully qualified Python name of the class you want used 🌟
  • setRHSFunction(function[, f, args, kargs]) — sets the routine for evaluating the function G in U_t = G(t, u) 🔥
  • setRHSJacobian(jacobian[, J, P, args, kargs]) — sets the function that computes the Jacobian of G in U_t = G(U, t). yes bestie, the Big Derivative Energy function 💅
  • setRHSJacobianP(rhsjacobianp[, A, args, kargs]) — sets the function that computes the Jacobian with respect to the parameters. parameters getting their own derivative moment, periodt ✨
  • setRHSSplitIFunction(splitname, function[, ...]) — sets the split implicit functions. 🌸
  • setRHSSplitIJacobian(splitname, jacobian[, ...]) — sets the Jacobian for the split implicit function. it's giving split energy and the Jacobian is the main character 💜
  • setRHSSplitIS(splitname, iss) — sets the index set for the specified split. 🎀
  • setRHSSplitRHSFunction(splitname, function) — sets the split right-hand-side functions. the RHS of it all fr fr 🦋
  • setRKType(ts_type) — sets the type of the Runge-Kutta scheme. lowkey iconic numerics 👑
  • setSaveTrajectory() — enable this to save solutions as an internal TS trajectory. your whole lil journey, archived, no cap 📼
  • setSolution(u) — sets the initial solution vector. where it all begins, bestie 🌈
  • setSolution2(u, v) — sets the initial solution and its time derivative. two for one, we love to see it 💖
  • setStepLimits(hmin, hmax) — sets the minimum and maximum allowed step sizes. boundaries!! we stan a healthy boundary 🫶
  • setStepNumber(step_number) — sets the number of steps completed. keeping count like a responsible queen 🔥
  • setTheta(theta) — sets the abscissa of the stage in (0, 1] for Type.THETA (see #petsc4py.PETSc.TS.Type.THETA). theta said "put me on the map" 🗺️⭐
  • setThetaEndpoint([flag]) — set this to use the endpoint variant of Type.THETA (see #petsc4py.PETSc.TS.Type.THETA). same vibe, endpoint edition 💅
  • setTime(t) — sets the time. ⏰
  • setTimeSpan(tspan) — sets the time span and the time points to evaluate the solution at. the whole timeline AND the lil checkpoints, obsessed 🌸
  • setTimeStep(time_step) — sets the duration of the timestep. how long each step gets to wiggle 🦋
  • setTolerances([rtol, atol]) — sets tolerances for local truncation error when you're using an adaptive controller. adaptive said "I'll behave, but here's my tolerance" 😌✨
  • setType(ts_type) — sets the method to be used as the TS solver. choose your fighter, bestie 👑
  • setUp() — sets up the internal data structures for the TS. get this object ready, it's about to perform 💅
  • solve([u]) — steps the requested number of timesteps. go go go 🏃‍♀️💨
  • step() — takes one step. literally just one, tiny, single step 🎀
  • view([viewer]) — prints the TS object. show us the TS, we wanna see her 🌟

Attributes Summary ✨

okay bestie, here's the whole vibe check on the attributes — these are the properties you can poke at on a TS object 💖

  • appctx — the application context, your lil' stash of whatever you wanna keep around 🎀
  • atol — the absolute tolerance 🎯
  • converged — tells you the TS has converged 💅
  • diverged — tells you the TS has stopped 😭
  • dm — the DM #petsc4py.PETSc.DM 🌸
  • equation_type — the equation type 🧮
  • iterating — tells you the TS is still iterating 🔁
  • ksp — the KSP #petsc4py.PETSc.KSP 👑
  • max_steps — the maximum number of steps 🚶
  • max_time — the maximum time ⏰
  • problem_type — the problem type 🦋
  • reason — the converged reason 🗣️
  • rtol — the relative tolerance 🎯
  • snes — the SNES #petsc4py.PETSc.SNES 🔥
  • step_number — the current step number 🔢
  • time — the current time ⌚
  • time_step — the current time step size 👟
  • vec_sol — the solution vector ✨

📚 Methods Documentation 📚

the actual receipts, fr fr — every method, every arg, no cap 🔥

adjointReset()

Reset a TS, removing any allocated vectors and matrices. like a lil' glow-up cleanse ✨

Collective.

See also:

TSAdjointReset <https://petsc.org/release/manualpages/Sensitivity/TSAdjointReset.html>

Source code at petsc4py/PETSc/TS.pyx:2908 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2908>

Return type

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

adjointSetSteps(adjoint_steps)

Set the number of steps the adjoint solver should take backward in time. going backwards but make it fashion 💅

Logically collective.

Parameters

Return type

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

See also:

TSAdjointSetSteps <https://petsc.org/release/manualpages/Sensitivity/TSAdjointSetSteps.html>

Source code at petsc4py/PETSc/TS.pyx:2854 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2854>

adjointSetUp()

Set up the internal data structures for the later use of an adjoint solver. prepping the backstage area before the main character walks out 🎀

Collective.

See also:

TSAdjointSetUp <https://petsc.org/release/manualpages/Sensitivity/TSAdjointSetUp.html>

Source code at petsc4py/PETSc/TS.pyx:2872 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2872>

Return type

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

adjointSolve()

Solve the discrete adjoint problem for an ODE/DAE. the actual solving moment, slay 🧚

Collective.

See also:

TSAdjointSolve <https://petsc.org/release/manualpages/Sensitivity/TSAdjointSolve.html>

Source code at petsc4py/PETSc/TS.pyx:2884 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2884>

Return type

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

adjointStep()

Step one time step backward in the adjoint run. one lil' step back in time, no DeLorean required 🚗

Collective.

See also:

TSAdjointStep <https://petsc.org/release/manualpages/Sensitivity/TSAdjointStep.html>

Source code at petsc4py/PETSc/TS.pyx:2896 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2896>

Return type

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

appendOptionsPrefix(prefix)

Append to the prefix used for all the TS options. tacking more onto the lil' name tag of every option 🏷️

Logically collective.

Parameters

Return type

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

Notes

A hyphen must not be given at the beginning of the prefix name. ⚠️ like, do NOT start it with a -, bestie, that's not the move.

watch out for that leading hyphen, it's giving "error message" energy 💀

See also:

Working with PETSc options #petsc-options>, TSAppendOptionsPrefix <https://petsc.org/release/manualpages/TS/TSAppendOptionsPrefix.html>

Source code at petsc4py/PETSc/TS.pyx:540 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L540>

clone()

Return a shallow clone of the TS object. it's giving twins, but make it shallow 👯

Collective.

See also:

TSClone <https://petsc.org/release/manualpages/TS/TSClone.html>

Source code at petsc4py/PETSc/TS.pyx:244 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L244>

Return type

TS #petsc4py.PETSc.TS>

computeI2Function(t, x, xdot, xdotdot, f)

Evaluate the DAE residual in implicit form. second derivatives in the chat, and it EATS 📈

Collective.

Parameters

  • t (float <https://docs.python.org/3/builtins/functions.html#float>) -- The current time. ⏰
  • x (Vec #petsc4py.PETSc.Vec>) -- The state vector. 📦
  • xdot (Vec #petsc4py.PETSc.Vec>) -- The time derivative of the state vector. 💨
  • xdotdot (Vec #petsc4py.PETSc.Vec>) -- The second time derivative of the state vector. 💨💨
  • f (Vec #petsc4py.PETSc.Vec>) -- The vector into which the residual is stored. 🗃️

Return type

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

See also:

TSComputeI2Function <https://petsc.org/release/manualpages/TS/TSComputeI2Function.html>

Source code at petsc4py/PETSc/TS.pyx:1143 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1143>

🦋 computeI2Jacobian(t, x, xdot, xdotdot, v, a, J, P=None)

Bestie, this one evaluates the Jacobian of the DAE. 💅

computeI2Jacobian(t, x, xdot, xdotdot, v, a, J, P=None)

Collective. (so like, everybody has to show up for this one, no ghosting the communicator 💀)

If F(t, U, V, A)=0 is the DAE, the required Jacobian is dF/dU + v dF/dV + a dF/dA. ✨ That's the whole vibe right there.

🌸 Parameters

Return type

None — https://docs.python.org/3/builtins/constants.html#None

See also

TSComputeI2Jacobian — https://petsc.org/release/manualpages/TS/TSComputeI2Jacobian.html

Source code at petsc4py/PETSc/TS.pyx:1170 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1170

🎀 computeIFunction(t, x, xdot, f, imex=False)

Evaluate the DAE residual written in implicit form. the way this thing just residuals, honestly. 😭

computeIFunction(t, x, xdot, f, imex=False)

Collective. ✨

Parameters

Return type

None — https://docs.python.org/3/builtins/constants.html#None

See also

TSComputeIFunction — https://petsc.org/release/manualpages/TS/TSComputeIFunction.html

Source code at petsc4py/PETSc/TS.pyx:928 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L928

💜 computeIJacobian(t, x, xdot, a, J, P=None, imex=False)

Evaluate the Jacobian of the DAE. yes queen, we're doing Jacobians again. 💅

computeIJacobian(t, x, xdot, a, J, P=None, imex=False)

Collective. 🌈

If F(t, U, Udot)=0 is the DAE, the required Jacobian is dF/dU + shift*dF/dUdot. periodt. ✨

Parameters

Return type

None — https://docs.python.org/3/builtins/constants.html#None

See also

TSComputeIJacobian — https://petsc.org/release/manualpages/TS/TSComputeIJacobian.html

Source code at petsc4py/PETSc/TS.pyx:958 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L958

🧚 computeIJacobianP(t, x, xdot, a, J, imex=False)

Evaluate the Jacobian with respect to parameters. not the state, bestie, the parameters. totally different girl. 💅

computeIJacobianP(t, x, xdot, a, J, imex=False)

Collective. 🌸

Parameters

Return type

None — https://docs.python.org/3/builtins/constants.html#None

See also

TSComputeIJacobianP — https://petsc.org/release/manualpages/Sensitivity/TSComputeIJacobianP.html

Source code at petsc4py/PETSc/TS.pyx:998 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L998

⭐ computeRHSFunction(t, x, f)

Evaluate the right-hand side function. the RHS said "it's my time to shine" and honestly? it ate. 🔥

computeRHSFunction(t, x, f)

Collective. ✨

Parameters

Return type

None — https://docs.python.org/3/builtins/constants.html#None

See also

TSComputeRHSFunction — https://petsc.org/release/manualpages/TS/TSComputeRHSFunction.html

Source code at petsc4py/PETSc/TS.pyx:675 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L675

🍓 computeRHSFunctionLinear(t, x, f)

Evaluate the right-hand side via the user-provided Jacobian. yeah, it just borrows your Jacobian. iconic behavior honestly. 👑

computeRHSFunctionLinear(t, x, f)

Collective. 🌈

Parameters

Return type

None — https://docs.python.org/3/builtins/constants.html#None

See also

TSComputeRHSFunctionLinear — https://petsc.org/release/manualpages/TS/TSComputeRHSFunctionLinear.html

Source code at petsc4py/PETSc/TS.pyx:697 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L697

💖 computeRHSJacobian(t, x, J, P=None)

Compute the Jacobian matrix that has been set with setRHSJacobian. it literally says it right there. no cap. 🫶

computeRHSJacobian(t, x, J, P=None)

Collective. ✨

Parameters

Return type

None — https://docs.python.org/3/builtins/constants.html#None

See also

TSComputeRHSJacobian — https://petsc.org/release/manualpages/TS/TSComputeRHSJacobian.html

Source code at petsc4py/PETSc/TS.pyx:719 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L719

🎀 computeRHSJacobianConstant(t, x, J, P=None)

Reuse a Jacobian that is time-independent. it said "I'm not changing for anyone" and honestly, respect. 💀✨

computeRHSJacobianConstant(t, x, J, P=None)

Collective. 🌸

Parameters

  • t (float — https://docs.python.org/3/builtins/functions.html#float) — The time at which to evaluate the Jacobian.
  • x (Vec — see #petsc4py.PETSc.Vec) — The state vector.
  • J (Mat — see #petsc4py.PETSc.Mat) — A pointer to the stored Jacobian.
  • P (Mat | None) — an optional pointer to the matrix that gets used to construct the preconditioner 💅

Return type: None

See also: TSComputeRHSJacobianConstant

Source code: petsc4py/PETSc/TS.pyx:745

computeRHSJacobianP(t, x, J)

Runs the user-defined JacobianP function 💖

Collective btw, so everybody's in on it.

Parameters

  • t (float) — the time at which we compute the Jacobian ⏰
  • x (Vec) — the solution at which we compute the Jacobian 🌸
  • J (Mat) — the output Jacobian matrix, bestie, it goes here ✨

Return type: None

See also: TSComputeRHSJacobianP

Source code: petsc4py/PETSc/TS.pyx:2832

create(comm=None)

Makes you an empty TS 🎀

Collective.

So here's the tea: the problem type can then be set with setProblemType, and the type of solver can then be set with setType. Two whole steps, we love a two-step 💅

Parameters

  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm 🦋

Return type: Self

See also: TSCreate

Source code: petsc4py/PETSc/TS.pyx:220

createPython(context=None, comm=None)

Creates an integrator of Python type 🐍✨

Collective.

Parameters

  • context (Any) — an instance of the Python class implementing the required methods 👑
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm 🦋

Return type: Self

See also: PETSc Python ode-integrator type (TODO), setType, setPythonContext, Type.PYTHON

Source code: petsc4py/PETSc/TS.pyx:2922

createQuadratureTS(forward=True)

Creates a sub TS that evaluates integrals over time 🧮✨ lowkey iconic

Collective.

Parameters

  • forward (bool) — enable to evaluate forward in time ⏩

Return type: TS

See also: TSCreateQuadratureTS

Source code: petsc4py/PETSc/TS.pyx:2751

destroy()

Destroys the TS that was created with create 💀 rip bozo, but respectfully

Collective.

See also: TSDestroy

Source code: petsc4py/PETSc/TS.pyx:207

Return type: Self

getARKIMEXType()

Returns the Type.ARKIMEX scheme 🌈

Not collective.

See also: TSARKIMEXGetType

Source code: petsc4py/PETSc/TS.pyx:390

Return type: str

getAlphaParams()

Returns the algorithmic parameters for Type.ALPHA 🎀

Not collective.

See also: TSAlphaGetParams

Source code: petsc4py/PETSc/TS.pyx:3129

Return type: tuple[float, float, float] — yes bestie, three floats, a whole trio ✨

getAppCtx()

Returns the application context 🫶

Source code: petsc4py/PETSc/TS.pyx:590

Return type: Any

getConvergedReason()

Returns the reason the TS step was stopped 🛑 not me checking why it quit

Not collective.

Careful bestie — this can only be called once solve is complete. Don't come for it early, it will not have a reason for you yet 😭

See also: TSGetConvergedReason

Source code: petsc4py/PETSc/TS.pyx:2149

Return type: ConvergedReason

getCostGradients()

Returns the cost gradients 📉✨

Not collective.

See also: setCostGradients, TSGetCostGradients

Source code: petsc4py/PETSc/TS.pyx:2693

Return type: tuple[list[Vec], list[Vec]] — a tuple of two lists of Vecs, okay periodt 💅

getCostIntegral()

Returns a vector of values of the integral term in the cost functions 🧮🦋

Not collective.

See also: TSGetCostIntegral

Source code: petsc4py/PETSc/TS.pyx:2632

Return type: Vec

getDIRKType()

Returns the Type.DIRK scheme 👑

Not collective.

See also: setDIRKType, TSDIRKGetType

Source code: petsc4py/PETSc/TS.pyx:427

Return type: str

getDM()

Returns the DM associated with the TS 🌸

Not collective.

Heads up: this is only valid if nonlinear solvers or preconditioners are used which use the DM. No DM in play? Then this is not the moment, bestie 🙈

See also: TSGetDM

Source code: petsc4py/PETSc/TS.pyx:1648

Return type: DM

getEquationType()

Grab the type of the equation that TS is solving. 👑

Not collective, bestie.

See also: TSGetEquationType <https://petsc.org/release/manualpages/TS/TSGetEquationType.html>

Source code at petsc4py/PETSc/TS.pyx:489 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L489>

Return type: EquationType <#petsc4py.PETSc.TS.EquationType>

getEvaluationSolutions()

Hands you back the solutions, plus the times they were recorded at. two-for-one deal, we love to see it 🫶

Not collective.

See also: setEvaluationTimes

Source code at petsc4py/PETSc/TS.pyx:1539 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1539>

Return type: tuple <https://docs.python.org/3/builtins/stdtypes.html#tuple>[ArrayReal <#petsc4py.typing.ArrayReal>, list <https://docs.python.org/3/builtins/stdtypes.html#list>[Vec <#petsc4py.PETSc.Vec>]]

getEvaluationTimes()

Return the evaluation points. those little checkpoints where we peek at how things are going 📍

Not collective.

See also: setEvaluationTimes

Source code at petsc4py/PETSc/TS.pyx:1523 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1523>

Return type: ArrayReal <#petsc4py.typing.ArrayReal>

getI2Function()

Return the vector and function which computes the residual. the second-order implicit situation, iykyk 💅

Not collective.

See also: TSGetI2Function <https://petsc.org/release/manualpages/TS/TSGetI2Function.html>

Source code at petsc4py/PETSc/TS.pyx:1219 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1219>

Return type: tuple <https://docs.python.org/3/builtins/stdtypes.html#tuple>[Vec <#petsc4py.PETSc.Vec>, TSI2Function <#petsc4py.typing.TSI2Function>]

getI2Jacobian()

Return the matrices and function which computes the Jacobian. matrices, plural — yes she's got more than one for you 🎀

Not collective.

See also: TSGetI2Jacobian <https://petsc.org/release/manualpages/TS/TSGetI2Jacobian.html>

Source code at petsc4py/PETSc/TS.pyx:1235 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1235>

Return type: tuple <https://docs.python.org/3/builtins/stdtypes.html#tuple>[Mat <#petsc4py.PETSc.Mat>, Mat <#petsc4py.PETSc.Mat>, TSI2Jacobian <#petsc4py.typing.TSI2Jacobian>]

getIFunction()

Return the vector and function which computes the implicit residual. implicit girlies rise ✨

Not collective.

See also: TSGetIFunction <https://petsc.org/release/manualpages/TS/TSGetIFunction.html>

Source code at petsc4py/PETSc/TS.pyx:1032 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1032>

Return type: tuple <https://docs.python.org/3/builtins/stdtypes.html#tuple>[Vec <#petsc4py.PETSc.Vec>, TSIFunction <#petsc4py.typing.TSIFunction>]

getIJacobian()

Return the matrices and function which computes the implicit Jacobian. 🧚

Not collective.

See also: TSGetIJacobian <https://petsc.org/release/manualpages/TS/TSGetIJacobian.html>

Source code at petsc4py/PETSc/TS.pyx:1048 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1048>

Return type: tuple <https://docs.python.org/3/builtins/stdtypes.html#tuple>[Mat <#petsc4py.PETSc.Mat>, Mat <#petsc4py.PETSc.Mat>, TSIJacobian <#petsc4py.typing.TSIJacobian>]

getKSP()

Return the KSP <#petsc4py.PETSc.KSP> associated with the TS. your solver's solver, the little guy inside the big guy 🪆

Not collective.

See also: TSGetKSP <https://petsc.org/release/manualpages/TS/TSGetKSP.html>

Source code at petsc4py/PETSc/TS.pyx:1631 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1631>

Return type: KSP <#petsc4py.PETSc.KSP>

getKSPIterations()

Return the total number of linear iterations used by the TS. 👑

Not collective.

heads up: this counter gets reset to zero for each successive call to solve. so don't be out here expecting it to accumulate, bestie 😭

See also: TSGetKSPIterations <https://petsc.org/release/manualpages/TS/TSGetKSPIterations.html>

Source code at petsc4py/PETSc/TS.pyx:1916 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1916>

Return type: int <https://docs.python.org/3/builtins/functions.html#int>

getMaxSteps()

Return the maximum number of steps to use. the step budget, if you will 💅

Not collective.

See also: TSGetMaxSteps <https://petsc.org/release/manualpages/TS/TSGetMaxSteps.html>

Source code at petsc4py/PETSc/TS.pyx:1885 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1885>

Return type: int <https://docs.python.org/3/builtins/functions.html#int>

getMaxTime()

Return the maximum (final) time. the finish line, the end of the runway 🌈

Not collective.

Defaults to 5.

See also: TSGetMaxTime <https://petsc.org/release/manualpages/TS/TSGetMaxTime.html>

Source code at petsc4py/PETSc/TS.pyx:1849 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1849>

Return type: float <https://docs.python.org/3/builtins/functions.html#float>

getMonitor()

Return the monitor. the lil watchers keeping an eye on your run, obsessed with them fr 👀

Not collective.

See also: setMonitor

Source code at petsc4py/PETSc/TS.pyx:2201 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2201>

Return type: list <https://docs.python.org/3/builtins/stdtypes.html#list>[tuple <https://docs.python.org/3/builtins/stdtypes.html#tuple>[TSMonitorFunction <#petsc4py.typing.TSMonitorFunction>, tuple <https://docs.python.org/3/builtins/stdtypes.html#tuple>[Any <https://docs.python.org/3/library/typing.html#typing.Any>, ...], dict <https://docs.python.org/3/builtins/stdtypes.html#dict>[str <https://docs.python.org/3/builtins/stdtypes.html#str>, Any <https://docs.python.org/3/library/typing.html#typing.Any>]]]

getNumEvents()

Return the number of events. how many events are we event-ing, bestie 📅

Logically collective.

See also: TSGetNumEvents <https://petsc.org/release/manualpages/TS/TSGetNumEvents.html>

Source code at petsc4py/PETSc/TS.pyx:2348 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2348>

Return type: int <https://docs.python.org/3/builtins/functions.html#int>

getOptionsPrefix()

Return the prefix used for all the TS options. the little name tag every single option wears 🏷️

Not collective.

See also: TSGetOptionsPrefix <https://petsc.org/release/manualpages/TS/TSGetOptionsPrefix.html>

Source code at petsc4py/PETSc/TS.pyx:526 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L526>

Return type: str <https://docs.python.org/3/builtins/stdtypes.html#str>

getPostStep()

Return the poststep function. the thing that runs after the step, like the little debrief after a long day 💜

Source code at petsc4py/PETSc/TS.pyx:2441 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2441>

Return type: tuple <https://docs.python.org/3/builtins/stdtypes.html#tuple>[TSPostStepFunction <#petsc4py.typing.TSPostStepFunction>, tuple <https://docs.python.org/3/builtins/stdtypes.html#tuple>[Any <https://docs.python.org/3/library/typing.html#typing.Any>, ...] | None <https://docs.python.org/3/builtins/constants.html#None>, dict <https://docs.python.org/3/builtins/stdtypes.html#dict>[str <https://docs.python.org/3/builtins/stdtypes.html#str>, Any <https://docs.python.org/3/library/typing.html#typing.Any>] | None <https://docs.python.org/3/builtins/constants.html#None>]

getPreStep()

Return the prestep function. the warm-up before the actual step, main character energy only 🎀

Not collective.

See also: setPreStep

Source code at petsc4py/PETSc/TS.pyx:2397

Return type — tuple[TSPreStepFunction, tuple[Any, ...] | None, dict[str, Any] | None]

getPrevTime()</p>

Bestie, this one hands you the starting time of the step that just finished. Like, the moment the previous completed step kicked off. Not collective, so every rank's got its own little answer here, no group huddle required. 💖

See also: TSGetPrevTime

Source code at petsc4py/PETSc/TS.pyx:1723

Return type — float

getProblemType()

Tells you what kind of problem we're solving here. Returns the type of problem to be solved. Not collective. 🦋

See also: TSGetProblemType

Source code at petsc4py/PETSc/TS.pyx:458

Return type — ProblemType

getPythonContext()

Okay so when you've got a whole Python class vibing and implementing the required Python methods, this is how you get that instance back. Returns the instance of the class implementing the required Python methods. Not collective. 🌸

See also: PETSc Python ode-integrator type (TODO), setPythonContext

Source code at petsc4py/PETSc/TS.pyx:2959

Return type — Any

getPythonType()

Same energy, different info — this gives you the fully qualified Python name of the class that the solver is using. Fully. Qualified. Name. ✨ Not collective.

See also: PETSc Python ode-integrator type (TODO), setPythonContext, setPythonType, TSPythonGetType

Source code at petsc4py/PETSc/TS.pyx:2988

Return type — str

getQuadratureTS()

Return the sub TS that evaluates integrals over time. It's giving sub-solver main character energy, honestly. 👑

Not collective.

Returns

  • forward (bool) — True if evaluating the integral forward in time
  • qts (TS) — The sub TS

Return type — tuple[bool, TS]

See also: TSGetQuadratureTS

Source code at petsc4py/PETSc/TS.pyx:2772

getRHSFunction()

Returns the vector where the rhs is stored and the function used to compute it. Two-for-one, no cap. 🎀 Not collective.

See also: TSGetRHSFunction

Source code at petsc4py/PETSc/TS.pyx:771

Return type — tuple[Vec, TSRHSFunction]

getRHSJacobian()

Returns the Jacobian and the function used to compute them. Yes babe, them — plural matrices coming at you. 🔥 Not collective.

See also: TSGetRHSJacobian

Source code at petsc4py/PETSc/TS.pyx:787

Return type — tuple[Mat, Mat, TSRHSJacobian]

getRKType()

Returns the Type.RK scheme — you know, the Runge-Kutta flavor currently in play. Which scheme? That scheme. 💅 Not collective.

See also: TSRKGetType

Source code at petsc4py/PETSc/TS.pyx:376

Return type — str

getSNES()

Returns the SNES associated with the TS. Like, the nonlinear solver that's living inside your time stepper. Not collective. ✨

See also: TSGetSNES

Source code at petsc4py/PETSc/TS.pyx:1616

Return type — SNES

getSNESFailures()

Returns the total number of failed SNES solves in the TS. Oof. 😭 The "how many L's did we take" counter. Not collective.

Heads up bestie: this counter is reset to zero for each successive call to solve. So it's a fresh slate every time, periodt.

See also: TSGetSNESFailures

Source code at petsc4py/PETSc/TS.pyx:1990

Return type — int

getSNESIterations()

Returns the total number of nonlinear iterations used by the TS. Counting every single one, she's thorough. 💖 Not collective.

Same vibe as above: this counter is reset to zero for each successive call to solve.

See also: TSGetSNESIterations

Source code at petsc4py/PETSc/TS.pyx:1899

Return type — int

getSolution()

Returns the solution at the present timestep. 🦋 Not collective.

It is valid to call this routine inside the function that you are evaluating in order to move to the new timestep. This vector is not changed until the solution at the next timestep has been calculated.

See also: TSGetSolution

Source code at petsc4py/PETSc/TS.pyx:1429

Return type — Vec

getSolution2()

Returns the solution and the time derivative at the present timestep. Double the info, double the slay. 👑 Not collective.

It is valid to call this routine inside the function that you are evaluating in order to move to the new timestep. These vectors are not changed until the solution at the next timestep has been calculated. (Notice: vectors, plural, because there's two of them.)

See also: TS2GetSolution

Source code at petsc4py/PETSc/TS.pyx:1467

Return type — tuple[Vec, Vec]

getSolveTime()

Returns the time after a call to solve. ⭐ Not collective.

This time corresponds to the final time set with setMaxTime.

See also: TSGetSolveTime — https://petsc.org/release/manualpages/TS/TSGetSolveTime.html

Source code at petsc4py/PETSc/TS.pyx:1737 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1737

Return type: float — https://docs.python.org/3/builtins/functions.html#float

🎀 getStepLimits() 🎀

Hands you back the minimum and maximum allowed time step sizes — like, the floor and the ceiling of how tiny or how chonky your steps are allowed to get. 💅

Not collective. (everyone's doing their own little thing, no group chat needed.)

See also: TSAdaptGetStepLimits — https://petsc.org/release/manualpages/TS/TSAdaptGetStepLimits.html

Source code at petsc4py/PETSc/TS.pyx:2582 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2582

Return type: tuple [float, float] — https://docs.python.org/3/builtins/stdtypes.html#tuple , https://docs.python.org/3/builtins/functions.html#float

✨ getStepNumber() ✨

Returns the number of time steps completed so far. It's giving "how far along are we" energy. 🦋

Not collective.

See also: TSGetStepNumber — https://petsc.org/release/manualpages/TS/TSGetStepNumber.html

Source code at petsc4py/PETSc/TS.pyx:1813 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1813

Return type: int — https://docs.python.org/3/builtins/functions.html#int

💀 getStepRejections() 💀

Returns the total number of rejected steps. The flops, bestie, the flops. 🙈

Not collective.

Heads up: this counter gets reset to zero for each successive call to solve. So it's a fresh count every solve, no carrying over.

See also: TSGetStepRejections — https://petsc.org/release/manualpages/TS/TSGetStepRejections.html

Source code at petsc4py/PETSc/TS.pyx:1955 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1955

Return type: int — https://docs.python.org/3/builtins/functions.html#int

🌸 getTheta() 🌸

Returns the abscissa of the stage, which lives in the range (0, 1], for Type.THETA (petsc4py.PETSc.TS.Type.THETA). 🧚

Not collective.

See also: TSThetaGetTheta — https://petsc.org/release/manualpages/TS/TSThetaGetTheta.html

Source code at petsc4py/PETSc/TS.pyx:3026 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L3026

Return type: float — https://docs.python.org/3/builtins/functions.html#float

⭐ getThetaEndpoint() ⭐

Tells you whether the endpoint variable of Type.THETA (petsc4py.PETSc.TS.Type.THETA) is being used — yes or no, that's it, slay. 🫶

Not collective.

See also: TSThetaGetEndpoint — https://petsc.org/release/manualpages/TS/TSThetaGetEndpoint.html

Source code at petsc4py/PETSc/TS.pyx:3058 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L3058

Return type: bool — https://docs.python.org/3/builtins/functions.html#bool

🦋 getTime() 🦋

Returns the time of the most recently completed step</c>. The way this is your little timestamp bestie… 💖

Not collective.

Lowkey important: when you call this during time step evaluation (like during residual evaluation, or from hooks you set with setPreStep or setPostStep), the time it hands you is at the start of the step, not wherever the eval is currently floating around.

See also: TSGetTime — https://petsc.org/release/manualpages/TS/TSGetTime.html

Source code at petsc4py/PETSc/TS.pyx:1705 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1705

Return type: float — https://docs.python.org/3/builtins/functions.html#float

💅 getTimeSpanSolutions() 💅

Returns the solutions at the times in the time span.

Deprecated. It's giving "we don't do this anymore bestie" — but it's still here, so.

Not collective.

See also: setTimeSpan, setEvaluationTimes, getEvaluationSolutions

Source code at petsc4py/PETSc/TS.pyx:1596 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1596

Return type: list [Vec] — https://docs.python.org/3/builtins/stdtypes.html#list , petsc4py.PETSc.Vec

🌈 getTimeStep() 🌈

Returns the duration of the current timestep — like, how long this step actually spans. No cap. 👑

Not collective.

See also: TSGetTimeStep — https://petsc.org/release/manualpages/TS/TSGetTimeStep.html

Source code at petsc4py/PETSc/TS.pyx:1772 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1772

Return type: float — https://docs.python.org/3/builtins/functions.html#float

🎀 getTolerances() 🎀

Returns the tolerances for local truncation error. This is the "how wrong are we allowed to be" sliders. 😭

Logically collective.

Returns:

Return type: tuple [float, float] — https://docs.python.org/3/builtins/stdtypes.html#tuple , https://docs.python.org/3/builtins/functions.html#float

See also: TSGetTolerances — https://petsc.org/release/manualpages/TS/TSGetTolerances.html

Source code at petsc4py/PETSc/TS.pyx:2072 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2072

✨ getType() ✨

Returns the TS type. Just the name of the vibe your solver is running. 💜

Not collective.

See also: TSGetType — https://petsc.org/release/manualpages/TS/TSGetType.html

Source code at petsc4py/PETSc/TS.pyx:362 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L362

Return type: str — https://docs.python.org/3/builtins/stdtypes.html#str

🧚 interpolate(t, u) 🧚

Interpolates the solution to a given time. Like time-travel but for your state vector, periodt. ⏰

Collective.

Parameters:

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: TSInterpolate — https://petsc.org/release/manualpages/TS/TSInterpolate.html

Source code at petsc4py/PETSc/TS.pyx:2539 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2539

🎀 load(viewer) 🎀

Loads a TS that's been stored in binary with view. It's giving "restore my whole entire situation". 🔥

Collective.

Parameters:

  • viewer (Viewer — petsc4py.PETSc.Viewer) — The visualization context.

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: TSLoad — https://petsc.org/release/manualpages/TS/TSLoad.html

Source code at petsc4py/PETSc/TS.pyx:190 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L190

🌸 monitor(step, time, u=None) 🌸

Monitors the solve — your little running commentary on how it's all going. 👀

Collective.

Parameters:

Return type: None — https://docs.python.org/3/builtins/constants.html#None

See also: TSMonitor — https://petsc.org/release/manualpages/TS/TSMonitor.html

Source code at petsc4py/PETSc/TS.pyx:2228 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2228

🦋 monitorCancel() 🦋

Clears all the monitors that have been set. Wiping the slate, no notes, bye. 💅

Logically collective.

See also: TSMonitorCancel — https://petsc.org/release/manualpages/TS/TSMonitorCancel.html

Source code at petsc4py/PETSc/TS.pyx:2213 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2213

Return type: None — and that was the tail end of the last one, bestie, nothing comes back from it. Periodt. 💅

🦋 removeTrajectory()

Removes the internal TS trajectory object. Gone, deleted, not coming back. ✨

Collective.

See also: TSRemoveTrajectory

Source: petsc4py/PETSc/TS.pyx:2620

Return type: None

🎀 reset()

Resets the TS, which means it straight up removes any allocated vectors and matrices. Fresh start energy, spring cleaning for your solver. 🧼🌈

Collective.

See also: TSReset

Source: petsc4py/PETSc/TS.pyx:2457

Return type: None

🔥 restartStep()

Flags the solver to restart the next step. 🚩

Collective.

Okay so this one's important, listen up 📢 — multistep methods like TSBDF or Runge-Kutta methods with FSAL property require restarting the solver in the event of discontinuities. Those discontinuities may show up because somebody explicitly modified the solution vector (which PETSc attempts to detect and handle on its own, king behaviour 👑) or the problem coefficients (which PETSc is not able to detect, so don't come for it). For the sake of correctness and maximum safety, users are expected to call TSRestart() whenever they introduce discontinuities in callback routines (e.g. prestep and poststep routines, or implicit/rhs function routines with discontinuous source terms).

See also: TSRestartStep

Source: petsc4py/PETSc/TS.pyx:2485

Return type: None

💫 rollBack()

Rolls back one time step. It's giving undo button, but make it physics. ⏪

Collective.

See also: TSRollBack

Source: petsc4py/PETSc/TS.pyx:2508

Return type: None

💜 setARKIMEXFastSlowSplit(flag)

Uses ARKIMEX for solving a fast-slow system. 🏃‍♀️💨🐢

Logically collective.

Parameters:

  • flag (bool) — Set to True for fast-slow partitioned systems.

Return type: None

See also: TSARKIMEXSetType

Source: petsc4py/PETSc/TS.pyx:345

🧚 setARKIMEXFullyImplicit(flag)

Solves both parts of the equation implicitly. No splitting, no shortcuts, all in. 🔥

Logically collective.

Parameters:

  • flag (bool) — Set to True for fully implicit.

Return type: None

See also: TSARKIMEXSetFullyImplicit

Source: petsc4py/PETSc/TS.pyx:327

⭐ setARKIMEXType(ts_type)

Sets the type of the Type.ARKIMEX scheme. Pick your fighter. 🥊

Logically collective.

Parameters:

  • ts_type (ARKIMEXType | str) — The type of Type.ARKIMEX scheme.

Return type: None

Notes:

  • -ts_arkimex_type sets scheme type from the commandline.

See also: TSARKIMEXSetType

Source: petsc4py/PETSc/TS.pyx:304

🌸 setAlphaParams(alpha_m=None, alpha_f=None, gamma=None)

Sets the algorithmic parameters for Type.ALPHA. 🎚️

Logically collective.

Ngl, users should call setAlphaRadius.

Parameters:

  • alpha_m (float | None) — Parameter, leave None to keep current value.
  • alpha_f (float | None) — Parameter, leave None to keep current value.
  • gamma (float | None) — Parameter, leave None to keep current value.

Return type: None

See also: TSAlphaSetParams

Source: petsc4py/PETSc/TS.pyx:3096

🌈 setAlphaRadius(radius)

Sets the spectral radius for Type.ALPHA. 📻

Logically collective.

Parameters:

  • radius (float) — the spectral radius

Return type: None

Notes:

  • -ts_alpha_radius can be used to set this from the commandline.

See also: TSAlphaSetRadius

Source: petsc4py/PETSc/TS.pyx:3074

🍓 setAppCtx(appctx)

Sets the application context. Your lil bag of stuff you want to carry around with you. 👜✨

Not collective.

Parameters:

  • appctx (Any) — The application context.

Return type: None

Source: petsc4py/PETSc/TS.pyx:577

👑 setConvergedReason(reason)

Sets the reason for handling the convergence of solve. Tells everyone why we stopped, so nobody's confused. 💀

Logically collective.

Can only be called when solve is active and reason must contain common value.

Parameters:

  • reason (ConvergedReason) — The reason for convergence.

Return type: None

See also: TSSetConvergedReason

Source: petsc4py/PETSc/TS.pyx:2128

🫶 setCostGradients(vl, vm=None)

Sets the cost gradients. 📉💖

Logically collective.

Parameters:

  • vl (Vec | Sequence[Vec] | None) — the gradients with respect to the initial condition variables ✨ the dimension and the parallel layout of these vectors match the ODE solution vector exactly, no cap 💅
    • vm (Vec | Sequence[Vec] | None) — the gradients with respect to the parameters 🎀 the number of entries in these vectors is the same as the number of parameters, periodt

Return type None

See also: TSSetCostGradients <https://petsc.org/release/manualpages/Sensitivity/TSSetCostGradients.html>

Source code at petsc4py/PETSc/TS.pyx:2647 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2647>

✨ setDIRKType(ts_type) ✨

Sets the type of the Type.DIRK scheme 🌀

Logically collective — the whole squad has to be on the same page, bestie.

Parameters

  • ts_type (DIRKType | str) — the type of Type.DIRK scheme we're going with 💫

Return type None

Notes

  • -ts_dirk_type sets the scheme type straight from the commandline, iykyk 👑

See also: TSDIRKSetType <https://petsc.org/release/manualpages/TS/TSDIRKSetType.html>

Source code at petsc4py/PETSc/TS.pyx:404 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L404>

✨ setDM(dm) ✨

Hands over the DM that some nonlinear solvers or preconditioners might wanna use 🫶

Logically collective.

Parameters

  • dm (DM) — the DM object itself 🎀

Return type None

See also: TSSetDM <https://petsc.org/release/manualpages/TS/TSSetDM.html>

Source code at petsc4py/PETSc/TS.pyx:1668 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1668>

✨ setEquationType(eqtype) ✨

Tells everybody which type of equation the TS is out here solving 🔥

Logically collective.

Parameters

  • eqtype (EquationType) — the type of equation, that's it, that's the whole job 💅

Return type None

See also: TSSetEquationType <https://petsc.org/release/manualpages/TS/TSSetEquationType.html>

Source code at petsc4py/PETSc/TS.pyx:472 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L472>

✨ setErrorIfStepFails(flag=True) ✨

The moment no step succeeds, it errors out. Immediately. Zero chill 😭

Not collective.

Parameters

  • flag (bool) — turn this on to error out if no step succeeds ⚠️

Return type None

Notes

  • use -ts_error_if_step_fails to flip it on from the commandline 🎯

See also: TSSetErrorIfStepFails <https://petsc.org/release/manualpages/TS/TSSetErrorIfStepFails.html>

Source code at petsc4py/PETSc/TS.pyx:2007 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2007>

✨ setEvaluationTimes(tspan) ✨

Sets the evaluation points where the solution gets computed and stored 🧚

Collective.

So here's the vibe: the solution is computed and stored for every single time you ask for. Those times have to be all increasing, and they need to line up with the intermediate points for time integration. You have to use ExactFinalTime.MATCHSTEP to make the last time step in each sub-interval actually match the intermediate points you specified. All those intermediate solutions get saved in a vector array, and you can get at them with getEvaluationSolutions 🎁

Parameters

  • tspan (Sequence[float]) — the sequence of time points 💫 the first element is the initial time and the last element is the final time, the rest are your intermediates

Return type None

Notes

  • -ts_eval_times <t0, ..., tn> sets the time span from the commandline ⭐

See also: getEvaluationTimes, TSGetEvaluationTimes <https://petsc.org/release/manualpages/TS/TSGetEvaluationTimes.html>

Source code at petsc4py/PETSc/TS.pyx:1490 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1490>

✨ setEventHandler(direction, terminate, indicator, postevent=None, args=None, kargs=None) ✨

Drops in the function that goes hunting for events 👀

Logically collective.

Parameters

  • direction (Sequence[int]) — the direction of the zero crossing we're detecting, and it's gotta be one of {-1, 0, +1} 🧭
  • terminate (Sequence[bool]) — flags, one per event, saying whether stepping should be terminated 🛑
  • indicator (TSIndicatorFunction | None) — the function that defines the indicator-functions marking the events 🚩
  • postevent (TSPostEventFunction | None) — the function to run after the event 🎬
  • args (tuple[Any, ...] | None) — extra positional arguments for indicator 🎀
  • kargs (dict[str, Any] | None) — extra keyword arguments for indicator 💅

Return type None

See also: TSSetEventHandler <https://petsc.org/release/manualpages/TS/TSSetEventHandler.html>

Source code at petsc4py/PETSc/TS.pyx:2257 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2257>

✨ setEventTolerances(tol=None, vtol=None) ✨

Sets the tolerances for event zero crossings when you're running with an event handler 🎯

Logically collective.

Heads up bestie: setEventHandler must have already been called before you do this one 🫣

Parameters

  • tol (float | None) — the scalar tolerance, or None if you wanna leave it sitting at the current value 💤
  • vtol (Sequence[float] | None) — bestie, this is a lil sequence of scalar tolerances, one for each event 💅. It's used in preference to tol if it's actually there. Set it to None and it just chills at whatever the current value is. No drama.

Return type — None

Notes — -ts_event_tol can be used to set values from the commandline ✨

See also: TSSetEventTolerances (petsc.org/release/manualpages/TS/TSSetEventTolerances.html)

Source code at petsc4py/PETSc/TS.pyx:2312

setExactFinalTime(option)

Set the method for computing that final time step, fr fr. 🕐

Logically collective — so if you're running in parallel, everybody has to show up to this call, okay? 👑

Parameters

  • option (ExactFinalTime) — the exact final time option.

Return type — None

Notes — -ts_exact_final_time may be used to specify it from the commandline 🎀

See also: TSSetExactFinalTime (petsc.org/release/manualpages/TS/TSSetExactFinalTime.html)

Source code at petsc4py/PETSc/TS.pyx:2106

setFromOptions()

Set all your various TS parameters straight from the user's options. It's giving "one call and you're configured" energy 💖

Collective — everyone in the communicator is in on this, no exceptions.

See also: Working with PETSc options (the #petsc-options vibe), and TSSetFromOptions (petsc.org/release/manualpages/TS/TSSetFromOptions.html)

Source code at petsc4py/PETSc/TS.pyx:563

Return type — None

setI2Function(function, f=None, args=None, kargs=None)

Set the function that computes the 2nd order DAE. We're doing second order now, we're fancy like that 🦋

Logically collective — yep, the whole squad again.

Parameters

  • function (TSI2Function | None) — the right-hand side function.
  • f (Vec | None) — the vector to store values, or None to have it created internally for you (so thoughtful 🫶).
  • args (tuple[Any, ...] | None) — extra positional arguments for function.
  • kargs (dict[str, Any] | None) — extra keyword arguments for function.

Return type — None

See also: TSSetI2Function (petsc.org/release/manualpages/TS/TSSetI2Function.html)

Source code at petsc4py/PETSc/TS.pyx:1064

setI2Jacobian(jacobian, J=None, P=None, args=None, kargs=None)

Set the function that computes the Jacobian of the 2nd order DAE. Yes, the second-order sibling, we love a matched set 🌸

Logically collective — group chat rules apply, everyone agrees on this one.

Parameters

  • jacobian (TSI2Jacobian | None) — the function which computes the Jacobian.
  • J (Mat | None) — the matrix into which the Jacobian gets computed.
  • P (Mat | None) — the optional matrix you use for building a preconditioner.
  • args — extra positional arguments for jacobian.
  • kargs — extra keyword arguments for jacobian.

Return type — None

See also: TSSetI2Jacobian (petsc.org/release/manualpages/TS/TSSetI2Jacobian.html)

Source code at petsc4py/PETSc/TS.pyx:1101

setIFunction(function, f=None, args=None, kargs=None)

Set the function representing the DAE to be solved — the main character of your whole solve 💅

Logically collective.

Parameters

  • function (TSIFunction | None) — the right-hand side function.
  • f (Vec | None) — the vector to store values, or None to have it created internally 💖
  • args (tuple[Any, ...] | None) — additional positional arguments for function.
  • kargs (dict[str, Any] | None) — additional keyword arguments for function.

Return type — None

See also: TSSetIFunction (petsc.org/release/manualpages/TS/TSSetIFunction.html)

Source code at petsc4py/PETSc/TS.pyx:805

setIJacobian(jacobian, J=None, P=None, args=None, kargs=None)

Set the function that computes the Jacobian. 🎀

Logically collective.

Set the function to compute the matrix dF/dU + a*dF/dU_t where F(t, U, U_t) is the function you handed over with setIFunction. That's the whole plot, no notes 😭✨

Parameters

  • jacobian (TSIJacobian | None) — the function which computes the Jacobian.
  • J (Mat | None) — the matrix into which the Jacobian gets computed.
  • P (Mat | None) — the optional matrix for building a preconditioner.
  • args (tuple[Any, ...] | None) — additional positional arguments for jacobian.
  • kargs (dict[str, Any] | None) — additional keyword arguments for jacobian.

Return type — None

💖 See also: TSSetIJacobian — that's the C-side soulmate if you wanna peep the OG.

Source code at petsc4py/PETSc/TS.pyx:842

💅 setIJacobianP(jacobian, J=None, args=None, kargs=None)

okay so this one drops in the function that computes the Jacobian.

Logically collective — so like, everybody's in on it together, no cap.

It sets the function that computes the Jacobian of F with respect to the parameters P where F(Udot, U, t) = G(U, P, t), and it tells PETSc where to stash the matrix. Two birds, one slay. 🦋

Parameters

  • jacobian — the function that computes the Jacobian. ✨
  • J (Mat | None) — the matrix that the Jacobian gets computed into.
  • args (tuple[Any, ...] | None) — extra positional args you wanna hand to jacobian.
  • kargs (dict[str, Any] | None) — extra keyword args for jacobian.

Return type

None

💜 See also: TSSetIJacobianP

Source code at petsc4py/PETSc/TS.pyx:887

🚫 setMaxSNESFailures(n)

Sets the max number of SNES solve failures you're willing to tolerate before it's giving up-city.

Not collective — this is a you-and-your-TS moment, nobody else needs to know. 🙈

Parameters

  • n (int) — the max number of failed nonlinear solver, use -1 for unlimited.

Return type

None

🌸 See also: TSSetMaxSNESFailures

Source code at petsc4py/PETSc/TS.pyx:1972

🛑 setMaxStepRejections(n)

Sets the max number of step rejections before a time step just fails, periodt.

Not collective.

Parameters

  • n (int) — the max number of rejected steps, use -1 for unlimited.

Return type

None

Notes

  • -ts_max_step_rejections can be used to set this from the commandline — cmdline girlies stay winning. 💅
⭐ See also: TSSetMaxStepRejections

Source code at petsc4py/PETSc/TS.pyx:1933

🔢 setMaxSteps(max_steps)

Sets the max number of steps to use. It just caps the whole run, bestie.

Logically collective.

Defaults to 5000.

Parameters

  • max_steps (int) — the max number of steps to use.

Return type

None

👑 See also: TSSetMaxSteps

Source code at petsc4py/PETSc/TS.pyx:1865

⏰ setMaxTime(max_time)

Sets the max (final) time. Like, the finish line. 🏁

Logically collective.

Parameters

  • max_time (float) — the final time

Return type

None

Notes

  • -ts_max_time sets the max time from the commandline
🌈 See also: TSSetMaxTime

Source code at petsc4py/PETSc/TS.pyx:1827

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

Adds one more monitor to the TS — extra eyes on the vibes while it solves. Literally surveillance, but make it math. 🔥

Logically collective.

Parameters

  • monitor (TSMonitorFunction | None) — the custom monitor function.
  • args (tuple[Any, ...] | None) — extra positional args for monitor.
  • kargs (dict[str, Any] | None) — extra keyword args for monitor.

Return type

None

💖 See also: TSMonitorSet

Source code at petsc4py/PETSc/TS.pyx:2167

🏷️ setOptionsPrefix(prefix)

Sets the prefix used for all the TS options. It's the little name tag every option wears so PETSc knows they belong to this TS.

Logically collective.

Parameters

  • prefix (str | None) — the prefix to prepend to all option names.

Return type

None

Notes

⚠️ A hyphen must not be given at the beginning of the prefix name. Do not do it. I'm serious, bestie. 😭
🦋 See also: Working with PETSc options, TSSetOptionsPrefix

Source code at petsc4py/PETSc/TS.pyx:503

🎀 setPostStep(poststep, args=None, kargs=None)

Sets a function that gets called at the end of every single time step. Like a lil outro for each loop. 🎬

Logically collective.

Parameters

  • poststep (TSPostStepFunction | None) — the function to be called at the end of each step.
  • args (tuple[Any, ...] | None) — extra positional args for poststep.
  • kargs (dict[str, Any] | None) — extra keyword args for poststep.

Return type

None

✨ See also: TSSetPostStep

Source code at petsc4py/PETSc/TS.pyx:2409

🌅 setPreStep(prestep, args=None, kargs=None)

Sets a function that gets called at the beginning of every time step. The lil intro, the opening credits, the pregame. 🧚

Logically collective.

Parameters

(and we're cutting right here — the rest of these params are rolling in with the next part, so hold that thought 💅)

  • prestep (TSPreStepFunction | None) — the function bestie wants called at the beginning of each and every step, no skipping ✨
    • args (tuple[Any, ...] | None) — extra positional arguments you wanna hand off to prestep.
    • kargs (dict[str, Any] | None) — extra keyword arguments for prestep, same vibe.

Return type: None

See also: TSSetPreStep — https://petsc.org/release/manualpages/TS/TSSetPreStep.html

Source code at petsc4py/PETSc/TS.pyx:2364 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2364

setProblemType(ptype)

okay so this one tells PETSc what shape of problem you're solving 🎀

Logically collective — everybody's in on it, group-chat style.

Parameters:

  • ptype (ProblemType) — the type of problem, out of all the forms it could be.

Return type: None

See also: TSSetProblemType — https://petsc.org/release/manualpages/TS/TSSetProblemType.html

Source code at petsc4py/PETSc/TS.pyx:441 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L441

setPythonContext(context)

drops in the instance of your class that implements all the required Python methods 💅

Not collective — this one's a solo moment, just you.

See also: PETSc Python ode-integrator type (TODO) — #petsc-python-ts, getPythonContext

Source code at petsc4py/PETSc/TS.pyx:2947 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2947

Parameters:

  • context (Any)

Return type: None

setPythonType(py_type)

hands over the fully qualified Python name of the class you want used 🐍

Collective — everyone participates, fr fr.

See also: PETSc Python ode-integrator type (TODO) — #petsc-python-ts, setPythonContext, getPythonType, TSPythonSetType — https://petsc.org/release/manualpages/TS/TSPythonSetType.html

Source code at petsc4py/PETSc/TS.pyx:2974 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2974

Parameters:

  • py_type (str)

Return type: None

setRHSFunction(function, f=None, args=None, kargs=None)

sets up the routine that evaluates the function G in U_t = G(t, u) 🔥 like, the entire right-hand side of your ODE, iconic.

Logically collective.

Parameters:

  • function (TSRHSFunction | None) — the right-hand side function itself, the star of the show.
  • f (Vec | None) — the vector that the right-hand side gets computed into.
  • args (tuple[Any, ...] | None) — extra positional arguments for function.
  • kargs (dict[str, Any] | None) — extra keyword arguments for function.

Return type: None

See also: TSSetRHSFunction — https://petsc.org/release/manualpages/TS/TSSetRHSFunction.html

Source code at petsc4py/PETSc/TS.pyx:596 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L596

setRHSJacobian(jacobian, J=None, P=None, args=None, kargs=None)

sets the function that computes the Jacobian of G in U_t = G(U, t) — yes bestie, we're doing calculus now 😭💜

Logically collective.

Parameters:

  • jacobian (TSRHSJacobian | None) — the right-hand side function.
  • J (Mat | None) — the matrix the jacobian gets computed into.
  • P (Mat | None) — the matrix the preconditioner gets computed into.
  • args (tuple[Any, ...] | None) — extra positional arguments for jacobian.
  • kargs (dict[str, Any] | None) — extra keyword arguments for jacobian.

Return type: None

See also: TSSetRHSJacobian — https://petsc.org/release/manualpages/TS/TSSetRHSJacobian.html

Source code at petsc4py/PETSc/TS.pyx:633 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L633

setRHSJacobianP(rhsjacobianp, A=None, args=None, kargs=None)

this one sets the function that computes the Jacobian with respect to the parameters — sensitivity girlies know 🍓

Collective.

Parameters:

  • rhsjacobianp (TSRHSJacobianP | None) — the function to compute the Jacobian.
  • A (Mat | None) — the JacobianP matrix.
  • args (tuple[Any, ...] | None) — extra positional arguments for rhsjacobianp.
  • kargs (dict[str, Any] | None) — extra keyword arguments for rhsjacobianp.

Return type: None

See also: TSSetRHSJacobianP — https://petsc.org/release/manualpages/Sensitivity/TSSetRHSJacobianP.html

Source code at petsc4py/PETSc/TS.pyx:2795 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2795

setRHSSplitIFunction(splitname, function, r=None, args=None, kargs=None)

sets up the split implicit functions — splitting? we love a structured moment 🌸

Logically collective.

Parameters:

  • splitname (str) — the name of the split you're targeting, iykyk.

and the rest of the params for setRHSSplitIFunction are giving:

  • splitname (str — https://docs.python.org/3/builtins/stdtypes.html#str) — the name of the split, bestie.
  • function (TSIFunction, see #petsc4py.typing.TSIFunction) — the implicit function evaluation routine, the actual star of the show.
  • r (Vec | None) — vector to hold the residual.
  • args (tuple[Any, ...] | None) — extra positional arguments for function.
  • kargs (dict[str, Any] | None) — extra keyword arguments for function.

Return type: None (https://docs.python.org/3/builtins/constants.html#None) — iconic, returns nothing, does nothing wrong 💅

See also: TSRHSSplitSetIFunction (https://petsc.org/release/manualpages/TS/TSRHSSplitSetIFunction.html)

Source code at petsc4py/PETSc/TS.pyx:1317 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1317)

setRHSSplitIJacobian(splitname, jacobian, J=None, P=None, args=None, kargs=None)

Set the Jacobian for the split implicit function. ✨

Logically collective. (yes bestie, everyone has to show up to this party)

Parameters

  • splitname (str — https://docs.python.org/3/builtins/stdtypes.html#str) — name of the split.
  • jacobian (TSRHSJacobian, see #petsc4py.typing.TSRHSJacobian) — the Jacobian evaluation routine.
  • J (Mat | None) — the matrix that stores the Jacobian entries your jacobian computes.
  • P (Mat | None) — the matrix used to compute the preconditioner (usually the same as J, fr fr).
  • args (tuple[Any, ...] | None) — additional positional arguments for jacobian.
  • kargs (dict[str, Any] | None) — additional keyword arguments for jacobian.

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

See also: TSRHSSplitSetIJacobian (https://petsc.org/release/manualpages/TS/TSRHSSplitSetIJacobian.html)

Source code at petsc4py/PETSc/TS.pyx:1361 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1361)

setRHSSplitIS(splitname, iss)

Set the index set for the specified split. 🎯

Logically collective.

Parameters

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

See also: TSRHSSplitSetIS (https://petsc.org/release/manualpages/TS/TSRHSSplitSetIS.html)

Source code at petsc4py/PETSc/TS.pyx:1252 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1252)

setRHSSplitRHSFunction(splitname, function, r=None, args=None, kargs=None)

Set the split right-hand-side functions. the way that this just… handles your RHS splits for you 🫶

Logically collective.

Parameters

  • splitname (str — https://docs.python.org/3/builtins/stdtypes.html#str) — name of the split.
  • function (TSRHSFunction, see #petsc4py.typing.TSRHSFunction) — the RHS function evaluation routine.
  • r (Vec | None) — vector to hold the residual.
  • args (tuple[Any, ...] | None) — additional positional arguments for function.
  • kargs (dict[str, Any] | None) — additional keyword arguments for function.

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

See also: TSRHSSplitSetRHSFunction (https://petsc.org/release/manualpages/TS/TSRHSSplitSetRHSFunction.html)

Source code at petsc4py/PETSc/TS.pyx:1273 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1273)

setRKType(ts_type)

Set the type of the Runge-Kutta scheme. 🏃‍♀️✨

Logically collective.

Parameters

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

Notes

  • -ts_rk_type sets the scheme type from the commandline. 🎀

See also: TSRKSetType (https://petsc.org/release/manualpages/TS/TSRKSetType.html)

Source code at petsc4py/PETSc/TS.pyx:281 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L281)

setSaveTrajectory()

Enable saving solutions as an internal TS trajectory. 🦋

Collective.

bestie, listen — this routine should be called after all TS options have been set. No setting it up first and then changing your mind, that's not the vibe.

Notes

  • -ts_save_trajectory can be used to save a trajectory to a file. 🔥

See also: TSSetSaveTrajectory (https://petsc.org/release/manualpages/TS/TSSetSaveTrajectory.html)

Source code at petsc4py/PETSc/TS.pyx:2601 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2601)

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

setSolution(u)

Set the initial solution vector. main character setup energy 💜

Logically collective.

Parameters

  • u (Vec, see #petsc4py.PETSc.Vec) — the solution vector.

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

See also: TSSetSolution (https://petsc.org/release/manualpages/TS/TSSetSolution.html)

Source code at petsc4py/PETSc/TS.pyx:1412 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1412)

setSolution2(u, v)

Set the initial solution and its time derivative — a lil two-for-one, obsessed. 🍓

Logically collective.

Parameters

  • u (Vec, see #petsc4py.PETSc.Vec) — the solution vector.
  • v (Vec, see #petsc4py.PETSc.Vec) — the time derivative vector.

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

See also: TS2SetSolution (https://petsc.org/release/manualpages/TS/TS2SetSolution.html)

Source code at petsc4py/PETSc/TS.pyx:1448 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L1448)

💫 setStepLimits(hmin, hmax)

okay so this one pins down the smallest and biggest step sizes your solver is allowed to take ✨

Logically collective.

Parameters

  • hmin (float) — the minimum step size
  • hmax (float) — the maximum step size

Return type: None

See also: TSAdaptSetStepLimits

Source code at petsc4py/PETSc/TS.pyx:2559

🎀 setStepNumber(step_number)

sets how many steps have already been completed, bestie 💅

Logically collective.

fr fr, for most uses of the TS solvers you do not need to explicitly call setStepNumber — the step counter gets updated in solve/step/rollBack like it's supposed to. But power users (yes, that's you, main character) may call this routine to reinitialize timestepping by setting the step counter to zero (and time back to the initial time) so you can solve a similar problem with different initial conditions or parameters. It can also be used to continue timestepping from a previously interrupted run in such a way that TS monitors will be called with an initial nonzero step counter 👑

Parameters

  • step_number (int) — the number of steps completed

Return type: None

See also: TSSetStepNumber

Source code at petsc4py/PETSc/TS.pyx:1786

🌸 setTheta(theta)

sets the abscissa of the stage in (0, 1] for Type.THETA 🦋

Logically collective.

Parameters

  • theta (float) — stage abscissa

Return type: None

Notes

  • -ts_theta_theta can be used to set a value from the commandline.

See also: TSThetaSetTheta

Source code at petsc4py/PETSc/TS.pyx:3004

🌈 setThetaEndpoint(flag=True)

flip this on to use the endpoint variant of Type.THETA — tiny flag, big energy 💖

Logically collective.

Parameters

  • flag — Enable to use the endpoint variant.

Return type: None

See also: TSThetaSetEndpoint

Source code at petsc4py/PETSc/TS.pyx:3040

⏰ setTime(t)

sets the time. that's it. that's the method. iconic minimalism 🫶

Logically collective.

Parameters

  • t (float) — The time.

Return type: None

See also: TSSetTime

Source code at petsc4py/PETSc/TS.pyx:1687

📅 setTimeSpan(tspan)

sets the time span and the time points where you wanna evaluate the solution ✨

Collective.

The solution will be computed and stored for each time requested in the span. The times must be all increasing and correspond to the intermediate points for time integration. ExactFinalTime.MATCHSTEP must be used to make the last time step in each sub-interval match the intermediate points specified — no cap, that's just how it is. The intermediate solutions are saved in a vector array that you can grab with getEvaluationSolutions.

Parameters

  • tspan (Sequence[float]) — The sequence of time points. The first element and the last element are the initial time and the final time respectively.

Return type: None

Notes

  • -ts_time_span <t0, ..., tf> sets the time span from the commandline

See also: setEvaluationTimes, TSSetTimeSpan

Source code at petsc4py/PETSc/TS.pyx:1561

🦋 setTimeStep(time_step)

sets how long the timestep lasts 💅

Logically collective.

Parameters

  • time_step (float) — the duration of the timestep

Return type: None

See also: TSSetTimeStep

Source code at petsc4py/PETSc/TS.pyx:1754

🎯 setTolerances(rtol=None, atol=None)

sets the tolerances for the local truncation error when you're using an adaptive controller ✨ lowkey one of the most important knobs to turn.

Logically collective.

Parameters

  • rtol (float | None) — The relative tolerance, DETERMINE to use the value when the object's type was set, or None to leave the current value.
  • atol (float | None) — The absolute tolerance, DETERMINE to use the value when the object's type was set, or None to leave the current value.

Return type: None

Notes

  • -ts_rtol and -ts_atol may be used to set values from the commandline.

See also: TSSetTolerances

Source code at petsc4py/PETSc/TS.pyx:2029

👑 setType(ts_type)

sets the method that's gonna be used as your TS solver — the big vibe check of your whole timestepping situation 🌈

Collective.

Parameters

  • ts_type (Type | str) — The solver type.

Return type: None

Notes

  • -ts_type sets the method from the commandline

See also: TSSetType

Source code at petsc4py/PETSc/TS.pyx:258

🧚 setUp()

builds out all the internal data structures for the TS. gotta do it before the fun stuff, bestie 🎀

Collective.

See also: TSSetUp

Source code at petsc4py/PETSc/TS.pyx:2445

Return type: None

🔥 solve(u=None)

steps through the requested number of timesteps. this is it. the moment. the main character energy ⭐

Collective.

Parameters

  • u (Vec | None) — The solution vector. Can be None. Like, literally optional, bestie 🫶

Return type None

See also: TSSolve

Source code at petsc4py/PETSc/TS.pyx:2520 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2520)

step() — Take one step 👟

Collective. So all your processes gotta be on the same vibe, no cap.

The preferred interface for the TS solvers is solve. If you need to execute code at the beginning or ending of each step, use setPreStep and setPostStep respectively.

See also: TSStep

Return type: None

Source code at petsc4py/PETSc/TS.pyx:2469 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L2469)

view(viewer=None) — Print the TS object 🖨️

Collective.

Parameters

  • viewer (Viewer | None) — The visualization context. ✨

Return type: None

Notes

  • -ts_view calls TSView at the end of TSStep

See also: TSView

Source code at petsc4py/PETSc/TS.pyx:167 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/TS.pyx#L167)

✨ Attributes Documentation ✨

petsc4py.PETSc.Vec

class petsc4py.PETSc.Vec

Bases: Object

A vector object. 🦋

See also: Vec

Enumerations

  • Option — Vector assembly option.
  • Type — The vector type.

petsc4py.PETSc.Vec.Option

class petsc4py.PETSc.Vec.Option

Bases: object

Vector assembly option.

Attributes Summary

  • IGNORE_NEGATIVE_INDICES — Constant IGNORE_NEGATIVE_INDICES of type int
  • IGNORE_OFF_PROC_ENTRIES — Constant IGNORE_OFF_PROC_ENTRIES of type int

Attributes Documentation

  • IGNORE_NEGATIVE_INDICES: int = IGNORE_NEGATIVE_INDICES — Constant IGNORE_NEGATIVE_INDICES of type int
  • IGNORE_OFF_PROC_ENTRIES: int = IGNORE_OFF_PROC_ENTRIES — Constant IGNORE_OFF_PROC_ENTRIES of type int
  • __init__()
  • classmethod __new__(*args, **kwargs)

petsc4py.PETSc.Vec.Type

class petsc4py.PETSc.Vec.Type

Bases: object

The vector type. 👑

✨ Attributes Summary ✨

okay bestie so this part of the page is literally just a big ol' table of attributes, and I am obsessed with how tidy it is 🎀 so let's vibe-check it together.

Every single one of these is an object of type str — like, ALL of them — and that str type points at the docs over here if you ever wanna go read up: https://docs.python.org/3/builtins/stdtypes.html#str 💅

So the full stack of attributes, no skips, no cuts, no crumbs left behind:

  • CUDA
  • HIP
  • KOKKOS
  • MPI
  • MPICUDA
  • MPIHIP
  • MPIKOKKOS
  • MPIVIENNACL
  • NEST
  • SEQ
  • SEQCUDA
  • SEQHIP
  • SEQKOKKOS
  • SEQVIENNACL
  • SHARED
  • STANDARD
  • VIENNACL

that's seventeen of them fr fr, and every one is the same type: plain old str, same link as above 🦋

💖 Attributes Documentation 💖

okay NOW we get the receipts 🧾 — this section spells each one out individually instead of just teasing you with a table. Same str type for all of them, same link for all of them (https://docs.python.org/3/builtins/stdtypes.html#str), and same energy: it's giving iconic, it's giving consistent 👑

🌸 CUDA: str = CUDA

Object CUDA of type str 🌈

🌸 HIP: str = HIP

Object HIP of type str 🌈

🌸 KOKKOS: str = KOKKOS

Object KOKKOS of type str 🌈

🌸 MPI: str = MPI

Object MPI of type str 🌈

🌸 MPICUDA: str = MPICUDA

Object MPICUDA of type str 🌈

🌸 MPIHIP: str = MPIHIP

Object MPIHIP of type str 🌈

🌸 MPIKOKKOS: str = MPIKOKKOS

Object MPIKOKKOS of type str 🌈

🌸 MPIVIENNACL: str = MPIVIENNACL

Object MPIVIENNACL of type str 🌈

🌸 NEST: str = NEST

Object NEST of type str 🌈

🌸 SEQ: str = SEQ

Object SEQ of type str 🌈

🌸 SEQCUDA: str = SEQCUDA

Object SEQCUDA of type str 🌈

🌸 SEQHIP: str = SEQHIP

Object SEQHIP of type str 🌈

🌸 SEQKOKKOS: str = SEQKOKKOS

Object SEQKOKKOS of type str 🌈

🌸 SEQVIENNACL: str = SEQVIENNACL

Object SEQVIENNACL of type str 🌈

🌸 SHARED: str = SHARED

Object SHARED of type str 🌈

🌸 STANDARD: str = STANDARD

Object STANDARD of type str 🌈

🌸 VIENNACL: str = VIENNACL

Object VIENNACL of type str 🌈

and yeah bestie that's the whole roster — each one a str, each one with its value equal to its own name, each one living its little main character life ✨ the way that every single entry is formatted identically is honestly so soothing, 10/10 no notes 💜

  • SHARED: str = SHARED — bestie this one's type is str and its whole entire personality is SHARED. Object SHARED of type str. That's it, that's the girl 💅 (the Python lore for str lives at https://docs.python.org/3/builtins/stdtypes.html#str if you're nosy like me 🫶)
  • STANDARD: str = STANDARD — and this one? Also a str. Also iconic. Its value is STANDARD, and it is an object of type str. no cap, the consistency is giving ✨ (same str docs energy: https://docs.python.org/3/builtins/stdtypes.html#str)
  • VIENNACL: str = VIENNACL — last of the trio, still a str, still thriving 🌸 this one's value is VIENNACL</pull>... okay wait, VIENNACL 😭 and yes, object VIENNACL of type str. She's got main character energy and the docs to match: https://docs.python.org/3/builtins/stdtypes.html#str 🦋
  • __init__() — the initializer, right there in the listing, taking no arguments as shown. Just vibing in the attribute table like 👑 it's literally the moment the object wakes up and says hi.
  • classmethod __new__(*args, **kwargs) — and here's __new__, marked as a classmethod, accepting *args and **kwargs — the flexible queen 🧚 that's exactly how it's written, don't @ me, don't change a character of it:
classmethod __new__(*args, **kwargs)

she does not do small signatures, she does not do small energy 💖

  • abs() — swaps every entry (xₙ) in the vector for abs|xₙ|. bye bye negative numbers bestie 💅
  • appendOptionsPrefix(prefix) — appends to the prefix that gets used when searching for options in the database. tacking more onto the front of your options lookup 🎀
  • assemble() — assembles the vector. that's it, that's the whole job ✨
  • assemblyBegin() — kicks off an assembling stage of the vector. the opening act 🫶
  • assemblyEnd() — wraps up the assembling stage that got started with assemblyBegin. the closer, the two of them are a set, don't separate them 😭
  • attachDLPackInfo([vec, dltensor]) — attaches tensor info from another vector or from a DLPack tensor. handing your tensor lore over 🦋
  • axpby(alpha, beta, x) — computes and stores y = ɑ·x + β·y. two coefficients, one function, iconic behavior 👑
  • axpy(alpha, x) — computes and stores y = ɑ·x + y. the classic 🔥
  • aypx(alpha, x) — computes and stores y = x + ɑ·y. note the order, it is not the same as axpy, do not play with me 😤
  • bindToCPU(flg) — binds vector operations execution on the CPU. stay on the CPU, babe 🍓
  • boundToCPU() — tells you whether the vector has been bound to the CPU. yes/no, that's all 🌸
  • chop(tol) — sets all vector entries less than some absolute tolerance to zero. tiny numbers? deleted 💀
  • clearDLPackInfo() — clears tensor information. ✨ poof ✨
  • concatenate(vecs) — concatenates vectors into a single vector. gluing the girlies together 🫂
  • conjugate() — conjugates the vector. 🧚
  • copy([result]) — returns a copy of the vector. a whole duplicate, fresh out the box 🎀
  • create([comm]) — creates a vector object. from scratch bestie 🌱
  • createCUDAWithArrays([cpuarray, cudahandle, ...]) — creates a Type.CUDA (petsc4py.PETSc.Vec.Type.CUDA) vector with optional arrays. GPU girlie era 💚
  • createGhost(ghosts, size[, bsize, comm]) — creates a parallel vector with ghost padding on each processor. 👻 no cap
  • createGhostWithArray(ghosts, array[, size, ...]) — creates a parallel vector with ghost padding and provided arrays. 👻 + your own arrays, a whole combo 🌈
  • createHIPWithArrays([cpuarray, hiphandle, ...]) — creates a Type.HIP (petsc4py.PETSc.Vec.Type.HIP) vector with optional arrays. 🔥
  • createLocalVector() — creates a local vector. 🏠 just for you, right here
  • createMPI(size[, bsize, comm]) — creates a parallel Type.MPI (petsc4py.PETSc.Vec.Type.MPI) vector. the classic distributed era 🦋
  • createNest(vecs[, isets, comm]) — creates a Type.NEST (petsc4py.PETSc.Vec.Type.NEST) vector containing multiple nested subvectors. vectors inside vectors, it's giving matryoshka 🪆
  • createSeq(size[, bsize, comm]) — creates a sequential Type.SEQ (petsc4py.PETSc.Vec.Type.SEQ) vector. one process, one vibe 🍑
  • createShared(size[, bsize, comm]) — creates a Type.SHARED (petsc4py.PETSc.Vec.Type.SHARED) vector that uses shared memory. sharing is caring fr fr 💖
  • createViennaCLWithArrays([cpuarray, ...]) — creates a Type.VIENNACL (petsc4py.PETSc.Vec.Type.VIENNACL) vector with optional arrays. ✨
  • createWithArray(array[, size, bsize, comm]) — bestie, this one makes you a brand new vector that's built on top of an array you already have. Optional extras: size, bsize, and comm.
  • createWithDLPack(dltensor[, size, bsize, comm]) — same energy as above but for the DLPack girlies 🌸 it wraps a dltensor and shares the same memory (size, bsize, comm are all optional, periodt).
  • destroy() — bye bye vector 💅 it's gone, it's destroyed, no coming back.
  • dot(vec) — gives you the dot product of your vector with vec. math ate, ngl ✨
  • dotBegin(vec) — kicks off the dot product computation but doesn't finish it. It's giving "we'll get to that later" energy.
  • dotEnd(vec) — the follow-up girl 🎀 it finishes the dot product that you started with dotBegin.
  • dotNorm2(vec) — two-for-one deal: returns the dot product with vec and its squared norm. obsessed 🔥
  • duplicate([array]) — spawns a new vector with the same type. Pass an array if you want it to have data too.
  • equal(vec) — vibe check 🦋 tells you whether this vector is equal to vec.
  • exp() — glow-up time: every entry (xₙ) in the vector gets replaced by exp(xₙ). literally a transformation 💖
  • getArray([readonly]) — hands you the local portion of the vector as a numpy ndarray <https://numpy.org/doc/stable/glossary.html#term-ndarray>. The readonly arg is optional, iykyk.
  • getBlockSize() — returns the block size of the vector. short and sweet, no cap.
  • getBuffer([readonly]) — gives you a buffered view of the local portion of the vector (optional readonly, bestie).
  • getCLContextHandle() — returns the OpenCL context that's associated with the vector. OpenCL girlie behavior 👑
  • getCLMemHandle([mode]) — returns the OpenCL buffer associated with the vector. mode is optional 💫
  • getCLQueueHandle() — returns the OpenCL command queue associated with the vector. the queue is queuing 💅
  • getCUDAHandle([mode]) — returns a pointer to the device buffer. optional mode, don't forget it exists.
  • getDM() — returns the DM <#petsc4py.PETSc.DM> that's associated to the vector. it's giving linked-up energy 🔗
  • getGhostIS() — returns the ghosting indices of a ghost vector 👻 (yes, ghosts are real in PETSc, no cap).
  • getHIPHandle([mode]) — returns a pointer to the device buffer. optional mode, same deal as its CUDA cousin ✨
  • getLGMap() — returns the local-to-global mapping. this is THE mapping bestie, don't lose it 🗺️
  • getLocalSize() — returns the local size of the vector. tiny but mighty info.
  • getLocalVector(lvec[, readonly]) — maps the local portion of the vector into a local vector lvec. optional readonly if you're feeling fancy 🎀
  • getNestSubVecs() — returns all the vectors contained in the nested vector. it's a whole friend group in there 🫶
  • getOffloadMask() — returns the offloading status of the vector. where's it offloading to? this tells you 💜
  • getOptionsPrefix() — returns the prefix used for searching for options in the database. your little name tag for the options database 🏷️
  • getOwnershipRange() — returns the locally owned range of indices as (start, end). this is your land, your range, main character energy 👑
  • getOwnershipRanges() — lowkey the map of who owns what 💖 returns the range of indices owned by each process, so every rank knows its lil slice of the vector.
  • getSize() — the global size of the vector, bestie. the whole thing, not just your rank's bit. ✨
  • getSizes() — plural era 🎀 returns the vector sizes.
  • getSubVector(iset[, subvec]) — hands you a subvector built from the indices you pass in iset, optionally dropping it into subvec. it's giving "just the parts I asked for" 💅
  • getType() — returns the type of the vector. yes ma'am, the whole vibe check of what kind of Vec you're holding. 🦋
  • getValue(index) — one (1) single value, plucked from the vector at index. maximum precision, minimum drama. 🌸
  • getValues(indices[, values]) — same energy but in bulk ✨ pulls values from certain locations in the vector, optionally stuffing them into values.
  • getValuesStagStencil(indices[, values]) — Not implemented. 💀 that's it, that's the whole lore, no cap.
  • ghostUpdate([addv, mode]) — the ghost whisperer 👻 updates ghosted vector entries. takes optional addv and mode because sometimes you wanna add instead of overwrite.
  • ghostUpdateBegin([addv, mode]) — the beginning of the ghost update saga 🫶 starts updating ghosted vector entries, with the same optional addv and mode.
  • ghostUpdateEnd([addv, mode]) — the grand finale 🔥 finishes up those ghosted vector entries that you kicked off with ghostUpdateBegin. optional addv and mode tag along here too.
  • isaxpy(idx, alpha, x) — adds a scaled reduced-space vector onto a subset of the vector. selective glow-up 💜
  • isset(idx, alpha) — takes specific elements of the vector and sets them all to the same value. copy-paste energy, but make it math. ✨
  • load(viewer) — loads a vector. feed it a viewer and watch it eat. 🍓
  • localForm() — returns a context manager for viewing ghost vectors in local form. use it with with, iykyk 💅
  • log() — replaces each entry in the vector by its natural logarithm. math but make it log 🌈 every single one, no skipping.
  • mDot(vecs[, out]) — computes Xᴴ·y where X is an array of vectors. conjugate-transpose dot product moment 👑 optional out for where the answer lands.
  • mDotBegin(vecs, out) — starts a split phase multiple dot product computation. takes vecs and out, both required, bestie. ⭐
  • mDotEnd(vecs, out) — ends that split phase multiple dot product computation. vecs and out, and yes you gotta pair it with the Begin one. 🙈
  • max() — returns the vector entry with the maximum real part and its location. two-for-one, iconic. 🌸
  • maxPointwiseDivide(vec) — returns the maximum of the component-wise absolute value division. yes it's a mouthful, yes it slays 💅
  • maxpy(alphas, vecs) — computes and stores y = Σₙ(ɑₙ·Xₙ) + y, with X an array of vectors. big cumulative accumulation energy 🔥
  • mean() — returns the arithmetic mean of all the entries of the vector. average girlie reporting for duty 🎀
  • min() — returns the vector entry with the minimum real part and its location. the mirror twin of max(), equally iconic. 💖
  • mtDot(vecs[, out]) — computes Xᵀ·y with X an array of vectors. note: transpose, not conjugate-transpose — them's different, bestie 👀 optional out included.
  • mtDotBegin(vecs, out) — starts a split phase transpose multiple dot product computation. 🦋
  • mtDotEnd(vecs, out) — ends that split phase transpose multiple dot product computation. don't leave it hanging, fr fr. ✨
  • norm([norm_type]) — computes the vector norm, bestie. Pass a norm_type if you're feeling specific, or just let it do its thing. 📏✨
  • normBegin([norm_type]) — begins computing the vector norm. It's the "part one" of a two-step moment. 🫶
  • normEnd([norm_type]) — finishes the computations you started with normBegin. Part two, the closer, the finale. 💅
  • normalize() — normalizes the vector by its 2-norm. Unit vibes only. 🎀
  • permute(order[, invert]) — permutes the vector in-place using an ordering you hand it. There's an optional invert, iykyk. 🔄
  • placeArray(array) — sets the local portion of the vector to a provided array. 🧚
  • pointwiseDivide(x, y) — computes and stores the component-wise division of two vectors. Math but make it cute. ➗
  • pointwiseMax(x, y) — computes and stores the component-wise maximum of two vectors. 👑
  • pointwiseMaxAbs(x, y) — computes and stores the component-wise maximum absolute values. So the biggest |·| energy. ⭐
  • pointwiseMin(x, y) — computes and stores the component-wise minimum of two vectors. The little one of the pair. 🌸
  • pointwiseMult(x, y) — computes and stores the component-wise multiplication of two vectors. ✖️
  • reciprocal() — replaces each entry in the vector by its reciprocal. Flip it, invert it, slay it. 🙃
  • resetArray([force]) — resets the vector to use its default array. Optional force for the stubborn ones. 🔁
  • restoreCLMemHandle() — restores a pointer to the OpenCL buffer you got with getCLMemHandle. Don't leave it hanging, bestie. 🫶
  • restoreCUDAHandle(handle[, mode]) — restores a pointer to the device buffer you got with getCUDAHandle. Optional mode of course. 💚
  • restoreHIPHandle(handle[, mode]) — restores a pointer to the device buffer you got with getHIPHandle. Same energy, different GPU. ❤️
  • restoreLocalVector(lvec[, readonly]) — unmaps a local access you got with getLocalVector. Optional readonly flag. 📦
  • restoreSubVector(iset, subvec) — restores a subvector that was extracted using getSubVector. Give it back, respectfully. 🎁
  • scale(alpha) — scales all entries of the vector by alpha. ✨
  • set(alpha) — sets all components of the vector to the same value alpha. Uniformity, periodt. 💅
  • setArray(array) — sets values for the local portion of the vector. 🔥
  • setBlockSize(bsize) — sets the block size of the vector to bsize. 🧱
  • setDM(dm) — associates a DM <#petsc4py.PETSc.DM> to the vector. Besties forever. 🫂
  • setFromOptions() — configures the vector from the options database. Let the options speak. 🗣️
  • setLGMap(lgmap) — sets the local-to-global mapping via lgmap. 🌐
  • setMPIGhost(ghosts) — sets the ghost points for a ghosted vector. Spooky but make it MPI. 👻
  • setNestSubVecs(sx[, idxm]) — sets the component vectors at specified indices in the nested vector. Optional idxm to pick your spots. 🪆
  • setOption(option, flag) — sets option to flag. Simple, iconic, does what it says. ⭐

okay bestie we are STILL vibing in the 🐍 petsc4py Vec method table and it's giving "encyclopedia but make it cute" — here's the rest of the alphabet, no skips, no shortcuts 💅

  • setOptionsPrefix(prefix) — Set the prefix used for searching for options in the database. 🏷️
  • setRandom([random]) — Set all components of the vector to random numbers. 🎲 chaos but make it math
  • setSizes(size[, bsize]) — Set the local and global sizes of the vector. 📏
  • setType(vec_type) — Set the vector type. 🧬
  • setUp() — Set up the internal data structures for using the vector. 🛠️
  • setValue(index, value[, addv]) — Insert or add a single value in the vector. ✍️
  • setValueLocal(index, value[, addv]) — Insert or add a single value in the vector using a local numbering. 📍
  • setValues(indices, values[, addv]) — Insert or add multiple values in the vector. 📦
  • setValuesBlocked(indices, values[, addv]) — Insert or add blocks of values in the vector. 🧱
  • setValuesBlockedLocal(indices, values[, addv]) — Insert or add blocks of values in the vector with a local numbering. 🧱📍
  • setValuesLocal(indices, values[, addv]) — Insert or add multiple values in the vector with a local numbering. 📦📍
  • setValuesStagStencil(indices, values[, addv]) — Not implemented. 💀 just straight up not implemented, bestie, do NOT come for me
  • shift(alpha) — Shift all entries in the vector. 🚚
  • sqrtabs() — Replace each entry (xₙ) in the vector by √|xₙ|. 🍋 absolute value then square root, iconic
  • strideGather(field, vec[, addv]) — Insert component values into a single-component vector. 🧲
  • strideMax(field) — Return the maximum of entries in a subvector. ⬆️
  • strideMin(field) — Return the minimum of entries in a subvector. ⬇️
  • strideNorm(field[, norm_type]) — Return the norm of entries in a subvector. 📐
  • strideScale(field, alpha) — Scale a component of the vector. ⚖️
  • strideScatter(field, vec[, addv]) — Scatter entries into a component of another vector. 🎊
  • strideSum(field) — Sum subvector entries. ➕
  • sum() — Return the sum of all the entries of the vector. 🧮
  • swap(vec) — Swap the content of two vectors. 🔄
  • tDot(vec) — Return the indefinite dot product with vec. 🎯
  • tDotBegin(vec) — Begin computing the indefinite dot product. 🚦
  • tDotEnd(vec) — Finish computing the indefinite dot product initiated with tDotBegin. 🏁
  • toDLPack([mode]) — Return a DLPack PyCapsule https://docs.python.org/3/c-api/capsule.html#c.PyCapsule wrapping the vector data. 🫙 capsule-core fr
  • view([viewer]) — Display the vector. 👀
  • waxpy(alpha, x, y) — Compute and store w = ɑ·x + y. 🔥 the moment we've all been waiting for

and that's the whole Vec roster, no cap — every single one of these is right there for you to call, so go be the main character of your own numerical simulation 💖

…and the method table rounds out with:

  • zeroEntries() — Set all entries in the vector to zero. 🧹 bye bye numbers

🌸 Attributes Summary 🌸

  • array — Alias for array_w.
  • array_r — Read-only ndarray (https://numpy.org/doc/stable/glossary.html#term-ndarray) containing the local portion of the vector.
  • array_w — Writeable ndarray (https://numpy.org/doc/stable/glossary.html#term-ndarray) containing the local portion of the vector.
  • block_size — The block size.
  • buffer — Alias for buffer_w.
  • buffer_r — Read-only buffered view of the local portion of the vector.
  • buffer_w — Writeable buffered view of the local portion of the vector.
  • local_size — The local vector size.
  • owner_range — The locally owned range of indices in the form [low, high).
  • owner_ranges — The range of indices owned by each process.
  • size — The global vector size.
  • sizes — The local and global vector sizes.
bestie these are just the lil windows into your vector okay. <pink>every single one of them is exact</pink>, don't come for me 💅

✨ Methods Documentation ✨

abs()

Replace each entry (xₙ) in the vector by abs|xₙ|.

Logically collective.

See also: VecAbs (https://petsc.org/release/manualpages/Vec/VecAbs.html)

Source code at petsc4py/PETSc/Vec.pyx:2307 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2307)

appendOptionsPrefix(prefix)

Append to the prefix used for searching for options in the database. 🎀

Logically collective.

See also: Working with PETSc options (#petsc-options), setOptionsPrefix, VecAppendOptionsPrefix (https://petsc.org/release/manualpages/Vec/VecAppendOptionsPrefix.html)

Source code at petsc4py/PETSc/Vec.pyx:1028 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1028)

assemble()

Assemble the vector. 🔧

Collective.

See also: assemblyBegin, assemblyEnd

Source code at petsc4py/PETSc/Vec.pyx:3061 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3061)

assemblyBegin()

Begin an assembling stage of the vector.

Collective.

See also: assemblyEnd, VecAssemblyBegin (https://petsc.org/release/manualpages/Vec/VecAssemblyBegin.html)

Source code at petsc4py/PETSc/Vec.pyx:3037 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3037)

assemblyEnd()

Finish the assembling stage initiated with assemblyBegin. the sequel we've all been waiting for

Collective.

See also: assemblyBegin, VecAssemblyEnd (https://petsc.org/release/manualpages/Vec/VecAssemblyEnd.html)

Source code at petsc4py/PETSc/Vec.pyx:3049 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3049)

attachDLPackInfo(vec=None, dltensor=None)

Attach tensor information from another vector or DLPack tensor. 🦋

Logically collective.

This tensor information is required when converting a Vec to a DLPack object.

Notes

This operation does not copy any data from vec or dltensor. it's giving "borrowed, not owned" energy fr

See also: clearDLPackInfo, createWithDLPack

Source code at petsc4py/PETSc/Vec.pyx:643 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L643)

axpby(alpha, beta, x)

Compute and store y = ɑ·x + β·y. 🔥

Logically collective.

  • Parameters:
    • alpha (Scalar (#petsc4py.typing.Scalar)) — First scale factor.
    • beta (Scalar (#petsc4py.typing.Scalar)) — Second scale factor.
    • x (Vec (#petsc4py.PETSc.Vec)) — Input vector, must not be the current vector. ⚠️ no self-referencing bestie
  • Return type: None (https://docs.python.org/3/builtins/constants.html#None)
See also: axpy, aypx, waxpy, VecAXPBY (https://petsc.org/release/manualpages/Vec/VecAXPBY.html)

Source code at petsc4py/PETSc/Vec.pyx:2538 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2538)

axpy(alpha, x)

Compute and store y = ɑ·x + y.

Logically collective.

See also: isaxpy, VecAXPY (https://petsc.org/release/manualpages/Vec/VecAXPY.html)

Source code at petsc4py/PETSc/Vec.pyx:2585 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2585)

closing out the last method's source link from the previous bit 🎀 — Source code at petsc4py/PETSc/Vec.pyx:2474 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2474

💖 aypx(alpha, x)

okay this one is so satisfying, it computes and stores y = x + ɑ·y. like, it just goes in and rewrites y with that whole expression, no notes. 💅

Logically collective.

Parameters

  • alpha (Scalar) — Scale factor. it's the ɑ in the little formula.
  • x (Vec) — Input vector — and read this twice bestie, it must not be the current vector. that's a real constraint, <red>not a vibe suggestion. 💀

Return type: None

See also: axpy, axpby, VecAYPX <https://petsc.org/release/manualpages/Vec/VecAYPX.html>

Source code at petsc4py/PETSc/Vec.pyx:2518 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2518

🧚 bindToCPU(flg)

Bind vector operations execution on the CPU. like, tell it to keep the work on the CPU, periodt. ✨

Logically collective.

See also: boundToCPU, VecBindToCPU <https://petsc.org/release/manualpages/Vec/VecBindToCPU.html>

Source code at petsc4py/PETSc/Vec.pyx:1396 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1396

Parameters

  • flg (bool)

Return type: None

🦋 boundToCPU()

Return whether the vector has been bound to the CPU. it's the little pop quiz version of the one above — it just tells you the answer, no changes made. 😌

Not collective. (so like, not everybody has to be in on this one 🫶)

See also: bindToCPU, VecBoundToCPU <https://petsc.org/release/manualpages/Vec/VecBoundToCPU.html>

Source code at petsc4py/PETSc/Vec.pyx:1409 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1409

Return type: bool

✂️ chop(tol)

Set all vector entries less than some absolute tolerance to zero. tiny numbers? gone. not invited. 🎀

Collective.

Parameters

  • tol (float) — The absolute tolerance below which entries are set to zero. anything under tol gets launched into the void.

Return type: None

See also: VecFilter <https://petsc.org/release/manualpages/Vec/VecFilter.html>

Source code at petsc4py/PETSc/Vec.pyx:1732 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1732

🫧 clearDLPackInfo()

Clear tensor information. that's the whole thing, bestie — it just wipes the tensor info. 🌸

Logically collective.

See also: attachDLPackInfo, createWithDLPack

Source code at petsc4py/PETSc/Vec.pyx:705 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L705

Return type: Self

🔗 classmethod concatenate(vecs)

Concatenate vectors into a single vector. glue them together into one big slay. ✨ it's a classmethod, so you call it on the class itself, iykyk.

Collective.

Parameters

  • vecs (Sequence[Vec]) — The vectors to be concatenated.

Returns

  • vector_out (Vec) — The concatenated vector.
  • indices_list (list of IS) — A list of index sets corresponding to the concatenated components.

Return type: tuple[Vec, list[IS]]

See also: VecConcatenate <https://petsc.org/release/manualpages/Vec/VecConcatenate.html>

Source code at petsc4py/PETSc/Vec.pyx:3552 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3552

🪞 conjugate()

Conjugate the vector. just conjugates it, in place, main character move, no return value. 💅

Logically collective.

See also: VecConjugate <https://petsc.org/release/manualpages/Vec/VecConjugate.html>

Source code at petsc4py/PETSc/Vec.pyx:2319 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2319

Return type: None

📋 copy(result=None)

Return a copy of the vector. an actual copy, not an alias pretending to be one, we don't do that here. 🙅

Logically collective.

This operation copies vector entries to the new vector.

Parameters

  • result (Vec | None) — Target vector for the copy. If None then a new vector is created internally.

Return type: Vec

See also: duplicate, VecCopy <https://petsc.org/release/manualpages/Vec/VecCopy.html>

Source code at petsc4py/PETSc/Vec.pyx:1707 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1707

🌱 create(comm=None)

Create a vector object. the classic. the beginning of the story. ✨

Collective.

After creation the vector type can then be set with setType.

Parameters

  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type: Self

See also: destroy, VecCreate <https://petsc.org/release/manualpages/Vec/VecCreate.html>

Source code at petsc4py/PETSc/Vec.pyx:176 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L176

💜 createCUDAWithArrays(cpuarray=None, cudahandle=None, size=None, bsize=None, comm=None)

Create a Type.CUDA vector with optional arrays. so you can hand it arrays you already have, or let it allocate them for you. generous behaviour honestly. 🫶

Collective.

Parameters

  • cpuarray (Sequence[Scalar] | None) — Host array. Will be lazily allocated if not provided.
  • cudahandle (Any | None) — Address of the array on the GPU. Will be lazily allocated if not provided.
  • size (LayoutSizeSpec | None) — Vector size.
  • bsize (int | None) — Vector block size. If None, bsize = 1.
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type: Self

See also: VecCreateSeqCUDAWithArrays <https://petsc.org/release/manualpages/Vec/VecCreateSeqCUDAWithArrays.html>, VecCreateMPICUDAWithArrays <https://petsc.org/release/manualpages/Vec/VecCreateMPICUDAWithArrays.html>

Source code at petsc4py/PETSc/Vec.pyx:370 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L370

👻 createGhost(ghosts, size, bsize=None, comm=None)

Create a parallel vector with ghost padding on each processor. yes, ghosts. they're the extra slots for the points you don't own but still need to peek at. spooky, useful, iconic. 🌈

Collective.

Parameters

  • ghosts (Sequence[int]) — Global indices of ghost points.
  • size (LayoutSizeSpec) — Vector size.

…and here's the rest of the createGhost deets, bestie, no skips 💅

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

See also: createGhostWithArray, VecCreateGhost <https://petsc.org/release/manualpages/Vec/VecCreateGhost.html>, VecCreateGhostBlock <https://petsc.org/release/manualpages/Vec/VecCreateGhostBlock.html>

Source code at petsc4py/PETSc/Vec.pyx:819 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L819>

createGhostWithArray(ghosts, array, size=None, bsize=None, comm=None)

Okay so this one is the glow-up version: build a parallel vector with ghost padding and hand it your own array right off the bat. 🦋

Collective. (everyone in the communicator shows up for this one, fr fr)

Parameters ✨

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

See also: createGhost, VecCreateGhostWithArray <https://petsc.org/release/manualpages/Vec/VecCreateGhostWithArray.html>, VecCreateGhostBlockWithArray <https://petsc.org/release/manualpages/Vec/VecCreateGhostBlockWithArray.html>

Source code at petsc4py/PETSc/Vec.pyx:861 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L861>

createHIPWithArrays(cpuarray=None, hiphandle=None, size=None, bsize=None, comm=None)

GPU time 👑✨ Build a Type.HIP <#petsc4py.PETSc.Vec.Type.HIP> vector with optional arrays. The arrays are optional, bestie — she'll handle it.

Collective.

Parameters 💖

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

See also: VecCreateSeqHIPWithArrays <https://petsc.org/release/manualpages/Vec/VecCreateSeqHIPWithArrays.html>, VecCreateMPIHIPWithArrays <https://petsc.org/release/manualpages/Vec/VecCreateMPIHIPWithArrays.html>

Source code at petsc4py/PETSc/Vec.pyx:428 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L428>

createLocalVector()

Make yourself a local vector, babe — tiny, local, lowkey iconic. 🎀

Not collective. (this one's just for you, no group chat needed)

Returns: The local vector.

Return type: Vec

See also: getLocalVector, VecCreateLocalVector <https://petsc.org/release/manualpages/Vec/VecCreateLocalVector.html>

Source code at petsc4py/PETSc/Vec.pyx:1204 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1204>

createMPI(size, bsize=None, comm=None)

Your classic parallel Type.MPI <#petsc4py.PETSc.Vec.Type.MPI> vector. The moment. The blueprint. 🌈

Collective.

Parameters ⭐

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

See also: createSeq, VecCreateMPI <https://petsc.org/release/manualpages/Vec/VecCreateMPI.html>

Source code at petsc4py/PETSc/Vec.pyx:283 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L283>

createNest(vecs, isets=None, comm=None)

Nested vectors, like a little matryoshka of subvectors 🪆✨ This builds a Type.NEST <#petsc4py.PETSc.Vec.Type.NEST> vector that contains multiple nested subvectors.

Collective.

Parameters

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

See also: VecCreateNest <https://petsc.org/release/manualpages/Vec/VecCreateNest.html>

Source code at petsc4py/PETSc/Vec.pyx:952 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L952>

createSeq(size, bsize=None, comm=None)

Sequential queen behavior 💅 A Type.SEQ <#petsc4py.PETSc.Vec.Type.SEQ> vector, made the sequential way.

Collective.

Parameters 🌸

Return type — Self

See also:

  • createMPI
  • VecCreateSeq

Source code at petsc4py/PETSc/Vec.pyx:247 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L247

createShared(size, bsize=None, comm=None)

Make a Type.SHARED vector that's living its best life in shared memory 🧠✨

Collective. (everyone in the communicator shows up for this one, no skipping)

Parameters:

  • size (LayoutSizeSpec) — how big the vector is gonna be, fr fr.
  • bsize (int | None) — the block size. If it's None, then bsize = 1. That's the rule, no cap.
  • comm (Comm | None) — MPI communicator. Defaults to Sys.getDefaultComm for this one 🫶

Return type — Self

See also:

  • VecCreateShared

Source code at petsc4py/PETSc/Vec.pyx:918 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L918

createViennaCLWithArrays(cpuarray=None, viennaclvechandle=None, size=None, bsize=None, comm=None)

Make a Type.VIENNACL vector, with optional arrays if you feel like it 💖 (optional = you can totally pass nothing and let it cook)

Collective.

Parameters:

  • cpuarray (Sequence[Scalar] | None) — the host array. If you don't hand one over, it gets lazily allocated later. Chill, it's fine.
  • viennaclvechandle (Any | None) — the address of the array over on the GPU ✨ Also lazily allocated if you're not providing it.
  • size (LayoutSizeSpec | None) — vector size, queen.
  • bsize (int | None) — block size. None means bsize = 1.
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type — Self

See also:

  • VecCreateSeqViennaCLWithArrays
  • VecCreateMPIViennaCLWithArrays

Source code at petsc4py/PETSc/Vec.pyx:486 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L486

createWithArray(array, size=None, bsize=None, comm=None)

Make a vector out of an array you already have lying around 🎀 giving "reuse, recycle, slay".

Collective.

The tea here: this method will build you either a Type.SEQ or a Type.MPI vector, and which one you get depends on how big the communicator is. Surprise mechanic, lowkey.

Parameters:

  • array (Sequence[Scalar]) — the array that's gonna hold the vector's values. It must be at least as large as the local size of the vector, periodt. Don't be out here passing a tiny array 😭
  • size (LayoutSizeSpec | None) — vector size.
  • bsize (int | None) — block size. None → bsize = 1.
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type — Self

See also:

  • VecCreateSeqWithArray
  • VecCreateMPIWithArray

Source code at petsc4py/PETSc/Vec.pyx:319 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L319

createWithDLPack(dltensor, size=None, bsize=None, comm=None)

Wrap a DLPack object in a vector, sharing the exact same memory. Not a copy. The same memory. Besties sharing one brain cell, literally 🧚✨

Collective.

Heads up, bestie: this operation does not touch the storage of the original tensor, so it's meant for contiguous tensors only. And if that tensor is stored in row-major order (hi, PyTorch tensors 👋), the resulting vector will look like an unrolled tensor in row-major order. That's the vibe, that's the deal.

Which flavor of vector you end up with depends on the type of dltensor and how many processes are in the communicator. The options are: Type.SEQ, Type.MPI, Type.SEQCUDA, Type.MPICUDA, Type.SEQHIP, or Type.MPIHIP 🌈

Parameters:

  • dltensor — either an object that has a __dlpack__ method, or an actual DLPack tensor object. Either way, we got you.
  • size (LayoutSizeSpec | None) — vector size.
  • bsize (int | None) — block size. None → bsize = 1.
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type — Self

Source code at petsc4py/PETSc/Vec.pyx:545 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L545

destroy()

Destroy the vector. Bye bestie, you were iconic 👑💀

Collective.

See also:

  • create
  • VecDestroy

Source code at petsc4py/PETSc/Vec.pyx:163 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L163

Return type — Self

dot(vec)

Return the dot product with vec. The math girlies are gonna love this one 🔥

Collective.

For complex numbers, this computes yᴴ·x, where self is x, vec is y, and yᴴ is the conjugate transpose of y. Yes queen, conjugate transpose, we do those here.

If you want the indefinite form instead — yᵀ·x, with yᵀ being the plain transpose of y — go use tDot. Different function, different vibe, don't mix them up 🙈

Parameters:

  • vec (Vec) — the vector you're computing the dot product with.

Return type — Scalar

See also:

  • dotBegin
  • dotEnd
  • tDot
  • VecDot

Source code at petsc4py/PETSc/Vec.pyx:1787 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1787

💫 dotBegin(vec)

okay so this one kicks off the dot product computation. It's giving "set up the shot, take it later" energy.

Collective.

You have to pair this with a call to dotEnd or you're just leaving the group chat on read. ✨

Parameters

  • vec (Vec (#petsc4py.PETSc.Vec)) — the vector you wanna compute the dot product with, bestie.

Return type

See also:

Source code at petsc4py/PETSc/Vec.pyx:1812 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1812

🎀 dotEnd(vec)

finishes the dot product that dotBegin started. the way the two of them are a matched set… iconic. 💅

Collective.

See also:

Source code at petsc4py/PETSc/Vec.pyx:1832 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1832

Parameters

  • vec (Vec (#petsc4py.PETSc.Vec))

Return type

  • Scalar (#petsc4py.typing.Scalar)

🦋 dotNorm2(vec)

literally hands you two things at once: the dot product with vec and its squared norm. multi-tasking queen. 👑

Collective.

See also:

Source code at petsc4py/PETSc/Vec.pyx:2151 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2151

Parameters

  • vec (Vec (#petsc4py.PETSc.Vec))

Return type

✨ duplicate(array=None)

makes a brand new vector of the same type, and if you want, it'll slap some data in there too. glow-up edition.

Collective.

Parameters

Return type

  • Vec (#petsc4py.PETSc.Vec)

See also:

Source code at petsc4py/PETSc/Vec.pyx:1682 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1682

🌸 equal(vec)

vibe check 🫶 — returns whether this vector is equal to another one. simple as that, no cap.

Collective.

Parameters

  • vec (Vec (#petsc4py.PETSc.Vec)) — the vector you're comparing against.

Return type

See also:

Source code at petsc4py/PETSc/Vec.pyx:1768 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1768

🧚 exp()

swaps every single entry (xₙ) in the vector for exp(xₙ). it's giving math but make it pop. 🔥

Logically collective.

See also:

Source code at petsc4py/PETSc/Vec.pyx:2271 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2271

Return type

💖 getArray(readonly=False)

gives you back the local portion of the vector as an ndarray (https://numpy.org/doc/stable/glossary.html#term-ndarray). yes bestie, actual numpy realness.

Logically collective.

Parameters

Return type

  • ArrayScalar (#petsc4py.typing.ArrayScalar)

See also:

  • setArray, getBuffer

Source code at petsc4py/PETSc/Vec.pyx:1313 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1313

⭐ getBlockSize()

returns the block size of the vector. that's it, that's the whole personality.

Not collective.

See also:

Source code at petsc4py/PETSc/Vec.pyx:1149 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1149

Return type

🌈 getBuffer(readonly=False)

hands you a buffered view of the local portion of the vector. lowkey one of the most useful lil things in here. ✨

Logically collective.

Parameters

Returns

Return type

Examples

accessing the data with a context manager:

>>> vec = PETSc.Vec().createWithArray([1, 2, 3])
>>> with vec.getBuffer() as arr:
...     arr
array([1., 2., 3.])

converting the buffer to an ndarray (https://numpy.org/doc/stable/glossary.html#term-ndarray):

>>> buf = PETSc.Vec().createWithArray([1, 2, 3]).getBuffer()
>>> np.asarray(buf)
array([1., 2., 3.])

See also:

  • getArray

Source code at petsc4py/PETSc/Vec.pyx:1270 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1270

💜 getCLContextHandle()

returns the OpenCL context that's linked up with the vector. very niche, very demure.

Not collective.

Returns

  • a pointer to the underlying CL context. you can use this with pyopencl through pyopencl.Context.from_int_ptr.

Return type

See also:

Source code at petsc4py/PETSc/Vec.pyx:1593 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1593

🔥 getCLMemHandle(mode='rw')

returns the OpenCL buffer that's tied to the vector.

Not collective.

Returns

  • a pointer to the device buffer. this works with pyopencl through pyopencl.Context.from_int_ptr.

Return type

Parameters

  • mode (AccessModeSpec (#petsc4py.typing.AccessModeSpec))

Notes

heads up bestie ⚠️ — this method may incur a host-to-device copy if the device data is out of date and mode is "r" or "rw". not a drill.

See also:

Source code at petsc4py/PETSc/Vec.pyx:1633 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1633

🍓 getCLQueueHandle()

returns the OpenCL command queue that's associated with the vector. we love a coordinated setup. 🎀

Not collective.

Returns

  • a pointer to the underlying CL command queue. use it with pyopencl through pyopencl.Context.from_int_ptr.

Return type

See also:

Source code at petsc4py/PETSc/Vec.pyx:1613 — that's the closing receipt for the one above bestie, and now we're back in the method buffet 💖

💅 getCUDAHandle(mode='rw')

Hands you back a pointer to the device buffer, no cap ✨

Not collective — everybody does their own thing here.

The pointer you get? You gotta give it back with restoreCUDAHandle using the same access mode, fr fr. Don't ghost it.

Returns: CUDA device pointer.

Return type: typing.Any

Parameters:

  • mode (AccessModeSpec)

Notes

Heads up bestie — this method may incur a host-to-device copy if the device data is out of date and mode is "r" or "rw". It's giving sneaky. 🫣

See also: restoreCUDAHandle, VecCUDAGetArray, VecCUDAGetArrayRead, VecCUDAGetArrayWrite

Source code at petsc4py/PETSc/Vec.pyx:1423

🎀 getDM()

Returns the DM associated to the vector. It's like finding out who your vector's plus-one is 💫

Not collective.

See also: setDM, VecGetDM

Source code at petsc4py/PETSc/Vec.pyx:3533

Return type: DM

👻 getGhostIS()

Returns the ghosting indices of a ghost vector. Yes it's literally called ghost, very spooky season of it 🌸

Collective — the whole squad is involved on this one.

Returns: Indices of ghosts.

Return type: IS

See also: VecGhostGetGhostIS

Source code at petsc4py/PETSc/Vec.pyx:3399

🦋 getHIPHandle(mode='rw')

Same energy as the CUDA one but for HIP — returns a pointer to the device buffer 💜

Not collective.

You must release the returned pointer with restoreHIPHandle using the same access mode. Release it, don't be a menace. 😤

Returns: HIP device pointer.

Return type: typing.Any

Parameters:

  • mode (AccessModeSpec)

Notes

Just like its CUDA sibling, this method may incur a host-to-device copy if the device data is out of date and mode is "r" or "rw".

See also: restoreHIPHandle, VecHIPGetArray, VecHIPGetArrayRead, VecHIPGetArrayWrite

Source code at petsc4py/PETSc/Vec.pyx:1495

🌈 getLGMap()

Returns the local-to-global mapping. Transporting you from small local vibes to the big global picture, iconic 🔥

Not collective.

See also: setLGMap, VecGetLocalToGlobalMapping

Source code at petsc4py/PETSc/Vec.pyx:2913

Return type: LGMap

⭐ getLocalSize()

Returns the local size of the vector — how many entries this process is holding, main character energy 👑

Not collective.

See also: setSizes, getSize, VecGetLocalSize

Source code at petsc4py/PETSc/Vec.pyx:1107

Return type: int

🧚 getLocalVector(lvec, readonly=False)

Maps the local portion of the vector into a local vector. Like a little window into your slice of the data 🍓

Logically collective.

Parameters:

  • lvec (Vec) — The local vector obtained from createLocalVector.
  • readonly (bool) — Request read-only access.

Return type: None

See also: createLocalVector, restoreLocalVector, VecGetLocalVectorRead, VecGetLocalVector

Source code at petsc4py/PETSc/Vec.pyx:1223

🪺 getNestSubVecs()

Returns all the vectors contained in the nested vector. It's a mom vector with her babies 💕

Not collective.

See also: setNestSubVecs, VecNestGetSubVecs

Source code at petsc4py/PETSc/Vec.pyx:3465

Return type: list[Vec]

💀 getOffloadMask()

Returns the offloading status of the vector. Where is the data living right now, bestie? CPU? GPU? Both? Vibe check time 👀

Not collective.

Common return values include:

  • 1: PETSC_OFFLOAD_CPU — CPU has valid entries
  • 2: PETSC_OFFLOAD_GPU — GPU has valid entries
  • 3: PETSC_OFFLOAD_BOTH — CPU and GPU are in sync

Returns: Enum value from PetscOffloadMask describing the offloading status.

Return type: int

See also: VecGetOffloadMask, PetscOffloadMask

Source code at petsc4py/PETSc/Vec.pyx:1567

🎀 getOptionsPrefix()

Returns the prefix used for searching for options in the database. Your vector's lil name tag so the option system knows who's who 🏷️

Not collective.

See also: Working with PETSc options, setOptionsPrefix, VecGetOptionsPrefix

Source code at petsc4py/PETSc/Vec.pyx:1014

Return type: str

✨ getOwnershipRange()

Returns the locally owned range of indices as (start, end). Your personal territory, periodt 💅

Not collective.

Returns:

  • start (int) — The first local element.
  • end (int) — One more than the last local element.

Return type: tuple[int, int]

See also: getOwnershipRanges, VecGetOwnershipRange

Source code at petsc4py/PETSc/Vec.pyx:1163

👑 getOwnershipRanges()

Returns the range of indices owned by each process. The whole squad's territory map, not just yours 🌍

Not collective.

The returned array is the result of an exclusive scan of the local sizes. Very math, very demure.

See also: getOwnershipRange, VecGetOwnershipRanges

Source code at petsc4py/PETSc/Vec.pyx:1184

Return type: ArrayInt

getSize() 💫

okay so this one hands you back the global size of the vector. That's the whole thing across every process, bestie, not just your little local slice. 🫶

Not collective — she doesn't need to ask anybody, she already knows. ✨

getSizes() 🎀

gives you the vector sizes, plural, the whole little size lineup. 💅

Not collective again — no gossip with the neighbors required.

getSubVector(iset, subvec=None) 🦋

pulls a subvector out of the given indices. the way that this one is Collective... she's on the phone with literally everyone. 📞

once you're done with the subvector you have to hand it back with restoreSubVector — that's the rule, no cap. 🙈

Parameters

getType() 👑

returns the type of the vector. that's it, that's the whole job, and she does it flawlessly. 💅

Not collective.

getValue(index) 🍓

grabs you a single value out of the vector. one (1) value. very demure, very mindful. 🎀

Not collective.

⚠️ bestie listen: only values locally stored may be accessed. if it's not yours locally, she cannot get it for you, periodt. 💀

Parameters

getValues(indices, values=None) 🌸

the plural version of the above — you hand her a whole list of locations and she comes back with a whole list of values. group order, but make it math. 🔥

Not collective.

⚠️ same caveat as her sister: only values locally stored may be accessed.

Parameters

getValuesStagStencil(indices, values=None) 💀

Not implemented.

yeah she's literally not here. ghosted. not me calling a method that doesn't exist 😭🙈

ghostUpdate(addv=None, mode=None) 👻

updates the ghosted vector entries. spooky name, extremely normal behavior, iconic honestly. 💜

Neighborwise collective — she only chats with the processes right next door. iykyk.

Parameters

  • 🔹 addv (petsc4py.typing.InsertModeSpec) — insertion mode.
  • 🔹 mode (petsc4py.typing.ScatterModeSpec) — scatter mode.
  • 🔁 Return type: None

Examples

to accumulate ghost region values onto owning processes:

>>> vec.ghostUpdate(InsertMode.ADD_VALUES, ScatterMode.REVERSE)

update ghost regions:

>>> vec.ghostUpdate(InsertMode.INSERT_VALUES, ScatterMode.FORWARD)

ghostUpdateBegin(addv=None, mode=None) 🌈

kicks off the update of ghosted vector entries. it's the beginning half of the whole situation — you start it here, you finish it with ghostUpdateEnd. the two of them are a package deal, fr fr. 🎀

Neighborwise collective.

Parameters

  • 🔹 addv (petsc4py.typing.InsertModeSpec)
  • 🔹 mode (petsc4py.typing.ScatterModeSpec)
  • 🔁 Return type: None

ghostUpdateEnd(addv=None, mode=None) ✨

finishes the ghosted-vector-entry update that you started back with ghostUpdateBegin. she's the closing parenthesis of the whole operation. 🫶

Neighborwise collective.

Parameters

  • 🔹 addv (petsc4py.typing.InsertModeSpec)
  • 🔹 mode (petsc4py.typing.ScatterModeSpec)
  • 🔁 Return type: None

isaxpy(idx, alpha, x) 🧚

adds a scaled reduced-space vector into a subset of the vector. very specific, very powerful, very her. 💅

Logically collective.

literally equivalent to y[idx[i]] += alpha*x[i]. 🎯

Parameters

isset(idx, alpha) 💖

sets specific elements of the vector all to the same value. one value, many spots, zero drama. 🌸

Not collective.

Parameters

load(viewer) ⭐

loads a vector. 📥

Collective.

🌸 localForm() 🌸

Returns a context manager for viewing ghost vectors in local form. 🫶

Logically collective.

Returns: a context manager that yields the vector in local (ghosted) form.

Return type: typing.Any (https://docs.python.org/3/library/typing.html#typing.Any)

Notes

okay bestie listen — this operation does not perform a copy. To obtain up-to-date ghost values ghostUpdateBegin and ghostUpdateEnd must be called first. 💅

Non-ghost values can be found at values[0:nlocal] and ghost values at values[nlocal:nlocal+nghost].

Examples

>>> with vec.localForm() as lf:
...     # compute with lf

See also: createGhost, ghostUpdateBegin, ghostUpdateEnd, VecGhostGetLocalForm (https://petsc.org/release/manualpages/Vec/VecGhostGetLocalForm.html), VecGhostRestoreLocalForm (https://petsc.org/release/manualpages/Vec/VecGhostRestoreLocalForm.html)

Source code at petsc4py/PETSc/Vec.pyx:3278 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3278)

🧮 log() 🧮

Replace each entry in the vector by its natural logarithm. lowkey the math glow-up. ✨

Logically collective.

See also: exp, VecLog (https://petsc.org/release/manualpages/Vec/VecLog.html)

Source code at petsc4py/PETSc/Vec.pyx:2283 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2283)

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

💫 mDot(vecs, out=None) 💫

Compute Xᴴ·y with X an array of vectors. it's giving conjugate-transpose realness. 👑

Collective.

Parameters

Return type: ArrayScalar (#petsc4py.typing.ArrayScalar)

See also: dot, tDot, mDotBegin, mDotEnd, VecMDot (https://petsc.org/release/manualpages/Vec/VecMDot.html)

Source code at petsc4py/PETSc/Vec.pyx:1902 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1902)

🔥 mDotBegin(vecs, out) 🔥

Starts a split phase multiple dot product computation. we love a two-part era. 💅

Collective.

Parameters

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

See also: mDot, mDotEnd, VecMDotBegin (https://petsc.org/release/manualpages/Vec/VecMDotBegin.html)

Source code at petsc4py/PETSc/Vec.pyx:1935 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1935)

💅 mDotEnd(vecs, out) 💅

Ends a split phase multiple dot product computation. the finale of the dot product saga. 🎬

Collective.

Parameters

Return type: ArrayScalar (#petsc4py.typing.ArrayScalar)

See also: mDot, mDotBegin, VecMDotEnd (https://petsc.org/release/manualpages/Vec/VecMDotEnd.html)

Source code at petsc4py/PETSc/Vec.pyx:1965 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1965)

👑 max() 👑

Return the vector entry with maximum real part and its location. the main character entry, literally. 🌟

Collective.

Returns

Return type: tuple (https://docs.python.org/3/builtins/stdtypes.html#tuple)[int (https://docs.python.org/3/builtins/functions.html#int), float (https://docs.python.org/3/builtins/functions.html#float)]

See also: min, VecMax (https://petsc.org/release/manualpages/Vec/VecMax.html)

Source code at petsc4py/PETSc/Vec.pyx:2217 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2217)

🍓 maxPointwiseDivide(vec) 🍓

Return the maximum of the component-wise absolute value division. dividing girlies stay winning. 💖

Logically collective.

Equivalent to result = max_i abs(x[i] / y[i]).

Parameters

  • x — Numerator vector.
  • y — Denominator vector.
  • vec (Vec (#petsc4py.PETSc.Vec))

Return type: float (https://docs.python.org/3/builtins/functions.html#float)

See also: pointwiseMin, pointwiseMax, pointwiseMaxAbs, VecMaxPointwiseDivide (https://petsc.org/release/manualpages/Vec/VecMaxPointwiseDivide.html)

Source code at petsc4py/PETSc/Vec.pyx:2710 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2710)

🌈 maxpy(alphas, vecs) 🌈

Compute and store y = Σₙ(ɑₙ·Xₙ) + y with X an array of vectors. a whole lineup of scaled vectors getting summed into y, obsessed. 🔥

Logically collective.

Equivalent to y[:] = alphas[i]*vecs[i, :] + y[:].

Parameters

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

See also: axpy, aypx, axpby, waxpy, VecMAXPY (https://petsc.org/release/manualpages/Vec/VecMAXPY.html)

Source code at petsc4py/PETSc/Vec.pyx:2583 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2583)

🦋 mean() 🦋

Return the arithmetic mean of all the entries of the vector. the average bestie, the vibe check of the whole vector. ✨

Collective.

See also: VecMean (https://petsc.org/release/manualpages/Vec/VecMean.html)

Source code at petsc4py/PETSc/Vec.pyx:2180 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2180)

Return type: Scalar (#petsc4py.typing.Scalar)

💀 min() 💀

Return the vector entry with minimum real part and its location. the underdog entry, we love to see it. 😭

Collective.

Returns

Return type: tuple (https://docs.python.org/3/builtins/stdtypes.html#tuple)[int (https://docs.python.org/3/builtins/functions.html#int), float (https://docs.python.org/3/builtins/functions.html#float)]

See also: max, VecMin (https://petsc.org/release/manualpages/Vec/VecMin.html)

Source code at petsc4py/PETSc/Vec.pyx:2194 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2194)

🌟 mtDot(vecs, out=None) 🌟

Compute Xᵀ·y with X an array of vectors. transpose edition, no conjugate this time bestie. 💜

Collective.

Parameters

  • vecs (Sequence[Vec]) — an array of vectors, bestie. Your whole little lineup 🌸
  • out (ArrayScalar | None) — an optional placeholder situation for the result, if you wanna hand one over 🫶

Return type: ArrayScalar ✨

See also: tDot, mDot, mtDotBegin, mtDotEnd, VecMTDot — https://petsc.org/release/manualpages/Vec/VecMTDot.html

Source code at petsc4py/PETSc/Vec.pyx:1996

🦋 mtDotBegin(vecs, out)

Ok so this one starts a split phase transpose multiple dot product computation. Think of it as the "we're about to do the thing, everybody get ready" era of the operation 💅

Collective.

Parameters 🎀

  • vecs (Sequence[Vec]) — array of vectors. Yes, again. It's always vectors.
  • out (ArrayScalar) — placeholder for the result. Not optional this time, you gotta give it a home.

Return type: None — it returns literally nothing and that's iconic of it 🙈

See also: mtDot, mtDotEnd, VecMTDotBegin — https://petsc.org/release/manualpages/Vec/VecMTDotBegin.html

Source code at petsc4py/PETSc/Vec.pyx:2029

🎀 mtDotEnd(vecs, out)

The ending of that split phase transpose multiple dot product computation. You and mtDotBegin are a matched set, no cap 🤝

Collective.

Parameters

  • vecs (Sequence[Vec]) — array of vectors.
  • out (ArrayScalar) — placeholder for the result.

Return type: ArrayScalar 💖

See also: mtDot, mtDotBegin, VecMTDotEnd — https://petsc.org/release/manualpages/Vec/VecMTDotEnd.html

Source code at petsc4py/PETSc/Vec.pyx:2059

✨ norm(norm_type=None)

Compute the vector norm. That's it, that's the vibe ⭐

Collective.

Lowkey important detail: a 2-tuple gets returned if NormType.NORM_1_AND_2 is specified. So sometimes you get one number, sometimes you get two in a trench coat 🧚

See also: VecNorm — https://petsc.org/release/manualpages/Vec/VecNorm.html, NormType — https://petsc.org/release/manualpages/Vec/NormType.html

Source code at petsc4py/PETSc/Vec.pyx:2090

Parameters

  • norm_type (NormTypeSpec) — the flavor of norm you want, devoured.

Return type: float | tuple[float, float] 👑

🌈 normBegin(norm_type=None)

Begin computing the vector norm. It's giving "I'll start it, you finish it."

Collective.

This should be paired with a call to normEnd. They're a duo, don't separate them 😭

See also: normEnd, norm, VecNormBegin — https://petsc.org/release/manualpages/Vec/VecNormBegin.html

Source code at petsc4py/PETSc/Vec.pyx:2112

Parameters

  • norm_type (NormTypeSpec)

Return type: None

💜 normEnd(norm_type=None)

Finish computations initiated with normBegin. The second half of the glow-up ✨

Collective.

See also: normBegin, norm, VecNormEnd — https://petsc.org/release/manualpages/Vec/VecNormEnd.html

Source code at petsc4py/PETSc/Vec.pyx:2131

Parameters

  • norm_type (NormTypeSpec)

Return type: float | tuple[float, float]

💅 normalize()

Normalize the vector by its 2-norm. Main character behavior, honestly 👑

Collective.

Returns: the vector norm before normalization. So it tells you what it was before it changed it. Messy but we love her 🍓

Return type: float

See also: norm, VecNormalize — https://petsc.org/release/manualpages/Vec/VecNormalize.html

Source code at petsc4py/PETSc/Vec.pyx:2240

🧚 permute(order, invert=False)

Permute the vector in-place with a provided ordering. Shuffling the vibes, but make it mathematically valid 💫

Collective.

Parameters

  • order (IS) — the ordering for the permutation.
  • invert (bool) — whether to invert the permutation. Defaults to False, so by default, no inverting bestie.

Return type: None

See also: VecPermute — https://petsc.org/release/manualpages/Vec/VecPermute.html

Source code at petsc4py/PETSc/Vec.pyx:2351

🦋 placeArray(array)

Set the local portion of the vector to a provided array. Handing the vector your array, and it's gonna live there now 💖

Not collective.

See also: resetArray, setArray, VecPlaceArray — https://petsc.org/release/manualpages/Vec/VecPlaceArray.html

Source code at petsc4py/PETSc/Vec.pyx:1345

Parameters

  • array (Sequence[Scalar])

Return type: None

⭐ pointwiseDivide(x, y)

Compute and store the component-wise division of two vectors. It's literally just w[i] = x[i] / y[i], slay 🎀

Logically collective.

Equivalent to w[i] = x[i] / y[i].

Parameters

  • x (Vec) — numerator vector. The one on top.
  • y (Vec) — denominator vector. The one doing the dividing. Do not let it be full of zeroes, that's a whole crisis 💀

Return type: None

See also: pointwiseMult, VecPointwiseDivide — https://petsc.org/release/manualpages/Vec/VecPointwiseDivide.html

Source code at petsc4py/PETSc/Vec.pyx:2632

🔥 pointwiseMax(x, y)

Compute and store the component-wise maximum of two vectors. Picking the bigger one, every single component, no hesitation 😤

Logically collective.

Equivalent to w[i] = max(x[i], y[i]).

Parameters

  • x (Vec) — input vectors to find the component-wise maxima.
  • y (Vec) — input vectors to find the component-wise maxima.

Return type: None

See also: pointwiseMin, pointwiseMaxAbs, VecPointwiseMax — https://petsc.org/release/manualpages/Vec/VecPointwiseMax.html

Source code at petsc4py/PETSc/Vec.pyx:2672

🌸 pointwiseMaxAbs(x, y)

Compute and store the component-wise maximum absolute values. So we're ignoring the sign entirely and just judging magnitude. Unbothered. Flourishing ✨

Logically collective.

Equivalent to w[i] = max(abs(x[i]), abs(y[i])).

Parameters

  • x (Vec) — input vectors to find the component-wise maxima.
  • y (Vec) — input vectors to find the component-wise maxima.

Return type: None — yeah bestie, it hands you back absolutely nothing and honestly? iconic behaviour

See also: pointwiseMin, pointwiseMax, VecPointwiseMaxAbs

Source code: petsc4py/PETSc/Vec.pyx:2691 — go peek at the source if you wanna, she's right there 💅

pointwiseMin(x, y)

Compute and store the component-wise minimum of two vectors.

Logically collective. (so everybody on the team has to show up, but nobody's blocked waiting around 🌸)

Equivalent to w[i] = min(x[i], y[i]) — like, literally just take whichever of the two is smaller at every single slot, no cap.

  • x (Vec) — Input vectors to find the component-wise minima.
  • y (Vec) — Input vectors to find the component-wise minima.

Return type: None

See also: pointwiseMax, pointwiseMaxAbs, VecPointwiseMin

Source code: petsc4py/PETSc/Vec.pyx:2653

pointwiseMult(x, y)

Compute and store the component-wise multiplication of two vectors.

Logically collective.

Equivalent to w[i] = x[i] * y[i] — each entry vibes with its matching entry and they multiply, periodt. ✨

  • x (Vec) — Input vectors to multiply component-wise.
  • y (Vec) — Input vectors to multiply component-wise.

Return type: None

See also: pointwiseDivide, VecPointwiseMult

Source code: petsc4py/PETSc/Vec.pyx:2613

reciprocal()

Replace each entry in the vector by its reciprocal. 💫 (so x becomes 1/x, she flipped the whole squad)

Logically collective.

See also: VecReciprocal

Source code: petsc4py/PETSc/Vec.pyx:2259

Return type: None

resetArray(force=False)

Reset the vector to use its default array.

Not collective — this one's a solo mission, she doesn't need the group chat for it.

Parameters

  • force (bool) — Force the calling of VecResetArray even if no user array has been placed with placeArray.

Returns: The array previously provided by the user with placeArray. Can be None if force is True and no array was placed before. (so lowkey it might hand you back nothing, and that's fine, that's allowed)

Return type: ArrayScalar

See also: placeArray, VecResetArray

Source code: petsc4py/PETSc/Vec.pyx:1366

restoreCLMemHandle()

Restore a pointer to the OpenCL buffer obtained with getCLMemHandle.

Not collective.

okay so this is the "give it back when you're done" step — you grabbed a handle with getCLMemHandle, now you're returning it. Don't be the friend who borrows a hoodie and never returns it 🙈

See also: getCLMemHandle, VecViennaCLRestoreCLMemWrite

Source code: petsc4py/PETSc/Vec.pyx:1670

Return type: None

restoreCUDAHandle(handle, mode='rw')

Restore a pointer to the device buffer obtained with getCUDAHandle.

Not collective.

Parameters

  • handle (Any) — CUDA device pointer.
  • mode (AccessModeSpec) — Access mode.

Return type: None

See also: getCUDAHandle, VecCUDARestoreArray, VecCUDARestoreArrayRead, VecCUDARestoreArrayWrite

Source code: petsc4py/PETSc/Vec.pyx:1462

restoreHIPHandle(handle, mode='rw')

Restore a pointer to the device buffer obtained with getHIPHandle.

Not collective.

Parameters

  • handle (Any) — HIP device pointer.
  • mode (AccessModeSpec) — Access mode.

Return type: None

See also: getHIPHandle, VecHIPRestoreArray, VecHIPRestoreArrayRead, VecHIPRestoreArrayWrite

Source code: petsc4py/PETSc/Vec.pyx:1534

not me writing the exact same paragraph for CUDA and HIP 💀 they're twins, your honour, one just says CUDA where the other says HIP

restoreLocalVector(lvec, readonly=False)

Unmap a local access obtained with getLocalVector. 🦋 (you opened it, now you close it, that's the whole arc)

Logically collective.

Parameters

  • lvec (Vec) — The local vector.
  • readonly (bool) — Request read-only access.

Return type: None

See also: createLocalVector, getLocalVector, VecRestoreLocalVectorRead, VecRestoreLocalVector

Source code: petsc4py/PETSc/Vec.pyx:1246

restoreSubVector(iset, subvec)

Restore a subvector extracted using getSubVector.

Collective — full squad assembled for this one, everybody's involved 🌈

Parameters

  • iset (IS) — Index set describing the indices represented by the subvector.
  • subvec (Vec) — Subvector to be restored.

Return type: None

See also: getSubVector, VecRestoreSubVector

Source code: petsc4py/PETSc/Vec.pyx:3446

scale(alpha)

Scale all entries of the vector. 🔥

Collective.

This method sets each entry (xₙ) in the vector to ɑ·xₙ. Every single entry gets multiplied by your alpha, no survivors, no exceptions.

Parameters

  • alpha (Scalar) — The scaling factor.

Return type: None

See also: shift, VecScale

Source code: petsc4py/PETSc/Vec.pyx:2417

set(alpha)

Set all components of the vector to the same value. (everybody matching, we love a unified aesthetic 💅)

Collective.

See also: zeroEntries, isset, VecSet

🔗 source code at petsc4py/PETSc/Vec.pyx:2384 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2384

Parameters

  • alpha — a Scalar 💜

Return type — None

and that's the whole tail of that one, bestie, periodt ✋

setArray(array) 🎀

okay so this one just sets the values for the local portion of the vector. local portion only, iykyk. that's the assignment.

Logically collective. everybody in the crew calls it together, we love a group activity 🫶

See also: placeArray

Source code at petsc4py/PETSc/Vec.pyx:1333 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1333

Parameters

  • array (Sequence[Scalar] 💜) — the values going in

Return type — None

setBlockSize(bsize) 🧱

sets the block size of the vector. tiny little knob, huge consequences, main character energy fr.

Logically collective.

See also: VecSetBlockSize → https://petsc.org/release/manualpages/Vec/VecSetBlockSize.html

Source code at petsc4py/PETSc/Vec.pyx:1136 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1136

Parameters

  • bsize (int) — the block size

Return type — None

setDM(dm) 🔗

hooks a DM (#petsc4py.PETSc.DM) up to your vector. like, this vector? it belongs to that DM now. slay.

Not collective. this one's a solo mission 🦋

See also: getDM, VecSetDM → https://petsc.org/release/manualpages/DM/VecSetDM.html

Source code at petsc4py/PETSc/Vec.pyx:3521 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3521

Parameters

  • dm (DM (#petsc4py.PETSc.DM))

Return type — None

setFromOptions() ⚙️

configures the vector straight from the options database. whatever you dropped in the options, it's picking it up. no cap.

Collective. everybody, together, now 🌈

See also: Working with PETSc options (#petsc-options), VecSetFromOptions → https://petsc.org/release/manualpages/Vec/VecSetFromOptions.html

Source code at petsc4py/PETSc/Vec.pyx:1042 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1042

Return type — None

setLGMap(lgmap) 🗺️

sets the local-to-global mapping. iconic behavior honestly.

Logically collective.

and the important part, bestie: this allows users to insert vector entries using a local numbering with setValuesLocal. so you get to pretend the local numbers are the real numbers and the mapping handles the rest. obsessed.

See also: setValues, setValuesLocal, getLGMap, VecSetLocalToGlobalMapping → https://petsc.org/release/manualpages/Vec/VecSetLocalToGlobalMapping.html

Source code at petsc4py/PETSc/Vec.pyx:2898 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2898

Parameters

  • lgmap (LGMap (#petsc4py.PETSc.LGMap))

Return type — None

setMPIGhost(ghosts) 👻

sets the ghost points for a ghosted vector. spooky season but make it linear algebra 💀

Collective.

Parameters

  • ghosts (Sequence[int]) — Global indices of ghost points.

Return type — None

See also: createGhost

Source code at petsc4py/PETSc/Vec.pyx:3380 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3380

setNestSubVecs(sx, idxm=None) 🪆

sets the component vectors at specified indices inside the nested vector. it's giving little vectors inside a big vector, nesting doll realness.

Not collective.

Parameters

  • sx (Sequence[Vec] (#petsc4py.PETSc.Vec)) — Array of component vectors.
  • idxm (Sequence[int] | None) — Indices of the component vectors, defaults to range(len(sx)).

Return type — None

See also: getNestSubVecs, VecNestSetSubVecs → https://petsc.org/release/manualpages/Vec/VecNestSetSubVecs.html

Source code at petsc4py/PETSc/Vec.pyx:3487 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3487

setOption(option, flag) 🔘

sets an option. that's it. short king behavior.

Collective.

See also: VecSetOption → https://petsc.org/release/manualpages/Vec/VecSetOption.html

Source code at petsc4py/PETSc/Vec.pyx:1067 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1067

Parameters

  • option (Option (#petsc4py.PETSc.Vec.Option))
  • flag (bool)

Return type — None

setOptionsPrefix(prefix) 🏷️

sets the prefix the vector uses when it goes looking for its options in the database. so your vector can have its own lil namespace, we stan a boundaries-having vector.

Logically collective.

See also: Working with PETSc options (#petsc-options), getOptionsPrefix, VecSetOptionsPrefix → https://petsc.org/release/manualpages/Vec/VecSetOptionsPrefix.html

Source code at petsc4py/PETSc/Vec.pyx:1000 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1000

Parameters

  • prefix (str | None)

Return type — None

setRandom(random=None) 🎲

fills every single component of the vector with random numbers. chaos, but make it reproducible-ish.

Collective.

Parameters

  • random (Random (#petsc4py.PETSc.Random) | None) — Random number generator. If None then one will be created internally.

Return type — None

See also: VecSetRandom → https://petsc.org/release/manualpages/Vec/VecSetRandom.html

Source code at petsc4py/PETSc/Vec.pyx:2331 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2331

setSizes(size, bsize=None) 📏

sets the local and global sizes of the vector. the glow-up where your vector finally knows how big it is ✨

Collective.

Parameters

  • size (LayoutSizeSpec (#petsc4py.typing.LayoutSizeSpec)) — Vector size.
  • bsize (int | None) — Vector block size. If None, bsize = 1.

Return type — None

See also: getSizes, VecSetSizes → https://petsc.org/release/manualpages/Vec/VecSetSizes.html

Source code at petsc4py/PETSc/Vec.pyx:218 → https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L218

setType(vec_type) 👑

sets the vector type. this is the vibe check for your whole vec, choose wisely bestie.

Collective.

Parameters

  • vec_type (Type (#petsc4py.PETSc.Vec.Type) | str) — The vector type.

Return type — None

See also: create, getType, VecSetType → https://petsc.org/release/manualpages/Vec/VecSetType.html

Source code at petsc4py/PETSc/Vec.pyx:218 — wait, no babes, that one's setSizes — this cutie lives at petsc4py/PETSc/Vec.pyx:1079-ish energy… but fr, the manpage for setType just points you back to create, getType and VecSetType, so go read those 💅

Source code at petsc4py/PETSc/Vec.pyx:199 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L199>

setUp()

okay bestie this one sets up all the internal data structures so the vector is actually ready to be used. 💅

Collective. (yes ma'am, everybody gotta show up for this one 🌈)

See also:

Source code at petsc4py/PETSc/Vec.pyx:1054 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1054>

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

setValue(index, value, addv=None)

Insert or add a single value into the vector. one (1) value. a lil guy. 🎀

Not collective.

Parameters

  • index (int <https://docs.python.org/3/builtins/functions.html#int>) — where we're writing to babes. Heads up: negative indices get ignored, they're not the vibe. 🙈
  • value (Scalar <#petsc4py.typing.Scalar>) — the value we're inserting at index.
  • addv (InsertModeSpec <#petsc4py.typing.InsertModeSpec>) — the insertion mode.

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

Notes

The values may be cached, so you gotta call assemblyBegin and assemblyEnd after all your calls to this method are done. no skipping, bestie. 😭
Multiple calls to setValue cannot be made with different values for addv without intermediate calls to assemblyBegin and assemblyEnd. lowkey important, don't do it. 💀

See also:

Source code at petsc4py/PETSc/Vec.pyx:2785 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2785>

setValueLocal(index, value, addv=None)

Same energy as setValue but it uses a local numbering. it's giving "same girl, different coordinate system" ✨

Not collective.

Parameters

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

Notes

Values may be cached, so assemblyBegin and assemblyEnd must be called after all your calls here are done. periodt. 🫶
Multiple calls to setValueLocal cannot be made with different values for addv without intermediate calls to assemblyBegin and assemblyEnd. 🚨

See also:

Source code at petsc4py/PETSc/Vec.pyx:2928 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2928>

setValues(indices, values, addv=None)

Now we're doing multiple values at once. it's the group chat version of setValue. 🔥

Not collective.

Parameters

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

Notes

Values may be cached, so assemblyBegin and assemblyEnd must be called after all calls of this method are done. don't forget, bestie, I'm begging. 😭
Multiple calls to setValues cannot be made with different values for addv without intermediate calls to assemblyBegin and assemblyEnd. 🧚

See also:

Source code at petsc4py/PETSc/Vec.pyx:2822 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2822>

setValuesBlocked(indices, values, addv=None)

Insert or add whole blocks of values. it's giving bulk order, iconic behavior. 👑

Not collective.

Equivalent to x[bs*indices[i]+j] = y[bs*i+j] for 0 <= i < len(indices), 0 <= j < bs and bs = block_size. ✨

Parameters

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

Notes

Values may be cached so assemblyBegin and assemblyEnd must be called after all calls of this method are completed. ⭐
Multiple calls to setValuesBlocked cannot be made with different values for addv without intermediate calls to assemblyBegin and assemblyEnd. 💀

See also:

Source code at petsc4py/PETSc/Vec.pyx:2856 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2856>

setValuesBlockedLocal(indices, values, addv=None)

Block values, but make it local numbering. best of both worlds fr fr. 🌈

Not collective.

Equivalent to x[bs*indices[i]+j] = y[bs*i+j] for 0 <= i < len(indices), 0 <= j < bs and bs = block_size. ✨

Parameters

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

Notes

Values may be cached so assemblyBegin and assemblyEnd must be called after every call of this method is done. 🎀
Multiple calls to setValuesBlockedLocal cannot be made with different values for addv without intermediate calls to assemblyBegin and assemblyEnd. 🚨

See also:

Source code at petsc4py/PETSc/Vec.pyx:2999 <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2999>

setValuesLocal(indices, values, addv=None)

Multiple values, local numbering. the local era continues and honestly? we're thriving. 🦋

Not collective.

Parameters

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

Notes

Values may be cached so assemblyBegin and assemblyEnd must be called after all calls of this method are completed. 💖
Multiple calls to setValuesLocal cannot be made with different values for addv without intermediate calls to assemblyBegin and assemblyEnd. 💀

🫠 setValuesStagStencil(indices, values, addv=None)

Not implemented. 😭 That's it, that's the whole thing. Bestie, do not come for me, I am simply the messenger. This one is literally just vibes and a promise.

Source code at petsc4py/PETSc/Vec.pyx:2894 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2894

Return type

  • None 👻

🌊 shift(alpha)

okay so this one shifts ALL the entries in the vector. Every single one. Group chat, roll call, everybody moves.

Collective. 🫶 Which means all your processes gotta show up for it, no ghosting.

What it actually does: it takes each entry (xₙ) in the vector and sets it to xₙ + ɑ. Cute, simple, slay.

Parameters

  • alpha (Scalar) — the shift to apply to the vector values. Like, how far you're scooting everything over 💅

Return type

  • None

See also: scale, VecShift — https://petsc.org/release/manualpages/Vec/VecShift.html

Source code at petsc4py/PETSc/Vec.pyx:2437 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2437

💅 sqrtabs()

Replaces each entry (xₙ) in the vector with √|xₙ|. So it's abs value first (throw away the negativity, we're healing), then square root. Iconic behaviour tbh. 🌸

Logically collective. Which is the chill version of collective — meaning it needs to be called the same way across processes to be meaningful, but we're not out here doing a whole ceremony about it.

See also: VecSqrtAbs — https://petsc.org/release/manualpages/Vec/VecSqrtAbs.html

Source code at petsc4py/PETSc/Vec.pyx:2295 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2295

Return type

  • None

🎀 strideGather(field, vec, addv=None)

bestie this is the glow-up pipeline ✨ It inserts component values into a single-component vector. You're taking one little slice of your big glow-up vector and moving it into a whole separate single-component vector.

Collective. 👑

Setup requirements, listen closely:

  • The current vector (the one you're calling this on, the source) is expected to be multi-component — block_size greater than 1.
  • The target vector is expected to be single-component.

Parameters

  • field (int) — component index. Must be between 0 and vec.block_size. 🚨
  • vec (Vec) — the single-component vector being inserted into.
  • addv (InsertModeSpec) — insertion mode. i.e. how you're putting the values in there.

Return type

  • None

See also: strideScatter, VecStrideScatter — https://petsc.org/release/manualpages/Vec/VecStrideScatter.html

Source code at petsc4py/PETSc/Vec.pyx:3245 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3245

👑 strideMax(field)

Returns the maximum of the entries in a subvector. We're finding the main character of this component. 😌

Collective.

Equivalent to:

max(x[field], x[field+bs], x[field+2*bs], ...)

where bs is block_size.

Parameters

  • field (int) — component index. Must be between 0 and vec.block_size. 🫶

Returns

  • int — location of maximum. (Where the icon lives 📍)
  • float — maximum value. (How iconic it is 🔥)

Return type

  • tuple[int, float]

See also: strideScale, strideSum, strideMin, VecStrideMax — https://petsc.org/release/manualpages/Vec/VecStrideMax.html

Source code at petsc4py/PETSc/Vec.pyx:3151 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3151

🦋 strideMin(field)

Returns the minimum of the entries in a subvector. The exact same energy as strideMax but for the quiet one in the group. 🙈

Collective.

Equivalent to:

min(x[field], x[field+bs], x[field+2*bs], ...)

where bs is block_size.

Parameters

  • field (int) — component index. Must be between 0 and vec.block_size. 🫶

Returns

  • int — location of minimum. 📍
  • float — minimum value. 🍓

Return type

  • tuple[int, float]

See also: strideScale, strideSum, strideMax, VecStrideMin — https://petsc.org/release/manualpages/Vec/VecStrideMin.html

Source code at petsc4py/PETSc/Vec.pyx:3120 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3120

🌈 strideNorm(field, norm_type=None)

Returns the norm of the entries in a subvector. Sizing up one component, measuring the vibe check 📏✨

Collective.

Equivalent to:

norm(x[field], x[field+bs], x[field+2*bs], ...)

where bs is block_size.

Parameters

  • field (int) — component index. Must be between 0 and vec.block_size. 🫶
  • norm_type (NormTypeSpec) — the norm type. You get to pick the flavour 💜

Return type

  • float | tuple[float, float] — yeah it can hand you back a single float OR a lil pair of them, depends on the norm type you asked for. Versatile.

See also: norm, strideScale, strideSum, VecStrideNorm — https://petsc.org/release/manualpages/Vec/VecStrideNorm.html

Source code at petsc4py/PETSc/Vec.pyx:3182 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3182

🧚 strideScale(field, alpha)

Scales one single component of the vector. Not the whole thing, just that one. Targeted glow-up. 💅

Logically collective.

Parameters

  • field (int) — component index. Must be between 0 and vec.block_size. 🫶
  • alpha (Scalar) — factor to multiple the component entries by. (Yes, the original says "multiple", I'm not touching it, it means multiply, we move on 😭)

Return type

  • None

See also: strideSum, strideMin, strideMax, VecStrideScale — https://petsc.org/release/manualpages/Vec/VecStrideScale.html

Source code at petsc4py/PETSc/Vec.pyx:3076 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3076

🍓 strideScatter(field, vec, addv=None)

This is strideGather's mirror selfie 🪞 Scatters entries into a component of another vector.

Collective. 👑

Setup requirements, opposite day edition:

  • The current vector (the source, the one you're calling this on) is expected to be single-component — block_size of 1.
  • The target vector is expected to be multi-component.

Parameters

  • field (int) — component index. Must be between 0 and vec.block_size. 🫶
  • vec (Vec) — the multi-component vector being scattered into.
  • addv (InsertModeSpec) — insertion mode.

Return type

  • None

See also: strideGather, VecStrideScatter — https://petsc.org/release/manualpages/Vec/VecStrideScatter.html

Source code at petsc4py/PETSc/Vec.pyx:3214 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3214

⭐ strideSum(field)

Sums up the subvector entries. Adding all the little guys together into one big total. ➕➖

Collective.

Equivalent to:

sum(x[field], x[field+bs], x[field+2*bs], ...)

where bs is block_size.

Parameters

  • field (int) — component index. Must be between 0 and vec.block_size. 🫶

Return type

  • Scalar

See also: strideScale, strideMin, strideMax, VecStrideSum — https://petsc.org/release/manualpages/Vec/VecStrideSum.html

✨ sum() — bestie, it's giving "add it ALL up" ✨

Return the sum of all the entries of the vector.

Collective. 🫶 (yes, everyone in the communicator has to show up, no skipping the group chat)

See also:

Source code at petsc4py/PETSc/Vec.pyx:2166 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2166>

Return type: Scalar

🔄 swap(vec) — trade places, no drama

Swap the content of two vectors. literally just swapping outfits with your bestie.

Logically collective.

Parameters:

  • vec (Vec) — The vector to swap data with.

Return type: None

See also:

Source code at petsc4py/PETSc/Vec.pyx:2457 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2457>

🎯 tDot(vec) — the indefinite dot product, iykyk

Return the indefinite dot product with vec.

Collective.

This computes yᵀ·x with self as x, vec as y and where yᵀ denotes the transpose of y. 🧮 (yes girl, transpose energy)

Parameters:

  • vec (Vec) — Vector to compute the indefinite dot product with.

Return type: Scalar

See also:

Source code at petsc4py/PETSc/Vec.pyx:1846 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1846>

🚀 tDotBegin(vec) — start it, don't finish it (yet)

Begin computing the indefinite dot product.

Collective.

This should be paired with a call to tDotEnd. 👯 (they're a matching set, you can't wear one without the other)

Parameters:

  • vec (Vec) — Vector to compute the indefinite dot product with.

Return type: None

See also:

Source code at petsc4py/PETSc/Vec.pyx:1868 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1868>

🏁 tDotEnd(vec) — the sequel, the payoff, the finale

Finish computing the indefinite dot product initiated with tDotBegin.

Collective.

See also:

Source code at petsc4py/PETSc/Vec.pyx:1888 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L1888>

Parameters:

  • vec (Vec)

Return type: Scalar

🎁 toDLPack(mode='rw') — wrap it up, it's a capsule era

Return a DLPack PyCapsule wrapping the vector data.

Collective.

Parameters:

  • mode (AccessModeSpec) — Access mode for the vector.

Returns: Capsule of a DLPack tensor wrapping a Vec.

Return type: PyCapsule — <https://docs.python.org/3/c-api/capsule.html#c.PyCapsule>

Notes

⚠️ It is important that the access mode is respected by the consumer as this is not enforced internally. no cap, PETSc is trusting you to behave and it will NOT be checking 💀

See also:

  • createWithDLPack

Source code at petsc4py/PETSc/Vec.pyx:726 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L726>

👀 view(viewer=None) — show her off

Display the vector.

Collective.

Parameters:

  • viewer (Viewer | None) — A Viewer instance or None for the default viewer.

Return type: None

See also:

Source code at petsc4py/PETSc/Vec.pyx:144 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L144>

💅 waxpy(alpha, x, y) — the math girlie move

Compute and store w = ɑ·x + y.

Logically collective.

Parameters:

  • alpha (Scalar) — Scale factor.
  • x (Vec) — First input vector.
  • y (Vec) — Second input vector.

Return type: None

See also:

Source code at petsc4py/PETSc/Vec.pyx:2561 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2561>

🫧 zeroEntries() — reset, refresh, restart

Set all entries in the vector to zero.

Logically collective.

See also:

Source code at petsc4py/PETSc/Vec.pyx:2372 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L2372>

Return type: None

🎀 Attributes Documentation 🎀

okay bestie these are the attributes, and they're all lowkey iconic.

💖 array — Alias for array_w.

Source code at petsc4py/PETSc/Vec.pyx:3658 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3658>

🔒 array_r — Read-only ndarray containing the local portion of the vector.

Source code at petsc4py/PETSc/Vec.pyx:3648 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3648>

✍️ array_w — Writeable ndarray containing the local portion of the vector.

Source code at petsc4py/PETSc/Vec.pyx:3639 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3639>

🧱 block_size — The block size.

Source code at petsc4py/PETSc/Vec.pyx:3614 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3614>

🎀 buffer — Alias for buffer_w.

Source code at petsc4py/PETSc/Vec.pyx:3653 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3653>

🔐 buffer_r — Read-only buffered view of the local portion of the vector.

Source code at petsc4py/PETSc/Vec.pyx:3634 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3634>

🖊️ buffer_w — Writeable buffered view of the local portion of the vector.

Source code at petsc4py/PETSc/Vec.pyx:3629 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3629>

📏 local_size — The local vector size.

Source code at petsc4py/PETSc/Vec.pyx:3609 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3609>

🗺️ owner_range — The locally owned range of indices in the form [low, high).

Source code at petsc4py/PETSc/Vec.pyx:3619 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3619>

🗺️ owner_ranges — The range of indices owned by each process.

Source code at petsc4py/PETSc/Vec.pyx:3624 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3624>

🌍 size — The global vector size.

Source code at petsc4py/PETSc/Vec.pyx:3604 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3604>

🔢 sizes — The local and global vector sizes.

Source code at petsc4py/PETSc/Vec.pyx:3596 — <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Vec.pyx#L3596>

🐣 __init__()

✨ classmethod __new__(*args, **kwargs)

👑 petsc4py.PETSc.Viewer

class petsc4py.PETSc.Viewer

Bases: Object — <#petsc4py.PETSc.Object>

Viewer object. 💅

So like, the Viewer is fully described in the PETSc manual, bestie — swing by <https://petsc.org/release/manual/other.html#sec-viewers> (that's https://petsc.org/release/manual/other.html#sec-viewers) if you want the whole lore. ✨

And the iconic part? Viewers can literally be called as functions, where the argument you pass in is the PETSc object getting viewed. Obsessed. Check the example below 👇

Examples

>>> from petsc4py import PETSc
>>> u = PETSc.Vec().createWithArray([1,2])
>>> v = PETSc.Viewer()
>>> v(u)
Vec Object: 1 MPI process
  type: seq
1.
2.

See also:

👑 Enumerations 👑

  • DrawSize — Window size. (#petsc4py.PETSc.Viewer.DrawSize)
  • FileMode — Viewer file mode. (#petsc4py.PETSc.Viewer.FileMode)
  • Format — Viewer format. (#petsc4py.PETSc.Viewer.Format)
  • Type — Viewer type. (#petsc4py.PETSc.Viewer.Type)

🦋 petsc4py.PETSc.Viewer.DrawSize 🦋

class petsc4py.PETSc.Viewer.DrawSize

Window size. Bestie this is literally just the size of the window, no cap. 🎀

🌸 Attributes Summary 🌸

💖 Attributes Documentation 💖

__init__()

classmethod __new__(*args, **kwargs)

🌈 petsc4py.PETSc.Viewer.FileMode 🌈

class petsc4py.PETSc.Viewer.FileMode

Viewer file mode. 🍓

🎀 Attributes Summary 🎀

okay bestie, vibe check on the constants this thing ships with 💖 they are all of type int, every single one, no exceptions, and the link points at Python's own int docs so you can go read the lore yourself https://docs.python.org/3/builtins/functions.html#int 🐍

📖 Attributes Documentation 📖

now for the individual glow-ups 💅 each one gets its own lil spotlight, each one is exactly what it says on the tin, and not one of them is doing anything sneaky. short names, long names, every flavor of viewer-mode realness ✨

A ✨

A: int = A

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

APPEND 🎀

APPEND: int = APPEND

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

APPEND_UPDATE 🦋

APPEND_UPDATE: int = APPEND_UPDATE

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

AU 🌸

AU: int = AU

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

R 💖

R: int = R

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

READ 📚

READ: int = READ

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

U 🫶

U: int = U

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

UA 🌈

UA: int = UA

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

UPDATE 👑

UPDATE: int = UPDATE

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

W ⭐

W: int = W

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

WRITE 💜

WRITE: int = WRITE

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

__init__()

no description here bestie, that's literally all she wrote 🙈

classmethod __new__(*args, **kwargs)

also no description. the docs are being ✨mysterious✨ and honestly? respect 😭

🦋 petsc4py.PETSc.Viewer.Format 🦋

class petsc4py.PETSc.Viewer.Format

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

Viewer format. 💅 that's the whole description, and she ate 🍓

lowkey the tiniest class description ever, but the constants above are doing the heavy lifting, so we move 💖

okay so bestie, we're still deep in the attributes zone, and every single one of these little icons is a constant of type int — like, the Python builtin int (https://docs.python.org/3/builtins/functions.html#int). no cap. here's the whole lineup, zero skips:

  • ASCII_COMMON — constant, type int 💅
  • ASCII_CSV — constant, type int ✨
  • ASCII_DENSE — constant, type int 🎀
  • ASCII_FACTOR_INFO — constant, type int 🦋
  • ASCII_GLVIS — constant, type int 🌸
  • ASCII_IMPL — constant, type int 💖
  • ASCII_INDEX — constant, type int 🫶
  • ASCII_INFO — constant, type int 😭
  • ASCII_INFO_DETAIL — constant, type int 🔥
  • ASCII_LATEX — constant, type int 👑
  • ASCII_MATHEMATICA — constant, type int 🌈
  • ASCII_MATLAB — constant, type int ⭐
  • ASCII_MATRIXMARKET — constant, type int 💀
  • ASCII_PCICE — constant, type int 🙈
  • ASCII_PYTHON — constant, type int 🍓
  • ASCII_SYMMODU — constant, type int 🧚
  • ASCII_XML — constant, type int 💜
  • BINARY_MATLAB — constant, type int 💅
  • DEFAULT — constant, type int ✨
  • DRAW_BASIC — constant, type int 🎀
  • DRAW_CONTOUR — constant, type int 🦋
  • DRAW_LG — constant, type int 🌸
  • DRAW_LG_XRANGE — constant, type int 💖

...and the grand tour of viewer constants just keeps going, bestie. Every single one of these is a plain old int, fr fr — no secret structs hiding in the bushes, just numbers. Collect them all like Pokémon cards 💅

Attributes Documentation 🎀

okay so this is the exact same squad of constants, but now presented as attributes with their signature and the whole "yes it's an int, bestie, I promise" situation spelled out. Same numbers, different outfit. Slay 💖

and that's the whole constants roster, every last one of them, no crumbs left behind 💅 keep scrolling bestie, there's still more of this page and we are not done yet 🫶

okay bestie we're still deep in the constant zone and I need you to know these are giving enum energy 🎀 — every single one of these is a constant of type int, no cap, and the docs for int itself live right here: https://docs.python.org/3/builtins/functions.html#int. That's the link for all of them, so I'm not gonna make you scroll past it fifteen times like some kind of chaos demon. 🦋

  • DRAW_CONTOUR — int = DRAW_CONTOUR. Constant of type int.
  • DRAW_LG — int = DRAW_LG. Constant of type int.
  • DRAW_LG_XRANGE — int = DRAW_LG_XRANGE. Constant of type int.
  • DRAW_PORTS — int = DRAW_PORTS. Constant of type int.
  • FAILED — int = FAILED. Constant of type int.
  • HDF5_MAT — int = HDF5_MAT. Constant of type int.
  • HDF5_PETSC — int = HDF5_PETSC. Constant of type int.
  • HDF5_VIZ — int = HDF5_VIZ. Constant of type int.
  • HDF5_XDMF — int = HDF5_XDMF. Constant of type int.
  • LOAD_BALANCE — int = LOAD_BALANCE. Constant of type int.
  • NATIVE — int = NATIVE. Constant of type int.
  • NOFORMAT — int = NOFORMAT. Constant of type int.
  • VTK_VTR — int = VTK_VTR. Constant of type int.
  • VTK_VTS — int = VTK_VTS. Constant of type int.
  • VTK_VTU — int = VTK_VTU. Constant of type int.

then, like, the two lil dunders that every class has because existing is a whole thing 🌸

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

petsc4py.PETSc.Viewer.Type 👑

class petsc4py.PETSc.Viewer.Type

Bases: object — and yes, the docs for object are chilling at https://docs.python.org/3/builtins/functions.html#object 🫶

Viewer type.

and the class itself is literally still unfolding, so don't you dare scroll away — there's more right below this 💅✨

✨ Attributes Summary ✨

okay bestie, gather round 🫶 these are all the attribute constants, and every single one is a str object. no cap. here's the full list, exactly as the docs drop it:

💖 Attributes Documentation 💖

and now the receipts, bestie — same energy, one by one. each one is literally just its own name assigned to a str type. slay. 💅

and the dunder besties themselves, no notes:

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

✨ Methods Summary ✨

okay bestie, here's the FULL roster of what a Viewer can do for you — every single method, every signature, nothing skipped, no cap 💅

  • ASCII(name[, comm]) — hands you back an ASCII viewer that's connected to the communicator 🌸
  • BINARY([comm]) — gives you the default Type.BINARY viewer tied to the communicator ✨
  • DRAW([comm]) — gives you the default Type.DRAW viewer tied to the communicator 🎨
  • STDERR([comm]) — the standard error viewer, associated with the communicator 👀
  • STDOUT([comm]) — the standard output viewer, associated with the communicator 📤
  • addASCIITab(tabs) — bumps the ASCII tab level up a notch 📈
  • clearDraw() — resets the graphics, wipes the slate clean 🧼
  • create([comm]) — makes you a viewer, periodt 🌟
  • createASCII(name[, mode, comm]) — spins up a viewer of type Type.ASCII 🖋️
  • createBinary(name[, mode, comm]) — spins up a viewer of type Type.BINARY 💾
  • createDraw([display, title, position, size, ...]) — spins up a Type.DRAW viewer 🖼️
  • createHDF5(name[, mode, comm]) — spins up a viewer of type Type.HDF5 🗂️
  • createMPIIO(name[, mode, comm]) — spins up a viewer of type Type.BINARY that supports MPI-IO 🚀
  • createPython([context, comm]) — spins up a Type.PYTHON viewer 🐍
  • createVTK(name[, mode, comm]) — spins up a viewer of type Type.VTK 🧊
  • destroy() — destroys the viewer, bye bye 👋
  • flush() — flushes the viewer 🚿
  • getASCIITab() — returns the current ASCII tab level 🔢
  • getFileMode() — returns the file mode 📁
  • getFileName() — returns the file name 🏷️
  • getFormat() — returns the viewer's format 🧾
  • getPythonContext() — returns the instance of the class that implements the Python methods it needs 🐍
  • getPythonType() — returns the fully qualified Python name of the class the viewer is using 📛
  • getSubViewer([comm]) — returns a viewer defined on a subcommunicator 🪆
  • getType() — returns the type of the viewer 🔍
  • popASCIISynchronized() — disallows ASCII synchronized calls 🚫
  • popASCIITab() — pops an extra tab level that was pushed via pushASCIITab ⏏️
  • popFormat() — pops the format off the viewer 📤
  • printfASCII(msg) — prints a message 💬
  • printfASCIISynchronized(msg) — print a synchronized message 💬
  • pushASCIISynchronized() — allow ASCII synchronized calls
  • pushASCIITab() — push an additional tab level ⬆️
  • pushFormat(format) — push format to the viewer
  • restoreSubViewer(sub) — restore a viewer defined on a subcommunicator
  • setASCIITab(tabs) — set ASCII tab level
  • setDrawInfo([display, title, position, size]) — set window information for a Type.DRAW viewer
  • setFileMode(mode) — set file mode
  • setFileName(name) — set file name 📁
  • setFromOptions() — configure the object from the options database
  • setPythonContext(context) — set the instance of the class implementing the required Python methods 🐍
  • setPythonType(py_type) — set the fully qualified Python name of the class to be used 🐍
  • setType(vwr_type) — set the type of the viewer
  • setUp() — set up the internal data structures for using the viewer
  • subtractASCIITab(tabs) — decrement the ASCII tab level ⬇️
  • useASCIITabs(flag) — enable/disable the use of ASCII tabs
  • view([obj]) — view the viewer
  • viewObjectPython(obj) — view a generic Object 🫶

🎀 Methods Documentation 🎀

classmethod ASCII(name, comm=None)

Bestie, this hands you an ASCII viewer that's chillin' with the communicator you give it. 💖

Collective.

Parameters

Return type

Viewer

Source code at petsc4py/PETSc/Viewer.pyx:604 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L604

classmethod BINARY(comm=None)

Returns the default Type.BINARY viewer associated with the communicator. yes she's giving binary realness ✨

Collective.

Parameters

Return type

Viewer

Source code at petsc4py/PETSc/Viewer.pyx:625 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L625

classmethod DRAW(comm=None)

Returns the default Type.DRAW viewer associated with the communicator — the artsy one, the main character 🎨👑

Collective.

Parameters

Return type

Viewer

Source code at petsc4py/PETSc/Viewer.pyx:643 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L643

classmethod STDERR(comm=None)

Returns the standard error viewer associated with the communicator. it's giving oops energy but make it structured 💀

Collective.

Parameters

Return type

Viewer

Source code at petsc4py/PETSc/Viewer.pyx:586 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L586

classmethod STDOUT(comm=None)

Returns the standard output viewer associated with the communicator. the classic, the icon, the one everyone knows 🌈

Collective.

Parameters

Return type

Viewer

Source code at petsc4py/PETSc/Viewer.pyx:568 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L568

addASCIITab(tabs)

Increments the ASCII tab level. more tabs, more vibes ✨

Collective.

See also:

PetscViewerASCIIAddTab — https://petsc.org/release/manualpages/Viewer/PetscViewerASCIIAddTab.html

Source code at petsc4py/PETSc/Viewer.pyx:690 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L690

Parameters

Return type

None (https://docs.python.org/3/builtins/constants.html#None)

clearDraw()

Resets the graphics. a little refresh moment 🧚

Not collective.

Wrapping up the previous one real quick before we keep it moving 💅

  • See also: PetscViewerDrawClear
  • Source code: petsc4py/PETSc/Viewer.pyx:921
  • Return type: None

create(comm=None) ✨

Makes you a viewer. That's it, that's the vibe. Instant viewer, no cap.

Collective — everybody on the communicator has to show up for this one, it's giving mandatory group chat energy 🫶

Parameters

  • comm (Comm | None) — the MPI communicator; don't pass one and it defaults to Sys.getDefaultComm 🌸

Return type: Self

See also: Sys.getDefaultComm, PetscViewerCreate

Source code: petsc4py/PETSc/Viewer.pyx:179

createASCII(name, mode=None, comm=None) 📝

Spins you up a viewer of type Type.ASCII. Plain text, human-readable, lowkey the humble queen of the viewer world 👑

Collective (yes bestie, everyone's in on it)

Parameters

  • name (str) — the filename this viewer is associated with 🏷️
  • mode (FileMode | str | None) — the mode type
  • comm (Comm | None) — MPI communicator, and if you skip it, it defaults to Sys.getDefaultComm

Return type: Self

See also: create, setType, setFileMode, setFileName, Sys.getDefaultComm, setASCIITab, addASCIITab, subtractASCIITab, getASCIITab

Source code: petsc4py/PETSc/Viewer.pyx:200

createBinary(name, mode=None, comm=None) 🧊

Same deal, but the type is Type.BINARY — raw and unfiltered, no reading glasses required 💀

Collective

Parameters

  • name (str) — the filename this viewer rides with
  • mode (FileMode | str | None) — the mode type
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm

Return type: Self

See also: create, setType, setFileMode, setFileName, Sys.getDefaultComm

Source code: petsc4py/PETSc/Viewer.pyx:238

createDraw(display=None, title=None, position=None, size=None, comm=None) 🎨

Opens you up a Type.DRAW viewer — like, an actual window, on your actual screen. Main character energy fr fr 🪟✨

Collective

Parameters

  • display (str | None) — the X display to use, or None if you just wanna rock the local machine 🖥️
  • title (str | None) — the window title, or None for literally no title (mysterious. iconic.)
  • position (tuple[int, int] | None) — screen coordinates of the upper left corner, or None to let it do its default thing 📍
  • size (tuple[int, int] | int | None) — the window size, or None for default
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm

Return type: Self

See also: Sys.getDefaultComm, PetscViewerDrawOpen

Source code: petsc4py/PETSc/Viewer.pyx:380

createHDF5(name, mode=None, comm=None) 🍓

Viewer time, but make it Type.HDF5. Very structured, very organized, very that girl 💖

Collective

Parameters

  • name (str) — the filename attached to this viewer
  • mode (FileMode | str | None) — the mode type
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm

Return type: Self

See also: create, setType, setFileMode, setFileName, Sys.getDefaultComm

Source code: petsc4py/PETSc/Viewer.pyx:344

createMPIIO(name, mode=None, comm=None) 🛰️

Creates a viewer of type Type.BINARY that supports MPI-IO — parallel I/O said "I got this" 😤

Collective

Parameters

  • name (str) — the filename this viewer is associated with
  • mode (FileMode | str | None) — the mode type
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm

Return type: Self

See also: create, setType, setFileMode, setFileName, Sys.getDefaultComm

Source code: petsc4py/PETSc/Viewer.pyx:271

createPython(context=None, comm=None) 🐍

Creates a viewer of type Type.PYTHON. Python girlies, this one's for you 💅

Collective

Parameters

  • context (Any) — an instance of the Python class that implements the required methods. bestie it's just your object, hand it over 💅
  • comm (Comm | None) — the MPI communicator. leave it as None and it defaults to Sys.getDefaultComm, which is the chill option, honestly 🫶

Return type Self

See also: PETSc Python viewer, setType, setPythonContext, Type.PYTHON

Source code at petsc4py/PETSc/Viewer.pyx:933 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L933)

✨ createVTK(name, mode=None, comm=None) ✨

Create a viewer of type Type.VTK. slay 🌈

Collective. (everyone in the gang shows up for this one, no solo missions 🫂)

Parameters

  • name (str) — the filename associated with the viewer 📁
  • mode (FileMode | str | None) — the mode type. iykyk 🎀
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm 💖

Return type Self

See also: create, setType, setFileMode, setFileName, Sys.getDefaultComm

Source code at petsc4py/PETSc/Viewer.pyx:308 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L308)

💀 destroy() 💀

Destroy the viewer. it's over, it's done, say bye 👋

Collective.

See also: PetscViewerDestroy (https://petsc.org/release/manualpages/Viewer/PetscViewerDestroy.html)

Source code at petsc4py/PETSc/Viewer.pyx:166 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L166)

Return type Self

🌸 flush() 🌸

Flush the viewer. yes bestie, flush it, get all that buffered content out the door 🚪✨

Collective.

See also: PetscViewerFlush (https://petsc.org/release/manualpages/Viewer/PetscViewerFlush.html)

Source code at petsc4py/PETSc/Viewer.pyx:809 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L809)

Return type None

🎀 getASCIITab() 🎀

Return the ASCII tab level. how much indentation is this thing vibing at 🌸

Not collective. (just you, main character, doing your own thing 💅)

See also: setASCIITab, PetscViewerASCIIGetTab (https://petsc.org/release/manualpages/Viewer/PetscViewerASCIIGetTab.html)

Source code at petsc4py/PETSc/Viewer.pyx:676 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L676)

Return type int

🦋 getFileMode() 🦋

Return the file mode. what mode are we in, bestie? 👀

Not collective.

See also: setFileMode, PetscViewerFileGetMode (https://petsc.org/release/manualpages/Viewer/PetscViewerFileGetMode.html)

Source code at petsc4py/PETSc/Viewer.pyx:833 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L833)

Return type FileMode

⭐ getFileName() ⭐

Return file name. the name! of the file! so simple, so iconic 💖

Not collective.

See also: setFileName, PetscViewerFileGetName (https://petsc.org/release/manualpages/Viewer/PetscViewerFileGetName.html)

Source code at petsc4py/PETSc/Viewer.pyx:861 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L861)

Return type str

🔥 getFormat() 🔥

Return the format of the viewer. the vibe of the output, if you will ✨

Not collective.

See also: pushFormat, popFormat, PetscViewerGetFormat (https://petsc.org/release/manualpages/Viewer/PetscViewerGetFormat.html)

Source code at petsc4py/PETSc/Viewer.pyx:488 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L488)

Return type Format

💜 getPythonContext() 💜

Return the instance of the class implementing the required Python methods. it's giving "gimme my object back" 🙈

Not collective.

See also: PETSc Python viewer, setPythonContext

Source code at petsc4py/PETSc/Viewer.pyx:973 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L973)

Return type Any

🧚 getPythonType() 🧚

Return the fully qualified Python name of the class used by the viewer. like module.ClassName, the whole government name, no nicknames bestie 🎀

Not collective.

See also: PETSc Python viewer, setPythonContext, setPythonType, PetscViewerPythonGetType (https://petsc.org/release/manualpages/Viewer/PetscViewerPythonGetType.html)

Source code at petsc4py/PETSc/Viewer.pyx:1003 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L1003)

Return type str

🌈 getSubViewer(comm=None) 🌈

Return a viewer defined on a subcommunicator. yes, a sub viewer, a little baby viewer for a little baby communicator 🍼✨

Collective.

Parameters

  • comm (Comm | None) — the subcommunicator. if it's None, it uses COMM_SELF 🫶

Return type Viewer

Notes

⚠️ bestie you must call restoreSubViewer when you're done. no leaving it hanging, that's not the move 😭

See also: restoreSubViewer, PetscViewerGetSubViewer (https://petsc.org/release/manualpages/Viewer/PetscViewerGetSubViewer.html)

Source code at petsc4py/PETSc/Viewer.pyx:526 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L526)

👑 getType() 👑

Return the type of the viewer. who is she? 💅

Not collective.

See also: setType, PetscViewerGetType (https://petsc.org/release/manualpages/Viewer/PetscViewerGetType.html)

Source code at petsc4py/PETSc/Viewer.pyx:449 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L449)

Return type str

🍓 popASCIISynchronized() 🍓

Disallow ASCII synchronized calls. popping that permission right off, sorry not sorry 🫠

Collective.

See also: printfASCIISynchronized, pushASCIISynchronized, PetscViewerASCIIPopSynchronized (https://petsc.org/release/manualpages/Viewer/PetscViewerASCIIPopSynchronized.html)

Source code at petsc4py/PETSc/Viewer.pyx:729 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L729)

Return type None

🌸 popASCIITab() 🌸

Pop an additional tab level that was pushed via pushASCIITab. undoing the indentation, un-nesting, de-denting, we love to see it ✨

Collective.

See also: pushASCIITab, PetscViewerASCIIPopTab (https://petsc.org/release/manualpages/Viewer/PetscViewerASCIIPopTab.html)

Source code at petsc4py/PETSc/Viewer.pyx:754 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L754)

Return type None

💖 popFormat() 💖

Pop format from the viewer. last in, first out, the format stack said bye 👋

Collective.

See also: pushFormat, PetscViewerPopFormat (https://petsc.org/release/manualpages/Viewer/PetscViewerPopFormat.html)

…and that last one's fine print, bestie 👇 (source at petsc4py/PETSc/Viewer.pyx:514, return type None) — moving on periodt ✨

printfASCII(msg)

Print a message. 🖨️

Collective.

See also: PetscViewerASCIIPrintf (https://petsc.org/release/manualpages/Viewer/PetscViewerASCIIPrintf.html)

Source code at petsc4py/PETSc/Viewer.pyx:779 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L779)

Parameters

Return type

printfASCIISynchronized(msg)

Print a synchronized message. 🎀 Collective, and it's giving teamwork fr fr.

See also: pushASCIISynchronized, PetscViewerASCIISynchronizedPrintf (https://petsc.org/release/manualpages/Viewer/PetscViewerASCIISynchronizedPrintf.html)

Source code at petsc4py/PETSc/Viewer.pyx:793 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L793)

Parameters

Return type

pushASCIISynchronized()

Allow ASCII synchronized calls. Collective. ✨

Think of it as opening the group chat so everyone's messages can actually land in order bestie 💬

See also: printfASCIISynchronized, popASCIISynchronized, PetscViewerASCIIPushSynchronized (https://petsc.org/release/manualpages/Viewer/PetscViewerASCIIPushSynchronized.html)

Source code at petsc4py/PETSc/Viewer.pyx:716 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L716)

Return type

pushASCIITab()

Push an additional tab level. 📑 Collective.

Nesting your output like it's a cute lil thread of replies, love that for you 🌸

See also: popASCIITab, PetscViewerASCIIPushTab (https://petsc.org/release/manualpages/Viewer/PetscViewerASCIIPushTab.html)

Source code at petsc4py/PETSc/Viewer.pyx:742 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L742)

Return type

pushFormat(format)

Push format to the viewer. 💅 Collective.

See also: popFormat, PetscViewerPushFormat (https://petsc.org/release/manualpages/Viewer/PetscViewerPushFormat.html)

Source code at petsc4py/PETSc/Viewer.pyx:502 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L502)

Parameters

  • format (Format (#petsc4py.PETSc.Viewer.Format))

Return type

restoreSubViewer(sub)

Restore a viewer defined on a subcommunicator. Collective 👑

Parameters

  • sub (Viewer (#petsc4py.PETSc.Viewer)) — The subviewer obtained from getSubViewer.

Return type

See also: getSubViewer, PetscViewerRestoreSubViewer (https://petsc.org/release/manualpages/Viewer/PetscViewerRestoreSubViewer.html)

Source code at petsc4py/PETSc/Viewer.pyx:550 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L550)

setASCIITab(tabs)

Set ASCII tab level. Collective ✨

See also: getASCIITab, PetscViewerASCIISetTab (https://petsc.org/release/manualpages/Viewer/PetscViewerASCIISetTab.html)

Source code at petsc4py/PETSc/Viewer.pyx:663 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L663)

Parameters

Return type

setDrawInfo(display=None, title=None, position=None, size=None)

Set window information for a Type.DRAW (#petsc4py.PETSc.Viewer.Type.DRAW) viewer. 🪟 Collective, and it's giving main character window energy fr.

Parameters

Return type

Source code at petsc4py/PETSc/Viewer.pyx:877 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L877)

setFileMode(mode)

Set file mode. Collective 🗂️

See also: getFileMode, PetscViewerFileSetMode (https://petsc.org/release/manualpages/Viewer/PetscViewerFileSetMode.html)

Source code at petsc4py/PETSc/Viewer.pyx:821 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L821)

Parameters

Return type

setFileName(name)

Set file name. Collective 📁

See also: getFileName, PetscViewerFileSetName (https://petsc.org/release/manualpages/Viewer/PetscViewerFileSetName.html)

Source code at petsc4py/PETSc/Viewer.pyx:847 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L847)

Parameters

Return type

setFromOptions()

Configure the object from the options database. Collective ⚙️ Bestie this is the "let the command line decide" button and honestly? iconic.

See also: Working with PETSc options #petsc-options, PetscViewerSetFromOptions (https://petsc.org/release/manualpages/Viewer/PetscViewerSetFromOptions.html)

Source code at petsc4py/PETSc/Viewer.pyx:463 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L463)

Return type

setPythonContext(context)

Set the instance of the class implementing the required Python methods. 🐍✨

Logically collective.

See also: PETSc Python viewer #petsc-python-viewer, getPythonContext, setPythonType

Source code at petsc4py/PETSc/Viewer.pyx:961 (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L961)

Parameters

  • context (Any)

Return type

None

setPythonType(py_type)

Bestie, this one sets the fully qualified Python name of the class you wanna use. Yes, the whole dotted path. Slay.

Collective. 🫶

See also: PETSc Python viewer, setPythonContext, getPythonType, PetscViewerPythonSetType

Source code at petsc4py/PETSc/Viewer.pyx:988

Parameters

  • py_type (str)

Return type

None

setType(vwr_type)

Sets the type of the viewer. Like, what kind of viewer are we even being rn.

Logically collective.

Parameters

  • vwr_type (Type | str) — The type of the viewer.

Return type

None

See also: getType, PetscViewerSetType

Source code at petsc4py/PETSc/Viewer.pyx:430

setUp()

Sets up the internal data structures so the viewer can actually, y'know, do viewer things. The prep era. 💅

Collective.

See also: PetscViewerSetUp

Source code at petsc4py/PETSc/Viewer.pyx:475

Return type

Self

subtractASCIITab(tabs)

Decrements the ASCII tab level. Going back a tab, iconically. The indent just got un-indented, no cap.

Collective.

See also: PetscViewerASCIISubtractTab

Source code at petsc4py/PETSc/Viewer.pyx:703

Parameters

  • tabs (int)

Return type

None

useASCIITabs(flag)

Turn the use of ASCII tabs on or off. A lil toggle for your formatting vibe.

Collective.

See also: PetscViewerASCIIUseTabs

Source code at petsc4py/PETSc/Viewer.pyx:766

Parameters

  • flag (bool)

Return type

None

view(obj=None)

View the viewer. Yes it's a viewer viewing itself, it's giving main character energy and honestly? Respect. 👑

Collective.

Parameters

  • obj (Viewer | Object | None) — A Viewer instance, or None for the default viewer. If none of the above applies, it assumes obj is an instance of Object and it calls the generic view for obj.

Return type

None

Notes

See also: PetscViewerView

Source code at petsc4py/PETSc/Viewer.pyx:138

viewObjectPython(obj)

Views a generic Object. So many objects, so little time. 🦋

Collective.

See also: PETSc Python viewer, setPythonContext, setPythonType, PetscViewerPythonViewObject

Source code at petsc4py/PETSc/Viewer.pyx:1018

Parameters

  • obj (Object)

Return type

None

__init__()

(no params, bestie, it's literally just the init)

classmethod __new__(*args, **kwargs)

🌈 petsc4py.PETSc.ViewerHDF5 🌈

class petsc4py.PETSc.ViewerHDF5

Bases: Viewer

The viewer object for HDF5 file formats. HDF5 girlies rise up, this one's for you. 💖

The Viewer is described in the PETSc manual.

See also: Viewer

✨ Methods Summary ✨

  • create(name[, mode, comm]) — Create a viewer of type Type.HDF5.
  • getGroup() — Return the current group.
  • getTimestep() — Return the current time step.
  • incrementTimestep() — Increment the time step.
  • popGroup() — Pop the current group from the stack.
  • popTimestepping() — Deactivate the timestepping mode.
  • pushGroup(group) — Set the current group.
  • pushTimestepping() — Activate the timestepping mode.
  • setTimestep(timestep) — Set the current time step.

🎀 Methods Documentation 🎀

create(name, mode=None, comm=None)

Creates a viewer of type Type.HDF5. Fresh viewer, just dropped. ✨

Collective.

Parameters

  • name (str) — The filename associated with the viewer.
  • mode (FileMode | str | None) — The mode type.
  • comm (Comm | None) — MPI communicator, defaults to Sys.getDefaultComm.

Return type

Self

See also: Viewer.createHDF5

getGroup()

Bestie this one is so simple it's almost unfair. It just hands you back the current group. That's the whole function. No plot twist, no drama, just vibes. 😌

Not collective — every rank does its own little thing, no group chat required. 💅

See also: pushGroup, popGroup, PetscViewerHDF5GetGroup — https://petsc.org/release/manualpages/Viewer/PetscViewerHDF5GetGroup.html

Source code at petsc4py/PETSc/Viewer.pyx:1044 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L1044

Return type: str — https://docs.python.org/3/builtins/stdtypes.html#str

getTimestep()

Returns the current time step. Like checking what episode you're on. 🍓

Not collective, so it's not a whole-team situation, it's a you situation.

See also: pushTimestepping, setTimestep, incrementTimestep, PetscViewerHDF5GetTimestep — https://petsc.org/release/manualpages/Viewer/PetscViewerHDF5GetTimestep.html

Source code at petsc4py/PETSc/Viewer.pyx:1104 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L1104

Return type: int — https://docs.python.org/3/builtins/functions.html#int

incrementTimestep()

Bumps the time step up. Next chapter, next episode, next timestep, we move. 🔥

Logically collective — everybody's got to be on the same page, no solo missions.

See also: pushTimestepping, setTimestep, getTimestep, PetscViewerHDF5IncrementTimestep — https://petsc.org/release/manualpages/Viewer/PetscViewerHDF5IncrementTimestep.html

Source code at petsc4py/PETSc/Viewer.pyx:1132 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L1132

Return type: None — https://docs.python.org/3/builtins/constants.html#None

popGroup()

Pops the current group right off the stack. It's giving "okay we're done here, bye 👋". No cap.

Logically collective, so the whole squad has to be in on it.

See also: pushGroup, getGroup, PetscViewerHDF5PopGroup — https://petsc.org/release/manualpages/Viewer/PetscViewerHDF5PopGroup.html

Source code at petsc4py/PETSc/Viewer.pyx:1159 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L1159

Return type: None — https://docs.python.org/3/builtins/constants.html#None

popTimestepping()

Turns the timestepping mode off. Closing the tab, putting the phone down, logging off. 🫶

Logically collective, as always with this stack business.

See also: pushTimestepping, PetscViewerHDF5PopTimestepping — https://petsc.org/release/manualpages/Viewer/PetscViewerHDF5PopTimestepping.html

Source code at petsc4py/PETSc/Viewer.pyx:1092 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L1092

Return type: None — https://docs.python.org/3/builtins/constants.html#None

pushGroup(group)

Sets the current group. Pass it the group you want and boom, that's where you live now. 🏠✨

Logically collective — no freelancing.

See also: popGroup, getGroup, PetscViewerHDF5PushGroup — https://petsc.org/release/manualpages/Viewer/PetscViewerHDF5PushGroup.html

Source code at petsc4py/PETSc/Viewer.pyx:1145 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L1145

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

pushTimestepping()

Activates timestepping mode. Periodt. ⭐

Logically collective — the whole team flips this switch together.

See also: popTimestepping, PetscViewerHDF5PushTimestepping — https://petsc.org/release/manualpages/Viewer/PetscViewerHDF5PushTimestepping.html

Source code at petsc4py/PETSc/Viewer.pyx:1080 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L1080

Return type: None — https://docs.python.org/3/builtins/constants.html#None

setTimestep(timestep)

Sets the current time step. You're telling it exactly which timestep you want, no guessing. 🎯

Logically collective, naturally.

See also: pushTimestepping, getTimestep, incrementTimestep, PetscViewerHDF5SetTimestep — https://petsc.org/release/manualpages/Viewer/PetscViewerHDF5SetTimestep.html

Source code at petsc4py/PETSc/Viewer.pyx:1119 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/Viewer.pyx#L1119

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

__init__()

classmethod __new__(*args, **kwargs)

Exceptions 💥

  • petsc4py.PETSc.Error — PETSc Error.

petsc4py.PETSc.Error

exception petsc4py.PETSc.Error

PETSc Error. Yeah, when PETSc is Big Mad, this is the exception you catch. 😭

ierr — PETSc error code.

__init__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

Functions 🛠️

  • garbage_cleanup([comm]) — Clean up unused PETSc objects.
  • garbage_view([comm]) — Print summary of the garbage PETSc objects.

petsc4py.PETSc.garbage_cleanup

petsc4py.PETSc.garbage_cleanup(comm=None)

Cleans up unused PETSc objects. It's the little broom coming through to sweep up everything nobody's holding onto anymore. 🧹💜

Collective.

Notes

If the communicator comm if not provided or it is None, then COMM_WORLD is used. 🌈

Source code at petsc4py/PETSc/cyclicgc.pxi:59 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/cyclicgc.pxi#L59

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

petsc4py.PETSc.garbage_view

petsc4py.PETSc.garbage_view(comm=None)

Prints a summary of the garbage PETSc objects. Like a lil receipt of everything still hanging around uncollected. 🧾👀

Collective.

Notes

Print out garbage summary on each rank of the communicator comm. If no communicator is provided then COMM_WORLD is used. 🌸

Source code at petsc4py/PETSc/cyclicgc.pxi:83 — https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/cyclicgc.pxi#L83

Parameters

Return type: None — https://docs.python.org/3/builtins/constants.html#None

petsc4py.PETSc.DECIDE

petsc4py.PETSc.DECIDE: int = DECIDE

Constant DECIDE of type int (https://docs.python.org/3/builtins/functions.html#int) 💖

petsc4py.PETSc.DEFAULT

petsc4py.PETSc.DEFAULT: int = DEFAULT

Constant DEFAULT of type int (https://docs.python.org/3/builtins/functions.html#int) ✨

petsc4py.PETSc.DETERMINE

petsc4py.PETSc.DETERMINE: int = DETERMINE

Constant DETERMINE of type int (https://docs.python.org/3/builtins/functions.html#int) 🎀

petsc4py.PETSc.CURRENT

petsc4py.PETSc.CURRENT: int = CURRENT

Constant CURRENT of type int (https://docs.python.org/3/builtins/functions.html#int) 🦋

petsc4py.PETSc.UNLIMITED

petsc4py.PETSc.UNLIMITED: int = UNLIMITED

Constant UNLIMITED of type int (https://docs.python.org/3/builtins/functions.html#int) 🌸

petsc4py.PETSc.INFINITY

petsc4py.PETSc.INFINITY: float = INFINITY

Object INFINITY of type float (https://docs.python.org/3/builtins/functions.html#float) 💅

petsc4py.PETSc.NINFINITY

petsc4py.PETSc.NINFINITY: float = NINFINITY

Object NINFINITY of type float (https://docs.python.org/3/builtins/functions.html#float) 🫶

petsc4py.PETSc.PINFINITY

petsc4py.PETSc.PINFINITY: float = PINFINITY

Object PINFINITY of type float (https://docs.python.org/3/builtins/functions.html#float) 😭

petsc4py.PETSc.COMM_NULL

petsc4py.PETSc.COMM_NULL: Comm = COMM_NULL

Object COMM_NULL of type Comm (#petsc4py.PETSc.Comm) 🔥

petsc4py.PETSc.COMM_SELF

petsc4py.PETSc.COMM_SELF: Comm = COMM_SELF

Object COMM_SELF of type Comm (#petsc4py.PETSc.Comm) 👑

petsc4py.PETSc.COMM_WORLD

petsc4py.PETSc.COMM_WORLD: Comm = COMM_WORLD

Object COMM_WORLD of type Comm (#petsc4py.PETSc.Comm) 🌈

💫 PETSC PYTHON TYPES 💫

okay so this is the fun part, bestie. this whole section is about the Python-aware PETSc types — the ones that let you actually be a Python girlie inside the library instead of being stuck in C land the whole time. 🐍✨

Specifically we're talking about:

  • matrices
  • preconditioners
  • Krylov solvers
  • nonlinear solvers
  • ODE integrators
  • and viewers 👀

The low-level, Cython implementation that exposes all these Python methods lives in src/petsc4py/PETSc/libpetsc4py.pyx (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/libpetsc4py.pyx). that's where the magic actually happens, no cap.

The scripts used here can be found at demo/python_types (https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/demo/python_types) — go look, they're literally right there. 🎀

🦋 PETSc Python matrix type 🦋

PETSc hands you a super convenient way to compute the action of linear operators you coded in Python through the petsc4py.PETSc.Mat.Type.PYTHON (#petsc4py.PETSc.Mat.Type.PYTHON) type. it's giving "write the math in Python, let PETSc do the rest." 💖

And it's not just the matrix action either — the implementation can expose extra methods for use within the library. A template class for all the supported methods is right here, and yes every single one of them is in the list:

from petsc4py.typing import Scalar
from petsc4py.PETSc import Mat
from petsc4py.PETSc import Vec
from petsc4py.PETSc import IS
from petsc4py.PETSc import InsertMode
from petsc4py.PETSc import NormType
from petsc4py.PETSc import Viewer

# A template class with the Python methods supported by MATPYTHON

class MatPythonProtocol:
    def mult(self, A: Mat, x: Vec, y: Vec) -> None:
        """Matrix vector multiplication: y = A @ x."""
        ...

    def multAdd(self, A: Mat, x: Vec, y: Vec, z: Vec) -> None:
        """Matrix vector multiplication: z = A @ x + y."""
        ...

    def multTranspose(self, A: Mat, x: Vec, y: Vec) -> None:
        """Transposed matrix vector multiplication: y = A^T @ x."""
        ...

    def multTransposeAdd(self, A: Mat, x: Vec, y: Vec, z: Vec) -> None:
        """Transposed matrix vector multiplication: z = A^T @ x + y."""
        ...

    def multHermitian(self, A: Mat, x: Vec, y: Vec) -> None:
        """Hermitian matrix vector multiplication: y = A^H @ x."""
        ...

    def multHermitianAdd(self, A: Mat, x: Vec, y: Vec, z: Vec) -> None:
        """Hermitian matrix vector multiplication: z = A^H @ x + y."""
        ...

    def view(self, A: Mat, viewer: Viewer) -> None:
        """View the matrix."""
        ...

    def setFromOptions(self, A: Mat) -> None:
        """Process command line for customization."""
        ...

    def multDiagonalBlock(self, A: Mat, x: Vec, y: Vec) -> None:
        """Perform the on-process matrix vector multiplication."""
        ...

    def createVecs(self, A: Mat) -> tuple[Vec, Vec]:
        """Return tuple of vectors (x,y) suitable for A @ x = y."""
        ...

    def scale(self, A: Mat, s: Scalar) -> None:
        """Scale the matrix by a scalar."""
        ...

    def shift(self, A: Mat, s: Scalar) -> None:
        """Shift the matrix by a scalar."""
        ...

    def createSubMatrix(self, A: Mat, r: IS, c: IS, out: Mat) -> Mat:
        """Return the submatrix corresponding to r rows and c columns.

        Matrix out must be reused if not None.

        """
        ...

    def zeroRowsColumns(self, A: Mat, r: IS, diag: Scalar, x: Vec, b: Vec) -> None:
        """Zero rows and columns of the matrix corresponding to the index set r.

Insert diag on the diagonal and modify vectors x and b accordingly if not None.

""" ...

def getDiagonal(self, A: Mat, d: Vec) -> None: """Compute the diagonal of the matrix: d = diag(A).""" ...

def setDiagonal(self, A: Mat, d: Vec, im: InsertMode) -> None: """Set the diagonal of the matrix.""" ...

def diagonalScale(self, A: Mat, L: Vec, R: Vec) -> None: """Perform left and right diagonal scaling if vectors are not None.

A = diag(L)@A@diag(R).

""" ...

def getDiagonalBlock(self, A: Mat) -> Mat: """Return the on-process matrix.""" ...

def setUp(self, A: Mat) -> None: """Perform the required setup.""" ...

def duplicate(self, A: Mat, op: Mat.DuplicateOption) -> Mat: """Duplicate the matrix.""" ...

def copy(self, A: Mat, B: Mat, op: Mat.Structure) -> None: """Copy the matrix: B = A.""" ...

def productSetFromOptions( self, A: Mat, prodtype: str, X: Mat, Y: Mat, Z: Mat ) -> bool: """The boolean flag indicating if the matrix supports prodtype.""" ...

def productSymbolic( self, A: Mat, product: Mat, producttype: str, X: Mat, Y: Mat, Z: Mat ) -> None: """Perform the symbolic stage of the requested matrix product.""" ...

def productNumeric( self, A: Mat, product: Mat, producttype: str, X: Mat, Y: Mat, Z: Mat ) -> None: """Perform the numeric stage of the requested matrix product.""" ...

def zeroEntries(self, A: Mat) -> None: """Set the matrix to zero.""" ...

def norm(self, A: Mat, normtype: NormType) -> float: """Compute the norm of the matrix.""" ...

def solve(self, A: Mat, y: Vec, x: Vec) -> None: """Solve the equation: x = inv(A) y.""" ...

def solveAdd(self, A: Mat, y: Vec, z: Vec, x: Vec) -> None: """Solve the equation: x = inv(A) y + z.""" ...

def solveTranspose(self, A: Mat, y: Vec, x: Vec) -> None: """Solve the equation: x = inv(A)^T y.""" ...

def solveTransposeAdd(self, A: Mat, y: Vec, z: Vec, x: Vec) -> None: """Solve the equation: x = inv(A)^T y + z.""" ...

def SOR( self, A: Mat, b: Vec, omega: float, sortype: Mat.SORType, shift: float, its: int, lits: int, x: Vec, ) -> None: """Perform SOR iterations.""" ...

def conjugate(self, A: Mat) -> None: """Perform the conjugation of the matrix: A = conj(A).""" ...

def imagPart(self, A: Mat) -> None: """Set real part to zero. A = imag(A).""" ...

def realPart(self, A: Mat) -> None: """Set imaginary part to zero. A = real(A).""" ...


---

okay pausing for a sec bestie, because that was a LOT of methods 💀 — but notice how they all follow the same little pattern, right? You write the ones you actually need, PETSc calls them, and the `...` ones just chill there. It's giving "pick your battles <3".

## 🦋 the Poisson 2D glow-up example 🦋

ngl this next bit is the part everyone screenshots. We make an <hotpink>operator</hotpink> that applies the Laplacian on a two-dimensional grid, then we use it to solve the associated linear system. ✨ And here's the tea: the default preconditioner in the script is `petsc4py.PETSc.PC.Type.JACOBI`, which <red>needs</red> to access the diagonal of the matrix — so that's exactly why our class has to hand over a `getDiagonal` method. no cap, that's the whole plot. 👑

------------------------------------------------------------------------

#

Poisson problem. This problem is modeled by the partial

differential equation

#

-Laplacian(u) = 1, 0 < x,y < 1,

#

with boundary conditions

#

u = 0 for x = 0, x = 1, y = 0, y = 1

#

A finite difference approximation with the usual 5-point stencil

is used to discretize the boundary value problem to obtain a

nonlinear system of equations. The problem is solved in a 2D

rectangular domain, using distributed arrays (DAs) to partition

the parallel grid.

#

------------------------------------------------------------------------

We first import petsc4py and sys to initialize PETSc

import sys import petsc4py

petsc4py.init(sys.argv)

Import the PETSc module

from petsc4py import PETSc

Here we define a class representing the discretized operator

This allows us to apply the operator "matrix-free"

class Poisson2D: def __init__(self, da): self.da = da self.localX = da.createLocalVec()

# This is the method that PETSc will look for when applying # the operator. X is the PETSc input vector, Y the output vector, # while mat is the PETSc matrix holding the PETSc datastructures. def mult(self, mat, X, Y): # Grid sizes mx, my = self.da.getSizes() hx, hy = (1.0 / m for m in [mx, my])

# Bounds for the local part of the grid this process owns (xs, xe), (ys, ye) = self.da.getRanges()

# Map global vector to local vectors self.da.globalToLocal(X, self.localX)

# We can access the vector data as NumPy arrays x = self.da.getVecArray(self.localX) y = self.da.getVecArray(Y)

# Loop on the local grid and compute the local action of the operator for j in range(ys, ye): for i in range(xs, xe): u = x[i, j] # center u_e = u_w = u_n = u_s = 0 if i > 0: u_w = x[i - 1, j] # west if i < mx - 1: u_e = x[i + 1, j] # east if j > 0: u_s = x[i, j - 1] # south if j < ny - 1: u_n = x[i, j + 1] # north u_xx = (-u_e + 2 * u - u_w) * hy / hx u_yy = (-u_n + 2 * u - u_s) * hx / hy y[i, j] = u_xx + u_yy

# This is the method that PETSc will look for when the diagonal of the matrix is needed. def getDiagonal(self, mat, D): mx, my = self.da.getSizes() hx, hy = (1.0 / m for m in [mx, my]) (xs, xe), (ys, ye) = self.da.getRanges()

d = self.da.getVecArray(D)

# Loop on the local grid and compute the diagonal for j in range(ys, ye): for i in range(xs, xe): d[i, j] = 2 * hy / hx + 2 * hx / hy

# The class can contain other methods that PETSc won't use def formRHS(self, B): b = self.da.getVecArray(B) mx, my = self.da.getSizes() hx, hy = (1.0 / m for m in [mx, my]) (xs, xe), (ys, ye) = self.da.getRanges() for j in range(ys, ye): for i in range(xs, xe): b[i, j] = 1 * hx * hy

Access the option database and read options from the command line

OptDB = PETSc.Options() nx, ny = OptDB.getIntArray( 'grid', (16, 16) ) # Read -grid <int,int>, defaults to 16,16

Create the distributed memory implementation for structured grid

da = PETSc.DMDA().create([nx, ny], stencil_width=1)

Create vectors to hold the solution and the right-hand side

x = da.createGlobalVec() b = da.createGlobalVec()

Instantiate an object of our Poisson2D class

pde = Poisson2D(da)

Create a PETSc matrix of type Python using pde as context

A = PETSc.Mat().create(comm=da.comm) A.setSizes([x.getSizes(), b.getSizes()]) A.setType(PETSc.Mat.Type.PYTHON) A.setPythonContext(pde) A.setUp()

Create a Conjugate Gradient Krylov solver

ksp = PETSc.KSP().create() ksp.setType(PETSc.KSP.Type.CG)

Use diagonal preconditioning

ksp.getPC().setType(PETSc.PC.Type.JACOBI)

Allow command-line customization

ksp.setFromOptions()

Assemble right-hand side and solve the linear system

pde.formRHS(b) ksp.setOperators(A) ksp.solve(b, x)

Here we programmatically visualize the solution

if OptDB.getBool('plot', True): # Modify the option database: keep the X window open for 1 second OptDB['draw_pause'] = 1

# Obtain a viewer of type DRAW draw = PETSc.Viewer.DRAW(x.comm)

# View the vector in the X window draw(x)

We can also visualize the solution by command line options

For example, we can dump a VTK file with:

#

$ python poisson2d.py -plot 0 -view_solution vtk:sol.vts:

#

or obtain the same visualization as programmatically done above as:

#

$ python poisson2d.py -plot 0 -view_solution draw -draw_pause 1

# x.viewFromOptions('-view_solution')


lowkey obsessed with this one because it does ✨everything✨ — a matrix-free operator, a Python context, a solver, a viewer, and command-line customisation all in like 100 lines. main character energy fr fr. 💅

Also peep the two command-line ways to look at your solution, both living in comments up there:

$ python poisson2d.py -plot 0 -view_solution vtk:sol.vts:

$ python poisson2d.py -plot 0 -view_solution draw -draw_pause 1


## 🎀 PETSc Python preconditioner type 🎀

okay so same deal but for preconditioners now. The protocol for the `petsc4py.PETSc.PC.Type.PYTHON` preconditioner is:

from petsc4py.PETSc import KSP from petsc4py.PETSc import PC from petsc4py.PETSc import Mat from petsc4py.PETSc import Vec from petsc4py.PETSc import Viewer

A template class with the Python methods supported by PCPYTHON

class PCPythonProtocol: def apply(self, pc: PC, b: Vec, x: Vec) -> None: """Apply the preconditioner on vector b, return in x.""" ...

def applySymmetricLeft(self, pc: PC, b: Vec, x: Vec) -> None: """Apply the symmetric left part of the preconditioner on vector b, return in x.""" ...

def applySymmetricRight(self, pc: PC, b: Vec, x: Vec) -> None: """Apply the symmetric right part of the preconditioner on vector b, return in x.""" ...

def applyTranspose(self, pc: PC, b: Vec, x: Vec) -> None: """Apply the transposed preconditioner on vector b, return in x.""" ...

def applyMat(self, pc: PC, B: Mat, X: Mat) -> None: """Apply the preconditioner on a block of right-hand sides B, return in X.""" ...

def preSolve(self, pc: PC, ksp: KSP, b: Vec, x: Vec) -> None: """Callback called at the beginning of a Krylov method.

This method is allowed to modify the right-hand side b and the initial guess x.

""" ...


> careful bestie — `preSolve` is *allowed* to modify the right-hand side `b` and the initial guess `x`. That's real power and real responsibility, so don't be out here changing things on a whim. 🙈

So like, once your preconditioner has done its little apply moment, there's a whole *cast* of optional callbacks it can also support. Here's the rest of the template squad:

def postSolve(self, pc: PC, ksp: KSP, b: Vec, x: Vec) -> None: """Callback called at the end of a Krylov method.

This method is allowed to modify the right-hand side b and the solution x.

"""

def view(self, pc: PC, viewer: Viewer) -> None: """View the preconditioner.""" ...

def setFromOptions(self, pc: PC) -> None: """Process command line for customization.""" ...

def setUp(self, pc: PC) -> None: """Perform the required setup.""" ...

def reset(self, pc: PC) -> None: """Reset the preconditioner.""" ...


<purple>Important vibe check</purple>: `postSolve` is the one place you're *allowed* to mess with the right-hand side `b` <italic>and</italic> the solution `x`. Everything else you've got in your lane, bestie. 💅

Okay so here's a real example, no cap. We're building a Jacobi preconditioner — it needs to peek at the diagonal of the matrix, and then its whole deal is just multiplying the inverse diagonal by the input vector, pointwise:

The user-defined Python class implementing the Jacobi method.

class myJacobi: # Setup the internal data. In this case, we access the matrix diagonal. def setUp(self, pc): _, P = pc.getOperators() self.D = P.getDiagonal()

# Apply the preconditioner def apply(self, pc, x, y): y.pointwiseDivide(x, self.D)


And then we run the script that tests our matrix class, but ✨fancy✨ — we pass command line arguments to tell it to use *our* preconditioner:

$ python mat.py -pc_type python -pc_python_type pc.myJacobi -ksp_view KSP Object: 1 MPI process type: cg maximum iterations=10000, initial guess is zero tolerances: relative=1e-05, absolute=1e-50, divergence=10000. left preconditioning using PRECONDITIONED norm type for convergence test PC Object: 1 MPI process type: python Python: pc.myJacobi linear system matrix, which is also used to construct the preconditioner: Mat Object: 1 MPI process type: python rows=256, cols=256 Python: __main__.Poisson2D


It's giving *immaculate*, honestly. 🎀

---

### 🌈 PETSc Python linear solver type

So the protocol for the `petsc4py.PETSc.KSP.Type.PYTHON <#petsc4py.PETSc.KSP.Type.PYTHON>` Krylov solver goes a lil something like this:

from petsc4py.PETSc import KSP from petsc4py.PETSc import Vec from petsc4py.PETSc import Viewer

A template class with the Python methods supported by KSPPYTHON

class KSPPythonProtocol: def solve(self, ksp: KSP, b: Vec, x: Vec) -> None: """Solve the linear system with right-hand side b. Return solution in x.""" ...

def solveTranspose(self, ksp: KSP, b: Vec, x: Vec) -> None: """Solve the transposed linear system with right-hand side b. Return solution in x.""" ...

def view(self, ksp: KSP, viewer: Viewer) -> None: """View the Krylov solver.""" ...

def setFromOptions(self, ksp: KSP) -> None: """Process command line for customization.""" ...

def setUp(self, ksp: KSP) -> None: """Perform the required setup.""" ...

def buildSolution(self, ksp: KSP, x: Vec) -> None: """Compute the solution vector.""" ...

def buildResidual(self, ksp: KSP, t: Vec, r: Vec) -> None: """Compute the residual vector, return it in r. t is a scratch working vector.""" ...

def reset(self, ksp: KSP) -> None: """Reset the Krylov solver.""" ...


### PETSc Python nonlinear solver type (TODO)

<purple>Yeah so this one is literally still a TODO, bestie. Nothing here yet — don't make me lie to you. 🙈</purple>

### PETSc Python ode-integrator type (TODO)

<purple>And this one? Also TODO. The vibes are pending. 💀</purple>

---

### 🚀 PETSc Python optimization solver type

Now THIS one is fun — the protocol for the `petsc4py.PETSc.TAO.Type.PYTHON <#petsc4py.PETSc.TAO.Type.PYTHON>` TAO optimizer:

The user-defined Python class implementing the gradient descent.

from petsc4py import PETSc

class myGradientDescent: def create(self, tao): # Create a line search type with constant step size. self._ls = PETSc.TAOLineSearch().create(comm=PETSc.COMM_SELF) self._ls.useTAORoutine(tao) self._ls.setType(PETSc.TAOLineSearch.Type.UNIT) self._ls.setInitialStepLength(0.2)

def solve(self, tao): # Get solution and Jacobian vector. x = tao.getSolution() gradient = tao.getGradient()[0]

# Prepare search direction for line search. search_direction = gradient.copy()

# Optimization loop. for it in range(tao.getMaximumIterations()): tao.setIterationNumber(it)

# Compute search_direction. # search_direction = -gradient tao.computeGradient(x, gradient) gradient.copy(search_direction) search_direction.scale(-1)

# Apply line search: # x += .2 search_direction f, s, reason = self._ls.apply(x, gradient, search_direction)

if reason < 0: raise RuntimeError('LS failed.')

# Log and update internal state. tao.monitor(f=f, res=gradient.norm())

# Convergence check. if tao.checkConverged() > 0: break


In the example below <pink>(yes we know, we just showed you one, but hear me out)</pink>, we create a simple gradient based (first order) optimization solver. A `petsc4py.PETSc.TAOLineSearch.Type.UNIT <#petsc4py.PETSc.TAOLineSearch.Type.UNIT>` line search with step size `0.2` is used. So the update becomes

x^{k+1} = x^k + 0.2 \nabla f(x^k).


> **Note:**
> This setup is also well suited for non-linesearch-based quasi-Newton optimization algorithms. It provides a general interface for using the TAO provided state and functionality on a custom algorithm. 🫶

The optimizer can be used from Python as

PETSc.TAO().createPython(myGradientDescent())


or selected through the PETSc options as

python tao.py -tao_type python -tao_python_type tao.myGradientDescent


> **Tip:**
> The prefix `tao` to `tao_python_type` is dependant on the Python module in which the optimizer is located. It aligns with the fully qualified Python module name. 👑

---

### 👀 PETSc Python viewer

And last but never least, the protocol for the `petsc4py.PETSc.Viewer.Type.PYTHON <#petsc4py.PETSc.Viewer.Type.PYTHON>` viewer:

from petsc4py.PETSc import Object from petsc4py.PETSc import Viewer

A template class with the Python methods supported by PETSCVIEWERPYTHON

class PetscViewerPythonProtocol: def viewObject(self, viewer: Viewer, obj: Object) -> None: """View a generic object.""" ...

def setUp(self, viewer: Viewer) -> None: """Setup the viewer.""" ...

def setFromOptions(self, viewer: Viewer) -> None: """Process command line for customization.""" ...

def flush(self, viewer: Viewer) -> None: """Flush the viewer.""" ...

def view(self, viewer: Viewer, outviewer: Viewer) -> None: """View the viewer.""" ...


---

# ✨ WORKING WITH PETSC OPTIONS ✨

Okay bestie, this is <rainbow>the</rainbow> moment. One of the most powerful things PETSc does is let you configure objects straight from the command line. So you can swap out the method being used or tweak a parameter <italic>without touching a single line of source code</italic>. Periodt. 🎀 For the whole deep dive, the PETSc manual lives at `https://petsc.org/release/manual/getting_started.html#the-options-database`.

So if you wanna use command-line options in a petsc4py program, you HAVE to initialize the module like this — no skips:

We first import petsc4py and sys to initialize PETSc

import sys, petsc4py petsc4py.init(sys.argv)

Import the PETSc module

from petsc4py import PETSc


Then you can just hand it command-line options when you run a script:

$ python foo.py -ksp_type gmres -ksp_gmres_restart 100 -ksp_view


And when the whole "pass `sys.argv`" thing isn't possible? <purple>No stress</purple> — PETSc options can also be specified via environment variables or configuration files, like:

$ PETSC_OPTIONS='-ksp_type gmres -ksp_gmres_restart 100 -ksp_view' python foo.py


You can read command-line options through an instance of the `Options` class. Like so:

OptDB = PETSc.Options() n = OptDB.getInt('n', 16) eta = OptDB.getReal('eta', 0.014) alpha = OptDB.getScalar('alpha', -12.3)


So in this setup, if the script is run with

$ python foo.py -n 50 -alpha 8.8


then the options `n` and `alpha` get the values `50` and `8.8` respectively, while `eta` gets assigned the default value it was given: `0.014`. Slay. 💅

Oh and — the options database is *also* accessible as a Python dictionary, so you can override, insert, or delete an option whenever you feel like it:

OptDB['draw_pause'] = 1 del OptDB['draw_pause']


Lowkey iconic. 🌸

## 🍓 Poisson in 2D 🍓

Okay bestie, this demo is the moment. It solves a constant coefficient Poisson problem on a regular grid ✨ — real "main character" energy. The source code for this demo can be downloaded here <../../_static/poisson2d.py>.
  • u_{xx} - u_{yy} = 1 \quad\textsf{in}\quad [0,1]^2\ u = 0 \quad\textsf{on the boundary.}

So this is a naïve, parallel implementation — and I say naïve with love, okay?? — using `n` interior grid points per dimension, with a lexicographic ordering of the nodes. It's giving "simple on purpose".

This code is kept as simple as possible. However, simplicity comes at a price 💀 — and the price is that here we use a naive decomposition that does **not** lead to an optimal communication complexity for the matrix-vector product. An optimal complexity decomposition of a structured grid could be achieved using `PETSc.DMDA`. So like, keep that in your back pocket for when you're famous 👑

This demo is structured as a script to be executed using:

$ python poisson2d.py


potentially with additional options passed at the end of the command. Yes queen, we love a flexible script 💅

At the start of your script, call `petsc4py.init` passing `sys.argv` so that command-line arguments to the script are passed through to PETSc 🫶

import sys import petsc4py

petsc4py.init(sys.argv)


The full petsc4py API is to be found in the `petsc4py.PETSc` module. Don't be shy, it's all in there:

from petsc4py import PETSc


PETSc is extensively programmable using the `PETSc.Options` database. For more information see working with PETSc Options.

OptDB = PETSc.Options()


Grid size and spacing using a default value of `5` ⭐ The user can specify a different number of points in each direction by passing the `-n` option to the script.

n = OptDB.getInt('n', 5) h = 1.0 / (n + 1)


Matrices are instances of the `PETSc.Mat` class. Iconic honestly:

A = PETSc.Mat()


Create the underlying PETSc C Mat object. You **can** omit the comm argument if your objects live on `PETSc.COMM_WORLD` — but fr fr, it is a dangerous choice to rely on default values for such important arguments 😭 don't do it bestie.

A.create(comm=PETSc.COMM_WORLD)


Specify global matrix shape with a tuple ✨

A.setSizes((n * n, n * n))


The call above implicitly assumes that we leave the parallel decomposition of the matrix rows to PETSc by using `PETSc.DECIDE` for local sizes. It is equivalent to:

A.setSizes(((PETSc.DECIDE, n * n), (PETSc.DECIDE, n * n)))


Here we use a sparse matrix of AIJ type 💖 Various matrix formats can be selected:

A.setType(PETSc.Mat.Type.AIJ)


Finally we allow the user to set any options they want to on the matrix from the command line. Generous queen 🎀

A.setFromOptions()


Insertion into some matrix types is **vastly** more efficient if we preallocate space rather than allow this to happen dynamically. Here we hint the number of nonzeros to be expected on each row. Lowkey a glow-up for your performance 🔥

A.setPreallocationNNZ(5)


We can now write out our finite difference matrix assembly using conventional Python syntax. `Mat.getOwnershipRange` is used to retrieve the range of rows local to this processor.

def index_to_grid(r): """Convert a row number into a grid point.""" return (r // n, r % n)

rstart, rend = A.getOwnershipRange() for row in range(rstart, rend): i, j = index_to_grid(row) A[row, row] = 4.0 / h2 if i > 0: column = row - n A[row, column] = -1.0 / h2 if i < n - 1: column = row + n A[row, column] = -1.0 / h2 if j > 0: column = row - 1 A[row, column] = -1.0 / h2 if j < n - 1: column = row + 1 A[row, column] = -1.0 / h**2


At this stage, any exchange of information required in the matrix assembly process has **not** occurred 🙈 (scandalous). We achieve this by calling `Mat.assemblyBegin` and then `Mat.assemblyEnd`.

A.assemblyBegin() A.assemblyEnd()


We set up an additional option so that the user can print the matrix by passing `-view_mat` to the script.

A.viewFromOptions('-view_mat')


PETSc represents all linear solvers as preconditioned Krylov subspace methods of type `PETSc.KSP`. Here we create a KSP object for a conjugate gradient solver preconditioned with an algebraic multigrid method. She's overachieving, we respect it 👑

ksp = PETSc.KSP() ksp.create(comm=A.getComm()) ksp.setType(PETSc.KSP.Type.CG) ksp.getPC().setType(PETSc.PC.Type.GAMG)


We set the matrix in our linear solver and allow the user to program the solver with options.

ksp.setOperators(A) ksp.setFromOptions()


Since the matrix knows its size and parallel distribution, we can retrieve appropriately-scaled vectors using `Mat.createVecs` 💫 PETSc vectors are objects of type `PETSc.Vec`. Here we set the right-hand side of our system to a vector of ones, and then solve. Periodt.

x, b = A.createVecs() b.set(1.0) ksp.solve(b, x)


Finally, allow the user to print the solution by passing `-view_sol` to the script.

x.viewFromOptions('-view_sol')


---

## ✨ Things to try ✨

- Show the solution with `-view_sol`. 🌈
- Show the matrix with `-view_mat`. 👀
- Change the resolution with `-n`. 🔍
- Use a direct solver by passing `-ksp_type preonly -pc_type lu`. 💅
- Run in parallel on two processors using:

mpiexec -n 2 python poisson2d.py


---

# 💜 DOCUMENTATION STANDARDS FOR PETSC4PY 💜

Subject to exceptions given below, new contributions to petsc4py **must** include type annotations for function parameters and results, and docstrings on every class, function and method. No skipping, bestie — the vibes demand completeness 💖

The documentation should be consistent with the corresponding C API documentation, including copying text where this is appropriate. More in-depth documentation from the C API (such as extended discussions of algorithmic or performance factors) should **not** be copied. Like, take the facts, leave the rambling 🦋

## 🌸 Docstring standards 🌸

Docstrings are to be written in `numpydoc` format. That's the format.

The first line of a class, function or method docstring must be a short description of the method in **imperative mood** ("Return the norm of the matrix.") — "Return" is to be preferred over "Get" in this sentence. A blank line **must** follow this description. Use one-liner descriptions for properties. Short and slay ✨

If the corresponding C API documentation of a method lists a function as being collective, then this information **must** be repeated on the next line of the docstring. Valid strings are: "Not collective.", "Logically collective.", "Collective.", "Neighborwise collective.", or "Collective the first time it is called". Copy them exactly, no freestyling 💅

The initial description section can contain more information if this is useful. In particular, if there is a PETSc manual chapter about a class, then this should be referred to from here.

Use double backticks around literals (like strings and numbers), e.g., ``2``, ``"foo"``.

Reference PETSc functions simply using backticks, e.g., KSP refers to the PETSc C documentation for KSP. Do **not** use URLs in docstrings. Always use Intersphinx references. No links, only lore 🔥

The following sections describe the use of numpydoc sections. Other sections allowed by numpydoc may be included if they are useful.

## 🎀 Parameters 🎀

This is required for methods unless there are no parameters, or it will be completely obvious to even a novice user what the parameters do.

If a class has a non-trivial constructor, the arguments of the constructor and their types **must** be explicitly documented within this section.

For methods, types should only be specified in this section if for some reason the types provided by typing prove to be inadequate. If no type is being specified, do **not** include a colon (`:`) to the right of the parameter name.

Use `Sys.getDefaultComm` when specifying the default communicator.

## 🫶 Returns 🫶

This should only be specified if the return value is not obvious from the initial description and typing.

If a "Returns" section is required, the type of the returned items **must** be specified, even if this duplicates typing information. Yes, even then. Duplication is the price of clarity, and we're paying it 😤

## ⭐ See Also ⭐

If any of the following apply, then this section is required. The order of entries is as follows. Other links are permitted in this section if they add information useful to users.

- Every `setFromOptions` must include the link `petsc_options`.
- Any closely related part of the petsc4py API not already linked in the docstring should appear (e.g. setters and getters should cross-refer).
- If there is a corresponding C API documentation page, this must be linked from the "See also" section, e.g. `petsc.MatSetValues`.

End docstring with an empty line — "closing three quotation marks must be on a line by itself, preferably preceded by a blank line". iykyk 🙈

## 🧚 Type hint standards 🧚

- If returning `self`, use `-> Self` in function signature.
- Type hints are **not** required when the static type signature includes a PETSc type (e.g. `Vec x`). These will be automatically generated. This will also work for `= None`. When using type hints, use spacing around the equals in any `= None`.
- Communicators in type signatures must use Python typing instead of c-typing (i.e. `comm: Comm` **not** `Comm comm`). This is because communicators can come from mpi4py and not just the `petsc4py.PETSc.Comm` class.
- For petsc4py native types that are strings, the type is `argument: KSP.Type | str` (**not** e.g.: `KSPType argument`). If the type is strictly an enum the `| str` can be omitted. Full signature example:

def setType(self, ksp_type: KSP.Type | str) -> None:


- If a NumPy array is returned, use `ArrayBool`/`ArrayInt`/`ArrayReal`/`ArrayScalar` as the return type.

---

# 👑 Author 👑

Lisandro Dalcin

---

> And that's a wrap on the whole page, bestie 🥹💖 you made it all the way to the end, which is genuinely iconic of you. Cute little sign-off moment: this beauty came from source/version **3.25**, dated **Oct 05, 2026**, and the page footer is `PETSC4PY(3)`. Slay, bye 👋🌸

---
📦 where this page comes from