Man page - petsc4py(3)

Packages contains this manual

Package: python-petsc4py-doc
apt-get install python-petsc4py-doc

Manuals in package:

petsc4py(3)

Documentations in package:

python-petsc4py-doc

Manual

PETSC4PY

NAME

petsc4py - PETSc for Python

Author

Lisandro Dalcin

Contact

dalcinl@gmail.com

Web Site

https://gitlab.com/petsc/petsc

Date

Mar 12, 2025

Abstract

This document describes petsc4py , a Python wrapper to the PETSc libraries.

PETSc (the Portable, Extensible Toolkit for Scientific Computation) 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 standard for all message-passing communication.

This package provides an important subset of PETSc functionalities and uses NumPy to efficiently manage input and output of array data.

A good friend of petsc4py is:

•

mpi4py : Python bindings for MPI , the Message Passing Interface .

Other projects depend on petsc4py:

•

slepc4py : Python bindings for SLEPc , the Scalable Library for Eigenvalue Problem Computations .

PETSC OVERVIEW

PETSc 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 standard for all message-passing communication.

PETSc is intended for use in large-scale application projects [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.

PETSc is easy to use for beginners [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.
[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.22, 2024. - http://dx.doi.org/10.2172/2205494 , - 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.

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.
	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.
	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 and its dependencies ( mpi4py is optional but highly recommended):

$ python -m pip install mpi4py petsc petsc4py

Install from the PETSc source tree

First build PETSc . Next cd to the top of the PETSc source tree and set the PETSC_DIR and PETSC_ARCH environment variables. Run:

$ python -m pip install src/binding/petsc4py

The installation of petsc4py supports multiple PETSC_ARCH in the form of colon separated list:

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

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

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

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 ${PETSC_DIR/doc/requirements.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.

CONTRIBUTING

Contributions from the user community are welcome. See the PETSc developers documentation for general information on contributions.

New contributions to petsc4py must adhere with the coding standards. We use cython-lint for Cython and 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 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='-W' -C src/binding/petsc4py/docs/source

WARNING:

The docstrings must not cause Sphinx warnings.

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.

	•		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.22, 2024. https://doi.org/10.2172/2205494 , - https://petsc.org/release/docs/manual/manual.pdf

REFERENCE

Image grohtml-288464-1.png

petsc4py

The PETSc for Python package.

This package is an interface to PETSc libraries.

Functions

Image grohtml-288464-2.png

petsc4py.get_config

petsc4py.get_config()

Return a dictionary with information about PETSc.
Return type

dict [ str , str ]

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.

Example

Using Python distutils or NumPy distutils:

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

Return type

str

petsc4py.init

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

Initialize PETSc.
Parameters

	•		args ( str \| list[str] \| None ) -- Command-line arguments, usually the sys.argv list
	•		arch ( str \| None ) -- Specific configuration to use
	•		comm ( Intracomm \| None ) -- MPI commmunicator

Return type

None

Notes

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

petsc4py.typing

Typing support.

Attributes

Image grohtml-288464-3.png

petsc4py.typing.Scalar

petsc4py.typing.Scalar = float | complex

Scalar type.

Scalars can be either float or complex (but not both) depending on how PETSc was configured ( ./configure --with-scalar-type=real|complex ).

petsc4py.typing.ArrayBool

petsc4py.typing.ArrayBool

Array of bool .

alias of ndarray [ tuple [ int , ...], dtype [ bool ]]

petsc4py.typing.ArrayInt

petsc4py.typing.ArrayInt

Array of int .

alias of ndarray [ tuple [ int , ...], dtype [ int ]]

petsc4py.typing.ArrayReal

petsc4py.typing.ArrayReal

Array of float .

alias of ndarray [ tuple [ int , ...], dtype [ float ]]

petsc4py.typing.ArrayComplex

petsc4py.typing.ArrayComplex

Array of complex .

alias of ndarray [ tuple [ int , ...], dtype [ complex ]]

petsc4py.typing.ArrayScalar

petsc4py.typing.ArrayScalar

Array of Scalar numbers.

alias of ndarray [ tuple [ int , ...], dtype [ float | complex ]]

petsc4py.typing.DimsSpec

petsc4py.typing.DimsSpec

Dimensions specification.

N-tuples indicates N-dimensional grid sizes.

alias of tuple [ int , ...]

petsc4py.typing.AccessModeSpec

petsc4py.typing.AccessModeSpec

Access mode specification.
Possible values are:

	•		'rw' Read-Write mode.
	•		'r' Read-only mode.
	•		'w' Write-only mode.
	•		None as 'rw' .

alias of Literal ['rw', 'r', 'w'] | None

petsc4py.typing.InsertModeSpec

petsc4py.typing.InsertModeSpec = petsc4py.PETSc.InsertMode | bool |
None

Insertion mode specification.
Possible values are:

	•		InsertMode.ADD_VALUES Add new value to existing one.
	•		InsertMode.INSERT_VALUES Replace existing entry with new value.
	•		None as InsertMode.INSERT_VALUES .
	•		False as InsertMode.INSERT_VALUES .
	•		True as InsertMode.ADD_VALUES .

SEE ALSO:

InsertMode

petsc4py.typing.ScatterModeSpec

petsc4py.typing.ScatterModeSpec = petsc4py.PETSc.ScatterMode | bool |
str | None

Scatter mode specification.
Possible values are:

	•		ScatterMode.FORWARD Forward mode.
	•		ScatterMode.REVERSE Reverse mode.
	•		None as ScatterMode.FORWARD .
	•		False as ScatterMode.FORWARD .
	•		True as ScatterMode.REVERSE .
	•		'forward' as ScatterMode.FORWARD .
	•		'reverse' as ScatterMode.REVERSE .

SEE ALSO:

ScatterMode

petsc4py.typing.LayoutSizeSpec

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

int or 2- tuple of int describing the layout sizes.

A single int indicates global size. A tuple of int indicates (local_size, global_size) .

SEE ALSO:

Sys.splitOwnership

petsc4py.typing.NormTypeSpec

petsc4py.typing.NormTypeSpec = petsc4py.PETSc.NormType | None

Norm type specification.

Possible values include:

	•		NormType.NORM_1 The 1-norm: Σₙ abs(xₙ) for vectors, maxₙ (Σᵢ abs(xₙᵢ)) for matrices.
	•		NormType.NORM_2 The 2-norm: √(Σₙ xₙ²) for vectors, largest singular values for matrices.
	•		NormType.NORM_INFINITY The ∞-norm: maxₙ abs(xₙ) for vectors, maxᵢ (Σₙ abs(xₙᵢ)) for matrices.
	•		NormType.NORM_FROBENIUS The Frobenius norm: same as 2-norm for vectors, √(Σₙᵢ xₙᵢ²) for matrices.
	•		NormType.NORM_1_AND_2 Compute both NormType.NORM_1 and NormType.NORM_2 .
	•		None as NormType.NORM_2 for vectors, NormType.NORM_FROBENIUS for matrices.

SEE ALSO:

PETSc.NormType , NormType

petsc4py.typing.PetscOptionsHandlerFunction

petsc4py.typing.PetscOptionsHandlerFunction

Callback for processing extra options.

alias of Callable [[ Object ], None ]

petsc4py.typing.MatAssemblySpec

petsc4py.typing.MatAssemblySpec = petsc4py.PETSc.Mat.AssemblyType |
bool | None

Matrix assembly specification.
Possible values are:

	•		Mat.AssemblyType.FINAL
	•		Mat.AssemblyType.FLUSH
	•		None as Mat.AssemblyType.FINAL
	•		False as Mat.AssemblyType.FINAL
	•		True as Mat.AssemblyType.FLUSH

SEE ALSO:

MatAssemblyType

petsc4py.typing.MatSizeSpec

petsc4py.typing.MatSizeSpec = int | tuple[int, int] | tuple[tuple[int,
int], tuple[int, int]]

int or (nested) tuple of int describing the matrix sizes.

If int then rows = columns. A single tuple of int indicates (rows, columns) . A nested tuple of int indicates ((local_rows, rows), (local_columns, columns)) .

SEE ALSO:

Sys.splitOwnership

petsc4py.typing.MatBlockSizeSpec

petsc4py.typing.MatBlockSizeSpec = int | tuple[int, int]

The row and column block sizes.

If a single int is provided then rows and columns share the same block size.

petsc4py.typing.CSRIndicesSpec

petsc4py.typing.CSRIndicesSpec

CSR indices format specification.

A 2-tuple carrying the (row_start, col_indices) information.

alias of tuple [ Sequence [ int ], Sequence [ int ]]

petsc4py.typing.CSRSpec

petsc4py.typing.CSRSpec

CSR format specification.

A 3-tuple carrying the (row_start, col_indices, values) information.

alias of tuple [ Sequence [ int ], Sequence [ int ], Sequence [ float | - complex ]]

petsc4py.typing.NNZSpec

petsc4py.typing.NNZSpec

Nonzero pattern specification.

A single int corresponds to fixed number of non-zeros per row. A Sequence of int indicates different non-zeros per row. If a 2- tuple is used, the elements of the tuple corresponds to the on-process and off-process parts of the matrix.

SEE ALSO:

MatSeqAIJSetPreallocation , MatMPIAIJSetPreallocation

alias of int | Sequence [ int ] | tuple [ Sequence [ int ], Sequence [- int ]]

petsc4py.typing.MatNullFunction

petsc4py.typing.MatNullFunction

PETSc.NullSpace callback.

alias of Callable [[ NullSpace , Vec ], None ]

petsc4py.typing.DMCoarsenHookFunction

petsc4py.typing.DMCoarsenHookFunction

PETSc.DM coarsening hook callback.

alias of Callable [[ DM , DM ], None ]

petsc4py.typing.DMRestrictHookFunction

petsc4py.typing.DMRestrictHookFunction

PETSc.DM restriction hook callback.

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

petsc4py.typing.KSPRHSFunction

petsc4py.typing.KSPRHSFunction

PETSc.KSP right-hand side function callback.

alias of Callable [[ KSP , Vec ], None ]

petsc4py.typing.KSPOperatorsFunction

petsc4py.typing.KSPOperatorsFunction

PETSc.KSP operators function callback.

alias of Callable [[ KSP , Mat , Mat ], None ]

petsc4py.typing.KSPConvergenceTestFunction

petsc4py.typing.KSPConvergenceTestFunction

PETSc.KSP convergence test callback.

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

petsc4py.typing.KSPMonitorFunction

petsc4py.typing.KSPMonitorFunction

PETSc.KSP monitor callback.

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

petsc4py.typing.KSPPreSolveFunction

petsc4py.typing.KSPPreSolveFunction

PETSc.KSP pre solve callback.

alias of Callable [[ KSP , Vec , Vec ], None ]

petsc4py.typing.KSPPostSolveFunction

petsc4py.typing.KSPPostSolveFunction

PETSc.KSP post solve callback.

alias of Callable [[ KSP , Vec , Vec ], None ]

petsc4py.typing.SNESMonitorFunction

petsc4py.typing.SNESMonitorFunction

SNES monitor callback.

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

petsc4py.typing.SNESObjFunction

petsc4py.typing.SNESObjFunction

SNES objective function callback.

alias of Callable [[ SNES , Vec ], None ]

petsc4py.typing.SNESFunction

petsc4py.typing.SNESFunction

SNES residual function callback.

alias of Callable [[ SNES , Vec , Vec ], None ]

petsc4py.typing.SNESJacobianFunction

petsc4py.typing.SNESJacobianFunction

SNES Jacobian callback.

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

petsc4py.typing.SNESGuessFunction

petsc4py.typing.SNESGuessFunction

SNES initial guess callback.

alias of Callable [[ SNES , Vec ], None ]

petsc4py.typing.SNESUpdateFunction

petsc4py.typing.SNESUpdateFunction

SNES step update callback.

alias of Callable [[ SNES , int ], None ]

petsc4py.typing.SNESLSPreFunction

petsc4py.typing.SNESLSPreFunction

SNES linesearch pre-check update callback.

alias of Callable [[ Vec , Vec ], None ]

petsc4py.typing.SNESNGSFunction

petsc4py.typing.SNESNGSFunction

SNES nonlinear Gauss-Seidel callback.

alias of Callable [[ SNES , Vec , Vec ], None ]

petsc4py.typing.SNESConvergedFunction

petsc4py.typing.SNESConvergedFunction

SNES convergence test callback.

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

petsc4py.typing.TSRHSFunction

petsc4py.typing.TSRHSFunction

TS right-hand side function callback.

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

petsc4py.typing.TSRHSJacobian

petsc4py.typing.TSRHSJacobian

TS right-hand side Jacobian callback.

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

petsc4py.typing.TSRHSJacobianP

petsc4py.typing.TSRHSJacobianP

TS right-hand side parameter Jacobian callback.

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

petsc4py.typing.TSIFunction

petsc4py.typing.TSIFunction

TS implicit function callback.

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

petsc4py.typing.TSIJacobian

petsc4py.typing.TSIJacobian

TS implicit Jacobian callback.

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

petsc4py.typing.TSIJacobianP

petsc4py.typing.TSIJacobianP

TS implicit parameter Jacobian callback.

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

petsc4py.typing.TSI2Function

petsc4py.typing.TSI2Function

TS implicit 2nd order function callback.

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

petsc4py.typing.TSI2Jacobian

petsc4py.typing.TSI2Jacobian

TS implicit 2nd order Jacobian callback.

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

petsc4py.typing.TSI2JacobianP

petsc4py.typing.TSI2JacobianP

TS implicit 2nd order parameter Jacobian callback.

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

petsc4py.typing.TSMonitorFunction

petsc4py.typing.TSMonitorFunction

TS monitor callback.

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

petsc4py.typing.TSPreStepFunction

petsc4py.typing.TSPreStepFunction

TS pre-step callback.

alias of Callable [[ TS ], None ]

petsc4py.typing.TSPostStepFunction

petsc4py.typing.TSPostStepFunction

TS post-step callback.

alias of Callable [[ TS ], None ]

petsc4py.typing.TSIndicatorFunction

petsc4py.typing.TSIndicatorFunction

TS event indicator callback.

alias of Callable [[ TS , float , Vec , ndarray [ tuple [ int , ...], - dtype [ float ]]], None ]

petsc4py.typing.TSPostEventFunction

petsc4py.typing.TSPostEventFunction

TS post-event callback.

alias of Callable [[ TS , ndarray [ tuple [ int , ...], dtype [ int ]], - float , Vec , bool ], None ]

petsc4py.typing.TAOObjectiveFunction

petsc4py.typing.TAOObjectiveFunction

TAO objective function callback.

alias of Callable [[ TAO , Vec ], float ]

petsc4py.typing.TAOGradientFunction

petsc4py.typing.TAOGradientFunction

TAO objective gradient callback.

alias of Callable [[ TAO , Vec , Vec ], None ]

petsc4py.typing.TAOObjectiveGradientFunction

petsc4py.typing.TAOObjectiveGradientFunction

TAO objective function and gradient callback.

alias of Callable [[ TAO , Vec , Vec ], float ]

petsc4py.typing.TAOHessianFunction

petsc4py.typing.TAOHessianFunction

TAO objective Hessian callback.

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

petsc4py.typing.TAOUpdateFunction

petsc4py.typing.TAOUpdateFunction

TAO update callback.

alias of Callable [[ TAO , int ], None ]

petsc4py.typing.TAOMonitorFunction

petsc4py.typing.TAOMonitorFunction

TAO monitor callback.

alias of Callable [[ TAO ], None ]

petsc4py.typing.TAOConvergedFunction

petsc4py.typing.TAOConvergedFunction

TAO convergence test callback.

alias of Callable [[ TAO ], None ]

petsc4py.typing.TAOJacobianFunction

petsc4py.typing.TAOJacobianFunction

TAO Jacobian callback.

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

petsc4py.typing.TAOResidualFunction

petsc4py.typing.TAOResidualFunction

TAO residual callback.

alias of Callable [[ TAO , Vec , Vec ], None ]

petsc4py.typing.TAOJacobianResidualFunction

petsc4py.typing.TAOJacobianResidualFunction

TAO Jacobian residual callback.

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

petsc4py.typing.TAOVariableBoundsFunction

petsc4py.typing.TAOVariableBoundsFunction

TAO variable bounds callback.

alias of Callable [[ TAO , Vec , Vec ], None ]

petsc4py.typing.TAOConstraintsFunction

petsc4py.typing.TAOConstraintsFunction

TAO constraints callback.

alias of Callable [[ TAO , Vec , Vec ], None ]

petsc4py.typing.TAOLSObjectiveFunction

petsc4py.typing.TAOLSObjectiveFunction

TAOLineSearch objective function callback.

alias of Callable [[ TAOLineSearch , Vec ], float ]

petsc4py.typing.TAOLSGradientFunction

petsc4py.typing.TAOLSGradientFunction

TAOLineSearch objective gradient callback.

alias of Callable [[ TAOLineSearch , Vec , Vec ], None ]

petsc4py.typing.TAOLSObjectiveGradientFunction

petsc4py.typing.TAOLSObjectiveGradientFunction

TAOLineSearch objective function and gradient callback.

alias of Callable [[ TAOLineSearch , Vec , Vec ], float ]

petsc4py.PETSc

Portable, Extensible Toolkit for Scientific Computation.

Basic constants:

DECIDE

Use a default value for an int or float parameter.

DEFAULT

Use a default value chosen by PETSc.

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.

CURRENT

Do not change the current value that is set.

UNLIMITED

For a parameter that is a bound, such as the maximum number of iterations, do not bound the value.

More constants:
INFINITY

Very large real value.

NINFINITY

Very large negative real value.

PINFINITY

Very large positive real value, same as INFINITY .

Classes

Image grohtml-288464-4.png

petsc4py.PETSc.AO

class petsc4py.PETSc.AO

Bases: Object

Application ordering object.

Enumerations

Image grohtml-288464-5.png

petsc4py.PETSc.AO.Type

class petsc4py.PETSc.AO.Type

Bases: object

The application ordering types.

Attributes Summary

Image grohtml-288464-6.png

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

Methods Summary

Image grohtml-288464-7.png

Methods Documentation
app2petsc(indices)

Map an application-defined ordering to the PETSc ordering.

Collective.

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

indices ( Sequence[int] | IS ) -- The indices; to be replaced with their mapped values.

Return type

Sequence [ int ] | IS

SEE ALSO:

petsc2app , AOApplicationToPetscIS , - AOApplicationToPetsc

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

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

	•		app ( Sequence[int] \| IS ) -- The application ordering.
	•		petsc ( Sequence[int] \| IS \| None ) -- Another ordering (may be None to indicate the natural ordering, that is 0, 1, 2, 3, ...).
	•		comm ( Comm \| None ) -- MPI communicator, defaults to Sys.getDefaultComm .

Return type

Self

SEE ALSO:

createMemoryScalable , createMapping , AOCreateBasicIS , AOCreateBasic

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

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

	•		app ( Sequence[int] \| IS ) -- The application ordering.
	•		petsc ( Sequence[int] \| IS \| None ) -- Another ordering. May be None to indicate the identity ordering.
	•		comm ( Comm \| None ) -- MPI communicator, defaults to Sys.getDefaultComm .

Return type

Self

SEE ALSO:

createBasic , AOCreateMappingIS , AOCreateMapping

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

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

Return a memory scalable application ordering using two orderings.

Collective.

Comparing with createBasic , this routine trades memory with message communication.
Parameters

	•		app ( Sequence[int] \| IS ) -- The application ordering.
	•		petsc ( Sequence[int] \| IS \| None ) -- Another ordering (may be None to indicate the natural ordering, that is 0, 1, 2, 3, ...).
	•		comm ( Comm \| None ) -- MPI communicator, defaults to Sys.getDefaultComm .

Return type

Self

SEE ALSO:

createBasic , createMapping , AOCreateMemoryScalableIS , AOCreateMemoryScalable

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

destroy()

Destroy the application ordering.

Collective.

SEE ALSO:

AODestroy

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

Self

getType()

Return the application ordering type.

Not collective.

SEE ALSO:

AOGetType

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

str

petsc2app(indices)

Map a PETSc ordering to the application-defined ordering.

Collective.

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

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

indices ( Sequence[int] | IS ) -- The indices; to be 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)

Display the application ordering.

Collective.
Parameters

viewer ( Viewer | None ) -- A Viewer to display the ordering.

Return type

None

SEE ALSO:

AOView

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

petsc4py.PETSc.Comm

class petsc4py.PETSc.Comm

Bases: object

Communicator object.

Predefined instances:
COMM_NULL

The null (or invalid) communicator.

COMM_SELF

The self communicator.

COMM_WORLD

The world communicator.

SEE ALSO:

Sys.setDefaultComm , Sys.getDefaultComm

Methods Summary

Image grohtml-288464-8.png

Attributes Summary

Image grohtml-288464-9.png

Methods Documentation
barrier()

Barrier synchronization.

Collective.

Source code at petsc4py/PETSc/Comm.pyx:123
Return type

None

destroy()

Destroy the communicator.

Collective.

SEE ALSO:

PetscCommDestroy

Source code at petsc4py/PETSc/Comm.pyx:61
Return type

None

duplicate()

Duplicate the communicator.

Collective.

SEE ALSO:

PetscCommDuplicate

Source code at petsc4py/PETSc/Comm.pyx:79
Return type

Self

getRank()

Return the rank of the calling processes in the communicator.

Not collective.

Source code at petsc4py/PETSc/Comm.pyx:111
Return type

int

getSize()

Return the number of processes in the communicator.

Not collective.

Source code at petsc4py/PETSc/Comm.pyx:99
Return type

int

tompi4py()

Convert communicator to mpi4py .

Not collective.

SEE ALSO:

mpi4py.MPI.Comm , mpi4py.MPI.Intracomm

Source code at petsc4py/PETSc/Comm.pyx:155
Return type

Intracomm

Attributes Documentation
fortran

Fortran handle.

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

rank

Communicator rank.

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

size

Communicator size.

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

petsc4py.PETSc.DM

class petsc4py.PETSc.DM

Bases: Object

An object describing a computational grid or mesh.

Enumerations

Image grohtml-288464-10.png

petsc4py.PETSc.DM.BoundaryType

class petsc4py.PETSc.DM.BoundaryType

Bases: object

DM Boundary types.

Attributes Summary

Image grohtml-288464-11.png

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

PERIODIC: int = PERIODIC

Constant PERIODIC of type int

TWIST: int = TWIST

Constant TWIST of type int

petsc4py.PETSc.DM.PolytopeType

class petsc4py.PETSc.DM.PolytopeType

Bases: object

The DM cell types.

Attributes Summary

Image grohtml-288464-12.png

Attributes Documentation
FV_GHOST: int = FV_GHOST

Constant FV_GHOST of type int

HEXAHEDRON: int = HEXAHEDRON

Constant HEXAHEDRON of type int

INTERIOR_GHOST: int = INTERIOR_GHOST

Constant INTERIOR_GHOST of type int

POINT: int = POINT

Constant POINT of type int

POINT_PRISM_TENSOR: int = POINT_PRISM_TENSOR

Constant POINT_PRISM_TENSOR of type int

PYRAMID: int = PYRAMID

Constant PYRAMID of type int

QUADRILATERAL: int = QUADRILATERAL

Constant QUADRILATERAL of type int

QUAD_PRISM_TENSOR: int = QUAD_PRISM_TENSOR

Constant QUAD_PRISM_TENSOR of type int

SEGMENT: int = SEGMENT

Constant SEGMENT of type int

SEG_PRISM_TENSOR: int = SEG_PRISM_TENSOR

Constant SEG_PRISM_TENSOR of type int

TETRAHEDRON: int = TETRAHEDRON

Constant TETRAHEDRON of type int

TRIANGLE: int = TRIANGLE

Constant TRIANGLE of type int

TRI_PRISM: int = TRI_PRISM

Constant TRI_PRISM of type int

TRI_PRISM_TENSOR: int = TRI_PRISM_TENSOR

Constant TRI_PRISM_TENSOR of type int

UNKNOWN: int = UNKNOWN

Constant UNKNOWN of type int

UNKNOWN_CELL: int = UNKNOWN_CELL

Constant UNKNOWN_CELL of type int

UNKNOWN_FACE: int = UNKNOWN_FACE

Constant UNKNOWN_FACE of type int

petsc4py.PETSc.DM.ReorderDefaultFlag

class petsc4py.PETSc.DM.ReorderDefaultFlag

Bases: object

The DM reordering default flags.

Attributes Summary

Image grohtml-288464-13.png

Attributes Documentation
FALSE: int = FALSE

Constant FALSE of type int

NOTSET: int = NOTSET

Constant NOTSET of type int

TRUE: int = TRUE

Constant TRUE of type int

petsc4py.PETSc.DM.Type

class petsc4py.PETSc.DM.Type

Bases: object

DM types.

Attributes Summary

Image grohtml-288464-14.png

Attributes Documentation
COMPOSITE: str = COMPOSITE

Object COMPOSITE of type str

DA: str = DA

Object DA of type str

FOREST: str = FOREST

Object FOREST of type str

MOAB: str = MOAB

Object MOAB of type str

NETWORK: str = NETWORK

Object NETWORK of type str

P4EST: str = P4EST

Object P4EST of type str

P8EST: str = P8EST

Object P8EST of type str

PATCH: str = PATCH

Object PATCH of type str

PLEX: str = PLEX

Object PLEX of type str

PRODUCT: str = PRODUCT

Object PRODUCT of type str

REDUNDANT: str = REDUNDANT

Object REDUNDANT of type str

SHELL: str = SHELL

Object SHELL of type str

SLICED: str = SLICED

Object SLICED of type str

STAG: str = STAG

Object STAG of type str

SWARM: str = SWARM

Object SWARM of type str

Methods Summary

Image grohtml-288464-15.png

Attributes Summary

Image grohtml-288464-16.png

Methods Documentation
adaptLabel(label)

Adapt a DM based on a DMLabel .

Collective.
Parameters

label ( str ) -- The name of the DMLabel .

Return type

SEE ALSO:

DMAdaptLabel

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

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

Return a mesh adapted to the specified metric field.

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

SEE ALSO:

DMAdaptMetric

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

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

Add a callback to be executed when restricting to a coarser grid.

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

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

addField(field, label=None)

Add a field to a DM object.

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

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

appendOptionsPrefix(prefix)

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

Logically collective.

SEE ALSO:

Working with PETSc options , setOptionsPrefix , - DMAppendOptionsPrefix

Source code at petsc4py/PETSc/DM.pyx:298
Parameters

prefix ( str | None )

Return type

None

clearDS()

Remove all discrete systems from the DM .

Logically collective.

SEE ALSO:

DMClearDS

Source code at petsc4py/PETSc/DM.pyx:691
Return type

None

clearFields()

Remove all fields from the DM .

Logically collective.

SEE ALSO:

DMClearFields

Source code at petsc4py/PETSc/DM.pyx:634
Return type

None

clearLabelStratum(name, value)

Remove all points from a stratum.

Not collective.
Parameters

	•		name ( str ) -- The label name.
	•		value ( int ) -- The stratum value.

Return type

None

SEE ALSO:

DMClearLabelStratum

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

clearLabelValue(name, point, value)

Remove a point from a DMLabel with given value.

Not collective.
Parameters

	•		name ( str ) -- The label name.
	•		point ( int ) -- The mesh point.
	•		value ( int ) -- The label value for the point.

Return type

None

SEE ALSO:

DMClearLabelValue

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

clone()

Return the cloned DM .

Collective.

SEE ALSO:

DMClone

Source code at petsc4py/PETSc/DM.pyx:155
Return type

coarsen(comm=None)

Return a coarsened DM object.

Collective.
Parameters

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

Return type

SEE ALSO:

DMCoarsen

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

coarsenHierarchy(nlevels)

Coarsen this DM and return the coarsened DM hierarchy.

Collective.
Parameters

nlevels ( int ) -- The number of levels of coarsening.

Return type

list

SEE ALSO:

DMCoarsenHierarchy

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

convert(dm_type)

Return a DM converted to another DM .

Collective.
Parameters

dm_type ( Type | str ) -- The new DM.Type , use “same” for the same type.

Return type

SEE ALSO:

DM.Type , DMConvert

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

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

Copy the discrete systems for this DM into another DM .

Collective.
Parameters

	•		dm ( DM ) -- The DM that the discrete fields are copied into.
	•		minDegree -- The minimum polynommial degree for the discretization, or None for no limit
	•		maxDegree -- The maximum polynommial degree for the discretization, or None for no limit

Return type

None

SEE ALSO:

DMCopyDS

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

copyDisc(dm)

Copy fields and discrete systems of a DM into another DM .

Collective.
Parameters

dm ( DM ) -- The DM that the fields and discrete systems are copied into.

Return type

None

SEE ALSO:

DMCopyDisc

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

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

Copy the discretizations of this DM into another DM .

Collective.
Parameters

	•		dm ( DM ) -- The DM that the fields are copied into.
	•		minDegree -- The minimum polynommial degree for the discretization, or None for no limit
	•		maxDegree -- The maximum polynommial degree for the discretization, or None for no limit

Return type

None

SEE ALSO:

DMCopyFields

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

create(comm=None)

Return an empty DM .

Collective.
Parameters

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

Return type

Self

SEE ALSO:

DMCreate

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

createDS()

Create discrete systems.

Collective.

SEE ALSO:

DMCreateDS

Source code at petsc4py/PETSc/DM.pyx:679
Return type

None

createFieldDecomposition()

Return a list of IS objects.

Not collective.

Notes

The user is responsible for freeing all requested arrays.

SEE ALSO:

DMCreateFieldDecomposition

Source code at petsc4py/PETSc/DM.pyx:2222
Return type

tuple [ list , list , list ]

createGlobalVec()

Return a global vector.

Collective.

SEE ALSO:

DMCreateGlobalVector

Source code at petsc4py/PETSc/DM.pyx:798
Return type

Vec

createInjection(dm)

Return the injection matrix into a finer DM .

Collective.
Parameters

dm ( DM ) -- The second, finer DM object.

Return type

Mat

SEE ALSO:

DMCreateInjection

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

createInterpolation(dm)

Return the interpolation matrix to a finer DM .

Collective.
Parameters

dm ( DM ) -- The second, finer DM .

Return type

tuple [ Mat , Vec ]

SEE ALSO:

DMCreateInterpolation

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

createLabel(name)

Create a label of the given name if it does not already exist.

Not collective.
Parameters

name ( str ) -- The label name.

Return type

None

SEE ALSO:

DMCreateLabel

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

createLocalVec()

Return a local vector.

Not collective.

SEE ALSO:

DMCreateLocalVector

Source code at petsc4py/PETSc/DM.pyx:812
Return type

Vec

createMassMatrix(dmf)

Return the mass matrix between this DM and the given DM .

Collective.
Parameters

dmf ( DM ) -- The second DM .

Return type

Mat

SEE ALSO:

DMCreateMassMatrix

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

createMat()

Return an empty matrix.

Collective.

SEE ALSO:

DMCreateMatrix

Source code at petsc4py/PETSc/DM.pyx:1380
Return type

Mat

createRestriction(dm)

Return the restriction matrix between this DM and the given DM .

Collective.
Parameters

dm ( DM ) -- The second, finer DM object.

Return type

Mat

SEE ALSO:

DMCreateRestriction

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

createSectionSF(localsec, globalsec)

Create the SF encoding the parallel DOF overlap for the DM .

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.

SEE ALSO:

DM.getSectionSF , DMCreateSectionSF

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

createSubDM(fields)

Return IS and DM encapsulating a subproblem.

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 ]

SEE ALSO:

DMCreateSubDM

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

destroy()

Destroy the object.

Collective.

SEE ALSO:

DMDestroy

Source code at petsc4py/PETSc/DM.pyx:121
Return type

Self

getAppCtx()

Return the application context.

Source code at petsc4py/PETSc/DM.pyx:343
Return type

Any

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

Return an auxiliary vector for region.

Not collective.
Parameters

	•		label ( str \| None ) -- The name of the DMLabel .
	•		value ( int \| None ) -- Indicate the region.
	•		part ( int \| None ) -- The equation part, or 0 is unused.

Return type

Vec

SEE ALSO:

DM.getLabel , DMGetAuxiliaryVec

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

getBasicAdjacency()

Return the flags for determining variable influence.

Not collective.
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:

DMGetBasicAdjacency

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

getBlockSize()

Return the inherent block size associated with a DM .

Not collective.

SEE ALSO:

DMGetBlockSize

Source code at petsc4py/PETSc/DM.pyx:770
Return type

int

getBoundingBox()

Return the dimension of embedding space for coordinates values.

Not collective.

SEE ALSO:

DMGetBoundingBox

Source code at petsc4py/PETSc/DM.pyx:1306
Return type

tuple [ tuple [ float , float ], ...]

getCellCoordinateDM()

Return the cell coordinate DM .

Collective.

SEE ALSO:

DMGetCellCoordinateDM

Source code at petsc4py/PETSc/DM.pyx:1159
Return type

getCellCoordinateSection()

Return the cell coordinate layout over the DM .

Collective.

SEE ALSO:

DMGetCellCoordinateSection

Source code at petsc4py/PETSc/DM.pyx:1194
Return type

Section

getCellCoordinates()

Return a global vector with the cellwise coordinates.

Collective.

SEE ALSO:

DMGetCellCoordinates

Source code at petsc4py/PETSc/DM.pyx:1226
Return type

Vec

getCellCoordinatesLocal()

Return a local vector with the cellwise coordinates.

Collective.

SEE ALSO:

DMGetCellCoordinatesLocal

Source code at petsc4py/PETSc/DM.pyx:1258
Return type

Vec

getCoarseDM()

Return the coarse DM .

Collective.

SEE ALSO:

DMGetCoarseDM

Source code at petsc4py/PETSc/DM.pyx:1020
Return type

getCoarsenLevel()

Return the number of coarsenings.

Not collective.

SEE ALSO:

DMGetCoarsenLevel

Source code at petsc4py/PETSc/DM.pyx:1629
Return type

int

getCoordinateDM()

Return the coordinate DM .

Collective.

SEE ALSO:

DMGetCoordinateDM

Source code at petsc4py/PETSc/DM.pyx:1048
Return type

getCoordinateDim()

Return the dimension of embedding space for coordinates values.

Not collective.

SEE ALSO:

DMGetCoordinateDim

Source code at petsc4py/PETSc/DM.pyx:238
Return type

int

getCoordinateSection()

Return coordinate values layout over the mesh.

Collective.

SEE ALSO:

DMGetCoordinateSection

Source code at petsc4py/PETSc/DM.pyx:1063
Return type

Section

getCoordinates()

Return a global vector with the coordinates associated.

Collective.

SEE ALSO:

DMGetCoordinates

Source code at petsc4py/PETSc/DM.pyx:1095
Return type

Vec

getCoordinatesLocal()

Return a local vector with the coordinates associated.

Collective the first time it is called.

SEE ALSO:

DMGetCoordinatesLocal

Source code at petsc4py/PETSc/DM.pyx:1127
Return type

Vec

getCoordinatesLocalized()

Check if the coordinates have been localized for cells.

Not collective.

SEE ALSO:

DMGetCoordinatesLocalized

Source code at petsc4py/PETSc/DM.pyx:1292
Return type

bool

getDS()

Return default DS .

Not collective.

SEE ALSO:

DMGetDS

Source code at petsc4py/PETSc/DM.pyx:703
Return type

getDimension()

Return the topological dimension of the DM .

Not collective.

SEE ALSO:

DMGetDimension

Source code at 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:586

getFieldAdjacency(field)

Return the flags for determining variable influence.

Not collective.
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:416

getGlobalSection()

Return the Section encoding the global data layout for the DM .

Collective the first time it is called.

SEE ALSO:

DMGetGlobalSection

Source code at petsc4py/PETSc/DM.pyx:1762
Return type

Section

getGlobalVec(name=None)

Return a global vector.

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

SEE ALSO:

restoreGlobalVec , DMGetGlobalVector , - DMGetNamedGlobalVector

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

getLGMap()

Return local mapping to global mapping.

Collective.

SEE ALSO:

DMGetLocalToGlobalMapping

Source code at petsc4py/PETSc/DM.pyx:1003
Return type

LGMap

getLabel(name)

Return the label of a given name.

Not collective.

SEE ALSO:

DMGetLabel

Source code at petsc4py/PETSc/DM.pyx:1704
Parameters

name ( str )

Return type

DMLabel

getLabelIdIS(name)

Return an IS of all values that the DMLabel takes.

Not collective.
Parameters

name ( str ) -- The label name.

Return type

SEE ALSO:

DMLabelGetValueIS , DMGetLabelIdIS

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

getLabelName(index)

Return the name of nth label.

Not collective.
Parameters

index ( int ) -- The label number.

Return type

str

SEE ALSO:

DMGetLabelName

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

getLabelOutput(name)

Return the output flag for a given label.

Not collective.
Parameters

name ( str ) -- The label name.

Return type

bool

SEE ALSO:

DMGetLabelOutput

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

getLabelSize(name)

Return the number of values that the DMLabel takes.

Not collective.
Parameters

name ( str ) -- The label name.

Return type

int

SEE ALSO:

DMLabelGetNumValues , DMGetLabelSize

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

getLabelValue(name, point)

Return the value in DMLabel for the given point.

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

getLocalBoundingBox()

Return the bounding box for the piece of the DM .

Not collective.

SEE ALSO:

DMGetLocalBoundingBox

Source code at petsc4py/PETSc/DM.pyx:1323
Return type

tuple [ tuple [ float , float ], ...]

getLocalSection()

Return the Section encoding the local data layout for the DM .

Not collective.

SEE ALSO:

DMGetGlobalSection

Source code at petsc4py/PETSc/DM.pyx:1735
Return type

Section

getLocalVec(name=None)

Return a local vector.

Not collective.
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 restoreLocalVec .

SEE ALSO:

restoreLocalVec , DMGetLocalVector , - DMGetNamedLocalVector

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

getNumFields()

Return the number of fields in the DM .

Not collective.

SEE ALSO:

DMGetNumFields

Source code at petsc4py/PETSc/DM.pyx:546
Return type

int

getNumLabels()

Return the number of labels defined by on the DM .

Not collective.

SEE ALSO:

DMGetNumLabels

Source code at petsc4py/PETSc/DM.pyx:1867
Return type

int

getOptionsPrefix()

Return the prefix used for searching for options in the database.

Not collective.

SEE ALSO:

Working with PETSc options , setOptionsPrefix , - DMGetOptionsPrefix

Source code at petsc4py/PETSc/DM.pyx:284
Return type

str

getPointSF()

Return the SF encoding the parallel DOF overlap for the DM .

Not collective.

SEE ALSO:

DMGetPointSF

Source code at petsc4py/PETSc/DM.pyx:1840
Return type

getRefineLevel()

Return the refinement level.

Not collective.

SEE ALSO:

DMGetRefineLevel

Source code at petsc4py/PETSc/DM.pyx:1597
Return type

int

getSectionSF()

Return the Section encoding the parallel DOF overlap.

Collective the first time it is called.

SEE ALSO:

DMGetSectionSF

Source code at petsc4py/PETSc/DM.pyx:1809
Return type

getStratumIS(name, value)

Return the points in a label stratum.

Not collective.
Parameters

	•		name ( str ) -- The label name.
	•		value ( int ) -- The stratum value.

Return type

SEE ALSO:

DMGetStratumIS

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

getStratumSize(name, value)

Return the number of points in a label stratum.

Not collective.
Parameters

	•		name ( str ) -- The label name.
	•		value ( int ) -- The stratum value.

Return type

int

SEE ALSO:

DMGetStratumSize

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

getType()

Return the DM type name.

Not collective.

SEE ALSO:

DMGetType

Source code at petsc4py/PETSc/DM.pyx:192
Return type

str

globalToLocal(vg, vl, addv=None)

Update local vectors from global vector.

Neighborwise collective.
Parameters

	•		vg ( Vec ) -- The global vector.
	•		vl ( Vec ) -- The local vector.
	•		addv ( InsertModeSpec \| None ) -- Insertion mode.

Return type

None

SEE ALSO:

DMGlobalToLocalBegin , DMGlobalToLocalEnd

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

hasLabel(name)

Determine whether the DM has a label.

Not collective.
Parameters

name ( str ) -- The label name.

Return type

bool

SEE ALSO:

DMHasLabel

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

load(viewer)

Return a DM stored in binary.

Collective.
Parameters

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

Return type

Self

Notes

When using Viewer.Type.HDF5 format, one can save multiple DMPlex meshes in a single HDF5 files. This in turn requires one to name the DMPlex object with Object.setName before saving it with DM.view and before loading it with DM.load for identification of the mesh object.

SEE ALSO:

DM.view , DM.load , Object.setName , DMLoad

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

localToGlobal(vl, vg, addv=None)

Update global vectors from local vector.

Neighborwise collective.
Parameters

	•		vl ( Vec ) -- The local vector.
	•		vg ( Vec ) -- The global vector.
	•		addv ( InsertModeSpec \| None ) -- Insertion mode.

Return type

None

SEE ALSO:

DMLocalToGlobalBegin , DMLocalToGlobalEnd

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

localToLocal(vl, vlg, addv=None)

Map the values from a local vector to another local vector.

Neighborwise collective.
Parameters

	•		vl ( Vec ) -- The local vector.
	•		vlg ( Vec ) -- The global vector.
	•		addv ( InsertModeSpec \| None ) -- Insertion mode.

Return type

None

SEE ALSO:

DMLocalToLocalBegin , DMLocalToLocalEnd

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

localizeCoordinates()

Create local coordinates for cells having periodic faces.

Collective.

Notes

Used if the mesh is periodic.

SEE ALSO:

DMLocalizeCoordinates

Source code at petsc4py/PETSc/DM.pyx:1340
Return type

None

refine(comm=None)

Return a refined DM object.

Collective.
Parameters

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

Return type

SEE ALSO:

DMRefine

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

refineHierarchy(nlevels)

Refine this DM and return the refined DM hierarchy.

Collective.
Parameters

nlevels ( int ) -- The number of levels of refinement.

Return type

list

SEE ALSO:

DMRefineHierarchy

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

removeLabel(name)

Remove and destroy the label by name.

Not collective.
Parameters

name ( str ) -- The label name.

Return type

None

SEE ALSO:

DMRemoveLabel

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

restoreGlobalVec(vg, name=None)

Restore a global vector obtained with getGlobalVec .

Logically collective.
Parameters

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

Return type

None

SEE ALSO:

getGlobalVec , DMRestoreGlobalVector , - DMRestoreNamedGlobalVector

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

restoreLocalVec(vl, name=None)

Restore a local vector obtained with getLocalVec .

Not collective.
Parameters

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

Return type

None

SEE ALSO:

getLocalVec , DMRestoreLocalVector , - DMRestoreNamedLocalVector

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

setAppCtx(appctx)

Set the application context.

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

appctx ( Any )

Return type

None

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

Set an auxiliary vector for a specific region.

Not collective.
Parameters

	•		aux ( Vec ) -- The auxiliary vector.
	•		label ( DMLabel \| None ) -- The name of the DMLabel .
	•		value -- Indicate the region.
	•		part -- The equation part, or 0 is unused.

Return type

None

SEE ALSO:

DMGetLabel , DMSetAuxiliaryVec

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

setBasicAdjacency(useCone, useClosure)

Set the flags for determining variable influence.

Not collective.
Parameters

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

Return type

None

SEE ALSO:

DMSetBasicAdjacency

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

setCellCoordinateDM(dm)

Set the cell coordinate DM .

Collective.
Parameters

dm ( DM ) -- The cell coordinate DM .

Return type

None

SEE ALSO:

DMSetCellCoordinateDM

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

setCellCoordinateSection(dim, sec)

Set the cell coordinate layout over the DM .

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

setCellCoordinates(c)

Set a global vector with the cellwise coordinates.

Collective.
Parameters

c ( Vec ) -- The global cell coordinate vector.

Return type

None

SEE ALSO:

DMSetCellCoordinates

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

setCellCoordinatesLocal(c)

Set 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:1241

setCoarseDM(dm)

Set the coarse DM .

Collective.

SEE ALSO:

DMSetCoarseDM

Source code at petsc4py/PETSc/DM.pyx:1035
Parameters

dm ( DM )

Return type

None

setCoordinateDim(dim)

Set the dimension of embedding space for coordinates values.

Not collective.
Parameters

dim ( int ) -- The embedding dimension.

Return type

None

SEE ALSO:

DMSetCoordinateDim

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

setCoordinateDisc(disc, project)

Project coordinates to a different space.

Collective.
Parameters

	•		disc ( FE ) -- The new coordinates discretization.
	•		project ( bool )

Return type

Self

SEE ALSO:

DMSetCoordinateDisc

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

setCoordinates(c)

Set a global vector that holds the coordinates.

Collective.
Parameters

c ( Vec ) -- Coordinate Vector.

Return type

None

SEE ALSO:

DMSetCoordinates

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

setCoordinatesLocal(c)

Set a local vector with the ghost point holding the coordinates.

Not collective.
Parameters

c ( Vec ) -- Coordinate Vector.

Return type

None

SEE ALSO:

DMSetCoordinatesLocal

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

setDimension(dim)

Set the topological dimension of the DM .

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)

Set the discretization object for a given DM field.

Logically collective.
Parameters

	•		index ( int ) -- The field number.
	•		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:

DMSetField

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

setFieldAdjacency(field, useCone, useClosure)

Set the flags for determining variable influence.

Not collective.
Parameters

	•		field ( int ) -- The field number.
	•		useCone ( bool ) -- Whether adjacency uses cone information.
	•		useClosure ( bool ) -- Whether adjacency is computed using full closure information.

Return type

None

SEE ALSO:

DMSetAdjacency

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

setFromOptions()

Configure the object from the options database.

Collective.

SEE ALSO:

Working with PETSc options , DMSetFromOptions

Source code at petsc4py/PETSc/DM.pyx:312
Return type

None

setGlobalSection(sec)

Set the Section encoding the global data layout for the DM .

Collective.

SEE ALSO:

DMSetGlobalSection

Source code at petsc4py/PETSc/DM.pyx:1750
Parameters

sec ( Section )

Return type

None

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

Matrix associated with the linear system.

Collective.
Parameters

	•		operator -- Callback function to compute the operators.
	•		args ( tuple[Any, ...] \| None ) -- Positional arguments for the callback.
	•		kargs ( dict[str, Any] \| None ) -- Keyword arguments for the callback.

Return type

None

SEE ALSO:

DMKSPSetComputeOperators

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

setLabelOutput(name, output)

Set if a given label should be saved to a view.

Not collective.
Parameters

	•		name ( str ) -- The label name.
	•		output ( bool ) -- If True , the label is saved to the viewer.

Return type

None

SEE ALSO:

DMSetLabelOutput

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

setLabelValue(name, point, value)

Set a point to a DMLabel with a given value.

Not collective.
Parameters

	•		name ( str ) -- The label name.
	•		point ( int ) -- The mesh point.
	•		value ( int ) -- The label value for the point.

Return type

None

SEE ALSO:

DMSetLabelValue

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

setLocalSection(sec)

Set the Section encoding the local data layout for the DM .

Collective.

SEE ALSO:

DMSetLocalSection

Source code at petsc4py/PETSc/DM.pyx:1723
Parameters

sec ( Section )

Return type

None

setMatType(mat_type)

Set matrix type to be used by DM.createMat .

Logically collective.
Parameters

mat_type ( Type | str ) -- The matrix type.

Return type

None

Notes

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

SEE ALSO:

Working with PETSc options , DMSetMatType

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

setNumFields(numFields)

Set the number of fields in the DM .

Logically collective.

SEE ALSO:

DMSetNumFields

Source code at petsc4py/PETSc/DM.pyx:533
Parameters

numFields ( int )

Return type

None

setOptionsPrefix(prefix)

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

Logically collective.

SEE ALSO:

Working with PETSc options , getOptionsPrefix , - DMSetOptionsPrefix

Source code at petsc4py/PETSc/DM.pyx:270
Parameters

prefix ( str | None )

Return type

None

setPointSF(sf)

Set the SF encoding the parallel DOF overlap for the DM .

Logically collective.

SEE ALSO:

DMSetPointSF

Source code at petsc4py/PETSc/DM.pyx:1855
Parameters

sf ( SF )

Return type

None

setRefineLevel(level)

Set the number of refinements.

Not collective.
Parameters

	•		nlevels -- The number of refinement.
	•		level ( int )

Return type

None

SEE ALSO:

DMSetRefineLevel

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

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

Set SNES residual evaluation function.

Not collective.
Parameters

	•		function ( SNESFunction ) -- 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:

SNES.setFunction , DMSNESSetFunction

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

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

Set the SNES Jacobian evaluation function.

Not collective.
Parameters

	•		jacobian ( SNESJacobianFunction ) -- The Jacobian 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:

SNES.setJacobian , DMSNESSetJacobian

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

setSectionSF(sf)

Set the Section encoding the parallel DOF overlap for the DM .

Logically collective.

SEE ALSO:

DMSetSectionSF

Source code at petsc4py/PETSc/DM.pyx:1824
Parameters

sf ( SF )

Return type

None

setType(dm_type)

Build a DM .

Collective.
Parameters

dm_type ( Type | str ) -- The type of DM .

Return type

None

Notes

DM types are available in DM.Type class.

SEE ALSO:

DM.Type , DMSetType

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

setUp()

Return the data structure.

Collective.

SEE ALSO:

DMSetUp

Source code at petsc4py/PETSc/DM.pyx:324
Return type

Self

setVecType(vec_type)

Set the type of vector.

Logically collective.

SEE ALSO:

Vec.Type , DMSetVecType

Source code at petsc4py/PETSc/DM.pyx:784
Parameters

vec_type ( Type | str )

Return type

None

view(viewer=None)

View the DM .

Collective.
Parameters

viewer ( Viewer | None ) -- The DM viewer.

Return type

None

SEE ALSO:

DMView

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

Attributes Documentation

appctx

Application context.

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

Discrete space.

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

petsc4py.PETSc.DMComposite

class petsc4py.PETSc.DMComposite

Bases: DM

A DM object that is used to manage data for a collection of DMs.

Methods Summary

Image grohtml-288464-17.png

Methods Documentation
addDM(dm, *args)

Add a DM vector to the composite.

Collective.
Parameters

	•		dm ( DM ) -- The DM object.
	•		*args ( DM ) -- Additional DM objects.

Return type

None

SEE ALSO:

DMCompositeAddDM

Source code at petsc4py/PETSc/DMComposite.pyx:28

create(comm=None)

Create a composite object.

Collective.
Parameters

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

Return type

Self

SEE ALSO:

DMCompositeCreate

Source code at petsc4py/PETSc/DMComposite.pyx:6

gather(gvec, imode, lvecs)

Gather split local vectors into a coupled global vector.

Collective.
Parameters

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

Return type

None

SEE ALSO:

scatter , DMCompositeGatherArray

Source code at petsc4py/PETSc/DMComposite.pyx:115

getAccess(gvec, locs=None)

Get access to the individual vectors from the global vector.

Not collective.

Use via The with statement context manager (PEP 343).
Parameters

	•		gvec ( Vec ) -- The global vector.
	•		locs ( Sequence[int] \| None ) -- Indices of vectors wanted, or None to get all vectors.

Return type

Any

Source code at petsc4py/PETSc/DMComposite.pyx:219

getEntries()

Return sub-DMs contained in the composite.

Not collective.

SEE ALSO:

DMCompositeGetEntriesArray

Source code at petsc4py/PETSc/DMComposite.pyx:66
Return type

list [ DM ]

getGlobalISs()

Return the index sets for each composed object in the composite.

Collective.

These could be used to extract a subset of vector entries for a "multi-physics" preconditioner.

Use getLocalISs for index sets in the packed local numbering, and getLGMaps for to map local sub-DM (including ghost) indices to packed global indices.

SEE ALSO:

DMCompositeGetGlobalISs

Source code at petsc4py/PETSc/DMComposite.pyx:143
Return type

list [ IS ]

getLGMaps()

Return a local-to-global mapping for each DM in the composite.

Collective.

Note that this includes all the ghost points that individual ghosted DMDA may have.

SEE ALSO:

DMCompositeGetISLocalToGlobalMappings

Source code at petsc4py/PETSc/DMComposite.pyx:196
Return type

list [ LGMap ]

getLocalISs()

Return index sets for each component of a composite local vector.

Not collective.

To get the composite global indices at all local points (including ghosts), use getLGMaps .

To get index sets for pieces of the composite global vector, use getGlobalISs .

SEE ALSO:

DMCompositeGetLocalISs

Source code at petsc4py/PETSc/DMComposite.pyx:170
Return type

list [ IS ]

getNumber()

Get number of sub-DMs contained in the composite.

Not collective.

SEE ALSO:

DMCompositeGetNumberDM

Source code at petsc4py/PETSc/DMComposite.pyx:51
Return type

int

scatter(gvec, lvecs)

Scatter coupled global vector into split local vectors.

Collective.
Parameters

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

Return type

None

SEE ALSO:

gather , DMCompositeScatterArray

Source code at petsc4py/PETSc/DMComposite.pyx:90

petsc4py.PETSc.DMDA

class petsc4py.PETSc.DMDA

Bases: DM

A DM object that is used to manage data for a structured grid.

Enumerations

Image grohtml-288464-18.png

petsc4py.PETSc.DMDA.ElementType

class petsc4py.PETSc.DMDA.ElementType

Bases: object

Element types.

Attributes Summary

Image grohtml-288464-19.png

Attributes Documentation
P1: int = P1

Constant P1 of type int

Q1: int = Q1

Constant Q1 of type int

petsc4py.PETSc.DMDA.InterpolationType

class petsc4py.PETSc.DMDA.InterpolationType

Bases: object

Interpolation types.

Attributes Summary

Image grohtml-288464-20.png

Attributes Documentation
Q0: int = Q0

Constant Q0 of type int

Q1: int = Q1

Constant Q1 of type int

petsc4py.PETSc.DMDA.StencilType

class petsc4py.PETSc.DMDA.StencilType

Bases: object

Stencil types.

Attributes Summary

Image grohtml-288464-21.png

Attributes Documentation
BOX: int = BOX

Constant BOX of type int

STAR: int = STAR

Constant STAR of type int

Methods Summary

Image grohtml-288464-22.png

Attributes Summary

Image grohtml-288464-23.png

Methods Documentation
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)

Create a DMDA object.

Collective.

This routine performs the following steps of the C API: - petsc.DMDACreate - petsc.DMSetDimension - petsc.DMDASetDof - petsc.DMDASetSizes - petsc.DMDASetNumProcs - petsc.DMDASetOwnershipRanges - petsc.DMDASetBoundaryType - petsc.DMDASetStencilType - petsc.DMDASetStencilWidth - petsc.DMSetUp (optionally)
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 x, y, z dimensions.
	•		boundary_type ( tuple[DM.BoundaryType \| int \| str \| bool, ...] \| None ) -- The boundary types.
	•		stencil_type ( StencilType \| None ) -- The ghost/halo stencil type.
	•		stencil_width ( int \| None ) -- The width of the ghost/halo region.
	•		setup ( bool ) -- Whether to call the setup routine after creating the object.
	•		ownership_ranges ( tuple[Sequence[int], ...] \| - None ) -- Local x, y, z element counts, of length equal to proc_sizes , summing to sizes .
	•		comm ( Comm \| None ) -- MPI communicator, defaults to Sys.getDefaultComm .

Return type

Self

SEE ALSO:

DMDACreate , DMSetDimension , DMDASetDof , DMDASetSizes , DMDASetNumProcs , DMDASetOwnershipRanges , - DMDASetBoundaryType , DMDASetStencilType , - DMDASetStencilWidth , DMSetUp

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

createNaturalVec()

Create a vector that will hold values in the natural numbering.

Collective.

The number of local entries in the vector on each process is the same as in a vector created with 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.

Collective.

This routine retrieves the information from the DMDA and recreates it. Parameters dof , boundary_type , stencil_type , stencil_width will be overwritten, if provided.
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.).

SEE ALSO:

DMDAGetAO

Source code at petsc4py/PETSc/DMDA.pyx:909
Return type

getBoundaryType()

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

Not collective.

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.

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.

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.

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

Source code at petsc4py/PETSc/DMDA.pyx:264
Return type

int

getElementType()

Return the element type to be returned by getElements .

Not collective.

SEE ALSO:

setElementType , DMDAGetElementType

Source code at petsc4py/PETSc/DMDA.pyx:1050
Return type

ElementType

getElements(elem_type=None)

Return an array containing the indices of all the local elements.

Not collective.

The elements are in local coordinates.

Each process uniquely owns a subset of the elements. That is, no element is owned by two or more processes.
Parameters

elem_type ( ElementType | None ) -- The element type.

Return type

ArrayInt

SEE ALSO:

DMDAGetElements

Source code at petsc4py/PETSc/DMDA.pyx:1064

getFieldName(field)

Return the name of an individual field component.

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

Return type

str

SEE ALSO:

setFieldName , DMDAGetFieldName

Source code at petsc4py/PETSc/DMDA.pyx:699

getGhostCorners()

Return the lower left corner and the size of the ghosted local region.

Not collective.

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

SEE ALSO:

getRanges , getGhostRanges , getOwnershipRanges , getCorners , DMDAGetGhostCorners

Source code at petsc4py/PETSc/DMDA.pyx:651
Return type

tuple [ tuple [ int , ...], tuple [ int , ...]]

getGhostRanges()

Return the ranges of the local region in each dimension, including ghost nodes.

Not collective.

SEE ALSO:

getRanges , getOwnershipRanges , getCorners , getGhostCorners , DMDAGetGhostCorners

Source code at petsc4py/PETSc/DMDA.pyx:577
Return type

tuple [ tuple [ int , int ], ...]

getInterpolationType()

Return the type of interpolation.

Not collective.

SEE ALSO:

setInterpolationType , DMDAGetInterpolationType

Source code at petsc4py/PETSc/DMDA.pyx:1020
Return type

InterpolationType

getOwnershipRanges()

Return the ranges of indices in each dimension owned by each process.

Not collective.

These numbers are not multiplied by the number of DOFs per node.

SEE ALSO:

getRanges , getGhostRanges , getCorners , getGhostCorners , DMDAGetOwnershipRanges

Source code at petsc4py/PETSc/DMDA.pyx:597
Return type

tuple [ ArrayInt , ...]

getProcSizes()

Return the number of processes in each dimension.

Not collective.

SEE ALSO:

setProcSizes , DMDAGetInfo

Source code at petsc4py/PETSc/DMDA.pyx:361
Return type

tuple [ int , ...]

getRanges()

Return the ranges of the owned local region in each dimension.

Not collective.

Excluding ghost nodes.

SEE ALSO:

getGhostRanges , getOwnershipRanges , getCorners , getGhostCorners , DMDAGetCorners

Source code at petsc4py/PETSc/DMDA.pyx:555
Return type

tuple [ tuple [ int , int ], ...]

getRefinementFactor()

Return the ratios that the DMDA grid is refined in each dimension.

Not collective.

SEE ALSO:

setRefinementFactor , DMDAGetRefinementFactor

Source code at petsc4py/PETSc/DMDA.pyx:981
Return type

tuple [ int , ...]

getScatter()

Return the global-to-local, and local-to-local scatter contexts.

Collective.

SEE ALSO:

DMDAGetScatter

Source code at petsc4py/PETSc/DMDA.pyx:930
Return type

tuple [ Scatter , Scatter ]

getSizes()

Return the number of grid points in each dimension.

Not collective.

SEE ALSO:

setSizes , DMDAGetInfo

Source code at petsc4py/PETSc/DMDA.pyx:311
Return type

tuple [ int , ...]

getStencil()

Return the stencil type and width.

Not collective.

SEE ALSO:

getStencilType , getStencilWidth

Source code at petsc4py/PETSc/DMDA.pyx:532
Return type

tuple [ StencilType , int ]

getStencilType()

Return the stencil type.

Not collective.

SEE ALSO:

setStencilType , DMDAGetInfo

Source code at petsc4py/PETSc/DMDA.pyx:448
Return type

StencilType

getStencilWidth()

Return the stencil width.

Not collective.

SEE ALSO:

setStencilWidth

Source code at petsc4py/PETSc/DMDA.pyx:486
Return type

int

getVecArray(vec, readonly=False)

Get access to the vector as laid out on a N-d grid.

Logically collective.
Parameters

	•		vec ( Vec ) -- The vector to which access is being requested.
	•		readonly ( bool ) -- Request read-only access.

Return type

Any

SEE ALSO:

Vec.getArray , DMDAVecGetArray , DMDAVecGetArrayDOF

Source code at petsc4py/PETSc/DMDA.pyx:723

globalToNatural(vg, vn, addv=None)

Map values to the "natural" grid ordering.

Neighborwise collective.

You must call createNaturalVec before using this routine.
Parameters

	•		vg ( Vec ) -- The global vector in a grid ordering.
	•		vn ( Vec ) -- The global vector in a "natural" ordering.
	•		addv ( InsertMode \| None ) -- The insertion mode.

Return type

None

SEE ALSO:

naturalToGlobal , DMDAGlobalToNaturalBegin , - DMDAGlobalToNaturalEnd

Source code at petsc4py/PETSc/DMDA.pyx:849

naturalToGlobal(vn, vg, addv=None)

Map values the to 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 ) -- The insertion mode.

Return type

None

SEE ALSO:

globalToNatural , DMDANaturalToGlobalBegin , - DMDANaturalToGlobalEnd

Source code at petsc4py/PETSc/DMDA.pyx:879

setBoundaryType(boundary_type)

Set the type of ghost nodes on domain boundaries.

Not collective.
Parameters

boundary_type ( tuple[BoundaryType | int | str | - bool, ...] ) -- The boundary type in (x), (x, y), or (x, y, z) dimensions.

Return type

None

SEE ALSO:

getBoundaryType , DMDASetBoundaryType

Source code at petsc4py/PETSc/DMDA.pyx:384

setCoordinateName(index, name)

Set the name of the coordinate dimension.

Logically collective.
Parameters

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

Return type

None

SEE ALSO:

getCoordinateName , DMDASetCoordinateName

Source code at petsc4py/PETSc/DMDA.pyx:788

setDim(dim)

Set the topological dimension.

Collective.
Parameters

dim ( int ) -- Topological dimension.

Return type

None

SEE ALSO:

getDim , DMSetDimension

Source code at petsc4py/PETSc/DMDA.pyx:217

setDof(dof)

Set the number of degrees of freedom per vertex.

Not collective.
Parameters

dof ( int ) -- The number of degrees of freedom.

Return type

None

SEE ALSO:

getDof , DMDASetDof

Source code at petsc4py/PETSc/DMDA.pyx:246

setElementType(elem_type)

Set the element type to be returned by getElements .

Not collective.

SEE ALSO:

getElementType , DMDASetElementType

Source code at petsc4py/PETSc/DMDA.pyx:1036
Parameters

elem_type ( ElementType | str )

Return type

None

setFieldName(field, name)

Set the name of individual field components.

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

SEE ALSO:

getFieldName , DMDASetFieldName

Source code at petsc4py/PETSc/DMDA.pyx:675

setInterpolationType(interp_type)

Set the type of interpolation.

Logically collective.

You should call this on the coarser of the two DMDAs you pass to DM.createInterpolation .
Parameters

interp_type ( InterpolationType ) -- The interpolation type.

Return type

None

SEE ALSO:

getInterpolationType , DMDASetInterpolationType

Source code at petsc4py/PETSc/DMDA.pyx:999

setProcSizes(proc_sizes)

Set the number of processes in each dimension.

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

Source code at petsc4py/PETSc/DMDA.pyx:334

setRefinementFactor(refine_x=2, refine_y=2, refine_z=2)

Set the ratios for the DMDA grid refinement.

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

Source code at petsc4py/PETSc/DMDA.pyx:949

setSizes(sizes)

Set the number of grid points in each dimension.

Logically collective.
Parameters

sizes ( DimsSpec ) -- The global (x,), (x, y), or (x, y, z) size.

Return type

None

SEE ALSO:

getSizes , DMDASetSizes

Source code at petsc4py/PETSc/DMDA.pyx:284

setStencil(stencil_type, stencil_width)

Set the stencil type and width.

Not collective.
Parameters

	•		stencil_type ( StencilType ) -- The stencil type.
	•		stencil_width ( int ) -- The stencil width.

Return type

None

SEE ALSO:

setStencilWidth , setStencilType , DMDASetStencilType , - DMDASetStencilWidth

Source code at petsc4py/PETSc/DMDA.pyx:506

setStencilType(stencil_type)

Set the stencil type.

Logically collective.
Parameters

	•		stype -- The stencil type.
	•		stencil_type ( StencilType )

Return type

None

SEE ALSO:

getStencilType , setStencil , DMDASetStencilType

Source code at petsc4py/PETSc/DMDA.pyx:430

setStencilWidth(stencil_width)

Set the stencil width.

Logically collective.
Parameters

stencil_width ( int ) -- The stencil width.

Return type

None

SEE ALSO:

getStencilWidth , setStencil , DMDASetStencilWidth

Source code at petsc4py/PETSc/DMDA.pyx:468

setUniformCoordinates(xmin=0, xmax=1, ymin=0, ymax=1, zmin=0,
zmax=1)

Set the DMDA coordinates to be a uniform grid.

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

Source code at petsc4py/PETSc/DMDA.pyx:744

Attributes Documentation
boundary_type

Boundary types in each dimension.

Source code at petsc4py/PETSc/DMDA.pyx:1123

corners

The lower left corner and size of local region in each dimension.

Source code at petsc4py/PETSc/DMDA.pyx:1153

dim

The grid dimension.

Source code at petsc4py/PETSc/DMDA.pyx:1103

dof

The number of DOFs associated with each stratum of the grid.

Source code at petsc4py/PETSc/DMDA.pyx:1108

ghost_corners

The lower left corner and size of local region in each dimension.

Source code at petsc4py/PETSc/DMDA.pyx:1158

ghost_ranges

Ranges of local region, including ghost nodes.

Source code at petsc4py/PETSc/DMDA.pyx:1148

proc_sizes

The number of processes in each dimension in the global decomposition.

Source code at petsc4py/PETSc/DMDA.pyx:1118

ranges

Ranges of the local region in each dimension.

Source code at petsc4py/PETSc/DMDA.pyx:1143

sizes

The global dimension.

Source code at petsc4py/PETSc/DMDA.pyx:1113

stencil

Stencil type and width.

Source code at petsc4py/PETSc/DMDA.pyx:1128

stencil_type

Stencil type.

Source code at petsc4py/PETSc/DMDA.pyx:1133

stencil_width

Elementwise stencil width.

Source code at petsc4py/PETSc/DMDA.pyx:1138

petsc4py.PETSc.DMInterpolation

class petsc4py.PETSc.DMInterpolation

Bases: object

Interpolation on a mesh.

Methods Summary

Image grohtml-288464-24.png

Methods Documentation
create(comm=None)

Create a DMInterpolation context.

Collective.
Parameters

comm ( Comm | None ) -- MPI communicator, defaults to COMM_SELF .

Return type

Self

SEE ALSO:

destroy , DMInterpolationCreate

Source code at petsc4py/PETSc/DMUtils.pyx:13

destroy()

Destroy the DMInterpolation context.

Collective.

SEE ALSO:

create , DMInterpolationDestroy

Source code at petsc4py/PETSc/DMUtils.pyx:35
Return type

Self

evaluate(dm, x, v=None)

Calculate interpolated field values at the interpolation points.

Collective.
Parameters

	•		dm ( DM ) -- The DM .
	•		x ( Vec ) -- The local vector containing the field to be interpolated.
	•		v ( Vec \| None ) -- A vector capable of holding the interpolated field values.

Return type

Vec

SEE ALSO:

DMInterpolationEvaluate

Source code at petsc4py/PETSc/DMUtils.pyx:48

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.

SEE ALSO:

DMInterpolationGetCoordinates

Source code at petsc4py/PETSc/DMUtils.pyx:74
Return type

Vec

getDim()

Return the spatial dimension of the interpolation context.

Not collective.

SEE ALSO:

setDim , DMInterpolationGetDim

Source code at petsc4py/PETSc/DMUtils.pyx:92
Return type

int

getDof()

Return the number of fields interpolated at a point.

Not collective.

SEE ALSO:

setDof , DMInterpolationGetDof

Source code at petsc4py/PETSc/DMUtils.pyx:106
Return type

int

getVector()

Return a Vec which can hold all the interpolated field values.

Collective.

This vector should be returned using restoreVector .

SEE ALSO:

restoreVector , DMInterpolationGetVector

Source code at petsc4py/PETSc/DMUtils.pyx:185
Return type

Vec

restoreVector(vec)

Restore a Vec which can hold all the interpolated field values.

Collective.
Parameters

vec ( Vec ) -- A vector capable of holding the interpolated field values.

Return type

None

SEE ALSO:

getVector , DMInterpolationRestoreVector

Source code at petsc4py/PETSc/DMUtils.pyx:201

setDim(dim)

Set the spatial dimension for the interpolation context.

Not collective.
Parameters

dim ( int ) -- The spatial dimension.

Return type

None

SEE ALSO:

getDim , DMInterpolationSetDim

Source code at petsc4py/PETSc/DMUtils.pyx:120

setDof(dof)

Set the number of fields interpolated at a point.

Not collective.
Parameters

dof ( int ) -- The number of fields.

Return type

None

SEE ALSO:

getDof , DMInterpolationSetDof

Source code at petsc4py/PETSc/DMUtils.pyx:138

setUp(dm, redundantPoints=False, ignoreOutsideDomain=False)

Compute spatial indices for point location during interpolation.

Collective.
Parameters

	•		dm ( DM ) -- The DM for the function space used for interpolation.
	•		redundantPoints ( bool ) -- If True , all processes are passing in the same array of points. Otherwise, points need to be communicated among processes.
	•		ignoreOutsideDomain ( bool ) -- Ignore points outside of the domain if True ; otherwise, return an error.

Return type

None

SEE ALSO:

DMInterpolationSetUp

Source code at petsc4py/PETSc/DMUtils.pyx:156

petsc4py.PETSc.DMLabel

class petsc4py.PETSc.DMLabel

Bases: Object

An object representing a subset of mesh entities from a DM .

Methods Summary

Image grohtml-288464-25.png

Methods Documentation
addStrata(strata)

Add new stratum values in a DMLabel .

Not collective.
Parameters

strata ( Sequence[int] ) -- The stratum values.

Return type

None

SEE ALSO:

addStrataIS , addStratum , DMLabelAddStrata

Source code at petsc4py/PETSc/DMLabel.pyx:238

addStrataIS(iset)

Add new stratum values in a DMLabel .

Not collective.
Parameters

iset ( IS ) -- Index set with stratum values.

Return type

None

SEE ALSO:

addStrata , addStratum , DMLabelAddStrataIS

Source code at petsc4py/PETSc/DMLabel.pyx:258

addStratum(value)

Add a new stratum value in a DMLabel .

Not collective.
Parameters

value ( int ) -- The stratum value.

Return type

None

SEE ALSO:

addStrata , addStrataIS , DMLabelAddStratum

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

clearStratum(stratum)

Remove a stratum.

Not collective.
Parameters

stratum ( int ) -- The stratum value.

Return type

None

SEE ALSO:

DMLabelClearStratum

Source code at petsc4py/PETSc/DMLabel.pyx:406

clearValue(point, value)

Clear the value a label assigns to a point.

Not collective.
Parameters

	•		point ( int ) -- The point.
	•		value ( int ) -- The point value.

Return type

None

SEE ALSO:

DMLabelClearValue

Source code at petsc4py/PETSc/DMLabel.pyx:199

computeIndex()

Create an index structure for membership determination.

Not collective.

Automatically determines the bounds.

SEE ALSO:

DMLabelComputeIndex

Source code at petsc4py/PETSc/DMLabel.pyx:424
Return type

None

convertToSection()

Return a Section and IS that encode the label.

Not collective.

SEE ALSO:

DMLabelConvertToSection

Source code at petsc4py/PETSc/DMLabel.pyx:607
Return type

tuple [ Section , IS ]

create(name, comm=None)

Create a DMLabel object, which is a multimap.

Collective.
Parameters

	•		name ( str ) -- The label name.
	•		comm ( Comm \| None ) -- MPI communicator, defaults to COMM_SELF .

Return type

Self

SEE ALSO:

DMLabelCreate

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

createIndex(pStart, pEnd)

Create an index structure for membership determination.

Not collective.
Parameters

	•		pStart ( int ) -- The smallest point.
	•		pEnd ( int ) -- The largest point + 1.

Return type

None

SEE ALSO:

destroyIndex , DMLabelCreateIndex

Source code at petsc4py/PETSc/DMLabel.pyx:438

destroy()

Destroy the label.

Collective.

SEE ALSO:

DMLabelDestroy

Source code at petsc4py/PETSc/DMLabel.pyx:8
Return type

Self

destroyIndex()

Destroy the index structure.

Not collective.

SEE ALSO:

createIndex , DMLabelDestroyIndex

Source code at petsc4py/PETSc/DMLabel.pyx:458
Return type

None

distribute(sf)

Create a new label pushed forward over the SF .

Collective.
Parameters

sf ( SF ) -- The map from old to new distribution.

Return type

DMLabel

SEE ALSO:

gather , DMLabelDistribute

Source code at petsc4py/PETSc/DMLabel.pyx:567

duplicate()

Duplicate the DMLabel .

Collective.

SEE ALSO:

DMLabelDuplicate

Source code at petsc4py/PETSc/DMLabel.pyx:65
Return type

DMLabel

filter(start, end)

Remove all points outside of [start, end).

Not collective.
Parameters

	•		start ( int ) -- The first point kept.
	•		end ( int ) -- One more than the last point kept.

Return type

None

SEE ALSO:

DMLabelFilter

Source code at petsc4py/PETSc/DMLabel.pyx:528

gather(sf)

Gather all label values from leaves into roots.

Collective.

This is the inverse operation to distribute .
Parameters

sf ( SF ) -- The SF communication map.

Return type

DMLabel

SEE ALSO:

distribute , DMLabelGather

Source code at petsc4py/PETSc/DMLabel.pyx:586

getBounds()

Return the smallest and largest point in the label.

Not collective.

The returned values are the smallest point and the largest point + 1.

SEE ALSO:

DMLabelGetBounds

Source code at petsc4py/PETSc/DMLabel.pyx:512
Return type

tuple [ int , int ]

getDefaultValue()

Return the default value returned by getValue .

Not collective.

The default value is returned if a point has not been explicitly given a value. When a label is created, it is initialized to -1 .

SEE ALSO:

setDefaultValue , DMLabelGetDefaultValue

Source code at petsc4py/PETSc/DMLabel.pyx:161
Return type

int

getNonEmptyStratumValuesIS()

Return an IS of all values that the DMLabel takes.

Not collective.

SEE ALSO:

DMLabelGetNonEmptyStratumValuesIS

Source code at petsc4py/PETSc/DMLabel.pyx:622
Return type

getNumValues()

Return the number of values that the DMLabel takes.

Not collective.

SEE ALSO:

DMLabelGetNumValues

Source code at petsc4py/PETSc/DMLabel.pyx:275
Return type

int

getStratumIS(stratum)

Return an IS with the stratum points.

Not collective.
Parameters

stratum ( int ) -- The stratum value.

Return type

SEE ALSO:

setStratumIS , DMLabelGetStratumIS

Source code at petsc4py/PETSc/DMLabel.pyx:366

getStratumSize(stratum)

Return the size of a stratum.

Not collective.
Parameters

stratum ( int ) -- The stratum value.

Return type

int

SEE ALSO:

DMLabelGetStratumSize

Source code at petsc4py/PETSc/DMLabel.pyx:346

getValue(point)

Return the value a label assigns to a point.

Not collective.

If no value was assigned, a default value will be returned The default value, initially -1 , can be changed with setDefaultValue .
Parameters

point ( int ) -- The point.

Return type

int

SEE ALSO:

setValue , setDefaultValue , DMLabelGetValue

Source code at petsc4py/PETSc/DMLabel.pyx:137

getValueIS()

Return an IS of all values that the DMLabel takes.

Not collective.

SEE ALSO:

DMLabelGetValueIS

Source code at petsc4py/PETSc/DMLabel.pyx:289
Return type

hasPoint(point)

Determine whether the label contains a point.

Not collective.

The user must call createIndex before this function.
Parameters

point ( int ) -- The point.

Return type

bool

SEE ALSO:

hasValue , DMLabelHasPoint

Source code at petsc4py/PETSc/DMLabel.pyx:490

hasStratum(value)

Determine whether points exist with the given value.

Not collective.
Parameters

value ( int ) -- The stratum value.

Return type

bool

SEE ALSO:

DMLabelHasStratum

Source code at petsc4py/PETSc/DMLabel.pyx:326

hasValue(value)

Determine whether a label assigns the value to any point.

Not collective.
Parameters

value ( int ) -- The value.

Return type

bool

SEE ALSO:

hasPoint , DMLabelHasValue

Source code at petsc4py/PETSc/DMLabel.pyx:470

insertIS(iset, value)

Set all points in the IS to a value.

Not collective.
Parameters

	•		iset ( IS ) -- The point IS.
	•		value ( int ) -- The point value.

Return type

Self

SEE ALSO:

DMLabelInsertIS

Source code at petsc4py/PETSc/DMLabel.pyx:91

permute(permutation)

Create a new label with permuted points.

Not collective.
Parameters

permutation ( IS ) -- The point permutation.

Return type

DMLabel

SEE ALSO:

DMLabelPermute

Source code at petsc4py/PETSc/DMLabel.pyx:548

reset()

Destroy internal data structures in the DMLabel .

Not collective.

SEE ALSO:

DMLabelReset

Source code at petsc4py/PETSc/DMLabel.pyx:79
Return type

None

setDefaultValue(value)

Set the default value returned by getValue .

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

value ( int ) -- The default value.

Return type

None

SEE ALSO:

getDefaultValue , DMLabelSetDefaultValue

Source code at petsc4py/PETSc/DMLabel.pyx:178

setStratumIS(stratum, iset)

Set the stratum points using an IS .

Not collective.
Parameters

	•		stratum ( int ) -- The stratum value.
	•		iset ( IS ) -- The stratum points.

Return type

None

SEE ALSO:

getStratumIS , DMLabelSetStratumIS

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

setValue(point, value)

Set the value a label assigns to a point.

Not collective.

If the value is the same as the label's default value (which is initially -1 , and can be changed with setDefaultValue ), this function will do nothing.
Parameters

	•		point ( int ) -- The point.
	•		value ( int ) -- The point value.

Return type

None

SEE ALSO:

getValue , setDefaultValue , DMLabelSetValue

Source code at petsc4py/PETSc/DMLabel.pyx:112

stratumHasPoint(value, point)

Return whether the stratum contains a point.

Not collective.
Parameters

	•		value ( int ) -- The stratum value.
	•		point ( int ) -- The point.

Return type

bool

SEE ALSO:

DMLabelStratumHasPoint

Source code at petsc4py/PETSc/DMLabel.pyx:303

view(viewer=None)

View the label.

Collective.
Parameters

viewer ( Viewer | None ) -- A Viewer to display the graph.

Return type

None

SEE ALSO:

DMLabelView

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

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.

Methods Summary

Image grohtml-288464-26.png

Methods Documentation
computeCellGeometryFVM(cell)

Compute the volume for a given cell.

Not collective.
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:2217

computeGradientClementInterpolant(locX, locC)

Return the L2 projection of the cellwise gradient of a function onto P1.

Collective.
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:3151

constructGhostCells(labelName=None)

Construct ghost cells which connect to every boundary face.

Collective.
Parameters

labelName ( str | None ) -- The name of the label specifying the boundary faces. Defaults to "Face Sets" .

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

coordinatesLoad(viewer, sfxc)

Load coordinates into this DMPlex object.

Collective.
Parameters

	•		viewer ( Viewer ) -- The Viewer for the saved coordinates.
	•		sfxc ( SF ) -- The SF returned by topologyLoad .

Return type

None

SEE ALSO:

DM , DMPlex , DM.load , DMPlex.topologyLoad , DMPlex.labelsLoad , DM.view , SF , Viewer , - DMPlexCoordinatesLoad

Source code at petsc4py/PETSc/DMPlex.pyx:3324

coordinatesView(viewer)

Save DMPlex coordinates into a file.

Collective.
Parameters

viewer ( Viewer ) -- The Viewer for saving.

Return type

None

SEE ALSO:

DM , DMPlex , DM.view , DMPlex.topologyView , DMPlex.labelsView , DMPlex.coordinatesLoad , Viewer , - DMPlexCoordinatesView

Source code at petsc4py/PETSc/DMPlex.pyx:3191

create(comm=None)

Create a DMPlex object, which encapsulates an unstructured mesh.

Collective.
Parameters

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

Return type

Self

SEE ALSO:

DM , DMPlex , DM.create , DM.setType , DMPlexCreate

Source code at petsc4py/PETSc/DMPlex.pyx:14

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.

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.
	•		simplex ( bool \| None ) -- True for simplices, - False for tensor cells.
	•		periodic ( Sequence \| str \| int \| bool \| None ) -- The boundary type for the X, Y, Z direction, or None for DM.BoundaryType.NONE .
	•		interpolate ( bool \| None ) -- Flag to create intermediate mesh entities (edges, faces).
	•		localizationHeight ( int \| None ) -- Flag to localize edges and faces in addition to cells; only significant for periodic meshes.
	•		sparseLocalize ( bool \| None ) -- Flag to localize coordinates only for cells near the periodic boundary; only significant for periodic meshes.
	•		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

Source code at petsc4py/PETSc/DMPlex.pyx:90

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.

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).
	•		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

Source code at petsc4py/PETSc/DMPlex.pyx:149

createCGNS(cgid, interpolate=True, comm=None)

Create a DMPlex mesh from a CGNS file.

Collective.
Parameters

	•		cgid ( int ) -- The CG id associated with a file and obtained using cg_open.
	•		interpolate ( bool \| None ) -- Create faces and edges in the mesh.
	•		comm ( Comm \| None ) -- 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.

Collective.
Parameters

	•		filename ( str ) -- The name of the CGNS file.
	•		interpolate ( bool \| None ) -- Create faces and edges in the mesh.
	•		comm ( Comm \| None ) -- 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.

Not collective.
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:2031

createCoarsePointIS()

Create an IS covering the coarse DMPlex chart with the fine points as data.

Collective.
Returns

fpointIS -- The IS of all the fine points which exist in the original coarse mesh.

Return type

SEE ALSO:

DM , DMPlex , IS , DM.refine , DMPlex.setRefinementUniform , DMPlexCreateCoarsePointIS

Source code at petsc4py/PETSc/DMPlex.pyx:1817

createCohesiveSubmesh(hasLagrange, value)

Extract the hypersurface defined by one face of the cohesive cells.

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

createExodus(exoid, interpolate=True, comm=None)

Create a DMPlex mesh from an ExodusII file ID.

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

Collective.
Parameters

	•		filename ( str ) -- The name of the ExodusII file.
	•		interpolate ( bool \| None ) -- Create faces and edges in the mesh.
	•		comm ( Comm \| None ) -- MPI communicator, 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)

Create a DMPlex from a list of vertices for each cell on process 0.

Collective.
Parameters

	•		dim ( int ) -- The topological dimension of the mesh.
	•		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)

Create DMPlex from a file.

Collective.
Parameters

	•		filename ( str ) -- A file name.
	•		plexname ( str \| None ) -- The name of the resulting DMPlex , also used for intra-datafile lookup by some formats.
	•		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

createGmsh(viewer, interpolate=True, comm=None)

Create a DMPlex mesh from a Gmsh file viewer.

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

createPointNumbering()

Create a global numbering for all points.

Collective.

SEE ALSO:

DM , DMPlex , DMPlex.getCellNumbering , - DMPlexCreatePointNumbering

Source code at petsc4py/PETSc/DMPlex.pyx:915
Return type

createSection(numComp, numDof, bcField=None, bcComps=None,
bcPoints=None, perm=None)

Create a Section based upon the DOF layout specification provided.

Not collective.
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 the number of DOFs per field on a mesh piece of dimension dim** .
	•		bcField ( Sequence[int] \| None ) -- An array of size numBC giving the field number for each boundary condition, where numBC is the number of boundary conditions.
	•		bcComps ( Sequence[IS] \| None ) -- An array of size numBC giving an IS holding the field components to which each boundary condition applies.
	•		bcPoints ( Sequence[IS] \| None ) -- An array of size numBC giving an IS holding the DMPlex points to which each boundary condition applies.
	•		perm ( IS \| None ) -- 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:1837

distribute(overlap=0)

Distribute the mesh and any associated sections.

Collective.
Parameters

overlap ( int | None ) -- The overlap of partitions.

Returns

sf -- The SF used for point distribution, or None if not distributed.

Return type

SF or None

SEE ALSO:

DM , DMPlex , DMPlex.create , DMPlexDistribute

Source code at petsc4py/PETSc/DMPlex.pyx:1561

distributeField(sf, sec, vec, newsec=None, newvec=None)

Distribute field data with a with a given SF .

Collective.
Parameters

	•		sf ( SF ) -- The SF describing the communication pattern.
	•		sec ( Section ) -- The Section for existing data layout.
	•		vec ( Vec ) -- The existing data in a local vector.
	•		newsec ( Section \| None ) -- The SF describing the new data layout.
	•		newvec ( Vec \| 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:1758

distributeGetDefault()

Return a flag indicating whether the DM should be distributed by default.

Not collective.
Returns

dist -- Flag indicating 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:1647

distributeOverlap(overlap=0)

Add partition overlap to a distributed non-overlapping DMPlex .

Collective.
Parameters

overlap ( int | None ) -- The overlap of partitions (the same on all ranks).

Returns

sf -- The SF used for point distribution.

Return type

SEE ALSO:

DM , DMPlex , SF , DMPlex.create , DMPlex.distribute , - DMPlexDistributeOverlap

Source code at petsc4py/PETSc/DMPlex.pyx:1589

distributeSetDefault(flag)

Set flag indicating whether the DMPlex should be distributed by default.

Logically collective.
Parameters

flag ( bool ) -- 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:1667

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

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

generate(boundary, name=None, interpolate=True)

Generate a mesh.

Not collective.
Parameters

	•		boundary ( DMPlex ) -- The DMPlex boundary object.
	•		name ( str \| None ) -- The mesh generation package name.
	•		interpolate ( bool \| None ) -- Flag to create intermediate mesh elements.

Return type

Self

SEE ALSO:

DM , DMPlex , DMPlex.create , DM.refine , Working with PETSc options , DMPlexGenerate

Source code at petsc4py/PETSc/DMPlex.pyx:1284

getAdjacency(p)

Return all points adjacent to the given point.

Not collective.
Parameters

p ( int ) -- The point.

Return type

ArrayInt

SEE ALSO:

DMPlex , DMPlex.distribute , DMPlexGetAdjacency

Source code at petsc4py/PETSc/DMPlex.pyx:1467

getAdjacencyUseAnchors()

Query whether adjacency in the mesh uses the point-to-point constraints.

Not collective.

SEE ALSO:

DMPlex , DMPlex.getAdjacency , DMPlex.distribute , - DMPlexGetAdjacencyUseAnchors

Source code at petsc4py/PETSc/DMPlex.pyx:1452
Return type

bool

getCellNumbering()

Return a global cell numbering for all cells on this process.

Collective the first time it is called.

SEE ALSO:

DM , DMPlex , DMPlex.getVertexNumbering , - DMPlexGetCellNumbering

Source code at petsc4py/PETSc/DMPlex.pyx:885
Return type

getCellType(p)

Return the polytope type of a given cell.

Not collective.
Parameters

p ( int ) -- The cell.

Return type

PolytopeType

SEE ALSO:

DM , DMPlex , DM.PolytopeType , DMPlex.getCellTypeLabel , DMPlex.getDepth , DMPlexGetCellType

Source code at petsc4py/PETSc/DMPlex.pyx:685

getCellTypeLabel()

Return the DMLabel recording the polytope type of each cell.

Not collective.

SEE ALSO:

DM , DMPlex , DMPlex.getCellType , DM.createLabel , - DMPlexGetCellTypeLabel

Source code at petsc4py/PETSc/DMPlex.pyx:706
Return type

DMLabel

getChart()

Return the interval for all mesh points [ pStart , pEnd ).

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 code at petsc4py/PETSc/DMPlex.pyx:400

getCone(p)

Return the points on the in-edges for this point in the DAG.

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 code at petsc4py/PETSc/DMPlex.pyx:491

getConeOrientation(p)

Return the orientations on the in-edges for this point in the DAG.

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

Source code at petsc4py/PETSc/DMPlex.pyx:606

getConeSize(p)

Return the number of in-edges for this point in the DAG.

Not collective.
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 , DMPlexGetConeSize

Source code at petsc4py/PETSc/DMPlex.pyx:442

getDepth()

Return the depth of the DAG representing this mesh.

Not collective.

SEE ALSO:

DM , DMPlex , DMPlex.getDepthStratum , DMPlex.symmetrize , DMPlexGetDepth

Source code at petsc4py/PETSc/DMPlex.pyx:929
Return type

int

getDepthStratum(svalue)

Return the bounds [ start , end ) for all points at a certain depth.

Not collective.
Parameters

svalue ( int ) -- The requested depth.

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 code at petsc4py/PETSc/DMPlex.pyx:944

getFullJoin(points)

Return an array for the join of the set of points.

Not collective.
Parameters

points ( Sequence[int] ) -- The input points.

Return type

ArrayInt

SEE ALSO:

DM , DMPlex , DMPlex.getJoin , DMPlex.getMeet , - DMPlexGetFullJoin

Source code at petsc4py/PETSc/DMPlex.pyx:1092

getHeightStratum(svalue)

Return the bounds [ start , end ) for all points at a certain height.

Not collective.
Parameters

svalue ( int ) -- The requested height.

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 code at petsc4py/PETSc/DMPlex.pyx:971

getJoin(points)

Return an array for the join of the set of points.

Not collective.
Parameters

points ( Sequence[int] ) -- The input points.

Return type

ArrayInt

SEE ALSO:

DM , DMPlex , DMPlex.getMeet , DMPlexGetJoin

Source code at petsc4py/PETSc/DMPlex.pyx:1066

getMaxSizes()

Return the maximum number of in-edges and out-edges of the DAG.

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 code at petsc4py/PETSc/DMPlex.pyx:826

getMeet(points)

Return an array for the meet of the set of points.

Not collective.
Parameters

points ( Sequence[int] ) -- The input points.

Return type

ArrayInt

SEE ALSO:

DM , DMPlex , DMPlex.getJoin , DMPlexGetMeet

Source code at petsc4py/PETSc/DMPlex.pyx:1040

getMinRadius()

Return the minimum distance from any cell centroid to a face.

Not collective.

SEE ALSO:

DMPlex , DM.getCoordinates , DMPlexGetMinRadius

Source code at petsc4py/PETSc/DMPlex.pyx:1803
Return type

float

getOrdering(otype)

Calculate a reordering of the mesh.

Collective.
Parameters

otype ( OrderingType ) -- Type of reordering, see Mat.OrderingType .

Returns

perm -- The point permutation.

Return type

SEE ALSO:

DMPlex , DMPlex.permute , Mat.OrderingType , Mat.getOrdering , DMPlexGetOrdering

Source code at petsc4py/PETSc/DMPlex.pyx:2130

getPartitioner()

Return the mesh partitioner.

Not collective.

SEE ALSO:

DM , DMPlex , Partitioner , Section , DMPlex.distribute , DMPlex.setPartitioner , Partitioner.create , - PetscPartitionerDMPlexPartition , DMPlexGetPartitioner

Source code at petsc4py/PETSc/DMPlex.pyx:1510
Return type

Partitioner

getPointDepth(point)

Return 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

Source code at petsc4py/PETSc/DMPlex.pyx:998

getPointGlobal(point)

Return location of point data in global Vec .

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.

Return type

tuple [ int , int ]

SEE ALSO:

DM , DMPlex , DMPlex.getPointGlobalField , Section.getOffset , Section.getDof , DMPlex.getPointLocal , DMPlexGetPointGlobal

Source code at petsc4py/PETSc/DMPlex.pyx:1972

getPointGlobalField(point, field)

Return location of point field data in 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

Source code at petsc4py/PETSc/DMPlex.pyx:2000

getPointHeight(point)

Return the height of a given point.

Not collective.
Parameters

point ( int ) -- The point.

Return type

int

SEE ALSO:

DM , DMPlex , DMPlex.getHeightStratum , - DMPlexGetPointHeight

Source code at petsc4py/PETSc/DMPlex.pyx:1019

getPointLocal(point)

Return location of point data in local Vec .

Not collective.
Parameters

point ( int ) -- The topological point.

Returns

	•		start ( int ) -- Start of point data.
	•		end ( int ) -- End of point data.

Return type

tuple [ int , int ]

SEE ALSO:

DM , DMPlex , DMPlex.getPointLocalField , Section.getOffset , Section.getDof , DMPlexGetPointLocal

Source code at petsc4py/PETSc/DMPlex.pyx:1913

getPointLocalField(point, field)

Return location of point field data in local Vec .

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

Source code at petsc4py/PETSc/DMPlex.pyx:1941

getRefinementLimit()

Retrieve the maximum cell volume for refinement.

Not collective.

SEE ALSO:

DM , DMPlex , DM.refine , DMPlex.setRefinementLimit , DMPlex.getRefinementUniform , DMPlex.setRefinementUniform , DMPlexGetRefinementLimit

Source code at petsc4py/PETSc/DMPlex.pyx:2114
Return type

float

getRefinementUniform()

Retrieve the flag for uniform refinement.

Not collective.
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 at petsc4py/PETSc/DMPlex.pyx:2073

getSubpointIS()

Return an IS covering the entire subdm chart.

Not collective.
Returns

iset -- The IS containing subdm's parent's points.

Return type

SEE ALSO:

DM , DMPlex , DMPlexGetSubpointIS

Source code at petsc4py/PETSc/DMPlex.pyx:2278

getSubpointMap()

Return a DMLabel with point dimension as values.

Not collective.
Returns

label -- The DMLabel whose values are subdm's point dimensions.

Return type

DMLabel

SEE ALSO:

DM , DMPlex , DMPlexGetSubpointMap

Source code at petsc4py/PETSc/DMPlex.pyx:2298

getSupport(p)

Return the points on the out-edges for this point in the DAG.

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.getSupportSize , DMPlex.setSupport , DMPlex.getCone , DMPlex.setChart , DMPlexGetSupport

Source code at petsc4py/PETSc/DMPlex.pyx:771

getSupportSize(p)

Return the number of out-edges for this point in the DAG.

Not collective.
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 at petsc4py/PETSc/DMPlex.pyx:722

getTransitiveClosure(p, useCone=True)

Return the points and orientations on the transitive closure of this point.

Not collective.
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 at petsc4py/PETSc/DMPlex.pyx:1118

getVecClosure(sec, vec, point)

Return an array of the values on the closure of a point.

Not collective.
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 at petsc4py/PETSc/DMPlex.pyx:1185

getVertexNumbering()

Return a global vertex numbering for all vertices on this process.

Collective the first time it is called.

SEE ALSO:

DM , DMPlex , DMPlex.getCellNumbering , - DMPlexGetVertexNumbering

Source code at petsc4py/PETSc/DMPlex.pyx:900
Return type

globalVectorLoad(viewer, sectiondm, sf, vec)

Load on-disk vector data into a global vector.

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

SEE ALSO:

DM , DMPlex , DMPlex.topologyLoad , DMPlex.sectionLoad , DMPlex.localVectorLoad , DMPlex.globalVectorView , DMPlex.localVectorView , SF , Viewer , - DMPlexGlobalVectorLoad

Source code at petsc4py/PETSc/DMPlex.pyx:3401

globalVectorView(viewer, sectiondm, vec)

Save a global vector.

Collective.
Parameters

	•		viewer ( Viewer ) -- The Viewer to save data with.
	•		sectiondm ( DM ) -- The DM containing the global section on which vec is defined; may be the same as this DMPlex object.
	•		vec ( Vec ) -- The global vector to be saved.

Return type

None

SEE ALSO:

DM , DMPlex , DMPlex.topologyView , DMPlex.sectionView , DMPlex.localVectorView , DMPlex.globalVectorLoad , DMPlex.localVectorLoad , DMPlexGlobalVectorView

Source code at petsc4py/PETSc/DMPlex.pyx:3248

insertCone(p, conePos, conePoint)

DMPlexInsertCone - Insert a point into the in-edges for the point p in the DAG.

Not collective.
Parameters

	•		p ( int ) -- The point, which must lie in the chart set with DMPlex.setChart .
	•		conePos ( int ) -- The local index in the cone where the point should be put.
	•		conePoint ( int ) -- The mesh point to insert.

Return type

None

SEE ALSO:

DM , DMPlex , DMPlex.create , DMPlex.getCone , DMPlex.setChart , DMPlex.setConeSize , DM.setUp , - DMPlexInsertCone

Source code at petsc4py/PETSc/DMPlex.pyx:556

insertConeOrientation(p, conePos, coneOrientation)

Insert a point orientation for the in-edge for the point p in the DAG.

Not collective.
Parameters

	•		p ( int ) -- The point, which must lie in the chart set with DMPlex.setChart
	•		conePos ( int ) -- The local index in the cone where the point should be put.
	•		coneOrientation ( int ) -- The point orientation to insert.

Return type

None

SEE ALSO:

DM , DMPlex , DMPlex.create , DMPlex.getCone , DMPlex.setChart , DMPlex.setConeSize , DM.setUp , - DMPlexInsertConeOrientation

Source code at petsc4py/PETSc/DMPlex.pyx:581

interpolate()

Convert to a mesh with all intermediate faces, edges, etc.

Collective.

SEE ALSO:

DMPlex , DMPlex.uninterpolate , DMPlex.createFromCellList , DMPlexInterpolate

Source code at petsc4py/PETSc/DMPlex.pyx:1728
Return type

None

isDistributed()

Return the flag indicating if the mesh is distributed.

Collective.

SEE ALSO:

DM , DMPlex , DMPlex.distribute , DMPlexIsDistributed

Source code at petsc4py/PETSc/DMPlex.pyx:1618
Return type

bool

isSimplex()

Return the flag indicating if the first cell is a simplex.

Not collective.

SEE ALSO:

DM , DMPlex , DMPlex.getCellType , DMPlex.getHeightStratum , DMPlexIsSimplex

Source code at petsc4py/PETSc/DMPlex.pyx:1632
Return type

bool

labelCohesiveComplete(label, bdlabel, bdvalue, flip, split,
subdm)

Add all other mesh pieces to complete the surface.

Not collective.
Parameters

	•		label ( DMLabel ) -- A DMLabel marking the surface.
	•		bdlabel ( DMLabel ) -- A DMLabel marking the vertices on the boundary which will not be duplicated.
	•		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.
	•		split ( bool ) -- Flag to split faces incident on the surface boundary, rather than clamping those faces to the boundary
	•		subdm ( DMPlex ) -- The DMPlex associated with the label.

Return type

None

SEE ALSO:

DM , DMPlex , DMPlex.labelComplete , - DMPlexLabelCohesiveComplete

Source code at petsc4py/PETSc/DMPlex.pyx:1396

labelComplete(label)

Add the transitive closure to the surface.

Not collective.
Parameters

label ( DMLabel ) -- A DMLabel marking the surface points.

Return type

None

SEE ALSO:

DM , DMPlex , DMPlex.labelCohesiveComplete , - DMPlexLabelComplete

Source code at petsc4py/PETSc/DMPlex.pyx:1379

labelsLoad(viewer, sfxc)

Load labels into this DMPlex object.

Collective.
Parameters

	•		viewer ( Viewer ) -- The Viewer for the saved labels.
	•		sfxc ( SF ) -- The SF returned by topologyLoad .

Return type

None

SEE ALSO:

DM , DMPlex , DM.load , DMPlex.topologyLoad , DMPlex.coordinatesLoad , DM.view , SF , Viewer , - DMPlexLabelsLoad

Source code at petsc4py/PETSc/DMPlex.pyx:3344

labelsView(viewer)

Save DMPlex labels into a file.

Collective.
Parameters

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

localVectorLoad(viewer, sectiondm, sf, vec)

Load on-disk vector data into a local vector.

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

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

localVectorView(viewer, sectiondm, vec)

Save a local vector.

Collective.
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.
	•		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:3272

markBoundaryFaces(label, value=None)

Mark all faces on the boundary.

Not collective.
Parameters

	•		value ( int \| None ) -- The marker value, or DETERMINE or None to use some value in the closure (or 1 if none are found).
	•		label ( str )

Return type

DMLabel

SEE ALSO:

DM , DMPlex , DMLabel.create , DM.createLabel , - DMPlexMarkBoundaryFaces

Source code at petsc4py/PETSc/DMPlex.pyx:1352

metricAverage2(metric1, metric2, metricAvg)

Compute and return the unweighted average of two metrics.

Collective.
Parameters

	•		metric1 ( Vec ) -- The first metric to be averaged.
	•		metric2 ( Vec ) -- The second metric to be averaged.
	•		metricAvg ( Vec ) -- The output averaged metric.

Return type

Vec

SEE ALSO:

DMPlex.metricAverage3 , DMPlexMetricAverage2

Source code at petsc4py/PETSc/DMPlex.pyx:3059

metricAverage3(metric1, metric2, metric3, metricAvg)

Compute and return the unweighted average of three metrics.

Collective.
Parameters

	•		metric1 ( Vec ) -- The first metric to be averaged.
	•		metric2 ( Vec ) -- The second metric to be averaged.
	•		metric3 ( Vec ) -- The third metric to be averaged.
	•		metricAvg ( Vec ) -- The output averaged metric.

Return type

Vec

SEE ALSO:

DMPlex.metricAverage2 , DMPlexMetricAverage3

Source code at petsc4py/PETSc/DMPlex.pyx:3081

metricCreate(field=0)

Create a Riemannian metric field.

Collective.
Parameters

field ( int | None ) -- The field number to use.

Return type

Vec

SEE ALSO:

DMPlex.metricCreateUniform , DMPlex.metricCreateIsotropic , Working with PETSc options , DMPlexMetricCreate

Source code at petsc4py/PETSc/DMPlex.pyx:2890

metricCreateIsotropic(indicator, field=0)

Construct an isotropic metric from 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:2935

metricCreateUniform(alpha, field=0)

Construct a uniform isotropic metric.

Collective.
Parameters

	•		alpha ( float ) -- Scaling parameter for the diagonal.
	•		field ( int \| None ) -- The field number to use.

Return type

Vec

SEE ALSO:

DMPlex.metricCreate , DMPlex.metricCreateIsotropic , - DMPlexMetricCreateUniform

Source code at petsc4py/PETSc/DMPlex.pyx:2911

metricDeterminantCreate(field=0)

Create the determinant field for a Riemannian metric.

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

Source code at petsc4py/PETSc/DMPlex.pyx:2958

metricEnforceSPD(metric, ometric, determinant,
restrictSizes=False, restrictAnisotropy=False)

Enforce symmetric positive-definiteness of a metric.

Collective.
Parameters

	•		metric ( Vec ) -- The metric.
	•		ometric ( Vec ) -- The output metric.
	•		determinant ( Vec ) -- The output determinant.
	•		restrictSizes ( bool \| None ) -- Flag indicating whether maximum/minimum magnitudes should be enforced.
	•		restrictAnisotropy ( bool \| None ) -- Flag indicating 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

Source code at petsc4py/PETSc/DMPlex.pyx:2987

metricGetGradationFactor()

Return the metric gradation factor.

Not collective.

SEE ALSO:

DMPlex.metricSetGradationFactor , DMPlex.metricGetHausdorffNumber , - DMPlexMetricGetGradationFactor

Source code at petsc4py/PETSc/DMPlex.pyx:2841
Return type

float

metricGetHausdorffNumber()

Return the metric Hausdorff number.

Not collective.

SEE ALSO:

DMPlex.metricGetGradationFactor , DMPlex.metricSetHausdorffNumber , - DMPlexMetricGetHausdorffNumber

Source code at petsc4py/PETSc/DMPlex.pyx:2875
Return type

float

metricGetMaximumAnisotropy()

Return the maximum tolerated metric anisotropy.

Not collective.

SEE ALSO:

DMPlex.metricSetMaximumAnisotropy , DMPlex.metricGetMaximumMagnitude , - DMPlexMetricGetMaximumAnisotropy

Source code at petsc4py/PETSc/DMPlex.pyx:2739
Return type

float

metricGetMaximumMagnitude()

Return the maximum tolerated metric magnitude.

Not collective.

SEE ALSO:

DMPlex.metricSetMaximumMagnitude , DMPlex.metricGetMinimumMagnitude , - DMPlexMetricGetMaximumMagnitude

Source code at petsc4py/PETSc/DMPlex.pyx:2705
Return type

float

metricGetMinimumMagnitude()

Return the minimum tolerated metric magnitude.

Not collective.

SEE ALSO:

DMPlex.metricSetMinimumMagnitude , DMPlex.metricGetMaximumMagnitude , - DMPlexMetricGetMinimumMagnitude

Source code at petsc4py/PETSc/DMPlex.pyx:2671
Return type

float

metricGetNormalizationOrder()

Return the order p for L-p normalization.

Not collective.

SEE ALSO:

DMPlex.metricSetNormalizationOrder , DMPlex.metricGetTargetComplexity , - DMPlexMetricGetNormalizationOrder

Source code at petsc4py/PETSc/DMPlex.pyx:2807
Return type

float

metricGetNumIterations()

Return the number of parallel adaptation iterations.

Not collective.

SEE ALSO:

DMPlex.metricSetNumIterations , DMPlex.metricGetVerbosity , - DMPlexMetricGetNumIterations

Source code at petsc4py/PETSc/DMPlex.pyx:2637
Return type

int

metricGetTargetComplexity()

Return the target metric complexity.

Not collective.

SEE ALSO:

DMPlex.metricSetTargetComplexity , DMPlex.metricGetNormalizationOrder , - DMPlexMetricGetTargetComplexity

Source code at petsc4py/PETSc/DMPlex.pyx:2773
Return type

float

metricGetVerbosity()

Return the verbosity of the mesh adaptation package.

Not collective.
Returns

verbosity -- The verbosity, where -1 is silent and 10 is maximum.

Return type

int

SEE ALSO:

DMPlex.metricSetVerbosity , DMPlex.metricGetNumIterations , - DMPlexMetricGetVerbosity

Source code at petsc4py/PETSc/DMPlex.pyx:2598

metricIntersection2(metric1, metric2, metricInt)

Compute and return the intersection of two metrics.

Collective.
Parameters

	•		metric1 ( Vec ) -- The first metric to be intersected.
	•		metric2 ( Vec ) -- The second metric to be intersected.
	•		metricInt ( Vec ) -- The output intersected metric.

Return type

Vec

SEE ALSO:

DMPlex.metricIntersection3 , DMPlexMetricIntersection2

Source code at petsc4py/PETSc/DMPlex.pyx:3105

metricIntersection3(metric1, metric2, metric3, metricInt)

Compute the intersection of three metrics.

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.
	•		metricInt ( Vec ) -- The output intersected metric.

Return type

Vec

SEE ALSO:

DMPlex.metricIntersection2 , DMPlexMetricIntersection3

Source code at petsc4py/PETSc/DMPlex.pyx:3127

metricIsIsotropic()

Return the flag indicating whether the metric is isotropic or not.

Not collective.

SEE ALSO:

DMPlex.metricSetIsotropic , DMPlex.metricIsUniform , DMPlex.metricRestrictAnisotropyFirst , - DMPlexMetricIsIsotropic

Source code at petsc4py/PETSc/DMPlex.pyx:2386
Return type

bool

metricIsUniform()

Return the flag indicating whether the metric is uniform or not.

Not collective.

SEE ALSO:

DMPlex.metricSetUniform , DMPlex.metricRestrictAnisotropyFirst , - DMPlexMetricIsUniform

Source code at petsc4py/PETSc/DMPlex.pyx:2352
Return type

bool

metricNoInsertion()

Return the flag indicating whether node insertion and deletion are turned off.

Not collective.

SEE ALSO:

DMPlex.metricSetNoInsertion , DMPlex.metricNoSwapping , DMPlex.metricNoMovement , DMPlex.metricNoSurf , - DMPlexMetricNoInsertion

Source code at petsc4py/PETSc/DMPlex.pyx:2455
Return type

bool

metricNoMovement()

Return the flag indicating whether node movement is turned off.

Not collective.

SEE ALSO:

DMPlex.metricSetNoMovement , DMPlex.metricNoInsertion , DMPlex.metricNoSwapping , DMPlex.metricNoSurf , - DMPlexMetricNoMovement

Source code at petsc4py/PETSc/DMPlex.pyx:2527
Return type

bool

metricNoSurf()

Return the flag indicating whether surface modification is turned off.

Not collective.

SEE ALSO:

DMPlex.metricSetNoSurf , DMPlex.metricNoMovement , DMPlex.metricNoInsertion , DMPlex.metricNoSwapping , - DMPlexMetricNoSurf

Source code at petsc4py/PETSc/DMPlex.pyx:2563
Return type

bool

metricNoSwapping()

Return the flag indicating whether facet swapping is turned off.

Not collective.

SEE ALSO:

DMPlex.metricSetNoSwapping , DMPlex.metricNoInsertion , DMPlex.metricNoMovement , DMPlex.metricNoSurf , - DMPlexMetricNoSwapping

Source code at petsc4py/PETSc/DMPlex.pyx:2491
Return type

bool

metricNormalize(metric, ometric, determinant,
restrictSizes=True, restrictAnisotropy=True)

Apply L-p normalization to a metric.

Collective.
Parameters

	•		metric ( Vec ) -- The metric.
	•		ometric ( Vec ) -- The output metric.
	•		determinant ( Vec ) -- The output determinant.
	•		restrictSizes ( bool \| None ) -- Flag indicating whether maximum/minimum magnitudes should be enforced.
	•		restrictAnisotropy ( bool \| None ) -- Flag indicating whether maximum anisotropy should be enforced.

Returns

	•		ometric ( Vec ) -- The output normalized metric.
	•		determinant ( Vec ) -- The output determinant.

Return type

tuple [ Vec , Vec ]

SEE ALSO:

DMPlex.metricEnforceSPD , DMPlex.metricIntersection2 , DMPlex.metricIntersection3 , Working with PETSc options , DMPlexMetricNormalize

Source code at petsc4py/PETSc/DMPlex.pyx:3023

metricRestrictAnisotropyFirst()

Return true if anisotropy is restricted before normalization.

Not collective.

SEE ALSO:

DMPlex.metricIsIsotropic , DMPlex.metricSetRestrictAnisotropyFirst , - DMPlexMetricRestrictAnisotropyFirst

Source code at petsc4py/PETSc/DMPlex.pyx:2420
Return type

bool

metricSetFromOptions()

Configure the object from the options database.

Collective.

SEE ALSO:

Working with PETSc options

Source code at petsc4py/PETSc/DMPlex.pyx:2320
Return type

None

metricSetGradationFactor(beta)

Set the metric gradation factor.

Logically collective.
Parameters

beta ( float ) -- The metric gradation factor.

Return type

None

SEE ALSO:

DMPlex.metricGetGradationFactor , DMPlex.metricSetHausdorffNumber , - DMPlexMetricSetGradationFactor

Source code at petsc4py/PETSc/DMPlex.pyx:2822

metricSetHausdorffNumber(hausd)

Set the metric Hausdorff number.

Logically collective.
Parameters

hausd ( float ) -- The metric Hausdorff number.

Return type

None

SEE ALSO:

DMPlex.metricSetGradationFactor , DMPlex.metricGetHausdorffNumber , - DMPlexMetricSetHausdorffNumber

Source code at petsc4py/PETSc/DMPlex.pyx:2856

metricSetIsotropic(isotropic)

Record whether the metric is isotropic or not.

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

Source code at petsc4py/PETSc/DMPlex.pyx:2367

metricSetMaximumAnisotropy(a_max)

Set the maximum tolerated metric anisotropy.

Logically collective.
Parameters

a_max ( float ) -- The maximum tolerated metric anisotropy.

Return type

None

SEE ALSO:

DMPlex.metricGetMaximumAnisotropy , DMPlex.metricSetMaximumMagnitude , - DMPlexMetricSetMaximumAnisotropy

Source code at petsc4py/PETSc/DMPlex.pyx:2720

metricSetMaximumMagnitude(h_max)

Set the maximum tolerated metric magnitude.

Logically collective.
Parameters

h_max ( float ) -- The maximum tolerated metric magnitude.

Return type

None

SEE ALSO:

DMPlex.metricGetMaximumMagnitude , DMPlex.metricSetMinimumMagnitude , - DMPlexMetricSetMaximumMagnitude

Source code at petsc4py/PETSc/DMPlex.pyx:2686

metricSetMinimumMagnitude(h_min)

Set the minimum tolerated metric magnitude.

Logically collective.
Parameters

h_min ( float ) -- The minimum tolerated metric magnitude.

Return type

None

SEE ALSO:

DMPlex.metricGetMinimumMagnitude , DMPlex.metricSetMaximumMagnitude , - DMPlexMetricSetMinimumMagnitude

Source code at petsc4py/PETSc/DMPlex.pyx:2652

metricSetNoInsertion(noInsert)

Set the flag indicating whether node insertion should be turned off.

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

Source code at petsc4py/PETSc/DMPlex.pyx:2435

metricSetNoMovement(noMove)

Set the flag indicating whether node movement should be turned off.

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

Source code at petsc4py/PETSc/DMPlex.pyx:2507

metricSetNoSurf(noSurf)

Set the flag indicating whether surface modification should be turned off.

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

Source code at petsc4py/PETSc/DMPlex.pyx:2543

metricSetNoSwapping(noSwap)

Set the flag indicating whether facet swapping should be turned off.

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

Source code at petsc4py/PETSc/DMPlex.pyx:2471

metricSetNormalizationOrder(p)

Set the order p for L-p normalization.

Logically collective.
Parameters

p ( float ) -- The normalization order.

Return type

None

SEE ALSO:

DMPlex.metricGetNormalizationOrder , DMPlex.metricSetTargetComplexity , - DMPlexMetricSetNormalizationOrder

Source code at petsc4py/PETSc/DMPlex.pyx:2788

metricSetNumIterations(numIter)

Set the number of parallel adaptation iterations.

Logically collective.
Parameters

numIter ( int ) -- The number of parallel adaptation iterations.

Return type

None

SEE ALSO:

DMPlex.metricSetVerbosity , DMPlex.metricGetNumIterations , - DMPlexMetricSetNumIterations

Source code at petsc4py/PETSc/DMPlex.pyx:2618

metricSetRestrictAnisotropyFirst(restrictAnisotropyFirst)

Record whether anisotropy is be restricted before normalization or after.

Logically collective.
Parameters

restrictAnisotropyFirst ( bool ) -- Flag indicating if anisotropy is restricted before normalization or after.

Return type

None

SEE ALSO:

DMPlex.metricSetIsotropic , DMPlex.metricRestrictAnisotropyFirst , - DMPlexMetricSetRestrictAnisotropyFirst

Source code at petsc4py/PETSc/DMPlex.pyx:2401

metricSetTargetComplexity(targetComplexity)

Set the target metric complexity.

Logically collective.
Parameters

targetComplexity ( float ) -- The target metric complexity.

Return type

None

SEE ALSO:

DMPlex.metricGetTargetComplexity , DMPlex.metricSetNormalizationOrder , - DMPlexMetricSetTargetComplexity

Source code at petsc4py/PETSc/DMPlex.pyx:2754

metricSetUniform(uniform)

Record whether the metric is uniform or not.

Logically collective.
Parameters

uniform ( bool ) -- Flag indicating whether the metric is uniform or not.

Return type

None

SEE ALSO:

DMPlex.metricIsUniform , DMPlex.metricSetIsotropic , DMPlex.metricSetRestrictAnisotropyFirst , - DMPlexMetricSetUniform

Source code at petsc4py/PETSc/DMPlex.pyx:2333

metricSetVerbosity(verbosity)

Set the verbosity of the mesh adaptation package.

Logically collective.
Parameters

verbosity ( int ) -- The verbosity, where -1 is silent and 10 is maximum.

Return type

None

SEE ALSO:

DMPlex.metricGetVerbosity , DMPlex.metricSetNumIterations , - DMPlexMetricSetVerbosity

Source code at petsc4py/PETSc/DMPlex.pyx:2579

orient()

Give a consistent orientation to the input mesh.

Collective.

SEE ALSO:

DM , DMPlex , DM.create , DMPlexOrient

Source code at petsc4py/PETSc/DMPlex.pyx:873
Return type

None

permute(perm)

Reorder the mesh according to the input permutation.

Collective.
Parameters

perm ( IS ) -- The point permutation, perm[old point number] = new point number .

Returns

pdm -- The permuted DMPlex .

Return type

DMPlex

SEE ALSO:

DMPlex , Mat.permute , DMPlexPermute

Source code at petsc4py/PETSc/DMPlex.pyx:2158

rebalanceSharedPoints(entityDepth=0, useInitialGuess=True,
parallel=True)

Redistribute shared points in order to achieve better balancing.

Collective.
Parameters

	•		entityDepth ( int \| None ) -- Depth of the entity to balance (e.g., 0 -> balance vertices).
	•		useInitialGuess ( bool \| None ) -- Whether to use the current distribution as initial guess.
	•		parallel ( bool \| None ) -- Whether to use ParMETIS and do the partition in parallel or gather the graph onto a single process.

Returns

success -- Whether the graph partitioning was successful or not. Unsuccessful simply means no change to the partitioning.

Return type

bool

SEE ALSO:

DM , DMPlex , DMPlex.distribute , Working with PETSc options , DMPlexRebalanceSharedPoints

Source code at petsc4py/PETSc/DMPlex.pyx:1527

reorderGetDefault()

Return flag indicating whether the DMPlex should be reordered by default.

Not collective.

SEE ALSO:

None , DMPlexReorderGetDefault

Source code at petsc4py/PETSc/DMPlex.pyx:2182
Return type

ReorderDefaultFlag

reorderSetDefault(flag)

Set flag indicating whether the DM should be reordered by default.

Logically collective.
Parameters

	•		reorder -- Flag for reordering.
	•		flag ( ReorderDefaultFlag )

Return type

None

SEE ALSO:

DMPlex.reorderGetDefault , DMPlexReorderSetDefault

Source code at petsc4py/PETSc/DMPlex.pyx:2196

sectionLoad(viewer, sectiondm, sfxc)

Load section into a DM .

Collective.
Parameters

	•		viewer ( Viewer ) -- The Viewer that represents the on-disk section ( sectionA ).
	•		sectiondm ( DM ) -- The DM into which the on-disk section ( sectionA ) is migrated.
	•		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:3364

sectionView(viewer, sectiondm)

Save a section associated with a DMPlex .

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

setAdjacencyUseAnchors(useAnchors=True)

Define adjacency in the mesh using the point-to-point constraints.

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.

Return type

None

SEE ALSO:

DMPlex , DMPlex.getAdjacency , DMPlex.distribute , - DMPlexSetAdjacencyUseAnchors

Source code at petsc4py/PETSc/DMPlex.pyx:1431

setCellType(p, ctype)

Set the polytope type of a given cell.

Not collective.
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:663

setChart(pStart, pEnd)

Set the interval for all mesh points [ pStart , pEnd ).

Not collective.
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:421

setCone(p, cone, orientation=None)

Set the points on the in-edges for this point in the DAG.

Not collective.
Parameters

	•		p ( int ) -- The point, which must lie in the chart set with DMPlex.setChart .
	•		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:517

setConeOrientation(p, orientation)

Set the orientations on the in-edges for this point in the DAG.

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

setConeSize(p, size)

Set the number of in-edges for this point in the DAG.

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

setMatClosure(sec, gsec, mat, point, values, addv=None)

Set an array of the values on the closure of point .

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

setPartitioner(part)

Set the mesh partitioner.

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

setRefinementLimit(refinementLimit)

Set the maximum cell volume for refinement.

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

setRefinementUniform(refinementUniform=True)

Set the flag for uniform refinement.

Logically collective.
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 code at petsc4py/PETSc/DMPlex.pyx:2053

setSupport(p, supp)

Set the points on the out-edges for this point in the DAG.

Not collective.
Parameters

	•		p ( int ) -- The point, which must lie in the chart set with DMPlex.setChart .
	•		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 code at petsc4py/PETSc/DMPlex.pyx:797

setSupportSize(p, size)

Set the number of out-edges for this point in the DAG.

Not collective.
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 code at petsc4py/PETSc/DMPlex.pyx:746

setTetGenOptions(opts)

Set the options used for the Tetgen mesh generator.

Not collective.
Parameters

opts ( str ) -- The command line options.

Return type

None

SEE ALSO:

Working with PETSc options , DM , DMPlex , DMPlex.setTriangleOptions , DMPlex.generate , - DMPlexTetgenSetOptions

Source code at petsc4py/PETSc/DMPlex.pyx:1332

setTriangleOptions(opts)

Set the options used for the Triangle mesh generator.

Not collective.
Parameters

opts ( str ) -- The command line options.

Return type

None

SEE ALSO:

Working with PETSc options , DM , DMPlex , DMPlex.setTetGenOptions , DMPlex.generate , - DMPlexTriangleSetOptions

Source code at petsc4py/PETSc/DMPlex.pyx:1312

setVecClosure(sec, vec, point, values, addv=None)

Set an array of the values on the closure of point .

Not collective.
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 code at petsc4py/PETSc/DMPlex.pyx:1215

stratify()

Calculate the strata of DAG.

Collective.

SEE ALSO:

DM , DMPlex , DMPlex.create , DMPlex.symmetrize , - DMPlexStratify

Source code at petsc4py/PETSc/DMPlex.pyx:861
Return type

None

symmetrize()

Create support (out-edge) information from cone (in-edge) information.

Not collective.

SEE ALSO:

DM , DMPlex , DMPlex.create , DMPlex.setChart , DMPlex.setConeSize , DMPlex.setCone , DMPlexSymmetrize

Source code at petsc4py/PETSc/DMPlex.pyx:848
Return type

None

topologyLoad(viewer)

Load a topology into this DMPlex object.

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

SEE ALSO:

DM , DMPlex , DM.load , DMPlex.coordinatesLoad , DMPlex.labelsLoad , DM.view , SF , Viewer , - DMPlexTopologyLoad

Source code at petsc4py/PETSc/DMPlex.pyx:3298

topologyView(viewer)

Save a DMPlex topology into a file.

Collective.
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:3173

uninterpolate()

Convert to a mesh with only cells and vertices.

Collective.

SEE ALSO:

DMPlex , DMPlex.interpolate , DMPlex.createFromCellList , DMPlexUninterpolate

Source code at petsc4py/PETSc/DMPlex.pyx:1743
Return type

None

vecGetClosure(sec, vec, p)

Return an array of values on the closure of p .

Not collective.
Parameters

	•		sec ( Section ) -- The section describing the layout in vec .
	•		vec ( Vec ) -- The local vector.
	•		p ( int ) -- The point in the DMPlex .

Return type

ArrayScalar

SEE ALSO:

DM , DMPlex , DMPlexVecRestoreClosure

Source code at petsc4py/PETSc/DMPlex.pyx:1157

petsc4py.PETSc.DMPlexTransform

class petsc4py.PETSc.DMPlexTransform

Bases: Object

Mesh transformations.

Methods Summary

Image grohtml-288464-27.png

Methods Documentation
apply(dm)

Apply a mesh transformation.

Collective.

Source code at petsc4py/PETSc/DMPlex.pyx:3475
Parameters

dm ( DM )

Return type

create(comm=None)

Create a mesh transformation.

Collective.

SEE ALSO:

DMPlexTransformCreate

Source code at petsc4py/PETSc/DMPlex.pyx:3486
Parameters

comm ( Comm | None )

Return type

Self

destroy()

Destroy a mesh transformation.

Collective.

SEE ALSO:

DMPlexTransformDestroy

Source code at petsc4py/PETSc/DMPlex.pyx:3503
Return type

Self

getType()

Return the transformation type name.

Not collective.

SEE ALSO:

DMPlexTransformGetType

Source code at petsc4py/PETSc/DMPlex.pyx:3516
Return type

str

setDM(dm)

Set the DM for the transformation.

Logically collective.

Source code at petsc4py/PETSc/DMPlex.pyx:3554
Parameters

dm ( DM )

Return type

None

setFromOptions()

Configure the transformation from the options database.

Collective.

SEE ALSO:

Working with PETSc options , - DMPlexTransformSetFromOptions

Source code at petsc4py/PETSc/DMPlex.pyx:3563
Return type

None

setType(tr_type)

Set the transformation type.

Collective.

SEE ALSO:

DMPlexTransformSetType

Source code at petsc4py/PETSc/DMPlex.pyx:3540
Parameters

tr_type ( DMPlexTransformType | str )

Return type

None

setUp()

Setup a mesh transformation.

Collective.

Source code at petsc4py/PETSc/DMPlex.pyx:3530
Return type

Self

view(viewer=None)

View the mesh transformation.

Collective.
Parameters

viewer ( Viewer | None ) -- A Viewer instance or - None for the default viewer.

Return type

None

SEE ALSO:

Viewer , DMPlexTransformView

Source code at petsc4py/PETSc/DMPlex.pyx:3575

petsc4py.PETSc.DMPlexTransformType

class petsc4py.PETSc.DMPlexTransformType

Bases: object

Transformation types.

Attributes Summary

Image grohtml-288464-28.png

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

petsc4py.PETSc.DMShell

class petsc4py.PETSc.DMShell

Bases: DM

A shell DM object, used to manage user-defined problem data.

Methods Summary

Image grohtml-288464-29.png

Methods Documentation
create(comm=None)

Creates a shell DM object.

Collective.
Parameters

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

Return type

Self

SEE ALSO:

DMShellCreate

Source code at petsc4py/PETSc/DMShell.pyx:4

setCoarsen(coarsen, args=None, kargs=None)

Set the routine used to coarsen the DMShell .

Logically collective.
Parameters

	•		coarsen ( Callable[[DM, Comm], DM] \| None ) -- The routine which coarsens the DM.
	•		args ( tuple[Any, ...] \| None ) -- Additional positional arguments for coarsen .
	•		kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for coarsen .

Return type

None

SEE ALSO:

setRefine , DMShellSetCoarsen

Source code at petsc4py/PETSc/DMShell.pyx:368

setCreateDomainDecomposition(decomp, args=None, kargs=None)

Set the routine used to create a domain decomposition.

Logically collective.
Parameters

	•		decomp ( Callable[[DM], tuple[list[str] \| None, - list[IS] \| None, list[IS] \| None, list[DM] \| - None]] \| None ) -- The routine to create the decomposition.
	•		args ( tuple[Any, ...] \| None ) -- Additional positional arguments for decomp .
	•		kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for decomp .

Return type

None

SEE ALSO:

DMShellSetCreateDomainDecomposition

Source code at petsc4py/PETSc/DMShell.pyx:560

setCreateDomainDecompositionScatters(scatter, args=None,
kargs=None)

Set the routine used to create the scatter contexts for domain decomposition.

Logically collective.
Parameters

	•		scatter ( Callable[[DM, list[DM]], tuple[list[- Scatter], list[Scatter], list[Scatter]]] \| None ) -- The routine to create the scatters.
	•		args ( tuple[Any, ...] \| None ) -- Additional positional arguments for scatter .
	•		kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for scatter .

Return type

None

SEE ALSO:

DMShellSetCreateDomainDecompositionScatters

Source code at petsc4py/PETSc/DMShell.pyx:592

setCreateFieldDecomposition(decomp, args=None, kargs=None)

Set the routine used to create a field decomposition.

Logically collective.
Parameters

	•		decomp ( Callable[[DM], tuple[list[str] \| None, - list[IS] \| None, list[DM] \| None]] \| None ) -- The routine to create the decomposition.
	•		args ( tuple[Any, ...] \| None ) -- Additional positional arguments for decomp .
	•		kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for decomp .

Return type

None

SEE ALSO:

DMShellSetCreateFieldDecomposition

Source code at petsc4py/PETSc/DMShell.pyx:528

setCreateGlobalVector(create_gvec, args=None, kargs=None)

Set the routine to create a global vector.

Logically collective.
Parameters

	•		create_gvec ( Callable[[DM], Vec] \| None ) -- The creation routine.
	•		args ( tuple[Any, ...] \| None ) -- Additional positional arguments for create_gvec .
	•		kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for create_gvec .

Return type

None

SEE ALSO:

setCreateLocalVector , DMShellSetCreateGlobalVector

Source code at petsc4py/PETSc/DMShell.pyx:76

setCreateInjection(create_injection, args=None, kargs=None)

Set the routine used to create the injection operator.

Logically collective.
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)

Set the routine used to create the interpolation operator.

Logically collective.
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)

Set the routine to create a local vector.

Logically collective.
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)

Set the routine to create a matrix.

Logically collective.
Parameters

	•		create_matrix ( Callable[[DM], Mat] \| None ) -- The function to create 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)

Set the routine used to create the restriction operator.

Logically collective.
Parameters

	•		create_restriction ( Callable[[DM, DM], Mat] \| - None ) -- The routine to create the restriction
	•		args ( tuple[Any, ...] \| None ) -- Additional positional arguments for create_restriction .
	•		kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for create_restriction .

Return type

None

SEE ALSO:

DMShellSetCreateRestriction

Source code at petsc4py/PETSc/DMShell.pyx:496

setCreateSubDM(create_subdm, args=None, kargs=None)

Set the routine used to create a sub DM from the DMShell .

Logically collective.
Parameters

	•		subdm -- The routine to create the decomposition.
	•		args ( tuple[Any, ...] \| None ) -- Additional positional arguments for subdm .
	•		kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for subdm .
	•		create_subdm ( Callable[[DM, Sequence[int]], - tuple[IS, DM]] \| None )

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)

Set the routines used to perform a global to local scatter.

Logically collective.
Parameters

	•		dm -- The DMShell .
	•		begin ( Callable[[DM, Vec, InsertMode, Vec], - None] \| None ) -- The routine which begins the global to local scatter.
	•		end ( Callable[[DM, Vec, InsertMode, Vec], None] \| None ) -- The routine which ends the global to local scatter.
	•		begin_args ( tuple[Any, ...] \| None ) -- Additional positional arguments for begin .
	•		begin_kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for begin .
	•		end_args ( tuple[Any, ...] \| None ) -- Additional positional arguments for end .
	•		end_kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for end .

Return type

None

SEE ALSO:

DMShellSetGlobalToLocal

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

setGlobalToLocalVecScatter(gtol)

Set a Scatter context for global to local communication.

Logically collective.
Parameters

gtol ( Scatter ) -- The global to local Scatter context.

Return type

None

SEE ALSO:

DMShellSetGlobalToLocalVecScatter

Source code at petsc4py/PETSc/DMShell.pyx:189

setGlobalVector(gv)

Set a template global vector.

Logically collective.
Parameters

gv ( Vec ) -- Template vector.

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)

Set the routines used to perform a local to global scatter.

Logically collective.
Parameters

	•		begin ( Callable[[DM, Vec, InsertMode, Vec], - None] \| None ) -- The routine which begins the local to global scatter.
	•		end ( Callable[[DM, Vec, InsertMode, Vec], None] \| None ) -- The routine which ends the local to global scatter.
	•		begin_args ( tuple[Any, ...] \| None ) -- Additional positional arguments for begin .
	•		begin_kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for begin .
	•		end_args ( tuple[Any, ...] \| None ) -- Additional positional arguments for end .
	•		end_kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for end .

Return type

None

SEE ALSO:

DMShellSetLocalToGlobal

Source code at petsc4py/PETSc/DMShell.pyx:206

setLocalToGlobalVecScatter(ltog)

Set a Scatter context for local to global communication.

Logically collective.
Parameters

ltog ( Scatter ) -- The local to global Scatter context.

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)

Set the routines used to perform a local to local scatter.

Logically collective.
Parameters

	•		begin ( Callable[[DM, Vec, InsertMode, Vec], - None] \| None ) -- The routine which begins the local to local scatter.
	•		end ( Callable[[DM, Vec, InsertMode, Vec], None] \| None ) -- The routine which ends the local to local scatter.
	•		begin_args ( tuple[Any, ...] \| None ) -- Additional positional arguments for begin .
	•		begin_kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for begin .
	•		end_args ( tuple[Any, ...] \| None ) -- Additional positional arguments for end .
	•		end_kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for end .

Return type

None

SEE ALSO:

DMShellSetLocalToLocal

Source code at petsc4py/PETSc/DMShell.pyx:270

setLocalToLocalVecScatter(ltol)

Set a Scatter context for local to local communication.

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)

Set a template local vector.

Logically collective.
Parameters

lv ( Vec ) -- Template vector.

Return type

None

SEE ALSO:

setGlobalVector , DMShellSetLocalVector

Source code at petsc4py/PETSc/DMShell.pyx:59

setMatrix(mat)

Set a template matrix.

Collective.
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)

Set the routine used to refine the DMShell .

Logically collective.
Parameters

	•		refine ( Callable[[DM, Comm], DM] \| None ) -- The routine which refines the DM.
	•		args ( tuple[Any, ...] \| None ) -- Additional positional arguments for refine .
	•		kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for refine .

Return type

None

SEE ALSO:

setCoarsen , DMShellSetRefine

Source code at petsc4py/PETSc/DMShell.pyx:400

petsc4py.PETSc.DMStag

class petsc4py.PETSc.DMStag

Bases: DM

A DM object representing a "staggered grid" or a structured cell complex.

Enumerations

Image grohtml-288464-30.png

petsc4py.PETSc.DMStag.StencilLocation

class petsc4py.PETSc.DMStag.StencilLocation

Bases: object

Stencil location types.

Attributes Summary

Image grohtml-288464-31.png

Attributes Documentation
BACK: int = BACK

Constant BACK of type int

BACK_DOWN: int = BACK_DOWN

Constant BACK_DOWN of type int

BACK_DOWN_LEFT: int = BACK_DOWN_LEFT

Constant BACK_DOWN_LEFT of type int

BACK_DOWN_RIGHT: int = BACK_DOWN_RIGHT

Constant BACK_DOWN_RIGHT of type int

BACK_LEFT: int = BACK_LEFT

Constant BACK_LEFT of type int

BACK_RIGHT: int = BACK_RIGHT

Constant BACK_RIGHT of type int

BACK_UP: int = BACK_UP

Constant BACK_UP of type int

BACK_UP_LEFT: int = BACK_UP_LEFT

Constant BACK_UP_LEFT of type int

BACK_UP_RIGHT: int = BACK_UP_RIGHT

Constant BACK_UP_RIGHT of type int

DOWN: int = DOWN

Constant DOWN of type int

DOWN_LEFT: int = DOWN_LEFT

Constant DOWN_LEFT of type int

DOWN_RIGHT: int = DOWN_RIGHT

Constant DOWN_RIGHT of type int

ELEMENT: int = ELEMENT

Constant ELEMENT of type int

FRONT: int = FRONT

Constant FRONT of type int

FRONT_DOWN: int = FRONT_DOWN

Constant FRONT_DOWN of type int

FRONT_DOWN_LEFT: int = FRONT_DOWN_LEFT

Constant FRONT_DOWN_LEFT of type int

FRONT_DOWN_RIGHT: int = FRONT_DOWN_RIGHT

Constant FRONT_DOWN_RIGHT of type int

FRONT_LEFT: int = FRONT_LEFT

Constant FRONT_LEFT of type int

FRONT_RIGHT: int = FRONT_RIGHT

Constant FRONT_RIGHT of type int

FRONT_UP: int = FRONT_UP

Constant FRONT_UP of type int

FRONT_UP_LEFT: int = FRONT_UP_LEFT

Constant FRONT_UP_LEFT of type int

FRONT_UP_RIGHT: int = FRONT_UP_RIGHT

Constant FRONT_UP_RIGHT of type int

LEFT: int = LEFT

Constant LEFT of type int

NULLLOC: int = NULLLOC

Constant NULLLOC of type int

RIGHT: int = RIGHT

Constant RIGHT of type int

UP: int = UP

Constant UP of type int

UP_LEFT: int = UP_LEFT

Constant UP_LEFT of type int

UP_RIGHT: int = UP_RIGHT

Constant UP_RIGHT of type int

petsc4py.PETSc.DMStag.StencilType

class petsc4py.PETSc.DMStag.StencilType

Bases: object

Stencil types.

Attributes Summary

Image grohtml-288464-32.png

Attributes Documentation
BOX: int = BOX

Constant BOX of type int

NONE: int = NONE

Constant NONE of type int

STAR: int = STAR

Constant STAR of type int

Methods Summary

Image grohtml-288464-33.png

Attributes Summary

Image grohtml-288464-34.png

Methods Documentation
VecSplitToDMDA(vec, loc, c)

Return DMDA , Vec from a subgrid of a DMStag , its Vec .

Collective.

If a c value of -k is provided, the first k DOFs for that position are extracted, padding with zero values if needed. If a non-negative value is provided, a single DOF is extracted.
Parameters

	•		vec ( Vec ) -- The Vec object.
	•		loc ( 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)

Create a DMDA object.

Collective.

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.
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 ( StencilType \| None ) -- The ghost/halo stencil type.
	•		stencil_width ( int \| None ) -- The width of the ghost/halo region.
	•		proc_sizes ( tuple[int, ...] \| None ) -- The number of processes in x, y, z dimensions.
	•		ownership_ranges ( tuple[Sequence[int], ...] \| - None ) -- Local x, y, z element counts, of length equal to proc_sizes , summing to sizes .
	•		comm ( Comm \| None ) -- MPI communicator, defaults to Sys.getDefaultComm .
	•		setUp ( bool \| None ) -- Whether to call the setup routine after creating the object.

Return type

Self

SEE ALSO:

DMStagCreate1d , DMStagCreate2d , DMStagCreate3d , - DMSetUp

Source code at petsc4py/PETSc/DMStag.pyx:50

createCompatibleDMStag(dofs)

Create a compatible DMStag with different DOFs/stratum.

Collective.
Parameters

dofs ( tuple[int, ...] ) -- The number of DOFs on the strata in the new DMStag .

Return type

SEE ALSO:

DMStagCreateCompatibleDMStag

Source code at petsc4py/PETSc/DMStag.pyx:766

get1dCoordinatecArrays()

Not implemented.

Source code at petsc4py/PETSc/DMStag.pyx:832
Return type

None

getBoundaryTypes()

Return 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 starting element index, width and number of partial elements.

Not collective.

The returned value is calculated excluding ghost points.

The number of extra partial elements is either 1 or 0 . The value is 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 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.

SEE ALSO:

DMStagGetEntriesPerElement

Source code at petsc4py/PETSc/DMStag.pyx:318
Return type

int

getGhostCorners()

Return starting element index and width of 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 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 , ...]

getLocalSizes()

Return local elementwise sizes in each dimension.

Not collective.

The returned value is calculated excluding ghost points.

SEE ALSO:

getGlobalSizes , DMStagGetLocalSizes

Source code at petsc4py/PETSc/DMStag.pyx:400
Return type

tuple [ int , ...]

getLocationDof(loc)

Return number of DOFs associated with a given point on the grid.

Not collective.
Parameters

loc ( StencilLocation ) -- The grid point.

Return type

int

SEE ALSO:

DMStagGetLocationDOF

Source code at petsc4py/PETSc/DMStag.pyx:721

getLocationSlot(loc, c)

Return index to use in accessing raw local arrays.

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

Return elements per process in each dimension.

Not collective.

SEE ALSO:

setOwnershipRanges , DMStagGetOwnershipRanges

Source code at petsc4py/PETSc/DMStag.pyx:461
Return type

tuple [ Sequence [ int ], ...]

getProcSizes()

Return number of processes in each dimension.

Not collective.

SEE ALSO:

DMStagGetNumRanks

Source code at petsc4py/PETSc/DMStag.pyx:432
Return type

tuple [ int , ...]

getProductCoordinateLocationSlot(loc)

Return slot for 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()

Return elementwise ghost/halo stencil type.

Not collective.

SEE ALSO:

setStencilType , DMStagGetStencilType

Source code at petsc4py/PETSc/DMStag.pyx:447
Return type

str

getStencilWidth()

Return elementwise stencil width.

Not collective.

SEE ALSO:

DMStagGetStencilWidth

Source code at petsc4py/PETSc/DMStag.pyx:334
Return type

int

getVecArray(vec)

Not implemented.

Source code at petsc4py/PETSc/DMStag.pyx:828
Parameters

vec ( Vec )

Return type

None

migrateVec(vec, dmTo, vecTo)

Transfer a vector between two DMStag objects.

Collective.

Currently only implemented to migrate global vectors to global vectors.
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)

Set the boundary types.

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)

Set the type to store coordinates.

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)

Set DOFs/stratum.

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

SEE ALSO:

DMStagSetDOF

Source code at petsc4py/PETSc/DMStag.pyx:224

setGlobalSizes(sizes)

Set global element counts in each dimension.

Logically collective.
Parameters

sizes ( tuple[int, ...] ) -- Global elementwise size in the one/two/three dimensions.

Return type

None

SEE ALSO:

DMStagSetGlobalSizes

Source code at petsc4py/PETSc/DMStag.pyx:246

setOwnershipRanges(ranges)

Set elements per process in each dimension.

Logically collective.
Parameters

ranges ( tuple[Sequence[int], ...] ) -- Element counts for each process in one/two/three dimensions.

Return type

None

SEE ALSO:

getOwnershipRanges , DMStagSetOwnershipRanges

Source code at petsc4py/PETSc/DMStag.pyx:286

setProcSizes(sizes)

Set the number of processes in each dimension in the global process grid.

Logically collective.
Parameters

sizes ( tuple[int, ...] ) -- Number of processes in one/two/three dimensions.

Return type

None

SEE ALSO:

DMStagSetNumRanks

Source code at petsc4py/PETSc/DMStag.pyx:266

setStencilType(stenciltype)

Set elementwise ghost/halo stencil type.

Logically collective.
Parameters

stenciltype ( StencilType | str ) -- The elementwise ghost stencil type.

Return type

None

SEE ALSO:

getStencilType , DMStagSetStencilType

Source code at petsc4py/PETSc/DMStag.pyx:183

setStencilWidth(swidth)

Set elementwise stencil width.

Logically collective.

The width value is not used when StencilType.NONE is specified.
Parameters

swidth ( int ) -- Stencil/halo/ghost width in elements.

Return type

None

SEE ALSO:

DMStagSetStencilWidth

Source code at petsc4py/PETSc/DMStag.pyx:163

setUniformCoordinates(xmin=0, xmax=1, ymin=0, ymax=1, zmin=0,
zmax=1)

Set the coordinates to be a uniform grid..

Collective.

Local coordinates are populated, linearly extrapolated to ghost cells, including those outside the physical domain. This is also done in case of periodic boundaries, meaning that the same global point may have different coordinates in different local representations, which are equivalent assuming a periodicity implied by the arguments to this function, i.e., two points are equivalent if their difference is a multiple of xmax-xmin in the x dimension, ymax-ymin in the y dimension, and zmax-zmin in the z dimension.
Parameters

	•		xmin ( float ) -- The minimum global coordinate value in the x dimension.
	•		xmax ( float ) -- The maximum global coordinate value in the x dimension.
	•		ymin ( float ) -- The minimum global coordinate value in the y dimension.
	•		ymax ( float ) -- The maximum global coordinate value in the y dimension.
	•		zmin ( float ) -- The minimum global coordinate value in the z dimension.
	•		zmax ( float ) -- The maximum global coordinate value in the z dimension.

Return type

None

SEE ALSO:

setUniformCoordinatesExplicit , setUniformCoordinatesProduct , - DMStagSetUniformCoordinates

Source code at petsc4py/PETSc/DMStag.pyx:610

setUniformCoordinatesExplicit(xmin=0, xmax=1, ymin=0, ymax=1,
zmin=0, zmax=1)

Set coordinates to be a uniform grid, storing all values.

Collective.
Parameters

	•		xmin ( float ) -- The minimum global coordinate value in the x dimension.
	•		xmax ( float ) -- The maximum global coordinate value in the x dimension.
	•		ymin ( float ) -- The minimum global coordinate value in the y dimension.
	•		ymax ( float ) -- The maximum global coordinate value in the y dimension.
	•		zmin ( float ) -- The minimum global coordinate value in the z dimension.
	•		zmax ( float ) -- The maximum global coordinate value in the z dimension.

Return type

None

SEE ALSO:

setUniformCoordinatesProduct , setUniformCoordinates , - DMStagSetUniformCoordinatesExplicit

Source code at petsc4py/PETSc/DMStag.pyx:530

setUniformCoordinatesProduct(xmin=0, xmax=1, ymin=0, ymax=1,
zmin=0, zmax=1)

Create uniform coordinates, as a product of 1D arrays.

Collective.

The per-dimension 1-dimensional DMStag objects that comprise the product always have active 0-cells (vertices, element boundaries) and 1-cells (element centers).
Parameters

	•		xmin ( float ) -- The minimum global coordinate value in the x dimension.
	•		xmax ( float ) -- The maximum global coordinate value in the x dimension.
	•		ymin ( float ) -- The minimum global coordinate value in the y dimension.
	•		ymax ( float ) -- The maximum global coordinate value in the y dimension.
	•		zmin ( float ) -- The minimum global coordinate value in the z dimension.
	•		zmax ( float ) -- The maximum global coordinate value in the z dimension.

Return type

None

SEE ALSO:

setUniformCoordinatesExplicit , setUniformCoordinates , DMStagSetUniformCoordinatesProduct

Source code at petsc4py/PETSc/DMStag.pyx:568

Attributes Documentation
boundary_types

Boundary types in each dimension.

Source code at petsc4py/PETSc/DMStag.pyx:866

corners

The lower left corner and size of local region in each dimension.

Source code at petsc4py/PETSc/DMStag.pyx:881

dim

The dimension.

Source code at petsc4py/PETSc/DMStag.pyx:836

dofs

The number of DOFs associated with each stratum of the grid.

Source code at petsc4py/PETSc/DMStag.pyx:841

entries_per_element

The number of entries per element in the local representation.

Source code at petsc4py/PETSc/DMStag.pyx:846

ghost_corners

The lower left corner and size of local region in each dimension.

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

The number of processes in each dimension in the global decomposition.

Source code at petsc4py/PETSc/DMStag.pyx:861

stencil_type

Stencil type.

Source code at petsc4py/PETSc/DMStag.pyx:871

stencil_width

Elementwise stencil width.

Source code at petsc4py/PETSc/DMStag.pyx:876

petsc4py.PETSc.DMSwarm

class petsc4py.PETSc.DMSwarm

Bases: DM

A DM object used to represent arrays of data (fields) of arbitrary type.

Enumerations

Image grohtml-288464-35.png

petsc4py.PETSc.DMSwarm.CollectType

class petsc4py.PETSc.DMSwarm.CollectType

Bases: object

Swarm collection types.

Attributes Summary

Image grohtml-288464-36.png

Attributes Documentation
COLLECT_BASIC: int = COLLECT_BASIC

Constant COLLECT_BASIC of type int

COLLECT_DMDABOUNDINGBOX: int = COLLECT_DMDABOUNDINGBOX

Constant COLLECT_DMDABOUNDINGBOX of type int

COLLECT_GENERAL: int = COLLECT_GENERAL

Constant COLLECT_GENERAL of type int

COLLECT_USER: int = COLLECT_USER

Constant COLLECT_USER of type int

petsc4py.PETSc.DMSwarm.MigrateType

class petsc4py.PETSc.DMSwarm.MigrateType

Bases: object

Swarm migration types.

Attributes Summary

Image grohtml-288464-37.png

Attributes Documentation
MIGRATE_BASIC: int = MIGRATE_BASIC

Constant MIGRATE_BASIC of type int

MIGRATE_DMCELLEXACT: int = MIGRATE_DMCELLEXACT

Constant MIGRATE_DMCELLEXACT of type int

MIGRATE_DMCELLNSCATTER: int = MIGRATE_DMCELLNSCATTER

Constant MIGRATE_DMCELLNSCATTER of type int

MIGRATE_USER: int = MIGRATE_USER

Constant MIGRATE_USER of type int

petsc4py.PETSc.DMSwarm.PICLayoutType

class petsc4py.PETSc.DMSwarm.PICLayoutType

Bases: object

Swarm PIC layout types.

Attributes Summary

Image grohtml-288464-38.png

Attributes Documentation
LAYOUT_GAUSS: int = LAYOUT_GAUSS

Constant LAYOUT_GAUSS of type int

LAYOUT_REGULAR: int = LAYOUT_REGULAR

Constant LAYOUT_REGULAR of type int

LAYOUT_SUBDIVISION: int = LAYOUT_SUBDIVISION

Constant LAYOUT_SUBDIVISION of type int

petsc4py.PETSc.DMSwarm.Type

class petsc4py.PETSc.DMSwarm.Type

Bases: object

Swarm types.

Attributes Summary

Image grohtml-288464-39.png

Attributes Documentation
BASIC: int = BASIC

Constant BASIC of type int

PIC: int = PIC

Constant PIC of type int

Methods Summary

Image grohtml-288464-40.png

Methods Documentation
addNPoints(npoints)

Add space for a number of new points in the DMSwarm .

Not collective.
Parameters

npoints ( int ) -- The number of new points to add.

Return type

None

SEE ALSO:

DMSwarmAddNPoints

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

addPoint()

Add space for one new point in the DMSwarm .

Not collective.

SEE ALSO:

DMSwarmAddPoint

Source code at petsc4py/PETSc/DMSwarm.pyx:317
Return type

None

collectViewCreate()

Apply a collection method and gather points in neighbor ranks.

Collective.

SEE ALSO:

collectViewDestroy , DMSwarmCollectViewCreate

Source code at petsc4py/PETSc/DMSwarm.pyx:445
Return type

None

collectViewDestroy()

Reset the DMSwarm to the size prior to calling collectViewCreate .

Collective.

SEE ALSO:

collectViewCreate , DMSwarmCollectViewDestroy

Source code at petsc4py/PETSc/DMSwarm.pyx:457
Return type

None

copyPoint(pi, pj)

Copy point pi to point pj in the DMSwarm .

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

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

create(comm=None)

Create an empty DM object and set its type to DM.Type.SWARM .

Collective.

DMs are the abstract objects in PETSc that mediate between meshes and discretizations and the algebraic solvers, time integrators, and optimization algorithms.
Parameters

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

Return type

Self

SEE ALSO:

DMCreate , DMSetType

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

createGlobalVectorFromField(fieldname)

Create a global Vec object associated with a given field.

Collective.

The vector must be returned to the DMSwarm using a matching call to destroyGlobalVectorFromField .
Parameters

fieldname ( str ) -- The textual name given to a registered field.

Return type

Vec

SEE ALSO:

destroyGlobalVectorFromField , - DMSwarmCreateGlobalVectorFromField

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

createLocalVectorFromField(fieldname)

Create a local Vec object associated with a given field.

Collective.

The vector must be returned to the DMSwarm using a matching call to destroyLocalVectorFromField .
Parameters

fieldname ( str ) -- The textual name given to a registered field.

Return type

Vec

SEE ALSO:

destroyLocalVectorFromField , - DMSwarmCreateLocalVectorFromField

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

destroyGlobalVectorFromField(fieldname)

Destroy the global Vec object associated with a given field.

Collective.
Parameters

fieldname ( str ) -- The textual name given to a registered field.

Return type

None

SEE ALSO:

createGlobalVectorFromField , - DMSwarmDestroyGlobalVectorFromField

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

destroyLocalVectorFromField(fieldname)

Destroy the local Vec object associated with a given field.

Collective.
Parameters

fieldname ( str ) -- The textual name given to a registered field.

Return type

None

SEE ALSO:

createLocalVectorFromField , - DMSwarmDestroyLocalVectorFromField

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

finalizeFieldRegister()

Finalize the registration of fields to a DMSwarm .

Collective.

SEE ALSO:

initializeFieldRegister , DMSwarmFinalizeFieldRegister

Source code at petsc4py/PETSc/DMSwarm.pyx:167
Return type

None

getCellDM()

Return DM cell attached to DMSwarm .

Collective.

SEE ALSO:

setCellDM , DMSwarmGetCellDM

Source code at petsc4py/PETSc/DMSwarm.pyx:486
Return type

getField(fieldname)

Return arrays storing all entries associated with a field.

Not collective.

The returned array contains underlying values of the field.

The array must be returned to the DMSwarm using a matching call to restoreField .
Parameters

fieldname ( str ) -- The textual name to identify this field.

Returns

The type of the entries in the array will match the type of the field.

Return type

numpy.ndarray

SEE ALSO:

restoreField , DMSwarmGetField

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

getLocalSize()

Return the local length of fields registered.

Not collective.

SEE ALSO:

DMSwarmGetLocalSize

Source code at petsc4py/PETSc/DMSwarm.pyx:398
Return type

int

getSize()

Return the total length of fields registered.

Collective.

SEE ALSO:

DMSwarmGetSize

Source code at petsc4py/PETSc/DMSwarm.pyx:412
Return type

int

initializeFieldRegister()

Initiate the registration of fields to a DMSwarm .

Collective.

After all fields have been registered, you must call finalizeFieldRegister .

SEE ALSO:

finalizeFieldRegister , DMSwarmInitializeFieldRegister

Source code at petsc4py/PETSc/DMSwarm.pyx:153
Return type

None

insertPointUsingCellDM(layoutType, fill_param)

Insert point coordinates within each cell.

Not collective.
Parameters

	•		layout_type -- Method used to fill each cell with the cell DM.
	•		fill_param ( int ) -- Parameter controlling how many points per cell are added (the meaning of this parameter is dependent on the layout type).
	•		layoutType ( PICLayoutType )

Return type

None

SEE ALSO:

DMSwarmInsertPointsUsingCellDM

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

migrate(remove_sent_points=False)

Relocate points defined in the DMSwarm to other MPI ranks.

Collective.
Parameters

remove_sent_points ( bool ) -- Flag indicating if sent points should be removed from the current MPI rank.

Return type

None

SEE ALSO:

DMSwarmMigrate

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

projectFields(dm, fieldnames, vecs, mode=None)

Project a set of DMSwarm fields onto the cell DM .

Collective.
Parameters

	•		dm ( DM ) -- The continuum DM .
	•		fieldnames ( Sequence[str] ) -- The textual names of the swarm fields to project.
	•		vecs ( Sequence[Vec] )
	•		mode ( ScatterModeSpec )

Return type

None

SEE ALSO:

DMSwarmProjectFields

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

registerField(fieldname, blocksize, dtype=ScalarType)

Collective.
Parameters

	•		fieldname ( str ) -- The textual name to identify this field.
	•		blocksize ( int ) -- The number of each data type.
	•		dtype ( dtype ) -- A valid PETSc data type.

Return type

None

SEE ALSO:

DMSwarmRegisterPetscDatatypeField

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

removePoint()

Remove the last point from the DMSwarm .

Not collective.

SEE ALSO:

DMSwarmRemovePoint

Source code at petsc4py/PETSc/DMSwarm.pyx:347
Return type

None

removePointAtIndex(index)

Remove a specific point from the DMSwarm .

Not collective.
Parameters

index ( int ) -- Index of point to remove

Return type

None

SEE ALSO:

DMSwarmRemovePointAtIndex

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

restoreField(fieldname)

Restore accesses associated with a registered field.

Not collective.
Parameters

fieldname ( str ) -- The textual name to identify this field.

Return type

None

SEE ALSO:

getField , DMSwarmRestoreField

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

setCellDM(dm)

Attach a DM to a DMSwarm .

Collective.
Parameters

dm ( DM ) -- The DM to attach to the DMSwarm .

Return type

None

SEE ALSO:

getCellDM , DMSwarmSetCellDM

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

setLocalSizes(nlocal, buffer)

Set the length of all registered fields on the DMSwarm .

Not collective.
Parameters

	•		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:179

setPointCoordinates(coordinates, redundant=False, mode=None)

Set point coordinates in a DMSwarm from a user-defined list.

Collective.
Parameters

	•		coordinates ( Sequence[float] ) -- The coordinate values.
	•		redundant ( bool ) -- If set to True , it is assumed that coordinates are only valid on rank 0 and should be broadcast to other ranks.
	•		mode ( InsertMode \| None ) -- Indicates whether to append points to the swarm ( InsertMode.ADD ), or override existing points ( InsertMode.INSERT ).

Return type

None

SEE ALSO:

DMSwarmSetPointCoordinates

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

setPointCoordinatesCellwise(coordinates)

Insert point coordinates within each cell.

Not collective.

Point coordinates are defined over the reference cell.
Parameters

coordinates ( Sequence[float] ) -- The coordinates (defined in the local coordinate system for each cell) to insert.

Return type

None

SEE ALSO:

DMSwarmSetPointCoordinatesCellwise

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

setPointsUniformCoordinates(min, max, npoints, mode=None)

Set point coordinates in a DMSwarm on a regular (ijk) grid.

Collective.
Parameters

	•		min ( Sequence[float] ) -- Minimum coordinate values in the x, y, z directions (array of length dim ).
	•		max ( Sequence[float] ) -- Maximum coordinate values in the x, y, z directions (array of length dim ).
	•		npoints ( Sequence[int] ) -- Number of points in each spatial direction (array of length dim ).
	•		mode ( InsertMode \| None ) -- Indicates whether to append points to the swarm ( InsertMode.ADD ), or override existing points ( InsertMode.INSERT ).

Return type

Self

SEE ALSO:

DMSwarmSetPointsUniformCoordinates

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

setType(dmswarm_type)

Set particular flavor of DMSwarm .

Collective.
Parameters

dmswarm_type ( Type | str ) -- The DMSwarm type.

Return type

None

SEE ALSO:

DMSwarmSetType

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

sortGetAccess()

Setup up a DMSwarm point sort context.

Not collective.

The point sort context is used for efficient traversal of points within a cell.

You must call sortRestoreAccess when you no longer need access to the sort context.

SEE ALSO:

sortRestoreAccess , DMSwarmSortGetAccess

Source code at petsc4py/PETSc/DMSwarm.pyx:698
Return type

None

sortGetIsValid()

Return whether the sort context is up-to-date.

Not collective.

Returns the flag associated with a DMSwarm point sorting context.

SEE ALSO:

DMSwarmSortGetIsValid

Source code at petsc4py/PETSc/DMSwarm.pyx:772
Return type

bool

sortGetNumberOfPointsPerCell(e)

Return the number of points in a cell.

Not collective.
Parameters

e ( int ) -- The index of the cell.

Return type

int

SEE ALSO:

DMSwarmSortGetNumberOfPointsPerCell

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

sortGetPointsPerCell(e)

Create an array of point indices for all points in a cell.

Not collective.
Parameters

e ( int ) -- The index of the cell.

Return type

list [ int ]

SEE ALSO:

DMSwarmSortGetPointsPerCell

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

sortGetSizes()

Return the sizes associated with a DMSwarm point sorting context.

Not collective.
Returns

	•		ncells ( int ) -- Number of cells within the sort context.
	•		npoints ( int ) -- Number of points used to create the sort context.

Return type

tuple [ int , int ]

SEE ALSO:

DMSwarmSortGetSizes

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

sortRestoreAccess()

Invalidate the DMSwarm point sorting context.

Not collective.

SEE ALSO:

sortGetAccess , DMSwarmSortRestoreAccess

Source code at petsc4py/PETSc/DMSwarm.pyx:716
Return type

None

vectorDefineField(fieldname)

Set the field from which to define a Vec object.

Collective.

The field will be used when DM.createLocalVec , or DM.createGlobalVec is called.
Parameters

fieldname ( str ) -- The textual name given to a registered field.

Return type

None

SEE ALSO:

DMSwarmVectorDefineField

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

viewFieldsXDMF(filename, fieldnames)

Write a selection of DMSwarm fields to an XDMF3 file.

Collective.
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:650

viewXDMF(filename)

Write this DMSwarm fields to an XDMF3 file.

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

petsc4py.PETSc.DS

class petsc4py.PETSc.DS

Bases: Object

Discrete System object.

Enumerations

Image grohtml-288464-41.png

petsc4py.PETSc.DS.Type

class petsc4py.PETSc.DS.Type

Bases: object

The Discrete System types.

Attributes Summary

Image grohtml-288464-42.png

Attributes Documentation
BASIC: str = BASIC

Object BASIC of type str

Methods Summary

Image grohtml-288464-43.png

Methods Documentation
create(comm=None)

Create an empty DS.

Collective.

The type can then be set with setType .
Parameters

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

Return type

Self

SEE ALSO:

setType , destroy , PetscDSCreate

Source code at petsc4py/PETSc/DS.pyx:53

destroy()

Destroy the discrete system.

Collective.

SEE ALSO:

create , PetscDSDestroy

Source code at petsc4py/PETSc/DS.pyx:40
Return type

Self

getComponents()

Return the number of components for each field on an evaluation point.

Not collective.

SEE ALSO:

PetscDSGetComponents

Source code at petsc4py/PETSc/DS.pyx:246
Return type

ArrayInt

getCoordinateDimension()

Return the coordinate dimension of the DS.

Not collective.

The coordinate dimension of the DS is the dimension of the space into which the discretiaztions are embedded.

SEE ALSO:

PetscDSGetCoordinateDimension

Source code at petsc4py/PETSc/DS.pyx:153
Return type

int

getDimensions()

Return the size of the space for each field on an evaluation point.

Not collective.

SEE ALSO:

PetscDSGetDimensions

Source code at petsc4py/PETSc/DS.pyx:231
Return type

ArrayInt

getFieldIndex(disc)

Return the index of the given field.

Not collective.
Parameters

disc ( Object ) -- The discretization object.

Return type

int

SEE ALSO:

PetscDSGetFieldIndex

Source code at petsc4py/PETSc/DS.pyx:184

getNumFields()

Return the number of fields in the DS.

Not collective.

SEE ALSO:

PetscDSGetNumFields

Source code at petsc4py/PETSc/DS.pyx:170
Return type

int

getSpatialDimension()

Return the spatial dimension of the DS.

Not collective.

The spatial dimension of the DS is the topological dimension of the discretizations.

SEE ALSO:

PetscDSGetSpatialDimension

Source code at petsc4py/PETSc/DS.pyx:136
Return type

int

getTotalComponents()

Return the total number of components in this system.

Not collective.

SEE ALSO:

PetscDSGetTotalComponents

Source code at petsc4py/PETSc/DS.pyx:217
Return type

int

getTotalDimensions()

Return the total size of the approximation space for this system.

Not collective.

SEE ALSO:

PetscDSGetTotalDimension

Source code at petsc4py/PETSc/DS.pyx:203
Return type

int

getType()

Return the type of the discrete system.

Not collective.

SEE ALSO:

setType , PetscDSGetType

Source code at petsc4py/PETSc/DS.pyx:95
Return type

str

setDiscretisation(f, disc)

Set the discretization object for the given field.

Not collective.
Parameters

	•		f ( int ) -- The field number.
	•		disc ( Object ) -- The discretization object.

Return type

None

SEE ALSO:

PetscDSSetDiscretization

Source code at petsc4py/PETSc/DS.pyx:261

setFromOptions()

Set parameters in a DS from the options database.

Collective.

SEE ALSO:

Working with PETSc options , PetscDSSetFromOptions

Source code at petsc4py/PETSc/DS.pyx:109
Return type

None

setType(ds_type)

Build a particular type of a discrete system.

Collective.
Parameters

ds_type ( Type | str ) -- The type of the discrete system.

Return type

None

SEE ALSO:

getType , PetscDSSetType

Source code at petsc4py/PETSc/DS.pyx:76

setUp()

Construct data structures for the discrete system.

Collective.

SEE ALSO:

PetscDSSetUp

Source code at petsc4py/PETSc/DS.pyx:121
Return type

Self

view(viewer=None)

View a discrete system.

Collective.
Parameters

viewer ( Viewer | None ) -- A Viewer to display the system.

Return type

None

SEE ALSO:

PetscDSView

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

petsc4py.PETSc.Device

class petsc4py.PETSc.Device

Bases: object

The device object.

Represents a handle to an accelerator (which may be the host).

SEE ALSO:

DeviceContext , PetscDevice

Enumerations

Image grohtml-288464-44.png

petsc4py.PETSc.Device.Type

class petsc4py.PETSc.Device.Type

Bases: object

The type of device.

SEE ALSO:

Device , Device.create , Device.getDeviceType , Device.type , PetscDeviceType

Attributes Summary

Image grohtml-288464-45.png

Attributes Documentation
CUDA: int = CUDA

Constant CUDA of type int

DEFAULT: int = DEFAULT

Constant DEFAULT of type int

HIP: int = HIP

Constant HIP of type int

HOST: int = HOST

Constant HOST of type int

SYCL: int = SYCL

Constant SYCL of type int

Methods Summary

Image grohtml-288464-46.png

Attributes Summary

Image grohtml-288464-47.png

Methods Documentation
configure()

Configure and setup a device object.

Not collective.

SEE ALSO:

create , PetscDeviceConfigure

Source code at petsc4py/PETSc/Device.pyx:132
Return type

None

classmethod create(dtype=None, device_id=DECIDE)

Create a device object.

Not collective.
Parameters

	•		dtype ( Type \| None ) -- The type of device to create (or None for the default).
	•		device_id ( int ) -- The numeric id of the device to create.

Return type

Device

SEE ALSO:

destroy , PetscDeviceCreate

Source code at petsc4py/PETSc/Device.pyx:94

destroy()

Destroy a device object.

Not collective.

SEE ALSO:

create , PetscDeviceDestroy

Source code at petsc4py/PETSc/Device.pyx:120
Return type

None

getDeviceId()

Return the device id.

Not collective.

SEE ALSO:

create , PetscDeviceGetDeviceId

Source code at petsc4py/PETSc/Device.pyx:180
Return type

int

getDeviceType()

Return the type of the device.

Not collective.

SEE ALSO:

type , PetscDeviceGetType

Source code at petsc4py/PETSc/Device.pyx:165
Return type

str

static setDefaultType(device_type)

Set the device type to be used as the default in subsequent calls to create .

Not collective.

SEE ALSO:

create , PetscDeviceSetDefaultDeviceType

Source code at petsc4py/PETSc/Device.pyx:195
Parameters

device_type ( Type | str )

Return type

None

view(viewer=None)

View a device object.

Collective.
Parameters

viewer ( Viewer | None ) -- A Viewer instance or - None for the default viewer.

Return type

None

SEE ALSO:

PetscDeviceView

Source code at petsc4py/PETSc/Device.pyx:144

Attributes Documentation
device_id

The device id.

Source code at petsc4py/PETSc/Device.pyx:215

type

The device type.

Source code at petsc4py/PETSc/Device.pyx:210

petsc4py.PETSc.DeviceContext

class petsc4py.PETSc.DeviceContext

Bases: Object

DeviceContext object.

Represents an abstract handle to a device context.

SEE ALSO:

Device , PetscDeviceContext

Enumerations

Image grohtml-288464-48.png

petsc4py.PETSc.DeviceContext.DeviceJoinMode

class petsc4py.PETSc.DeviceContext.DeviceJoinMode

Bases: object

The type of join to perform.

SEE ALSO:

DeviceContext , DeviceContext.join , DeviceContext.fork , PetscDeviceContextJoinMode

Attributes Summary

Image grohtml-288464-49.png

Attributes Documentation
DESTROY: int = DESTROY

Constant DESTROY of type int

NO_SYNC: int = NO_SYNC

Constant NO_SYNC of type int

SYNC: int = SYNC

Constant SYNC of type int

petsc4py.PETSc.DeviceContext.StreamType

class petsc4py.PETSc.DeviceContext.StreamType

Bases: object

The type of stream.

SEE ALSO:

DeviceContext , DeviceContext.getStreamType , DeviceContext.setStreamType , PetscStreamType

Attributes Summary

Image grohtml-288464-50.png

Attributes Documentation
DEFAULT: int = DEFAULT

Constant DEFAULT of type int

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

Methods Summary

Image grohtml-288464-51.png

Attributes Summary

Image grohtml-288464-52.png

Methods Documentation
create()

Create an empty DeviceContext.

Not collective.

SEE ALSO:

destroy , Device , PetscDeviceContextCreate

Source code at petsc4py/PETSc/Device.pyx:240
Return type

Self

destroy()

Destroy a device context.

Not collective.

SEE ALSO:

create , PetscDeviceContextDestroy

Source code at petsc4py/PETSc/Device.pyx:255
Return type

Self

duplicate()

Duplicate a the device context.

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.

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.

Return type

list [ DeviceContext ]

Examples

The device contexts created must be destroyed using join .

>>> 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 code at petsc4py/PETSc/Device.pyx:399

static getCurrent()

Return the current device context.

Not collective.

SEE ALSO:

current , setCurrent , - PetscDeviceContextGetCurrentContext

Source code at petsc4py/PETSc/Device.pyx:519
Return type

DeviceContext

getDevice()

Get the Device which this instance is attached to.

Not collective.

SEE ALSO:

setDevice , device , Device , PetscDeviceContextGetDevice

Source code at petsc4py/PETSc/Device.pyx:302
Return type

Device

getStreamType()

Return the StreamType .

Not collective.

SEE ALSO:

stream_type , setStreamType , - PetscDeviceContextGetStreamType

Source code at petsc4py/PETSc/Device.pyx:268
Return type

str

idle()

Return whether the underlying stream for the device context is idle.

Not collective.

SEE ALSO:

synchronize , PetscDeviceContextQueryIdle

Source code at petsc4py/PETSc/Device.pyx:363
Return type

bool

join(join_mode, py_sub_ctxs)

Join a set of device contexts on this one.

Not collective.
Parameters

	•		join_mode ( DeviceJoinMode \| str ) -- The type of join to perform.
	•		py_sub_ctxs ( list[DeviceContext] ) -- The list of device contexts to join.

Return type

None

SEE ALSO:

fork , waitFor , PetscDeviceContextJoin

Source code at petsc4py/PETSc/Device.pyx:448

static setCurrent(dctx)

Set the current device context.

Not collective.
Parameters

dctx ( DeviceContext | None ) -- The DeviceContext to set as current (or None to use the default context).

Return type

None

SEE ALSO:

current , getCurrent , - PetscDeviceContextSetCurrentContext

Source code at petsc4py/PETSc/Device.pyx:535

setDevice(device)

Set the Device which this DeviceContext is attached to.

Collective.
Parameters

device ( Device ) -- The Device to which this instance is attached to.

Return type

None

SEE ALSO:

getDevice , device , Device , PetscDeviceContextSetDevice

Source code at petsc4py/PETSc/Device.pyx:317

setFromOptions(comm=None)

Configure the DeviceContext from the options database.

Collective.
Parameters

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

Return type

None

SEE ALSO:

Sys.getDefaultComm , PetscDeviceContextSetFromOptions

Source code at petsc4py/PETSc/Device.pyx:500

setStreamType(stream_type)

Set the StreamType .

Not collective.
Parameters

stream_type ( StreamType | str ) -- The type of stream to set

Return type

None

SEE ALSO:

stream_type , getStreamType , - PetscDeviceContextSetStreamType

Source code at petsc4py/PETSc/Device.pyx:283

setUp()

Set up the internal data structures for using the device context.

Not collective.

SEE ALSO:

create , PetscDeviceContextSetUp

Source code at petsc4py/PETSc/Device.pyx:336
Return type

None

synchronize()

Synchronize a device context.

Not collective.

Notes

The underlying stream is considered idle after this routine returns, i.e. idle will return True .

SEE ALSO:

idle , PetscDeviceContextSynchronize

Source code at petsc4py/PETSc/Device.pyx:483
Return type

None

waitFor(other)

Make this instance wait for other .

Not collective.
Parameters

other ( DeviceContext | None ) -- The other DeviceContext to wait for

Return type

None

SEE ALSO:

fork , join , PetscDeviceContextWaitForContext

Source code at petsc4py/PETSc/Device.pyx:378

Attributes Documentation
current

The current global device context.

Source code at petsc4py/PETSc/Device.pyx:574

device

The device associated to the device context.

Source code at petsc4py/PETSc/Device.pyx:566

stream_type

The stream type.

Source code at petsc4py/PETSc/Device.pyx:558

petsc4py.PETSc.DualSpace

class petsc4py.PETSc.DualSpace

Bases: Object

Dual space to a linear space.

Enumerations

Image grohtml-288464-53.png

petsc4py.PETSc.DualSpace.Type

class petsc4py.PETSc.DualSpace.Type

Bases: object

The dual space types.

Attributes Summary

Image grohtml-288464-54.png

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

Methods Summary

Image grohtml-288464-55.png

Methods Documentation
create(comm=None)

Create an empty DualSpace object.

Collective.

The type can then be set with setType .
Parameters

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

Return type

Self

SEE ALSO:

PetscDualSpaceCreate

Source code at petsc4py/PETSc/Space.pyx:594

destroy()

Destroy the DualSpace object.

Collective.

SEE ALSO:

PetscDualSpaceDestroy

Source code at petsc4py/PETSc/Space.pyx:636
Return type

Self

duplicate()

Create a duplicate DualSpace object that is not set up.

Collective.

SEE ALSO:

PetscDualSpaceDuplicate

Source code at petsc4py/PETSc/Space.pyx:649
Return type

DualSpace

getDM()

Return the DM representing the reference cell of a DualSpace .

Not collective.

SEE ALSO:

setDM , PetscDualSpaceGetDM

Source code at petsc4py/PETSc/Space.pyx:662
Return type

getDimension()

Return the dimension of the dual space.

Not collective.

The dimension of the dual space, i.e. the number of basis functionals.

SEE ALSO:

PetscDualSpaceGetDimension

Source code at petsc4py/PETSc/Space.pyx:696
Return type

int

getFunctional(i)

Return the i-th basis functional in the dual space.

Not collective.
Parameters

i ( int ) -- The basis number.

Return type

Quad

SEE ALSO:

PetscDualSpaceGetFunctional

Source code at petsc4py/PETSc/Space.pyx:826

getInteriorDimension()

Return the interior dimension of the dual space.

Not collective.

The interior dimension of the dual space, i.e. the number of basis functionals assigned to the interior of the reference domain.

SEE ALSO:

PetscDualSpaceGetInteriorDimension

Source code at petsc4py/PETSc/Space.pyx:847
Return type

int

getLagrangeContinuity()

Return whether the element is continuous.

Not collective.

SEE ALSO:

setLagrangeContinuity , - PetscDualSpaceLagrangeGetContinuity

Source code at petsc4py/PETSc/Space.pyx:864
Return type

bool

getLagrangeTensor()

Return the tensor nature of the dual space.

Not collective.

SEE ALSO:

setLagrangeTensor , PetscDualSpaceLagrangeGetTensor

Source code at petsc4py/PETSc/Space.pyx:896
Return type

bool

getLagrangeTrimmed()

Return the trimmed nature of the dual space.

Not collective.

SEE ALSO:

setLagrangeTrimmed , PetscDualSpaceLagrangeGetTrimmed

Source code at petsc4py/PETSc/Space.pyx:928
Return type

bool

getNumComponents()

Return the number of components for this space.

Not collective.

SEE ALSO:

setNumComponents , PetscDualSpaceGetNumComponents

Source code at petsc4py/PETSc/Space.pyx:712
Return type

int

getNumDof()

Return the number of degrees of freedom for each spatial dimension.

Not collective.

SEE ALSO:

PetscDualSpaceGetNumDof

Source code at petsc4py/PETSc/Space.pyx:810
Return type

ArrayInt

getOrder()

Return the order of the dual space.

Not collective.

SEE ALSO:

setOrder , PetscDualSpaceGetOrder

Source code at petsc4py/PETSc/Space.pyx:778
Return type

int

getType()

Return the type of the dual space object.

Not collective.

SEE ALSO:

setType , PetscDualSpaceGetType

Source code at petsc4py/PETSc/Space.pyx:744
Return type

str

setDM(dm)

Set the DM representing the reference cell.

Not collective.
Parameters

dm ( DM ) -- The reference cell.

Return type

None

SEE ALSO:

getDM , PetscDualSpaceSetDM

Source code at petsc4py/PETSc/Space.pyx:679

setLagrangeContinuity(continuous)

Indicate whether the element is continuous.

Not collective.
Parameters

continuous ( bool ) -- The flag for element continuity.

Return type

None

SEE ALSO:

getLagrangeContinuity , - PetscDualSpaceLagrangeSetContinuity

Source code at petsc4py/PETSc/Space.pyx:878

setLagrangeTensor(tensor)

Set the tensor nature of the dual space.

Not collective.
Parameters

tensor ( bool ) -- Whether the dual space has tensor layout (vs. simplicial).

Return type

None

SEE ALSO:

getLagrangeTensor , PetscDualSpaceLagrangeSetTensor

Source code at petsc4py/PETSc/Space.pyx:910

setLagrangeTrimmed(trimmed)

Set the trimmed nature of the dual space.

Not collective.
Parameters

trimmed ( bool ) -- Whether the dual space represents to dual basis of a trimmed polynomial space (e.g. Raviart-Thomas and higher order / other form degree variants).

Return type

None

SEE ALSO:

getLagrangeTrimmed , PetscDualSpaceLagrangeSetTrimmed

Source code at petsc4py/PETSc/Space.pyx:942

setNumComponents(nc)

Set the number of components for this space.

Logically collective.
Parameters

nc ( int ) -- The number of components

Return type

None

SEE ALSO:

getNumComponents , PetscDualSpaceSetNumComponents

Source code at petsc4py/PETSc/Space.pyx:726

setOrder(order)

Set the order of the dual space.

Not collective.
Parameters

order ( int ) -- The order.

Return type

None

SEE ALSO:

getOrder , PetscDualSpaceSetOrder

Source code at petsc4py/PETSc/Space.pyx:792

setSimpleDimension(dim)

Set the number of functionals in the dual space basis.

Logically collective.
Parameters

dim ( int ) -- The basis dimension.

Return type

None

SEE ALSO:

PetscDualSpaceSimpleSetDimension

Source code at petsc4py/PETSc/Space.pyx:962

setSimpleFunctional(func, functional)

Set the given basis element for this dual space.

Not collective.
Parameters

	•		func ( int ) -- The basis index.
	•		functional ( Quad ) -- The basis functional.

Return type

None

SEE ALSO:

PetscDualSpaceSimpleSetFunctional

Source code at petsc4py/PETSc/Space.pyx:980

setType(dualspace_type)

Build a particular type of dual space.

Collective.
Parameters

dualspace_type ( Type | str ) -- The kind of space.

Return type

Self

SEE ALSO:

getType , PetscDualSpaceSetType

Source code at petsc4py/PETSc/Space.pyx:758

setUp()

Construct a basis for a DualSpace .

Collective.

SEE ALSO:

PetscDualSpaceSetUp

Source code at petsc4py/PETSc/Space.pyx:582
Return type

None

view(viewer=None)

View a DualSpace .

Collective.
Parameters

viewer ( Viewer | None ) -- A Viewer to display the DualSpace .

Return type

None

SEE ALSO:

PetscDualSpaceView

Source code at petsc4py/PETSc/Space.pyx:617

petsc4py.PETSc.FE

class petsc4py.PETSc.FE

Bases: Object

A PETSc object that manages a finite element space.

Enumerations

Image grohtml-288464-56.png

petsc4py.PETSc.FE.Type

class petsc4py.PETSc.FE.Type

Bases: object

The finite element types.

Attributes Summary

Image grohtml-288464-57.png

Attributes Documentation
BASIC: str = BASIC

Object BASIC of type str

COMPOSITE: str = COMPOSITE

Object COMPOSITE of type str

OPENCL: str = OPENCL

Object OPENCL of type str

Methods Summary

Image grohtml-288464-58.png

Methods Documentation
create(comm=None)

Create an empty FE object.

Collective.

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

createDefault(dim, nc, isSimplex, qorder=DETERMINE, prefix=None,
comm=None)

Create a FE for basic FEM computation.

Collective.
Parameters

	•		dim ( int ) -- The spatial dimension.
	•		nc ( int ) -- The number of components.
	•		isSimplex ( bool ) -- Flag for simplex reference cell, otherwise it's a tensor product.
	•		qorder ( int ) -- The quadrature order or DETERMINE to use Space polynomial degree.
	•		prefix ( str ) -- The options prefix, or None .
	•		comm ( Comm \| None ) -- MPI communicator, defaults to Sys.getDefaultComm .

Return type

Self

SEE ALSO:

PetscFECreateDefault

Source code at petsc4py/PETSc/FE.pyx:76

createLagrange(dim, nc, isSimplex, k, qorder=DETERMINE,
comm=None)

Create a FE for the basic Lagrange space of degree k.

Collective.
Parameters

	•		dim ( int ) -- The spatial dimension.
	•		nc ( int ) -- The number of components.
	•		isSimplex ( bool ) -- Flag for simplex reference cell, otherwise it's a tensor product.
	•		k ( int ) -- The degree of the space.
	•		qorder ( int ) -- The quadrature order or DETERMINE to use Space polynomial degree.
	•		comm ( Comm \| None ) -- MPI communicator, defaults to Sys.getDefaultComm .

Return type

Self

SEE ALSO:

PetscFECreateLagrange

Source code at petsc4py/PETSc/FE.pyx:122

destroy()

Destroy the FE object.

Collective.

SEE ALSO:

PetscFEDestroy

Source code at petsc4py/PETSc/FE.pyx:40
Return type

Self

getBasisSpace()

Return the Space used for the approximation of the FE solution.

Not collective.

SEE ALSO:

setBasisSpace , PetscFEGetBasisSpace

Source code at petsc4py/PETSc/FE.pyx:387
Return type

Space

getDimension()

Return the dimension of the finite element space on a cell.

Not collective.

SEE ALSO:

PetscFEGetDimension

Source code at petsc4py/PETSc/FE.pyx:181
Return type

int

getDualSpace()

Return the DualSpace used to define the inner product for the FE .

Not collective.

SEE ALSO:

setDualSpace , DualSpace , PetscFEGetDualSpace

Source code at petsc4py/PETSc/FE.pyx:443
Return type

DualSpace

getFaceQuadrature()

Return the Quad used to calculate inner products on faces.

Not collective.

SEE ALSO:

setFaceQuadrature , PetscFEGetFaceQuadrature

Source code at petsc4py/PETSc/FE.pyx:316
Return type

Quad

getNumComponents()

Return the number of components in the element.

Not collective.

SEE ALSO:

setNumComponents , PetscFEGetNumComponents

Source code at petsc4py/PETSc/FE.pyx:209
Return type

int

getNumDof()

Return the number of DOFs.

Not collective.

Return the number of DOFs (dual basis vectors) associated with mesh points on the reference cell of a given dimension.

SEE ALSO:

PetscFEGetNumDof

Source code at petsc4py/PETSc/FE.pyx:241
Return type

ndarray

getQuadrature()

Return the Quad used to calculate inner products.

Not collective.

SEE ALSO:

setQuadrature , PetscFEGetQuadrature

Source code at petsc4py/PETSc/FE.pyx:166
Return type

Quad

getSpatialDimension()

Return the spatial dimension of the element.

Not collective.

SEE ALSO:

PetscFEGetSpatialDimension

Source code at petsc4py/PETSc/FE.pyx:195
Return type

int

getTileSizes()

Return the tile sizes for evaluation.

Not collective.
Returns

	•		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

tuple ( int , int , int , int )

SEE ALSO:

setTileSizes , PetscFEGetTileSizes

Source code at petsc4py/PETSc/FE.pyx:260

setBasisSpace(sp)

Set the Space used for the approximation of the solution.

Not collective.
Parameters

sp ( Space ) -- The Space object.

Return type

None

SEE ALSO:

getBasisSpace , PetscFESetBasisSpace

Source code at petsc4py/PETSc/FE.pyx:402

setDualSpace(dspace)

Set the DualSpace used to define the inner product.

Not collective.
Parameters

dspace ( DualSpace ) -- The DualSpace object.

Return type

None

SEE ALSO:

getDualSpace , DualSpace , PetscFESetDualSpace

Source code at petsc4py/PETSc/FE.pyx:458

setFaceQuadrature(quad)

Set the Quad used to calculate inner products on faces.

Not collective.
Parameters

quad ( Quad ) -- The Quad object.

Return type

Quad

SEE ALSO:

getFaceQuadrature , PetscFESetFaceQuadrature

Source code at petsc4py/PETSc/FE.pyx:349

setFromOptions()

Set parameters in a FE from the options database.

Collective.

SEE ALSO:

Working with PETSc options , PetscFESetFromOptions

Source code at petsc4py/PETSc/FE.pyx:419
Return type

None

setNumComponents(comp)

Set the number of field components in the element.

Not collective.
Parameters

comp ( int ) -- The number of field components.

Return type

None

SEE ALSO:

getNumComponents , PetscFESetNumComponents

Source code at petsc4py/PETSc/FE.pyx:223

setQuadrature(quad)

Set the Quad used to calculate inner products.

Not collective.
Parameters

quad ( Quad ) -- The Quad object.

Return type

Self

SEE ALSO:

getQuadrature , PetscFESetQuadrature

Source code at petsc4py/PETSc/FE.pyx:331

setTileSizes(blockSize, numBlocks, batchSize, numBatches)

Set the tile sizes for evaluation.

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

setType(fe_type)

Build a particular FE .

Collective.
Parameters

fe_type ( Type | str ) -- The kind of FEM space.

Return type

Self

SEE ALSO:

PetscFESetType

Source code at petsc4py/PETSc/FE.pyx:367

setUp()

Construct data structures for the FE after the Type has been set.

Collective.

SEE ALSO:

PetscFESetUp

Source code at petsc4py/PETSc/FE.pyx:431
Return type

None

view(viewer=None)

View a FE object.

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

petsc4py.PETSc.IS

class petsc4py.PETSc.IS

Bases: Object

A collection of indices.

IS objects are used to index into vectors and matrices and to set up vector scatters.

SEE ALSO:

Enumerations

Image grohtml-288464-59.png

petsc4py.PETSc.IS.Type

class petsc4py.PETSc.IS.Type

Bases: object

The index set types.

Attributes Summary

Image grohtml-288464-60.png

Attributes Documentation
BLOCK: str = BLOCK

Object BLOCK of type str

GENERAL: str = GENERAL

Object GENERAL of type str

STRIDE: str = STRIDE

Object STRIDE of type str

Methods Summary

Image grohtml-288464-61.png

Attributes Summary

Image grohtml-288464-62.png

Methods Documentation
allGather()

Concatenate index sets stored across processors.

Collective.

The returned index set will be the same on every processor.

SEE ALSO:

ISAllGather

Source code at petsc4py/PETSc/IS.pyx:304
Return type

buildTwoSided(toindx=None)

Create an index set describing a global mapping.

Collective.

This function generates an index set that contains new numbers from remote or local on the index set.
Parameters

toindx ( IS | 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

SEE ALSO:

ISBuildTwoSided

Source code at petsc4py/PETSc/IS.pyx:333

complement(nmin, nmax)

Create a complement index set.

Collective.

The complement set of indices is all indices that are not in the provided set (and within the provided bounds).
Parameters

	•		nmin ( int ) -- Minimum index that can be found 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.

Return type

Notes

For a parallel index set, this will generate the local part of the complement on each process.

To generate the entire complement (on each process) of a parallel index set, first call IS.allGather and then call this method.

SEE ALSO:

IS.allGather , ISComplement

Source code at petsc4py/PETSc/IS.pyx:674

copy(result=None)

Copy the contents of the index set into another.

Collective.
Parameters

result ( IS | None ) -- The target index set. If - None then IS.duplicate is called first.

Returns

The copied index set. If result is not None then this is returned here.

Return type

SEE ALSO:

IS.duplicate , ISCopy

Source code at petsc4py/PETSc/IS.pyx:253

create(comm=None)

Create an IS.

Collective.
Parameters

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

Return type

Self

SEE ALSO:

ISCreate

Source code at petsc4py/PETSc/IS.pyx:88

createBlock(bsize, indices, comm=None)

Create a blocked index set.

Collective.
Parameters

	•		bsize ( int ) -- Block size.
	•		indices ( Sequence[int] ) -- Integer array of indices.
	•		comm ( Comm \| None ) -- MPI communicator, defaults to Sys.getDefaultComm .

Return type

Self

SEE ALSO:

ISCreateBlock

Source code at petsc4py/PETSc/IS.pyx:171

createGeneral(indices, comm=None)

Create an IS with indices.

Collective.
Parameters

	•		indices ( Sequence[int] ) -- Integer array.
	•		comm ( Comm \| None ) -- MPI communicator, defaults to Sys.getDefaultComm .

Return type

Self

SEE ALSO:

ISCreateGeneral

Source code at petsc4py/PETSc/IS.pyx:142

createStride(size, first=0, step=0, comm=None)

Create an index set consisting of evenly spaced values.

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 \| None ) -- MPI communicator, defaults to Sys.getDefaultComm .

Return type

Self

SEE ALSO:

ISCreateStride

Source code at petsc4py/PETSc/IS.pyx:204

destroy()

Destroy the index set.

Collective.

SEE ALSO:

ISDestroy

Source code at petsc4py/PETSc/IS.pyx:75
Return type

Self

difference(iset)

Return the difference between two index sets.

Collective.
Parameters

iset ( IS ) -- Index set to compute the difference with.

Returns

Index set representing the difference between self and iset .

Return type

SEE ALSO:

ISDifference

Source code at petsc4py/PETSc/IS.pyx:650

duplicate()

Create a copy of the index set.

Collective.

SEE ALSO:

IS.copy , ISDuplicate

Source code at petsc4py/PETSc/IS.pyx:239
Return type

embed(iset, drop)

Embed self into iset .

Not collective.

The embedding is performed by finding the locations in iset that have the same indices as self .
Parameters

	•		iset ( IS ) -- The index set to embed into.
	•		drop ( bool ) -- Flag indicating whether to drop indices from self that are not in iset .

Returns

The embedded index set.

Return type

SEE ALSO:

ISEmbed

Source code at petsc4py/PETSc/IS.pyx:710

equal(iset)

Return whether the index sets have the same set of indices or not.

Collective.
Parameters

iset ( IS ) -- The index set to compare indices with.

Return type

bool

SEE ALSO:

ISEqual

Source code at petsc4py/PETSc/IS.pyx:550

expand(iset)

Return the union of two (possibly unsorted) index sets.

Collective.

To compute the union, expand concatenates the two index sets and removes any duplicates.
Parameters

iset ( IS ) -- Index set to compute the union with.

Returns

The new, combined, index set.

Return type

SEE ALSO:

ISExpand

Source code at petsc4py/PETSc/IS.pyx:588

getBlockIndices()

Return the indices of an index set with type IS.Type.BLOCK .

Not collective.

SEE ALSO:

ISBlockGetIndices

Source code at petsc4py/PETSc/IS.pyx:833
Return type

ArrayInt

getBlockSize()

Return the number of elements in a block.

Not collective.

SEE ALSO:

ISGetBlockSize

Source code at petsc4py/PETSc/IS.pyx:437
Return type

int

getIndices()

Return the indices of the index set.

Not collective.

SEE ALSO:

ISGetIndices

Source code at petsc4py/PETSc/IS.pyx:789
Return type

ArrayInt

getInfo()

Return stride information for an index set with type IS.Type.STRIDE .

Not collective.
Returns

	•		first ( int ) -- First element of the index set.
	•		step ( int ) -- Difference between adjacent indices.

Return type

tuple [ int , int ]

SEE ALSO:

IS.getStride , ISStrideGetInfo

Source code at petsc4py/PETSc/IS.pyx:903

getLocalSize()

Return the process-local length of the index set.

Not collective.

SEE ALSO:

ISGetLocalSize

Source code at petsc4py/PETSc/IS.pyx:401
Return type

int

getSize()

Return the global length of an index set.

Not collective.

SEE ALSO:

ISGetSize

Source code at petsc4py/PETSc/IS.pyx:387
Return type

int

getSizes()

Return the local and global sizes of the index set.

Not collective.
Returns

	•		local_size ( int ) -- The local size.
	•		global_size ( int ) -- The global size.

Return type

tuple [ int , int ]

SEE ALSO:

IS.getLocalSize , IS.getSize

Source code at petsc4py/PETSc/IS.pyx:415

getStride()

Return size and stride information.

Not collective.
Returns

	•		size ( int ) -- Length of the locally owned portion of the index set.
	•		first ( int ) -- First element of the index set.
	•		step ( int ) -- Difference between adjacent indices.

Return type

tuple [ int , int , int ]

SEE ALSO:

ISGetLocalSize , ISStrideGetInfo

Source code at petsc4py/PETSc/IS.pyx:879

getType()

Return the index set type associated with the IS.

Not collective.

SEE ALSO:

ISGetType

Source code at petsc4py/PETSc/IS.pyx:128
Return type

str

invertPermutation(nlocal=None)

Invert the index set.

Collective.

For this to be correct the index set must be a permutation.
Parameters

nlocal ( int | None ) -- The number of indices on this processor in the resulting index set, defaults to PETSC_DECIDE .

Return type

SEE ALSO:

ISInvertPermutation

Source code at petsc4py/PETSc/IS.pyx:363

isIdentity()

Return whether the index set has been declared as an identity.

Collective.

SEE ALSO:

ISIdentity

Source code at petsc4py/PETSc/IS.pyx:536
Return type

bool

isPermutation()

Return whether an index set has been declared to be a permutation.

Logically collective.

SEE ALSO:

ISPermutation

Source code at petsc4py/PETSc/IS.pyx:509
Return type

bool

isSorted()

Return whether the indices have been sorted.

Collective.

SEE ALSO:

ISSorted

Source code at petsc4py/PETSc/IS.pyx:482
Return type

bool

load(viewer)

Load a stored index set.

Collective.
Parameters

viewer ( Viewer ) -- Binary file viewer, either Viewer.Type.BINARY or Viewer.Type.HDF5 .

Return type

Self

SEE ALSO:

ISLoad

Source code at petsc4py/PETSc/IS.pyx:281

renumber(mult=None)

Renumber the non-negative entries of an index set, starting from 0.

Collective.
Parameters

mult ( IS | None ) -- The multiplicity of each entry in self , default implies a multiplicity of 1.

Returns

	•		int -- One past the largest entry of the new index set.
	•		IS -- The renumbered index set.

Return type

tuple [ int , IS ]

SEE ALSO:

ISRenumber

Source code at petsc4py/PETSc/IS.pyx:741

setBlockIndices(bsize, indices)

Set the indices for an index set with type IS.Type.BLOCK .

Collective.
Parameters

	•		bsize ( int ) -- Number of elements in each block.
	•		indices ( Sequence[int] ) -- List of integers.

Return type

None

SEE ALSO:

ISBlockSetIndices

Source code at petsc4py/PETSc/IS.pyx:810

setBlockSize(bs)

Set the block size of the index set.

Logically collective.
Parameters

bs ( int ) -- Block size.

Return type

None

SEE ALSO:

ISSetBlockSize

Source code at petsc4py/PETSc/IS.pyx:451

setIdentity()

Mark the index set as being an identity.

Logically collective.

SEE ALSO:

ISSetIdentity

Source code at petsc4py/PETSc/IS.pyx:523
Return type

Self

setIndices(indices)

Set the indices of an index set.

Logically collective.

The index set is assumed to be of type IS.Type.GENERAL .

SEE ALSO:

ISGeneralSetIndices

Source code at petsc4py/PETSc/IS.pyx:772
Parameters

indices ( Sequence[int] )

Return type

None

setPermutation()

Mark the index set as being a permutation.

Logically collective.

SEE ALSO:

ISSetPermutation

Source code at petsc4py/PETSc/IS.pyx:496
Return type

Self

setStride(size, first=0, step=1)

Set the stride information for an index set with type IS.Type.STRIDE .

Logically collective.
Parameters

	•		size ( int ) -- Length of the locally owned portion of the index set.
	•		first ( int ) -- First element of the index set.
	•		step ( int ) -- Difference between adjacent indices.

Return type

None

SEE ALSO:

ISStrideSetStride

Source code at petsc4py/PETSc/IS.pyx:855

setType(is_type)

Set the type of the index set.

Collective.
Parameters

is_type ( Type | str ) -- The index set type.

Return type

None

SEE ALSO:

ISSetType

Source code at petsc4py/PETSc/IS.pyx:109

sort()

Sort the indices of an index set.

Collective.

SEE ALSO:

ISSort

Source code at petsc4py/PETSc/IS.pyx:469
Return type

Self

sum(iset)

Return the union of two (sorted) index sets.

Collective.
Parameters

iset ( IS ) -- The index set to compute the union with.

Return type

SEE ALSO:

ISSum

Source code at petsc4py/PETSc/IS.pyx:569

toGeneral()

Convert the index set type to IS.Type.GENERAL .

Collective.

SEE ALSO:

ISToGeneral , ISType

Source code at petsc4py/PETSc/IS.pyx:320
Return type

Self

union(iset)

Return the union of two (possibly unsorted) index sets.

Collective.

This function will call either ISSum or ISExpand depending on whether or not the input sets are already sorted.

Sequential only (as ISSum is sequential only).
Parameters

iset ( IS ) -- Index set to compute the union with.

Returns

The new, combined, index set.

Return type

SEE ALSO:

IS.expand , IS.sum

Source code at petsc4py/PETSc/IS.pyx:615

view(viewer=None)

Display the index set.

Collective.
Parameters

viewer ( Viewer | None ) -- Viewer used to display the IS.

Return type

None

SEE ALSO:

ISView

Source code at petsc4py/PETSc/IS.pyx:56

Attributes Documentation

array

View of the index set as an array of integers.

Not collective.

Source code at petsc4py/PETSc/IS.pyx:1032

block_size

The number of elements in a block.

Not collective.

SEE ALSO:

IS.getBlockSize

Source code at petsc4py/PETSc/IS.pyx:1006

identity

True if index set is an identity, False otherwise.

Collective.

SEE ALSO:

IS.isIdentity

Source code at petsc4py/PETSc/IS.pyx:939

indices

The indices of the index set.

Not collective.

SEE ALSO:

IS.getIndices

Source code at petsc4py/PETSc/IS.pyx:1019

local_size

The local size of the index set.

Not collective.

SEE ALSO:

IS.getLocalSize

Source code at petsc4py/PETSc/IS.pyx:993

permutation

True if index set is a permutation, False otherwise.

Logically collective.

SEE ALSO:

IS.isPermutation

Source code at petsc4py/PETSc/IS.pyx:926

size

The global size of the index set.

Not collective.

SEE ALSO:

IS.getSize

Source code at petsc4py/PETSc/IS.pyx:980

sizes

The local and global sizes of the index set.

Not collective.

SEE ALSO:

IS.getSizes

Source code at petsc4py/PETSc/IS.pyx:967

sorted

True if index set is sorted, False otherwise.

Collective.

SEE ALSO:

IS.isSorted

Source code at petsc4py/PETSc/IS.pyx:952

petsc4py.PETSc.InsertMode

class petsc4py.PETSc.InsertMode

Bases: object

Insertion mode.

Most commonly used insertion modes are:

	INSERT		Insert provided value/s discarding previous value/s.
	ADD		Add provided value/s to current value/s.
	MAX		Insert the maximum of provided value/s and current value/s.

SEE ALSO:

InsertMode

Attributes Summary

Image grohtml-288464-63.png

Attributes Documentation
ADD: int = ADD

Constant ADD of type int

ADD_ALL: int = ADD_ALL

Constant ADD_ALL of type int

ADD_ALL_VALUES: int = ADD_ALL_VALUES

Constant ADD_ALL_VALUES of type int

ADD_BC: int = ADD_BC

Constant ADD_BC of type int

ADD_BC_VALUES: int = ADD_BC_VALUES

Constant ADD_BC_VALUES of type int

ADD_VALUES: int = ADD_VALUES

Constant ADD_VALUES of type int

INSERT: int = INSERT

Constant INSERT of type int

INSERT_ALL: int = INSERT_ALL

Constant INSERT_ALL of type int

INSERT_ALL_VALUES: int = INSERT_ALL_VALUES

Constant INSERT_ALL_VALUES of type int

INSERT_BC: int = INSERT_BC

Constant INSERT_BC of type int

INSERT_BC_VALUES: int = INSERT_BC_VALUES

Constant INSERT_BC_VALUES of type int

INSERT_VALUES: int = INSERT_VALUES

Constant INSERT_VALUES of type int

MAX: int = MAX

Constant MAX of type int

MAX_VALUES: int = MAX_VALUES

Constant MAX_VALUES of type int

NOT_SET_VALUES: int = NOT_SET_VALUES

Constant NOT_SET_VALUES of type int

petsc4py.PETSc.KSP

class petsc4py.PETSc.KSP

Bases: Object

Abstract PETSc object that manages all Krylov methods.

This is the object that manages the linear solves in PETSc (even those such as direct solvers that do no use Krylov accelerators).

Notes

When a direct solver is used, but no Krylov solver is used, the KSP object is still used but with a Type.PREONLY , meaning that only application of the preconditioner is used as the linear solver.

SEE ALSO:

create , setType , SNES , TS , PC , Type.CG , Type.GMRES , KSP

Enumerations

Image grohtml-288464-64.png

petsc4py.PETSc.KSP.ConvergedReason

class petsc4py.PETSc.KSP.ConvergedReason

Bases: object

KSP Converged Reason.
CONVERGED_ITERATING

Still iterating

ITERATING

Still iterating

CONVERGED_RTOL_NORMAL

Undocumented.

CONVERGED_ATOL_NORMAL

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.

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

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

Attributes Summary

Image grohtml-288464-65.png

Attributes Documentation
CONVERGED_ATOL: int = CONVERGED_ATOL

Constant CONVERGED_ATOL of type int

CONVERGED_ATOL_NORMAL: int = CONVERGED_ATOL_NORMAL

Constant CONVERGED_ATOL_NORMAL of type int

CONVERGED_HAPPY_BREAKDOWN: int =
CONVERGED_HAPPY_BREAKDOWN

Constant CONVERGED_HAPPY_BREAKDOWN 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_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: int = CONVERGED_RTOL_NORMAL

Constant CONVERGED_RTOL_NORMAL 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

petsc4py.PETSc.KSP.HPDDMType

class petsc4py.PETSc.KSP.HPDDMType

Bases: object

The HPDDM Krylov solver type.

Attributes Summary

Image grohtml-288464-66.png

Attributes Documentation
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

petsc4py.PETSc.KSP.NormType

class petsc4py.PETSc.KSP.NormType

Bases: object

KSP norm type.

The available norm types are:

NONE

Skips computing the norm, this should generally only be used if you are using the Krylov method as a smoother with a fixed small number of iterations. Implicitly sets KSPConvergedSkip as KSP convergence test. Note that certain algorithms such as Type.GMRES ALWAYS require the norm calculation, for these methods the norms are still computed, they are just not used in the convergence test.

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.

NATURAL

Supported by Type.CG , Type.CR , Type.CGNE , Type.CGS .

Attributes Summary

Image grohtml-288464-67.png

Attributes Documentation
DEFAULT: int = DEFAULT

Constant DEFAULT of type int

NATURAL: int = NATURAL

Constant NATURAL of type int

NO: int = NO

Constant NO of type int

NONE: int = NONE

Constant NONE of type int

NORM_DEFAULT: int = NORM_DEFAULT

Constant NORM_DEFAULT of type int

NORM_NATURAL: int = NORM_NATURAL

Constant NORM_NATURAL of type int

NORM_NONE: int = NORM_NONE

Constant NORM_NONE of type int

NORM_PRECONDITIONED: int = NORM_PRECONDITIONED

Constant NORM_PRECONDITIONED of type int

NORM_UNPRECONDITIONED: int = NORM_UNPRECONDITIONED

Constant NORM_UNPRECONDITIONED of type int

PRECONDITIONED: int = PRECONDITIONED

Constant PRECONDITIONED of type int

UNPRECONDITIONED: int = UNPRECONDITIONED

Constant UNPRECONDITIONED of type int

petsc4py.PETSc.KSP.Type

class petsc4py.PETSc.KSP.Type

Bases: object

KSP Type.

The available types are:
RICHARDSON

The preconditioned Richardson iterative method - KSPRICHARDSON .

CHEBYSHEV

The preconditioned Chebyshev iterative method. - KSPCHEBYSHEV .

The Preconditioned Conjugate Gradient (PCG) iterative method. KSPCG

GROPPCG

A pipelined conjugate gradient method (Gropp). - KSPGROPPCG

PIPECG

A pipelined conjugate gradient method. KSPPIPECG

PIPECGRR

Pipelined Conjugate Gradients with Residual Replacement. KSPPIPECGRR

PIPELCG

Deep pipelined (length l) Conjugate Gradient method. KSPPIPELCG

PIPEPRCG

Pipelined predict-and-recompute conjugate gradient method. KSPPIPEPRCG

PIPECG2

Pipelined conjugate gradient method with a single non-blocking reduction per two iterations. - KSPPIPECG2

	CGNE		Applies the preconditioned conjugate gradient method to the normal equations without explicitly forming AᵀA. KSPCGNE
	NASH		Conjugate gradient method subject to a constraint on the solution norm. KSPNASH
	STCG		Conjugate gradient method subject to a constraint on the solution norm. KSPSTCG
	GLTR		Conjugate gradient method subject to a constraint on the solution norm. KSPGLTR
	FCG		Flexible Conjugate Gradient method (FCG). Unlike most KSP methods this allows the preconditioner to be nonlinear. KSPFCG

PIPEFCG

Pipelined, Flexible Conjugate Gradient method. - KSPPIPEFCG

GMRES

Generalized Minimal Residual method with restart. KSPGMRES

PIPEFGMRES

Pipelined (1-stage) Flexible Generalized Minimal Residual method. KSPPIPEFGMRES

	FGMRES		Implements the Flexible Generalized Minimal Residual method. KSPFGMRES
	LGMRES		Augments the standard Generalized Minimal Residual method approximation space with approximations to the error from previous restart cycles. KSPLGMRES
	DGMRES		Deflated Generalized Minimal Residual method. In this implementation, the adaptive strategy allows to switch to the deflated GMRES when the stagnation occurs. KSPDGMRES
	PGMRES		Pipelined Generalized Minimal Residual method. - KSPPGMRES
	TCQMR		A variant of Quasi Minimal Residual (QMR). - KSPTCQMR
	BCGS		Stabilized version of Biconjugate Gradient (BiCGStab) method. KSPBCGS
	IBCGS		Improved Stabilized version of BiConjugate Gradient (IBiCGStab) method in an alternative form to have only a single global reduction operation instead of the usual 3 (or 4). KSPIBCGS
	QMRCGS		Quasi- Minimal Residual variant of the Bi-CGStab algorithm (QMRCGStab) method. KSPQMRCGS
	FBCGS		Flexible Stabilized version of BiConjugate Gradient (BiCGStab) method. KSPFBCGS
	FBCGSR		A mathematically equivalent variant of flexible stabilized BiConjugate Gradient (BiCGStab). - KSPFBCGSR
	BCGSL		Variant of the L-step stabilized BiConjugate Gradient (BiCGStab(L)) algorithm. Uses "L-step" Minimal Residual (MR) polynomials. The variation concerns cases when some parameters are negative due to round-off. KSPBCGSL

PIPEBCGS

Pipelined stabilized BiConjugate Gradient (BiCGStab) method. KSPPIPEBCGS

	CGS		Conjugate Gradient Squared method. KSPCGS
	TFQMR		A Transpose Tree Quasi- Minimal Residual (QMR). - KSPCR
	CR		(Preconditioned) Conjugate Residuals (CR) method. KSPCR
	PIPECR		Pipelined Conjugate Residual (CR) method. - KSPPIPECR
	LSQR		Least squares solver. KSPLSQR

PREONLY

Applies ONLY the preconditioner exactly once. This may be used in inner iterations, where it is desired to allow multiple iterations as well as the "0-iteration" case. It is commonly used with the direct solver preconditioners like PCLU and PCCHOLESKY. There is an alias of KSPNONE. - KSPPREONLY

	NONE		No solver KSPNONE
	QCG		Conjugate Gradient (CG) method subject to a constraint on the solution norm. KSPQCG
	BICG		Implements the Biconjugate gradient method (BiCG). Similar to running the conjugate gradient on the normal equations. KSPBICG
	MINRES		Minimum Residual (MINRES) method. KSPMINRES
	SYMMLQ		Symmetric LQ method (SymmLQ). Uses LQ decomposition (lower trapezoidal). KSPSYMMLQ
	LCD		Left Conjugate Direction (LCD) method. KSPLCD
	PYTHON		Python shell solver. Call Python function to implement solver. KSPPYTHON
	GCR		Preconditioned flexible Generalized Conjugate Residual (GCR) method. KSPGCR

PIPEGCR

Pipelined Generalized Conjugate Residual method. KSPPIPEGCR

	TSIRM		Two-Stage Iteration with least-squares Residual Minimization method. KSPTSIRM
	CGLS		Conjugate Gradient method for Least-Squares problems. Supports non-square (rectangular) matrices. KSPCGLS
	FETIDP		Dual-Primal (DP) Finite Element Tearing and Interconnect (FETI) method. KSPFETIDP
	HPDDM		Interface with the HPDDM library. This KSP may be used to further select methods that are currently not implemented natively in PETSc, e.g., GCRODR, a recycled Krylov method which is similar to KSPLGMRES. KSPHPDDM

SEE ALSO:

Working with PETSc options , KSPType

Attributes Summary

Image grohtml-288464-68.png

Attributes Documentation
BCGS: str = BCGS

Object BCGS of type str

BCGSL: str = BCGSL

Object BCGSL of type str

BICG: str = BICG

Object BICG of type str

CG: str = CG

Object CG of type str

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

Methods Summary

Image grohtml-288464-69.png

Attributes Summary

Image grohtml-288464-70.png

Methods Documentation
addConvergenceTest(converged, args=None, kargs=None,
prepend=False)

Add the function to be used to determine convergence.

Logically collective.
Parameters

	•		converged ( KSPConvergenceTestFunction ) -- Callback which computes the convergence.
	•		args ( tuple[Any, ...] \| None ) -- Positional arguments for callback function.
	•		kargs ( dict[str, Any] \| None ) -- Keyword arguments for 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.

SEE ALSO:

setTolerances , getConvergenceTest , setConvergenceTest , KSPSetConvergenceTest , KSPConvergedDefault

Source code at petsc4py/PETSc/KSP.pyx:1065

appendOptionsPrefix(prefix)

Append to prefix used for all KSP options in the database.

Logically collective.
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.

SEE ALSO:

KSPAppendOptionsPrefix

Source code at petsc4py/PETSc/KSP.pyx:575

buildResidual(r=None)

Return the residual of the linear system.

Collective.
Parameters

r ( Vec | None ) -- Optional vector to use for the result.

Return type

Vec

SEE ALSO:

buildSolution , KSPBuildResidual

Source code at petsc4py/PETSc/KSP.pyx:2063

buildSolution(x=None)

Return the solution vector.

Collective.
Parameters

x ( Vec | None ) -- Optional vector to store the solution.

Return type

Vec

SEE ALSO:

buildResidual , KSPBuildSolution

Source code at petsc4py/PETSc/KSP.pyx:2041

callConvergenceTest(its, rnorm)

Call the convergence test callback.

Collective.
Parameters

	•		its ( int ) -- Number of iterations.
	•		rnorm ( float ) -- The residual norm.

Return type

None

Notes

This functionality is implemented in petsc4py.

Source code at petsc4py/PETSc/KSP.pyx:1121

computeEigenvalues()

Compute the extreme eigenvalues for the preconditioned operator.

Not collective.

SEE ALSO:

KSPComputeEigenvalues

Source code at petsc4py/PETSc/KSP.pyx:2085
Return type

ArrayComplex

computeExtremeSingularValues()

Compute the extreme singular values for the preconditioned operator.

Collective.
Returns

	•		smax ( float ) -- The maximum singular value.
	•		smin ( float ) -- The minimum singular value.

Return type

tuple [ float , float ]

SEE ALSO:

KSPComputeExtremeSingularValues

Source code at petsc4py/PETSc/KSP.pyx:2108

create(comm=None)

Create the KSP context.

Collective.

SEE ALSO:

KSPCreate

Source code at petsc4py/PETSc/KSP.pyx:457
Parameters

comm ( Comm | None )

Return type

Self

createPython(context=None, comm=None)

Create a linear solver 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 linear solver type , setType , setPythonContext , Type.PYTHON

Source code at petsc4py/PETSc/KSP.pyx:2154

destroy()

Destroy KSP context.

Collective.

SEE ALSO:

KSPDestroy

Source code at petsc4py/PETSc/KSP.pyx:444
Return type

Self

getAppCtx()

Return the user-defined context for the linear solver.

Not collective.

SEE ALSO:

setAppCtx

Source code at petsc4py/PETSc/KSP.pyx:640
Return type

Any

getCGObjectiveValue()

Return the CG objective function value.

Not collective.

SEE ALSO:

KSPCGGetObjFcn

Source code at petsc4py/PETSc/KSP.pyx:1882
Return type

float

getComputeEigenvalues()

Return flag indicating whether eigenvalues will be calculated.

Not collective.

Return 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

Source code at petsc4py/PETSc/KSP.pyx:1430
Return type

bool

getComputeSingularValues()

Return flag indicating whether singular values will be calculated.

Not collective.

Return 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

Source code at petsc4py/PETSc/KSP.pyx:1474
Return type

bool

getConvergedReason()

Use reason property.

Source code at petsc4py/PETSc/KSP.pyx:1876
Return type

ConvergedReason

getConvergenceHistory()

Return array containing the residual history.

Not collective.

SEE ALSO:

setConvergenceHistory , KSPGetResidualHistory

Source code at petsc4py/PETSc/KSP.pyx:1188
Return type

ArrayReal

getConvergenceTest()

Return the function to be used to determine convergence.

Logically collective.

SEE ALSO:

setTolerances , setConvergenceTest , - KSPGetConvergenceTest , KSPConvergedDefault

Source code at petsc4py/PETSc/KSP.pyx:1108
Return type

KSPConvergenceTestFunction

getDM()

Return the DM that may be used by some preconditioners.

Not collective.

SEE ALSO:

PETSc.KSP , DM , KSPGetDM

Source code at petsc4py/PETSc/KSP.pyx:654
Return type

getErrorIfNotConverged()

Return the flag indicating the solver will error if divergent.

Not collective.

SEE ALSO:

KSPGetErrorIfNotConverged

Source code at petsc4py/PETSc/KSP.pyx:1946
Return type

bool

getHPDDMType()

Return the Krylov solver type.

Not collective.

SEE ALSO:

KSPHPDDMGetType

Source code at petsc4py/PETSc/KSP.pyx:1914
Return type

HPDDMType

getInitialGuessKnoll()

Determine whether the KSP solver is using the Knoll trick.

Not collective.

This uses the Knoll trick; using PC.apply to compute the initial guess.

SEE ALSO:

KSPGetInitialGuessKnoll

Source code at petsc4py/PETSc/KSP.pyx:1550
Return type

bool

getInitialGuessNonzero()

Determine whether the KSP solver uses a zero initial guess.

Not collective.

SEE ALSO:

KSPGetInitialGuessNonzero

Source code at petsc4py/PETSc/KSP.pyx:1516
Return type

bool

getIterationNumber()

Use its property.

Source code at petsc4py/PETSc/KSP.pyx:1854
Return type

int

getMonitor()

Return function used to monitor the residual.

Not collective.

SEE ALSO:

Working with PETSc options , setMonitor , monitor , monitorCancel , KSPGetMonitorContext

Source code at petsc4py/PETSc/KSP.pyx:1266
Return type

KSPMonitorFunction

getNormType()

Return the norm that is used for convergence testing.

Not collective.

SEE ALSO:

NormType , setNormType , KSPGetNormType , - KSPConvergedSkip

Source code at petsc4py/PETSc/KSP.pyx:1390
Return type

NormType

getOperators()

Return the matrix associated with the linear system.

Collective.

Return the matrix associated with the linear system and a (possibly) different one used to construct the preconditioner.
Returns

	•		A ( Mat ) -- Matrix that defines the linear system.
	•		P ( Mat ) -- Matrix to be used in constructing the preconditioner, usually the same as A .

Return type

tuple [ Mat , Mat ]

SEE ALSO:

PETSc.KSP , solve , setOperators , KSPGetOperators

Source code at petsc4py/PETSc/KSP.pyx:850

getOptionsPrefix()

Return the prefix used for all KSP options in the database.

Not collective.

SEE ALSO:

KSPGetOptionsPrefix

Source code at petsc4py/PETSc/KSP.pyx:561
Return type

str

getPC()

Return the preconditioner.

Not collective.

SEE ALSO:

PETSc.KSP , setPC , KSPGetPC

Source code at petsc4py/PETSc/KSP.pyx:897
Return type

getPCSide()

Return the preconditioning side.

Not collective.

SEE ALSO:

Working with PETSc options , setPCSide , setNormType , getNormType , KSPGetPCSide

Source code at petsc4py/PETSc/KSP.pyx:1349
Return type

Side

getPythonContext()

Return the instance of the class implementing Python methods.

Not collective.

SEE ALSO:

PETSc Python linear solver type , setPythonContext

Source code at petsc4py/PETSc/KSP.pyx:2195
Return type

Any

getPythonType()

Return the fully qualified Python name of the class used by the solver.

Not collective.

SEE ALSO:

PETSc Python linear solver type , setPythonContext , setPythonType , KSPPythonGetType

Source code at petsc4py/PETSc/KSP.pyx:2225
Return type

str

getResidualNorm()

Use norm property.

Source code at petsc4py/PETSc/KSP.pyx:1865
Return type

float

getRhs()

Return the right-hand side vector for the linear system.

Not collective.

SEE ALSO:

KSPGetRhs

Source code at petsc4py/PETSc/KSP.pyx:1960
Return type

Vec

getSolution()

Return the solution for the linear system to be solved.

Not collective.

Note that this may not be the solution that is stored during the iterative process.

SEE ALSO:

KSPGetSolution

Source code at petsc4py/PETSc/KSP.pyx:1975
Return type

Vec

getTolerances()

Return various tolerances used by the KSP convergence tests.

Not collective.

Return the relative, absolute, divergence, and maximum iteration tolerances used by the default KSP convergence tests.
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

Source code at petsc4py/PETSc/KSP.pyx:971

getType()

Return the KSP type as a string from the KSP object.

Not collective.

SEE ALSO:

KSPGetType

Source code at petsc4py/PETSc/KSP.pyx:509
Return type

str

getWorkVecs(right=None, left=None)

Create working vectors.

Collective.
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:1993

logConvergenceHistory(rnorm)

Add residual to convergence history.

Logically collective.
Parameters

rnorm ( float ) -- Residual norm to be added to convergence history.

Return type

None

Source code at petsc4py/PETSc/KSP.pyx:1203

matSolve(B, X)

Solve a linear system with multiple right-hand sides.

Collective.

These are stored as a Mat.Type.DENSE . Unlike solve , B and X must be different matrices.
Parameters

	•		B ( Mat ) -- Block of right-hand sides.
	•		X ( Mat ) -- Block of solutions.

Return type

None

SEE ALSO:

solve , KSPMatSolve

Source code at petsc4py/PETSc/KSP.pyx:1808

matSolveTranspose(B, X)

Solve the transpose of a linear system with multiple RHS.

Collective.
Parameters

	•		B ( Mat ) -- Block of right-hand sides.
	•		X ( Mat ) -- Block of solutions.

Return type

None

SEE ALSO:

solveTranspose , KSPMatSolve

Source code at petsc4py/PETSc/KSP.pyx:1830

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.

SEE ALSO:

setMonitor , KSPMonitor

Source code at petsc4py/PETSc/KSP.pyx:1294
Parameters

	•		its ( int )
	•		rnorm ( float )

Return type

None

monitorCancel()

Clear all monitors for a KSP object.

Logically collective.

SEE ALSO:

Working with PETSc options , getMonitor , setMonitor , monitor , KSPMonitorCancel

Source code at petsc4py/PETSc/KSP.pyx:1279
Return type

None

reset()

Resets a KSP context.

Collective.

Resets a KSP context to the kspsetupcalled = 0 state and removes any allocated Vecs and Mats.

SEE ALSO:

KSPReset

Source code at petsc4py/PETSc/KSP.pyx:1607
Return type

None

setAppCtx(appctx)

Set the optional user-defined context for the linear solver.

Not collective.
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.

SEE ALSO:

getAppCtx

Source code at petsc4py/PETSc/KSP.pyx:617

setComputeEigenvalues(flag)

Set a flag to compute eigenvalues.

Logically collective.

Set a flag so that the extreme eigenvalues values will be calculated via a Lanczos or Arnoldi process as the linear system is solved.
Parameters

flag ( bool ) -- Boolean whether to compute eigenvalues (or not).

Return type

None

Notes

Currently this option is not valid for all iterative methods.

SEE ALSO:

getComputeEigenvalues , KSPSetComputeEigenvalues

Source code at petsc4py/PETSc/KSP.pyx:1404

setComputeOperators(operators, args=None, kargs=None)

Set routine to compute the linear operators.

Logically collective.
Parameters

	•		operators ( KSPOperatorsFunction ) -- Function which computes the operators.
	•		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

The user provided function Operators 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. This allows the same system to be solved several times with different right-hand side functions, but is a confusing API since one might expect it to be called for each solve .

To reuse the same preconditioner for the next solve and not compute a new one based on the most recently computed matrix call KSPSetReusePreconditioner .

SEE ALSO:

PETSc.KSP , solve , setOperators , - KSPSetComputeOperators , KSPSetReusePreconditioner

Source code at petsc4py/PETSc/KSP.pyx:764

setComputeRHS(rhs, args=None, kargs=None)

Set routine to compute the right-hand side of the linear system.

Logically collective.
Parameters

	•		rhs ( KSPRHSFunction ) -- Function which computes the right-hand side.
	•		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.

SEE ALSO:

PETSc.KSP , solve , KSPSetComputeRHS

Source code at petsc4py/PETSc/KSP.pyx:730

setComputeSingularValues(flag)

Set flag to calculate singular values.

Logically collective.

Set a flag so that the extreme singular values will be calculated via a Lanczos or Arnoldi process as the linear system is solved.
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.

SEE ALSO:

getComputeSingularValues , KSPSetComputeSingularValues

Source code at petsc4py/PETSc/KSP.pyx:1448

setConvergedReason(reason)

Use reason property.

Source code at petsc4py/PETSc/KSP.pyx:1871
Parameters

reason ( ConvergedReason )

Return type

None

setConvergenceHistory(length=None, reset=False)

Set the array used to hold the residual history.

Not collective.

If set, this array will contain the residual norms computed at each iteration of the solver.
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.

If the array is not long enough then once the iterations is longer than the array length solve stops recording the history.

SEE ALSO:

getConvergenceHistory , KSPSetResidualHistory

Source code at petsc4py/PETSc/KSP.pyx:1144

setConvergenceTest(converged, args=None, kargs=None)

Set the function to be used to determine convergence.

Logically collective.
Parameters

	•		converged ( KSPConvergenceTestFunction ) -- Callback which computes the convergence.
	•		args ( tuple[Any, ...] \| None ) -- Positional arguments for callback function.
	•		kargs ( dict[str, Any] \| None ) -- Keyword arguments for callback function.

Return type

None

Notes

Must be called after the KSP type has been set so put this after a call to setType , or setFromOptions .

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:

addConvergenceTest , ConvergedReason , setTolerances , getConvergenceTest , buildResidual , - KSPSetConvergenceTest , KSPConvergedDefault

Source code at petsc4py/PETSc/KSP.pyx:1000

setDM(dm)

Set the DM that may be used by some preconditioners.

Logically collective.
Parameters

dm ( DM ) -- The DM object, cannot be None .

Return type

None

Notes

If this is used then the KSP will attempt to use the DM to create the matrix and use the routine set with DM.setKSPComputeOperators . Use setDMActive(False) to instead use the matrix you have provided with setOperators .

A DM can only be used for solving one problem at a time because information about the problem is stored on the DM , even when not using interfaces like DM.setKSPComputeOperators . Use DM.clone to get a distinct DM when solving different problems using the same function space.

SEE ALSO:

PETSc.KSP , DM , DM.setKSPComputeOperators , setOperators , DM.clone , KSPSetDM

Source code at petsc4py/PETSc/KSP.pyx:671

setDMActive(flag)

DM should be used to generate system matrix & RHS vector.

Logically collective.
Parameters

flag ( bool ) -- Whether to use the DM .

Return type

None

Notes

By default setDM sets the DM as active, call setDMActive(False) after setDM(dm) to not have the KSP object use the DM to generate the matrices.

SEE ALSO:

PETSc.KSP , DM , setDM , KSPSetDMActive

Source code at petsc4py/PETSc/KSP.pyx:704

setErrorIfNotConverged(flag)

Cause solve to generate an error if not converged.

Logically collective.
Parameters

flag ( bool ) -- True enables this behavior.

Return type

None

SEE ALSO:

KSPSetErrorIfNotConverged

Source code at petsc4py/PETSc/KSP.pyx:1928

setFromOptions()

Set KSP options from the options database.

Collective.

This routine must be called before setUp if the user is to be allowed to set the Krylov type.

SEE ALSO:

Working with PETSc options , KSPSetFromOptions

Source code at petsc4py/PETSc/KSP.pyx:600
Return type

None

setGMRESRestart(restart)

Set number of iterations at which KSP restarts.

Logically collective.

Suitable KSPs are: KSPGMRES, KSPFGMRES and KSPLGMRES.
Parameters

restart ( int ) -- Integer restart value.

Return type

None

SEE ALSO:

KSPGMRESSetRestart

Source code at petsc4py/PETSc/KSP.pyx:2132

setHPDDMType(hpddm_type)

Set the Krylov solver type.

Collective.
Parameters

hpddm_type ( HPDDMType ) -- The type of Krylov solver to use.

Return type

None

SEE ALSO:

KSPHPDDMSetType

Source code at petsc4py/PETSc/KSP.pyx:1896

setInitialGuessKnoll(flag)

Tell solver to use PC.apply to compute the initial guess.

Logically collective.

This is the Knoll trick.
Parameters

flag ( bool ) -- True uses Knoll trick.

Return type

None

SEE ALSO:

KSPSetInitialGuessKnoll

Source code at petsc4py/PETSc/KSP.pyx:1530

setInitialGuessNonzero(flag)

Tell the iterative solver that the initial guess is nonzero.

Logically collective.

Otherwise KSP assumes the initial guess is to be zero (and thus zeros it out before solving).
Parameters

flag ( bool ) -- True indicates the guess is non-zero, False indicates the guess is zero.

Return type

None

SEE ALSO:

KSPSetInitialGuessNonzero

Source code at petsc4py/PETSc/KSP.pyx:1494

setIterationNumber(its)

Use its property.

Source code at petsc4py/PETSc/KSP.pyx:1849
Parameters

its ( int )

Return type

None

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

Set 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 ) -- Callback which monitors the convergence.
	•		args ( tuple[Any, ...] \| None ) -- Positional arguments for callback function.
	•		kargs ( dict[str, Any] \| None ) -- Keyword arguments for callback function.

Return type

None

Notes

The default is to do nothing. To print the residual, or preconditioned residual if setNormType(NORM_PRECONDITIONED) was called, use monitor as the monitoring routine, with a PETSc.Viewer.ASCII as the context.

Several different monitoring routines may be set by calling setMonitor multiple times; all will be called in the order in which they were set.

SEE ALSO:

Working with PETSc options , getMonitor , monitor , monitorCancel , KSPMonitorSet

Source code at petsc4py/PETSc/KSP.pyx:1219

setNormType(normtype)

Set the norm that is used for convergence testing.

Logically collective.
Parameters

normtype ( NormType ) -- The norm type to use (see NormType ).

Return type

None

Notes

Not all combinations of preconditioner side (see setPCSide ) and norm type are supported by all Krylov methods. If only one is set, PETSc tries to automatically change the other to find a compatible pair. If no such combination is supported, PETSc will generate an error.

SEE ALSO:

NormType , Working with PETSc options , setUp , solve , destroy , setPCSide , getPCSide , NormType , - KSPSetNormType , KSPConvergedSkip , - KSPSetCheckNormIteration

Source code at petsc4py/PETSc/KSP.pyx:1363

setOperators(A=None, P=None)

Set matrix associated with the linear system.

Collective.

Set the matrix associated with the linear system and a (possibly) different one from which the preconditioner will be built.
Parameters

	•		A ( Mat \| None ) -- Matrix that defines the linear system.
	•		P ( Mat \| None ) -- Matrix to be used in constructing the preconditioner, usually the same as A .

Return type

None

Notes

If you know the operator A has a null space you can use Mat.setNullSpace and Mat.setTransposeNullSpace to supply the null space to A and the KSP solvers will automatically use that null space as needed during the solution process.

All future calls to setOperators must use the same size matrices!

Passing None for A or P removes the matrix that is currently used.

SEE ALSO:

PETSc.KSP , solve , setComputeOperators , KSPSetOperators

Source code at petsc4py/PETSc/KSP.pyx:809

setOptionsPrefix(prefix)

Set 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. The first character of all runtime options is AUTOMATICALLY the hyphen. For example, to distinguish between the runtime options for two different KSP contexts, one could call ` KSPSetOptionsPrefix(ksp1, "sys1_") KSPSetOptionsPrefix(ksp2, "sys2_") `

This would enable use of different options for each system, such as ` -sys1_ksp_type gmres -sys1_ksp_rtol 1.e-3 -sys2_ksp_type bcgs -sys2_ksp_rtol 1.e-4 `

SEE ALSO:

Working with PETSc options , KSPSetOptionsPrefix

Source code at petsc4py/PETSc/KSP.pyx:523

setPC(pc)

Set the preconditioner.

Collective.

Set the preconditioner to be used to calculate the application of the preconditioner on a vector.
Parameters

pc ( PC ) -- The preconditioner object

Return type

None

SEE ALSO:

PETSc.KSP , getPC , KSPSetPC

Source code at petsc4py/PETSc/KSP.pyx:877

setPCSide(side)

Set the preconditioning side.

Logically collective.
Parameters

side ( Side ) -- The preconditioning side (see PC.Side ).

Return type

None

Notes

Left preconditioning is used by default for most Krylov methods except Type.FGMRES which only supports right preconditioning.

For methods changing the side of the preconditioner changes the norm type that is used, see setNormType .

Symmetric preconditioning is currently available only for the Type.QCG method. Note, however, that symmetric preconditioning can be emulated by using either right or left preconditioning and a pre or post processing step.

Setting the PC side often affects the default norm type. See setNormType for details.

SEE ALSO:

PC.Side , Working with PETSc options , getPCSide , setNormType , getNormType , KSPSetPCSide

Source code at petsc4py/PETSc/KSP.pyx:1315

setPostSolve(postsolve, args=None, kargs=None)

Set the function that is called at the end of each KSP.solve .

Logically collective.
Parameters

	•		postsolve ( KSPPostSolveFunction \| None ) -- The callback function.
	•		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:1670

setPreSolve(presolve, args=None, kargs=None)

Set the function that is called at the beginning of each KSP.solve .

Logically collective.
Parameters

	•		presolve ( KSPPreSolveFunction \| None ) -- The callback function.
	•		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:1637

setPythonContext(context=None)

Set the instance of the class implementing Python methods.

Not collective.

SEE ALSO:

PETSc Python linear solver type , getPythonContext

Source code at petsc4py/PETSc/KSP.pyx:2183
Parameters

context ( Any | None )

Return type

None

setPythonType(py_type)

Set the fully qualified Python name of the class to be used.

Collective.

SEE ALSO:

PETSc Python linear solver type , setPythonContext , getPythonType , KSPPythonSetType

Source code at petsc4py/PETSc/KSP.pyx:2210
Parameters

py_type ( str )

Return type

None

setResidualNorm(rnorm)

Use norm property.

Source code at petsc4py/PETSc/KSP.pyx:1860
Parameters

rnorm ( float )

Return type

None

setTolerances(rtol=None, atol=None, divtol=None, max_it=None)

Set various tolerances used by the KSP convergence testers.

Logically collective.

Set the relative, absolute, divergence, and maximum iteration tolerances used by the default KSP convergence testers.
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 (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.
	•		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 )

Return type

None

Notes

Use None to retain the default value of any of the tolerances.

SEE ALSO:

Working with PETSc options , getTolerances , setConvergenceTest , KSPSetTolerances , - KSPConvergedDefault

Source code at petsc4py/PETSc/KSP.pyx:914

setType(ksp_type)

Build the KSP data structure for a particular Type .

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

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.

SEE ALSO:

KSPSetType

Source code at petsc4py/PETSc/KSP.pyx:473

setUp()

Set up internal data structures for an iterative solver.

Collective.

SEE ALSO:

KSPSetUp

Source code at petsc4py/PETSc/KSP.pyx:1595
Return type

None

setUpOnBlocks()

Set up the preconditioner for each block in a block method.

Collective.

Methods include: block Jacobi, block Gauss-Seidel, and overlapping Schwarz methods.

SEE ALSO:

KSPSetUpOnBlocks

Source code at petsc4py/PETSc/KSP.pyx:1622
Return type

None

setUseFischerGuess(model, size)

Use the Paul Fischer algorithm to compute initial guesses.

Logically collective.

Use the Paul Fischer algorithm or its variants to compute initial guesses for a set of solves with related right hand sides.
Parameters

	•		model ( int ) -- Use model 1 , model 2 , model 3 , any other number to turn it off.
	•		size ( int ) -- Size of subspace used to generate initial guess.

Return type

None

SEE ALSO:

KSPSetUseFischerGuess

Source code at petsc4py/PETSc/KSP.pyx:1567

solve(b, x)

Solve the linear system.

Collective.
Parameters

	•		b ( Vec ) -- Right hand side vector.
	•		x ( Vec ) -- Solution vector.

Return type

None

Notes

If one uses setDM then x or b need not be passed. Use getSolution to access the solution in this case.

The operator is specified with setOperators .

solve will normally return without generating an error regardless of whether the linear system was solved or if constructing the preconditioner failed. 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.

The number of iterations can be obtained from its .

If you provide a matrix that has a Mat.setNullSpace and Mat.setTransposeNullSpace this will use that information to solve singular systems in the least squares sense with a norm minimizing solution.

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 .

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 for such singular systems. 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).

If using a direct method (e.g., via the KSP solver Type.PREONLY and a preconditioner such as PC.Type.LU or 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.

SEE ALSO:

create , setUp , destroy , setTolerances , is_converged , solveTranspose , its , Mat.setNullSpace , Mat.setTransposeNullSpace , Type , setErrorIfNotConverged , KSPSolve

Source code at petsc4py/PETSc/KSP.pyx:1703

solveTranspose(b, x)

Solve the transpose of a linear system.

Collective.
Parameters

	•		b ( Vec ) -- Right hand side vector.
	•		x ( Vec ) -- Solution vector.

Return type

None

Notes

For complex numbers this solve the non-Hermitian transpose system.

SEE ALSO:

solve , KSPSolveTranspose

Source code at petsc4py/PETSc/KSP.pyx:1784

view(viewer=None)

Print the KSP data structure.

Collective.
Parameters

viewer ( Viewer | None ) -- Viewer used to display the KSP.

Return type

None

SEE ALSO:

KSPView

Source code at petsc4py/PETSc/KSP.pyx:425

Attributes Documentation

appctx

The solver application context.

Source code at petsc4py/PETSc/KSP.pyx:2242

atol

The absolute tolerance of the solver.

Source code at petsc4py/PETSc/KSP.pyx:2335

divtol

The divergence tolerance of the solver.

Source code at petsc4py/PETSc/KSP.pyx:2343

The solver DM .

Source code at petsc4py/PETSc/KSP.pyx:2252

guess_knoll

Whether solver uses Knoll trick.

Source code at petsc4py/PETSc/KSP.pyx:2294

guess_nonzero

Whether guess is non-zero.

Source code at petsc4py/PETSc/KSP.pyx:2286

history

The convergence history of the solver.

Source code at petsc4py/PETSc/KSP.pyx:2377

is_converged

Boolean indicating if the solver has converged.

Source code at petsc4py/PETSc/KSP.pyx:2397

is_diverged

Boolean indicating if the solver has failed.

Source code at petsc4py/PETSc/KSP.pyx:2402

is_iterating

Boolean indicating if the solver has not converged yet.

Source code at petsc4py/PETSc/KSP.pyx:2392

its

The current number of iterations the solver has taken.

Source code at petsc4py/PETSc/KSP.pyx:2361

mat_op

The system matrix operator.

Source code at petsc4py/PETSc/KSP.pyx:2274

mat_pc

The preconditioner operator.

Source code at petsc4py/PETSc/KSP.pyx:2279

max_it

The maximum number of iteration the solver may take.

Source code at petsc4py/PETSc/KSP.pyx:2351

norm

The norm of the residual at the current iteration.

Source code at petsc4py/PETSc/KSP.pyx:2369

norm_type

The norm used by the solver.

Source code at petsc4py/PETSc/KSP.pyx:2317

The PC of the solver.

Source code at petsc4py/PETSc/KSP.pyx:2304

pc_side

The side on which preconditioning is performed.

Source code at petsc4py/PETSc/KSP.pyx:2309

reason

The converged reason.

Source code at petsc4py/PETSc/KSP.pyx:2384

rtol

The relative tolerance of the solver.

Source code at petsc4py/PETSc/KSP.pyx:2327

vec_rhs

The right-hand side vector.

Source code at petsc4py/PETSc/KSP.pyx:2267

vec_sol

The solution vector.

Source code at petsc4py/PETSc/KSP.pyx:2262

petsc4py.PETSc.LGMap

class petsc4py.PETSc.LGMap

Bases: Object

Mapping from a local to a global ordering.

SEE ALSO:

ISLocalToGlobalMapping

Enumerations

Image grohtml-288464-71.png

petsc4py.PETSc.LGMap.GLMapMode

class petsc4py.PETSc.LGMap.GLMapMode

Bases: object

Enum describing mapping behavior when global indices are missing.

	MASK		Give missing global indices a local index of -1.
	DROP		Drop missing global indices.

SEE ALSO:

ISGlobalToLocalMappingMode

Attributes Summary

Image grohtml-288464-72.png

Attributes Documentation
DROP: int = DROP

Constant DROP of type int

MASK: int = MASK

Constant MASK of type int

petsc4py.PETSc.LGMap.Type

class petsc4py.PETSc.LGMap.Type

Bases: object

Local to global map types.

Attributes Summary

Image grohtml-288464-73.png

Attributes Documentation
BASIC: str = BASIC

Object BASIC of type str

HASH: str = HASH

Object HASH of type str

Methods Summary

Image grohtml-288464-74.png

Attributes Summary

Image grohtml-288464-75.png

Methods Documentation
apply(indices, result=None)

Convert a locally numbered list of integers to a global numbering.

Not collective.
Parameters

	•		indices ( Sequence[int] ) -- Input indices in local numbering.
	•		result ( ArrayInt \| None ) -- Array to write the global numbering to. If None then a new array will be allocated.

Returns

Indices in global numbering. If result is not None then this is returned here.

Return type

ArrayInt

SEE ALSO:

LGMap.applyBlock , ISLocalToGlobalMappingApply

Source code at petsc4py/PETSc/IS.pyx:1404

applyBlock(indices, result=None)

Convert a local block numbering to 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 to. If None then a new array will be allocated.

Returns

Block indices in global numbering. If result is not None then this is returned here.

Return type

ArrayInt

SEE ALSO:

LGMap.apply , ISLocalToGlobalMappingApplyBlock

Source code at petsc4py/PETSc/IS.pyx:1441

applyBlockInverse(indices, mode=None)

Compute blocked local numbering from blocked global numbering.

Not collective.
Parameters

	•		indices ( Sequence[int] ) -- Indices with a global block numbering.
	•		mode ( GLMapMode \| str \| None ) -- Flag indicating 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:1542

applyIS(iset)

Create an index set with global numbering from a local numbering.

Collective.
Parameters

iset ( IS ) -- Index set with local numbering.

Returns

Index set with global numbering.

Return type

SEE ALSO:

ISLocalToGlobalMappingApplyIS

Source code at petsc4py/PETSc/IS.pyx:1478

applyInverse(indices, mode=None)

Compute local numbering from global numbering.

Not collective.
Parameters

	•		indices ( Sequence[int] ) -- Indices with a global numbering.
	•		mode ( GLMapMode \| str \| None ) -- Flag indicating 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:1503

create(indices, bsize=None, comm=None)

Create a local-to-global mapping.

Not collective.
Parameters

	•		indices ( Sequence[int] ) -- 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:1187

createIS(iset)

Create a local-to-global mapping from an index set.

Not collective.
Parameters

iset ( IS ) -- Index set containing the global numbers for each local number.

Return type

Self

SEE ALSO:

ISLocalToGlobalMappingCreateIS

Source code at petsc4py/PETSc/IS.pyx:1222

createSF(sf, start)

Create a local-to-global mapping from a star forest.

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

destroy()

Destroy the local-to-global mapping.

Not collective.

SEE ALSO:

ISLocalToGlobalMappingDestroy

Source code at petsc4py/PETSc/IS.pyx:1174
Return type

Self

getBlockIndices()

Return the global indices for each local block.

Not collective.

SEE ALSO:

ISLocalToGlobalMappingGetBlockIndices

Source code at petsc4py/PETSc/IS.pyx:1318
Return type

ArrayInt

getBlockInfo()

Determine the block indices shared with neighboring processes.

Collective.
Returns

Mapping from neighboring processor number to an array of shared block indices (in local numbering).

Return type

dict

SEE ALSO:

ISLocalToGlobalMappingGetBlockInfo

Source code at petsc4py/PETSc/IS.pyx:1373

getBlockSize()

Return the block size of the local-to-global mapping.

Not collective.

SEE ALSO:

ISLocalToGlobalMappingGetBlockSize

Source code at petsc4py/PETSc/IS.pyx:1280
Return type

int

getIndices()

Return the global indices for each local point in the mapping.

Not collective.

SEE ALSO:

ISLocalToGlobalMappingGetIndices

Source code at petsc4py/PETSc/IS.pyx:1294
Return type

ArrayInt

getInfo()

Determine the indices shared with neighboring processes.

Collective.
Returns

Mapping from neighboring processor number to an array of shared indices (in local numbering).

Return type

dict

SEE ALSO:

ISLocalToGlobalMappingGetInfo

Source code at petsc4py/PETSc/IS.pyx:1344

getSize()

Return the local size of the local-to-global mapping.

Not collective.

SEE ALSO:

ISLocalToGlobalMappingGetSize

Source code at petsc4py/PETSc/IS.pyx:1266
Return type

int

setFromOptions()

Set mapping options from the options database.

Not collective.

SEE ALSO:

Working with PETSc options , - ISLocalToGlobalMappingSetFromOptions

Source code at petsc4py/PETSc/IS.pyx:1143
Return type

None

setType(lgmap_type)

Set the type of the local-to-global map.

Logically collective.
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

Source code at petsc4py/PETSc/IS.pyx:1119

view(viewer=None)

View the local-to-global mapping.

Not collective.
Parameters

viewer ( Viewer | None ) -- Viewer instance, defaults to an instance of Viewer.Type.ASCII .

Return type

None

SEE ALSO:

ISLocalToGlobalMappingView

Source code at petsc4py/PETSc/IS.pyx:1155

Attributes Documentation
block_indices

The global indices for each local block in the mapping.

Not collective.

SEE ALSO:

LGMap.getBlockIndices , - ISLocalToGlobalMappingGetBlockIndices

Source code at petsc4py/PETSc/IS.pyx:1621

block_info

Mapping describing block indices shared with neighboring processes.

Collective.

SEE ALSO:

LGMap.getBlockInfo , ISLocalToGlobalMappingGetBlockInfo

Source code at petsc4py/PETSc/IS.pyx:1647

block_size

The block size.

Not collective.

SEE ALSO:

LGMap.getBlockSize

Source code at petsc4py/PETSc/IS.pyx:1595

indices

The global indices for each local point in the mapping.

Not collective.

SEE ALSO:

LGMap.getIndices , ISLocalToGlobalMappingGetIndices

Source code at petsc4py/PETSc/IS.pyx:1608

info

Mapping describing indices shared with neighboring processes.

Collective.

SEE ALSO:

LGMap.getInfo , ISLocalToGlobalMappingGetInfo

Source code at petsc4py/PETSc/IS.pyx:1634

size

The local size.

Not collective.

SEE ALSO:

LGMap.getSize

Source code at petsc4py/PETSc/IS.pyx:1582

petsc4py.PETSc.Log

class petsc4py.PETSc.Log

Bases: object

Logging support.

Methods Summary

Image grohtml-288464-76.png

Methods Documentation
classmethod Class(name)

Source code at petsc4py/PETSc/Log.pyx:25
Return type

LogClass

classmethod Event(name, klass=None)

Source code at petsc4py/PETSc/Log.pyx:39
Return type

LogEvent

classmethod EventDecorator(name=None, klass=None)

Decorate a function with a PETSc event.

Source code at petsc4py/PETSc/Log.pyx:178
Return type

Any

classmethod Stage(name)

Source code at petsc4py/PETSc/Log.pyx:11
Return type

LogStage

classmethod addFlops(flops)

Add floating point operations to the current event.

Not collective.
Parameters

flops ( float ) -- The number of flops to log.

Return type

None

Notes

This method exists for backward compatibility.

SEE ALSO:

logFlops , PetscLogFlops

Source code at petsc4py/PETSc/Log.pyx:108

classmethod begin()

Turn on logging of objects and events.

Collective.

SEE ALSO:

PetscLogDefaultBegin

Source code at petsc4py/PETSc/Log.pyx:55
Return type

None

classmethod getCPUTime()

Return the CPU time.

Source code at petsc4py/PETSc/Log.pyx:171
Return type

float

classmethod getFlops()

Return the number of flops used on this processor since the program began.

Not collective.
Returns

Number of floating point operations.

Return type

float

SEE ALSO:

PetscGetFlops

Source code at petsc4py/PETSc/Log.pyx:131

classmethod getTime()

Return the current time of day in seconds.

Collective.
Returns

wctime -- Current time.

Return type

float

SEE ALSO:

PetscTime

Source code at petsc4py/PETSc/Log.pyx:151

classmethod isActive()

Return whether logging is currently in progress.

Not collective.

SEE ALSO:

PetscLogIsActive

Source code at petsc4py/PETSc/Log.pyx:193
Return type

bool

classmethod logFlops(flops)

Add floating point operations to the current event.

Not collective.
Parameters

flops ( float ) -- The number of flops to log.

Return type

None

SEE ALSO:

PetscLogFlops

Source code at petsc4py/PETSc/Log.pyx:89

classmethod view(viewer=None)

Print the log.

Collective.
Parameters

viewer ( Viewer | None ) -- A Viewer instance or - None for the default viewer.

Return type

None

SEE ALSO:

Working with PETSc options , PetscLogView

Source code at petsc4py/PETSc/Log.pyx:68

petsc4py.PETSc.LogClass

class petsc4py.PETSc.LogClass

Bases: object

Logging support.

Methods Summary

Image grohtml-288464-77.png

Attributes Summary

Image grohtml-288464-78.png

Methods Documentation
activate()

Activate the log class.

Source code at petsc4py/PETSc/Log.pyx:431
Return type

None

deactivate()

Deactivate the log class.

Source code at petsc4py/PETSc/Log.pyx:435
Return type

None

getActive()

Not implemented.

Source code at petsc4py/PETSc/Log.pyx:439
Return type

bool

getName()

Return the log class name.

Source code at petsc4py/PETSc/Log.pyx:414
Return type

str

setActive(flag)

Activate or deactivate the log class.

Source code at petsc4py/PETSc/Log.pyx:444
Parameters

flag ( bool )

Return type

None

Attributes Documentation

active

Log class activation.

Source code at petsc4py/PETSc/Log.pyx:451

The log class identifier.

Source code at petsc4py/PETSc/Log.pyx:401

name

The log class name.

Source code at petsc4py/PETSc/Log.pyx:420

petsc4py.PETSc.LogEvent

class petsc4py.PETSc.LogEvent

Bases: object

Logging support.

Methods Summary

Image grohtml-288464-79.png

Attributes Summary

Image grohtml-288464-80.png

Methods Documentation
activate()

Indicate that the event should be logged.

Logically collective.

SEE ALSO:

PetscLogEventActivate

Source code at petsc4py/PETSc/Log.pyx:552
Return type

None

begin(*objs)

Log the beginning of a user event.

Collective.
Parameters

*objs -- objects associated with the event

Return type

None

SEE ALSO:

PetscLogEventBegin

Source code at petsc4py/PETSc/Log.pyx:496

deactivate()

Indicate that the event should not be logged.

Logically collective.

SEE ALSO:

PetscLogEventDeactivate

Source code at petsc4py/PETSc/Log.pyx:564
Return type

None

end(*objs)

Log the end of a user event.

Collective.
Parameters

*objs -- Objects associated with the event.

Return type

None

SEE ALSO:

PetscLogEventEnd

Source code at petsc4py/PETSc/Log.pyx:515

getActive()

Not implemented.

Source code at petsc4py/PETSc/Log.pyx:576
Return type

bool

getActiveAll()

Not implemented.

Source code at petsc4py/PETSc/Log.pyx:609
Return type

bool

getName()

The current event name.

Source code at petsc4py/PETSc/Log.pyx:535
Return type

str

getPerfInfo(stage=None)

Get the performance information about the given event in the given event.

Not collective.
Parameters

stage ( int | None ) -- The stage number.

Returns

info -- This structure is filled with the performance information.

Return type

dict

SEE ALSO:

PetscLogEventGetPerfInfo

Source code at petsc4py/PETSc/Log.pyx:643

setActive(flag)

Indicate whether or not the event should be logged.

Logically collective.
Parameters

flag ( bool ) -- Activate or deactivate the event.

Return type

None

SEE ALSO:

PetscLogEventDeactivate , PetscLogEventActivate

Source code at petsc4py/PETSc/Log.pyx:581

setActiveAll(flag)

Turn on logging of all events.

Logically collective.
Parameters

flag ( bool ) -- Activate (if True ) or deactivate (if False ) the logging of all events.

Return type

None

SEE ALSO:

PetscLogEventSetActiveAll

Source code at petsc4py/PETSc/Log.pyx:614

Attributes Documentation

active

Event activation.

Source code at petsc4py/PETSc/Log.pyx:601

active_all

All events activation.

Source code at petsc4py/PETSc/Log.pyx:633

The log event identifier.

Source code at petsc4py/PETSc/Log.pyx:478

name

The current event name.

Source code at petsc4py/PETSc/Log.pyx:541

petsc4py.PETSc.LogStage

class petsc4py.PETSc.LogStage

Bases: object

Logging support for different stages.

Methods Summary

Image grohtml-288464-81.png

Attributes Summary

Image grohtml-288464-82.png

Methods Documentation
activate()

Activate the stage.

Logically collective.

SEE ALSO:

PetscLogStageSetActive

Source code at petsc4py/PETSc/Log.pyx:279
Return type

None

deactivate()

Deactivate the stage.

Logically collective.

SEE ALSO:

PetscLogStageSetActive

Source code at petsc4py/PETSc/Log.pyx:291
Return type

None

getActive()

Check if the stage is activated.

Not collective.

SEE ALSO:

PetscLogStageGetActive

Source code at petsc4py/PETSc/Log.pyx:303
Return type

bool

getName()

Return the current stage name.

Source code at petsc4py/PETSc/Log.pyx:262
Return type

str

getVisible()

Return whether the stage is visible.

Not collective.

SEE ALSO:

LogStage.setVisible , PetscLogStageSetVisible

Source code at petsc4py/PETSc/Log.pyx:341
Return type

bool

pop()

Pop a stage from the logging stack.

Logically collective.

SEE ALSO:

LogStage.push , PetscLogStagePop

Source code at petsc4py/PETSc/Log.pyx:247
Return type

None

push()

Push a stage on the logging stack.

Logically collective.

SEE ALSO:

LogStage.pop , PetscLogStagePush

Source code at petsc4py/PETSc/Log.pyx:235
Return type

None

setActive(flag)

Activate or deactivate the current stage.

Logically collective.

SEE ALSO:

PetscLogStageSetActive

Source code at petsc4py/PETSc/Log.pyx:317
Parameters

flag ( bool )

Return type

None

setVisible(flag)

Set the visibility of the stage.

Logically collective.
Parameters

flag ( bool ) -- True to make the stage visible, - False otherwise.

Return type

None

SEE ALSO:

LogStage.getVisible , PetscLogStageSetVisible

Source code at petsc4py/PETSc/Log.pyx:355

Attributes Documentation

active

Whether the stage is activate.

Source code at petsc4py/PETSc/Log.pyx:331

The log stage identifier.

Source code at petsc4py/PETSc/Log.pyx:215

name

The current stage name.

Source code at petsc4py/PETSc/Log.pyx:268

visible

Whether the stage is visible.

Source code at petsc4py/PETSc/Log.pyx:374

petsc4py.PETSc.Mat

class petsc4py.PETSc.Mat

Bases: Object

Matrix object.

Mat is described in the PETSc manual .

SEE ALSO:

Mat

Enumerations

Image grohtml-288464-83.png

petsc4py.PETSc.Mat.AssemblyType

class petsc4py.PETSc.Mat.AssemblyType

Bases: object

Matrix assembly type.

SEE ALSO:

MatAssemblyType

Attributes Summary

Image grohtml-288464-84.png

Attributes Documentation
FINAL: int = FINAL

Constant FINAL of type int

FINAL_ASSEMBLY: int = FINAL_ASSEMBLY

Constant FINAL_ASSEMBLY of type int

FLUSH: int = FLUSH

Constant FLUSH of type int

FLUSH_ASSEMBLY: int = FLUSH_ASSEMBLY

Constant FLUSH_ASSEMBLY of type int

petsc4py.PETSc.Mat.DuplicateOption

class petsc4py.PETSc.Mat.DuplicateOption

Bases: object

Matrix duplicate option.

SEE ALSO:

MatDuplicateOption

Attributes Summary

Image grohtml-288464-85.png

Attributes Documentation
COPY_VALUES: int = COPY_VALUES

Constant COPY_VALUES of type int

DO_NOT_COPY_VALUES: int = DO_NOT_COPY_VALUES

Constant DO_NOT_COPY_VALUES of type int

SHARE_NONZERO_PATTERN: int = SHARE_NONZERO_PATTERN

Constant SHARE_NONZERO_PATTERN of type int

petsc4py.PETSc.Mat.FactorShiftType

class petsc4py.PETSc.Mat.FactorShiftType

Bases: object

Factored matrix shift type.

SEE ALSO:

MatFactorShiftType

Attributes Summary

Image grohtml-288464-86.png

Attributes Documentation
INBLOCKS: int = INBLOCKS

Constant INBLOCKS of type int

NONE: int = NONE

Constant NONE of type int

NONZERO: int = NONZERO

Constant NONZERO of type int

NZ: int = NZ

Constant NZ of type int

PD: int = PD

Constant PD of type int

POSITIVE_DEFINITE: int = POSITIVE_DEFINITE

Constant POSITIVE_DEFINITE of type int

petsc4py.PETSc.Mat.InfoType

class petsc4py.PETSc.Mat.InfoType

Bases: object

Matrix info type.

Attributes Summary

Image grohtml-288464-87.png

Attributes Documentation
GLOBAL_MAX: int = GLOBAL_MAX

Constant GLOBAL_MAX of type int

GLOBAL_SUM: int = GLOBAL_SUM

Constant GLOBAL_SUM of type int

LOCAL: int = LOCAL

Constant LOCAL of type int

petsc4py.PETSc.Mat.Option

class petsc4py.PETSc.Mat.Option

Bases: object

Matrix option.

SEE ALSO:

MatOption

Attributes Summary

Image grohtml-288464-88.png

Attributes Documentation
ERROR_LOWER_TRIANGULAR: int = ERROR_LOWER_TRIANGULAR

Constant ERROR_LOWER_TRIANGULAR of type int

FORCE_DIAGONAL_ENTRIES: int = FORCE_DIAGONAL_ENTRIES

Constant FORCE_DIAGONAL_ENTRIES of type int

GETROW_UPPERTRIANGULAR: int = GETROW_UPPERTRIANGULAR

Constant GETROW_UPPERTRIANGULAR of type int

HERMITIAN: int = HERMITIAN

Constant HERMITIAN of type int

IGNORE_LOWER_TRIANGULAR: int = IGNORE_LOWER_TRIANGULAR

Constant IGNORE_LOWER_TRIANGULAR of type int

IGNORE_OFF_PROC_ENTRIES: int = IGNORE_OFF_PROC_ENTRIES

Constant IGNORE_OFF_PROC_ENTRIES of type int

IGNORE_ZERO_ENTRIES: int = IGNORE_ZERO_ENTRIES

Constant IGNORE_ZERO_ENTRIES of type int

KEEP_NONZERO_PATTERN: int = KEEP_NONZERO_PATTERN

Constant KEEP_NONZERO_PATTERN of type int

NEW_NONZERO_ALLOCATION_ERR: int =
NEW_NONZERO_ALLOCATION_ERR

Constant NEW_NONZERO_ALLOCATION_ERR of type int

NEW_NONZERO_LOCATIONS: int = NEW_NONZERO_LOCATIONS

Constant NEW_NONZERO_LOCATIONS of type int

NEW_NONZERO_LOCATION_ERR: int = NEW_NONZERO_LOCATION_ERR

Constant NEW_NONZERO_LOCATION_ERR of type int

NO_OFF_PROC_ENTRIES: int = NO_OFF_PROC_ENTRIES

Constant NO_OFF_PROC_ENTRIES of type int

NO_OFF_PROC_ZERO_ROWS: int = NO_OFF_PROC_ZERO_ROWS

Constant NO_OFF_PROC_ZERO_ROWS of type int

OPTION_MAX: int = OPTION_MAX

Constant OPTION_MAX of type int

OPTION_MIN: int = OPTION_MIN

Constant OPTION_MIN of type int

ROW_ORIENTED: int = ROW_ORIENTED

Constant ROW_ORIENTED of type int

SORTED_FULL: int = SORTED_FULL

Constant SORTED_FULL of type int

SPD: int = SPD

Constant SPD of type int

STRUCTURALLY_SYMMETRIC: int = STRUCTURALLY_SYMMETRIC

Constant STRUCTURALLY_SYMMETRIC of type int

STRUCTURE_ONLY: int = STRUCTURE_ONLY

Constant STRUCTURE_ONLY of type int

SUBMAT_SINGLEIS: int = SUBMAT_SINGLEIS

Constant SUBMAT_SINGLEIS of type int

SUBSET_OFF_PROC_ENTRIES: int = SUBSET_OFF_PROC_ENTRIES

Constant SUBSET_OFF_PROC_ENTRIES of type int

SYMMETRIC: int = SYMMETRIC

Constant SYMMETRIC of type int

SYMMETRY_ETERNAL: int = SYMMETRY_ETERNAL

Constant SYMMETRY_ETERNAL of type int

UNUSED_NONZERO_LOCATION_ERR: int =
UNUSED_NONZERO_LOCATION_ERR

Constant UNUSED_NONZERO_LOCATION_ERR of type int

USE_HASH_TABLE: int = USE_HASH_TABLE

Constant USE_HASH_TABLE of type int

USE_INODES: int = USE_INODES

Constant USE_INODES of type int

petsc4py.PETSc.Mat.OrderingType

class petsc4py.PETSc.Mat.OrderingType

Bases: object

Factored matrix ordering type.

SEE ALSO:

MatOrderingType

Attributes Summary

Image grohtml-288464-89.png

Attributes Documentation
AMD: str = AMD

Object AMD of type str

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

petsc4py.PETSc.Mat.SORType

class petsc4py.PETSc.Mat.SORType

Bases: object

Matrix SOR type.

SEE ALSO:

MatSORType

Attributes Summary

Image grohtml-288464-90.png

Attributes Documentation
APPLY_LOWER: int = APPLY_LOWER

Constant APPLY_LOWER of type int

APPLY_UPPER: int = APPLY_UPPER

Constant APPLY_UPPER of type int

BACKWARD_SWEEP: int = BACKWARD_SWEEP

Constant BACKWARD_SWEEP of type int

EISENSTAT: int = EISENSTAT

Constant EISENSTAT of type int

FORWARD_SWEEP: int = FORWARD_SWEEP

Constant FORWARD_SWEEP of type int

LOCAL_BACKWARD_SWEEP: int = LOCAL_BACKWARD_SWEEP

Constant LOCAL_BACKWARD_SWEEP of type int

LOCAL_FORWARD_SWEEP: int = LOCAL_FORWARD_SWEEP

Constant LOCAL_FORWARD_SWEEP of type int

LOCAL_SYMMETRIC_SWEEP: int = LOCAL_SYMMETRIC_SWEEP

Constant LOCAL_SYMMETRIC_SWEEP of type int

SYMMETRY_SWEEP: int = SYMMETRY_SWEEP

Constant SYMMETRY_SWEEP of type int

ZERO_INITIAL_GUESS: int = ZERO_INITIAL_GUESS

Constant ZERO_INITIAL_GUESS of type int

petsc4py.PETSc.Mat.SolverType

class petsc4py.PETSc.Mat.SolverType

Bases: object

Factored matrix solver type.

SEE ALSO:

MatSolverType

Attributes Summary

Image grohtml-288464-91.png

Attributes Documentation
BAS: str = BAS

Object BAS of type str

CHOLMOD: str = CHOLMOD

Object CHOLMOD of type str

CUDA: str = CUDA

Object CUDA of type str

CUSPARSE: str = CUSPARSE

Object CUSPARSE of type str

ELEMENTAL: str = ELEMENTAL

Object ELEMENTAL of type str

ESSL: str = ESSL

Object ESSL of type str

KLU: str = KLU

Object KLU of type str

LUSOL: str = LUSOL

Object LUSOL of type str

MATLAB: str = MATLAB

Object MATLAB of type str

MKL_CPARDISO: str = MKL_CPARDISO

Object MKL_CPARDISO of type str

MKL_PARDISO: str = MKL_PARDISO

Object MKL_PARDISO of type str

MUMPS: str = MUMPS

Object MUMPS of type str

PASTIX: str = PASTIX

Object PASTIX of type str

PETSC: str = PETSC

Object PETSC of type str

SCALAPACK: str = SCALAPACK

Object SCALAPACK of type str

SPQR: str = SPQR

Object SPQR of type str

STRUMPACK: str = STRUMPACK

Object STRUMPACK of type str

SUPERLU: str = SUPERLU

Object SUPERLU of type str

SUPERLU_DIST: str = SUPERLU_DIST

Object SUPERLU_DIST of type str

UMFPACK: str = UMFPACK

Object UMFPACK of type str

petsc4py.PETSc.Mat.Stencil

class petsc4py.PETSc.Mat.Stencil

Bases: object

Associate structured grid coordinates with matrix indices.

SEE ALSO:

MatStencil

Attributes Summary

Image grohtml-288464-92.png

Attributes Documentation

Field component.

Source code at petsc4py/PETSc/Mat.pyx:317

field

Field component.

Source code at petsc4py/PETSc/Mat.pyx:336

First logical grid coordinate.

Source code at petsc4py/PETSc/Mat.pyx:293

index

Logical grid coordinates (i, j, k) .

Source code at petsc4py/PETSc/Mat.pyx:325

Second logical grid coordinate.

Source code at petsc4py/PETSc/Mat.pyx:301

Third logical grid coordinate.

Source code at petsc4py/PETSc/Mat.pyx:309

petsc4py.PETSc.Mat.Structure

class petsc4py.PETSc.Mat.Structure

Bases: object

Matrix modification structure.

SEE ALSO:

MatStructure

Attributes Summary

Image grohtml-288464-93.png

Attributes Documentation
DIFFERENT: int = DIFFERENT

Constant DIFFERENT of type int

DIFFERENT_NONZERO_PATTERN: int =
DIFFERENT_NONZERO_PATTERN

Constant DIFFERENT_NONZERO_PATTERN of type int

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

petsc4py.PETSc.Mat.Type

class petsc4py.PETSc.Mat.Type

Bases: object

Matrix type.

SEE ALSO:

MatType

Attributes Summary

Image grohtml-288464-94.png

Attributes Documentation
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

AIJSELL: str = AIJSELL

Object AIJSELL of type str

AIJVIENNACL: str = AIJVIENNACL

Object AIJVIENNACL of type str

BAIJ: str = BAIJ

Object BAIJ of type str

BAIJMKL: str = BAIJMKL

Object BAIJMKL of type str

BLOCKMAT: str = BLOCKMAT

Object BLOCKMAT of type str

COMPOSITE: str = COMPOSITE

Object COMPOSITE of type str

CONSTANTDIAGONAL: str = CONSTANTDIAGONAL

Object CONSTANTDIAGONAL of type str

DENSE: str = DENSE

Object DENSE of type str

DENSECUDA: str = DENSECUDA

Object DENSECUDA of type str

DIAGONAL: str = DIAGONAL

Object DIAGONAL of type str

DUMMY: str = DUMMY

Object DUMMY of type str

ELEMENTAL: str = ELEMENTAL

Object ELEMENTAL of type str

FFT: str = FFT

Object FFT of type str

FFTW: str = FFTW

Object FFTW of type str

H2OPUS: str = H2OPUS

Object H2OPUS of type str

HERMITIANTRANSPOSE: str = HERMITIANTRANSPOSE

Object HERMITIANTRANSPOSE of type str

HYPRE: str = HYPRE

Object HYPRE of type str

HYPRESSTRUCT: str = HYPRESSTRUCT

Object HYPRESSTRUCT of type str

HYPRESTRUCT: str = HYPRESTRUCT

Object HYPRESTRUCT of type str

IS: str = IS

Object IS of type str

KAIJ: str = KAIJ

Object KAIJ of type str

LMVM: str = LMVM

Object LMVM of type str

LMVMBADBROYDEN: str = LMVMBADBROYDEN

Object LMVMBADBROYDEN of type str

LMVMBFGS: str = LMVMBFGS

Object LMVMBFGS of type str

LMVMBROYDEN: str = LMVMBROYDEN

Object LMVMBROYDEN of type str

LMVMDBFGS: str = LMVMDBFGS

Object LMVMDBFGS of type str

LMVMDDFP: str = LMVMDDFP

Object LMVMDDFP of type str

LMVMDFP: str = LMVMDFP

Object LMVMDFP of type str

LMVMDIAGBBROYDEN: str = LMVMDIAGBBROYDEN

Object LMVMDIAGBBROYDEN of type str

LMVMDQN: str = LMVMDQN

Object LMVMDQN of type str

LMVMSR1: str = LMVMSR1

Object LMVMSR1 of type str

LMVMSYMBADBROYDEN: str = LMVMSYMBADBROYDEN

Object LMVMSYMBADBROYDEN of type str

LMVMSYMBROYDEN: str = LMVMSYMBROYDEN

Object LMVMSYMBROYDEN of type str

LOCALREF: str = LOCALREF

Object LOCALREF of type str

LRC: str = LRC

Object LRC of type str

MAIJ: str = MAIJ

Object MAIJ of type str

MFFD: str = MFFD

Object MFFD of type str

MPIADJ: str = MPIADJ

Object MPIADJ of type str

MPIAIJ: str = MPIAIJ

Object MPIAIJ of type str

MPIAIJCRL: str = MPIAIJCRL

Object MPIAIJCRL of type str

MPIAIJCUSPARSE: str = MPIAIJCUSPARSE

Object MPIAIJCUSPARSE of type str

MPIAIJMKL: str = MPIAIJMKL

Object MPIAIJMKL of type str

MPIAIJPERM: str = MPIAIJPERM

Object 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

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

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

Methods Summary

Image grohtml-288464-95.png

Attributes Summary

Image grohtml-288464-96.png

Methods Documentation
H2OpusCompress(tol)

Compress a hierarchical matrix.

Collective.
Parameters

tol ( float ) -- The absolute truncation threshold.

Return type

Self

SEE ALSO:

MatH2OpusCompress

Source code at petsc4py/PETSc/Mat.pyx:4992

H2OpusLowRankUpdate(U, V=None, s=1.0)

Perform a low-rank update of the form self += sUVᵀ.

Collective.
Parameters

	•		U ( Mat ) -- The dense low-rank update matrix.
	•		V ( Mat \| None ) -- The dense low-rank update matrix. If None , V = U .
	•		s ( float ) -- The scaling factor.

Return type

Self

SEE ALSO:

MatH2OpusLowRankUpdate

Source code at petsc4py/PETSc/Mat.pyx:5011

H2OpusOrthogonalize()

Orthogonalize the basis tree of a hierarchical matrix.

Collective.

SEE ALSO:

MatH2OpusOrthogonalize

Source code at petsc4py/PETSc/Mat.pyx:4979
Return type

Self

SOR(b, x, omega=1.0, sortype=None, shift=0.0, its=1, lits=1)

Compute relaxation (SOR, Gauss-Seidel) sweeps.

Neighborwise collective.

SEE ALSO:

MatSOR

Source code at petsc4py/PETSc/Mat.pyx:3825
Parameters

	•		b ( Vec )
	•		x ( Vec )
	•		omega ( float )
	•		sortype ( SORType \| None )
	•		shift ( float )
	•		its ( int )
	•		lits ( int )

Return type

None

appendOptionsPrefix(prefix=None)

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

Logically collective.

SEE ALSO:

Working with PETSc options , setOptionsPrefix , - MatAppendOptionsPrefix

Source code at petsc4py/PETSc/Mat.pyx:1751
Parameters

prefix ( str | None )

Return type

None

assemble(assembly=None)

Assemble the matrix.

Collective.
Parameters

assembly ( MatAssemblySpec ) -- The assembly type.

Return type

None

SEE ALSO:

assemblyBegin , assemblyEnd

Source code at petsc4py/PETSc/Mat.pyx:3338

assemblyBegin(assembly=None)

Begin an assembling stage of the matrix.

Collective.
Parameters

assembly ( MatAssemblySpec ) -- The assembly type.

Return type

None

SEE ALSO:

assemblyEnd , assemble , MatAssemblyBegin

Source code at petsc4py/PETSc/Mat.pyx:3302

assemblyEnd(assembly=None)

Complete an assembling stage of the matrix initiated with assemblyBegin .

Collective.
Parameters

assembly ( MatAssemblySpec ) -- The assembly type.

Return type

None

SEE ALSO:

assemblyBegin , assemble , MatAssemblyEnd

Source code at petsc4py/PETSc/Mat.pyx:3320

axpy(alpha, X, structure=None)

Perform the matrix summation self + = ɑ·X.

Collective.
Parameters

	•		alpha ( Scalar ) -- The scalar.
	•		X ( Mat ) -- The matrix to be added.
	•		structure ( Structure ) -- The structure of the operation.

Return type

None

SEE ALSO:

MatAXPY

Source code at petsc4py/PETSc/Mat.pyx:4153

aypx(alpha, X, structure=None)

Perform the matrix summation self = ɑ· self + X.

Collective.
Parameters

	•		alpha ( Scalar ) -- The scalar.
	•		X ( Mat ) -- The matrix to be added.
	•		structure ( Structure ) -- The structure of the operation.

Return type

None

SEE ALSO:

MatAYPX

Source code at petsc4py/PETSc/Mat.pyx:4176

bindToCPU(flg)

Mark a matrix to temporarily stay on the CPU.

Collective.

Once marked, perform computations on the CPU.
Parameters

flg ( bool ) -- Bind to the CPU if True .

Return type

None

SEE ALSO:

MatBindToCPU

Source code at petsc4py/PETSc/Mat.pyx:4520

boundToCPU()

Query if a matrix is bound to the CPU.

Not collective.

SEE ALSO:

MatBoundToCPU

Source code at petsc4py/PETSc/Mat.pyx:4540
Return type

bool

chop(tol)

Set entries smallest of tol (in absolute values) to zero.

Collective.

SEE ALSO:

MatFilter

Source code at petsc4py/PETSc/Mat.pyx:4121
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

Source code at petsc4py/PETSc/Mat.pyx:2215

convert(mat_type=None, out=None)

Convert the matrix type.

Collective.
Parameters

	•		mat_type ( Type \| str ) -- 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

Source code at petsc4py/PETSc/Mat.pyx:2071

copy(result=None, structure=None)

Return a copy of the matrix.

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 , MatDuplicate

Source code at petsc4py/PETSc/Mat.pyx:2026

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

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

Return type

Self

SEE ALSO:

destroy , MatCreate

Source code at petsc4py/PETSc/Mat.pyx:488

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 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 ( CSRIndicesSpec \| None ) -- Optional compressed sparse row layout information. If provided, it takes precedence on nnz .
	•		comm ( Comm \| None ) -- MPI communicator, defaults to Sys.getDefaultComm .

Return type

Self

SEE ALSO:

setSizes , createBAIJ , MATAIJ , MATSEQAIJ , MATMPIAIJ , - MatCreateAIJ , MatSeqAIJSetPreallocation , - MatSeqAIJSetPreallocationCSR

Source code at petsc4py/PETSc/Mat.pyx:693

createAIJCRL(size, bsize=None, nnz=None, csr=None, comm=None)

Create a sparse Type.AIJCRL matrix.

Collective.

This is similar to Type.AIJ matrices but stores some additional information that improves vectorization for the matrix-vector product.

	•		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 ( CSRIndicesSpec \| None ) -- Optional compressed sparse row layout information. If provided, it takes precedence on nnz .
	•		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:826

createAIJWithArrays(size, csr, bsize=None, comm=None)

Create a sparse Type.AIJ matrix with data 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 None , a block size of 1 is set.
	•		comm ( Comm \| None ) -- MPI communicator, defaults to Sys.getDefaultComm .

Return type

Self

Notes

For Type.SEQAIJ matrices, the csr data is not copied. For Type.MPIAIJ matrices, the csr data is not copied only in the case it represents on-process and off-process information.

SEE ALSO:

createAIJ , MatCreateSeqAIJWithArrays , - MatCreateMPIAIJWithArrays , - MatCreateMPIAIJWithSplitArrays

Source code at petsc4py/PETSc/Mat.pyx:956

createBAIJ(size, bsize, nnz=None, csr=None, comm=None)

Create a sparse blocked Type.BAIJ matrix, optionally preallocating.

Collective.

	•		size ( MatSizeSpec ) -- Matrix size.
	•		bsize ( MatBlockSizeSpec ) -- Matrix block size.
	•		nnz ( NNZSpec \| None ) -- Optional non-zeros preallocation pattern for block rows.
	•		csr ( CSRIndicesSpec \| None ) -- Optional block-compressed sparse row layout information. If provided, it takes precedence on 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:738

createConstantDiagonal(size, diag, comm=None)

Create a diagonal matrix of type Type.CONSTANTDIAGONAL .

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

createDense(size, bsize=None, array=None, comm=None)

Create a Type.DENSE matrix.

Collective.
Parameters

	•		size ( MatSizeSpec ) -- Matrix size.
	•		bsize ( MatBlockSizeSpec \| None ) -- Matrix block size. If None , a block size of 1 is set.
	•		array ( Sequence[Scalar] \| None ) -- Optional matrix data. If None , memory is internally allocated.
	•		comm ( Comm \| None ) -- MPI communicator, defaults to Sys.getDefaultComm .

Return type

Self

SEE ALSO:

createDenseCUDA , MATDENSE , MatCreateDense

Source code at petsc4py/PETSc/Mat.pyx:1047

createDenseCUDA(size, bsize=None, array=None, cudahandle=None,
comm=None)

Create a Type.DENSECUDA matrix with optional host and device data.

Collective.
Parameters

	•		size ( MatSizeSpec ) -- Matrix size.
	•		bsize ( MatBlockSizeSpec \| None ) -- Matrix block size. If None , a block size of 1 is set.
	•		array ( Sequence[Scalar] \| None ) -- Host data. Will be lazily allocated if None .
	•		cudahandle ( int \| None ) -- Address of the array on the GPU. Will be lazily allocated if None . If cudahandle is provided, array will be ignored.
	•		comm ( Comm \| None ) -- MPI communicator, defaults to Sys.getDefaultComm .

Return type

Self

SEE ALSO:

createDense , MatCreateDenseCUDA

Source code at petsc4py/PETSc/Mat.pyx:1083

createDiagonal(diag)

Create a diagonal matrix of type Type.DIAGONAL .

Collective.
Parameters

diag ( Vec ) -- The vector holding diagonal values.

Return type

Self

SEE ALSO:

createConstantDiagonal

Source code at petsc4py/PETSc/Mat.pyx:1594

createH2OpusFromMat(A, coordinates=None, dist=None, eta=None,
leafsize=None, maxrank=None, bs=None, rtol=None)

Create a hierarchical Type.H2OPUS matrix sampling from a provided operator.

Collective.
Parameters

	•		A ( Mat ) -- Matrix to be sampled.
	•		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.

SEE ALSO:

Working with PETSc options , MatCreateH2OpusFromMat

Source code at petsc4py/PETSc/Mat.pyx:1427

createHermitianTranspose(mat)

Create a Type.HERMITIANTRANSPOSE matrix that behaves like (A*)ᵀ.

Collective.
Parameters

mat ( Mat ) -- Matrix A to represent the hermitian transpose of.

Return type

Self

Notes

The Hermitian transpose is never actually formed.

SEE ALSO:

createNormal , createNormalHermitian , - MATHERMITIANTRANSPOSEVIRTUAL , - MatCreateHermitianTranspose

Source code at petsc4py/PETSc/Mat.pyx:1263

createIS(size, bsize=None, lgmapr=None, lgmapc=None, comm=None)

Create a Type.IS matrix representing globally unassembled operators.

Collective.
Parameters

	•		size ( MatSizeSpec ) -- Matrix size.
	•		bsize ( MatBlockSizeSpec \| None ) -- Matrix block size. If None , a block size of 1 is set.
	•		lgmapr ( LGMap \| None ) -- Optional local-to-global mapping for the rows. If None , the local row space matches the global row space.
	•		lgmapc ( LGMap \| None ) -- Optional local-to-global mapping for the columns. If - None , the local column space matches the global column space.
	•		comm ( Comm \| None ) -- MPI communicator, defaults to Sys.getDefaultComm .

Return type

Self

SEE ALSO:

MATIS

Source code at petsc4py/PETSc/Mat.pyx:1508

createLRC(A, U, c, V)

Create a low-rank correction Type.LRC matrix representing A + UCVᵀ.

Collective.
Parameters

	•		A ( Mat ) -- Sparse matrix, can be None .
	•		U ( Mat ) -- Dense rectangular matrices.
	•		V ( Mat ) -- Dense rectangular matrices.
	•		c ( Vec ) -- Vector containing the diagonal of C, can be None .

Return type

Self

Notes

The matrix A + UCVᵀ is never actually formed.

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 V=None ) for a symmetric low-rank correction, A + UCUᵀ.

If c is None then the low-rank correction is just U*Vᵀ. If a sequential c vector is used for a parallel matrix, PETSc assumes that the values of the vector are consistently set across processors.

SEE ALSO:

MATLRC , MatCreateLRC

Source code at petsc4py/PETSc/Mat.pyx:1288

createNest(mats, isrows=None, iscols=None, comm=None)

Create a Type.NEST matrix containing multiple submatrices.

Collective.
Parameters

	•		mats ( Sequence[Sequence[Mat]] ) -- Iterable of matrix block rows with size len(isrows) . Each matrix block row must be of size len(iscols) . 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:1360

createNormal(mat)

Create a Type.NORMAL matrix representing AᵀA.

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ᵀ are used during mult and various other matrix operations.

SEE ALSO:

MATNORMAL , MatCreateNormal

Source code at petsc4py/PETSc/Mat.pyx:1188

createNormalHermitian(mat)

Create a Type.NORMALHERMITIAN matrix representing (A*)ᵀA.

Collective.
Parameters

mat ( Mat ) -- The (possibly rectangular) matrix A.

Return type

Self

Notes

The product (A*)ᵀA is never actually formed.

SEE ALSO:

createHermitianTranspose , MATNORMAL , - MATNORMALHERMITIAN , MatCreateNormalHermitian

Source code at petsc4py/PETSc/Mat.pyx:1238

createPython(size, context=None, comm=None)

Create a Type.PYTHON matrix.

Collective.
Parameters

	•		size ( MatSizeSpec ) -- Matrix size.
	•		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 matrix type , setType , setPythonContext , Type.PYTHON

Source code at petsc4py/PETSc/Mat.pyx:1617

createSBAIJ(size, bsize, nnz=None, csr=None, comm=None)

Create a sparse Type.SBAIJ matrix in symmetric block format.

Collective.

	•		size ( MatSizeSpec ) -- Matrix size.
	•		bsize ( MatBlockSizeSpec ) -- Matrix block size.
	•		nnz ( NNZSpec \| None ) -- Optional upper-triangular (including diagonal) non-zeros preallocation pattern for block rows.
	•		csr ( CSRIndicesSpec \| None ) -- Optional block-compressed sparse row layout information. If provided, it takes precedence on nnz .
	•		comm ( Comm \| None ) -- MPI communicator, defaults to Sys.getDefaultComm .

Return type

Self

SEE ALSO:

createAIJ , createBAIJ , MatCreateSBAIJ

Source code at petsc4py/PETSc/Mat.pyx:782

createScatter(scatter, comm=None)

Create a Type.SCATTER matrix from a vector scatter.

Collective.
Parameters

	•		scatter ( Scatter ) -- Vector scatter.
	•		comm ( Comm \| None ) -- MPI communicator, defaults to Sys.getDefaultComm .

Return type

Self

SEE ALSO:

MATSCATTER , MatCreateScatter

Source code at petsc4py/PETSc/Mat.pyx:1164

createSchurComplement(A00, Ap00, A01, A10, A11=None)

Create a Type.SCHURCOMPLEMENT matrix.

Collective.
Parameters

	•		A00 ( Mat ) -- the upper-left block of the original matrix A = [A00 A01; A10 A11].
	•		Ap00 ( Mat ) -- preconditioning matrix for use in ksp(A00,Ap00) to approximate the action of A00ˆ{-1}.
	•		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 ) -- Optional lower-right block of the original matrix A = [A00 A01; A10 A11].

Return type

Self

SEE ALSO:

MatCreateSchurComplement

Source code at petsc4py/PETSc/Mat.pyx:3969

createSubMatrices(isrows, iscols=None, submats=None)

Return several sequential submatrices.

Collective.
Parameters

	•		isrows ( IS \| Sequence[IS] ) -- Row index sets.
	•		iscols ( IS \| Sequence[IS] ) -- Column index sets. If None , iscols = isrows .
	•		submats ( Mat \| Sequence[Mat] ) -- Optional resultant matrices. When None , new matrices are created, and MAT_INITIAL_MATRIX is used. When not None , the matrices are reused with MAT_REUSE_MATRIX .

Return type

Sequence [ Mat ]

SEE ALSO:

MatCreateSubMatrices

Source code at petsc4py/PETSc/Mat.pyx:3912

createSubMatrix(isrow, iscol=None, submat=None)

Return a submatrix.

Collective.
Parameters

	•		isrow ( IS ) -- Row index set.
	•		iscol ( IS \| None ) -- Column index set. If None , iscol = isrow .
	•		submat ( Mat \| None ) -- Optional resultant matrix. When None , a new matrix is created, and MAT_INITIAL_MATRIX is used. When not None , the matrix is reused with MAT_REUSE_MATRIX .

Return type

Mat

SEE ALSO:

MatCreateSubMatrix

Source code at petsc4py/PETSc/Mat.pyx:3882

createSubMatrixVirtual(A, isrow, iscol=None)

Create a Type.SUBMATRIX matrix that acts as a submatrix.

Collective.
Parameters

	•		A ( Mat ) -- Matrix to extract submatrix from.
	•		isrow ( IS ) -- Rows present in the submatrix.
	•		iscol ( IS \| None ) -- Columns present in the submatrix, defaults to isrow .

Return type

Self

SEE ALSO:

MatCreateSubMatrixVirtual

Source code at petsc4py/PETSc/Mat.pyx:1335

createTranspose(mat)

Create a Type.TRANSPOSE matrix that behaves like Aᵀ.

Collective.
Parameters

mat ( Mat ) -- 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.

SEE ALSO:

createNormal , MatCreateTranspose

Source code at petsc4py/PETSc/Mat.pyx:1213

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:3438
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:3424
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 - None returns a 2-tuple of vectors (right, left) . Otherwise it just return a left or right vector.

Return type

Vec | tuple [ Vec , Vec ]

Notes

right vectors are vectors in the column space of the matrix. left vectors are vectors in the row space of the matrix.

SEE ALSO:

createVecLeft , createVecRight , MatCreateVecs

Source code at petsc4py/PETSc/Mat.pyx:3385

destroy()

Destroy the matrix.

Collective.

SEE ALSO:

create , MatDestroy

Source code at petsc4py/PETSc/Mat.pyx:475
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:3577

duplicate(copy=False)

Return a clone of the matrix.

Collective.
Parameters

copy ( bool ) -- If True , it also copies the values.

Return type

Mat

SEE ALSO:

MatDuplicate

Source code at petsc4py/PETSc/Mat.pyx:2004

equal(mat)

Return the result of matrix comparison.

Collective.

SEE ALSO:

MatEqual

Source code at petsc4py/PETSc/Mat.pyx:2259
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:4684

factorICC(isperm, options=None)

Perform an in-place an incomplete 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:

factorILU , MatICCFactor

Source code at petsc4py/PETSc/Mat.pyx:4717

factorILU(isrow, iscol, options=None)

Perform 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

Source code at petsc4py/PETSc/Mat.pyx:4650

factorLU(isrow, iscol, options=None)

Perform 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

Source code at petsc4py/PETSc/Mat.pyx:4612

factorNumericCholesky(mat, options=None)

Not implemented.

Source code at petsc4py/PETSc/Mat.pyx:4713
Parameters

mat ( Mat )

Return type

None

factorNumericLU(mat, options=None)

Not implemented.

Source code at petsc4py/PETSc/Mat.pyx:4646
Parameters

mat ( Mat )

Return type

None

factorSymbolicCholesky(isperm, options=None)

Not implemented.

Source code at petsc4py/PETSc/Mat.pyx:4709
Parameters

isperm ( IS )

Return type

None

factorSymbolicICC(isperm, options=None)

Not implemented.

Source code at petsc4py/PETSc/Mat.pyx:4742
Parameters

isperm ( IS )

Return type

None

factorSymbolicILU(isrow, iscol, options=None)

Not implemented.

Source code at petsc4py/PETSc/Mat.pyx:4680
Parameters

	•		isrow ( IS )
	•		iscol ( IS )

Return type

None

factorSymbolicLU(mat, isrow, iscol, options=None)

Not implemented.

Source code at petsc4py/PETSc/Mat.pyx:4642
Parameters

	•		mat ( Mat )
	•		isrow ( IS )
	•		iscol ( IS )

Return type

None

findZeroRows()

Return the index set of empty rows.

Collective.

SEE ALSO:

MatFindZeroRows

Source code at petsc4py/PETSc/Mat.pyx:3371
Return type

fixISLocalEmpty(fix=True)

Compress out zero local rows from the local matrices.

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

Source code at petsc4py/PETSc/Mat.pyx:4817

getBlockSize()

Return the matrix block size.

Not collective.

SEE ALSO:

getBlockSize , MatGetBlockSize

Source code at petsc4py/PETSc/Mat.pyx:1874
Return type

int

getBlockSizes()

Return the row and column block sizes.

Not collective.

SEE ALSO:

getBlockSize , MatGetBlockSizes

Source code at petsc4py/PETSc/Mat.pyx:1888
Return type

tuple [ int , int ]

getColumnIJ(symmetric=False, compressed=False)

Return the CSC representation of the local sparsity pattern.

Collective.
Parameters

	•		symmetric ( bool ) -- If True , return the symmetrized graph.
	•		compressed ( bool ) -- If True , return the compressed graph.

Return type

tuple [ ArrayInt , ArrayInt ]

SEE ALSO:

MatGetRowIJ

Source code at petsc4py/PETSc/Mat.pyx:2518

getColumnVector(column, result=None)

Return the columnᵗʰ column vector of the matrix.

Collective.
Parameters

	•		column ( int ) -- Column index.
	•		result ( Vec \| None ) -- Optional vector to store the result.

Return type

Vec

SEE ALSO:

MatGetColumnVector

Source code at petsc4py/PETSc/Mat.pyx:3458

getDM()

Return the DM defining the data layout of the matrix.

Not collective.

SEE ALSO:

MatGetDM

Source code at petsc4py/PETSc/Mat.pyx:5570
Return type

getDenseArray(readonly=False)

Return the array where the data is stored.

Not collective.
Parameters

readonly ( bool ) -- Enable to obtain a read only array.

Return type

ArrayScalar

SEE ALSO:

MatDenseGetArrayRead , MatDenseGetArray

Source code at petsc4py/PETSc/Mat.pyx:5375

getDenseColumnVec(i, mode='rw')

Return the iᵗʰ column vector of the dense matrix.

Collective.
Parameters

	•		i ( int ) -- The column index to access.
	•		mode ( AccessModeSpec ) -- The access type of the returned array

Return type

Vec

SEE ALSO:

restoreDenseColumnVec , MatDenseGetColumnVec , - MatDenseGetColumnVecRead , MatDenseGetColumnVecWrite

Source code at petsc4py/PETSc/Mat.pyx:5428

getDenseLDA()

Return the leading dimension of the array used by the dense matrix.

Not collective.

SEE ALSO:

MatDenseGetLDA

Source code at petsc4py/PETSc/Mat.pyx:5361
Return type

int

getDenseLocalMatrix()

Return the local part of the dense matrix.

Not collective.

SEE ALSO:

MatDenseGetLocalMatrix

Source code at petsc4py/PETSc/Mat.pyx:5413
Return type

Mat

getDiagonal(result=None)

Return the diagonal of the matrix.

Collective.
Parameters

result ( Vec | None ) -- Optional vector to store the result.

Return type

Vec

SEE ALSO:

setDiagonal , MatGetDiagonal

Source code at petsc4py/PETSc/Mat.pyx:3513

getDiagonalBlock()

Return the part of the matrix associated with the on-process coupling.

Not collective.

SEE ALSO:

MatGetDiagonalBlock

Source code at petsc4py/PETSc/Mat.pyx:3854
Return type

Mat

getISAllowRepeated()

Get the flag for repeated entries in the local to global map.

Not collective.

SEE ALSO:

setISAllowRepeated , MatISGetAllowRepeated

Source code at petsc4py/PETSc/Mat.pyx:4803
Return type

bool

getISLocalMat()

Return the local matrix stored inside a Type.IS matrix.

Not collective.

SEE ALSO:

MatISGetLocalMat

Source code at petsc4py/PETSc/Mat.pyx:4836
Return type

Mat

getInertia()

Return the inertia from a factored matrix.

Collective.

The matrix must have been factored by calling factorCholesky .
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

Source code at petsc4py/PETSc/Mat.pyx:4746

getInfo(info=None)

Return summary information.

Collective.
Parameters

info ( InfoType ) -- If None , it uses InfoType.GLOBAL_SUM .

Return type

dict [ str , float ]

SEE ALSO:

MatInfo , MatGetInfo

Source code at petsc4py/PETSc/Mat.pyx:1984

getLGMap()

Return the local-to-global mappings.

Not collective.

SEE ALSO:

setLGMap , MatGetLocalToGlobalMapping

Source code at petsc4py/PETSc/Mat.pyx:2784
Return type

tuple [ LGMap , LGMap ]

getLRCMats()

Return the constituents of a Type.LRC matrix.

Not collective.
Returns

	•		A ( Mat ) -- The A matrix.
	•		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

Source code at petsc4py/PETSc/Mat.pyx:4918

getLocalSize()

Return the local number of rows and columns.

Not collective.

SEE ALSO:

getSize , MatGetLocalSize

Source code at petsc4py/PETSc/Mat.pyx:1844
Return type

tuple [ int , int ]

getLocalSubMatrix(isrow, iscol, submat=None)

Return a reference to a submatrix specified in local numbering.

Collective.
Parameters

	•		isrow ( IS ) -- Row index set.
	•		iscol ( IS ) -- Column index set.
	•		submat ( Mat \| None ) -- Optional resultant matrix. When None , a new matrix is created. When not None , the matrix is first destroyed and then recreated.

Return type

Mat

SEE ALSO:

restoreLocalSubMatrix , MatGetLocalSubMatrix

Source code at petsc4py/PETSc/Mat.pyx:4024

getMumpsCntl(icntl)

Return the MUMPS parameter, CNTL[icntl] .

Logically collective.

SEE ALSO:

Working with PETSc options , MatMumpsGetCntl

Source code at petsc4py/PETSc/Mat.pyx:5096
Parameters

icntl ( int )

Return type

float

getMumpsIcntl(icntl)

Return the MUMPS parameter, ICNTL[icntl] .

Logically collective.

SEE ALSO:

Working with PETSc options , MatMumpsGetIcntl

Source code at petsc4py/PETSc/Mat.pyx:5060
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

Source code at petsc4py/PETSc/Mat.pyx:5111

getMumpsInfog(icntl)

Return the MUMPS parameter, INFOG[icntl] .

Logically collective.
Parameters

icntl ( int ) -- The index of the MUMPS INFOG array.

Return type

int

SEE ALSO:

MatMumpsGetInfog

Source code at petsc4py/PETSc/Mat.pyx:5131

getMumpsRinfo(icntl)

Return the MUMPS parameter, RINFO[icntl] .

Logically collective.
Parameters

icntl ( int ) -- The index of the MUMPS RINFO array.

Return type

float

SEE ALSO:

MatMumpsGetRinfo

Source code at petsc4py/PETSc/Mat.pyx:5151

getMumpsRinfog(icntl)

Return the MUMPS parameter, RINFOG[icntl] .

Logically collective.
Parameters

icntl ( int ) -- The index of the MUMPS RINFOG array.

Return type

float

SEE ALSO:

MatMumpsGetRinfog

Source code at petsc4py/PETSc/Mat.pyx:5171

getNearNullSpace()

Return the near-nullspace.

Not collective.

SEE ALSO:

getNullSpace , setNearNullSpace , MatSetNearNullSpace

Source code at petsc4py/PETSc/Mat.pyx:3686
Return type

NullSpace

getNestISs()

Return the index sets representing the row and column spaces.

Not collective.

SEE ALSO:

MatNestGetISs

Source code at petsc4py/PETSc/Mat.pyx:5502
Return type

tuple [ list [ IS ], list [ IS ]]

getNestLocalISs()

Return the local index sets representing the row and column spaces.

Not collective.

SEE ALSO:

MatNestGetLocalISs

Source code at petsc4py/PETSc/Mat.pyx:5523
Return type

tuple [ list [ IS ], list [ IS ]]

getNestSize()

Return the number of rows and columns of the matrix.

Not collective.

SEE ALSO:

MatNestGetSize

Source code at petsc4py/PETSc/Mat.pyx:5488
Return type

tuple [ int , int ]

getNestSubMatrix(i, j)

Return a single submatrix.

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

getNullSpace()

Return the nullspace.

Not collective.

SEE ALSO:

setNullSpace , MatGetNullSpace

Source code at petsc4py/PETSc/Mat.pyx:3632
Return type

NullSpace

getOption(option)

Return the option value.

Not collective.

SEE ALSO:

setOption , MatGetOption

Source code at petsc4py/PETSc/Mat.pyx:1802
Parameters

option ( Option )

Return type

bool

getOptionsPrefix()

Return the prefix used for searching for options in the database.

Not collective.

SEE ALSO:

Working with PETSc options , setOptionsPrefix , - MatGetOptionsPrefix

Source code at petsc4py/PETSc/Mat.pyx:1737
Return type

str

getOrdering(ord_type)

Return a reordering for a matrix to improve a LU factorization.

Collective.
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:4556

getOwnershipIS()

Return the ranges of rows and columns owned by each process as index sets.

Not collective.

SEE ALSO:

getOwnershipRanges , getOwnershipRangesColumn , - MatGetOwnershipIS

Source code at petsc4py/PETSc/Mat.pyx:1969
Return type

tuple [ IS , IS ]

getOwnershipRange()

Return the locally owned range of rows.

Not collective.

SEE ALSO:

getOwnershipRanges , getOwnershipRangeColumn , - MatGetOwnershipRange

Source code at petsc4py/PETSc/Mat.pyx:1902
Return type

tuple [ int , int ]

getOwnershipRangeColumn()

Return the locally owned range of columns.

Not collective.

SEE ALSO:

getOwnershipRangesColumn , getOwnershipRange , - MatGetOwnershipRangeColumn

Source code at petsc4py/PETSc/Mat.pyx:1936
Return type

tuple [ int , int ]

getOwnershipRanges()

Return the range of rows owned by each process.

Not collective.

The returned array is the result of exclusive scan of the local sizes.

SEE ALSO:

getOwnershipRange , MatGetOwnershipRanges

Source code at petsc4py/PETSc/Mat.pyx:1916
Return type

ArrayInt

getOwnershipRangesColumn()

Return the range of columns owned by each process.

Not collective.

SEE ALSO:

getOwnershipRangeColumn , MatGetOwnershipRangesColumn

Source code at petsc4py/PETSc/Mat.pyx:1951
Return type

ArrayInt

getPythonContext()

Return the instance of the class implementing the required Python methods.

Not collective.

SEE ALSO:

PETSc Python matrix type , setPythonContext

Source code at petsc4py/PETSc/Mat.pyx:1671
Return type

Any

getPythonType()

Return the fully qualified Python name of the class used by the matrix.

Not collective.

SEE ALSO:

PETSc Python matrix type , setPythonContext , setPythonType , MatPythonGetType

Source code at petsc4py/PETSc/Mat.pyx:1706
Return type

str

getRedundantMatrix(nsubcomm, subcomm=None, out=None)

Return redundant matrices on subcommunicators.

Collective.
Parameters

	•		nsubcomm ( int ) -- The number of subcommunicators.
	•		subcomm ( Comm \| None ) -- Communicator split or - None for the null communicator.
	•		out ( Mat \| None ) -- Optional resultant matrix. When None , a new matrix is created, and MAT_INITIAL_MATRIX is used. When not None , the matrix is reused with MAT_REUSE_MATRIX .

Return type

Mat

SEE ALSO:

MatCreateRedundantMatrix

Source code at petsc4py/PETSc/Mat.pyx:3483

getRow(row)

Return the column indices and values for the requested row.

Not collective.

SEE ALSO:

MatGetRow

Source code at petsc4py/PETSc/Mat.pyx:2467
Parameters

row ( int )

Return type

tuple [ ArrayInt , ArrayScalar ]

getRowIJ(symmetric=False, compressed=False)

Return the CSR representation of the local sparsity pattern.

Collective.
Parameters

	•		symmetric ( bool ) -- If True , return the symmetrized graph.
	•		compressed ( bool ) -- If True , return the compressed graph.

Return type

tuple [ ArrayInt , ArrayInt ]

SEE ALSO:

MatGetRowIJ

Source code at petsc4py/PETSc/Mat.pyx:2487

getRowSum(result=None)

Return the row-sum vector.

Collective.
Parameters

result ( Vec | None ) -- Optional vector to store the result.

Return type

Vec

SEE ALSO:

MatGetRowSum

Source code at petsc4py/PETSc/Mat.pyx:3535

getSchurComplementSubMatrices()

Return Schur complement sub-matrices.

Collective.

SEE ALSO:

MatSchurComplementGetSubMatrices

Source code at petsc4py/PETSc/Mat.pyx:4003
Return type

tuple [ Mat , Mat , Mat , Mat , Mat ]

getSize()

Return the global number of rows and columns.

Not collective.

SEE ALSO:

getLocalSize , getSizes , MatGetSize

Source code at petsc4py/PETSc/Mat.pyx:1830
Return type

tuple [ int , int ]

getSizes()

Return the tuple of matrix layouts.

Not collective.

SEE ALSO:

getLocalSize , getSize

Source code at petsc4py/PETSc/Mat.pyx:1858
Return type

tuple [ LayoutSizeSpec , LayoutSizeSpec ]

getTransposeNullSpace()

Return the transpose nullspace.

Not collective.

SEE ALSO:

getNullSpace , setTransposeNullSpace , - MatGetTransposeNullSpace

Source code at petsc4py/PETSc/Mat.pyx:3659
Return type

NullSpace

getType()

Return the type of the matrix.

Not collective.

SEE ALSO:

setType , Type , MatGetType

Source code at petsc4py/PETSc/Mat.pyx:1816
Return type

str

getValue(row, col)

Return the value in the (row, col) position.

Not collective.

SEE ALSO:

MatGetValues

Source code at petsc4py/PETSc/Mat.pyx:2392
Return type

Scalar

getValues(rows, cols, values=None)

Return the values in the zip(rows, cols) positions.

Not collective.
Parameters

	•		rows ( Sequence[int] ) -- Row indices.
	•		cols ( Sequence[int] ) -- Column indices.
	•		values ( ArrayScalar ) -- Optional array where to store the values.

Return type

ArrayScalar

SEE ALSO:

MatGetValues

Source code at petsc4py/PETSc/Mat.pyx:2408

getValuesCSR()

Return the CSR representation of the local part of the matrix.

Not collective.

SEE ALSO:

MatGetRow

Source code at petsc4py/PETSc/Mat.pyx:2429
Return type

tuple [ ArrayInt , ArrayInt , ArrayScalar ]

getVecType()

Return the vector type used by the matrix.

Not collective.

SEE ALSO:

setVecType , MatGetVecType

Source code at petsc4py/PETSc/Mat.pyx:658
Return type

str

hermitianTranspose(out=None)

Return the transposed Hermitian matrix.

Collective.
Parameters

out ( Mat | None ) -- Optional return matrix. If - None , inplace transposition is performed. Otherwise, the matrix is reused.

Return type

Mat

SEE ALSO:

MatHermitianTranspose

Source code at petsc4py/PETSc/Mat.pyx:2142

imagPart(out=None)

Return the imaginary part of the 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 , conjugate , MatImaginaryPart

Source code at petsc4py/PETSc/Mat.pyx:2192

increaseOverlap(iset, overlap=1)

Increase the overlap of a index set.

Collective.

SEE ALSO:

MatIncreaseOverlap

Source code at petsc4py/PETSc/Mat.pyx:3869
Parameters

	•		iset ( IS )
	•		overlap ( int )

Return type

None

invertBlockDiagonal()

Return the inverse of the block-diagonal entries.

Collective.

SEE ALSO:

MatInvertBlockDiagonal

Source code at petsc4py/PETSc/Mat.pyx:3599
Return type

ArrayScalar

isAssembled()

The boolean flag indicating if the matrix is assembled.

Not collective.

SEE ALSO:

assemble , MatAssembled

Source code at petsc4py/PETSc/Mat.pyx:3357
Return type

bool

isHermitian(tol=0)

Return the boolean indicating if the matrix is Hermitian.

Collective.
Parameters

tol ( float ) -- Tolerance for comparison.

Return type

bool

SEE ALSO:

MatIsHermitian

Source code at petsc4py/PETSc/Mat.pyx:2331

isHermitianKnown()

Return the 2-tuple indicating if the matrix is known to be Hermitian.

Not collective.

SEE ALSO:

MatIsHermitianKnown

Source code at petsc4py/PETSc/Mat.pyx:2351
Return type

tuple [ bool , bool ]

isStructurallySymmetric()

Return the boolean indicating if the matrix is structurally symmetric.

Not collective.

SEE ALSO:

MatIsStructurallySymmetric

Source code at petsc4py/PETSc/Mat.pyx:2366
Return type

bool

isSymmetric(tol=0)

Return the boolean indicating if the matrix is symmetric.

Collective.
Parameters

tol ( float ) -- Tolerance for comparison.

Return type

bool

SEE ALSO:

MatIsSymmetric

Source code at petsc4py/PETSc/Mat.pyx:2296

isSymmetricKnown()

Return the 2-tuple indicating if the matrix is known to be symmetric.

Not collective.

SEE ALSO:

MatIsSymmetricKnown

Source code at petsc4py/PETSc/Mat.pyx:2316
Return type

tuple [ bool , bool ]

isTranspose(mat=None, tol=0)

Return the result of matrix comparison with transposition.

Collective.
Parameters

	•		mat ( Mat \| None ) -- Matrix to compare against. Uses self if None .
	•		tol ( float ) -- Tolerance for comparison.

Return type

bool

SEE ALSO:

MatIsTranspose

Source code at petsc4py/PETSc/Mat.pyx:2273

kron(mat, result=None)

Compute C, the Kronecker product of A and B.

Collective.
Parameters

	•		mat ( Mat ) -- The right hand matrix B.
	•		result ( Mat \| None ) -- The optional resultant matrix. When None , a new matrix is created, and MAT_INITIAL_MATRIX is used. When it is not None , the matrix is reused with MAT_REUSE_MATRIX .

Returns

result -- The resultant matrix C, the Kronecker product of A and B.

Return type

Mat

SEE ALSO:

MatSeqAIJKron , MatReuse

Source code at petsc4py/PETSc/Mat.pyx:4485

load(viewer)

Load a matrix.

Collective.

SEE ALSO:

MatLoad

Source code at petsc4py/PETSc/Mat.pyx:2053
Parameters

viewer ( Viewer )

Return type

Self

matMatMult(B, C, result=None, fill=None)

Perform matrix-matrix-matrix multiplication D=ABC.

Neighborwise collective.
Parameters

	•		B ( Mat ) -- The middle matrix B.
	•		C ( Mat ) -- The right hand matrix C.
	•		result ( Mat \| None ) -- The optional resultant matrix D. When 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 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:4440

matMult(mat, result=None, fill=None)

Perform matrix-matrix multiplication C=AB.

Neighborwise collective.
Parameters

	•		mat ( Mat ) -- The right hand matrix B.
	•		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) + 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.

SEE ALSO:

MatMatMult , MatReuse

Source code at petsc4py/PETSc/Mat.pyx:4201

matSolve(B, X)

Solve 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, must be different than B .

Return type

None

SEE ALSO:

KSP.create , MatMatSolve

Source code at petsc4py/PETSc/Mat.pyx:5321

matTransposeMult(mat, result=None, fill=None)

Perform matrix-matrix multiplication C=ABᵀ.

Neighborwise collective.
Parameters

	•		mat ( Mat ) -- The right hand matrix B.
	•		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) + 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.

SEE ALSO:

MatMatTransposeMult , MatReuse

Source code at petsc4py/PETSc/Mat.pyx:4248

mult(x, y)

Perform the matrix vector product y = A @ x.

Collective.
Parameters

	•		x ( Vec ) -- The input vector.
	•		y ( Vec ) -- The output vector.

Return type

None

SEE ALSO:

MatMult

Source code at petsc4py/PETSc/Mat.pyx:3703

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

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

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

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

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

norm(norm_type=None)

Compute the requested matrix norm.

Collective.

A 2-tuple is returned if NormType.NORM_1_AND_2 is specified.

SEE ALSO:

MatNorm , NormType

Source code at petsc4py/PETSc/Mat.pyx:4073
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:2238

preallocatorPreallocate(A, fill=True)

Preallocate memory for a matrix using a preallocator matrix.

Collective.

The current matrix ( self ) must be of type Type.PREALLOCATOR .
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 .

Return type

None

SEE ALSO:

MatPreallocatorPreallocate

Source code at petsc4py/PETSc/Mat.pyx:933

ptap(P, result=None, fill=None)

Creates the matrix product C = PᵀAP.

Neighborwise collective.
Parameters

	•		P ( Mat ) -- The matrix P.
	•		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) + nnz(P)), 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.

An alternative approach to this function is to use - MatProductCreate and set the desired options before the computation is done.

SEE ALSO:

MatPtAP , MatReuse

Source code at petsc4py/PETSc/Mat.pyx:4342

rart(R, result=None, fill=None)

Create the matrix product C = RARᵀ.

Neighborwise collective.
Parameters

	•		R ( Mat ) -- The projection matrix.
	•		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), 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.

SEE ALSO:

MatRARt , MatReuse

Source code at petsc4py/PETSc/Mat.pyx:4393

realPart(out=None)

Return the real part of the 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:

imagPart , conjugate , MatRealPart

Source code at petsc4py/PETSc/Mat.pyx:2169

reorderForNonzeroDiagonal(isrow, iscol, atol=0)

Change a matrix ordering to remove zeros from the diagonal.

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.

Return type

None

SEE ALSO:

getOrdering , MatReorderForNonzeroDiagonal

Source code at petsc4py/PETSc/Mat.pyx:4584

restoreDenseColumnVec(i, mode='rw')

Restore the iᵗʰ column vector of the dense matrix.

Collective.
Parameters

	•		i ( int ) -- The column index to be restored.
	•		mode ( AccessModeSpec ) -- The access type of the restored array

Return type

None

SEE ALSO:

getDenseColumnVec , MatDenseRestoreColumnVec , - MatDenseRestoreColumnVecRead , - MatDenseRestoreColumnVecWrite

Source code at petsc4py/PETSc/Mat.pyx:5460

restoreISLocalMat(local)

Restore the local matrix obtained with getISLocalMat .

Not collective.
Parameters

local ( Mat ) -- The local matrix.

Return type

None

SEE ALSO:

MatISRestoreLocalMat

Source code at petsc4py/PETSc/Mat.pyx:4851

restoreLocalSubMatrix(isrow, iscol, submat)

Restore a reference to a submatrix obtained with getLocalSubMatrix .

Collective.
Parameters

	•		isrow ( IS ) -- Row index set.
	•		iscol ( IS ) -- Column index set.
	•		submat ( Mat ) -- The submatrix.

Return type

None

SEE ALSO:

getLocalSubMatrix , MatRestoreLocalSubMatrix

Source code at petsc4py/PETSc/Mat.pyx:4050

retrieveValues()

Retrieve a copy of the matrix values previously stored with storeValues .

Collective.

SEE ALSO:

storeValues , MatRetrieveValues

Source code at petsc4py/PETSc/Mat.pyx:3290
Return type

None

scale(alpha)

Scale the matrix.

Collective.

SEE ALSO:

MatScale

Source code at petsc4py/PETSc/Mat.pyx:4095
Parameters

alpha ( Scalar )

Return type

None

setBlockSize(bsize)

Set the matrix block size (same for rows and columns).

Logically collective.
Parameters

bsize ( int ) -- Block size.

Return type

None

SEE ALSO:

setBlockSizes , setSizes , MatSetBlockSize

Source code at petsc4py/PETSc/Mat.pyx:586

setBlockSizes(row_bsize, col_bsize)

Set the row and column block sizes.

Logically collective.
Parameters

	•		row_bsize ( int ) -- Row block size.
	•		col_bsize ( int ) -- Column block size.

Return type

None

SEE ALSO:

setBlockSize , setSizes , MatSetBlockSizes

Source code at petsc4py/PETSc/Mat.pyx:604

setDM(dm)

Set the DM defining the data layout of the matrix.

Not collective.
Parameters

dm ( DM ) -- The DM .

Return type

None

SEE ALSO:

MatSetDM

Source code at petsc4py/PETSc/Mat.pyx:5587

setDenseLDA(lda)

Set the leading dimension of the array used by the dense matrix.

Not collective.
Parameters

lda ( int ) -- The leading dimension.

Return type

None

SEE ALSO:

MatDenseSetLDA

Source code at petsc4py/PETSc/Mat.pyx:5343

setDiagonal(diag, addv=None)

Set the diagonal values of the matrix.

Collective.
Parameters

	•		diag ( Vec ) -- Vector storing diagonal values.
	•		addv ( InsertModeSpec ) -- Insertion mode.

Return type

None

SEE ALSO:

getDiagonal , MatDiagonalSet

Source code at petsc4py/PETSc/Mat.pyx:3557

setFromOptions()

Configure the matrix from the options database.

Collective.

SEE ALSO:

Working with PETSc options , MatSetFromOptions

Source code at petsc4py/PETSc/Mat.pyx:1765
Return type

None

setISAllowRepeated(allow=True)

Allow repeated entries in the local to global map.

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

Source code at petsc4py/PETSc/Mat.pyx:4785

setISLocalMat(local)

Set the local matrix stored inside a Type.IS .

Not collective.
Parameters

local ( Mat ) -- The local matrix.

Return type

None

SEE ALSO:

MatISSetLocalMat

Source code at petsc4py/PETSc/Mat.pyx:4868

setISPreallocation(nnz, onnz)

Preallocate memory for a Type.IS parallel matrix.

Collective.
Parameters

	•		nnz ( Sequence[int] ) -- The sequence whose length corresponds to the number of local rows and values which 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 values which represent the number of nonzeros in the various rows of the off-diagonal of the local submatrix.

Return type

Self

SEE ALSO:

MatISSetPreallocation

Source code at petsc4py/PETSc/Mat.pyx:4885

setLGMap(rmap, cmap=None)

Set the local-to-global mappings.

Collective.
Parameters

	•		rmap ( LGMap ) -- Row mapping.
	•		cmap ( LGMap \| None ) -- Column mapping. If None , cmap = rmap .

Return type

None

SEE ALSO:

getLGMap , MatSetLocalToGlobalMapping

Source code at petsc4py/PETSc/Mat.pyx:2764

setLRCMats(A, U, c=None, V=None)

Set the constituents of a Type.LRC matrix.

Logically collective.
Parameters

	•		A ( Mat ) -- The A matrix, or None to omit A .
	•		U ( Mat ) -- The first dense rectangular matrix.
	•		c ( Vec ) -- The sequential vector containing the diagonal of C , or None for all ones.
	•		V ( Mat ) -- The second dense rectangular matrix, or None for a copy of U .

Return type

None

SEE ALSO:

MatLRCSetMats

Source code at petsc4py/PETSc/Mat.pyx:4950

setMumpsCntl(icntl, val)

Set a MUMPS parameter, CNTL[icntl] = val .

Logically collective.
Parameters

	•		icntl ( int ) -- The index of the MUMPS parameter array.
	•		val ( float ) -- The value to set.

Return type

None

SEE ALSO:

Working with PETSc options , MatMumpsSetCntl

Source code at petsc4py/PETSc/Mat.pyx:5075

setMumpsIcntl(icntl, ival)

Set a MUMPS parameter, ICNTL[icntl] = ival .

Logically collective.
Parameters

	•		icntl ( int ) -- The index of the MUMPS parameter array.
	•		ival ( int ) -- The value to set.

Return type

None

SEE ALSO:

Working with PETSc options , MatMumpsSetIcntl

Source code at petsc4py/PETSc/Mat.pyx:5039

setNearNullSpace(nsp)

Set the near-nullspace.

Collective.

SEE ALSO:

setNullSpace , getNearNullSpace , MatSetNearNullSpace

Source code at petsc4py/PETSc/Mat.pyx:3674
Parameters

nsp ( NullSpace )

Return type

None

setNestVecType(vec_type)

Set the vector type for a Type.NEST matrix.

Collective.
Parameters

vec_type ( Type | str ) -- Vector type used when creating vectors with createVecs .

Return type

None

SEE ALSO:

getVecType , MatNestSetVecType

Source code at petsc4py/PETSc/Mat.pyx:672

setNullSpace(nsp)

Set the nullspace.

Collective.

SEE ALSO:

getNullSpace , MatSetNullSpace

Source code at petsc4py/PETSc/Mat.pyx:3620
Parameters

nsp ( NullSpace )

Return type

None

setOption(option, flag)

Set option.

Collective.

SEE ALSO:

getOption , MatSetOption

Source code at petsc4py/PETSc/Mat.pyx:1790
Parameters

	•		option ( Option )
	•		flag ( bool )

Return type

None

setOptionsPrefix(prefix=None)

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

Logically collective.

SEE ALSO:

Working with PETSc options , getOptionsPrefix , - MatSetOptionsPrefix

Source code at petsc4py/PETSc/Mat.pyx:1723
Parameters

prefix ( str | None )

Return type

None

setPreallocationCSR(csr)

Preallocate memory for the matrix with a CSR layout.

Collective.

Correct preallocation can result in a dramatic reduction in matrix assembly time.
Parameters

csr ( CSRIndicesSpec ) -- Local matrix data in compressed sparse row layout format.

Return type

Self

Notes

Must use the block-compressed form with Type.BAIJ and Type.SBAIJ .

SEE ALSO:

setPreallocationNNZ , createAIJ , createBAIJ , createSBAIJ , MatSeqAIJSetPreallocationCSR , - MatMPIAIJSetPreallocationCSR , - MatSeqBAIJSetPreallocationCSR , - MatMPIBAIJSetPreallocationCSR , - MatSeqSBAIJSetPreallocationCSR , - MatMPISBAIJSetPreallocationCSR

Source code at petsc4py/PETSc/Mat.pyx:899

setPreallocationDense(array)

Set the array used for storing matrix elements for a dense matrix.

Collective.
Parameters

array ( Sequence[Scalar] ) -- Array that will be used to store matrix data.

Return type

Self

SEE ALSO:

MatSeqDenseSetPreallocation , - MatMPIDenseSetPreallocation

Source code at petsc4py/PETSc/Mat.pyx:1140

setPreallocationNNZ(nnz)

Preallocate memory for the matrix with a non-zero pattern.

Collective.

Correct preallocation can result in a dramatic reduction in matrix assembly time.
Parameters

nnz ( NNZSpec ) -- The number of non-zeros per row for the local portion of the matrix, or a 2-tuple for the on-process and off-process part of the matrix.

Return type

Self

SEE ALSO:

setPreallocationCSR , createAIJ , - MatSeqAIJSetPreallocation , MatMPIAIJSetPreallocation

Source code at petsc4py/PETSc/Mat.pyx:873

setPythonContext(context)

Set the instance of the class implementing the required Python methods.

Logically collective.

Notes

In order to use the matrix, Mat.setUp must be called after having set the context. Pass None to reset the matrix to its initial state.

SEE ALSO:

PETSc Python matrix type , getPythonContext , setPythonType

Source code at petsc4py/PETSc/Mat.pyx:1654
Parameters

context ( Any )

Return type

None

setPythonType(py_type)

Set the fully qualified Python name of the class to be used.

Collective.

Notes

In order to use the matrix, Mat.setUp must be called after having set the type.

SEE ALSO:

PETSc Python matrix type , setPythonContext , getPythonType , MatPythonSetType

Source code at petsc4py/PETSc/Mat.pyx:1686
Parameters

py_type ( str )

Return type

None

setRandom(random=None)

Set random values in the matrix.

Collective.
Parameters

random ( Random | None ) -- The random number generator object or None for the default.

Return type

None

SEE ALSO:

MatSetRandom

Source code at petsc4py/PETSc/Mat.pyx:4134

setSizes(size, bsize=None)

Set the local, global and block sizes.

Collective.
Parameters

	•		size ( MatSizeSpec ) -- Matrix size.
	•		bsize ( MatBlockSizeSpec \| None ) -- Matrix block size. If None , a block size of 1 is set.

Return type

None

Examples

Create a Mat with n rows and columns and the same local and global sizes.

>>> mat = PETSc.Mat().create()
>>> mat.setFromOptions()
>>> mat.setSizes(n)

Create a Mat with nr rows, nc columns and the same local and global sizes.

>>> mat = PETSc.Mat().create()
>>> mat.setFromOptions()
>>> mat.setSizes([nr, nc])

Create a Mat with nrl local rows, nrg global rows, ncl local columns and ncg global columns.

>>> mat = PETSc.Mat().create()
>>> mat.setFromOptions()
>>> mat.setSizes([[nrl, nrg], [ncl, ncg]])

SEE ALSO:

setBlockSize , setBlockSizes , MatSetSizes , - MatSetBlockSize , MatSetBlockSizes

Source code at petsc4py/PETSc/Mat.pyx:533

setStencil(dims, starts=None, dof=1)

Set matrix stencil.

Not collective.

SEE ALSO:

MatSetStencil

Source code at petsc4py/PETSc/Mat.pyx:3022
Parameters

	•		dims ( DimsSpec )
	•		starts ( DimsSpec \| None )
	•		dof ( int )

Return type

None

setTransposeNullSpace(nsp)

Set the transpose nullspace.

Collective.

SEE ALSO:

setNullSpace , getTransposeNullSpace , - MatSetTransposeNullSpace

Source code at petsc4py/PETSc/Mat.pyx:3647
Parameters

nsp ( NullSpace )

Return type

None

setTransposePrecursor(out)

Set transpose precursor.

Logically collective.

SEE ALSO:

MatTransposeSetPrecursor

Source code at petsc4py/PETSc/Mat.pyx:2130
Parameters

out ( Mat )

Return type

None

setType(mat_type)

Set the matrix type.

Collective.
Parameters

mat_type ( Type | str ) -- The matrix type.

Return type

None

SEE ALSO:

create , getType , MatSetType

Source code at petsc4py/PETSc/Mat.pyx:514

setUnfactored()

Set a factored matrix to be treated as unfactored.

Logically collective.

SEE ALSO:

MatSetUnfactored

Source code at petsc4py/PETSc/Mat.pyx:4771
Return type

None

setUp()

Set up the internal data structures for using the matrix.

Collective.

SEE ALSO:

MatSetUp

Source code at petsc4py/PETSc/Mat.pyx:1777
Return type

Self

setValue(row, col, value, addv=None)

Set a value to the (row, col) entry of the matrix.

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

Source code at petsc4py/PETSc/Mat.pyx:2548

setValueBlockedStagStencil(row, col, value, addv=None)

Not implemented.

Source code at petsc4py/PETSc/Mat.pyx:3106
Return type

None

setValueBlockedStencil(row, col, value, addv=None)

Set a block of values to row and col stencil.

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

Source code at petsc4py/PETSc/Mat.pyx:3076

setValueLocal(row, col, value, addv=None)

Set a value to the (row, col) entry of the matrix in local ordering.

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

Source code at petsc4py/PETSc/Mat.pyx:2801

setValueStagStencil(row, col, value, addv=None)

Not implemented.

Source code at petsc4py/PETSc/Mat.pyx:3072
Return type

None

setValueStencil(row, col, value, addv=None)

Set a value to row and col stencil.

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

Source code at petsc4py/PETSc/Mat.pyx:3042

setValues(rows, cols, values, addv=None)

Set values to the rows ⊗ cols entries of the matrix.

Not collective.
Parameters

	•		rows ( Sequence[int] ) -- Row indices.
	•		cols ( Sequence[int] ) -- Column indices.
	•		values ( Sequence[Scalar] ) -- The scalar values. A sequence of length at least *len(rows) len(cols)** .
	•		addv ( InsertModeSpec ) -- Insertion mode.

Return type

None

SEE ALSO:

MatSetValues

Source code at petsc4py/PETSc/Mat.pyx:2580

setValuesBlocked(rows, cols, values, addv=None)

Set values to the rows ⊗ col block entries of the matrix.

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.
	•		addv ( InsertModeSpec ) -- Insertion mode.

Return type

None

SEE ALSO:

MatSetValuesBlocked

Source code at petsc4py/PETSc/Mat.pyx:2671

setValuesBlockedCSR(I, J, V, addv=None)

Set values stored in block CSR format.

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

Source code at petsc4py/PETSc/Mat.pyx:2736

setValuesBlockedIJV(I, J, V, addv=None, rowmap=None)

Set a subset of values stored in block CSR format.

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] ) -- Optional iterable indicating which block row to insert.

Return type

None

SEE ALSO:

MatSetValuesBlocked

Source code at petsc4py/PETSc/Mat.pyx:2705

setValuesBlockedLocal(rows, cols, values, addv=None)

Set values to the rows ⊗ col block entries of the matrix in local ordering.

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

Source code at petsc4py/PETSc/Mat.pyx:2925

setValuesBlockedLocalCSR(I, J, V, addv=None)

Set values stored in block CSR format.

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

Source code at petsc4py/PETSc/Mat.pyx:2990

setValuesBlockedLocalIJV(I, J, V, addv=None, rowmap=None)

Set a subset of values stored in block CSR format.

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.
	•		rowmap ( Sequence[int] ) -- Optional iterable indicating which block row to insert.

Return type

None

SEE ALSO:

MatSetValuesBlockedLocal

Source code at petsc4py/PETSc/Mat.pyx:2959

setValuesBlockedLocalRCV(R, C, V, addv=None)

Undocumented.

Source code at petsc4py/PETSc/Mat.pyx:2955
Return type

None

setValuesBlockedRCV(R, C, V, addv=None)

Undocumented.

Source code at petsc4py/PETSc/Mat.pyx:2701
Return type

None

setValuesCSR(I, J, V, addv=None)

Set values stored in CSR format.

Not collective.
Parameters

	•		I ( Sequence[int] ) -- Row pointers.
	•		J ( Sequence[int] ) -- Column indices.
	•		V ( Sequence[Scalar] ) -- The scalar values.
	•		addv ( InsertModeSpec ) -- Insertion mode.

Return type

None

SEE ALSO:

MatSetValues

Source code at petsc4py/PETSc/Mat.pyx:2643

setValuesIJV(I, J, V, addv=None, rowmap=None)

Set a subset of values stored in CSR format.

Not collective.
Parameters

	•		I ( Sequence[int] ) -- Row pointers.
	•		J ( Sequence[int] ) -- Column indices.
	•		V ( Sequence[Scalar] ) -- The scalar values.
	•		addv ( InsertModeSpec ) -- Insertion mode.
	•		rowmap ( Sequence[int] ) -- Optional iterable indicating which row to insert.

Return type

None

SEE ALSO:

MatSetValues

Source code at petsc4py/PETSc/Mat.pyx:2612

setValuesLocal(rows, cols, values, addv=None)

Set values to the rows ⊗ col entries of the matrix in local ordering.

Not collective.
Parameters

	•		rows ( Sequence[int] ) -- Local row indices.
	•		cols ( Sequence[int] ) -- Local column indices.
	•		values ( Sequence[Scalar] ) -- The scalar values. A sequence of length at least *len(rows) len(cols)** .
	•		addv ( InsertModeSpec ) -- Insertion mode.

Return type

None

SEE ALSO:

MatSetValuesLocal

Source code at petsc4py/PETSc/Mat.pyx:2834

setValuesLocalCSR(I, J, V, addv=None)

Set values stored in CSR format.

Not collective.
Parameters

	•		I ( Sequence[int] ) -- Row pointers.
	•		J ( Sequence[int] ) -- Local column indices.
	•		V ( Sequence[Scalar] ) -- The scalar values.
	•		addv ( InsertModeSpec ) -- Insertion mode.

Return type

None

SEE ALSO:

MatSetValuesLocal

Source code at petsc4py/PETSc/Mat.pyx:2897

setValuesLocalIJV(I, J, V, addv=None, rowmap=None)

Set a subset of values stored in CSR format.

Not collective.
Parameters

	•		I ( Sequence[int] ) -- Row pointers.
	•		J ( Sequence[int] ) -- Local column indices.
	•		V ( Sequence[Scalar] ) -- The scalar values.
	•		addv ( InsertModeSpec ) -- Insertion mode.
	•		rowmap ( Sequence[int] ) -- Optional iterable indicating which row to insert.

Return type

None

SEE ALSO:

MatSetValuesLocal

Source code at petsc4py/PETSc/Mat.pyx:2866

setValuesLocalRCV(R, C, V, addv=None)

Undocumented.

Source code at petsc4py/PETSc/Mat.pyx:2862
Return type

None

setValuesRCV(R, C, V, addv=None)

Undocumented.

Source code at petsc4py/PETSc/Mat.pyx:2608
Return type

None

setVariableBlockSizes(blocks)

Set diagonal point-blocks of the matrix.

Not collective.

SEE ALSO:

setBlockSize , MatSetVariableBlockSizes

Source code at petsc4py/PETSc/Mat.pyx:625
Parameters

blocks ( Sequence[int] )

Return type

None

setVecType(vec_type)

Set the vector type.

Collective.
Parameters

vec_type ( Type | str ) -- Vector type used when creating vectors with createVecs .

Return type

None

SEE ALSO:

getVecType , MatSetVecType

Source code at petsc4py/PETSc/Mat.pyx:639

shift(alpha)

Shift the matrix.

Collective.

SEE ALSO:

MatShift

Source code at petsc4py/PETSc/Mat.pyx:4108
Parameters

alpha ( Scalar )

Return type

None

solve(b, x)

Solve Ax=b, given a factored matrix.

Neighborwise collective.

The vectors b and x cannot be the same. Most users should employ the KSP interface for linear solvers instead of working directly with matrix algebra routines.
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 at petsc4py/PETSc/Mat.pyx:5231

solveAdd(b, y, x)

Solve x=y+A⁻¹b, given a factored matrix.

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 at petsc4py/PETSc/Mat.pyx:5275

solveBackward(b, x)

Solve Ux=b, given a factored matrix A=LU.

Neighborwise collective.
Parameters

	•		b ( Vec ) -- The right-hand side vector.
	•		x ( Vec ) -- The output solution vector.

Return type

None

SEE ALSO:

MatBackwardSolve

Source code at petsc4py/PETSc/Mat.pyx:5212

solveForward(b, x)

Solve Lx = b, given a factored matrix A = LU.

Neighborwise collective.
Parameters

	•		b ( Vec ) -- The right-hand side vector.
	•		x ( Vec ) -- The output solution vector.

Return type

None

SEE ALSO:

MatForwardSolve

Source code at petsc4py/PETSc/Mat.pyx:5193

solveTranspose(b, x)

Solve Aᵀx=b, given a factored matrix.

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 at petsc4py/PETSc/Mat.pyx:5254

solveTransposeAdd(b, y, x)

Solve x=y+A⁻ᵀb, given a factored matrix.

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 at petsc4py/PETSc/Mat.pyx:5298

storeValues()

Stash a copy of the matrix values.

Collective.

SEE ALSO:

retrieveValues , MatStoreValues

Source code at petsc4py/PETSc/Mat.pyx:3278
Return type

None

toDLPack(mode='rw')

Return a DLPack PyCapsule wrapping the vector data.

Source code at petsc4py/PETSc/Mat.pyx:5675
Parameters

mode ( AccessModeSpec )

Return type

Any

transpose(out=None)

Return the transposed matrix.

Collective.
Parameters

out ( Mat | None ) -- Optional return matrix. If - None , inplace transposition is performed. Otherwise, the matrix is reused.

Return type

Mat

SEE ALSO:

MatTranspose

Source code at petsc4py/PETSc/Mat.pyx:2103

transposeMatMult(mat, result=None, fill=None)

Perform matrix-matrix multiplication C=AᵀB.

Neighborwise collective.
Parameters

	•		mat ( Mat ) -- The right hand matrix B.
	•		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) + 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.

SEE ALSO:

MatTransposeMatMult , MatReuse

Source code at petsc4py/PETSc/Mat.pyx:4295

view(viewer=None)

View the matrix.

Collective.
Parameters

viewer ( Viewer | None ) -- A Viewer instance or - None for the default viewer.

Return type

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 .

SEE ALSO:

load , Viewer , MatView

Source code at petsc4py/PETSc/Mat.pyx:450

zeroEntries()

Zero the entries of the matrix.

Collective.

SEE ALSO:

MatZeroEntries

Source code at petsc4py/PETSc/Mat.pyx:2380
Return type

None

zeroRows(rows, diag=1, x=None, b=None)

Zero selected rows of the matrix.

Collective.
Parameters

	•		rows ( IS \| Sequence[int] ) -- 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:

zeroRowsLocal , MatZeroRows , MatZeroRowsIS

Source code at petsc4py/PETSc/Mat.pyx:3110

zeroRowsColumns(rows, diag=1, x=None, b=None)

Zero selected rows and columns of the matrix.

Collective.
Parameters

	•		rows ( IS \| Sequence[int] ) -- 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:

zeroRowsColumnsLocal , zeroRows , MatZeroRowsColumns , - MatZeroRowsColumnsIS

Source code at petsc4py/PETSc/Mat.pyx:3176

zeroRowsColumnsLocal(rows, diag=1, x=None, b=None)

Zero selected rows and columns of the matrix in local ordering.

Collective.
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:

zeroRowsLocal , zeroRowsColumns , - MatZeroRowsColumnsLocal , MatZeroRowsColumnsLocalIS

Source code at petsc4py/PETSc/Mat.pyx:3210

zeroRowsColumnsStencil(rows, diag=1, x=None, b=None)

Zero selected rows and columns of the matrix.

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:

zeroRowsLocal , zeroRowsColumns , - MatZeroRowsColumnsStencil

Source code at petsc4py/PETSc/Mat.pyx:3244

zeroRowsLocal(rows, diag=1, x=None, b=None)

Zero selected rows of the matrix in local ordering.

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:

zeroRows , MatZeroRowsLocal , MatZeroRowsLocalIS

Source code at petsc4py/PETSc/Mat.pyx:3143

Attributes Documentation
assembled

The boolean flag indicating if the matrix is assembled.

Source code at petsc4py/PETSc/Mat.pyx:5650

block_size

Matrix block size.

Source code at petsc4py/PETSc/Mat.pyx:5628

block_sizes

Matrix row and column block sizes.

Source code at petsc4py/PETSc/Mat.pyx:5633

hermitian

The boolean flag indicating if the matrix is Hermitian.

Source code at petsc4py/PETSc/Mat.pyx:5658

local_size

Matrix local size.

Source code at petsc4py/PETSc/Mat.pyx:5623

owner_range

Matrix local row range.

Source code at petsc4py/PETSc/Mat.pyx:5638

owner_ranges

Matrix row ranges.

Source code at petsc4py/PETSc/Mat.pyx:5643

size

Matrix global size.

Source code at petsc4py/PETSc/Mat.pyx:5618

sizes

Matrix local and global sizes.

Source code at petsc4py/PETSc/Mat.pyx:5610

structsymm

The boolean flag indicating if the matrix is structurally symmetric.

Source code at petsc4py/PETSc/Mat.pyx:5662

symmetric

The boolean flag indicating if the matrix is symmetric.

Source code at petsc4py/PETSc/Mat.pyx:5654

petsc4py.PETSc.MatPartitioning

class petsc4py.PETSc.MatPartitioning

Bases: Object

Object for managing the partitioning of a matrix or graph.

Enumerations

Image grohtml-288464-97.png

petsc4py.PETSc.MatPartitioning.Type

class petsc4py.PETSc.MatPartitioning.Type

Bases: object

The partitioning types.

Attributes Summary

Image grohtml-288464-98.png

Attributes Documentation
PARTITIONINGAVERAGE: str = PARTITIONINGAVERAGE

Object PARTITIONINGAVERAGE of type str

PARTITIONINGCHACO: str = PARTITIONINGCHACO

Object PARTITIONINGCHACO of type str

PARTITIONINGCURRENT: str = PARTITIONINGCURRENT

Object PARTITIONINGCURRENT of type str

PARTITIONINGHIERARCH: str = PARTITIONINGHIERARCH

Object PARTITIONINGHIERARCH of type str

PARTITIONINGPARMETIS: str = PARTITIONINGPARMETIS

Object PARTITIONINGPARMETIS of type str

PARTITIONINGPARTY: str = PARTITIONINGPARTY

Object PARTITIONINGPARTY of type str

PARTITIONINGPTSCOTCH: str = PARTITIONINGPTSCOTCH

Object PARTITIONINGPTSCOTCH of type str

PARTITIONINGSQUARE: str = PARTITIONINGSQUARE

Object PARTITIONINGSQUARE of type str

Methods Summary

Image grohtml-288464-99.png

Methods Documentation
apply(partitioning)

Return a partitioning for the graph represented by a sparse matrix.

Collective.

For each local node this tells the processor number that that node is assigned to.

SEE ALSO:

MatPartitioningApply

Source code at petsc4py/PETSc/MatPartitioning.pyx:144
Parameters

partitioning ( IS )

Return type

None

create(comm=None)

Create a partitioning context.

Collective.
Parameters

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

Return type

Self

SEE ALSO:

destroy , MatPartitioningCreate

Source code at petsc4py/PETSc/MatPartitioning.pyx:62

destroy()

Destroy the partitioning context.

Collective.

SEE ALSO:

create , MatPartitioningDestroy

Source code at petsc4py/PETSc/MatPartitioning.pyx:49
Return type

Self

getType()

Return the partitioning method.

Not collective.

SEE ALSO:

setType , MatPartitioningGetType

Source code at petsc4py/PETSc/MatPartitioning.pyx:100
Return type

str

setAdjacency(adj)

Set the adjacency graph (matrix) of the thing to be partitioned.

Collective.
Parameters

adj ( Mat ) -- The adjacency matrix, this can be any Mat.Type but the natural representation is Mat.Type.MPIADJ .

Return type

None

SEE ALSO:

MatPartitioningSetAdjacency

Source code at petsc4py/PETSc/MatPartitioning.pyx:126

setFromOptions()

Set parameters in the partitioner from the options database.

Collective.

SEE ALSO:

Working with PETSc options , - MatPartitioningSetFromOptions

Source code at petsc4py/PETSc/MatPartitioning.pyx:114
Return type

None

setType(matpartitioning_type)

Set the type of the partitioner to use.

Collective.
Parameters

matpartitioning_type ( Type | str ) -- The partitioner type.

Return type

None

SEE ALSO:

getType , MatPartitioningSetType

Source code at petsc4py/PETSc/MatPartitioning.pyx:81

view(viewer=None)

View the partitioning data structure.

Collective.
Parameters

viewer ( Viewer | None ) -- A Viewer to display the graph.

Return type

None

SEE ALSO:

MatPartitioningView

Source code at petsc4py/PETSc/MatPartitioning.pyx:29

petsc4py.PETSc.NormType

class petsc4py.PETSc.NormType

Bases: object

Norm type.

Commonly used norm types:

	N1		The one norm.
	N2		The two norm.

FROBENIUS

The Frobenius norm.

INFINITY

The infinity norm.

SEE ALSO:

NormType

Attributes Summary

Image grohtml-288464-100.png

Attributes Documentation
FRB: int = FRB

Constant FRB of type int

FROBENIUS: int = FROBENIUS

Constant FROBENIUS of type int

INF: int = INF

Constant INF of type int

INFINITY: int = INFINITY

Constant INFINITY of type int

MAX: int = MAX

Constant MAX of type int

N1: int = N1

Constant N1 of type int

N12: int = N12

Constant N12 of type int

N2: int = N2

Constant N2 of type int

NORM_1: int = NORM_1

Constant NORM_1 of type int

NORM_1_AND_2: int = NORM_1_AND_2

Constant NORM_1_AND_2 of type int

NORM_2: int = NORM_2

Constant NORM_2 of type int

NORM_FROBENIUS: int = NORM_FROBENIUS

Constant NORM_FROBENIUS of type int

NORM_INFINITY: int = NORM_INFINITY

Constant NORM_INFINITY of type int

NORM_MAX: int = NORM_MAX

Constant NORM_MAX of type int

petsc4py.PETSc.NullSpace

class petsc4py.PETSc.NullSpace

Bases: Object

Nullspace object.

SEE ALSO:

MatNullSpace

Methods Summary

Image grohtml-288464-101.png

Methods Documentation
create(constant=False, vectors=(), comm=None)

Create the null space.

Collective.
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:

destroy , MatNullSpaceCreate

Source code at petsc4py/PETSc/Mat.pyx:5799

createRigidBody(coords)

Create rigid body modes from coordinates.

Collective.
Parameters

coords ( Vec ) -- The block coordinates of each node. Requires the block size to have been set.

Return type

Self

SEE ALSO:

MatNullSpaceCreateRigidBody

Source code at petsc4py/PETSc/Mat.pyx:5835

destroy()

Destroy the null space.

Collective.

SEE ALSO:

create , MatNullSpaceDestroy

Source code at petsc4py/PETSc/Mat.pyx:5786
Return type

Self

getFunction()

Return the callback to remove the nullspace.

Not collective.

SEE ALSO:

setFunction

Source code at petsc4py/PETSc/Mat.pyx:5926
Return type

MatNullFunction

getVecs()

Return the vectors defining the null space.

Not collective.

SEE ALSO:

MatNullSpaceGetVecs

Source code at petsc4py/PETSc/Mat.pyx:5904
Return type

list [ Vec ]

hasConstant()

Return whether the null space contains the constant.

Not collective.

SEE ALSO:

MatNullSpaceGetVecs

Source code at petsc4py/PETSc/Mat.pyx:5890
Return type

bool

remove(vec)

Remove all components of a null space from a vector.

Collective.
Parameters

vec ( Vec ) -- The vector from which the null space is removed.

Return type

None

SEE ALSO:

MatNullSpaceRemove

Source code at petsc4py/PETSc/Mat.pyx:5940

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

Set the callback to remove the nullspace.

Logically collective.
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:

getFunction , MatNullSpaceSetFunction

Source code at petsc4py/PETSc/Mat.pyx:5856

test(mat)

Return if the claimed null space is valid for a matrix.

Collective.
Parameters

mat ( Mat ) -- The matrix to check.

Return type

bool

SEE ALSO:

MatNullSpaceTest

Source code at petsc4py/PETSc/Mat.pyx:5957

view(viewer=None)

View the null space.

Collective.
Parameters

viewer ( Viewer | None ) -- A Viewer instance or - None for the default viewer.

Return type

None

SEE ALSO:

Viewer , MatNullSpaceView

Source code at petsc4py/PETSc/Mat.pyx:5767

petsc4py.PETSc.Object

class petsc4py.PETSc.Object

Bases: object

Base class wrapping a PETSc object.

SEE ALSO:

PetscObject

Methods Summary

Image grohtml-288464-102.png

Attributes Summary

Image grohtml-288464-103.png

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

Source code at petsc4py/PETSc/Object.pyx:138
Parameters

prefix ( str | None )

Return type

None

compose(name, obj)

Associate a PETSc object using a key string.

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

Source code at petsc4py/PETSc/Object.pyx:329

decRef()

Decrement the object reference count.

Logically collective.

SEE ALSO:

getRefCount , PetscObjectDereference

Source code at petsc4py/PETSc/Object.pyx:389
Return type

int

destroy()

Destroy the object.

Collective.

SEE ALSO:

PetscObjectDestroy

Source code at petsc4py/PETSc/Object.pyx:81
Return type

Self

destroyOptionsHandlers()

Clear all the option handlers.

Collective.

SEE ALSO:

Working with PETSc options , setOptionsHandler , - PetscObjectDestroyOptionsHandlers

Source code at petsc4py/PETSc/Object.pyx:213
Return type

None

getAttr(name)

Return the attribute associated with a given name.

Not collective.

SEE ALSO:

setAttr , getDict

Source code at petsc4py/PETSc/Object.pyx:408
Parameters

name ( str )

Return type

object

getClassId()

Return the class identifier of the object.

Not collective.

SEE ALSO:

PetscObjectGetClassId

Source code at petsc4py/PETSc/Object.pyx:270
Return type

int

getClassName()

Return the class name of the object.

Not collective.

SEE ALSO:

PetscObjectGetClassName

Source code at petsc4py/PETSc/Object.pyx:284
Return type

str

getComm()

Return the communicator of the object.

Not collective.

SEE ALSO:

PetscObjectGetComm

Source code at petsc4py/PETSc/Object.pyx:228
Return type

Comm

getDict()

Return the dictionary of attributes.

Not collective.

SEE ALSO:

setAttr , getAttr

Source code at petsc4py/PETSc/Object.pyx:436
Return type

dict

getId()

Return the unique identifier of the object.

Not collective.

SEE ALSO:

PetscObjectGetId

Source code at petsc4py/PETSc/Object.pyx:313
Return type

int

getName()

Return the name of the object.

Not collective.

SEE ALSO:

PetscObjectGetName

Source code at petsc4py/PETSc/Object.pyx:242
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

Source code at petsc4py/PETSc/Object.pyx:124
Return type

str

getRefCount()

Return the reference count of the object.

Not collective.

SEE ALSO:

PetscObjectGetReference

Source code at petsc4py/PETSc/Object.pyx:298
Return type

int

getTabLevel()

Return the PETSc object tab level.

Not collective.

SEE ALSO:

setTabLevel , incrementTabLevel , PetscObjectGetTabLevel

Source code at petsc4py/PETSc/Object.pyx:518
Return type

None

getType()

Return the object type name.

Not collective.

SEE ALSO:

PetscObjectGetType

Source code at petsc4py/PETSc/Object.pyx:94
Return type

str

incRef()

Increment the object reference count.

Logically collective.

SEE ALSO:

getRefCount , PetscObjectReference

Source code at petsc4py/PETSc/Object.pyx:372
Return type

int

incrementTabLevel(tab, parent=None)

Increment the PETSc object tab level.

Logically collective.

SEE ALSO:

setTabLevel , getTabLevel , PetscObjectIncrementTabLevel

Source code at petsc4py/PETSc/Object.pyx:491
Parameters

	•		tab ( int )
	•		parent ( Object \| None )

Return type

None

query(name)

Query for the PETSc object associated with a key string.

Not collective.

SEE ALSO:

compose , PetscObjectQuery

Source code at petsc4py/PETSc/Object.pyx:352
Parameters

name ( str )

Return type

Object

setAttr(name, attr)

Set an the attribute associated with a given name.

Not collective.

SEE ALSO:

getAttr , getDict

Source code at petsc4py/PETSc/Object.pyx:422
Parameters

	•		name ( str )
	•		attr ( object )

Return type

None

setFromOptions()

Configure the object from the options database.

Collective.

Classes that do not implement setFromOptions use this method that, in turn, calls PetscObjectSetFromOptions .

SEE ALSO:

Working with PETSc options , PetscObjectSetFromOptions

Source code at petsc4py/PETSc/Object.pyx:152
Return type

None

setName(name)

Associate a name to the object.

Not collective.

SEE ALSO:

PetscObjectSetName

Source code at petsc4py/PETSc/Object.pyx:256
Parameters

name ( str | None )

Return type

None

setOptionsHandler(handler)

Set the callback for processing extra options.

Logically collective.
Parameters

handler ( PetscOptionsHandlerFunction | None ) -- The callback function, called at the end of a setFromOptions invocation for the given class.

Return type

None

SEE ALSO:

Working with PETSc options , Mat.setFromOptions , KSP.setFromOptions , PetscObjectAddOptionsHandler

Source code at petsc4py/PETSc/Object.pyx:190

setOptionsPrefix(prefix)

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

Logically collective.

SEE ALSO:

Working with PETSc options , getOptionsPrefix , - PetscObjectSetOptionsPrefix

Source code at petsc4py/PETSc/Object.pyx:110
Parameters

prefix ( str | None )

Return type

None

setTabLevel(level)

Set the PETSc object tab level.

Logically collective.

SEE ALSO:

incrementTabLevel , getTabLevel , PetscObjectSetTabLevel

Source code at petsc4py/PETSc/Object.pyx:505
Parameters

level ( int )

Return type

None

stateGet()

Return the PETSc object state.

Not collective.

SEE ALSO:

stateSet , stateIncrease , PetscObjectStateGet

Source code at petsc4py/PETSc/Object.pyx:462
Return type

int

stateIncrease()

Increment the PETSc object state.

Logically collective.

SEE ALSO:

stateGet , stateSet , PetscObjectStateIncrease

Source code at petsc4py/PETSc/Object.pyx:450
Return type

None

stateSet(state)

Set the PETSc object state.

Logically collective.

SEE ALSO:

stateIncrease , stateGet , PetscObjectStateSet

Source code at petsc4py/PETSc/Object.pyx:476
Parameters

state ( int )

Return type

None

view(viewer=None)

Display the object.

Collective.
Parameters

viewer ( Viewer | None ) -- A Viewer instance or - None for the default viewer.

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.

Collective.
Parameters

	•		name ( str ) -- The command line option.
	•		objpre ( Object \| None ) -- Optional object that provides prefix.

Return type

None

SEE ALSO:

Working with PETSc options , PetscObjectViewFromOptions

Source code at petsc4py/PETSc/Object.pyx:167

Attributes Documentation
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

The object identifier.

Source code at petsc4py/PETSc/Object.pyx:568

klass

The class name.

Source code at petsc4py/PETSc/Object.pyx:573

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

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

prefix ( str , optional ) -- Optional string to prepend to all the options.

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:

Working with PETSc options

Methods Summary

Image grohtml-288464-104.png

Attributes Summary

Image grohtml-288464-105.png

Methods Documentation
clear()

Clear an options database.

Source code at petsc4py/PETSc/Options.pyx:91
Return type

Self

create()

Create an options database.

Source code at petsc4py/PETSc/Options.pyx:79
Return type

Self

delValue(name)

Delete an option from the database.

Logically collective.

SEE ALSO:

setValue , PetscOptionsClearValue

Source code at petsc4py/PETSc/Options.pyx:195
Parameters

name ( str )

Return type

None

destroy()

Destroy an options database.

Source code at petsc4py/PETSc/Options.pyx:85
Return type

Self

getAll()

Return all the options and their values.

Not collective.

SEE ALSO:

PetscOptionsGetAll

Source code at petsc4py/PETSc/Options.pyx:414
Return type

dict [ str , str ]

getBool(name, default=None)

Return the boolean value associated with the option.

Not collective.
Parameters

	•		name ( str ) -- The option name.
	•		default -- The default value. If None , it raises a KeyError if the option is not found.

Return type

bool

SEE ALSO:

getBoolArray , PetscOptionsGetBool

Source code at petsc4py/PETSc/Options.pyx:218

getBoolArray(name, default=None)

Return the boolean values associated with the option.

Not collective.
Parameters

	•		name ( str ) -- The option name.
	•		default -- The default value. If None , it raises a KeyError if the option is not found.

Return type

ArrayBool

SEE ALSO:

getBool , PetscOptionsGetBoolArray

Source code at petsc4py/PETSc/Options.pyx:238

getInt(name, default=None)

Return the integer value associated with the option.

Not collective.
Parameters

	•		name ( str ) -- The option name.
	•		default -- The default value. If None , it raises a KeyError if the option is not found.

Return type

int

SEE ALSO:

getIntArray , PetscOptionsGetInt

Source code at petsc4py/PETSc/Options.pyx:258

getIntArray(name, default=None)

Return the integer array associated with the option.

Not collective.
Parameters

	•		name ( str ) -- The option name.
	•		default -- The default value. If None , it raises a KeyError if the option is not found.

Return type

ArrayInt

SEE ALSO:

getInt , PetscOptionsGetIntArray

Source code at petsc4py/PETSc/Options.pyx:278

getReal(name, default=None)

Return the real value associated with the option.

Not collective.
Parameters

	•		name ( str ) -- The option name.
	•		default -- The default value. If None , it raises a KeyError if the option is not found.

Return type

float

SEE ALSO:

getRealArray , PetscOptionsGetReal

Source code at petsc4py/PETSc/Options.pyx:298

getRealArray(name, default=None)

Return the real array associated with the option.

Not collective.
Parameters

	•		name ( str ) -- The option name.
	•		default -- The default value. If None , it raises a KeyError if the option is not found.

Return type

ArrayReal

SEE ALSO:

getReal , PetscOptionsGetRealArray

Source code at petsc4py/PETSc/Options.pyx:318

getScalar(name, default=None)

Return the scalar value associated with the option.

Not collective.
Parameters

	•		name ( str ) -- The option name.
	•		default -- The default value. If None , it raises a KeyError if the option is not found.

Return type

Scalar

SEE ALSO:

getScalarArray , PetscOptionsGetScalar

Source code at petsc4py/PETSc/Options.pyx:338

getScalarArray(name, default=None)

Return the scalar array associated with the option.

Not collective.
Parameters

	•		name ( str ) -- The option name.
	•		default -- The default value. If None , it raises a KeyError if the option is not found.

Return type

ArrayScalar

SEE ALSO:

getScalar , PetscOptionsGetScalarArray

Source code at petsc4py/PETSc/Options.pyx:358

getString(name, default=None)

Return the string associated with the option.

Not collective.
Parameters

	•		name ( str ) -- The option name.
	•		default -- The default value. If None , it raises a KeyError if the option is not found.

Return type

str

SEE ALSO:

PetscOptionsGetString

Source code at petsc4py/PETSc/Options.pyx:378

hasName(name)

Return the boolean indicating if the option is in the database.

Source code at petsc4py/PETSc/Options.pyx:144
Parameters

name ( str )

Return type

bool

insertString(string)

Insert a string in the options database.

Logically collective.

SEE ALSO:

PetscOptionsInsertString

Source code at petsc4py/PETSc/Options.pyx:400
Parameters

string ( str )

Return type

None

prefixPop()

Pop a prefix for the options database.

Logically collective.

SEE ALSO:

prefixPush , PetscOptionsPrefixPop

Source code at petsc4py/PETSc/Options.pyx:131
Return type

None

prefixPush(prefix)

Push a prefix for the options database.

Logically collective.

SEE ALSO:

prefixPop , PetscOptionsPrefixPush

Source code at petsc4py/PETSc/Options.pyx:116
Parameters

prefix ( str | Options | Object | None )

Return type

None

setValue(name, value)

Set a value for an option.

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

Source code at petsc4py/PETSc/Options.pyx:153

view(viewer=None)

View the options database.

Collective.
Parameters

viewer ( Viewer | None ) -- A Viewer instance or - None for the default viewer.

Return type

None

SEE ALSO:

Viewer , PetscOptionsView

Source code at petsc4py/PETSc/Options.pyx:97

Attributes Documentation

prefix

Prefix for options.

Source code at petsc4py/PETSc/Options.pyx:67

petsc4py.PETSc.PC

class petsc4py.PETSc.PC

Bases: Object

Preconditioners.

PC is described in the PETSc manual . Calling the PC with a vector as an argument will apply the preconditioner as shown in the example below.

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:

Enumerations

Image grohtml-288464-106.png

petsc4py.PETSc.PC.ASMType

class petsc4py.PETSc.PC.ASMType

Bases: object

The ASM subtype.

Attributes Summary

Image grohtml-288464-107.png

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

petsc4py.PETSc.PC.CompositeType

class petsc4py.PETSc.PC.CompositeType

Bases: object

The composite type.

Attributes Summary

Image grohtml-288464-108.png

Attributes Documentation
ADDITIVE: int = ADDITIVE

Constant ADDITIVE of type int

MULTIPLICATIVE: int = MULTIPLICATIVE

Constant MULTIPLICATIVE of type int

SCHUR: int = SCHUR

Constant SCHUR of type int

SPECIAL: int = SPECIAL

Constant SPECIAL of type int

SYMMETRIC_MULTIPLICATIVE: int = SYMMETRIC_MULTIPLICATIVE

Constant SYMMETRIC_MULTIPLICATIVE of type int

petsc4py.PETSc.PC.DeflationSpaceType

class petsc4py.PETSc.PC.DeflationSpaceType

Bases: object

The deflation space subtype.

Attributes Summary

Image grohtml-288464-109.png

Attributes Documentation
AGGREGATION: int = AGGREGATION

Constant AGGREGATION of type int

BIORTH22: int = BIORTH22

Constant BIORTH22 of type int

DB16: int = DB16

Constant DB16 of type int

DB2: int = DB2

Constant DB2 of type int

DB4: int = DB4

Constant DB4 of type int

DB8: int = DB8

Constant DB8 of type int

HAAR: int = HAAR

Constant HAAR of type int

MEYER: int = MEYER

Constant MEYER of type int

USER: int = USER

Constant USER of type int

petsc4py.PETSc.PC.FailedReason

class petsc4py.PETSc.PC.FailedReason

Bases: object

The reason the preconditioner has failed.

Attributes Summary

Image grohtml-288464-110.png

Attributes Documentation
FACTOR_NUMERIC_ZEROPIVOT: int = FACTOR_NUMERIC_ZEROPIVOT

Constant FACTOR_NUMERIC_ZEROPIVOT of type int

FACTOR_OTHER: int = FACTOR_OTHER

Constant FACTOR_OTHER of type int

FACTOR_OUTMEMORY: int = FACTOR_OUTMEMORY

Constant FACTOR_OUTMEMORY of type int

FACTOR_STRUCT_ZEROPIVOT: int = FACTOR_STRUCT_ZEROPIVOT

Constant FACTOR_STRUCT_ZEROPIVOT of type int

NOERROR: int = NOERROR

Constant NOERROR of type int

SETUP_ERROR: int = SETUP_ERROR

Constant SETUP_ERROR of type int

SUBPC_ERROR: int = SUBPC_ERROR

Constant SUBPC_ERROR of type int

petsc4py.PETSc.PC.FieldSplitSchurFactType

class petsc4py.PETSc.PC.FieldSplitSchurFactType

Bases: object

The field split Schur factorization type.

Attributes Summary

Image grohtml-288464-111.png

Attributes Documentation
DIAG: int = DIAG

Constant DIAG of type int

FULL: int = FULL

Constant FULL of type int

LOWER: int = LOWER

Constant LOWER of type int

UPPER: int = UPPER

Constant UPPER of type int

petsc4py.PETSc.PC.FieldSplitSchurPreType

class petsc4py.PETSc.PC.FieldSplitSchurPreType

Bases: object

The field split Schur subtype.

Attributes Summary

Image grohtml-288464-112.png

Attributes Documentation
A11: int = A11

Constant A11 of type int

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

petsc4py.PETSc.PC.GAMGType

class petsc4py.PETSc.PC.GAMGType

Bases: object

The GAMG subtype.

Attributes Summary

Image grohtml-288464-113.png

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

petsc4py.PETSc.PC.GASMType

class petsc4py.PETSc.PC.GASMType

Bases: object

The GASM subtype.

Attributes Summary

Image grohtml-288464-114.png

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

petsc4py.PETSc.PC.HPDDMCoarseCorrectionType

class petsc4py.PETSc.PC.HPDDMCoarseCorrectionType

Bases: object

The HPDDM coarse correction type.

Attributes Summary

Image grohtml-288464-115.png

Attributes Documentation
ADDITIVE: int = ADDITIVE

Constant ADDITIVE of type int

BALANCED: int = BALANCED

Constant BALANCED of type int

DEFLATED: int = DEFLATED

Constant DEFLATED of type int

NONE: int = NONE

Constant NONE of type int

petsc4py.PETSc.PC.MGCycleType

class petsc4py.PETSc.PC.MGCycleType

Bases: object

The MG cycle type.

Attributes Summary

Image grohtml-288464-116.png

Attributes Documentation
V: int = V

Constant V of type int

W: int = W

Constant W of type int

petsc4py.PETSc.PC.MGType

class petsc4py.PETSc.PC.MGType

Bases: object

The MG subtype.

Attributes Summary

Image grohtml-288464-117.png

Attributes Documentation
ADDITIVE: int = ADDITIVE

Constant ADDITIVE of type int

FULL: int = FULL

Constant FULL of type int

KASKADE: int = KASKADE

Constant KASKADE of type int

MULTIPLICATIVE: int = MULTIPLICATIVE

Constant MULTIPLICATIVE of type int

petsc4py.PETSc.PC.PatchConstructType

class petsc4py.PETSc.PC.PatchConstructType

Bases: object

The patch construction type.

Attributes Summary

Image grohtml-288464-118.png

Attributes Documentation
PARDECOMP: int = PARDECOMP

Constant PARDECOMP of type int

PYTHON: int = PYTHON

Constant PYTHON of type int

STAR: int = STAR

Constant STAR of type int

USER: int = USER

Constant USER of type int

VANKA: int = VANKA

Constant VANKA of type int

petsc4py.PETSc.PC.Side

class petsc4py.PETSc.PC.Side

Bases: object

The manner in which the preconditioner is applied.

Attributes Summary

Image grohtml-288464-119.png

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

petsc4py.PETSc.PC.Type

class petsc4py.PETSc.PC.Type

Bases: object

The preconditioner method.

Attributes Summary

Image grohtml-288464-120.png

Attributes Documentation
ASM: str = ASM

Object ASM of type str

BDDC: str = BDDC

Object BDDC of type str

BFBT: str = BFBT

Object BFBT of type str

BJACOBI: str = BJACOBI

Object BJACOBI of type str

CHOLESKY: str = CHOLESKY

Object CHOLESKY of type str

CHOWILUVIENNACL: str = CHOWILUVIENNACL

Object CHOWILUVIENNACL of type str

COMPOSITE: str = COMPOSITE

Object COMPOSITE of type str

CP: str = CP

Object CP of type str

DEFLATION: str = DEFLATION

Object DEFLATION of type str

EISENSTAT: str = EISENSTAT

Object EISENSTAT of type str

EXOTIC: str = EXOTIC

Object EXOTIC of type str

FIELDSPLIT: str = FIELDSPLIT

Object FIELDSPLIT of type str

GALERKIN: str = GALERKIN

Object GALERKIN of type str

GAMG: str = GAMG

Object GAMG of type str

GASM: str = GASM

Object GASM of type str

H2OPUS: str = H2OPUS

Object H2OPUS of type str

HMG: str = HMG

Object HMG of type str

HPDDM: str = HPDDM

Object HPDDM of type str

HYPRE: str = HYPRE

Object HYPRE of type str

ICC: str = ICC

Object ICC of type str

ILU: str = ILU

Object ILU of type str

JACOBI: str = JACOBI

Object JACOBI of type str

KACZMARZ: str = KACZMARZ

Object KACZMARZ of type str

KSP: str = KSP

Object KSP of type str

LMVM: str = LMVM

Object LMVM of type str

LSC: str = LSC

Object LSC of type str

LU: str = LU

Object LU of type str

MAT: str = MAT

Object MAT of type str

MG: str = MG

Object MG of type str

ML: str = ML

Object ML of type str

NN: str = NN

Object NN of type str

NONE: str = NONE

Object NONE of type str

PARMS: str = PARMS

Object PARMS of type str

PATCH: str = PATCH

Object PATCH of type str

PBJACOBI: str = PBJACOBI

Object PBJACOBI of type str

PFMG: str = PFMG

Object PFMG of type str

PYTHON: str = PYTHON

Object PYTHON of type str

QR: str = QR

Object QR of type str

REDISTRIBUTE: str = REDISTRIBUTE

Object REDISTRIBUTE of type str

REDUNDANT: str = REDUNDANT

Object REDUNDANT of type str

ROWSCALINGVIENNACL: str = ROWSCALINGVIENNACL

Object ROWSCALINGVIENNACL of type str

SAVIENNACL: str = SAVIENNACL

Object SAVIENNACL of type str

SHELL: str = SHELL

Object SHELL of type str

SOR: str = SOR

Object SOR of type str

SPAI: str = SPAI

Object SPAI of type str

SVD: str = SVD

Object SVD of type str

SYSPFMG: str = SYSPFMG

Object SYSPFMG of type str

TELESCOPE: str = TELESCOPE

Object TELESCOPE of type str

TFS: str = TFS

Object TFS of type str

VPBJACOBI: str = VPBJACOBI

Object VPBJACOBI of type str

Methods Summary

Image grohtml-288464-121.png

Methods Documentation
addCompositePCType(pc_type)

Add a PC of the given type to the composite PC .

Collective.
Parameters

pc_type ( Type | str ) -- The type of the preconditioner to add.

Return type

None

SEE ALSO:

PCCompositeAddPCType

Source code at petsc4py/PETSc/PC.pyx:1665

appendOptionsPrefix(prefix)

Append to the prefix used for all the PC options.

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

apply(x, y)

Apply the PC to a vector.

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

applySymmetricLeft(x, y)

Apply the left part of a symmetric PC to a vector.

Collective.
Parameters

	•		x ( Vec ) -- The input vector.
	•		y ( Vec ) -- The output vector, cannot be the same as x .

Return type

None

SEE ALSO:

PCApplySymmetricLeft

Source code at petsc4py/PETSc/PC.pyx:641

applySymmetricRight(x, y)

Apply the right part of a symmetric PC to a vector.

Collective.
Parameters

	•		x ( Vec ) -- The input vector.
	•		y ( Vec ) -- The output vector, cannot be the same as x .

Return type

None

SEE ALSO:

PCApplySymmetricRight

Source code at petsc4py/PETSc/PC.pyx:660

applyTranspose(x, y)

Apply the transpose of the PC to a vector.

Collective.

For complex numbers this applies the non-Hermitian transpose.
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:619

create(comm=None)

Create an empty PC .

Collective.

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

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

Return type

Self

SEE ALSO:

destroy , PCCreate

Source code at petsc4py/PETSc/PC.pyx:264

createPython(context=None, comm=None)

Create a preconditioner 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 preconditioner type , setType , setPythonContext , PC.Type.PYTHON

Source code at petsc4py/PETSc/PC.pyx:742

destroy()

Destroy the PC that was created with create .

Collective.

SEE ALSO:

PCDestroy

Source code at petsc4py/PETSc/PC.pyx:250
Return type

Self

getASMSubKSP()

Return the local KSP object for all blocks on this process.

Not collective.

SEE ALSO:

PCASMGetSubKSP

Source code at petsc4py/PETSc/PC.pyx:946
Return type

list [ KSP ]

getCompositePC(n)

Return a component of the composite PC .

Not collective.
Parameters

n ( int ) -- The index of the PC in the composition.

Return type

None

SEE ALSO:

PCCompositeGetPC

Source code at petsc4py/PETSc/PC.pyx:1644

getDM()

Return the DM associated with the PC .

Not collective.

SEE ALSO:

PCGetDM

Source code at petsc4py/PETSc/PC.pyx:681
Return type

getDeflationCoarseKSP()

Return the coarse problem KSP .

Not collective.

SEE ALSO:

PCDeflationGetCoarseKSP

Source code at petsc4py/PETSc/PC.pyx:2910
Return type

KSP

getDeflationPC()

Return the additional preconditioner.

Not collective.

SEE ALSO:

PCDeflationGetPC

Source code at petsc4py/PETSc/PC.pyx:2925
Return type

getFactorMatrix()

Return the factored matrix.

Not collective.

SEE ALSO:

PCFactorGetMatrix

Source code at petsc4py/PETSc/PC.pyx:1434
Return type

Mat

getFactorSolverType()

Return the solver package used to perform the factorization.

Not collective.

SEE ALSO:

PCFactorGetMatSolverType

Source code at petsc4py/PETSc/PC.pyx:1290
Return type

str

getFailedReason()

Return the reason the PC terminated.

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 is the local value.

SEE ALSO:

PCGetFailedReason

Source code at petsc4py/PETSc/PC.pyx:520
Return type

FailedReason

getFieldSplitSchurGetSubKSP()

Return the KSP for the Schur complement based splits.

Not collective.

SEE ALSO:

PCFieldSplitSchurGetSubKSP , PCFieldSplitGetSubKSP

Source code at petsc4py/PETSc/PC.pyx:1545
Return type

list [ KSP ]

getFieldSplitSubIS(splitname)

Return the IS associated with a given name.

Not collective.

SEE ALSO:

PCFieldSplitGetIS

Source code at petsc4py/PETSc/PC.pyx:1565
Parameters

splitname ( str )

Return type

getFieldSplitSubKSP()

Return the KSP for all splits.

Not collective.

SEE ALSO:

PCFieldSplitGetSubKSP

Source code at petsc4py/PETSc/PC.pyx:1525
Return type

list [ KSP ]

getHPDDMCoarseCorrectionType()

Return the coarse correction type.

Not collective.

SEE ALSO:

PCHPDDMGetCoarseCorrectionType

Source code at petsc4py/PETSc/PC.pyx:2562
Return type

HPDDMCoarseCorrectionType

getHPDDMComplexities()

Compute the grid and operator complexities.

Collective.

SEE ALSO:

PCHPDDMGetComplexities

Source code at petsc4py/PETSc/PC.pyx:2512
Return type

tuple [ float , float ]

getHPDDMSTShareSubKSP()

Return true if the KSP in SLEPc ST and the subdomain solver is shared.

Not collective.

SEE ALSO:

PCHPDDMGetSTShareSubKSP

Source code at petsc4py/PETSc/PC.pyx:2576
Return type

bool

getHYPREType()

Return the Type.HYPRE type.

Not collective.

SEE ALSO:

PCHYPREGetType

Source code at petsc4py/PETSc/PC.pyx:1076
Return type

str

getKSP()

Return the KSP if the PC is Type.KSP .

Not collective.

SEE ALSO:

PCKSPGetKSP

Source code at petsc4py/PETSc/PC.pyx:1686
Return type

KSP

getMGCoarseSolve()

Return the KSP used on the coarse grid.

Not collective.

SEE ALSO:

PCMGGetCoarseSolve

Source code at petsc4py/PETSc/PC.pyx:1762
Return type

KSP

getMGInterpolation(level)

Return the interpolation operator for the given level.

Logically collective.
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:1797

getMGLevels()

Return the number of MG levels.

Not collective.

SEE ALSO:

PCMGGetLevels

Source code at petsc4py/PETSc/PC.pyx:1730
Return type

int

getMGRScale(level)

Return the pointwise scaling for the restriction operator on the given level.

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

getMGRestriction(level)

Return the restriction operator for the given level.

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

getMGSmoother(level)

Return the KSP to be used as a smoother.

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

getMGSmootherDown(level)

Return the KSP to be used as a smoother before coarse grid correction.

Not collective.
Parameters

level ( int ) -- The level of the smoother.

Return type

KSP

SEE ALSO:

getMGSmoother , getMGSmootherUp , PCMGGetSmootherDown

Source code at petsc4py/PETSc/PC.pyx:1921

getMGSmootherUp(level)

Return the KSP to be used as a smoother after coarse grid correction.

Not collective.
Parameters

level ( int ) -- The level of the smoother.

Return type

KSP

SEE ALSO:

getMGSmootherDown , getMGSmoother , PCMGGetSmootherUp

Source code at petsc4py/PETSc/PC.pyx:1942

getMGType()

Return the form of multigrid.

Logically collective.

SEE ALSO:

PCMGGetType

Source code at petsc4py/PETSc/PC.pyx:1703
Return type

MGType

getOperators()

Return the matrices associated with a linear system.

Not collective.

SEE ALSO:

setOperators , PCGetOperators

Source code at petsc4py/PETSc/PC.pyx:416
Return type

tuple [ Mat , Mat ]

getOptionsPrefix()

Return the prefix used for all the PC options.

Not collective.

SEE ALSO:

Working with PETSc options , PCGetOptionsPrefix

Source code at petsc4py/PETSc/PC.pyx:341
Return type

str

getPatchSubKSP()

Return the local KSP object for all blocks on this process.

Not collective.

Source code at petsc4py/PETSc/PC.pyx:2372
Return type

list [ KSP ]

getPythonContext()

Return the instance of the class implementing the required Python methods.

Not collective.

SEE ALSO:

PETSc Python preconditioner type , setPythonContext

Source code at petsc4py/PETSc/PC.pyx:779
Return type

Any

getPythonType()

Return the fully qualified Python name of the class used by the preconditioner.

Not collective.

SEE ALSO:

PETSc Python preconditioner type , setPythonContext , setPythonType , PCPythonGetType

Source code at petsc4py/PETSc/PC.pyx:808
Return type

str

getType()

Return the preconditioner type.

Not collective.

SEE ALSO:

setType , PCGetType

Source code at petsc4py/PETSc/PC.pyx:308
Return type

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

SEE ALSO:

setUseAmat , PCGetUseAmat

Source code at petsc4py/PETSc/PC.pyx:458

matApply(x, y)

Apply the PC to many vectors stored as Mat.Type.DENSE .

Collective.
Parameters

	•		x ( Mat ) -- The input matrix.
	•		y ( Mat ) -- The output matrix, cannot be the same as x .

Return type

None

SEE ALSO:

PCMatApply , PCApply

Source code at petsc4py/PETSc/PC.pyx:600

reset()

Reset the PC , removing any allocated vectors and matrices.

Collective.

SEE ALSO:

PCReset

Source code at petsc4py/PETSc/PC.pyx:553
Return type

None

setASMLocalSubdomains(nsd, is_sub=None, is_local=None)

Set the local subdomains.

Collective.
Parameters

	•		nsd ( int ) -- The number of subdomains for this process.
	•		is_sub ( Sequence[IS] \| None ) -- Defines the subdomains for this process or None to determine internally.
	•		is_local ( Sequence[IS] \| None ) -- Defines the local part of the subdomains for this process, only used for PC.ASMType.RESTRICT .

Return type

None

SEE ALSO:

setASMTotalSubdomains , PCASMSetLocalSubdomains

Source code at petsc4py/PETSc/PC.pyx:860

setASMOverlap(overlap)

Set the overlap between a pair of subdomains.

Logically collective.
Parameters

overlap ( int ) -- The amount of overlap between subdomains.

Return type

None

SEE ALSO:

PCASMSetOverlap

Source code at petsc4py/PETSc/PC.pyx:842

setASMSortIndices(dosort)

Set to sort subdomain indices.

Logically collective.
Parameters

dosort ( bool ) -- Set to True to sort indices

Return type

None

SEE ALSO:

PCASMSetSortIndices

Source code at petsc4py/PETSc/PC.pyx:961

setASMTotalSubdomains(nsd, is_sub=None, is_local=None)

Set the subdomains for all processes.

Collective.
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.
	•		is_local ( Sequence[IS] \| None ) -- Defines the local part of the subdomains for this process, only used for PC.ASMType.RESTRICT .

Return type

None

SEE ALSO:

setASMLocalSubdomains , PCASMSetTotalSubdomains

Source code at petsc4py/PETSc/PC.pyx:903

setASMType(asmtype)

Set 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 code at petsc4py/PETSc/PC.pyx:824

setBDDCChangeOfBasisMat(T, interior=False)

Set a user defined change of basis for degrees of freedom.

Collective.
Parameters

	•		T ( Mat ) -- The matrix representing the change of basis.
	•		interior ( bool ) -- Enable to indicate the change of basis affects interior degrees of freedom.

Return type

None

SEE ALSO:

PCBDDCSetChangeOfBasisMat

Source code at petsc4py/PETSc/PC.pyx:2165

setBDDCCoarseningRatio(cratio)

Set 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 code at petsc4py/PETSc/PC.pyx:2220

setBDDCDirichletBoundaries(bndr)

Set 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 code at petsc4py/PETSc/PC.pyx:2256

setBDDCDirichletBoundariesLocal(bndr)

Set 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 code at petsc4py/PETSc/PC.pyx:2273

setBDDCDiscreteGradient(G, order=1, field=1, gord=True,
conforming=True)

Set the discrete gradient.

Collective.
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.
	•		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 code at petsc4py/PETSc/PC.pyx:2129

setBDDCDivergenceMat(div, trans=False, l2l=None)

Set the linear operator representing ∫ div(u)•p dx.

Collective.
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 ( IS \| None ) -- Optional IS describing the local to local map for velocities.

Return type

None

SEE ALSO:

PCBDDCSetDivergenceMat

Source code at petsc4py/PETSc/PC.pyx:2103

setBDDCDofsSplitting(isfields)

Set the index set(s) defining fields of the global matrix.

Collective.
Parameters

isfields ( IS | Sequence[IS] ) -- The sequence of IS describing the fields in global ordering.

Return type

None

SEE ALSO:

PCBDDCSetDofsSplitting

Source code at petsc4py/PETSc/PC.pyx:2324

setBDDCDofsSplittingLocal(isfields)

Set the index set(s) defining fields of the local subdomain matrix.

Collective.

Not all nodes need to be listed. Unlisted nodes will belong to the complement field.
Parameters

isfields ( IS | Sequence[IS] ) -- The sequence of IS describing the fields in local ordering.

Return type

None

SEE ALSO:

PCBDDCSetDofsSplittingLocal

Source code at petsc4py/PETSc/PC.pyx:2346

setBDDCLevels(levels)

Set the maximum number of additional levels allowed.

Logically collective.
Parameters

levels ( int ) -- The maximum number of levels.

Return type

None

SEE ALSO:

PCBDDCSetLevels

Source code at petsc4py/PETSc/PC.pyx:2238

setBDDCLocalAdjacency(csr)

Provide a custom connectivity graph for local dofs.

Not collective.
Parameters

csr ( CSRIndicesSpec ) -- Compressed sparse row layout information.

Return type

None

SEE ALSO:

PCBDDCSetLocalAdjacencyGraph

Source code at petsc4py/PETSc/PC.pyx:2073

setBDDCNeumannBoundaries(bndr)

Set the IS defining Neumann boundaries for the global problem.

Collective.
Parameters

bndr ( IS ) -- The parallel IS defining Neumann boundaries.

Return type

None

SEE ALSO:

PCBDDCSetNeumannBoundaries

Source code at petsc4py/PETSc/PC.pyx:2290

setBDDCNeumannBoundariesLocal(bndr)

Set the IS defining Neumann boundaries in local ordering.

Collective.
Parameters

bndr ( IS ) -- The parallel IS defining Neumann boundaries in local ordering.

Return type

None

SEE ALSO:

setBDDCNeumannBoundaries , - PCBDDCSetNeumannBoundariesLocal

Source code at petsc4py/PETSc/PC.pyx:2307

setBDDCPrimalVerticesIS(primv)

Set additional user defined primal vertices.

Collective.
Parameters

primv ( IS ) -- The IS of primal vertices in global numbering.

Return type

None

SEE ALSO:

PCBDDCSetPrimalVerticesIS

Source code at petsc4py/PETSc/PC.pyx:2186

setBDDCPrimalVerticesLocalIS(primv)

Set additional user defined primal vertices.

Collective.
Parameters

primv ( IS ) -- The IS of primal vertices in local numbering.

Return type

None

SEE ALSO:

PCBDDCSetPrimalVerticesLocalIS

Source code at petsc4py/PETSc/PC.pyx:2203

setCompositeType(ctype)

Set the type of composite preconditioner.

Logically collective.
Parameters

ctype ( CompositeType ) -- The type of composition.

Return type

None

SEE ALSO:

PCCompositeSetType

Source code at petsc4py/PETSc/PC.pyx:1626

setCoordinates(coordinates)

Set the coordinates for the nodes on the local process.

Collective.
Parameters

coordinates ( Sequence[Sequence[float]] ) -- The two dimensional coordinate array.

Return type

None

SEE ALSO:

PCSetCoordinates

Source code at petsc4py/PETSc/PC.pyx:715

setDM(dm)

Set the DM that may be used by some preconditioners.

Logically collective.
Parameters

dm ( DM ) -- The DM object.

Return type

None

SEE ALSO:

PCSetDM

Source code at petsc4py/PETSc/PC.pyx:698

setDeflationCoarseMat(mat)

Set the coarse problem matrix.

Collective.
Parameters

mat ( Mat ) -- The coarse problem matrix.

Return type

None

SEE ALSO:

PCDeflationSetCoarseMat

Source code at petsc4py/PETSc/PC.pyx:2893

setDeflationCorrectionFactor(fact)

Set the coarse problem correction factor.

Logically collective.
Parameters

fact ( float ) -- The correction factor.

Return type

None

SEE ALSO:

PCDeflationSetCorrectionFactor

Source code at petsc4py/PETSc/PC.pyx:2816

setDeflationInitOnly(flg)

Set to only perform the initialization.

Logically collective.

Sets initial guess to the solution on the deflation space but does not apply the deflation preconditioner. The additional preconditioner is still applied.
Parameters

flg ( bool ) -- Enable to only initialize the preconditioner.

Return type

None

SEE ALSO:

PCDeflationSetInitOnly

Source code at petsc4py/PETSc/PC.pyx:2758

setDeflationLevels(levels)

Set the maximum level of deflation nesting.

Logically collective.
Parameters

levels ( int ) -- The maximum deflation level.

Return type

None

SEE ALSO:

PCDeflationSetLevels

Source code at petsc4py/PETSc/PC.pyx:2780

setDeflationProjectionNullSpaceMat(mat)

Set the projection null space matrix.

Collective.
Parameters

mat ( Mat ) -- The projection null space matrix.

Return type

None

SEE ALSO:

PCDeflationSetProjectionNullSpaceMat

Source code at petsc4py/PETSc/PC.pyx:2876

setDeflationReductionFactor(red)

Set the reduction factor for the preconditioner.

Logically collective.
Parameters

red ( int ) -- The reduction factor or DEFAULT .

Return type

None

SEE ALSO:

PCDeflationSetReductionFactor

Source code at petsc4py/PETSc/PC.pyx:2798

setDeflationSpace(W, transpose)

Set the deflation space matrix or its (Hermitian) transpose.

Logically collective.
Parameters

	•		W ( Mat ) -- The deflation matrix.
	•		transpose ( bool ) -- Enable to indicate that W is an explicit transpose of the deflation matrix.

Return type

None

SEE ALSO:

PCDeflationSetSpace

Source code at petsc4py/PETSc/PC.pyx:2855

setDeflationSpaceToCompute(space_type, size)

Set the deflation space type.

Logically collective.
Parameters

	•		space_type ( DeflationSpaceType ) -- The deflation space type.
	•		size ( int ) -- The size of the space to compute

Return type

None

SEE ALSO:

PCDeflationSetSpaceToCompute

Source code at petsc4py/PETSc/PC.pyx:2834

setFactorLevels(levels)

Set the number of levels of fill.

Logically collective.
Parameters

levels ( int ) -- The number of levels to fill.

Return type

None

SEE ALSO:

PCFactorSetLevels

Source code at petsc4py/PETSc/PC.pyx:1416

setFactorOrdering(ord_type=None, nzdiag=None, reuse=None)

Set options for the matrix factorization reordering.

Logically collective.
Parameters

	•		ord_type ( str \| None ) -- The name of the matrix ordering or None to leave unchanged.
	•		nzdiag ( float \| None ) -- Threshold to consider diagonal entries in the matrix as zero.
	•		reuse ( bool \| None ) -- Enable to reuse the ordering of a factored matrix.

Return type

None

SEE ALSO:

PCFactorSetMatOrderingType , - PCFactorReorderForNonzeroDiagonal , - PCFactorSetReuseOrdering

Source code at petsc4py/PETSc/PC.pyx:1320

setFactorPivot(zeropivot=None, inblocks=None)

Set options for matrix factorization pivoting.

Logically collective.
Parameters

	•		zeropivot ( float \| None ) -- The size at which smaller pivots are treated as zero.
	•		inblocks ( bool \| None ) -- Enable to allow pivoting while factoring in blocks.

Return type

None

SEE ALSO:

PCFactorSetZeroPivot , PCFactorSetPivotInBlocks

Source code at petsc4py/PETSc/PC.pyx:1357

setFactorSetUpSolverType()

Set up the factorization solver.

Collective.

This can be called after KSP.setOperators or PC.setOperators , causes MatGetFactor to be called so then one may set the options for that particular factorization object.

SEE ALSO:

Working with PETSc options , PCFactorSetUpMatSolverType

Source code at petsc4py/PETSc/PC.pyx:1304
Return type

None

setFactorShift(shift_type=None, amount=None)

Set options for shifting diagonal entries of a matrix.

Logically collective.
Parameters

	•		shift_type ( FactorShiftType \| None ) -- The type of shift, or None to leave unchanged.
	•		amount ( float \| None ) -- The amount of shift. Specify DEFAULT to determine internally or None to leave unchanged.

Return type

None

SEE ALSO:

PCFactorSetShiftType , PCFactorSetShiftAmount

Source code at petsc4py/PETSc/PC.pyx:1386

setFactorSolverType(solver)

Set the solver package used to perform the factorization.

Logically collective.
Parameters

solver ( SolverType | str ) -- The solver package used to factorize.

Return type

None

SEE ALSO:

PCFactorSetMatSolverType

Source code at petsc4py/PETSc/PC.pyx:1271

setFailedReason(reason)

Set the reason the PC terminated.

Logically collective.
Parameters

reason ( FailedReason | str ) -- the reason the PC terminated

Return type

None

SEE ALSO:

PCSetFailedReason

Source code at petsc4py/PETSc/PC.pyx:502

setFieldSplitFields(bsize, *fields)

Sets the elements for the field split.

Collective.
Parameters

	•		bsize ( int ) -- The block size
	•		fields ( Tuple[str, Sequence[int]] ) -- A sequence of tuples containing the split name and a sequence of integers that define the elements in the split.

Return type

None

SEE ALSO:

PCFieldSplitSetBlockSize , PCFieldSplitSetFields

Source code at petsc4py/PETSc/PC.pyx:1495

setFieldSplitIS(*fields)

Set the elements for the field split by IS .

Logically collective.

Solve options for this split will be available under the prefix -fieldsplit_SPLITNAME_* .
Parameters

fields ( Tuple[str, IS] ) -- A sequence of tuples containing the split name and the IS that defines the elements in the split.

Return type

None

SEE ALSO:

Working with PETSc options , PCFieldSplitSetIS

Source code at petsc4py/PETSc/PC.pyx:1469

setFieldSplitSchurFactType(ctype)

Set the type of approximate block factorization.

Collective.
Parameters

ctype ( FieldSplitSchurFactType ) -- The type indicating which blocks to retain.

Return type

None

SEE ALSO:

PCFieldSplitSetSchurFactType

Source code at petsc4py/PETSc/PC.pyx:1581

setFieldSplitSchurPreType(ptype, pre=None)

Set from what operator the PC is 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.

Return type

None

SEE ALSO:

PCFieldSplitSetSchurPre

Source code at petsc4py/PETSc/PC.pyx:1599

setFieldSplitType(ctype)

Set the type of composition of a field split preconditioner.

Collective.
Parameters

ctype ( CompositeType ) -- The type of composition.

Return type

None

SEE ALSO:

PCFieldSplitSetType

Source code at petsc4py/PETSc/PC.pyx:1451

setFromOptions()

Set various PC parameters from user options.

Collective.

SEE ALSO:

Working with PETSc options , PCSetFromOptions

Source code at petsc4py/PETSc/PC.pyx:374
Return type

None

setGAMGLevels(levels)

Set the maximum number of levels.

Not collective.
Parameters

levels ( int ) -- The maximum number of levels to use.

Return type

None

SEE ALSO:

PCGAMGSetNlevels

Source code at petsc4py/PETSc/PC.pyx:1038

setGAMGSmooths(smooths)

Set the number of smoothing steps used on all levels.

Logically collective.
Parameters

smooths ( int ) -- The maximum number of smooths.

Return type

None

SEE ALSO:

PCGAMGSetNSmooths

Source code at petsc4py/PETSc/PC.pyx:1056

setGAMGType(gamgtype)

Set the type of algorithm.

Collective.
Parameters

gamgtype ( GAMGType | str ) -- The type of GAMG

Return type

None

SEE ALSO:

PCGAMGSetType

Source code at petsc4py/PETSc/PC.pyx:1019

setGASMOverlap(overlap)

Set the overlap between a pair of subdomains.

Logically collective.
Parameters

overlap ( int ) -- The amount of overlap between subdomains.

Return type

None

SEE ALSO:

PCGASMSetOverlap

Source code at petsc4py/PETSc/PC.pyx:999

setGASMType(gasmtype)

Set the type of restriction and interpolation.

Logically collective.
Parameters

gasmtype ( GASMType ) -- The type of GASM .

Return type

None

SEE ALSO:

PCGASMSetType

Source code at petsc4py/PETSc/PC.pyx:981

setHPDDMAuxiliaryMat(uis, uaux)

Set the auxiliary matrix used by the preconditioner.

Logically collective.
Parameters

	•		uis ( IS ) -- The IS of the local auxiliary matrix
	•		uaux ( Mat ) -- The auxiliary sequential matrix

Return type

None

SEE ALSO:

PCHPDDMSetAuxiliaryMat

Source code at petsc4py/PETSc/PC.pyx:2476

setHPDDMCoarseCorrectionType(correction_type)

Set the coarse correction type.

Collective.
Parameters

correction_type ( HPDDMCoarseCorrectionType ) -- The type of coarse correction to apply.

Return type

None

SEE ALSO:

PCHPDDMSetCoarseCorrectionType

Source code at petsc4py/PETSc/PC.pyx:2544

setHPDDMDeflationMat(uis, U)

Set the deflation space used to assemble a coarse operator.

Logically collective.
Parameters

	•		uis ( IS ) -- The IS of the local deflation matrix.
	•		U ( Mat ) -- The deflation sequential matrix of type Mat.Type.DENSE .

Return type

None

SEE ALSO:

PCHPDDMSetDeflationMat

Source code at petsc4py/PETSc/PC.pyx:2590

setHPDDMHasNeumannMat(has)

Set to indicate that the Mat passed to the PC is the local Neumann matrix.

Logically collective.
Parameters

has ( bool ) -- Enable to indicate the matrix is the local Neumann matrix.

Return type

None

SEE ALSO:

PCHPDDMHasNeumannMat

Source code at petsc4py/PETSc/PC.pyx:2526

setHPDDMRHSMat(B)

Set the right-hand side matrix of the preconditioner.

Logically collective.
Parameters

B ( Mat ) -- The right-hand side sequential matrix.

Return type

None

SEE ALSO:

PCHPDDMSetRHSMat

Source code at petsc4py/PETSc/PC.pyx:2495

setHYPREAMSSetInteriorNodes(interior)

Set the list of interior nodes to a zero conductivity region.

Collective.
Parameters

interior ( Vec ) -- A vector where a value of 1.0 indicates an interior node.

Return type

None

SEE ALSO:

PCHYPREAMSSetInteriorNodes

Source code at petsc4py/PETSc/PC.pyx:1252

setHYPREDiscreteCurl(mat)

Set the discrete curl matrix.

Collective.
Parameters

mat ( Mat ) -- The discrete curl.

Return type

None

SEE ALSO:

PCHYPRESetDiscreteCurl

Source code at petsc4py/PETSc/PC.pyx:1110

setHYPREDiscreteGradient(mat)

Set the discrete gradient matrix.

Collective.
Parameters

mat ( Mat ) -- The discrete gradient.

Return type

None

SEE ALSO:

PCHYPRESetDiscreteGradient

Source code at petsc4py/PETSc/PC.pyx:1127

setHYPRESetAlphaPoissonMatrix(mat)

Set the vector Poisson matrix.

Collective.
Parameters

mat ( Mat ) -- The vector Poisson matrix.

Return type

None

SEE ALSO:

PCHYPRESetAlphaPoissonMatrix

Source code at petsc4py/PETSc/PC.pyx:1144

setHYPRESetBetaPoissonMatrix(mat=None)

Set the Posson matrix.

Collective.
Parameters

mat ( Mat | None ) -- The Poisson matrix or None to turn off.

Return type

None

SEE ALSO:

PCHYPRESetBetaPoissonMatrix

Source code at petsc4py/PETSc/PC.pyx:1161

setHYPRESetEdgeConstantVectors(ozz, zoz, zzo=None)

Set the representation of the constant vector fields in the edge element basis.

Collective.
Parameters

	•		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 \| None ) -- A vector representing [0, 0, 1] or None in 2D.

Return type

None

SEE ALSO:

PCHYPRESetEdgeConstantVectors

Source code at petsc4py/PETSc/PC.pyx:1228

setHYPRESetInterpolations(dim, RT_Pi_Full=None, RT_Pi=None,
ND_Pi_Full=None, ND_Pi=None)

Set the interpolation matrices.

Collective.
Parameters

	•		dim ( int ) -- The dimension of the problem.
	•		RT_Pi_Full ( Mat \| 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 \| 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

Source code at petsc4py/PETSc/PC.pyx:1180

setHYPREType(hypretype)

Set the Type.HYPRE type.

Collective.
Parameters

hypretype ( str ) -- The name of the type, one of "euclid" , "pilut" , "parasails" , "boomeramg" , "ams" , "ads"

Return type

None

SEE ALSO:

PCHYPRESetType

Source code at petsc4py/PETSc/PC.pyx:1090

setMGCycleType(cycle_type)

Set the type of cycles.

Logically collective.
Parameters

cycle_type ( MGCycleType ) -- The type of multigrid cycles to use.

Return type

None

SEE ALSO:

setMGCycleTypeOnLevel , PCMGSetCycleType

Source code at petsc4py/PETSc/PC.pyx:1963

setMGCycleTypeOnLevel(level, cycle_type)

Set the type of cycle on the given level.

Logically collective.
Parameters

	•		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

Source code at petsc4py/PETSc/PC.pyx:1981

setMGInterpolation(level, mat)

Set the interpolation operator for the given level.

Logically collective.
Parameters

	•		level -- The level where interpolation is defined from level-1 to level .
	•		mat ( Mat ) -- The interpolation operator

Return type

None

SEE ALSO:

PCMGSetInterpolation

Source code at petsc4py/PETSc/PC.pyx:1777

setMGLevels(levels)

Set the number of MG levels.

Logically collective.
Parameters

levels ( int ) -- The number of levels

Return type

None

SEE ALSO:

PCMGSetLevels

Source code at petsc4py/PETSc/PC.pyx:1744

setMGR(level, r)

Set the vector where the residual is stored.

Logically collective.

If not provided, one will be set internally. Will be cleaned up in destroy .
Parameters

	•		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

Source code at petsc4py/PETSc/PC.pyx:2048

setMGRScale(level, rscale)

Set the pointwise scaling for the restriction operator on the given level.

Logically collective.
Parameters

	•		level ( int ) -- The level where restriction is defined from level to level-1 .
	•		rscale ( Vec ) -- The scaling vector.

Return type

None

SEE ALSO:

PCMGSetRScale

Source code at petsc4py/PETSc/PC.pyx:1859

setMGRestriction(level, mat)

Set the restriction operator for the given level.

Logically collective.
Parameters

	•		level ( int ) -- The level where restriction is defined from level to level-1 .
	•		mat ( Mat ) -- The restriction operator

Return type

None

SEE ALSO:

PCMGSetRestriction

Source code at petsc4py/PETSc/PC.pyx:1818

setMGRhs(level, rhs)

Set the vector where the right-hand side is stored.

Logically collective.

If not provided, one will be set internally. Will be cleaned up in destroy .
Parameters

	•		level ( int ) -- The level on which to set the right-hand side.
	•		rhs ( Vec ) -- The vector where the right-hand side is stored.

Return type

None

SEE ALSO:

PCMGSetRhs

Source code at petsc4py/PETSc/PC.pyx:2002

setMGType(mgtype)

Set the form of multigrid.

Logically collective.

SEE ALSO:

PCMGSetType

Source code at petsc4py/PETSc/PC.pyx:1717
Parameters

mgtype ( MGType )

Return type

None

setMGX(level, x)

Set the vector where the solution is stored.

Logically collective.

If not provided, one will be set internally. Will be cleaned up in destroy .
Parameters

	•		level ( int ) -- The level on which to set the solution.
	•		x ( Vec ) -- The vector where the solution is stored.

Return type

None

SEE ALSO:

PCMGSetX

Source code at petsc4py/PETSc/PC.pyx:2025

setOperators(A=None, P=None)

Set the matrices associated with the linear system.

Logically collective.

Passing None for A or P removes the matrix that is currently used. PETSc does not reset the matrix entries of either A or P to zero after a linear solve; the user is completely responsible for matrix assembly. See Mat.zeroEntries to zero all elements of a matrix.
Parameters

	•		A ( Mat \| None ) -- the matrix which defines the linear system
	•		P ( Mat \| None ) -- the matrix to be used in constructing the preconditioner, usually the same as A

Return type

None

SEE ALSO:

PCSetOperators

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

setOptionsPrefix(prefix)

Set the prefix used for all the PC options.

Logically collective.
Parameters

prefix ( str | None ) -- The prefix to prepend to all option names.

Return type

None

SEE ALSO:

Working with PETSc options , PCSetOptionsPrefix

Source code at petsc4py/PETSc/PC.pyx:322

setPatchCellNumbering(sec)

Set the cell numbering.

Source code at petsc4py/PETSc/PC.pyx:2383
Parameters

sec ( Section )

Return type

None

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

Set compute operator callbacks.

Source code at petsc4py/PETSc/PC.pyx:2444
Return type

None

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

Set compute operator callbacks.

Source code at petsc4py/PETSc/PC.pyx:2452
Return type

None

setPatchComputeOperator(operator, args=None, kargs=None)

Set compute operator callbacks.

Source code at petsc4py/PETSc/PC.pyx:2428
Return type

None

setPatchComputeOperatorInteriorFacets(operator, args=None,
kargs=None)

Set compute operator callbacks.

Source code at petsc4py/PETSc/PC.pyx:2436
Return type

None

setPatchConstructType(typ, operator=None, args=None, kargs=None)

Set compute operator callbacks.

Source code at petsc4py/PETSc/PC.pyx:2460
Return type

None

setPatchDiscretisationInfo(dms, bs, cellNodeMaps,
subspaceOffsets, ghostBcNodes, globalBcNodes)

Set discretisation info.

Source code at petsc4py/PETSc/PC.pyx:2387
Return type

None

setPythonContext(context)

Set the instance of the class implementing the required Python methods.

Not collective.

SEE ALSO:

PETSc Python preconditioner type , getPythonContext

Source code at petsc4py/PETSc/PC.pyx:767
Parameters

context ( Any )

Return type

None

setPythonType(py_type)

Set the fully qualified Python name of the class to be used.

Collective.

SEE ALSO:

PETSc Python preconditioner type , setPythonContext , getPythonType , PCPythonSetType

Source code at petsc4py/PETSc/PC.pyx:794
Parameters

py_type ( str )

Return type

None

setReusePreconditioner(flag)

Set to indicate the preconditioner is to be reused.

Logically collective.

Normally if the A matrix inside a PC changes, the PC automatically updates itself using information from the changed matrix. Enable this option prevents this.
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

Source code at petsc4py/PETSc/PC.pyx:477

setSPAIBlockSize(n)

Set the block size of the preconditioner.

Logically collective.
Parameters

n ( int ) -- The block size, defaults to 1 .

Return type

None

SEE ALSO:

PCSPAISetBlockSize

Source code at petsc4py/PETSc/PC.pyx:2684

setSPAICacheSize(size)

Set the cache size.

Logically collective.
Parameters

size ( int ) -- The size of the cache, defaults to 5 .

Return type

None

SEE ALSO:

PCSPAISetCacheSize

Source code at petsc4py/PETSc/PC.pyx:2702

setSPAIEpsilon(val)

Set the tolerance for the preconditioner.

Logically collective.
Parameters

val ( float ) -- The tolerance, defaults to 0.4 .

Return type

None

SEE ALSO:

PCSPAISetEpsilon

Source code at petsc4py/PETSc/PC.pyx:2611

setSPAIMax(maxval)

Set the size of working buffers in the preconditioner.

Logically collective.
Parameters

maxval ( int ) -- Number of entries in the work arrays to be allocated, defaults to 5000 .

Return type

None

SEE ALSO:

PCSPAISetMax

Source code at petsc4py/PETSc/PC.pyx:2647

setSPAIMaxNew(maxval)

Set the maximum number of new non-zero candidates per step.

Logically collective.
Parameters

maxval ( int ) -- Number of entries allowed, defaults to 5 .

Return type

None

SEE ALSO:

PCSPAISetMaxNew

Source code at petsc4py/PETSc/PC.pyx:2666

setSPAINBSteps(nbsteps)

Set the maximum number of improvement steps per row.

Logically collective.
Parameters

nbsteps ( int ) -- The number of steps, defaults to 5 .

Return type

None

SEE ALSO:

PCSPAISetNBSteps

Source code at petsc4py/PETSc/PC.pyx:2629

setSPAISp(sym)

Set to specify a symmetric sparsity pattern.

Logically collective.
Parameters

sym ( int ) -- Enable to indicate the matrix is symmetric.

Return type

None

SEE ALSO:

PCSPAISetSp

Source code at petsc4py/PETSc/PC.pyx:2738

setSPAIVerbose(level)

Set the verbosity level.

Logically collective.
Parameters

level ( int ) -- The level of verbosity, defaults to 1 .

Return type

None

SEE ALSO:

PCSPAISetVerbose

Source code at petsc4py/PETSc/PC.pyx:2720

setType(pc_type)

Set the preconditioner type.

Collective.
Parameters

pc_type ( Type | str ) -- The preconditioner type.

Return type

None

SEE ALSO:

Working with PETSc options , getType , TSSetType

Source code at petsc4py/PETSc/PC.pyx:289

setUp()

Set up the internal data structures for the PC .

Collective.

SEE ALSO:

PCSetUp

Source code at petsc4py/PETSc/PC.pyx:541
Return type

None

setUpOnBlocks()

Set up the PC for each block.

Collective.

For nested preconditioners such as BJACOBI , setUp is not called on each sub- KSP when setUp is called on the outer PC . This routine ensures it is called.

SEE ALSO:

setUp , PCSetUpOnBlocks

Source code at petsc4py/PETSc/PC.pyx:565
Return type

None

setUseAmat(flag)

Set to indicate to apply PC to A and not P .

Logically collective.

Sets a flag to indicate that when the preconditioner needs to apply (part of) the operator during the preconditioning process, it applies to A provided to TS.setRHSJacobian , TS.setIJacobian , SNES.setJacobian , KSP.setOperators or PC.setOperators not the P .
Parameters

flag ( bool ) -- Set True to use A and False to use P .

Return type

None

SEE ALSO:

setOperators , PCSetUseAmat

Source code at petsc4py/PETSc/PC.pyx:432

view(viewer=None)

View the PC object.

Collective.
Parameters

viewer ( Viewer | None ) -- The visualization context.

Return type

None

SEE ALSO:

PCView

Source code at petsc4py/PETSc/PC.pyx:231

petsc4py.PETSc.Partitioner

class petsc4py.PETSc.Partitioner

Bases: Object

A graph partitioner.

Enumerations

Image grohtml-288464-122.png

petsc4py.PETSc.Partitioner.Type

class petsc4py.PETSc.Partitioner.Type

Bases: object

The partitioner types.

Attributes Summary

Image grohtml-288464-123.png

Attributes Documentation
CHACO: str = CHACO

Object CHACO of type str

GATHER: str = GATHER

Object GATHER of type str

MATPARTITIONING: str = MATPARTITIONING

Object MATPARTITIONING of type str

PARMETIS: str = PARMETIS

Object PARMETIS of type str

PTSCOTCH: str = PTSCOTCH

Object PTSCOTCH of type str

SHELL: str = SHELL

Object SHELL of type str

SIMPLE: str = SIMPLE

Object SIMPLE of type str

Methods Summary

Image grohtml-288464-124.png

Methods Documentation
create(comm=None)

Create an empty partitioner object.

Collective.

The type can be set with setType .
Parameters

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

Return type

Self

SEE ALSO:

setType , PetscPartitionerCreate

Source code at petsc4py/PETSc/Partitioner.pyx:57

destroy()

Destroy the partitioner object.

Collective.

SEE ALSO:

PetscPartitionerDestroy

Source code at petsc4py/PETSc/Partitioner.pyx:44
Return type

Self

getType()

Return the partitioner type.

Not collective.

SEE ALSO:

setType , PetscPartitionerGetType

Source code at petsc4py/PETSc/Partitioner.pyx:99
Return type

Type

reset()

Reset data structures of the partitioner.

Collective.

SEE ALSO:

PetscPartitionerReset

Source code at petsc4py/PETSc/Partitioner.pyx:137
Return type

None

setFromOptions()

Set parameters in the partitioner from the options database.

Collective.

SEE ALSO:

Working with PETSc options , - PetscPartitionerSetFromOptions

Source code at petsc4py/PETSc/Partitioner.pyx:113
Return type

None

setShellPartition(numProcs, sizes=None, points=None)

Set a custom partition for a mesh.

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

Source code at petsc4py/PETSc/Partitioner.pyx:149

setType(part_type)

Build a particular type of the partitioner.

Collective.
Parameters

part_type ( Type | str ) -- The kind of partitioner.

Return type

None

SEE ALSO:

getType , PetscPartitionerSetType

Source code at petsc4py/PETSc/Partitioner.pyx:80

setUp()

Construct data structures for the partitioner.

Collective.

SEE ALSO:

PetscPartitionerSetUp

Source code at petsc4py/PETSc/Partitioner.pyx:125
Return type

None

view(viewer=None)

View the partitioner.

Collective.
Parameters

viewer ( Viewer | None ) -- A Viewer to display the graph.

Return type

None

SEE ALSO:

PetscPartitionerView

Source code at petsc4py/PETSc/Partitioner.pyx:25

petsc4py.PETSc.Quad

class petsc4py.PETSc.Quad

Bases: Object

Quadrature rule for integration.

Methods Summary

Image grohtml-288464-125.png

Methods Documentation
create(comm=None)

Create a Quad object.

Collective.
Parameters

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

Return type

Self

SEE ALSO:

PetscQuadratureCreate

Source code at petsc4py/PETSc/DT.pyx:28

destroy()

Destroy the Quad object.

Collective.

SEE ALSO:

PetscQuadratureDestroy

Source code at petsc4py/PETSc/DT.pyx:63
Return type

Self

duplicate()

Create a deep copy of the Quad object.

Collective.

SEE ALSO:

PetscQuadratureDuplicate

Source code at petsc4py/PETSc/DT.pyx:49
Return type

Quad

getData()

Return the data defining the Quad .

Not collective.
Returns

	•		points ( ArrayReal ) -- The coordinates of the quadrature points.
	•		weights ( ArrayReal ) -- The quadrature weights.

Return type

tuple ( ArrayReal , ArrayReal )

SEE ALSO:

PetscQuadratureGetData

Source code at petsc4py/PETSc/DT.pyx:76

getNumComponents()

Return the number of components for functions to be integrated.

Not collective.

SEE ALSO:

setNumComponents , PetscQuadratureGetNumComponents

Source code at petsc4py/PETSc/DT.pyx:104
Return type

int

getOrder()

Return the order of the method in the Quad .

Not collective.

SEE ALSO:

setOrder , PetscQuadratureGetOrder

Source code at petsc4py/PETSc/DT.pyx:136
Return type

int

setNumComponents(nc)

Return the number of components for functions to be integrated.

Not collective.
Parameters

nc ( int ) -- The number of components.

Return type

None

SEE ALSO:

getNumComponents , PetscQuadratureSetNumComponents

Source code at petsc4py/PETSc/DT.pyx:118

setOrder(order)

Set the order of the method in the Quad .

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

Source code at petsc4py/PETSc/DT.pyx:150

view(viewer=None)

View a Quad object.

Collective.
Parameters

viewer ( Viewer | None ) -- A Viewer to display the graph.

Return type

None

SEE ALSO:

PetscQuadratureView

Source code at petsc4py/PETSc/DT.pyx:9

petsc4py.PETSc.Random

class petsc4py.PETSc.Random

Bases: Object

The random number generator object.

SEE ALSO:

PetscRandom

Enumerations

Image grohtml-288464-126.png

petsc4py.PETSc.Random.Type

class petsc4py.PETSc.Random.Type

Bases: object

The random number generator type.

Attributes Summary

Image grohtml-288464-127.png

Attributes Documentation
RAND: str = RAND

Object RAND of type str

RAND48: str = RAND48

Object RAND48 of type str

RANDER48: str = RANDER48

Object RANDER48 of type str

RANDOM123: str = RANDOM123

Object RANDOM123 of type str

SPRNG: str = SPRNG

Object SPRNG of type str

Methods Summary

Image grohtml-288464-128.png

Attributes Summary

Image grohtml-288464-129.png

Methods Documentation
create(comm=None)

Create a random number generator object.

Collective.
Parameters

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

Return type

Self

SEE ALSO:

Sys.getDefaultComm , PetscRandomCreate

Source code at petsc4py/PETSc/Random.pyx:74

destroy()

Destroy the random number generator object.

Collective.

SEE ALSO:

PetscRandomDestroy

Source code at petsc4py/PETSc/Random.pyx:61
Return type

Self

getInterval()

Return the interval containing the random numbers generated.

Not collective.

SEE ALSO:

setInterval , PetscRandomGetInterval

Source code at petsc4py/PETSc/Random.pyx:199
Return type

tuple [ Scalar , Scalar ]

getSeed()

Return the random number generator seed.

Not collective.

SEE ALSO:

setSeed , PetscRandomGetSeed

Source code at petsc4py/PETSc/Random.pyx:166
Return type

int

getType()

Return the type of the random number generator object.

Not collective.

SEE ALSO:

setType , PetscRandomGetType

Source code at petsc4py/PETSc/Random.pyx:112
Return type

str

getValue()

Generate a scalar random number.

Not collective.

SEE ALSO:

PetscRandomGetValue

Source code at petsc4py/PETSc/Random.pyx:138
Return type

Scalar

getValueReal()

Generate a real random number.

Not collective.

SEE ALSO:

PetscRandomGetValueReal

Source code at petsc4py/PETSc/Random.pyx:152
Return type

float

setFromOptions()

Configure the random number generator from the options database.

Collective.

SEE ALSO:

Working with PETSc options , PetscRandomSetFromOptions

Source code at petsc4py/PETSc/Random.pyx:126
Return type

None

setInterval(interval)

Set the interval of the random number generator.

Not collective.

SEE ALSO:

getInterval , PetscRandomSetInterval

Source code at petsc4py/PETSc/Random.pyx:214
Parameters

interval ( tuple[Scalar, Scalar] )

Return type

None

setSeed(seed=None)

Set the seed of random number generator.

Not collective.
Parameters

seed ( int | None ) -- The value for the seed. If - None , it only seeds the generator.

Return type

None

SEE ALSO:

getSeed , PetscRandomSetSeed , PetscRandomSeed

Source code at petsc4py/PETSc/Random.pyx:180

setType(rnd_type)

Set the type of the random number generator object.

Collective.
Parameters

rnd_type ( Type | str ) -- The type of the generator.

Return type

None

SEE ALSO:

getType , PetscRandomSetType

Source code at petsc4py/PETSc/Random.pyx:93

view(viewer=None)

View a random number generator object.

Collective.
Parameters

viewer ( Viewer | None ) -- A Viewer instance or - None for the default viewer.

Return type

None

SEE ALSO:

PetscRandomView

Source code at petsc4py/PETSc/Random.pyx:41

Attributes Documentation
interval

The interval of the generated random numbers.

Source code at petsc4py/PETSc/Random.pyx:241

seed

The seed of the random number generator.

Source code at petsc4py/PETSc/Random.pyx:233

petsc4py.PETSc.SF

class petsc4py.PETSc.SF

Bases: Object

Star Forest object for communication.

SF is used for setting up and managing the communication of certain entries of arrays and Vec between MPI processes.

Enumerations

Image grohtml-288464-130.png

petsc4py.PETSc.SF.Type

class petsc4py.PETSc.SF.Type

Bases: object

The star forest types.

Attributes Summary

Image grohtml-288464-131.png

Attributes Documentation
ALLGATHER: str = ALLGATHER

Object ALLGATHER of type str

ALLGATHERV: str = ALLGATHERV

Object ALLGATHERV of type str

ALLTOALL: str = ALLTOALL

Object ALLTOALL of type str

BASIC: str = BASIC

Object BASIC of type str

GATHER: str = GATHER

Object GATHER of type str

GATHERV: str = GATHERV

Object GATHERV of type str

NEIGHBOR: str = NEIGHBOR

Object NEIGHBOR of type str

WINDOW: str = WINDOW

Object WINDOW of type str

Methods Summary

Image grohtml-288464-132.png

Methods Documentation
bcastBegin(unit, rootdata, leafdata, op)

Begin pointwise broadcast.

Collective.

Root values are reduced to leaf values. This call has to be concluded with a call to bcastEnd .
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:

bcastEnd , PetscSFBcastBegin

Source code at petsc4py/PETSc/SF.pyx:434

bcastEnd(unit, rootdata, leafdata, op)

End a broadcast & reduce operation started with bcastBegin .

Collective.
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)

Compose a new SF .

Collective.

Puts the sf under this object in a top (roots) down (leaves) view.
Parameters

sf ( SF ) -- SF to put under this object.

Return type

SEE ALSO:

PetscSFCompose

Source code at petsc4py/PETSc/SF.pyx:413

computeDegree()

Compute and return the degree of each root vertex.

Collective.

SEE ALSO:

PetscSFComputeDegreeBegin , PetscSFComputeDegreeEnd

Source code at petsc4py/PETSc/SF.pyx:279
Return type

ArrayInt

create(comm=None)

Create a star forest communication context.

Collective.
Parameters

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

Return type

Self

SEE ALSO:

PetscSFCreate

Source code at petsc4py/PETSc/SF.pyx:63

createEmbeddedLeafSF(selected)

Remove edges from all but the selected leaves.

Collective.

Does not remap indices.
Parameters

selected ( Sequence[int] ) -- Indices of the selected roots on this process.

Return type

SEE ALSO:

PetscSFCreateEmbeddedLeafSF

Source code at petsc4py/PETSc/SF.pyx:321

createEmbeddedRootSF(selected)

Remove edges from all but the selected roots.

Collective.

Does not remap indices.
Parameters

selected ( Sequence[int] ) -- Indices of the selected roots on this process.

Return type

SEE ALSO:

PetscSFCreateEmbeddedRootSF

Source code at petsc4py/PETSc/SF.pyx:297

createInverse()

Create the inverse map.

Collective.

Create the inverse map given a PetscSF in which all vertices have degree 1.

SEE ALSO:

PetscSFCreateInverseSF

Source code at petsc4py/PETSc/SF.pyx:262
Return type

createSectionSF(rootSection, remoteOffsets, leafSection)

Create an expanded SF of DOFs.

Collective.

Assumes the input SF relates points.
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

SEE ALSO:

PetscSFCreateSectionSF

Source code at petsc4py/PETSc/SF.pyx:345

destroy()

Destroy the star forest.

Collective.

SEE ALSO:

PetscSFDestroy

Source code at petsc4py/PETSc/SF.pyx:50
Return type

Self

distributeSection(rootSection, leafSection=None)

Create a new, reorganized Section .

Collective.

Moves from the root to the leaves of the SF .
Parameters

	•		rootSection ( Section ) -- Section defined on root space.
	•		leafSection ( Section \| None ) -- Section defined on the leaf space.

Return type

tuple [ ArrayInt , Section ]

SEE ALSO:

PetscSFDistributeSection

Source code at petsc4py/PETSc/SF.pyx:378

fetchAndOpBegin(unit, rootdata, leafdata, leafupdate, op)

Begin fetch and update operation.

Collective.

This operation fetches values from root and updates atomically by applying an operation using the leaf value.

This call has to be completed with fetchAndOpEnd .
Parameters

	•		unit ( Datatype ) -- MPI datatype.
	•		rootdata ( ndarray ) -- Root values to be updated, input state is seen by first process to perform an update.
	•		leafdata ( ndarray ) -- Leaf values to use in reduction.
	•		leafupdate ( ndarray ) -- State at each leaf's respective root immediately prior to my atomic update.
	•		op ( Op ) -- MPI reduction operation.

Return type

None

SEE ALSO:

fetchAndOpEnd , PetscSFFetchAndOpBegin

Source code at petsc4py/PETSc/SF.pyx:642

fetchAndOpEnd(unit, rootdata, leafdata, leafupdate, op)

End operation started in a matching call to fetchAndOpBegin .

Collective.
Parameters

	•		unit ( Datatype ) -- MPI datatype.
	•		rootdata ( ndarray ) -- Root values to be updated, input state is seen by first process to perform an update.
	•		leafdata ( ndarray ) -- Leaf values to use in reduction.
	•		leafupdate ( ndarray ) -- State at each leaf's respective root immediately prior to my atomic update.
	•		op ( Op ) -- MPI reduction operation.

Return type

None

SEE ALSO:

fetchAndOpBegin , PetscSFFetchAndOpEnd

Source code at petsc4py/PETSc/SF.pyx:678

gatherBegin(unit, leafdata, multirootdata)

Begin pointwise gather of all leaves into multi-roots.

Collective.

This call has to be completed with gatherEnd .
Parameters

	•		unit ( Datatype ) -- MPI datatype.
	•		leafdata ( ndarray ) -- Leaf data to gather to roots.
	•		multirootdata ( ndarray ) -- Root buffer to gather into, amount of space per root is equal to its degree.

Return type

None

SEE ALSO:

gatherEnd , PetscSFGatherBegin

Source code at petsc4py/PETSc/SF.pyx:592

gatherEnd(unit, leafdata, multirootdata)

End gather operation that was started with gatherBegin .

Collective.
Parameters

	•		unit ( Datatype ) -- MPI datatype.
	•		leafdata ( ndarray ) -- Leaf data to gather to roots.
	•		multirootdata ( ndarray ) -- Root buffer to gather into, amount of space per root is equal to its degree.

Return type

None

SEE ALSO:

gatherBegin , PetscSFGatherEnd

Source code at petsc4py/PETSc/SF.pyx:618

getGraph()

Return star forest graph.

Not collective.

The number of leaves can be determined from the size of ilocal .
Returns

	•		nroots ( int ) -- Number of root vertices on the current process (these are possible targets for other process to attach leaves).
	•		ilocal ( ArrayInt ) -- Locations of leaves in leafdata buffers.
	•		iremote ( ArrayInt ) -- Remote locations of root vertices for each leaf on the current process.

Return type

tuple [ int , ArrayInt , ArrayInt ]

SEE ALSO:

PetscSFGetGraph

Source code at petsc4py/PETSc/SF.pyx:155

getMulti()

Return the inner SF implementing gathers and scatters.

Collective.

SEE ALSO:

PetscSFGetMultiSF

Source code at petsc4py/PETSc/SF.pyx:247
Return type

getType()

Return the type name of the star forest.

Collective.

SEE ALSO:

PetscSFGetType

Source code at petsc4py/PETSc/SF.pyx:103
Return type

str

reduceBegin(unit, leafdata, rootdata, op)

Begin reduction of leafdata into rootdata.

Collective.

This call has to be completed with call to reduceEnd .
Parameters

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

reduceEnd , PetscSFReduceBegin

Source code at petsc4py/PETSc/SF.pyx:489

reduceEnd(unit, leafdata, rootdata, op)

End a reduction operation started with reduceBegin .

Collective.
Parameters

	•		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

Source code at petsc4py/PETSc/SF.pyx:517

reset()

Reset a star forest so that different sizes or neighbors can be used.

Collective.

SEE ALSO:

PetscSFReset

Source code at petsc4py/PETSc/SF.pyx:141
Return type

None

scatterBegin(unit, multirootdata, leafdata)

Begin pointwise scatter operation.

Collective.

Operation is from multi-roots to leaves. This call has to be completed with scatterEnd .
Parameters

	•		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

Source code at petsc4py/PETSc/SF.pyx:543

scatterEnd(unit, multirootdata, leafdata)

End scatter operation that was started with scatterBegin .

Collective.
Parameters

	•		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

Source code at petsc4py/PETSc/SF.pyx:569

setFromOptions()

Set options using the options database.

Logically collective.

SEE ALSO:

Working with PETSc options , PetscSFSetFromOptions

Source code at petsc4py/PETSc/SF.pyx:117
Return type

None

setGraph(nroots, local, remote)

Set star forest graph.

Collective.

The number of leaves argument can be determined from the size of local and/or remote .
Parameters

	•		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 *2nleaves** long as (rank, index) pairs.

Return type

None

SEE ALSO:

PetscSFSetGraph

Source code at petsc4py/PETSc/SF.pyx:190

setRankOrder(flag)

Sort multi-points for gathers and scatters by rank order.

Logically collective.
Parameters

flag ( bool ) -- True to sort, False to skip sorting.

Return type

None

SEE ALSO:

PetscSFSetRankOrder

Source code at petsc4py/PETSc/SF.pyx:229

setType(sf_type)

Set the type of the star forest.

Collective.
Parameters

sf_type ( Type | str ) -- The star forest type.

Return type

None

SEE ALSO:

PetscSFSetType

Source code at petsc4py/PETSc/SF.pyx:84

setUp()

Set up communication structures.

Collective.

SEE ALSO:

PetscSFSetUp

Source code at petsc4py/PETSc/SF.pyx:129
Return type

None

view(viewer=None)

View a star forest.

Collective.
Parameters

viewer ( Viewer | None ) -- A Viewer to display the graph.

Return type

None

SEE ALSO:

PetscSFView

Source code at petsc4py/PETSc/SF.pyx:31

petsc4py.PETSc.SNES

class petsc4py.PETSc.SNES

Bases: Object

Nonlinear equations solver.

SNES is described in the PETSc manual .

SEE ALSO:

SNES

Enumerations

Image grohtml-288464-133.png

petsc4py.PETSc.SNES.ConvergedReason

class petsc4py.PETSc.SNES.ConvergedReason

Bases: object

SNES solver termination reason.

SEE ALSO:

SNESGetConvergedReason

Attributes Summary

Image grohtml-288464-134.png

Attributes Documentation
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_FNORM_NAN: int = DIVERGED_FNORM_NAN

Constant DIVERGED_FNORM_NAN 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_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_TR_DELTA: int = DIVERGED_TR_DELTA

Constant DIVERGED_TR_DELTA of type int

ITERATING: int = ITERATING

Constant ITERATING of type int

petsc4py.PETSc.SNES.NormSchedule

class petsc4py.PETSc.SNES.NormSchedule

Bases: object

SNES norm schedule.

SEE ALSO:

SNESNormSchedule

Attributes Summary

Image grohtml-288464-135.png

Attributes Documentation
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

petsc4py.PETSc.SNES.Type

class petsc4py.PETSc.SNES.Type

Bases: object

SNES solver type.

SEE ALSO:

SNESType

Attributes Summary

Image grohtml-288464-136.png

Attributes Documentation
ANDERSON: str = ANDERSON

Object ANDERSON of type str

ASPIN: str = ASPIN

Object ASPIN of type str

COMPOSITE: str = COMPOSITE

Object COMPOSITE of type str

FAS: str = FAS

Object FAS of type str

KSPONLY: str = KSPONLY

Object KSPONLY of type str

KSPTRANSPOSEONLY: str = KSPTRANSPOSEONLY

Object KSPTRANSPOSEONLY of type str

MS: str = MS

Object MS of type str

NASM: str = NASM

Object NASM of type str

NCG: str = NCG

Object NCG of type str

NEWTONLS: str = NEWTONLS

Object NEWTONLS of type str

NEWTONTR: str = NEWTONTR

Object NEWTONTR of type str

NGMRES: str = NGMRES

Object NGMRES of type str

NGS: str = NGS

Object NGS of type str

NRICHARDSON: str = NRICHARDSON

Object NRICHARDSON of type str

PATCH: str = PATCH

Object PATCH of type str

PYTHON: str = PYTHON

Object PYTHON of type str

QN: str = QN

Object QN of type str

SHELL: str = SHELL

Object SHELL of type str

VINEWTONRSLS: str = VINEWTONRSLS

Object VINEWTONRSLS of type str

VINEWTONSSLS: str = VINEWTONSSLS

Object VINEWTONSSLS of type str

Methods Summary

Image grohtml-288464-137.png

Attributes Summary

Image grohtml-288464-138.png

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 , - SNESAppendOptionsPrefix

Source code at petsc4py/PETSc/SNES.pyx:227
Parameters

prefix ( str | None )

Return type

None

callConvergenceTest(its, xnorm, ynorm, fnorm)

Compute the convergence test.

Collective.
Parameters

	•		its ( int ) -- Iteration number.
	•		xnorm ( float ) -- Solution norm.
	•		ynorm ( float ) -- Update norm.
	•		fnorm ( float ) -- Function norm.

Return type

ConvergedReason

SEE ALSO:

setConvergenceTest , getConvergenceTest

Source code at petsc4py/PETSc/SNES.pyx:1326

computeFunction(x, f)

Compute the function.

Collective.
Parameters

	•		x ( Vec ) -- The input state vector.
	•		f ( Vec ) -- The output vector.

Return type

None

SEE ALSO:

setFunction , SNESComputeFunction

Source code at petsc4py/PETSc/SNES.pyx:1027

computeJacobian(x, J, P=None)

Compute the Jacobian.

Collective.
Parameters

	•		x ( Vec ) -- The input state vector.
	•		J ( Mat ) -- The output Jacobian matrix.
	•		P ( Mat \| None ) -- The output Jacobian matrix used to construct the preconditioner.

Return type

None

SEE ALSO:

setJacobian , SNESComputeJacobian

Source code at petsc4py/PETSc/SNES.pyx:1046

computeNGS(x, b=None)

Compute a nonlinear Gauss-Seidel step.

Collective.
Parameters

	•		x ( Vec ) -- The input/output state vector.
	•		b ( Vec \| None ) -- The input right-hand side vector.

Return type

None

SEE ALSO:

setNGS , getNGS , SNESComputeNGS

Source code at petsc4py/PETSc/SNES.pyx:1133

computeObjective(x)

Compute the value of the objective function.

Collective.
Parameters

x ( Vec ) -- The input state vector.

Return type

float

SEE ALSO:

setObjective , SNESComputeObjective

Source code at petsc4py/PETSc/SNES.pyx:1069

converged(its, xnorm, ynorm, fnorm)

Compute the convergence test and update the solver converged reason.

Collective.
Parameters

	•		its ( int ) -- Iteration number.
	•		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:1356

create(comm=None)

Create a SNES solver.

Collective.
Parameters

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

Return type

Self

SEE ALSO:

Sys.getDefaultComm , SNESCreate

Source code at petsc4py/PETSc/SNES.pyx:145

createPython(context=None, comm=None)

Create a nonlinear solver 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 nonlinear solver type (TODO) , setType , setPythonContext , Type.PYTHON

Source code at petsc4py/PETSc/SNES.pyx:2179

destroy()

Destroy the solver.

Collective.

SEE ALSO:

SNESDestroy

Source code at petsc4py/PETSc/SNES.pyx:132
Return type

Self

getApplicationContext()

Return the application context.

Source code at petsc4py/PETSc/SNES.pyx:264
Return type

Any

getCompositeNumber()

Return the number of solvers in the composite.

Not collective.

SEE ALSO:

getCompositeSNES , SNESCompositeGetNumber , - SNESCOMPOSITE

Source code at petsc4py/PETSc/SNES.pyx:2280
Return type

int

getCompositeSNES(n)

Return the n-th solver in the composite.

Not collective.

SEE ALSO:

getCompositeNumber , SNESCompositeGetSNES , - SNESCOMPOSITE

Source code at petsc4py/PETSc/SNES.pyx:2263
Parameters

n ( int )

Return type

SNES

getConvergedReason()

Return the termination flag.

Not collective.

SEE ALSO:

setConvergedReason , SNESGetConvergedReason

Source code at petsc4py/PETSc/SNES.pyx:1739
Return type

ConvergedReason

getConvergenceHistory()

Return the convergence history.

Not collective.

SEE ALSO:

SNESGetConvergenceHistory

Source code at petsc4py/PETSc/SNES.pyx:1407
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:1314
Return type

SNESConvergedFunction

getDM()

Return the DM associated with the solver.

Not collective.

SEE ALSO:

setDM , SNESGetDM

Source code at petsc4py/PETSc/SNES.pyx:279
Return type

getDivergenceTolerance()

Get the divergence tolerance parameter used in the convergence tests.

Not collective.

SEE ALSO:

setDivergenceTolerance , getTolerances , - SNESGetDivergenceTolerance

Source code at petsc4py/PETSc/SNES.pyx:1239
Return type

float

getErrorIfNotConverged()

Return the flag indicating error on divergence.

Not collective.

SEE ALSO:

setErrorIfNotConverged , SNESGetErrorIfNotConverged

Source code at petsc4py/PETSc/SNES.pyx:1766
Return type

bool

getFASCoarseSolve()

Return the SNES used at the coarsest level of the FAS hierarchy.

Not collective.

SEE ALSO:

getFASSmoother , SNESFASGetCoarseSolve , SNESFAS

Source code at petsc4py/PETSc/SNES.pyx:594
Return type

SNES

getFASCycleSNES(level)

Return the SNES corresponding to a particular level of the FAS hierarchy.

Not collective.

SEE ALSO:

setFASLevels , getFASCoarseSolve , getFASSmoother , - SNESFASGetCycleSNES , SNESFAS

Source code at petsc4py/PETSc/SNES.pyx:577
Parameters

level ( int )

Return type

SNES

getFASInjection(level)

Return the Mat used to apply the injection from level-1 to level.

Not collective.

SEE ALSO:

setFASInjection , SNESFASGetInjection , SNESFAS

Source code at petsc4py/PETSc/SNES.pyx:500
Parameters

level ( int )

Return type

Mat

getFASInterpolation(level)

Return the Mat used to apply the interpolation from level-1 to level.

Not collective.

SEE ALSO:

setFASInterpolation , SNESFASGetInterpolation , SNESFAS

Source code at petsc4py/PETSc/SNES.pyx:440
Parameters

level ( int )

Return type

Mat

getFASLevels()

Return the number of levels used.

Not collective.

SEE ALSO:

setFASLevels , SNESFASGetLevels , SNESFAS

Source code at petsc4py/PETSc/SNES.pyx:563
Return type

int

getFASRestriction(level)

Return the Mat used to apply the restriction from level-1 to level.

Not collective.

SEE ALSO:

setFASRestriction , SNESFASGetRestriction , SNESFAS

Source code at petsc4py/PETSc/SNES.pyx:470
Parameters

level ( int )

Return type

Mat

getFASSmoother(level)

Return the smoother used at a given level of the FAS hierarchy.

Not collective.

SEE ALSO:

setFASLevels , getFASCoarseSolve , getFASSmootherDown , getFASSmootherUp , SNESFASGetSmoother , SNESFAS

Source code at petsc4py/PETSc/SNES.pyx:609
Parameters

level ( int )

Return type

SNES

getFASSmootherDown(level)

Return the downsmoother used at a given level of the FAS hierarchy.

Not collective.

SEE ALSO:

setFASLevels , getFASCoarseSolve , getFASSmoother , getFASSmootherUp , SNESFASGetSmootherDown , SNESFAS

Source code at petsc4py/PETSc/SNES.pyx:626
Parameters

level ( int )

Return type

SNES

getFASSmootherUp(level)

Return the upsmoother used at a given level of the FAS hierarchy.

Not collective.

SEE ALSO:

setFASLevels , getFASCoarseSolve , getFASSmoother , getFASSmootherDown , SNESFASGetSmootherUp , SNESFAS

Source code at petsc4py/PETSc/SNES.pyx:643
Parameters

level ( int )

Return type

SNES

getFunction()

Return the callback to compute the nonlinear function.

Not collective.

SEE ALSO:

setFunction , SNESGetFunction

Source code at petsc4py/PETSc/SNES.pyx:843
Return type

SNESFunction

getFunctionEvaluations()

Return the current number of function evaluations.

Not collective.

SEE ALSO:

setMaxFunctionEvaluations , SNESGetNumberFunctionEvals

Source code at petsc4py/PETSc/SNES.pyx:1560
Return type

int

getFunctionNorm()

Return the function norm.

Not collective.

SEE ALSO:

setFunctionNorm , SNESGetFunctionNorm

Source code at petsc4py/PETSc/SNES.pyx:1837
Return type

float

getInitialGuess()

Return the callback to compute the initial guess.

Not collective.

SEE ALSO:

setInitialGuess

Source code at petsc4py/PETSc/SNES.pyx:796
Return type

SNESGuessFunction

getIterationNumber()

Return the current iteration number.

Not collective.

SEE ALSO:

setIterationNumber , SNESGetIterationNumber

Source code at petsc4py/PETSc/SNES.pyx:1795
Return type

int

getJacobian()

Return the matrices used to compute the Jacobian and the callback tuple.

Not collective.
Returns

	•		J ( Mat ) -- The matrix to store the Jacobian.
	•		P ( Mat ) -- The matrix to construct the preconditioner.
	•		callback ( SNESJacobianFunction ) -- callback, positional and keyword arguments.

Return type

tuple [ Mat , Mat , SNESJacobianFunction ]

SEE ALSO:

setJacobian , SNESGetJacobian

Source code at petsc4py/PETSc/SNES.pyx:955

getKSP()

Return the linear solver used by the nonlinear solver.

Not collective.

SEE ALSO:

setKSP , SNESGetKSP

Source code at petsc4py/PETSc/SNES.pyx:1936
Return type

KSP

getKSPFailures()

Return the current number of linear solve failures.

Not collective.

SEE ALSO:

getMaxKSPFailures , SNESGetLinearSolveFailures

Source code at petsc4py/PETSc/SNES.pyx:1642
Return type

int

getLinearSolveIterations()

Return the total number of linear iterations.

Not collective.

SEE ALSO:

SNESGetLinearSolveIterations

Source code at petsc4py/PETSc/SNES.pyx:1851
Return type

int

getMaxFunctionEvaluations()

Return the maximum allowed number of function evaluations.

Not collective.

SEE ALSO:

setMaxFunctionEvaluations , SNESSetTolerances

Source code at petsc4py/PETSc/SNES.pyx:1544
Return type

int

getMaxKSPFailures()

Return the maximum allowed number of linear solve failures.

Not collective.

SEE ALSO:

setMaxKSPFailures , SNESGetMaxLinearSolveFailures

Source code at petsc4py/PETSc/SNES.pyx:1628
Return type

int

getMaxStepFailures()

Return the maximum allowed number of step failures.

Not collective.

SEE ALSO:

setMaxStepFailures , SNESGetMaxNonlinearStepFailures

Source code at petsc4py/PETSc/SNES.pyx:1587
Return type

int

getMonitor()

Return the callback used to monitor solver convergence.

Not collective.

SEE ALSO:

setMonitor

Source code at petsc4py/PETSc/SNES.pyx:1479
Return type

list [ tuple [ SNESMonitorFunction , tuple [Any, ...], - dict [ str , Any]]]

getNASMNumber()

Return the number of solvers in NASM.

Not collective.

SEE ALSO:

getNASMSNES , SNESNASMGetNumber , SNESNASM

Source code at petsc4py/PETSc/SNES.pyx:2312
Return type

int

getNASMSNES(n)

Return the n-th solver in NASM.

Not collective.

SEE ALSO:

getNASMNumber , SNESNASMGetSNES , SNESNASM

Source code at petsc4py/PETSc/SNES.pyx:2296
Parameters

n ( int )

Return type

SNES

getNGS()

Return the nonlinear Gauss-Seidel callback tuple.

Not collective.

SEE ALSO:

setNGS , computeNGS

Source code at petsc4py/PETSc/SNES.pyx:1119
Return type

SNESNGSFunction

getNPC()

Return the nonlinear preconditioner associated with the solver.

Not collective.

SEE ALSO:

setNPC , hasNPC , setNPCSide , getNPCSide , SNESGetNPC

Source code at petsc4py/PETSc/SNES.pyx:662
Return type

SNES

getNPCSide()

Return the nonlinear preconditioning side.

Not collective.

SEE ALSO:

setNPC , getNPC , hasNPC , setNPCSide , SNESGetNPCSide

Source code at petsc4py/PETSc/SNES.pyx:715
Return type

Side

getNormSchedule()

Return the norm schedule.

Not collective.

SEE ALSO:

setNormSchedule , SNESGetNormSchedule

Source code at petsc4py/PETSc/SNES.pyx:1265
Return type

NormSchedule

getObjective()

Return the objective callback tuple.

Not collective.

SEE ALSO:

setObjective

Source code at petsc4py/PETSc/SNES.pyx:1013
Return type

SNESObjFunction

getOptionsPrefix()

Return the prefix used for searching for options in the database.

Not collective.

SEE ALSO:

Working with PETSc options , setOptionsPrefix , - SNESGetOptionsPrefix

Source code at petsc4py/PETSc/SNES.pyx:213
Return type

str

getParamsEW()

Get the parameters of the Eisenstat and Walker trick.

Not collective.

SEE ALSO:

setUseEW , setParamsEW , SNESKSPGetParametersEW

Source code at petsc4py/PETSc/SNES.pyx:2040
Return type

dict [ str , int | float ]

getPythonContext()

Return the instance of the class implementing the required Python methods.

Not collective.

SEE ALSO:

PETSc Python nonlinear solver type (TODO) , setPythonContext

Source code at petsc4py/PETSc/SNES.pyx:2216
Return type

Any

getPythonType()

Return the fully qualified Python name of the class used by the solver.

Not collective.

SEE ALSO:

PETSc Python nonlinear solver type (TODO) , setPythonContext , setPythonType , SNESPythonGetType

Source code at petsc4py/PETSc/SNES.pyx:2246
Return type

str

getRhs()

Return the vector holding the right-hand side.

Not collective.

SEE ALSO:

SNESGetRhs

Source code at petsc4py/PETSc/SNES.pyx:1865
Return type

Vec

getSolution()

Return the vector holding the solution.

Not collective.

SEE ALSO:

setSolution , SNESGetSolution

Source code at petsc4py/PETSc/SNES.pyx:1880
Return type

Vec

getSolutionUpdate()

Return the vector holding the solution update.

Not collective.

SEE ALSO:

SNESGetSolutionUpdate

Source code at petsc4py/PETSc/SNES.pyx:1907
Return type

Vec

getStepFailures()

Return the current number of step failures.

Not collective.

SEE ALSO:

getMaxStepFailures , SNESGetNonlinearStepFailures

Source code at petsc4py/PETSc/SNES.pyx:1601
Return type

int

getTRTolerances()

Return the tolerance parameters used for the trust region.

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

getTRUpdateParameters()

Return the update parameters used for the trust region.

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

getTolerances()

Return the tolerance parameters used in the solver convergence tests.

Not collective.
Returns

	•		rtol ( float ) -- The relative norm of the residual.
	•		atol ( float ) -- The absolute norm of the residual.
	•		stol ( float ) -- The absolute norm of the step.
	•		max_it ( int ) -- The maximum allowed number of iterations.

Return type

tuple [ float , float , float , int ]

SEE ALSO:

setTolerances , SNESGetTolerances

Source code at petsc4py/PETSc/SNES.pyx:1195

getType()

Return the type of the solver.

Not collective.

SEE ALSO:

setType , SNESGetType

Source code at petsc4py/PETSc/SNES.pyx:185
Return type

str

getUpdate()

Return the callback to compute the update at the beginning of each step.

Not collective.

SEE ALSO:

setUpdate

Source code at petsc4py/PETSc/SNES.pyx:904
Return type

SNESUpdateFunction

getUseEW()

Return the flag indicating if the solver uses the Eisenstat-Walker trick.

Not collective.

SEE ALSO:

setUseEW , setParamsEW , SNESKSPGetUseEW

Source code at petsc4py/PETSc/SNES.pyx:1974
Return type

bool

getUseFD()

Return true if the solver uses color finite-differencing for the Jacobian.

Not collective.

SEE ALSO:

setUseFD

Source code at petsc4py/PETSc/SNES.pyx:2134
Return type

False

getUseKSP()

Return the flag indicating if the solver uses a linear solver.

Not collective.

SEE ALSO:

setUseKSP

Source code at petsc4py/PETSc/SNES.pyx:2078
Return type

bool

getUseMF()

Return the flag indicating if the solver uses matrix-free finite-differencing.

Not collective.

SEE ALSO:

setUseMF

Source code at petsc4py/PETSc/SNES.pyx:2107
Return type

bool

getVIInactiveSet()

Return the index set for the inactive set.

Not collective.

SEE ALSO:

SNESVIGetInactiveSet

Source code at petsc4py/PETSc/SNES.pyx:2162
Return type

hasNPC()

Return a boolean indicating whether the solver has a nonlinear preconditioner.

Not collective.

SEE ALSO:

setNPC , getNPC , setNPCSide , getNPCSide , SNESHasNPC

Source code at petsc4py/PETSc/SNES.pyx:677
Return type

bool

logConvergenceHistory(norm, linear_its=0)

Log residual norm and linear iterations.

Source code at petsc4py/PETSc/SNES.pyx:1425
Parameters

	•		norm ( float )
	•		linear_its ( int )

Return type

None

monitor(its, rnorm)

Monitor the solver.

Collective.
Parameters

	•		its -- Current number of iterations.
	•		rnorm -- Current value of the residual norm.

Return type

None

SEE ALSO:

setMonitor , SNESMonitor

Source code at petsc4py/PETSc/SNES.pyx:1506

monitorCancel()

Cancel all the monitors of the solver.

Logically collective.

SEE ALSO:

setMonitor , SNESMonitorCancel

Source code at petsc4py/PETSc/SNES.pyx:1491
Return type

None

reset()

Reset the solver.

Collective.

SEE ALSO:

SNESReset

Source code at petsc4py/PETSc/SNES.pyx:1691
Return type

None

setApplicationContext(appctx)

Set the application context.

Source code at petsc4py/PETSc/SNES.pyx:255
Parameters

appctx ( Any )

Return type

None

setConvergedReason(reason)

Set the termination flag.

Collective.

SEE ALSO:

getConvergedReason , SNESSetConvergedReason

Source code at petsc4py/PETSc/SNES.pyx:1726
Parameters

reason ( ConvergedReason )

Return type

None

setConvergenceHistory(length=None, reset=False)

Set the convergence history.

Logically collective.

SEE ALSO:

SNESSetConvergenceHistory

Source code at petsc4py/PETSc/SNES.pyx:1383
Return type

None

setConvergenceTest(converged, args=None, kargs=None)

Set the callback to use as convergence test.

Logically collective.
Parameters

	•		converged ( SNESConvergedFunction \| Literal['skip', 'default'] ) -- The convergence testing 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:

getConvergenceTest , callConvergenceTest , - SNESSetConvergenceTest

Source code at petsc4py/PETSc/SNES.pyx:1279

setDM(dm)

Associate a DM with the solver.

Not collective.

SEE ALSO:

getDM , SNESSetDM

Source code at petsc4py/PETSc/SNES.pyx:296
Parameters

dm ( DM )

Return type

None

setDivergenceTolerance(dtol)

Set the divergence tolerance parameter used in the convergence tests.

Logically collective.
Parameters

dtol ( float ) -- The divergence tolerance.

Return type

None

SEE ALSO:

getDivergenceTolerance , setTolerances , - SNESSetDivergenceTolerance

Source code at petsc4py/PETSc/SNES.pyx:1222

setErrorIfNotConverged(flag)

Immediately generate an error if the solver has not converged.

Collective.

SEE ALSO:

getErrorIfNotConverged , SNESSetErrorIfNotConverged

Source code at petsc4py/PETSc/SNES.pyx:1753
Parameters

flag ( bool )

Return type

None

setFASInjection(level, mat)

Set the Mat to be used to apply the injection from level-1 to level.

Collective.

SEE ALSO:

getFASInjection , setFASInterpolation , setFASRestriction , SNESFASSetInjection , SNESFAS

Source code at petsc4py/PETSc/SNES.pyx:486
Parameters

	•		level ( int )
	•		mat ( Mat )

Return type

None

setFASInterpolation(level, mat)

Set the Mat to be used to apply the interpolation from level-1 to level.

Collective.

SEE ALSO:

getFASInterpolation , setFASRestriction , setFASInjection , SNESFASSetInterpolation , SNESFAS

Source code at petsc4py/PETSc/SNES.pyx:426
Parameters

	•		level ( int )
	•		mat ( Mat )

Return type

None

setFASLevels(levels, comms=None)

Set the number of levels to use with FAS.

Collective.
Parameters

	•		levels ( int ) -- The number of levels
	•		comms ( Sequence[Comm] ) -- 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:529

setFASRScale(level, vec)

Set the scaling factor of the restriction operator from level to level-1.

Collective.

SEE ALSO:

setFASRestriction , SNESFASSetRScale , SNESFAS

Source code at petsc4py/PETSc/SNES.pyx:516
Parameters

	•		level ( int )
	•		vec ( Vec )

Return type

None

setFASRestriction(level, mat)

Set the Mat to be used to apply the restriction from level-1 to level.

Collective.

SEE ALSO:

setFASRScale , getFASRestriction , setFASInterpolation , setFASInjection , SNESFASSetRestriction , SNESFAS

Source code at petsc4py/PETSc/SNES.pyx:456
Parameters

	•		level ( int )
	•		mat ( Mat )

Return type

None

setForceIteration(force)

Force solve to take at least one iteration.

Collective.

SEE ALSO:

SNESSetForceIteration

Source code at petsc4py/PETSc/SNES.pyx:1809
Parameters

force ( bool )

Return type

None

setFromOptions()

Configure the solver from the options database.

Collective.

SEE ALSO:

Working with PETSc options , SNESSetFromOptions

Source code at petsc4py/PETSc/SNES.pyx:241
Return type

None

setFunction(function, f=None, args=None, kargs=None)

Set the callback to compute the nonlinear function.

Logically collective.
Parameters

	•		function ( SNESFunction \| None ) -- The callback.
	•		f ( Vec \| None ) -- An optional vector to store the result.
	•		args ( tuple[Any, ...] \| None ) -- Positional arguments for the callback.
	•		kargs ( dict[str, Any] \| None ) -- Keyword arguments for the callback.

Return type

None

SEE ALSO:

getFunction , SNESSetFunction

Source code at petsc4py/PETSc/SNES.pyx:808

setFunctionNorm(norm)

Set the function norm value.

Collective.

This is only of use to implementers of custom SNES types.

SEE ALSO:

getFunctionNorm , SNESSetFunctionNorm

Source code at petsc4py/PETSc/SNES.pyx:1822
Parameters

norm ( float )

Return type

None

setInitialGuess(initialguess, args=None, kargs=None)

Set the callback to compute the initial guess.

Logically collective.
Parameters

	•		initialguess ( SNESGuessFunction \| None ) -- 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:

getInitialGuess , SNESSetComputeInitialGuess

Source code at petsc4py/PETSc/SNES.pyx:765

setIterationNumber(its)

Set the current iteration number.

Collective.

This is only of use to implementers of custom SNES types.

SEE ALSO:

getIterationNumber , SNESSetIterationNumber

Source code at petsc4py/PETSc/SNES.pyx:1780
Parameters

its ( int )

Return type

None

setJacobian(jacobian, J=None, P=None, args=None, kargs=None)

Set the callback to compute the Jacobian.

Logically collective.
Parameters

	•		jacobian ( SNESJacobianFunction \| None ) -- The Jacobian callback.
	•		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:

getJacobian , SNESSetJacobian

Source code at petsc4py/PETSc/SNES.pyx:916

setKSP(ksp)

Set the linear solver that will be used by the nonlinear solver.

Logically collective.

SEE ALSO:

getKSP , SNESSetKSP

Source code at petsc4py/PETSc/SNES.pyx:1924
Parameters

ksp ( KSP )

Return type

None

setLineSearchPreCheck(precheck, args=None, kargs=None)

Set the callback that will be called before applying the linesearch.

Logically collective.
Parameters

	•		precheck ( SNESLSPreFunction \| None ) -- 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:

SNESLineSearchSetPreCheck

Source code at petsc4py/PETSc/SNES.pyx:731

setMaxFunctionEvaluations(max_funcs)

Set the maximum allowed number of function evaluations.

Collective.

SEE ALSO:

getMaxFunctionEvaluations , SNESSetTolerances

Source code at petsc4py/PETSc/SNES.pyx:1529
Parameters

max_funcs ( int )

Return type

None

setMaxKSPFailures(max_fails)

Set the maximum allowed number of linear solve failures.

Collective.

SEE ALSO:

getMaxKSPFailures , SNESSetMaxLinearSolveFailures

Source code at petsc4py/PETSc/SNES.pyx:1615
Parameters

max_fails ( int )

Return type

None

setMaxStepFailures(max_fails)

Set the maximum allowed number of step failures.

Collective.

SEE ALSO:

getMaxStepFailures , SNESSetMaxNonlinearStepFailures

Source code at petsc4py/PETSc/SNES.pyx:1574
Parameters

max_fails ( int )

Return type

None

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

Set the callback used to monitor solver convergence.

Logically collective.
Parameters

	•		monitor ( SNESMonitorFunction \| None ) -- 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:

getMonitor , SNESMonitorSet

Source code at petsc4py/PETSc/SNES.pyx:1446

setNGS(ngs, args=None, kargs=None)

Set the callback to compute nonlinear Gauss-Seidel.

Logically collective.
Parameters

	•		ngs ( SNESNGSFunction \| None ) -- The nonlinear Gauss-Seidel 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:

getNGS , computeNGS , SNESSetNGS

Source code at petsc4py/PETSc/SNES.pyx:1088

setNPC(snes)

Set the nonlinear preconditioner.

Logically collective.

SEE ALSO:

getNPC , hasNPC , setNPCSide , getNPCSide , SNESSetNPC

Source code at petsc4py/PETSc/SNES.pyx:691
Parameters

snes ( SNES )

Return type

None

setNPCSide(side)

Set the nonlinear preconditioning side.

Collective.

SEE ALSO:

setNPC , getNPC , hasNPC , getNPCSide , SNESSetNPCSide

Source code at petsc4py/PETSc/SNES.pyx:703
Parameters

side ( Side )

Return type

None

setNormSchedule(normsched)

Set the norm schedule.

Collective.

SEE ALSO:

getNormSchedule , SNESSetNormSchedule

Source code at petsc4py/PETSc/SNES.pyx:1253
Parameters

normsched ( NormSchedule )

Return type

None

setObjective(objective, args=None, kargs=None)

Set the callback to compute the objective function.

Logically collective.
Parameters

	•		objective ( SNESObjFunction \| None ) -- The Jacobian 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:

getObjective , SNESSetObjective

Source code at petsc4py/PETSc/SNES.pyx:982

setOptionsPrefix(prefix)

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

Logically collective.

SEE ALSO:

Working with PETSc options , SNESSetOptionsPrefix

Source code at petsc4py/PETSc/SNES.pyx:199
Parameters

prefix ( str | None )

Return type

None

setParamsEW(version=None, rtol_0=None, rtol_max=None,
gamma=None, alpha=None, alpha2=None, threshold=None)

Set the parameters for the Eisenstat and Walker trick.

Logically collective.
Parameters

	•		version ( int ) -- The version of the algorithm. Defaults to CURRENT .
	•		rtol_0 ( float ) -- The initial relative residual norm. Defaults to CURRENT .
	•		rtol_max ( float ) -- The maximum relative residual norm. Defaults to CURRENT .
	•		gamma ( float ) -- Parameter. Defaults to CURRENT .
	•		alpha ( float ) -- Parameter. Defaults to CURRENT .
	•		alpha2 ( float ) -- Parameter. Defaults to CURRENT .
	•		threshold ( float ) -- Parameter. Defaults to CURRENT .

Return type

None

SEE ALSO:

setUseEW , getParamsEW , SNESKSPSetParametersEW

Source code at petsc4py/PETSc/SNES.pyx:1988

setPatchCellNumbering(sec)

Set cell patch numbering.

Source code at petsc4py/PETSc/SNES.pyx:2328
Parameters

sec ( Section )

Return type

None

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

Set patch compute function.

Source code at petsc4py/PETSc/SNES.pyx:2381
Return type

None

setPatchComputeOperator(operator, args=None, kargs=None)

Set patch compute operator.

Source code at petsc4py/PETSc/SNES.pyx:2373
Return type

None

setPatchConstructType(typ, operator=None, args=None, kargs=None)

Set patch construct type.

Source code at petsc4py/PETSc/SNES.pyx:2389
Return type

None

setPatchDiscretisationInfo(dms, bs, cellNodeMaps,
subspaceOffsets, ghostBcNodes, globalBcNodes)

Set patch discretisation information.

Source code at petsc4py/PETSc/SNES.pyx:2332
Return type

None

setPythonContext(context)

Set the instance of the class implementing the required Python methods.

Not collective.

SEE ALSO:

PETSc Python nonlinear solver type (TODO) , getPythonContext

Source code at petsc4py/PETSc/SNES.pyx:2204
Parameters

context ( Any )

Return type

None

setPythonType(py_type)

Set the fully qualified Python name of the class to be used.

Collective.

SEE ALSO:

PETSc Python nonlinear solver type (TODO) , setPythonContext , getPythonType , SNESPythonSetType

Source code at petsc4py/PETSc/SNES.pyx:2231
Parameters

py_type ( str )

Return type

None

setResetCounters(reset=True)

Set the flag to reset the counters.

Collective.

SEE ALSO:

SNESSetCountersReset

Source code at petsc4py/PETSc/SNES.pyx:1431
Parameters

reset ( bool )

Return type

None

setSolution(vec)

Set the vector used to store the solution.

Collective.

SEE ALSO:

getSolution , SNESSetSolution

Source code at petsc4py/PETSc/SNES.pyx:1895
Parameters

vec ( Vec )

Return type

None

setTRTolerances(delta_min=None, delta_max=None, delta_0=None)

Set the tolerance parameters used for the trust region.

Logically collective.
Parameters

	•		delta_min ( float ) -- The minimum allowed trust region size. Defaults to CURRENT .
	•		delta_max ( float ) -- The maximum allowed trust region size. Defaults to CURRENT .
	•		delta_0 ( float ) -- The initial trust region size. Defaults to CURRENT .

Return type

None

SEE ALSO:

getTRTolerances , setTRUpdateParameters , - SNESNewtonTRSetTolerances

Source code at petsc4py/PETSc/SNES.pyx:310

setTRUpdateParameters(eta1=None, eta2=None, eta3=None, t1=None,
t2=None)

Set the update parameters used for the trust region.

Logically collective.
Parameters

	•		eta1 ( float ) -- The step acceptance tolerance. Defaults to CURRENT .
	•		eta2 ( float ) -- The shrinking tolerance. Defaults to CURRENT .
	•		eta3 ( float ) -- The enlarging tolerance. Defaults to CURRENT .
	•		t1 ( float ) -- The shrinking factor. Defaults to CURRENT .
	•		t2 ( float ) -- The enlarging factor. Defaults to CURRENT .

Return type

None

SEE ALSO:

setTRTolerances , getTRUpdateParameters , - SNESNewtonTRSetUpdateParameters

Source code at petsc4py/PETSc/SNES.pyx:361

setTolerances(rtol=None, atol=None, stol=None, max_it=None)

Set the tolerance parameters used in the solver convergence tests.

Logically collective.
Parameters

	•		rtol ( float ) -- The relative norm of the residual, or DETERMINE to use the value when the object's type was set. Defaults to CURRENT .
	•		atol ( float ) -- The absolute norm of the residual, or DETERMINE to use the value when the object's type was set. Defaults to CURRENT .
	•		stol ( float ) -- The absolute norm of the step, or DETERMINE to use the value when the object's type was set. Defaults to CURRENT .
	•		max_it ( int ) -- The maximum allowed number of iterations, or DETERMINE to use the value when the object's type was set. Defaults to CURRENT . Use UNLIMITED to have no maximum.

Return type

None

SEE ALSO:

getTolerances , SNESSetTolerances

Source code at petsc4py/PETSc/SNES.pyx:1156

setType(snes_type)

Set the type of the solver.

Logically collective.
Parameters

snes_type ( Type | str ) -- The type of the solver.

Return type

None

SEE ALSO:

getType , SNESSetType

Source code at petsc4py/PETSc/SNES.pyx:166

setUp()

Set up the internal data structures for using the solver.

Collective.

SEE ALSO:

SNESSetUp

Source code at petsc4py/PETSc/SNES.pyx:1665
Return type

None

setUpMatrices()

Ensures that matrices are available for Newton-like methods.

Collective.

This is only of use to implementers of custom SNES types.

SEE ALSO:

setUp , SNESSetUpMatrices

Source code at petsc4py/PETSc/SNES.pyx:1677
Return type

None

setUpdate(update, args=None, kargs=None)

Set the callback to compute update at the beginning of each step.

Logically collective.
Parameters

	•		update ( SNESUpdateFunction \| None ) -- 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:

getUpdate , SNESSetUpdate

Source code at petsc4py/PETSc/SNES.pyx:873

setUseEW(flag=True, *targs, **kargs)

Tell the solver to use the Eisenstat-Walker trick.

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

Source code at petsc4py/PETSc/SNES.pyx:1951

setUseFD(flag=True)

Set the boolean flag to use coloring finite-differencing for Jacobian assembly.

Logically collective.

SEE ALSO:

getUseFD

Source code at petsc4py/PETSc/SNES.pyx:2121
Return type

None

setUseKSP(flag=True)

Set the boolean flag indicating to use a linear solver.

Logically collective.

SEE ALSO:

getUseKSP

Source code at petsc4py/PETSc/SNES.pyx:2065
Return type

None

setUseMF(flag=True)

Set the boolean flag indicating to use matrix-free finite-differencing.

Logically collective.

SEE ALSO:

getUseMF

Source code at petsc4py/PETSc/SNES.pyx:2094
Return type

None

setVariableBounds(xl, xu)

Set the vector for the variable bounds.

Collective.

SEE ALSO:

SNESVISetVariableBounds

Source code at petsc4py/PETSc/SNES.pyx:2150
Parameters

	•		xl ( Vec )
	•		xu ( Vec )

Return type

None

solve(b=None, x=None)

Solve the nonlinear equations.

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

Source code at petsc4py/PETSc/SNES.pyx:1703

view(viewer=None)

View the solver.

Collective.
Parameters

viewer ( Viewer | None ) -- A Viewer instance or - None for the default viewer.

Return type

None

SEE ALSO:

SNESView

Source code at petsc4py/PETSc/SNES.pyx:113

Attributes Documentation

appctx

Application context.

Source code at petsc4py/PETSc/SNES.pyx:2405

atol

Absolute residual tolerance.

Source code at petsc4py/PETSc/SNES.pyx:2486

DM .

Source code at petsc4py/PETSc/SNES.pyx:2415

history

Convergence history.

Source code at petsc4py/PETSc/SNES.pyx:2538

is_converged

Boolean indicating if the solver has converged.

Source code at petsc4py/PETSc/SNES.pyx:2558

is_diverged

Boolean indicating if the solver has failed.

Source code at petsc4py/PETSc/SNES.pyx:2563

is_iterating

Boolean indicating if the solver has not converged yet.

Source code at petsc4py/PETSc/SNES.pyx:2553

its

Number of iterations.

Source code at petsc4py/PETSc/SNES.pyx:2522

ksp

Linear solver.

Source code at petsc4py/PETSc/SNES.pyx:2452

max_funcs

Maximum number of function evaluations.

Source code at petsc4py/PETSc/SNES.pyx:2512

max_it

Maximum number of iterations.

Source code at petsc4py/PETSc/SNES.pyx:2502

norm

Function norm.

Source code at petsc4py/PETSc/SNES.pyx:2530

npc

Nonlinear preconditioner.

Source code at petsc4py/PETSc/SNES.pyx:2425

reason

Converged reason.

Source code at petsc4py/PETSc/SNES.pyx:2545

rtol

Relative residual tolerance.

Source code at petsc4py/PETSc/SNES.pyx:2478

stol

Solution update tolerance.

Source code at petsc4py/PETSc/SNES.pyx:2494

use_ew

Use the Eisenstat-Walker trick.

Source code at petsc4py/PETSc/SNES.pyx:2468

use_fd

Boolean indicating if the solver uses coloring finite-differencing.

Source code at petsc4py/PETSc/SNES.pyx:2578

use_ksp

Boolean indicating if the solver uses a linear solver.

Source code at petsc4py/PETSc/SNES.pyx:2460

use_mf

Boolean indicating if the solver uses matrix-free finite-differencing.

Source code at petsc4py/PETSc/SNES.pyx:2570

vec_rhs

Right-hand side vector.

Source code at petsc4py/PETSc/SNES.pyx:2445

vec_sol

Solution vector.

Source code at petsc4py/PETSc/SNES.pyx:2435

vec_upd

Update vector.

Source code at petsc4py/PETSc/SNES.pyx:2440

petsc4py.PETSc.Scatter

class petsc4py.PETSc.Scatter

Bases: Object

Scatter object.

The object used to perform data movement between vectors. Scatter is described in the PETSc manual .

SEE ALSO:

Vec , SF , VecScatter

Enumerations

Image grohtml-288464-139.png

petsc4py.PETSc.Scatter.Mode

class petsc4py.PETSc.Scatter.Mode

Bases: object

Scatter mode.

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

Attributes Summary

Image grohtml-288464-140.png

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

SCATTER_FORWARD: int = SCATTER_FORWARD

Constant SCATTER_FORWARD of type int

SCATTER_FORWARD_LOCAL: int = SCATTER_FORWARD_LOCAL

Constant SCATTER_FORWARD_LOCAL of type int

SCATTER_REVERSE: int = SCATTER_REVERSE

Constant SCATTER_REVERSE of type int

SCATTER_REVERSE_LOCAL: int = SCATTER_REVERSE_LOCAL

Constant SCATTER_REVERSE_LOCAL of type int

petsc4py.PETSc.Scatter.Type

class petsc4py.PETSc.Scatter.Type

Bases: object

Scatter type.

SEE ALSO:

VecScatterType

Attributes Summary

Image grohtml-288464-141.png

Attributes Documentation
ALLGATHER: str = ALLGATHER

Object ALLGATHER of type str

ALLGATHERV: str = ALLGATHERV

Object ALLGATHERV of type str

ALLTOALL: str = ALLTOALL

Object ALLTOALL of type str

BASIC: str = BASIC

Object BASIC of type str

GATHER: str = GATHER

Object GATHER of type str

GATHERV: str = GATHERV

Object GATHERV of type str

NEIGHBOR: str = NEIGHBOR

Object NEIGHBOR of type str

WINDOW: str = WINDOW

Object WINDOW of type str

Methods Summary

Image grohtml-288464-142.png

Methods Documentation
begin(vec_from, vec_to, addv=None, mode=None)

Begin a generalized scatter from one vector into another.

Collective.

This call has to be concluded with a call to end . For additional details on the Parameters, see scatter .

SEE ALSO:

create , end , VecScatterBegin

Source code at petsc4py/PETSc/Scatter.pyx:262
Parameters

	•		vec_from ( Vec )
	•		vec_to ( Vec )
	•		addv ( InsertModeSpec )
	•		mode ( ScatterModeSpec )

Return type

None

copy()

Return a copy of the scatter.

Source code at petsc4py/PETSc/Scatter.pyx:199
Return type

Scatter

create(vec_from, is_from, vec_to, is_to)

Create a scatter object.

Collective.
Parameters

	•		vec_from ( Vec ) -- Representative vector from which to scatter the data.
	•		is_from ( IS ) -- Indices of vec_from to scatter. If None , use all indices.
	•		vec_to ( Vec ) -- Representative vector to which scatter the data.
	•		is_to ( IS ) -- Indices of vec_to where to receive. If None , use all indices.

Return type

Self

Examples

The scatter object can be used to repeatedly perform data movement. 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 , VecScatterCreate

Source code at petsc4py/PETSc/Scatter.pyx:90

destroy()

Destroy the scatter.

Collective.

SEE ALSO:

VecScatterDestroy

Source code at petsc4py/PETSc/Scatter.pyx:77
Return type

Self

end(vec_from, vec_to, addv=None, mode=None)

Complete a generalized scatter from one vector into another.

Collective.

This call has to be preceded by a call to begin . For additional details on the Parameters, see scatter .

SEE ALSO:

create , begin , VecScatterEnd

Source code at petsc4py/PETSc/Scatter.pyx:285
Parameters

	•		vec_from ( Vec )
	•		vec_to ( Vec )
	•		addv ( InsertModeSpec )
	•		mode ( ScatterModeSpec )

Return type

None

getType()

Return the type of the scatter.

Not collective.

SEE ALSO:

setType , VecScatterGetType

Source code at petsc4py/PETSc/Scatter.pyx:160
Return type

str

scatter(vec_from, vec_to, addv=None, mode=None)

Perform a generalized scatter from one vector into another.

Collective.
Parameters

	•		vec_from ( Vec ) -- The source vector.
	•		vec_to ( Vec ) -- The destination vector.
	•		addv ( InsertModeSpec ) -- Insertion mode.
	•		mode ( ScatterModeSpec ) -- Scatter mode.

Return type

None

SEE ALSO:

create , begin , end , VecScatterBegin , VecScatterEnd

Source code at petsc4py/PETSc/Scatter.pyx:308

setFromOptions()

Configure the scatter from the options database.

Collective.

SEE ALSO:

Working with PETSc options , VecScatterSetFromOptions

Source code at petsc4py/PETSc/Scatter.pyx:174
Return type

None

setType(scatter_type)

Set the type of the scatter.

Logically collective.

SEE ALSO:

getType , VecScatterSetType

Source code at petsc4py/PETSc/Scatter.pyx:146
Parameters

scatter_type ( Type | str )

Return type

None

setUp()

Set up the internal data structures for using the scatter.

Collective.

SEE ALSO:

VecScatterSetUp

Source code at petsc4py/PETSc/Scatter.pyx:186
Return type

Self

classmethod toAll(vec)

Create a scatter that communicates a vector to all sharing processes.

Collective.
Parameters

vec ( Vec ) -- The vector to scatter from.

Return type

tuple [ Scatter , Vec ]

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

Source code at petsc4py/PETSc/Scatter.pyx:205

classmethod toZero(vec)

Create a scatter that communicates a vector to rank zero.

Collective.
Parameters

vec ( Vec ) -- The vector to scatter from.

Return type

tuple [ Scatter , Vec ]

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

Source code at petsc4py/PETSc/Scatter.pyx:233

view(viewer=None)

View the scatter.

Collective.
Parameters

viewer ( Viewer | None ) -- A Viewer instance or - None for the default viewer.

Return type

None

SEE ALSO:

VecScatterView

Source code at petsc4py/PETSc/Scatter.pyx:58

petsc4py.PETSc.ScatterMode

class petsc4py.PETSc.ScatterMode

Bases: object

Scatter mode.

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

Attributes Summary

Image grohtml-288464-143.png

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

SCATTER_FORWARD: int = SCATTER_FORWARD

Constant SCATTER_FORWARD of type int

SCATTER_FORWARD_LOCAL: int = SCATTER_FORWARD_LOCAL

Constant SCATTER_FORWARD_LOCAL of type int

SCATTER_REVERSE: int = SCATTER_REVERSE

Constant SCATTER_REVERSE of type int

SCATTER_REVERSE_LOCAL: int = SCATTER_REVERSE_LOCAL

Constant SCATTER_REVERSE_LOCAL of type int

petsc4py.PETSc.Section

class petsc4py.PETSc.Section

Bases: Object

Mapping from integers in a range to unstructured set of integers.

Methods Summary

Image grohtml-288464-144.png

Methods Documentation
addConstraintDof(point, numDof)

Increment the number of constrained DOFs for a given point.

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)

Add numDof degrees of freedom associated with a given point.

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)

Add 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)

Add numDof DOFs associated with a field on a given point.

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

Return a copy of the section.

Collective.

The copy is shallow, if possible.

SEE ALSO:

PetscSectionClone

Source code at petsc4py/PETSc/Section.pyx:80
Return type

Section

create(comm=None)

Allocate a section and set the map contents to the default.

Collective.

Typical calling sequence: - create - setNumFields - setChart - setDof - setUp - getOffset - destroy

The Section object and methods are intended to be used in the PETSc Vec and Mat implementations. The indices returned by the Section are appropriate for the kind of Vec it is associated with. For example, if the vector being indexed is a local vector, we call the section a local section. If the section indexes a global vector, we call it a global section. For parallel vectors, like global vectors, we use negative indices to indicate DOFs owned by other processes.
Parameters

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

Return type

Self

SEE ALSO:

PetscSectionCreate

Source code at petsc4py/PETSc/Section.pyx:42

createGlobalSection(sf)

Create a section describing the global field layout.

Collective.

The section describes the global field layout using the local section and an SF describing the section point overlap.

If we have a set of local sections defining the layout of a set of local vectors, and also an SF to determine which section points are shared and the ownership, we can calculate a global section defining the parallel data layout, and the associated global vector.

This gives negative sizes and offsets to points not owned by this process.

includeConstraints and localOffsets parameters of the C API are always set to False .
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 at petsc4py/PETSc/Section.pyx:846

destroy()

Destroy a section.

Not collective.

SEE ALSO:

PetscSectionDestroy

Source code at petsc4py/PETSc/Section.pyx:29
Return type

Self

getChart()

Return the range in which points (indices) lie for this section.

Not collective.

The range is [pStart, pEnd), i.e., from the first point to one past the last point.

SEE ALSO:

PetscSectionGetChart

Source code at petsc4py/PETSc/Section.pyx:238
Return type

tuple [ int , int ]

getConstrainedStorageSize()

Return the size capable of holding all unconstrained DOFs in a section.

Not collective.

SEE ALSO:

getStorageSize , PetscSectionGetConstrainedStorageSize

Source code at petsc4py/PETSc/Section.pyx:720
Return type

int

getConstraintDof(point)

Return 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 at petsc4py/PETSc/Section.pyx:445

getConstraintIndices(point)

Return the point DOFs numbers which are constrained for a given point.

Not collective.

The range is in [0, DOFs).
Parameters

point ( int ) -- The point.

Return type

ArrayInt

SEE ALSO:

setConstraintIndices , PetscSectionGetConstraintIndices

Source code at petsc4py/PETSc/Section.pyx:586

getDof(point)

Return the number of degrees of freedom for a given point.

Not collective.

In a global section, this value will be negative for points not owned by this process.
Parameters

point ( int ) -- The point.

Return type

int

SEE ALSO:

setDof , addDof , PetscSectionGetDof

Source code at petsc4py/PETSc/Section.pyx:311

getFieldComponents(field)

Return 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 at petsc4py/PETSc/Section.pyx:198

getFieldConstraintDof(point, field)

Return 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 at petsc4py/PETSc/Section.pyx:506

getFieldConstraintIndices(point, field)

Return the field DOFs numbers, in [0, DOFs), which are constrained.

Not collective.

The constrained DOFs are sorted in ascending order.
Parameters

	•		field ( int ) -- The field number.
	•		point ( int ) -- The point.

Return type

ArrayInt

SEE ALSO:

setFieldConstraintIndices , - PetscSectionGetFieldConstraintIndices

Source code at petsc4py/PETSc/Section.pyx:634

getFieldDof(point, field)

Return the number of DOFs associated with a field on a given point.

Not collective.
Parameters

	•		point ( int ) -- The point.
	•		field ( int ) -- The field.

Return type

int

SEE ALSO:

setFieldDof , PetscSectionGetFieldDof

Source code at petsc4py/PETSc/Section.pyx:375

getFieldName(field)

Return the name of a field in the section.

Not collective.
Parameters

field ( int ) -- The field number.

Return type

str

SEE ALSO:

setFieldName , PetscSectionGetFieldName

Source code at petsc4py/PETSc/Section.pyx:156

getFieldOffset(point, field)

Return the offset for the field DOFs on the given point.

Not collective.

In a global section, this offset will be negative for points not owned by this process.
Parameters

	•		point ( int ) -- The point.
	•		field ( int ) -- The field.

Return type

int

SEE ALSO:

setFieldOffset , PetscSectionGetFieldOffset

Source code at petsc4py/PETSc/Section.pyx:779

getMaxDof()

Return the maximum number of DOFs for any point in the section.

Not collective.

SEE ALSO:

PetscSectionGetMaxDof

Source code at petsc4py/PETSc/Section.pyx:692
Return type

int

getNumFields()

Return the number of fields in a section.

Not collective.

Returns 0 if no fields were defined.

SEE ALSO:

setNumFields , PetscSectionGetNumFields

Source code at petsc4py/PETSc/Section.pyx:122
Return type

int

getOffset(point)

Return the offset for the DOFs associated with the given point.

Not collective.

In a global section, this offset will be negative for points not owned by this process.
Parameters

point ( int ) -- The point.

Return type

int

SEE ALSO:

setOffset , PetscSectionGetOffset

Source code at petsc4py/PETSc/Section.pyx:734

getOffsetRange()

Return the full range of offsets, [start, end), for a section.

Not collective.

SEE ALSO:

PetscSectionGetOffsetRange

Source code at petsc4py/PETSc/Section.pyx:831
Return type

tuple [ int , int ]

getPermutation()

Return the permutation that was set with setPermutation .

Not collective.

SEE ALSO:

setPermutation , PetscSectionGetPermutation

Source code at petsc4py/PETSc/Section.pyx:279
Return type

getStorageSize()

Return the size capable of holding all the DOFs defined in a section.

Not collective.

SEE ALSO:

getConstrainedStorageSize , PetscSectionGetStorageSize

Source code at petsc4py/PETSc/Section.pyx:706
Return type

int

reset()

Free all section data.

Not collective.

SEE ALSO:

PetscSectionReset

Source code at petsc4py/PETSc/Section.pyx:110
Return type

None

setChart(pStart, pEnd)

Set the range in which points (indices) lie for this section.

Not collective.

The range is [pStart, pEnd), i.e., from the first point to one past the last point.
Parameters

	•		pStart ( int ) -- The first point.
	•		pEnd ( int ) -- One past the last point.

Return type

None

SEE ALSO:

PetscSectionSetChart

Source code at petsc4py/PETSc/Section.pyx:255

setConstraintDof(point, numDof)

Set the number of constrained DOFs associated with 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:

getConstraintDof , addConstraintDof , - PetscSectionSetConstraintDof

Source code at petsc4py/PETSc/Section.pyx:464

setConstraintIndices(point, indices)

Set the point DOFs numbers, in [0, DOFs), which are constrained.

Not collective.
Parameters

	•		point ( int ) -- The point.
	•		indices ( Sequence[int] ) -- The constrained DOFs.

Return type

None

SEE ALSO:

getConstraintIndices , PetscSectionSetConstraintIndices

Source code at petsc4py/PETSc/Section.pyx:610

setDof(point, numDof)

Set the number of degrees of freedom associated with a given point.

Not collective.
Parameters

	•		point ( int ) -- The point.
	•		numDof ( int ) -- The number of DOFs.

Return type

None

SEE ALSO:

getDof , addDof , PetscSectionSetDof

Source code at petsc4py/PETSc/Section.pyx:333

setFieldComponents(field, numComp)

Set the number of field components for the given field.

Not collective.
Parameters

	•		field ( int ) -- The field number.
	•		numComp ( int ) -- The number of field components.

Return type

None

SEE ALSO:

getFieldComponents , PetscSectionSetFieldComponents

Source code at petsc4py/PETSc/Section.pyx:217

setFieldConstraintDof(point, field, numDof)

Set the number of 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 DOFs which are fixed by constraints.

Return type

None

SEE ALSO:

getFieldConstraintDof , addFieldConstraintDof , - PetscSectionSetFieldConstraintDof

Source code at petsc4py/PETSc/Section.pyx:528

setFieldConstraintIndices(point, field, indices)

Set the field DOFs numbers, in [0, DOFs), which are constrained.

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

Source code at petsc4py/PETSc/Section.pyx:661

setFieldDof(point, field, numDof)

Set the number of DOFs associated with a field on a given point.

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

Source code at petsc4py/PETSc/Section.pyx:397

setFieldName(field, fieldName)

Set the name of a field in the section.

Not collective.
Parameters

	•		field ( int ) -- The field number.
	•		fieldName ( str ) -- The field name.

Return type

None

SEE ALSO:

getFieldName , PetscSectionSetFieldName

Source code at petsc4py/PETSc/Section.pyx:176

setFieldOffset(point, field, offset)

Set the offset for the DOFs on the given field at a point.

Not collective.

The user usually does not call this function, but uses setUp .
Parameters

	•		point ( int ) -- The point.
	•		field ( int ) -- The field.
	•		offset ( int ) -- The offset.

Return type

None

SEE ALSO:

getFieldOffset , PetscSectionSetFieldOffset

Source code at petsc4py/PETSc/Section.pyx:805

setNumFields(numFields)

Set the number of fields in a section.

Not collective.
Parameters

numFields ( int ) -- The number of fields.

Return type

None

SEE ALSO:

getNumFields , PetscSectionSetNumFields

Source code at petsc4py/PETSc/Section.pyx:138

setOffset(point, offset)

Set the offset for the DOFs associated with the given point.

Not collective.

The user usually does not call this function, but uses setUp .
Parameters

	•		point ( int ) -- The point.
	•		offset ( int ) -- The offset.

Return type

None

SEE ALSO:

getOffset , PetscSectionSetOffset

Source code at petsc4py/PETSc/Section.pyx:756

setPermutation(perm)

Set the permutation for [0, pEnd - pStart).

Not collective.
Parameters

perm ( IS ) -- The permutation of points.

Return type

None

SEE ALSO:

getPermutation , PetscSectionSetPermutation

Source code at petsc4py/PETSc/Section.pyx:294

setUp()

Calculate offsets.

Not collective.

Offsets are based on the number of degrees of freedom for each point.

SEE ALSO:

PetscSectionSetUp

Source code at petsc4py/PETSc/Section.pyx:96
Return type

None

view(viewer=None)

View the section.

Collective.
Parameters

viewer ( Viewer | None ) -- A Viewer to display the section.

Return type

None

SEE ALSO:

PetscSectionView

Source code at petsc4py/PETSc/Section.pyx:10

petsc4py.PETSc.Space

class petsc4py.PETSc.Space

Bases: Object

Function space object.

Enumerations

Image grohtml-288464-145.png

petsc4py.PETSc.Space.Type

class petsc4py.PETSc.Space.Type

Bases: object

The function space types.

Attributes Summary

Image grohtml-288464-146.png

Attributes Documentation
POINT: str = POINT

Object POINT of type str

POLYNOMIAL: str = POLYNOMIAL

Object POLYNOMIAL of type str

PTRIMMED: str = PTRIMMED

Object PTRIMMED of type str

SUBSPACE: str = SUBSPACE

Object SUBSPACE of type str

SUM: str = SUM

Object SUM of type str

TENSOR: str = TENSOR

Object TENSOR of type str

WXY: str = WXY

Object WXY of type str

Methods Summary

Image grohtml-288464-147.png

Methods Documentation
create(comm=None)

Create an empty Space object.

Collective.

The type can then be set with setType .
Parameters

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

Return type

Self

SEE ALSO:

PetscSpaceCreate

Source code at petsc4py/PETSc/Space.pyx:36

destroy()

Destroy the Space object.

Collective.

SEE ALSO:

PetscSpaceDestroy

Source code at petsc4py/PETSc/Space.pyx:59
Return type

Self

getDegree()

Return the polynomial degrees that 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

Source code at petsc4py/PETSc/Space.pyx:117

getDimension()

Return the number of basis vectors.

Not collective.

SEE ALSO:

PetscSpaceGetDimension

Source code at petsc4py/PETSc/Space.pyx:103
Return type

int

getNumComponents()

Return the number of components for this space.

Not collective.

SEE ALSO:

setNumComponents , PetscSpaceGetNumComponents

Source code at petsc4py/PETSc/Space.pyx:195
Return type

int

getNumVariables()

Return the number of variables for this space.

Not collective.

SEE ALSO:

setNumVariables , PetscSpaceGetNumVariables

Source code at petsc4py/PETSc/Space.pyx:163
Return type

int

getPTrimmedFormDegree()

Return the form degree of the trimmed polynomials.

Not collective.

SEE ALSO:

setPTrimmedFormDegree , PetscSpacePTrimmedGetFormDegree

Source code at petsc4py/PETSc/Space.pyx:546
Return type

int

getPointPoints()

Return the evaluation points for the space as the points of a quad.

Logically collective.

SEE ALSO:

setPointPoints , PetscSpacePointGetPoints

Source code at petsc4py/PETSc/Space.pyx:513
Return type

Quad

getPolynomialTensor()

Return whether a function space is a space of tensor polynomials.

Not collective.

Return 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).

SEE ALSO:

setPolynomialTensor , PetscSpacePolynomialGetTensor

Source code at petsc4py/PETSc/Space.pyx:448
Return type

bool

getSumConcatenate()

Return the concatenate flag for this space.

Not collective.

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.

SEE ALSO:

setSumConcatenate , PetscSpaceSumGetConcatenate

Source code at petsc4py/PETSc/Space.pyx:261
Return type

bool

getSumNumSubspaces()

Return the number of spaces in the sum.

Not collective.

SEE ALSO:

setSumNumSubspaces , PetscSpaceSumGetNumSubspaces

Source code at petsc4py/PETSc/Space.pyx:304
Return type

int

getSumSubspace(s)

Return a space in the sum.

Not collective.
Parameters

s ( int ) -- The space number.

Return type

Space

SEE ALSO:

setSumSubspace , PetscSpaceSumGetSubspace

Source code at petsc4py/PETSc/Space.pyx:318

getTensorNumSubspaces()

Return the number of spaces in the tensor product.

Not collective.

SEE ALSO:

setTensorNumSubspaces , PetscSpaceTensorGetNumSubspaces

Source code at petsc4py/PETSc/Space.pyx:376
Return type

int

getTensorSubspace(s)

Return a space 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()

Return the type of the space object.

Not collective.

SEE ALSO:

setType , PetscSpaceGetType

Source code at petsc4py/PETSc/Space.pyx:227
Return type

str

setDegree(degree, maxDegree)

Set the degree of approximation for this space.

Logically collective.

One of degree and maxDegree can be None .
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()

Set parameters in Space from the options database.

Collective.

SEE ALSO:

Working with PETSc options , PetscSpaceSetFromOptions

Source code at petsc4py/PETSc/Space.pyx:91
Return type

None

setNumComponents(nc)

Set the number of components for this space.

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)

Set the number of variables for this space.

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)

Set the form degree of the trimmed polynomials.

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)

Set the evaluation points for the space to be based on a quad.

Logically collective.

Sets the evaluation points for the space to coincide with the points of a quadrature rule.
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)

Set whether a function space is a space of tensor polynomials.

Logically collective.

Set to True for a function space which 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).
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)

Set the concatenate flag for this space.

Logically collective.

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)

Set the number of spaces in the sum.

Logically collective.
Parameters

numSumSpaces ( int ) -- The number of spaces.

Return type

None

SEE ALSO:

getSumNumSubspaces , PetscSpaceSumSetNumSubspaces

Source code at petsc4py/PETSc/Space.pyx:358

setSumSubspace(s, subsp)

Set a space in the sum.

Logically collective.
Parameters

	•		s ( int ) -- The space number.
	•		subsp ( Space ) -- The number of spaces.

Return type

None

SEE ALSO:

getSumSubspace , PetscSpaceSumSetSubspace

Source code at petsc4py/PETSc/Space.pyx:338

setTensorNumSubspaces(numTensSpaces)

Set the number of spaces in the tensor product.

Logically collective.
Parameters

numTensSpaces ( int ) -- The number of spaces.

Return type

None

SEE ALSO:

getTensorNumSubspaces , PetscSpaceTensorSetNumSubspaces

Source code at petsc4py/PETSc/Space.pyx:430

setTensorSubspace(s, subsp)

Set a space in the tensor product.

Logically collective.
Parameters

	•		s ( int ) -- The space number.
	•		subsp ( Space ) -- The number of spaces.

Return type

None

SEE ALSO:

getTensorSubspace , PetscSpaceTensorSetSubspace

Source code at petsc4py/PETSc/Space.pyx:390

setType(space_type)

Build a particular type of space.

Collective.
Parameters

space_type ( Type | str ) -- The kind of space.

Return type

Self

SEE ALSO:

getType , PetscSpaceSetType

Source code at petsc4py/PETSc/Space.pyx:241

setUp()

Construct data structures for the Space .

Collective.

SEE ALSO:

PetscSpaceSetUp

Source code at petsc4py/PETSc/Space.pyx:24
Return type

None

view(viewer=None)

View a Space .

Collective.
Parameters

viewer ( Viewer | None ) -- A Viewer to display the Space .

Return type

None

SEE ALSO:

PetscSpaceView

Source code at petsc4py/PETSc/Space.pyx:72

petsc4py.PETSc.Sys

class petsc4py.PETSc.Sys

Bases: object

System utilities.

Methods Summary

Image grohtml-288464-148.png

Methods Documentation
classmethod Print(*args, sep=' ', end='\n', comm=None, **kwargs)

Print output from the first processor of a communicator.

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

Source code at petsc4py/PETSc/Sys.pyx:155

classmethod getDefaultComm()

Get the default MPI communicator used to create PETSc objects.

Not collective.

SEE ALSO:

setDefaultComm

Source code at petsc4py/PETSc/Sys.pyx:116
Return type

Comm

classmethod getVersion(devel=False, date=False, author=False)

Return PETSc version information.

Not collective.
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 , PetscGetVersionNumber

Source code at petsc4py/PETSc/Sys.pyx:7

classmethod getVersionInfo()

Return PETSc version information.

Not collective.
Returns

info -- Dictionary with version information.

Return type

dict

SEE ALSO:

PetscGetVersion , PetscGetVersionNumber

Source code at petsc4py/PETSc/Sys.pyx:62

classmethod hasExternalPackage(package)

Return whether PETSc has support for external package.

Not collective.
Parameters

package ( str ) -- The external package name.

Return type

bool

SEE ALSO:

PetscHasExternalPackage

Source code at petsc4py/PETSc/Sys.pyx:449

classmethod infoAllow(flag, filename=None, mode='w')

Enables or disables PETSc info messages.

Not collective.
Parameters

	•		flag ( bool ) -- Whether to enable info messages.
	•		filename ( str \| None ) -- Name of a file where to dump output.
	•		mode ( str ) -- Write mode for file, by default "w" .

Return type

None

SEE ALSO:

PetscInfoAllow , PetscInfoSetFile

Source code at petsc4py/PETSc/Sys.pyx:392

classmethod isFinalized()

Return whether PETSc has been finalized.

Not collective.

SEE ALSO:

isInitialized

Source code at petsc4py/PETSc/Sys.pyx:101
Return type

bool

classmethod isInitialized()

Return whether PETSc has been initialized.

Not collective.

SEE ALSO:

isFinalized

Source code at petsc4py/PETSc/Sys.pyx:88
Return type

bool

classmethod popErrorHandler()

Remove the current error handler.

Logically collective.

SEE ALSO:

PetscPopErrorHandler

Source code at petsc4py/PETSc/Sys.pyx:366
Return type

None

classmethod popSignalHandler()

Remove the current signal handler.

Logically collective.

SEE ALSO:

PetscPopSignalHandler

Source code at petsc4py/PETSc/Sys.pyx:379
Return type

None

classmethod pushErrorHandler(errhandler)

Set the current error handler.

Logically collective.
Parameters

errhandler ( str ) -- The name of the error handler.

Return type

None

SEE ALSO:

PetscPushErrorHandler

Source code at petsc4py/PETSc/Sys.pyx:331

classmethod registerCitation(citation)

Not collective.
Parameters

citation ( str ) -- The BibTex citation entry to register.

Return type

None

SEE ALSO:

PetscCitationsRegister

Source code at petsc4py/PETSc/Sys.pyx:426

classmethod setDefaultComm(comm)

Set the default MPI communicator used to create PETSc objects.

Logically collective.
Parameters

comm ( Comm | None ) -- MPI communicator. If set to None , uses COMM_WORLD .

Return type

None

SEE ALSO:

getDefaultComm

Source code at petsc4py/PETSc/Sys.pyx:131

classmethod sleep(seconds=1.0)

Sleep some number of seconds.

Not collective.
Parameters

seconds ( float ) -- Time to sleep in seconds.

Return type

None

SEE ALSO:

PetscSleep

Source code at petsc4py/PETSc/Sys.pyx:310

classmethod splitOwnership(size, bsize=None, comm=None)

Given a global (or local) size determines a local (or global) size.

Collective.
Parameters

	•		size ( int \| tuple[int, int] ) -- Global size N or 2-tuple (n, N) with local and global sizes. Either of 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. That is, an array with 10 blocks and a block size of 3 will have a size of 30, not 10.

SEE ALSO:

PetscSplitOwnership

Source code at petsc4py/PETSc/Sys.pyx:261

classmethod syncFlush(comm=None)

Flush output from previous syncPrint calls.

Collective.
Parameters

comm ( Comm | None ) -- MPI communicator, defaults to getDefaultComm .

Return type

None

SEE ALSO:

PetscSynchronizedPrintf , PetscSynchronizedFlush

Source code at petsc4py/PETSc/Sys.pyx:240

classmethod syncPrint(*args, sep=' ', end='\n', flush=False,
comm=None, **kwargs)

Print synchronized output from several processors of a communicator.

Not collective.
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.
	•		flush ( bool ) -- Whether to flush output with syncFlush .
	•		comm ( Comm \| None ) -- MPI communicator, defaults to getDefaultComm .
	•		*kwargs ( Any* ) -- Keyword arguments.

Return type

None

SEE ALSO:

PetscSynchronizedPrintf , PetscSynchronizedFlush

Source code at petsc4py/PETSc/Sys.pyx:197

petsc4py.PETSc.TAO

class petsc4py.PETSc.TAO

Bases: Object

Optimization solver.

TAO is described in the PETSc manual .

SEE ALSO:

Tao

Enumerations

Image grohtml-288464-149.png

petsc4py.PETSc.TAO.BNCGType

class petsc4py.PETSc.TAO.BNCGType

Bases: object

TAO Bound Constrained Conjugate Gradient (BNCG) Update Type.

Attributes Summary

Image grohtml-288464-150.png

Attributes Documentation
DK: int = DK

Constant DK of type int

DY: int = DY

Constant DY of type int

FR: int = FR

Constant FR of type int

GD: int = GD

Constant GD of type int

HS: int = HS

Constant HS of type int

HZ: int = HZ

Constant HZ of type int

KD: int = KD

Constant KD of type int

PCGD: int = PCGD

Constant PCGD of type int

PRP: int = PRP

Constant PRP of type int

PRP_PLUS: int = PRP_PLUS

Constant PRP_PLUS of type int

SSML_BFGS: int = SSML_BFGS

Constant SSML_BFGS of type int

SSML_BRDN: int = SSML_BRDN

Constant SSML_BRDN of type int

SSML_DFP: int = SSML_DFP

Constant SSML_DFP of type int

petsc4py.PETSc.TAO.ConvergedReason

class petsc4py.PETSc.TAO.ConvergedReason

Bases: object

TAO solver termination reason.

SEE ALSO:

TaoConvergedReason

Attributes Summary

Image grohtml-288464-151.png

Attributes Documentation
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

DIVERGED_TR_REDUCTION: int = DIVERGED_TR_REDUCTION

Constant DIVERGED_TR_REDUCTION of type int

DIVERGED_USER: int = DIVERGED_USER

Constant DIVERGED_USER of type int

ITERATING: int = ITERATING

Constant ITERATING of type int

petsc4py.PETSc.TAO.Type

class petsc4py.PETSc.TAO.Type

Bases: object

TAO solver type.

SEE ALSO:

TaoType

Attributes Summary

Image grohtml-288464-152.png

Attributes Documentation
ADMM: str = ADMM

Object ADMM of type str

ALMM: str = ALMM

Object ALMM of type str

ASFLS: str = ASFLS

Object ASFLS of type str

ASILS: str = ASILS

Object ASILS of type str

BLMVM: str = BLMVM

Object BLMVM of type str

BMRM: str = BMRM

Object BMRM of type str

BNCG: str = BNCG

Object BNCG of type str

BNLS: str = BNLS

Object BNLS of type str

BNTL: str = BNTL

Object BNTL of type str

BNTR: str = BNTR

Object BNTR of type str

BQNKLS: str = BQNKLS

Object BQNKLS of type str

BQNKTL: str = BQNKTL

Object BQNKTL of type str

BQNKTR: str = BQNKTR

Object BQNKTR of type str

BQNLS: str = BQNLS

Object BQNLS of type str

BQPIP: str = BQPIP

Object BQPIP of type str

BRGN: str = BRGN

Object BRGN of type str

CG: str = CG

Object CG of type str

GPCG: str = GPCG

Object GPCG of type str

IPM: str = IPM

Object IPM of type str

LCL: str = LCL

Object LCL of type str

LMVM: str = LMVM

Object LMVM of type str

NLS: str = NLS

Object NLS of type str

NM: str = NM

Object NM of type str

NTL: str = NTL

Object NTL of type str

NTR: str = NTR

Object NTR of type str

OWLQN: str = OWLQN

Object OWLQN of type str

PDIPM: str = PDIPM

Object PDIPM of type str

POUNDERS: str = POUNDERS

Object POUNDERS of type str

PYTHON: str = PYTHON

Object PYTHON of type str

SHELL: str = SHELL

Object SHELL of type str

SSFLS: str = SSFLS

Object SSFLS of type str

SSILS: str = SSILS

Object SSILS of type str

TRON: str = TRON

Object TRON of type str

Methods Summary

Image grohtml-288464-153.png

Attributes Summary

Image grohtml-288464-154.png

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 , - TaoAppendOptionsPrefix

Source code at petsc4py/PETSc/TAO.pyx:213
Parameters

prefix ( str | None )

Return type

None

cancelMonitor()

Cancel all the monitors of the solver.

Logically collective.

SEE ALSO:

setMonitor , TaoMonitorCancel

Source code at petsc4py/PETSc/TAO.pyx:1220
Return type

None

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

Source code at petsc4py/PETSc/TAO.pyx:887

computeDualVariables(xl, xu)

Compute the dual vectors corresponding to variables' bounds.

Collective.

SEE ALSO:

TaoComputeDualVariables

Source code at petsc4py/PETSc/TAO.pyx:851
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

Source code at petsc4py/PETSc/TAO.pyx:810

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

Source code at petsc4py/PETSc/TAO.pyx:906

computeJacobian(x, J, P=None)

Compute the Jacobian.

Collective.
Parameters

	•		x ( Vec ) -- The parameter vector.
	•		J ( Mat ) -- The output Jacobian matrix.
	•		P ( Mat \| None ) -- The output Jacobian matrix used to construct the preconditioner.

Return type

None

SEE ALSO:

setJacobian , TaoComputeJacobian

Source code at petsc4py/PETSc/TAO.pyx:929

computeObjective(x)

Compute the value of the objective function.

Collective.
Parameters

x ( Vec ) -- The parameter vector.

Return type

float

SEE ALSO:

setObjective , TaoComputeObjective

Source code at petsc4py/PETSc/TAO.pyx:772

computeObjectiveGradient(x, g)

Compute the gradient of the objective function and its value.

Collective.
Parameters

	•		x ( Vec ) -- The parameter vector.
	•		g ( Vec ) -- The output gradient vector.

Return type

float

SEE ALSO:

setObjectiveGradient , setGradient , setObjective , - TaoComputeObjectiveAndGradient

Source code at petsc4py/PETSc/TAO.pyx:829

computeResidual(x, f)

Compute the residual.

Collective.
Parameters

	•		x ( Vec ) -- The parameter vector.
	•		f ( Vec ) -- The output vector.

Return type

None

SEE ALSO:

setResidual , TaoComputeResidual

Source code at petsc4py/PETSc/TAO.pyx:791

computeVariableBounds(xl, xu)

Compute the vectors corresponding to variables' bounds.

Collective.

SEE ALSO:

setVariableBounds , TaoComputeVariableBounds

Source code at petsc4py/PETSc/TAO.pyx:863
Parameters

	•		xl ( Vec )
	•		xu ( Vec )

Return type

None

create(comm=None)

Create a TAO solver.

Collective.
Parameters

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

Return type

Self

SEE ALSO:

Sys.getDefaultComm , TaoCreate

Source code at petsc4py/PETSc/TAO.pyx:145

createPython(context=None, comm=None)

Create an optimization solver 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 optimization solver type (TODO) , setType , setPythonContext , Type.PYTHON

Source code at petsc4py/PETSc/TAO.pyx:1662

destroy()

Destroy the solver.

Collective.

SEE ALSO:

TaoDestroy

Source code at petsc4py/PETSc/TAO.pyx:132
Return type

Self

getAppCtx()

Return the application context.

Source code at petsc4py/PETSc/TAO.pyx:286
Return type

Any

getBNCGType()

Return the type of the BNCG solver.

Not collective.

SEE ALSO:

setBNCGType , TaoBNCGGetType

Source code at petsc4py/PETSc/TAO.pyx:1416
Return type

BNCGType

getBRGNDampingVector()

Return the damping vector.

Not collective.

Source code at petsc4py/PETSc/TAO.pyx:1647
Return type

Vec

getBRGNSubsolver()

Return the subsolver inside the BRGN solver.

Not collective.

SEE ALSO:

TaoBRGNGetSubsolver

Source code at petsc4py/PETSc/TAO.pyx:1564
Return type

TAO

getConstraintTolerances()

Return the constraints tolerance parameters used in the convergence tests.

Not collective.
Returns

	•		catol ( float ) -- The absolute norm of the constraints.
	•		crtol ( float ) -- The relative norm of the constraints.

Return type

tuple [ float , float ]

SEE ALSO:

setConstraintTolerances , TaoGetConstraintTolerances

Source code at petsc4py/PETSc/TAO.pyx:1091

getConvergedReason()

Return the termination flag.

Not collective.

SEE ALSO:

setConvergedReason , TaoGetConvergedReason

Source code at petsc4py/PETSc/TAO.pyx:1165
Return type

ConvergedReason

getConvergenceTest()

Return the callback used to test for solver convergence.

Not collective.

SEE ALSO:

setConvergenceTest

Source code at petsc4py/PETSc/TAO.pyx:1140
Return type

tuple [ TAOConvergedFunction , tuple [ Any , ...], - dict [ str , Any ]]

getGradient()

Return the vector used to store the gradient and the evaluation callback.

Not collective.

SEE ALSO:

setGradient , setHessian , TaoGetGradient

Source code at petsc4py/PETSc/TAO.pyx:416
Return type

tuple [ Vec , TAOGradientFunction ]

getGradientNorm()

Return the matrix used to compute inner products.

Not collective.

SEE ALSO:

setGradientNorm , TaoGetGradientNorm

Source code at petsc4py/PETSc/TAO.pyx:1331
Return type

Mat

getHessian()

Return the matrices used to store the Hessian and the evaluation callback.

Not collective.

SEE ALSO:

setHessian , TaoGetHessian

Source code at petsc4py/PETSc/TAO.pyx:578
Return type

tuple [ Mat , Mat , TAOHessianFunction ]

getIterationNumber()

Return the current iteration number.

Not collective.

SEE ALSO:

setIterationNumber , TaoGetIterationNumber

Source code at petsc4py/PETSc/TAO.pyx:1443
Return type

int

getKSP()

Return the linear solver used by the nonlinear solver.

Not collective.

SEE ALSO:

TaoGetKSP

Source code at petsc4py/PETSc/TAO.pyx:1547
Return type

KSP

getLMVMH0()

Return the initial Hessian for the quasi-Newton approximation.

Not collective.

SEE ALSO:

setLMVMH0 , TaoLMVMGetH0

Source code at petsc4py/PETSc/TAO.pyx:1358
Return type

Mat

getLMVMH0KSP()

Return the KSP for the inverse of the initial Hessian approximation.

Not collective.

SEE ALSO:

setLMVMH0 , TaoLMVMGetH0KSP

Source code at petsc4py/PETSc/TAO.pyx:1373
Return type

KSP

getLineSearch()

Return the TAO Line Search object.

Not collective.

SEE ALSO:

TaoGetLineSearch

Source code at petsc4py/PETSc/TAO.pyx:1744
Return type

TAOLineSearch

getMaximumFunctionEvaluations()

Return the maximum number of objective evaluations within the solver.

Not collective.

SEE ALSO:

setMaximumFunctionEvaluations , - TaoGetMaximumFunctionEvaluations

Source code at petsc4py/PETSc/TAO.pyx:1051
Return type

int

getMaximumIterations()

Return the maximum number of solver iterations.

Not collective.

SEE ALSO:

setMaximumIterations , TaoGetMaximumIterations

Source code at petsc4py/PETSc/TAO.pyx:1024
Return type

int

getMonitor()

Return the callback used to monitor solver convergence.

Not collective.

SEE ALSO:

setMonitor

Source code at petsc4py/PETSc/TAO.pyx:1208
Return type

list [ tuple [ TAOMonitorFunction , tuple [ Any , ...], - dict [ str , Any ]]]

getObjectiveAndGradient()

Return the vector used to store the gradient and the evaluation callback.

Not collective.

SEE ALSO:

setObjectiveGradient , TaoGetObjectiveAndGradient

Source code at petsc4py/PETSc/TAO.pyx:462
Return type

tuple [ Vec , TAOObjectiveGradientFunction ]

getObjectiveValue()

Return the current value of the objective function.

Not collective.

SEE ALSO:

setObjective , TaoGetSolutionStatus

Source code at petsc4py/PETSc/TAO.pyx:1457
Return type

float

getOptionsPrefix()

Return the prefix used for searching for options in the database.

Not collective.

SEE ALSO:

Working with PETSc options , setOptionsPrefix , - TaoGetOptionsPrefix

Source code at petsc4py/PETSc/TAO.pyx:227
Return type

str

getPythonContext()

Return the instance of the class implementing the required Python methods.

Not collective.

SEE ALSO:

PETSc Python optimization solver type (TODO) , setPythonContext

Source code at petsc4py/PETSc/TAO.pyx:1699
Return type

Any

getPythonType()

Return the fully qualified Python name of the class used by the solver.

Not collective.

SEE ALSO:

PETSc Python optimization solver type (TODO) , setPythonContext , setPythonType , TaoPythonGetType

Source code at petsc4py/PETSc/TAO.pyx:1729
Return type

str

getSolution()

Return the vector holding the solution.

Not collective.

SEE ALSO:

setSolution , TaoGetSolution

Source code at petsc4py/PETSc/TAO.pyx:1304
Return type

Vec

getSolutionNorm()

Return the objective function value and the norms of gradient and constraints.

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.

Return type

tuple [ float , float , float ]

SEE ALSO:

getSolutionStatus , TaoGetSolutionStatus

Source code at petsc4py/PETSc/TAO.pyx:1487

getSolutionStatus()

Return the solution status.

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

Source code at petsc4py/PETSc/TAO.pyx:1512

getTolerances()

Return the tolerance parameters used in the solver convergence tests.

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

Source code at petsc4py/PETSc/TAO.pyx:987

getType()

Return the type of the solver.

Not collective.

SEE ALSO:

setType , TaoGetType

Source code at petsc4py/PETSc/TAO.pyx:185
Return type

str

getUpdate()

Return the callback to compute the update.

Not collective.

SEE ALSO:

setUpdate

Source code at petsc4py/PETSc/TAO.pyx:758
Return type

tuple [ TAOUpdateFunction , tuple [ Any , ...], dict [- str , Any ]]

getVariableBounds()

Return the upper and lower bounds vectors.

Not collective.

SEE ALSO:

setVariableBounds , TaoGetVariableBounds

Source code at petsc4py/PETSc/TAO.pyx:1388
Return type

tuple [ Vec , Vec ]

monitor(its=None, f=None, res=None, cnorm=None, step=None)

Monitor the solver.

Collective.

This function should be called without arguments, unless users want to modify the values internally stored by the solver.
Parameters

	•		its ( int ) -- Current number of iterations or - None to use the value stored internally by the solver.
	•		f ( float ) -- Current value of the objective function or None to use the value stored internally by the solver.
	•		res ( float ) -- Current value of the residual norm or None to use the value stored internally by the solver.
	•		cnorm ( float ) -- Current value of the constrains norm or None to use the value stored internally by the solver.
	•		step ( float ) -- Current value of the step or - None to use the value stored internally by the solver.

Return type

None

SEE ALSO:

setMonitor , TaoMonitor

Source code at petsc4py/PETSc/TAO.pyx:1234

setAppCtx(appctx)

Set the application context.

Source code at petsc4py/PETSc/TAO.pyx:282
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:1403
Parameters

cg_type ( BNCGType )

Return type

None

setBRGNDictionaryMatrix(D)

Set the dictionary matrix.

Collective.

SEE ALSO:

TaoBRGNSetDictionaryMatrix

Source code at petsc4py/PETSc/TAO.pyx:1635
Parameters

D ( Mat )

Return type

None

setBRGNRegularizerHessian(hessian, H=None, args=None,
kargs=None)

Set the callback to compute the regularizer Hessian.

Logically collective.

SEE ALSO:

TaoBRGNSetRegularizerHessianRoutine

Source code at petsc4py/PETSc/TAO.pyx:1595
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.

Logically collective.

SEE ALSO:

TaoBRGNSetRegularizerObjectiveAndGradientRoutine

Source code at petsc4py/PETSc/TAO.pyx:1579
Parameters

	•		args ( tuple[Any, ...] \| None )
	•		kargs ( dict[str, Any] \| None )

Return type

None

setBRGNRegularizerWeight(weight)

Set the regularizer weight.

Collective.

Source code at petsc4py/PETSc/TAO.pyx:1613
Parameters

weight ( float )

Return type

None

setBRGNSmoothL1Epsilon(epsilon)

Set the smooth L1 epsilon.

Collective.

SEE ALSO:

TaoBRGNSetL1SmoothEpsilon

Source code at petsc4py/PETSc/TAO.pyx:1622
Parameters

epsilon ( float )

Return type

None

setConstraintTolerances(catol=None, crtol=None)

Set the constraints tolerance parameters used in the solver convergence tests.

Collective.
Parameters

	•		catol ( float ) -- The absolute norm of the constraints, or DETERMINE to use the value when the object's type was set. Defaults to CURRENT .
	•		crtol ( float ) -- The relative norm of the constraints, or DETERMINE to use the value when the object's type was set. Defaults to CURRENT .

Return type

None

SEE ALSO:

getConstraintTolerances , TaoSetConstraintTolerances

Source code at petsc4py/PETSc/TAO.pyx:1065

setConstraints(constraints, C=None, args=None, kargs=None)

Set the callback to compute constraints.

Logically collective.
Parameters

	•		constraints ( TAOConstraintsFunction ) -- The callback.
	•		C ( Vec \| None ) -- The vector to hold the constraints.
	•		args ( tuple[Any, ...] \| None ) -- Positional arguments for 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:514

setConvergedReason(reason)

Set the termination flag.

Collective.

SEE ALSO:

getConvergedReason , TaoSetConvergedReason

Source code at petsc4py/PETSc/TAO.pyx:1152
Parameters

reason ( ConvergedReason )

Return type

None

setConvergenceTest(converged, args=None, kargs=None)

Set the callback used to test for solver convergence.

Logically collective.
Parameters

	•		converged ( TAOConvergedFunction \| None ) -- The callback. If None , reset to the default convergence test.
	•		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:1112

setEqualityConstraints(equality_constraints, c, args=None,
kargs=None)

Set equality constraints callback.

Logically collective.

SEE ALSO:

TaoSetEqualityConstraintsRoutine

Source code at petsc4py/PETSc/TAO.pyx:689
Parameters

	•		c ( Vec )
	•		args ( tuple[Any, ...] \| None )
	•		kargs ( dict[str, Any] \| None )

Return type

None

setFromOptions()

Configure the solver from the options database.

Collective.

SEE ALSO:

Working with PETSc options , TaoSetFromOptions

Source code at petsc4py/PETSc/TAO.pyx:241
Return type

None

setGradient(gradient, g=None, args=None, kargs=None)

Set the gradient evaluation callback.

Logically collective.
Parameters

	•		gradient ( TAOGradientFunction ) -- The gradient callback.
	•		g ( Vec \| None ) -- The vector to store the gradient.
	•		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:387

setGradientNorm(mat)

Set the matrix used to compute inner products.

Collective.

SEE ALSO:

getGradientNorm , TaoSetGradientNorm

Source code at petsc4py/PETSc/TAO.pyx:1319
Parameters

mat ( Mat )

Return type

None

setHessian(hessian, H=None, P=None, args=None, kargs=None)

Set the callback to compute the Hessian matrix.

Logically collective.
Parameters

	•		hessian ( TAOHessianFunction ) -- The Hessian callback.
	•		H ( Mat \| None ) -- The matrix to store the Hessian.
	•		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:

getHessian , setObjective , setObjectiveGradient , setGradient , TaoSetHessian

Source code at petsc4py/PETSc/TAO.pyx:543

setInitialTrustRegionRadius(radius)

Set the initial trust region radius.

Collective.

SEE ALSO:

TaoSetInitialTrustRegionRadius

Source code at petsc4py/PETSc/TAO.pyx:267
Parameters

radius ( float )

Return type

None

setIterationNumber(its)

Set the current iteration number.

Collective.

SEE ALSO:

getIterationNumber , TaoSetIterationNumber

Source code at petsc4py/PETSc/TAO.pyx:1430
Parameters

its ( int )

Return type

None

setJacobian(jacobian, J=None, P=None, args=None, kargs=None)

Set the callback to compute the Jacobian.

Logically collective.
Parameters

	•		jacobian ( TAOJacobianFunction ) -- The Jacobian callback.
	•		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:596

setJacobianDesign(jacobian_design, J=None, args=None,
kargs=None)

Set Jacobian design callback.

Logically collective.

SEE ALSO:

TaoSetJacobianDesignRoutine

Source code at petsc4py/PETSc/TAO.pyx:669
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)

Set Jacobian equality constraints callback.

Logically collective.

SEE ALSO:

TaoSetJacobianEqualityRoutine

Source code at petsc4py/PETSc/TAO.pyx:707
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)

Set the callback to compute the least-squares residual Jacobian.

Logically collective.
Parameters

	•		jacobian ( TAOJacobianResidualFunction ) -- The Jacobian callback.
	•		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:

setResidual , TaoSetJacobianResidualRoutine

Source code at petsc4py/PETSc/TAO.pyx:354

setJacobianState(jacobian_state, J=None, P=None, I=None,
args=None, kargs=None)

Set Jacobian state callback.

Logically collective.

SEE ALSO:

TaoSetJacobianStateRoutine

Source code at petsc4py/PETSc/TAO.pyx:645
Parameters

	•		J ( Mat \| None )
	•		P ( Mat \| None )
	•		I ( Mat \| None )
	•		args ( tuple[Any, ...] \| None )
	•		kargs ( dict[str, Any] \| None )

Return type

None

setLMVMH0(mat)

Set the initial Hessian for the quasi-Newton approximation.

Collective.

SEE ALSO:

getLMVMH0 , TaoLMVMSetH0

Source code at petsc4py/PETSc/TAO.pyx:1346
Parameters

mat ( Mat )

Return type

None

setMaximumFunctionEvaluations(mit)

Set the maximum number of objective evaluations within the solver.

Collective.

SEE ALSO:

setMaximumIterations , TaoSetMaximumFunctionEvaluations

Source code at petsc4py/PETSc/TAO.pyx:1038
Parameters

mit ( int )

Return type

None

setMaximumIterations(mit)

Set the maximum number of solver iterations.

Collective.

SEE ALSO:

setTolerances , TaoSetMaximumIterations

Source code at petsc4py/PETSc/TAO.pyx:1011
Parameters

mit ( int )

Return type

float

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

Set the callback used to monitor solver convergence.

Logically collective.
Parameters

	•		monitor ( TAOMonitorFunction ) -- 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:

getMonitor , TaoMonitorSet

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

setObjective(objective, args=None, kargs=None)

Set the objective function evaluation callback.

Logically collective.
Parameters

	•		objective ( TAOObjectiveFunction ) -- The objective function 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:

setGradient , setObjectiveGradient , TaoSetObjective

Source code at petsc4py/PETSc/TAO.pyx:302

setObjectiveGradient(objgrad, g=None, args=None, kargs=None)

Set the objective function and gradient evaluation callback.

Logically collective.
Parameters

	•		objgrad ( TAOObjectiveGradientFunction ) -- The objective function and gradient callback.
	•		g ( Vec \| None ) -- The vector to store the gradient.
	•		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 , setGradient , setHessian , getObjectiveAndGradient , TaoSetObjectiveAndGradient

Source code at petsc4py/PETSc/TAO.pyx:432

setOptionsPrefix(prefix)

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

Logically collective.

SEE ALSO:

Working with PETSc options , TaoSetOptionsPrefix

Source code at petsc4py/PETSc/TAO.pyx:199
Parameters

prefix ( str | None )

Return type

None

setPythonContext(context)

Set the instance of the class implementing the required Python methods.

Not collective.

SEE ALSO:

PETSc Python optimization solver type (TODO) , getPythonContext

Source code at petsc4py/PETSc/TAO.pyx:1687
Parameters

context ( Any )

Return type

None

setPythonType(py_type)

Set the fully qualified Python name of the class to be used.

Collective.

SEE ALSO:

PETSc Python optimization solver type (TODO) , setPythonContext , getPythonType , TaoPythonSetType

Source code at petsc4py/PETSc/TAO.pyx:1714
Parameters

py_type ( str )

Return type

None

setResidual(residual, R, args=None, kargs=None)

Set the residual evaluation callback for least-squares applications.

Logically collective.
Parameters

	•		residual ( TAOResidualFunction ) -- The residual callback.
	•		R ( Vec ) -- The vector to store the residual.
	•		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:327

setSolution(x)

Set the vector used to store the solution.

Collective.

SEE ALSO:

getSolution , TaoSetSolution

Source code at petsc4py/PETSc/TAO.pyx:290
Parameters

x ( Vec )

Return type

None

setStateDesignIS(state=None, design=None)

Set the index sets indicating state and design variables.

Collective.

SEE ALSO:

TaoSetStateDesignIS

Source code at petsc4py/PETSc/TAO.pyx:630
Parameters

	•		state ( IS \| None )
	•		design ( IS \| None )

Return type

None

setTolerances(gatol=None, grtol=None, gttol=None)

Set the tolerance parameters used in the solver convergence tests.

Collective.
Parameters

	•		gatol ( float ) -- The absolute norm of the gradient, or DETERMINE to use the value when the object's type was set. Defaults to CURRENT .
	•		grtol ( float ) -- The relative norm of the gradient with respect to the initial norm of the objective, or DETERMINE to use the value when the object's type was set. Defaults to CURRENT .
	•		gttol ( float ) -- The relative norm of the gradient with respect to the initial norm of the gradient, or DETERMINE to use the value when the object's type was set. Defaults to CURRENT .

Return type

None

SEE ALSO:

getTolerances , TaoSetTolerances

Source code at petsc4py/PETSc/TAO.pyx:954

setType(tao_type)

Set the type of the solver.

Logically collective.
Parameters

tao_type ( Type | str ) -- The type of the solver.

Return type

None

SEE ALSO:

getType , TaoSetType

Source code at petsc4py/PETSc/TAO.pyx:166

setUp()

Set up the internal data structures for using the solver.

Collective.

SEE ALSO:

TaoSetUp

Source code at petsc4py/PETSc/TAO.pyx:253
Return type

None

setUpdate(update, args=None, kargs=None)

Set the callback to compute update at each optimization step.

Logically collective.
Parameters

	•		update ( TAOUpdateFunction ) -- The update callback or None to reset it.
	•		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 , TaoSetUpdate

Source code at petsc4py/PETSc/TAO.pyx:729

setVariableBounds(varbounds, args=None, kargs=None)

Set the upper and lower bounds for the optimization problem.

Logically collective.
Parameters

	•		varbounds ( tuple[Vec, Vec] \| TAOVariableBoundsFunction ) -- Either a tuple of Vec or a TAOVariableBoundsFunction 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:

TaoSetVariableBounds , TaoSetVariableBoundsRoutine

Source code at petsc4py/PETSc/TAO.pyx:478

solve(x=None)

Solve the optimization problem.

Collective.
Parameters

x ( Vec | None ) -- The starting vector or None to use the vector stored internally.

Return type

None

SEE ALSO:

setSolution , getSolution , TaoSolve

Source code at petsc4py/PETSc/TAO.pyx:1285

view(viewer=None)

View the solver.

Collective.
Parameters

viewer ( Viewer | None ) -- A Viewer instance or - None for the default viewer.

Return type

None

SEE ALSO:

TaoView

Source code at petsc4py/PETSc/TAO.pyx:113

Attributes Documentation

appctx

Application context.

Source code at petsc4py/PETSc/TAO.pyx:1765

cnorm

Constraints norm.

Source code at petsc4py/PETSc/TAO.pyx:1834

converged

Boolean indicating if the solver has converged.

Source code at petsc4py/PETSc/TAO.pyx:1871

ctol

Broken.

Source code at petsc4py/PETSc/TAO.pyx:1809

diverged

Boolean indicating if the solver has failed.

Source code at petsc4py/PETSc/TAO.pyx:1876

ftol

Broken.

Source code at petsc4py/PETSc/TAO.pyx:1783

function

Objective value.

Source code at petsc4py/PETSc/TAO.pyx:1849

gnorm

Gradient norm.

Source code at petsc4py/PETSc/TAO.pyx:1829

gradient

Gradient vector.

Source code at petsc4py/PETSc/TAO.pyx:1854

gtol

Broken.

Source code at petsc4py/PETSc/TAO.pyx:1796

iterating

Boolean indicating if the solver has not converged yet.

Source code at petsc4py/PETSc/TAO.pyx:1866

its

Number of iterations.

Source code at petsc4py/PETSc/TAO.pyx:1824

ksp

Linear solver.

Source code at petsc4py/PETSc/TAO.pyx:1775

objective

Objective value.

Source code at petsc4py/PETSc/TAO.pyx:1844

reason

Converged reason.

Source code at petsc4py/PETSc/TAO.pyx:1861

solution

Solution vector.

Source code at petsc4py/PETSc/TAO.pyx:1839

petsc4py.PETSc.TAOLineSearch

class petsc4py.PETSc.TAOLineSearch

Bases: Object

TAO Line Search.

Enumerations

Image grohtml-288464-155.png

petsc4py.PETSc.TAOLineSearch.ConvergedReason

class petsc4py.PETSc.TAOLineSearch.ConvergedReason

Bases: object

TAO Line Search Termination Reasons.

Attributes Summary

Image grohtml-288464-156.png

Attributes Documentation
CONTINUE_SEARCH: int = CONTINUE_SEARCH

Constant CONTINUE_SEARCH of type int

FAILED_ASCENT: int = FAILED_ASCENT

Constant FAILED_ASCENT of type int

FAILED_BADPARAMETER: int = FAILED_BADPARAMETER

Constant FAILED_BADPARAMETER of type int

FAILED_INFORNAN: int = FAILED_INFORNAN

Constant FAILED_INFORNAN of type int

HALTED_LOWERBOUND: int = HALTED_LOWERBOUND

Constant HALTED_LOWERBOUND of type int

HALTED_MAXFCN: int = HALTED_MAXFCN

Constant HALTED_MAXFCN of type int

HALTED_OTHER: int = HALTED_OTHER

Constant HALTED_OTHER of type int

HALTED_RTOL: int = HALTED_RTOL

Constant HALTED_RTOL of type int

HALTED_UPPERBOUND: int = HALTED_UPPERBOUND

Constant HALTED_UPPERBOUND of type int

HALTED_USER: int = HALTED_USER

Constant HALTED_USER of type int

SUCCESS: int = SUCCESS

Constant SUCCESS of type int

SUCCESS_USER: int = SUCCESS_USER

Constant SUCCESS_USER of type int

petsc4py.PETSc.TAOLineSearch.Type

class petsc4py.PETSc.TAOLineSearch.Type

Bases: object

TAO Line Search Types.

Attributes Summary

Image grohtml-288464-157.png

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

Methods Summary

Image grohtml-288464-158.png

Methods Documentation
apply(x, g, s)

Performs a line-search in a given step direction.

Collective.

SEE ALSO:

TaoLineSearchApply

Source code at petsc4py/PETSc/TAO.pyx:2161
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

Source code at petsc4py/PETSc/TAO.pyx:1964

destroy()

Destroy the linesearch object.

Collective.

SEE ALSO:

TaoLineSearchDestroy

Source code at petsc4py/PETSc/TAO.pyx:1951
Return type

Self

getOptionsPrefix()

Return the prefix used for searching for options in the database.

Not collective.

SEE ALSO:

Working with PETSc options , setOptionsPrefix , - TaoLineSearchGetOptionsPrefix

Source code at petsc4py/PETSc/TAO.pyx:2056
Return type

str

getType()

Return the type of the linesearch.

Not collective.

SEE ALSO:

setType , TaoLineSearchGetType

Source code at petsc4py/PETSc/TAO.pyx:2004
Return type

str

setFromOptions()

Configure the linesearch from the options database.

Collective.

SEE ALSO:

Working with PETSc options , - TaoLineSearchSetFromOptions

Source code at petsc4py/PETSc/TAO.pyx:2018
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 ) -- Positional arguments for the callback.
	•		kargs ( dict[str, Any] \| None ) -- Keyword arguments for the callback.

Return type

None

SEE ALSO:

setObjective , setObjectiveGradient , setHessian , - TaoLineSearchSetGradientRoutine

Source code at petsc4py/PETSc/TAO.pyx:2095

setObjective(objective, args=None, kargs=None)

Set the objective function evaluation callback.

Logically collective.
Parameters

	•		objective ( TAOLSObjectiveFunction ) -- The objective function 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:

setGradient , setObjectiveGradient , - TaoLineSearchSetObjectiveRoutine

Source code at petsc4py/PETSc/TAO.pyx:2070

setObjectiveGradient(objgrad, args=None, kargs=None)

Set the objective function and gradient evaluation callback.

Logically collective.
Parameters

	•		objgrad ( TAOLSObjectiveGradientFunction ) -- The objective function and gradient callback.
	•		g -- The vector to store the gradient.
	•		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 , setGradient , setHessian , getObjectiveAndGradient , - TaoLineSearchSetObjectiveAndGradientRoutine

Source code at petsc4py/PETSc/TAO.pyx:2122

setOptionsPrefix(prefix=None)

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

Logically collective.

SEE ALSO:

Working with PETSc options , - TaoLineSearchSetOptionsPrefix

Source code at petsc4py/PETSc/TAO.pyx:2042
Parameters

prefix ( str | None )

Return type

None

setType(ls_type)

Set the type of the linesearch.

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

setUp()

Set up the internal data structures for using the linesearch.

Collective.

SEE ALSO:

TaoLineSearchSetUp

Source code at petsc4py/PETSc/TAO.pyx:2030
Return type

None

useTAORoutine(tao)

Use the objective and gradient evaluation routines from the given Tao object.

Logically collective.

SEE ALSO:

TaoLineSearchUseTaoRoutines

Source code at petsc4py/PETSc/TAO.pyx:2149
Parameters

tao ( TAO )

Return type

None

view(viewer=None)

View the linesearch object.

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

petsc4py.PETSc.TS

class petsc4py.PETSc.TS

Bases: Object

ODE integrator.

TS is described in the PETSc manual .

SEE ALSO:

Enumerations

Image grohtml-288464-159.png

petsc4py.PETSc.TS.ARKIMEXType

class petsc4py.PETSc.TS.ARKIMEXType

Bases: object

The ARKIMEX subtype.

Attributes Summary

Image grohtml-288464-160.png

Attributes Documentation
ARKIMEX1BEE: str = ARKIMEX1BEE

Object ARKIMEX1BEE of type str

ARKIMEX2C: str = ARKIMEX2C

Object ARKIMEX2C of type str

ARKIMEX2D: str = ARKIMEX2D

Object ARKIMEX2D of type str

ARKIMEX2E: str = ARKIMEX2E

Object ARKIMEX2E of type str

ARKIMEX3: str = ARKIMEX3

Object ARKIMEX3 of type str

ARKIMEX4: str = ARKIMEX4

Object ARKIMEX4 of type str

ARKIMEX5: str = ARKIMEX5

Object ARKIMEX5 of type str

ARKIMEXA2: str = ARKIMEXA2

Object ARKIMEXA2 of type str

ARKIMEXARS122: str = ARKIMEXARS122

Object ARKIMEXARS122 of type str

ARKIMEXARS443: str = ARKIMEXARS443

Object ARKIMEXARS443 of type str

ARKIMEXBPR3: str = ARKIMEXBPR3

Object ARKIMEXBPR3 of type str

ARKIMEXL2: str = ARKIMEXL2

Object ARKIMEXL2 of type str

ARKIMEXPRSSP2: str = ARKIMEXPRSSP2

Object ARKIMEXPRSSP2 of type str

petsc4py.PETSc.TS.ConvergedReason

class petsc4py.PETSc.TS.ConvergedReason

Bases: object

The reason the time step is converging.

Attributes Summary

Image grohtml-288464-161.png

Attributes Documentation
CONVERGED_EVENT: int = CONVERGED_EVENT

Constant CONVERGED_EVENT 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_TIME: int = CONVERGED_TIME

Constant CONVERGED_TIME of type int

CONVERGED_USER: int = CONVERGED_USER

Constant CONVERGED_USER of type int

DIVERGED_NONLINEAR_SOLVE: int = DIVERGED_NONLINEAR_SOLVE

Constant DIVERGED_NONLINEAR_SOLVE of type int

DIVERGED_STEP_REJECTED: int = DIVERGED_STEP_REJECTED

Constant DIVERGED_STEP_REJECTED of type int

ITERATING: int = ITERATING

Constant ITERATING of type int

petsc4py.PETSc.TS.DIRKType

class petsc4py.PETSc.TS.DIRKType

Bases: object

The DIRK subtype.

Attributes Summary

Image grohtml-288464-162.png

Attributes Documentation
DIRK657A: str = DIRK657A

Object DIRK657A of type str

DIRK658A: str = DIRK658A

Object DIRK658A of type str

DIRK7510SAL: str = DIRK7510SAL

Object DIRK7510SAL of type str

DIRK759A: str = DIRK759A

Object DIRK759A of type str

DIRK8614A: str = DIRK8614A

Object DIRK8614A of type str

DIRK8616SAL: str = DIRK8616SAL

Object DIRK8616SAL of type str

DIRKES122SAL: str = DIRKES122SAL

Object DIRKES122SAL of type str

DIRKES213SAL: str = DIRKES213SAL

Object DIRKES213SAL of type str

DIRKES324SAL: str = DIRKES324SAL

Object DIRKES324SAL of type str

DIRKES325SAL: str = DIRKES325SAL

Object DIRKES325SAL of type str

DIRKES648SA: str = DIRKES648SA

Object DIRKES648SA of type str

DIRKES7510SA: str = DIRKES7510SA

Object DIRKES7510SA of type str

DIRKES8516SAL: str = DIRKES8516SAL

Object DIRKES8516SAL of type str

DIRKS212: str = DIRKS212

Object DIRKS212 of type str

DIRKS659A: str = DIRKS659A

Object DIRKS659A of type str

DIRKS7511SAL: str = DIRKS7511SAL

Object DIRKS7511SAL of type str

petsc4py.PETSc.TS.EquationType

class petsc4py.PETSc.TS.EquationType

Bases: object

Distinguishes among types of explicit and implicit equations.

Attributes Summary

Image grohtml-288464-163.png

Attributes Documentation
DAE_IMPLICIT_INDEX1: int = DAE_IMPLICIT_INDEX1

Constant DAE_IMPLICIT_INDEX1 of type int

DAE_IMPLICIT_INDEX2: int = DAE_IMPLICIT_INDEX2

Constant DAE_IMPLICIT_INDEX2 of type int

DAE_IMPLICIT_INDEX3: int = DAE_IMPLICIT_INDEX3

Constant DAE_IMPLICIT_INDEX3 of type int

DAE_IMPLICIT_INDEXHI: int = DAE_IMPLICIT_INDEXHI

Constant DAE_IMPLICIT_INDEXHI of type int

DAE_SEMI_EXPLICIT_INDEX1: int = DAE_SEMI_EXPLICIT_INDEX1

Constant DAE_SEMI_EXPLICIT_INDEX1 of type int

DAE_SEMI_EXPLICIT_INDEX2: int = DAE_SEMI_EXPLICIT_INDEX2

Constant DAE_SEMI_EXPLICIT_INDEX2 of type int

DAE_SEMI_EXPLICIT_INDEX3: int = DAE_SEMI_EXPLICIT_INDEX3

Constant DAE_SEMI_EXPLICIT_INDEX3 of type int

DAE_SEMI_EXPLICIT_INDEXHI: int =
DAE_SEMI_EXPLICIT_INDEXHI

Constant DAE_SEMI_EXPLICIT_INDEXHI of type int

EXPLICIT: int = EXPLICIT

Constant EXPLICIT of type int

IMPLICIT: int = IMPLICIT

Constant IMPLICIT of type int

ODE_EXPLICIT: int = ODE_EXPLICIT

Constant ODE_EXPLICIT of type int

ODE_IMPLICIT: int = ODE_IMPLICIT

Constant ODE_IMPLICIT of type int

UNSPECIFIED: int = UNSPECIFIED

Constant UNSPECIFIED of type int

petsc4py.PETSc.TS.ExactFinalTime

class petsc4py.PETSc.TS.ExactFinalTime

Bases: object

The method for ending time stepping.

Attributes Summary

Image grohtml-288464-164.png

Attributes Documentation
INTERPOLATE: int = INTERPOLATE

Constant INTERPOLATE of type int

MATCHSTEP: int = MATCHSTEP

Constant MATCHSTEP of type int

STEPOVER: int = STEPOVER

Constant STEPOVER of type int

UNSPECIFIED: int = UNSPECIFIED

Constant UNSPECIFIED of type int

petsc4py.PETSc.TS.ProblemType

class petsc4py.PETSc.TS.ProblemType

Bases: object

Distinguishes linear and nonlinear problems.

Attributes Summary

Image grohtml-288464-165.png

Attributes Documentation
LINEAR: int = LINEAR

Constant LINEAR of type int

NONLINEAR: int = NONLINEAR

Constant NONLINEAR of type int

petsc4py.PETSc.TS.RKType

class petsc4py.PETSc.TS.RKType

Bases: object

The RK subtype.

Attributes Summary

Image grohtml-288464-166.png

Attributes Documentation
RK1FE: str = RK1FE

Object RK1FE of type str

RK2A: str = RK2A

Object RK2A of type str

RK2B: str = RK2B

Object RK2B of type str

RK3: str = RK3

Object RK3 of type str

RK3BS: str = RK3BS

Object RK3BS of type str

RK4: str = RK4

Object RK4 of type str

RK5BS: str = RK5BS

Object RK5BS of type str

RK5DP: str = RK5DP

Object RK5DP of type str

RK5F: str = RK5F

Object RK5F of type str

RK6VR: str = RK6VR

Object RK6VR of type str

RK7VR: str = RK7VR

Object RK7VR of type str

RK8VR: str = RK8VR

Object RK8VR of type str

petsc4py.PETSc.TS.Type

class petsc4py.PETSc.TS.Type

Bases: object

The time stepping method.

Attributes Summary

Image grohtml-288464-167.png

Attributes Documentation
ALPHA: str = ALPHA

Object ALPHA of type str

ALPHA2: str = ALPHA2

Object ALPHA2 of type str

ARKIMEX: str = ARKIMEX

Object ARKIMEX of type str

BASICSYMPLECTIC: str = BASICSYMPLECTIC

Object BASICSYMPLECTIC of type str

BDF: str = BDF

Object BDF of type str

BE: str = BE

Object BE of type str

BEULER: str = BEULER

Object BEULER of type str

CN: str = CN

Object CN of type str

CRANK_NICOLSON: str = CRANK_NICOLSON

Object CRANK_NICOLSON of type str

DIRK: str = DIRK

Object DIRK of type str

DISCGRAD: str = DISCGRAD

Object DISCGRAD of type str

EIMEX: str = EIMEX

Object EIMEX of type str

EULER: str = EULER

Object EULER of type str

FE: str = FE

Object FE of type str

GLEE: str = GLEE

Object GLEE of type str

GLLE: str = GLLE

Object GLLE of type str

MIMEX: str = MIMEX

Object MIMEX of type str

MPRK: str = MPRK

Object MPRK of type str

PSEUDO: str = PSEUDO

Object PSEUDO of type str

PYTHON: str = PYTHON

Object PYTHON of type str

RADAU5: str = RADAU5

Object RADAU5 of type str

RK: str = RK

Object RK of type str

ROSW: str = ROSW

Object ROSW of type str

RUNGE_KUTTA: str = RUNGE_KUTTA

Object RUNGE_KUTTA of type str

SSP: str = SSP

Object SSP of type str

SUNDIALS: str = SUNDIALS

Object SUNDIALS of type str

TH: str = TH

Object TH of type str

THETA: str = THETA

Object THETA of type str

Methods Summary

Image grohtml-288464-168.png

Attributes Summary

Image grohtml-288464-169.png

Methods Documentation
adjointReset()

Reset a TS , removing any allocated vectors and matrices.

Collective.

SEE ALSO:

TSAdjointReset

Source code at petsc4py/PETSc/TS.pyx:2849
Return type

None

adjointSetSteps(adjoint_steps)

Set the number of steps the adjoint solver should take backward in time.

Logically collective.
Parameters

adjoint_steps ( int ) -- The number of steps to take.

Return type

None

SEE ALSO:

TSAdjointSetSteps

Source code at petsc4py/PETSc/TS.pyx:2795

adjointSetUp()

Set up the internal data structures for the later use of an adjoint solver.

Collective.

SEE ALSO:

TSAdjointSetUp

Source code at petsc4py/PETSc/TS.pyx:2813
Return type

None

adjointSolve()

Solve the discrete adjoint problem for an ODE/DAE.

Collective.

SEE ALSO:

TSAdjointSolve

Source code at petsc4py/PETSc/TS.pyx:2825
Return type

None

adjointStep()

Step one time step backward in the adjoint run.

Collective.

SEE ALSO:

TSAdjointStep

Source code at petsc4py/PETSc/TS.pyx:2837
Return type

None

appendOptionsPrefix(prefix)

Append to the prefix used for all the TS options.

Logically collective.
Parameters

prefix ( str | None ) -- The prefix to append to the current prefix.

Return type

None

Notes

A hyphen must not be given at the beginning of the prefix name.

SEE ALSO:

Working with PETSc options , TSAppendOptionsPrefix

Source code at petsc4py/PETSc/TS.pyx:539

clone()

Return a shallow clone of the TS object.

Collective.

SEE ALSO:

TSClone

Source code at petsc4py/PETSc/TS.pyx:243
Return type

computeI2Function(t, x, xdot, xdotdot, f)

Evaluate the DAE residual in implicit form.

Collective.
Parameters

	•		t ( float ) -- The current time.
	•		x ( Vec ) -- The state vector.
	•		xdot ( Vec ) -- The time derivative of the state vector.
	•		xdotdot ( Vec ) -- The second time derivative of the state vector.
	•		f ( Vec ) -- The vector into which the residual is stored.

Return type

None

SEE ALSO:

TSComputeI2Function

Source code at petsc4py/PETSc/TS.pyx:1142

computeI2Jacobian(t, x, xdot, xdotdot, v, a, J, P=None)

Evaluate the Jacobian of the DAE.

Collective.

If F(t, U, V, A)=0 is the DAE, the required Jacobian is dF/dU + v dF/dV + a dF/dA .
Parameters

	•		t ( float ) -- The current time.
	•		x ( Vec ) -- The state vector.
	•		xdot ( Vec ) -- The time derivative of the state vector.
	•		xdotdot ( Vec ) -- The second time derivative of the state vector.
	•		v ( float ) -- The shift to apply to the first derivative.
	•		a ( float ) -- The shift to apply to the second derivative.
	•		J ( Mat ) -- The matrix into which the Jacobian is computed.
	•		P ( Mat \| None ) -- The optional matrix to use for building a preconditioner matrix.

Return type

None

SEE ALSO:

TSComputeI2Jacobian

Source code at petsc4py/PETSc/TS.pyx:1169

computeIFunction(t, x, xdot, f, imex=False)

Evaluate the DAE residual written in implicit form.

Collective.
Parameters

	•		t ( float ) -- The current time.
	•		x ( Vec ) -- The state vector.
	•		xdot ( Vec ) -- The time derivative of the state vector.
	•		f ( Vec ) -- The vector into which the residual is stored.
	•		imex ( bool ) -- A flag which indicates if the RHS should be kept separate.

Return type

None

SEE ALSO:

TSComputeIFunction

Source code at petsc4py/PETSc/TS.pyx:927

computeIJacobian(t, x, xdot, a, J, P=None, imex=False)

Evaluate the Jacobian of the DAE.

Collective.

If F(t, U, Udot)=0 is the DAE, the required Jacobian is dF/dU + shift*dF/dUdot
Parameters

	•		t ( float ) -- The current time.
	•		x ( Vec ) -- The state vector.
	•		xdot ( Vec ) -- The time derivative of the state vector.
	•		a ( float ) -- The shift to apply
	•		J ( Mat ) -- The matrix into which the Jacobian is computed.
	•		P ( Mat \| None ) -- The optional matrix to use for building a preconditioner matrix.
	•		imex ( bool ) -- A flag which indicates if the RHS should be kept separate.

Return type

None

SEE ALSO:

TSComputeIJacobian

Source code at petsc4py/PETSc/TS.pyx:957

computeIJacobianP(t, x, xdot, a, J, imex=False)

Evaluate the Jacobian with respect to parameters.

Collective.
Parameters

	•		t ( float ) -- The current time.
	•		x ( Vec ) -- The state vector.
	•		xdot ( Vec ) -- The time derivative of the state vector.
	•		a ( float ) -- The shift to apply
	•		J ( Mat ) -- The matrix into which the Jacobian is computed.
	•		imex ( bool ) -- A flag which indicates if the RHS should be kept separate.

Return type

None

SEE ALSO:

TSComputeIJacobianP

Source code at petsc4py/PETSc/TS.pyx:997

computeRHSFunction(t, x, f)

Evaluate the right-hand side function.

Collective.
Parameters

	•		t ( float ) -- The time at which to evaluate the RHS.
	•		x ( Vec ) -- The state vector.
	•		f ( Vec ) -- The Vec into which the RHS is computed.

Return type

None

SEE ALSO:

TSComputeRHSFunction

Source code at petsc4py/PETSc/TS.pyx:674

computeRHSFunctionLinear(t, x, f)

Evaluate the right-hand side via the user-provided Jacobian.

Collective.
Parameters

	•		t ( float ) -- The time at which to evaluate the RHS.
	•		x ( Vec ) -- The state vector.
	•		f ( Vec ) -- The Vec into which the RHS is computed.

Return type

None

SEE ALSO:

TSComputeRHSFunctionLinear

Source code at petsc4py/PETSc/TS.pyx:696

computeRHSJacobian(t, x, J, P=None)

Compute the Jacobian matrix that has been set with setRHSJacobian .

Collective.
Parameters

	•		t ( float ) -- The time at which to evaluate the Jacobian.
	•		x ( Vec ) -- The state vector.
	•		J ( Mat ) -- The matrix into which the Jacobian is computed.
	•		P ( Mat \| None ) -- The optional matrix to use for building a preconditioner matrix.

Return type

None

SEE ALSO:

TSComputeRHSJacobian

Source code at petsc4py/PETSc/TS.pyx:718

computeRHSJacobianConstant(t, x, J, P=None)

Reuse a Jacobian that is time-independent.

Collective.
Parameters

	•		t ( float ) -- The time at which to evaluate the Jacobian.
	•		x ( Vec ) -- The state vector.
	•		J ( Mat ) -- A pointer to the stored Jacobian.
	•		P ( Mat \| None ) -- An optional pointer to the preconditioner matrix.

Return type

None

SEE ALSO:

TSComputeRHSJacobianConstant

Source code at petsc4py/PETSc/TS.pyx:744

computeRHSJacobianP(t, x, J)

Run the user-defined JacobianP function.

Collective.
Parameters

	•		t ( float ) -- The time at which to compute the Jacobian.
	•		x ( Vec ) -- The solution at which to compute the Jacobian.
	•		J ( Mat ) -- The output Jacobian matrix.

Return type

None

SEE ALSO:

TSComputeRHSJacobianP

Source code at petsc4py/PETSc/TS.pyx:2773

create(comm=None)

Create an empty TS .

Collective.

The problem type can then be set with setProblemType and the type of solver can then be set with setType .
Parameters

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

Return type

Self

SEE ALSO:

TSCreate

Source code at petsc4py/PETSc/TS.pyx:219

createPython(context=None, comm=None)

Create 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 at petsc4py/PETSc/TS.pyx:2863

createQuadratureTS(forward=True)

Create a sub TS that evaluates integrals over time.

Collective.
Parameters

forward ( bool ) -- Enable to evaluate forward in time.

Return type

SEE ALSO:

TSCreateQuadratureTS

Source code at petsc4py/PETSc/TS.pyx:2692

destroy()

Destroy the TS that was created with create .

Collective.

SEE ALSO:

TSDestroy

Source code at petsc4py/PETSc/TS.pyx:206
Return type

Self

getARKIMEXType()

Return the Type.ARKIMEX scheme.

Not collective.

SEE ALSO:

TSARKIMEXGetType

Source code at petsc4py/PETSc/TS.pyx:389
Return type

str

getAlphaParams()

Return the algorithmic parameters for Type.ALPHA .

Not collective.

SEE ALSO:

TSAlphaGetParams

Source code at petsc4py/PETSc/TS.pyx:3070
Return type

tuple [ float , float , float ]

getAppCtx()

Return the application context.

Source code at petsc4py/PETSc/TS.pyx:589
Return type

Any

getConvergedReason()

Return the reason the TS step was stopped.

Not collective.

Can only be called once solve is complete.

SEE ALSO:

TSGetConvergedReason

Source code at petsc4py/PETSc/TS.pyx:2090
Return type

ConvergedReason

getCostGradients()

Return the cost gradients.

Not collective.

SEE ALSO:

setCostGradients , TSGetCostGradients

Source code at petsc4py/PETSc/TS.pyx:2634
Return type

tuple [ list [ Vec ], list [ Vec ]]

getCostIntegral()

Return a vector of values of the integral term in the cost functions.

Not collective.

SEE ALSO:

TSGetCostIntegral

Source code at petsc4py/PETSc/TS.pyx:2573
Return type

Vec

getDIRKType()

Return the Type.DIRK scheme.

Not collective.

SEE ALSO:

setDIRKType , TSDIRKGetType

Source code at petsc4py/PETSc/TS.pyx:426
Return type

str

getDM()

Return the DM associated with the TS .

Not collective.

Only valid if nonlinear solvers or preconditioners are used which use the DM .

SEE ALSO:

TSGetDM

Source code at petsc4py/PETSc/TS.pyx:1589
Return type

getEquationType()

Get the type of the equation that TS is solving.

Not collective.

SEE ALSO:

TSGetEquationType

Source code at petsc4py/PETSc/TS.pyx:488
Return type

EquationType

getI2Function()

Return the vector and function which computes the residual.

Not collective.

SEE ALSO:

TSGetI2Function

Source code at petsc4py/PETSc/TS.pyx:1218
Return type

tuple [ Vec , TSI2Function ]

getI2Jacobian()

Return the matrices and function which computes the Jacobian.

Not collective.

SEE ALSO:

TSGetI2Jacobian

Source code at petsc4py/PETSc/TS.pyx:1234
Return type

tuple [ Mat , Mat , TSI2Jacobian ]

getIFunction()

Return the vector and function which computes the implicit residual.

Not collective.

SEE ALSO:

TSGetIFunction

Source code at petsc4py/PETSc/TS.pyx:1031
Return type

tuple [ Vec , TSIFunction ]

getIJacobian()

Return the matrices and function which computes the implicit Jacobian.

Not collective.

SEE ALSO:

TSGetIJacobian

Source code at petsc4py/PETSc/TS.pyx:1047
Return type

tuple [ Mat , Mat , TSIJacobian ]

getKSP()

Return the KSP associated with the TS .

Not collective.

SEE ALSO:

TSGetKSP

Source code at petsc4py/PETSc/TS.pyx:1572
Return type

KSP

getKSPIterations()

Return the total number of linear iterations used by the TS .

Not collective.

This counter is reset to zero for each successive call to solve .

SEE ALSO:

TSGetKSPIterations

Source code at petsc4py/PETSc/TS.pyx:1857
Return type

int

getMaxSteps()

Return the maximum number of steps to use.

Not collective.

SEE ALSO:

TSGetMaxSteps

Source code at petsc4py/PETSc/TS.pyx:1826
Return type

int

getMaxTime()

Return the maximum (final) time.

Not collective.

Defaults to 5 .

SEE ALSO:

TSGetMaxTime

Source code at petsc4py/PETSc/TS.pyx:1790
Return type

float

getMonitor()

Return the monitor.

Not collective.

SEE ALSO:

setMonitor

Source code at petsc4py/PETSc/TS.pyx:2142
Return type

list [ tuple [ TSMonitorFunction , tuple [ Any , ...], - dict [ str , Any ]]]

getNumEvents()

Return the number of events.

Logically collective.

SEE ALSO:

TSGetNumEvents

Source code at petsc4py/PETSc/TS.pyx:2289
Return type

int

getOptionsPrefix()

Return the prefix used for all the TS options.

Not collective.

SEE ALSO:

TSGetOptionsPrefix

Source code at petsc4py/PETSc/TS.pyx:525
Return type

str

getPostStep()

Return the poststep function.

Source code at petsc4py/PETSc/TS.pyx:2382
Return type

tuple [ TSPostStepFunction , tuple [ Any , ...] | None , dict [ str , Any ] | None ]

getPreStep()

Return the prestep function.

Not collective.

SEE ALSO:

setPreStep

Source code at petsc4py/PETSc/TS.pyx:2338
Return type

tuple [ TSPreStepFunction , tuple [ Any , ...] | None , - dict [ str , Any ] | None ]

getPrevTime()

Return the starting time of the previously completed step.

Not collective.

SEE ALSO:

TSGetPrevTime

Source code at petsc4py/PETSc/TS.pyx:1664
Return type

float

getProblemType()

Return the type of problem to be solved.

Not collective.

SEE ALSO:

TSGetProblemType

Source code at petsc4py/PETSc/TS.pyx:457
Return type

ProblemType

getPythonContext()

Return 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:2900
Return type

Any

getPythonType()

Return the fully qualified Python name of the class used by the solver.

Not collective.

SEE ALSO:

PETSc Python ode-integrator type (TODO) , setPythonContext , setPythonType , TSPythonGetType

Source code at petsc4py/PETSc/TS.pyx:2929
Return type

str

getQuadratureTS()

Return the sub TS that evaluates integrals over time.

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

getRHSFunction()

Return the vector where the rhs is stored and the function used to compute it.

Not collective.

SEE ALSO:

TSGetRHSFunction

Source code at petsc4py/PETSc/TS.pyx:770
Return type

tuple [ Vec , TSRHSFunction ]

getRHSJacobian()

Return the Jacobian and the function used to compute them.

Not collective.

SEE ALSO:

TSGetRHSJacobian

Source code at petsc4py/PETSc/TS.pyx:786
Return type

tuple [ Mat , Mat , TSRHSJacobian ]

getRKType()

Return the Type.RK scheme.

Not collective.

SEE ALSO:

TSRKGetType

Source code at petsc4py/PETSc/TS.pyx:375
Return type

str

getSNES()

Return the SNES associated with the TS .

Not collective.

SEE ALSO:

TSGetSNES

Source code at petsc4py/PETSc/TS.pyx:1557
Return type

SNES

getSNESFailures()

Return the total number of failed SNES solves in the TS .

Not collective.

This counter is reset to zero for each successive call to solve .

SEE ALSO:

TSGetSNESFailures

Source code at petsc4py/PETSc/TS.pyx:1931
Return type

int

getSNESIterations()

Return the total number of nonlinear iterations used by the TS .

Not collective.

This counter is reset to zero for each successive call to solve .

SEE ALSO:

TSGetSNESIterations

Source code at petsc4py/PETSc/TS.pyx:1840
Return type

int

getSolution()

Return 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:1428
Return type

Vec

getSolution2()

Return the solution and time derivative 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. These vectors are not changed until the solution at the next timestep has been calculated.

SEE ALSO:

TS2GetSolution

Source code at petsc4py/PETSc/TS.pyx:1466
Return type

tuple [ Vec , Vec ]

getSolveTime()

Return the time after a call to solve .

Not collective.

This time corresponds to the final time set with setMaxTime .

SEE ALSO:

TSGetSolveTime

Source code at petsc4py/PETSc/TS.pyx:1678
Return type

float

getStepLimits()

Return the minimum and maximum allowed time step sizes.

Not collective.

SEE ALSO:

TSAdaptGetStepLimits

Source code at petsc4py/PETSc/TS.pyx:2523
Return type

tuple [ float , float ]

getStepNumber()

Return the number of time steps completed.

Not collective.

SEE ALSO:

TSGetStepNumber

Source code at petsc4py/PETSc/TS.pyx:1754
Return type

int

getStepRejections()

Return the total number of rejected steps.

Not collective.

This counter is reset to zero for each successive call to solve .

SEE ALSO:

TSGetStepRejections

Source code at petsc4py/PETSc/TS.pyx:1896
Return type

int

getTheta()

Return the abscissa of the stage in (0, 1] for Type.THETA .

Not collective.

SEE ALSO:

TSThetaGetTheta

Source code at petsc4py/PETSc/TS.pyx:2967
Return type

float

getThetaEndpoint()

Return whether the endpoint variable of Type.THETA is used.

Not collective.

SEE ALSO:

TSThetaGetEndpoint

Source code at petsc4py/PETSc/TS.pyx:2999
Return type

bool

getTime()

Return the time of the most recently completed step.

Not collective.

When called during time step evaluation (e.g. during residual evaluation or via hooks set using setPreStep or setPostStep ), the time returned is at the start of the step.

SEE ALSO:

TSGetTime

Source code at petsc4py/PETSc/TS.pyx:1646
Return type

float

getTimeSpan()

Return the time span.

Not collective.

SEE ALSO:

TSGetTimeSpan

Source code at petsc4py/PETSc/TS.pyx:1521
Return type

ArrayReal

getTimeSpanSolutions()

Return the solutions at the times in the time span.

Not collective.

SEE ALSO:

setTimeSpan , TSGetTimeSpanSolutions

Source code at petsc4py/PETSc/TS.pyx:1537
Return type

list [ Vec ]

getTimeStep()

Return the duration of the current timestep.

Not collective.

SEE ALSO:

TSGetTimeStep

Source code at petsc4py/PETSc/TS.pyx:1713
Return type

float

getTolerances()

Return the tolerances for local truncation error.

Logically collective.
Returns

	•		rtol ( float ) -- the relative tolerance
	•		atol ( float ) -- the absolute tolerance

Return type

tuple [ float , float ]

SEE ALSO:

TSGetTolerances

Source code at petsc4py/PETSc/TS.pyx:2013

getType()

Return the TS type.

Not collective.

SEE ALSO:

TSGetType

Source code at petsc4py/PETSc/TS.pyx:361
Return type

str

interpolate(t, u)

Interpolate the solution to a given time.

Collective.
Parameters

	•		t ( float ) -- The time to interpolate.
	•		u ( Vec ) -- The state vector to interpolate.

Return type

None

SEE ALSO:

TSInterpolate

Source code at petsc4py/PETSc/TS.pyx:2480

load(viewer)

Load a TS that has been stored in binary with view .

Collective.
Parameters

viewer ( Viewer ) -- The visualization context.

Return type

None

SEE ALSO:

TSLoad

Source code at petsc4py/PETSc/TS.pyx:189

monitor(step, time, u=None)

Monitor the solve.

Collective.
Parameters

	•		step ( int ) -- The step number that has just completed.
	•		time ( float ) -- The model time of the state.
	•		u ( Vec \| None ) -- The state at the current model time.

Return type

None

SEE ALSO:

TSMonitor

Source code at petsc4py/PETSc/TS.pyx:2169

monitorCancel()

Clear all the monitors that have been set.

Logically collective.

SEE ALSO:

TSMonitorCancel

Source code at petsc4py/PETSc/TS.pyx:2154
Return type

None

removeTrajectory()

Remove the internal TS trajectory object.

Collective.

SEE ALSO:

TSRemoveTrajectory

Source code at petsc4py/PETSc/TS.pyx:2561
Return type

None

reset()

Reset the TS , removing any allocated vectors and matrices.

Collective.

SEE ALSO:

TSReset

Source code at petsc4py/PETSc/TS.pyx:2398
Return type

None

restartStep()

Flag the solver to restart the next step.

Collective.

Multistep methods like TSBDF or Runge-Kutta methods with FSAL property require restarting the solver in the event of discontinuities. These discontinuities may be introduced as a consequence of explicitly modifications to the solution vector (which PETSc attempts to detect and handle) or problem coefficients (which PETSc is not able to detect). 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 code at petsc4py/PETSc/TS.pyx:2426
Return type

None

rollBack()

Roll back one time step.

Collective.

SEE ALSO:

TSRollBack

Source code at petsc4py/PETSc/TS.pyx:2449
Return type

None

setARKIMEXFastSlowSplit(flag)

Use 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 code at petsc4py/PETSc/TS.pyx:344

setARKIMEXFullyImplicit(flag)

Solve both parts of the equation implicitly.

Logically collective.
Parameters

flag ( bool ) -- Set to True for fully implicit.

Return type

None

SEE ALSO:

TSARKIMEXSetFullyImplicit

Source code at petsc4py/PETSc/TS.pyx:326

setARKIMEXType(ts_type)

Set the type of Type.ARKIMEX scheme.

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 code at petsc4py/PETSc/TS.pyx:303

setAlphaParams(alpha_m=None, alpha_f=None, gamma=None)

Set the algorithmic parameters for Type.ALPHA .

Logically collective.

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 code at petsc4py/PETSc/TS.pyx:3037

setAlphaRadius(radius)

Set 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 code at petsc4py/PETSc/TS.pyx:3015

setAppCtx(appctx)

Set the application context.

Not collective.
Parameters

appctx ( Any ) -- The application context.

Return type

None

Source code at petsc4py/PETSc/TS.pyx:576

setConvergedReason(reason)

Set the reason for handling the convergence of solve .

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 code at petsc4py/PETSc/TS.pyx:2069

setCostGradients(vl, vm=None)

Set the cost gradients.

Logically collective.
Parameters

	•		vl ( Vec \| Sequence[Vec] \| None ) -- gradients with respect to the initial condition variables, the dimension and parallel layout of these vectors is the same as the ODE solution vector
	•		vm ( Vec \| Sequence[Vec] \| None ) -- gradients with respect to the parameters, the number of entries in these vectors is the same as the number of parameters

Return type

None

SEE ALSO:

TSSetCostGradients

Source code at petsc4py/PETSc/TS.pyx:2588

setDIRKType(ts_type)

Set the type of Type.DIRK scheme.

Logically collective.
Parameters

ts_type ( DIRKType | str ) -- The type of Type.DIRK scheme.

Return type

None

Notes

-ts_dirk_type sets scheme type from the commandline.

SEE ALSO:

TSDIRKSetType

Source code at petsc4py/PETSc/TS.pyx:403

setDM(dm)

Set the DM that may be used by some nonlinear solvers or preconditioners.

Logically collective.
Parameters

dm ( DM ) -- The DM object.

Return type

None

SEE ALSO:

TSSetDM

Source code at petsc4py/PETSc/TS.pyx:1609

setEquationType(eqtype)

Set the type of the equation that TS is solving.

Logically collective.
Parameters

eqtype ( EquationType ) -- The type of equation.

Return type

None

SEE ALSO:

TSSetEquationType

Source code at petsc4py/PETSc/TS.pyx:471

setErrorIfStepFails(flag=True)

Immediately error is no step succeeds.

Not collective.
Parameters

flag ( bool ) -- Enable to error if no step succeeds.

Return type

None

Notes

-ts_error_if_step_fails to enable from the commandline.

SEE ALSO:

TSSetErrorIfStepFails

Source code at petsc4py/PETSc/TS.pyx:1948

setEventHandler(direction, terminate, indicator, postevent=None,
args=None, kargs=None)

Set a function used for detecting events.

Logically collective.
Parameters

	•		direction ( Sequence[int] ) -- Direction of zero crossing to be detected {-1, 0, +1}.
	•		terminate ( Sequence[bool] ) -- Flags for each event to indicate stepping should be terminated.
	•		indicator ( TSIndicatorFunction \| None ) -- Function for defining the indicator-functions marking the events
	•		postevent ( TSPostEventFunction ) -- Function to execute after the event
	•		args ( tuple[Any, ...] \| None ) -- Additional positional arguments for indicator .
	•		kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for indicator .

Return type

None

SEE ALSO:

TSSetEventHandler

Source code at petsc4py/PETSc/TS.pyx:2198

setEventTolerances(tol=None, vtol=None)

Set tolerances for event zero crossings when using event handler.

Logically collective.

setEventHandler must have already been called.
Parameters

	•		tol ( float ) -- The scalar tolerance or None to leave at the current value
	•		vtol ( Sequence[float] ) -- A sequence of scalar tolerance for each event. Used in preference to tol if present. Set to None to leave at the current value.

Return type

None

Notes

-ts_event_tol can be used to set values from the commandline.

SEE ALSO:

TSSetEventTolerances

Source code at petsc4py/PETSc/TS.pyx:2253

setExactFinalTime(option)

Set method of computing the final time step.

Logically collective.
Parameters

option ( ExactFinalTime ) -- The exact final time option

Return type

None

Notes

-ts_exact_final_time may be used to specify from the commandline.

SEE ALSO:

TSSetExactFinalTime

Source code at petsc4py/PETSc/TS.pyx:2047

setFromOptions()

Set various TS parameters from user options.

Collective.

SEE ALSO:

Working with PETSc options , TSSetFromOptions

Source code at petsc4py/PETSc/TS.pyx:562
Return type

None

setI2Function(function, f=None, args=None, kargs=None)

Set the function to compute the 2nd order DAE.

Logically collective.
Parameters

	•		function ( TSI2Function \| None ) -- The right-hand side function.
	•		f ( Vec \| None ) -- The vector to store values or None to be 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:

TSSetI2Function

Source code at petsc4py/PETSc/TS.pyx:1063

setI2Jacobian(jacobian, J=None, P=None, args=None, kargs=None)

Set the function to compute the Jacobian of the 2nd order DAE.

Logically collective.
Parameters

	•		jacobian ( TSI2Jacobian \| None ) -- The function which computes the Jacobian.
	•		J ( Mat \| None ) -- The matrix into which the Jacobian is computed.
	•		P ( Mat \| None ) -- The optional matrix to use for building a preconditioner matrix.
	•		args -- Additional positional arguments for jacobian .
	•		kargs -- Additional keyword arguments for jacobian .

Return type

None

SEE ALSO:

TSSetI2Jacobian

Source code at petsc4py/PETSc/TS.pyx:1100

setIFunction(function, f=None, args=None, kargs=None)

Set the function representing the DAE to be solved.

Logically collective.
Parameters

	•		function ( TSIFunction \| None ) -- The right-hand side function.
	•		f ( Vec \| None ) -- The vector to store values or None to be 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

Source code at petsc4py/PETSc/TS.pyx:804

setIJacobian(jacobian, J=None, P=None, args=None, kargs=None)

Set the function to compute 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 provided with setIFunction .
Parameters

	•		jacobian ( TSIJacobian \| None ) -- The function which computes the Jacobian.
	•		J ( Mat \| None ) -- The matrix into which the Jacobian is computed.
	•		P ( Mat \| None ) -- The optional matrix to use for building a preconditioner matrix.
	•		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

Source code at petsc4py/PETSc/TS.pyx:841

setIJacobianP(jacobian, J=None, args=None, kargs=None)

Set the function that computes the Jacobian.

Logically collective.

Set the function that computes the Jacobian of F with respect to the parameters P where F(Udot, U, t) = G(U, P, t) , as well as the location to store the matrix.
Parameters

	•		jacobian -- The function which computes the Jacobian.
	•		J ( Mat \| None ) -- The matrix into which the Jacobian is computed.
	•		args ( tuple[Any, ...] \| None ) -- Additional positional arguments for jacobian .
	•		kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for jacobian .

Return type

None

SEE ALSO:

TSSetIJacobianP

Source code at petsc4py/PETSc/TS.pyx:886

setMaxSNESFailures(n)

Set the maximum number of SNES solves failures allowed.

Not collective.
Parameters

n ( int ) -- The maximum number of failed nonlinear solver, use -1 for unlimited.

Return type

None

SEE ALSO:

TSSetMaxSNESFailures

Source code at petsc4py/PETSc/TS.pyx:1913

setMaxStepRejections(n)

Set the maximum number of step rejections before a time step fails.

Not collective.
Parameters

n ( int ) -- The maximum number of rejected steps, use -1 for unlimited.

Return type

None

Notes

-ts_max_reject can be used to set this from the commandline

SEE ALSO:

TSSetMaxStepRejections

Source code at petsc4py/PETSc/TS.pyx:1874

setMaxSteps(max_steps)

Set the maximum number of steps to use.

Logically collective.

Defaults to 5000 .
Parameters

max_steps ( int ) -- The maximum number of steps to use.

Return type

None

SEE ALSO:

TSSetMaxSteps

Source code at petsc4py/PETSc/TS.pyx:1806

setMaxTime(max_time)

Set the maximum (final) time.

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

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

Set an additional monitor to the TS .

Logically collective.
Parameters

	•		monitor ( TSMonitorFunction \| None ) -- The custom monitor function.
	•		args ( tuple[Any, ...] \| None ) -- Additional positional arguments for monitor .
	•		kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for monitor .

Return type

None

SEE ALSO:

TSMonitorSet

Source code at petsc4py/PETSc/TS.pyx:2108

setOptionsPrefix(prefix)

Set the prefix used for all the TS options.

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.

SEE ALSO:

Working with PETSc options , TSSetOptionsPrefix

Source code at petsc4py/PETSc/TS.pyx:502

setPostStep(poststep, args=None, kargs=None)

Set a function to be called at the end of each time step.

Logically collective.
Parameters

	•		poststep ( TSPostStepFunction \| None ) -- The function to be called at the end of each step.
	•		args ( tuple[Any, ...] \| None ) -- Additional positional arguments for poststep .
	•		kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for poststep .

Return type

None

SEE ALSO:

TSSetPostStep

Source code at petsc4py/PETSc/TS.pyx:2350

setPreStep(prestep, args=None, kargs=None)

Set a function to be called at the beginning of each time step.

Logically collective.
Parameters

	•		prestep ( TSPreStepFunction \| None ) -- The function to be called at the beginning of each step.
	•		args ( tuple[Any, ...] \| None ) -- Additional positional arguments for prestep .
	•		kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for prestep .

Return type

None

SEE ALSO:

TSSetPreStep

Source code at petsc4py/PETSc/TS.pyx:2305

setProblemType(ptype)

Set the type of problem to be solved.

Logically collective.
Parameters

ptype ( ProblemType ) -- The type of problem of the forms.

Return type

None

SEE ALSO:

TSSetProblemType

Source code at petsc4py/PETSc/TS.pyx:440

setPythonContext(context)

Set the instance of the class implementing the required Python methods.

Not collective.

SEE ALSO:

PETSc Python ode-integrator type (TODO) , getPythonContext

Source code at petsc4py/PETSc/TS.pyx:2888
Parameters

context ( Any )

Return type

None

setPythonType(py_type)

Set the fully qualified Python name of the class to be used.

Collective.

SEE ALSO:

PETSc Python ode-integrator type (TODO) , setPythonContext , getPythonType , TSPythonSetType

Source code at petsc4py/PETSc/TS.pyx:2915
Parameters

py_type ( str )

Return type

None

setRHSFunction(function, f=None, args=None, kargs=None)

Set the routine for evaluating the function G in U_t = G(t, u) .

Logically collective.
Parameters

	•		function ( TSRHSFunction \| None ) -- The right-hand side function.
	•		f ( Vec \| None ) -- The vector into which the right-hand side is computed.
	•		args ( tuple[Any, ...] \| None ) -- Additional positional arguments for function .
	•		kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for function .

Return type

None

SEE ALSO:

TSSetRHSFunction

Source code at petsc4py/PETSc/TS.pyx:595

setRHSJacobian(jacobian, J=None, P=None, args=None, kargs=None)

Set the function to compute the Jacobian of G in U_t = G(U, t) .

Logically collective.
Parameters

	•		jacobian ( TSRHSJacobian \| None ) -- The right-hand side function.
	•		J ( Mat \| None ) -- The matrix into which the jacobian is computed.
	•		P ( Mat \| None ) -- The matrix into which the preconditioner is computed.
	•		args ( tuple[Any, ...] \| None ) -- Additional positional arguments for jacobian .
	•		kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for jacobian .

Return type

None

SEE ALSO:

TSSetRHSJacobian

Source code at petsc4py/PETSc/TS.pyx:632

setRHSJacobianP(jacobianp, A=None, args=None, kargs=None)

Set the function that computes the Jacobian with respect to the parameters.

Logically collective.
Parameters

	•		jacobianp ( TSRHSJacobianP \| None ) -- The user-defined function.
	•		A ( Mat \| None ) -- The matrix into which the Jacobian will be computed.
	•		args ( tuple[Any, ...] \| None ) -- Additional positional arguments for jacobianp .
	•		kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for jacobianp .

Return type

None

SEE ALSO:

TSSetRHSJacobianP

Source code at petsc4py/PETSc/TS.pyx:2655

setRHSSplitIFunction(splitname, function, r=None, args=None,
kargs=None)

Set the split implicit functions.

Logically collective.
Parameters

	•		splitname ( str ) -- Name of the split.
	•		function ( TSIFunction ) -- The implicit 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

SEE ALSO:

TSRHSSplitSetIFunction

Source code at petsc4py/PETSc/TS.pyx:1316

setRHSSplitIJacobian(splitname, jacobian, J=None, P=None,
args=None, kargs=None)

Set the Jacobian for the split implicit function.

Logically collective.
Parameters

	•		splitname ( str ) -- Name of the split.
	•		jacobian ( TSRHSJacobian ) -- The Jacobian evaluation routine.
	•		J ( Mat \| None ) -- Matrix to store Jacobian entries computed by jacobian .
	•		P ( Mat \| None ) -- Matrix used to compute preconditioner (usually the same as J ).
	•		args ( tuple[Any, ...] \| None ) -- Additional positional arguments for jacobian .
	•		kargs ( dict[str, Any] \| None ) -- Additional keyword arguments for jacobian .

Return type

None

SEE ALSO:

TSRHSSplitSetIJacobian

Source code at petsc4py/PETSc/TS.pyx:1360

setRHSSplitIS(splitname, iss)

Set the index set for the specified split.

Logically collective.
Parameters

	•		splitname ( str ) -- Name of this split, if None the number of the split is used.
	•		iss ( IS ) -- The index set for part of the solution vector.

Return type

None

SEE ALSO:

TSRHSSplitSetIS

Source code at petsc4py/PETSc/TS.pyx:1251

setRHSSplitRHSFunction(splitname, function, r=None, args=None,
kargs=None)

Set the split right-hand-side functions.

Logically collective.
Parameters

	•		splitname ( str ) -- Name of the split.
	•		function ( 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

SEE ALSO:

TSRHSSplitSetRHSFunction

Source code at petsc4py/PETSc/TS.pyx:1272

setRKType(ts_type)

Set the type of the Runge-Kutta scheme.

Logically collective.
Parameters

ts_type ( RKType | str ) -- The type of scheme.

Return type

None

Notes

-ts_rk_type sets scheme type from the commandline.

SEE ALSO:

TSRKSetType

Source code at petsc4py/PETSc/TS.pyx:280

setSaveTrajectory()

Enable to save solutions as an internal TS trajectory.

Collective.

This routine should be called after all TS options have been set.

Notes

-ts_save_trajectory can be used to save a trajectory to a file.

SEE ALSO:

TSSetSaveTrajectory

Source code at petsc4py/PETSc/TS.pyx:2542
Return type

None

setSolution(u)

Set the initial solution vector.

Logically collective.
Parameters

u ( Vec ) -- The solution vector.

Return type

None

SEE ALSO:

TSSetSolution

Source code at petsc4py/PETSc/TS.pyx:1411

setSolution2(u, v)

Set the initial solution and its time derivative.

Logically collective.
Parameters

	•		u ( Vec ) -- The solution vector.
	•		v ( Vec ) -- The time derivative vector.

Return type

None

SEE ALSO:

TS2SetSolution

Source code at petsc4py/PETSc/TS.pyx:1447

setStepLimits(hmin, hmax)

Set the minimum and maximum allowed step sizes.

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

setStepNumber(step_number)

Set the number of steps completed.

Logically collective.

For most uses of the TS solvers the user need not explicitly call setStepNumber , as the step counter is appropriately updated in solve / step / rollBack . Power users may call this routine to reinitialize timestepping by setting the step counter to zero (and time to the initial time) to solve a similar problem with different initial conditions or parameters. It may also be used to continue timestepping from a previously interrupted run in such a way that TS monitors will be called with a 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:1727

setTheta(theta)

Set 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:2945

setThetaEndpoint(flag=True)

Set to use the endpoint variant of Type.THETA .

Logically collective.
Parameters

flag -- Enable to use the endpoint variant.

Return type

None

SEE ALSO:

TSThetaSetEndpoint

Source code at petsc4py/PETSc/TS.pyx:2981

setTime(t)

Set the time.

Logically collective.
Parameters

t ( float ) -- The time.

Return type

None

SEE ALSO:

TSSetTime

Source code at petsc4py/PETSc/TS.pyx:1628

setTimeSpan(tspan)

Set the time span.

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. The intermediate solutions are saved in a vector array that can be accessed with getTimeSpanSolutions .
Parameters

tspan ( Sequence[float] ) -- The sequence of time points.

Return type

None

Notes

-ts_time_span <t0, ..., tf> sets the time span from the commandline

SEE ALSO:

TSSetTimeSpan

Source code at petsc4py/PETSc/TS.pyx:1489

setTimeStep(time_step)

Set the duration of the timestep.

Logically collective.
Parameters

time_step ( float ) -- the duration of the timestep

Return type

None

SEE ALSO:

TSSetTimeStep

Source code at petsc4py/PETSc/TS.pyx:1695

setTolerances(rtol=None, atol=None)

Set tolerances for local truncation error when using an adaptive controller.

Logically collective.
Parameters

	•		rtol ( float ) -- The relative tolerance, DETERMINE to use the value when the object's type was set, or None to leave the current value.
	•		atol ( float ) -- 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:1970

setType(ts_type)

Set the method to be used as the TS solver.

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

setUp()

Set up the internal data structures for the TS .

Collective.

SEE ALSO:

TSSetUp

Source code at petsc4py/PETSc/TS.pyx:2386
Return type

None

solve(u=None)

Step the requested number of timesteps.

Collective.
Parameters

u ( Vec | None ) -- The solution vector. Can be - None .

Return type

None

SEE ALSO:

TSSolve

Source code at petsc4py/PETSc/TS.pyx:2461

step()

Take one step.

Collective.

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

Source code at petsc4py/PETSc/TS.pyx:2410
Return type

None

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

Attributes Documentation

appctx

Application context.

Source code at petsc4py/PETSc/TS.pyx:3086

atol

The absolute tolerance.

Source code at petsc4py/PETSc/TS.pyx:3189

converged

Indicates the TS has converged.

Source code at petsc4py/PETSc/TS.pyx:3210

diverged

Indicates the TS has stopped.

Source code at petsc4py/PETSc/TS.pyx:3215

The DM .

Source code at petsc4py/PETSc/TS.pyx:3096

equation_type

The equation type.

Source code at petsc4py/PETSc/TS.pyx:3114

iterating

Indicates the TS is still iterating.

Source code at petsc4py/PETSc/TS.pyx:3205

ksp

The KSP .

Source code at petsc4py/PETSc/TS.pyx:3127

max_steps

The maximum number of steps.

Source code at petsc4py/PETSc/TS.pyx:3171

max_time

The maximum time.

Source code at petsc4py/PETSc/TS.pyx:3163

problem_type

The problem type.

Source code at petsc4py/PETSc/TS.pyx:3106

reason

The converged reason.

Source code at petsc4py/PETSc/TS.pyx:3197

rtol

The relative tolerance.

Source code at petsc4py/PETSc/TS.pyx:3181

snes

The SNES .

Source code at petsc4py/PETSc/TS.pyx:3122

step_number

The current step number.

Source code at petsc4py/PETSc/TS.pyx:3155

time

The current time.

Source code at petsc4py/PETSc/TS.pyx:3139

time_step

The current time step size.

Source code at petsc4py/PETSc/TS.pyx:3147

vec_sol

The solution vector.

Source code at petsc4py/PETSc/TS.pyx:3132

petsc4py.PETSc.Vec

class petsc4py.PETSc.Vec

Bases: Object

A vector object.

SEE ALSO:

Vec

Enumerations

Image grohtml-288464-170.png

petsc4py.PETSc.Vec.Option

class petsc4py.PETSc.Vec.Option

Bases: object

Vector assembly option.

Attributes Summary

Image grohtml-288464-171.png

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

petsc4py.PETSc.Vec.Type

class petsc4py.PETSc.Vec.Type

Bases: object

The vector type.

Attributes Summary

Image grohtml-288464-172.png

Attributes Documentation
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

Methods Summary

Image grohtml-288464-173.png

Attributes Summary

Image grohtml-288464-174.png

Methods Documentation

abs()

Replace each entry (xₙ) in the vector by abs|xₙ|.

Logically collective.

SEE ALSO:

VecAbs

Source code at petsc4py/PETSc/Vec.pyx:2293
Return type

None

appendOptionsPrefix(prefix)

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

Logically collective.

SEE ALSO:

Working with PETSc options , setOptionsPrefix , - VecAppendOptionsPrefix

Source code at petsc4py/PETSc/Vec.pyx:1028
Parameters

prefix ( str | None )

Return type

None

assemble()

Assemble the vector.

Collective.

SEE ALSO:

assemblyBegin , assemblyEnd

Source code at petsc4py/PETSc/Vec.pyx:3047
Return type

None

assemblyBegin()

Begin an assembling stage of the vector.

Collective.

SEE ALSO:

assemblyEnd , VecAssemblyBegin

Source code at petsc4py/PETSc/Vec.pyx:3023
Return type

None

assemblyEnd()

Finish the assembling stage initiated with assemblyBegin .

Collective.

SEE ALSO:

assemblyBegin , VecAssemblyEnd

Source code at petsc4py/PETSc/Vec.pyx:3035
Return type

None

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

	•		vec ( Vec \| None ) -- Vector with attached tensor information. This is typically created by calling createWithDLPack .
	•		dltensor -- DLPack tensor. This will only be used if vec is None .

Return type

Self

Notes

This operation does not copy any data from vec or dltensor .

SEE ALSO:

clearDLPackInfo , createWithDLPack

Source code at petsc4py/PETSc/Vec.pyx:643

axpby(alpha, beta, x)

Compute and store y = ɑ·x + β·y.

Logically collective.
Parameters

	•		alpha ( Scalar ) -- First scale factor.
	•		beta ( Scalar ) -- Second scale factor.
	•		x ( Vec ) -- Input vector, must not be the current vector.

Return type

None

SEE ALSO:

axpy , aypx , waxpy , VecAXPBY

Source code at petsc4py/PETSc/Vec.pyx:2524

axpy(alpha, x)

Compute and store y = ɑ·x + y.

Logically collective.
Parameters

	•		alpha ( Scalar ) -- Scale factor.
	•		x ( Vec ) -- Input vector.

Return type

None

SEE ALSO:

isaxpy , VecAXPY

Source code at petsc4py/PETSc/Vec.pyx:2460

aypx(alpha, x)

Compute and store y = x + ɑ·y.

Logically collective.
Parameters

	•		alpha ( Scalar ) -- Scale factor.
	•		x ( Vec ) -- Input vector, must not be the current vector.

Return type

None

SEE ALSO:

axpy , axpby , VecAYPX

Source code at petsc4py/PETSc/Vec.pyx:2504

bindToCPU(flg)

Bind vector operations execution on the CPU.

Logically collective.

SEE ALSO:

boundToCPU , VecBindToCPU

Source code at petsc4py/PETSc/Vec.pyx:1396
Parameters

flg ( bool )

Return type

None

boundToCPU()

Return whether the vector has been bound to the CPU.

Not collective.

SEE ALSO:

bindToCPU , VecBoundToCPU

Source code at petsc4py/PETSc/Vec.pyx:1409
Return type

bool

chop(tol)

Set all vector entries less than some absolute tolerance to zero.

Collective.
Parameters

tol ( float ) -- The absolute tolerance below which entries are set to zero.

Return type

None

SEE ALSO:

VecFilter

Source code at petsc4py/PETSc/Vec.pyx:1732

clearDLPackInfo()

Clear tensor information.

Logically collective.

SEE ALSO:

attachDLPackInfo , createWithDLPack

Source code at petsc4py/PETSc/Vec.pyx:705
Return type

Self

classmethod concatenate(vecs)

Concatenate vectors into a single vector.

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

Source code at petsc4py/PETSc/Vec.pyx:3536

conjugate()

Conjugate the vector.

Logically collective.

SEE ALSO:

VecConjugate

Source code at petsc4py/PETSc/Vec.pyx:2305
Return type

None

copy(result=None)

Return a copy of the vector.

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

Source code at petsc4py/PETSc/Vec.pyx:1707

create(comm=None)

Create a vector object.

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

Source code at petsc4py/PETSc/Vec.pyx:176

createCUDAWithArrays(cpuarray=None, cudahandle=None, size=None,
bsize=None, comm=None)

Create a Type.CUDA vector with optional arrays.

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 , VecCreateMPICUDAWithArrays

Source code at petsc4py/PETSc/Vec.pyx:370

createGhost(ghosts, size, bsize=None, comm=None)

Create a parallel vector with ghost padding on each processor.

Collective.
Parameters

	•		ghosts ( Sequence[int] ) -- Global indices of ghost points.
	•		size ( LayoutSizeSpec ) -- 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:

createGhostWithArray , VecCreateGhost , - VecCreateGhostBlock

Source code at petsc4py/PETSc/Vec.pyx:819

createGhostWithArray(ghosts, array, size=None, bsize=None,
comm=None)

Create a parallel vector with ghost padding and provided arrays.

Collective.
Parameters

	•		ghosts ( Sequence[int] ) -- Global indices of ghost points.
	•		array ( Sequence[Scalar] ) -- Array to store the vector values. Must be at least as large as the local size of the vector (including ghost points).
	•		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:

createGhost , VecCreateGhostWithArray , - VecCreateGhostBlockWithArray

Source code at petsc4py/PETSc/Vec.pyx:861

createHIPWithArrays(cpuarray=None, hiphandle=None, size=None,
bsize=None, comm=None)

Create a Type.HIP vector with optional arrays.

Collective.
Parameters

	•		cpuarray ( Sequence[Scalar] \| None ) -- Host array. Will be lazily allocated if not provided.
	•		hiphandle ( 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:

VecCreateSeqHIPWithArrays , VecCreateMPIHIPWithArrays

Source code at petsc4py/PETSc/Vec.pyx:428

createLocalVector()

Create a local vector.

Not collective.
Returns

The local vector.

Return type

Vec

SEE ALSO:

getLocalVector , VecCreateLocalVector

Source code at petsc4py/PETSc/Vec.pyx:1204

createMPI(size, bsize=None, comm=None)

Create a parallel Type.MPI vector.

Collective.
Parameters

	•		size ( LayoutSizeSpec ) -- 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:

createSeq , VecCreateMPI

Source code at petsc4py/PETSc/Vec.pyx:283

createNest(vecs, isets=None, comm=None)

Create a Type.NEST vector containing multiple nested subvectors.

Collective.
Parameters

	•		vecs ( Sequence[Vec] ) -- Iterable of subvectors.
	•		isets ( Sequence[IS] ) -- Iterable of index sets for each nested subvector. Defaults to contiguous ordering.
	•		comm ( Comm \| None ) -- MPI communicator, defaults to Sys.getDefaultComm .

Return type

Self

SEE ALSO:

VecCreateNest

Source code at petsc4py/PETSc/Vec.pyx:952

createSeq(size, bsize=None, comm=None)

Create a sequential Type.SEQ vector.

Collective.
Parameters

	•		size ( LayoutSizeSpec ) -- Vector size.
	•		bsize ( int \| None ) -- Vector block size. If - None , bsize = 1 .
	•		comm ( Comm \| None ) -- MPI communicator, defaults to COMM_SELF .

Return type

Self

SEE ALSO:

createMPI , VecCreateSeq

Source code at petsc4py/PETSc/Vec.pyx:247

createShared(size, bsize=None, comm=None)

Create a Type.SHARED vector that uses shared memory.

Collective.
Parameters

	•		size ( LayoutSizeSpec ) -- 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:

VecCreateShared

Source code at petsc4py/PETSc/Vec.pyx:918

createViennaCLWithArrays(cpuarray=None, viennaclvechandle=None,
size=None, bsize=None, comm=None)

Create a Type.VIENNACL vector with optional arrays.

Collective.
Parameters

	•		cpuarray ( Sequence[Scalar] \| None ) -- Host array. Will be lazily allocated if not provided.
	•		viennaclvechandle ( 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:

VecCreateSeqViennaCLWithArrays , - VecCreateMPIViennaCLWithArrays

Source code at petsc4py/PETSc/Vec.pyx:486

createWithArray(array, size=None, bsize=None, comm=None)

Create a vector using a provided array.

Collective.

This method will create either a Type.SEQ or Type.MPI depending on the size of the communicator.
Parameters

	•		array ( Sequence[Scalar] ) -- Array to store the vector values. Must be at least as large as the local size of the vector.
	•		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:

VecCreateSeqWithArray , VecCreateMPIWithArray

Source code at petsc4py/PETSc/Vec.pyx:319

createWithDLPack(dltensor, size=None, bsize=None, comm=None)

Create a vector wrapping a DLPack object, sharing the same memory.

Collective.

This operation does not modify the storage of the original tensor and should be used with contiguous tensors only. If the tensor is stored in row-major order (e.g. PyTorch tensors), the resulting vector will look like an unrolled tensor using row-major order.

The resulting vector type will be one of Type.SEQ , Type.MPI , Type.SEQCUDA , Type.MPICUDA , Type.SEQHIP or Type.MPIHIP depending on the type of dltensor and the number of processes in the communicator.
Parameters

	•		dltensor -- Either an object with a __dlpack__ method or a DLPack tensor object.
	•		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

Source code at petsc4py/PETSc/Vec.pyx:545

destroy()

Destroy the vector.

Collective.

SEE ALSO:

create , VecDestroy

Source code at petsc4py/PETSc/Vec.pyx:163
Return type

Self

dot(vec)

Return the dot product with vec .

Collective.

For complex numbers this computes yᴴ·x with self as x, vec as y and where yᴴ denotes the conjugate transpose of y.

Use tDot for the indefinite form yᵀ·x where yᵀ denotes the transpose of y.
Parameters

vec ( Vec ) -- Vector to compute the dot product with.

Return type

Scalar

SEE ALSO:

dotBegin , dotEnd , tDot , VecDot

Source code at petsc4py/PETSc/Vec.pyx:1787

dotBegin(vec)

Begin computing the dot product.

Collective.

This should be paired with a call to dotEnd .
Parameters

vec ( Vec ) -- Vector to compute the dot product with.

Return type

None

SEE ALSO:

dotEnd , dot , VecDotBegin

Source code at petsc4py/PETSc/Vec.pyx:1812

dotEnd(vec)

Finish computing the dot product initiated with dotBegin .

Collective.

SEE ALSO:

dotBegin , dot , VecDotEnd

Source code at petsc4py/PETSc/Vec.pyx:1832
Parameters

vec ( Vec )

Return type

Scalar

dotNorm2(vec)

Return the dot product with vec and its squared norm.

Collective.

SEE ALSO:

dot , norm , VecDotNorm2

Source code at petsc4py/PETSc/Vec.pyx:2151
Parameters

vec ( Vec )

Return type

tuple [ Scalar , float ]

duplicate(array=None)

Create a new vector with the same type, optionally with data.

Collective.
Parameters

array ( Sequence[Scalar] | None ) -- Optional values to store in the new vector.

Return type

Vec

SEE ALSO:

copy , VecDuplicate

Source code at petsc4py/PETSc/Vec.pyx:1682

equal(vec)

Return whether the vector is equal to another.

Collective.
Parameters

vec ( Vec ) -- Vector to compare with.

Return type

bool

SEE ALSO:

VecEqual

Source code at petsc4py/PETSc/Vec.pyx:1768

exp()

Replace each entry (xₙ) in the vector by exp(xₙ).

Logically collective.

SEE ALSO:

log , VecExp

Source code at petsc4py/PETSc/Vec.pyx:2257
Return type

None

getArray(readonly=False)

Return local portion of the vector as an ndarray .

Logically collective.
Parameters

readonly ( bool ) -- Request read-only access.

Return type

ArrayScalar

SEE ALSO:

setArray , getBuffer

Source code at petsc4py/PETSc/Vec.pyx:1313

getBlockSize()

Return the block size of the vector.

Not collective.

SEE ALSO:

VecGetBlockSize

Source code at petsc4py/PETSc/Vec.pyx:1149
Return type

int

getBuffer(readonly=False)

Return a buffered view of the local portion of the vector.

Logically collective.
Parameters

readonly ( bool ) -- Request read-only access.

Returns

Buffer object wrapping the local portion of the vector data. This can be used either as a context manager providing access as a numpy array or can be passed to array constructors accepting buffered objects such as numpy.asarray .

Return type

typing.Any

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 :

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

getCLContextHandle()

Return the OpenCL context associated with the vector.

Not collective.
Returns

Pointer to underlying CL context. This can be used with pyopencl through pyopencl.Context.from_int_ptr .

Return type

int

SEE ALSO:

getCLQueueHandle , VecViennaCLGetCLContext

Source code at petsc4py/PETSc/Vec.pyx:1593

getCLMemHandle(mode='rw')

Return the OpenCL buffer associated with the vector.

Not collective.
Returns

Pointer to the device buffer. This can be used with pyopencl through pyopencl.Context.from_int_ptr .

Return type

int

Parameters

mode ( AccessModeSpec )

Notes

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:

restoreCLMemHandle , VecViennaCLGetCLMem , - VecViennaCLGetCLMemRead , VecViennaCLGetCLMemWrite

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

getCLQueueHandle()

Return the OpenCL command queue associated with the vector.

Not collective.
Returns

Pointer to underlying CL command queue. This can be used with pyopencl through pyopencl.Context.from_int_ptr .

Return type

int

SEE ALSO:

getCLContextHandle , VecViennaCLGetCLQueue

Source code at petsc4py/PETSc/Vec.pyx:1613

getCUDAHandle(mode='rw')

Return a pointer to the device buffer.

Not collective.

The returned pointer should be released using restoreCUDAHandle with the same access mode.
Returns

CUDA device pointer.

Return type

typing.Any

Parameters

mode ( AccessModeSpec )

Notes

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:

restoreCUDAHandle , VecCUDAGetArray , - VecCUDAGetArrayRead , VecCUDAGetArrayWrite

Source code at petsc4py/PETSc/Vec.pyx:1423

getDM()

Return the DM associated to the vector.

Not collective.

SEE ALSO:

setDM , VecGetDM

Source code at petsc4py/PETSc/Vec.pyx:3519
Return type

getGhostIS()

Return ghosting indices of a ghost vector.

Collective.
Returns

Indices of ghosts.

Return type

SEE ALSO:

VecGhostGetGhostIS

Source code at petsc4py/PETSc/Vec.pyx:3385

getHIPHandle(mode='rw')

Return a pointer to the device buffer.

Not collective.

The returned pointer should be released using restoreHIPHandle with the same access mode.
Returns

HIP device pointer.

Return type

typing.Any

Parameters

mode ( AccessModeSpec )

Notes

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

Return the local-to-global mapping.

Not collective.

SEE ALSO:

setLGMap , VecGetLocalToGlobalMapping

Source code at petsc4py/PETSc/Vec.pyx:2899
Return type

LGMap

getLocalSize()

Return the local size of the vector.

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.

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

Return all the vectors contained in the nested vector.

Not collective.

SEE ALSO:

setNestSubVecs , VecNestGetSubVecs

Source code at petsc4py/PETSc/Vec.pyx:3451
Return type

list [ Vec ]

getOffloadMask()

Return the offloading status of the vector.

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

Return the prefix used for searching for options in the database.

Not collective.

SEE ALSO:

Working with PETSc options , setOptionsPrefix , - VecGetOptionsPrefix

Source code at petsc4py/PETSc/Vec.pyx:1014
Return type

str

getOwnershipRange()

Return the locally owned range of indices (start, end) .

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

Return the range of indices owned by each process.

Not collective.

The returned array is the result of exclusive scan of the local sizes.

SEE ALSO:

getOwnershipRange , VecGetOwnershipRanges

Source code at petsc4py/PETSc/Vec.pyx:1184
Return type

ArrayInt

getSize()

Return the global size of the vector.

Not collective.

SEE ALSO:

setSizes , getLocalSize , VecGetSize

Source code at petsc4py/PETSc/Vec.pyx:1093
Return type

int

getSizes()

Return the vector sizes.

Not collective.

SEE ALSO:

getSize , getLocalSize , VecGetLocalSize , VecGetSize

Source code at petsc4py/PETSc/Vec.pyx:1121
Return type

LayoutSizeSpec

getSubVector(iset, subvec=None)

Return a subvector from given indices.

Collective.

Once finished with the subvector it should be returned with restoreSubVector .
Parameters

	•		iset ( IS ) -- Index set describing which indices to extract into the subvector.
	•		subvec ( Vec \| None ) -- Subvector to copy entries into. If None then a new Vec will be created.

Return type

Vec

SEE ALSO:

restoreSubVector , VecGetSubVector

Source code at petsc4py/PETSc/Vec.pyx:3406

getType()

Return the type of the vector.

Not collective.

SEE ALSO:

setType , VecGetType

Source code at petsc4py/PETSc/Vec.pyx:1079
Return type

str

getValue(index)

Return a single value from the vector.

Not collective.

Only values locally stored may be accessed.
Parameters

index ( int ) -- Location of the value to read.

Return type

Scalar

SEE ALSO:

getValues , VecGetValues

Source code at petsc4py/PETSc/Vec.pyx:2720

getValues(indices, values=None)

Return values from certain locations in the vector.

Not collective.

Only values locally stored may be accessed.
Parameters

	•		indices ( Sequence[int] ) -- Locations of the values to read.
	•		values ( Sequence[Scalar] \| None ) -- Location to store the collected values. If not provided then a new array will be allocated.

Return type

ArrayScalar

SEE ALSO:

getValue , setValues , VecGetValues

Source code at petsc4py/PETSc/Vec.pyx:2742

getValuesStagStencil(indices, values=None)

Not implemented.

Source code at petsc4py/PETSc/Vec.pyx:2767
Return type

None

ghostUpdate(addv=None, mode=None)

Update ghosted vector entries.

Neighborwise collective.
Parameters

	•		addv ( InsertModeSpec ) -- Insertion mode.
	•		mode ( 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)

SEE ALSO:

ghostUpdateBegin , ghostUpdateEnd

Source code at petsc4py/PETSc/Vec.pyx:3331

ghostUpdateBegin(addv=None, mode=None)

Begin updating ghosted vector entries.

Neighborwise collective.

SEE ALSO:

ghostUpdateEnd , ghostUpdate , createGhost , - VecGhostUpdateBegin

Source code at petsc4py/PETSc/Vec.pyx:3297
Parameters

	•		addv ( InsertModeSpec )
	•		mode ( ScatterModeSpec )

Return type

None

ghostUpdateEnd(addv=None, mode=None)

Finish updating ghosted vector entries initiated with ghostUpdateBegin .

Neighborwise collective.

SEE ALSO:

ghostUpdateBegin , ghostUpdate , createGhost , - VecGhostUpdateEnd

Source code at petsc4py/PETSc/Vec.pyx:3314
Parameters

	•		addv ( InsertModeSpec )
	•		mode ( ScatterModeSpec )

Return type

None

isaxpy(idx, alpha, x)

Add a scaled reduced-space vector to a subset of the vector.

Logically collective.

This is equivalent to y[idx[i]] += alpha*x[i] .
Parameters

	•		idx ( IS ) -- Index set for the reduced space. Negative indices are skipped.
	•		alpha ( Scalar ) -- Scale factor.
	•		x ( Vec ) -- Reduced-space vector.

Return type

None

SEE ALSO:

axpy , aypx , axpby , VecISAXPY

Source code at petsc4py/PETSc/Vec.pyx:2480

isset(idx, alpha)

Set specific elements of the vector to the same value.

Not collective.
Parameters

	•		idx ( IS ) -- Index set specifying the vector entries to set.
	•		alpha ( Scalar ) -- Value to set the selected entries to.

Return type

None

SEE ALSO:

set , zeroEntries , VecISSet

Source code at petsc4py/PETSc/Vec.pyx:2383

load(viewer)

Load a vector.

Collective.

SEE ALSO:

view , VecLoad

Source code at petsc4py/PETSc/Vec.pyx:1750
Parameters

viewer ( Viewer )

Return type

Self

localForm()

Return a context manager for viewing ghost vectors in local form.

Logically collective.
Returns

Context manager yielding the vector in local (ghosted) form.

Return type

typing.Any

Notes

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 , VecGhostRestoreLocalForm

Source code at petsc4py/PETSc/Vec.pyx:3264

log()

Replace each entry in the vector by its natural logarithm.

Logically collective.

SEE ALSO:

exp , VecLog

Source code at petsc4py/PETSc/Vec.pyx:2269
Return type

None

mDot(vecs, out=None)

Compute Xᴴ·y with X an array of vectors.

Collective.
Parameters

	•		vecs ( Sequence[Vec] ) -- Array of vectors.
	•		out ( ArrayScalar \| None ) -- Optional placeholder for the result.

Return type

ArrayScalar

SEE ALSO:

dot , tDot , mDotBegin , mDotEnd , VecMDot

Source code at petsc4py/PETSc/Vec.pyx:1902

mDotBegin(vecs, out)

Starts a split phase multiple dot product computation.

Collective.
Parameters

	•		vecs ( Sequence[Vec] ) -- Array of vectors.
	•		out ( ArrayScalar ) -- Placeholder for the result.

Return type

None

SEE ALSO:

mDot , mDotEnd , VecMDotBegin

Source code at petsc4py/PETSc/Vec.pyx:1935

mDotEnd(vecs, out)

Ends a split phase multiple dot product computation.

Collective.
Parameters

	•		vecs ( Sequence[Vec] ) -- Array of vectors.
	•		out ( ArrayScalar ) -- Placeholder for the result.

Return type

ArrayScalar

SEE ALSO:

mDot , mDotBegin , VecMDotEnd

Source code at petsc4py/PETSc/Vec.pyx:1965

max()

Return the vector entry with maximum real part and its location.

Collective.
Returns

	•		p ( int ) -- Location of the maximum value. If multiple entries exist with the same value then the smallest index will be returned.
	•		val ( Scalar ) -- Minimum value.

Return type

tuple [ int , float ]

SEE ALSO:

min , VecMax

Source code at petsc4py/PETSc/Vec.pyx:2203

maxPointwiseDivide(vec)

Return the maximum of the component-wise absolute value division.

Logically collective.

Equivalent to result = max_i abs(x[i] / y[i]) .
Parameters

	•		x -- Numerator vector.
	•		y -- Denominator vector.
	•		vec ( Vec )

Return type

float

SEE ALSO:

pointwiseMin , pointwiseMax , pointwiseMaxAbs , - VecMaxPointwiseDivide

Source code at petsc4py/PETSc/Vec.pyx:2696

maxpy(alphas, vecs)

Compute and store y = Σₙ(ɑₙ·Xₙ) + y with X an array of vectors.

Logically collective.

Equivalent to y[:] = alphas[i]*vecs[i, :] + y[:] .
Parameters

	•		alphas ( Sequence[Scalar] ) -- Array of scale factors, one for each vector in vecs .
	•		vecs ( Sequence[Vec] ) -- Array of vectors.

Return type

None

SEE ALSO:

axpy , aypx , axpby , waxpy , VecMAXPY

Source code at petsc4py/PETSc/Vec.pyx:2569

min()

Return the vector entry with minimum real part and its location.

Collective.
Returns

	•		p ( int ) -- Location of the minimum value. If multiple entries exist with the same value then the smallest index will be returned.
	•		val ( Scalar ) -- Minimum value.

Return type

tuple [ int , float ]

SEE ALSO:

max , VecMin

Source code at petsc4py/PETSc/Vec.pyx:2180

mtDot(vecs, out=None)

Compute Xᵀ·y with X an array of vectors.

Collective.
Parameters

	•		vecs ( Sequence[Vec] ) -- Array of vectors.
	•		out ( ArrayScalar \| None ) -- Optional placeholder for the result.

Return type

ArrayScalar

SEE ALSO:

tDot , mDot , mtDotBegin , mtDotEnd , VecMTDot

Source code at petsc4py/PETSc/Vec.pyx:1996

mtDotBegin(vecs, out)

Starts a split phase transpose multiple dot product computation.

Collective.
Parameters

	•		vecs ( Sequence[Vec] ) -- Array of vectors.
	•		out ( ArrayScalar ) -- Placeholder for the result.

Return type

None

SEE ALSO:

mtDot , mtDotEnd , VecMTDotBegin

Source code at petsc4py/PETSc/Vec.pyx:2029

mtDotEnd(vecs, out)

Ends a split phase transpose multiple dot product computation.

Collective.
Parameters

	•		vecs ( Sequence[Vec] ) -- Array of vectors.
	•		out ( ArrayScalar ) -- Placeholder for the result.

Return type

ArrayScalar

SEE ALSO:

mtDot , mtDotBegin , VecMTDotEnd

Source code at petsc4py/PETSc/Vec.pyx:2059

norm(norm_type=None)

Compute the vector norm.

Collective.

A 2-tuple is returned if NormType.NORM_1_AND_2 is specified.

SEE ALSO:

VecNorm , NormType

Source code at petsc4py/PETSc/Vec.pyx:2090
Parameters

norm_type ( NormTypeSpec )

Return type

float | tuple [ float , float ]

normBegin(norm_type=None)

Begin computing the vector norm.

Collective.

This should be paired with a call to normEnd .

SEE ALSO:

normEnd , norm , VecNormBegin

Source code at petsc4py/PETSc/Vec.pyx:2112
Parameters

norm_type ( NormTypeSpec )

Return type

None

normEnd(norm_type=None)

Finish computations initiated with normBegin .

Collective.

SEE ALSO:

normBegin , norm , VecNormEnd

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.

Collective.
Returns

The vector norm before normalization.

Return type

float

SEE ALSO:

norm , VecNormalize

Source code at petsc4py/PETSc/Vec.pyx:2226

permute(order, invert=False)

Permute the vector in-place with a provided ordering.

Collective.
Parameters

	•		order ( IS ) -- Ordering for the permutation.
	•		invert ( bool ) -- Whether to invert the permutation.

Return type

None

SEE ALSO:

VecPermute

Source code at petsc4py/PETSc/Vec.pyx:2337

placeArray(array)

Set the local portion of the vector to a provided array.

Not collective.

SEE ALSO:

resetArray , setArray , VecPlaceArray

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.

Logically collective.

Equivalent to w[i] = x[i] / y[i] .
Parameters

	•		x ( Vec ) -- Numerator vector.
	•		y ( Vec ) -- Denominator vector.

Return type

None

SEE ALSO:

pointwiseMult , VecPointwiseDivide

Source code at petsc4py/PETSc/Vec.pyx:2618

pointwiseMax(x, y)

Compute and store the component-wise maximum of two vectors.

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

Source code at petsc4py/PETSc/Vec.pyx:2658

pointwiseMaxAbs(x, y)

Compute and store the component-wise maximum absolute values.

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

SEE ALSO:

pointwiseMin , pointwiseMax , VecPointwiseMaxAbs

Source code at petsc4py/PETSc/Vec.pyx:2677

pointwiseMin(x, y)

Compute and store the component-wise minimum of two vectors.

Logically collective.

Equivalent to w[i] = min(x[i], y[i]) .
Parameters

	•		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 at petsc4py/PETSc/Vec.pyx:2639

pointwiseMult(x, y)

Compute and store the component-wise multiplication of two vectors.

Logically collective.

Equivalent to w[i] = x[i] * y[i] .
Parameters

	•		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 at petsc4py/PETSc/Vec.pyx:2599

reciprocal()

Replace each entry in the vector by its reciprocal.

Logically collective.

SEE ALSO:

VecReciprocal

Source code at petsc4py/PETSc/Vec.pyx:2245
Return type

None

resetArray(force=False)

Reset the vector to use its default array.

Not collective.
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.

Return type

ArrayScalar

SEE ALSO:

placeArray , VecResetArray

Source code at petsc4py/PETSc/Vec.pyx:1366

restoreCLMemHandle()

Restore a pointer to the OpenCL buffer obtained with getCLMemHandle .

Not collective.

SEE ALSO:

getCLMemHandle , VecViennaCLRestoreCLMemWrite

Source code at 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 at 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 at petsc4py/PETSc/Vec.pyx:1534

restoreLocalVector(lvec, readonly=False)

Unmap a local access obtained with getLocalVector .

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 at petsc4py/PETSc/Vec.pyx:1246

restoreSubVector(iset, subvec)

Restore a subvector extracted using getSubVector .

Collective.
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 at petsc4py/PETSc/Vec.pyx:3432

scale(alpha)

Scale all entries of the vector.

Collective.

This method sets each entry (xₙ) in the vector to ɑ·xₙ.
Parameters

alpha ( Scalar ) -- The scaling factor.

Return type

None

SEE ALSO:

shift , VecScale

Source code at petsc4py/PETSc/Vec.pyx:2403

set(alpha)

Set all components of the vector to the same value.

Collective.

SEE ALSO:

zeroEntries , isset , VecSet

Source code at petsc4py/PETSc/Vec.pyx:2370
Parameters

alpha ( Scalar )

Return type

None

setArray(array)

Set values for the local portion of the vector.

Logically collective.

SEE ALSO:

placeArray

Source code at petsc4py/PETSc/Vec.pyx:1333
Parameters

array ( Sequence[Scalar] )

Return type

None

setBlockSize(bsize)

Set the block size of the vector.

Logically collective.

SEE ALSO:

VecSetBlockSize

Source code at petsc4py/PETSc/Vec.pyx:1136
Parameters

bsize ( int )

Return type

None

setDM(dm)

Associate a DM to the vector.

Not collective.

SEE ALSO:

getDM , VecSetDM

Source code at petsc4py/PETSc/Vec.pyx:3507
Parameters

dm ( DM )

Return type

None

setFromOptions()

Configure the vector from the options database.

Collective.

SEE ALSO:

Working with PETSc options , VecSetFromOptions

Source code at petsc4py/PETSc/Vec.pyx:1042
Return type

None

setLGMap(lgmap)

Set the local-to-global mapping.

Logically collective.

This allows users to insert vector entries using a local numbering with setValuesLocal .

SEE ALSO:

setValues , setValuesLocal , getLGMap , - VecSetLocalToGlobalMapping

Source code at petsc4py/PETSc/Vec.pyx:2884
Parameters

lgmap ( LGMap )

Return type

None

setMPIGhost(ghosts)

Set the ghost points for a ghosted vector.

Collective.
Parameters

ghosts ( Sequence[int] ) -- Global indices of ghost points.

Return type

None

SEE ALSO:

createGhost

Source code at petsc4py/PETSc/Vec.pyx:3366

setNestSubVecs(sx, idxm=None)

Set the component vectors at specified indices in the nested vector.

Not collective.
Parameters

	•		sx ( Sequence[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

Source code at petsc4py/PETSc/Vec.pyx:3473

setOption(option, flag)

Set option.

Collective.

SEE ALSO:

VecSetOption

Source code at petsc4py/PETSc/Vec.pyx:1067
Parameters

	•		option ( Option )
	•		flag ( bool )

Return type

None

setOptionsPrefix(prefix)

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

Logically collective.

SEE ALSO:

Working with PETSc options , getOptionsPrefix , - VecSetOptionsPrefix

Source code at petsc4py/PETSc/Vec.pyx:1000
Parameters

prefix ( str | None )

Return type

None

setRandom(random=None)

Set all components of the vector to random numbers.

Collective.
Parameters

random ( Random | None ) -- Random number generator. If None then one will be created internally.

Return type

None

SEE ALSO:

VecSetRandom

Source code at petsc4py/PETSc/Vec.pyx:2317

setSizes(size, bsize=None)

Set the local and global sizes of the vector.

Collective.
Parameters

	•		size ( LayoutSizeSpec ) -- Vector size.
	•		bsize ( int \| None ) -- Vector block size. If - None , bsize = 1 .

Return type

None

SEE ALSO:

getSizes , VecSetSizes

Source code at petsc4py/PETSc/Vec.pyx:218

setType(vec_type)

Set the vector type.

Collective.
Parameters

vec_type ( Type | str ) -- The vector type.

Return type

None

SEE ALSO:

create , getType , VecSetType

Source code at petsc4py/PETSc/Vec.pyx:199

setUp()

Set up the internal data structures for using the vector.

Collective.

SEE ALSO:

create , destroy , VecSetUp

Source code at petsc4py/PETSc/Vec.pyx:1054
Return type

Self

setValue(index, value, addv=None)

Insert or add a single value in the vector.

Not collective.
Parameters

	•		index ( int ) -- Location to write to. Negative indices are ignored.
	•		value ( Scalar ) -- Value to insert at index .
	•		addv ( InsertModeSpec ) -- Insertion mode.

Return type

None

Notes

The values may be cached so assemblyBegin and assemblyEnd must be called after all calls of this method are completed.

Multiple calls to setValue cannot be made with different values for addv without intermediate calls to assemblyBegin and assemblyEnd .

SEE ALSO:

setValues , VecSetValues

Source code at petsc4py/PETSc/Vec.pyx:2771

setValueLocal(index, value, addv=None)

Insert or add a single value in the vector using a local numbering.

Not collective.
Parameters

	•		index ( int ) -- Location to write to.
	•		value ( Scalar ) -- Value to insert at index .
	•		addv ( InsertModeSpec ) -- Insertion mode.

Return type

None

Notes

The values may be cached so assemblyBegin and assemblyEnd must be called after all calls of this method are completed.

Multiple calls to setValueLocal cannot be made with different values for addv without intermediate calls to assemblyBegin and assemblyEnd .

SEE ALSO:

setValuesLocal , VecSetValuesLocal

Source code at petsc4py/PETSc/Vec.pyx:2914

setValues(indices, values, addv=None)

Insert or add multiple values in the vector.

Not collective.
Parameters

	•		indices ( Sequence[int] ) -- Locations to write to. Negative indices are ignored.
	•		values ( Sequence[Scalar] ) -- Values to insert at indices .
	•		addv ( InsertModeSpec ) -- Insertion mode.

Return type

None

Notes

The values may be cached so assemblyBegin and assemblyEnd must be called after all calls of this method are completed.

Multiple calls to setValues cannot be made with different values for addv without intermediate calls to assemblyBegin and assemblyEnd .

SEE ALSO:

setValue , VecSetValues

Source code at petsc4py/PETSc/Vec.pyx:2808

setValuesBlocked(indices, values, addv=None)

Insert or add blocks of values in the vector.

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

	•		indices ( Sequence[int] ) -- Block indices to write to. Negative indices are ignored.
	•		values ( Sequence[Scalar] ) -- Values to insert at indices . Should have length *len(indices) vec.block_size** .
	•		addv ( InsertModeSpec ) -- Insertion mode.

Return type

None

Notes

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

setValues , VecSetValuesBlocked

Source code at petsc4py/PETSc/Vec.pyx:2842

setValuesBlockedLocal(indices, values, addv=None)

Insert or add blocks of values in the vector with a local numbering.

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

	•		indices ( Sequence[int] ) -- Local block indices to write to.
	•		values ( Sequence[Scalar] ) -- Values to insert at indices . Should have length *len(indices) vec.block_size** .
	•		addv ( InsertModeSpec ) -- Insertion mode.

Return type

None

Notes

The values may be cached so assemblyBegin and assemblyEnd must be called after all calls of this method are completed.

Multiple calls to setValuesBlockedLocal cannot be made with different values for addv without intermediate calls to assemblyBegin and assemblyEnd .

SEE ALSO:

setValuesBlocked , setValuesLocal , - VecSetValuesBlockedLocal

Source code at petsc4py/PETSc/Vec.pyx:2985

setValuesLocal(indices, values, addv=None)

Insert or add multiple values in the vector with a local numbering.

Not collective.
Parameters

	•		indices ( Sequence[int] ) -- Locations to write to.
	•		values ( Sequence[Scalar] ) -- Values to insert at indices .
	•		addv ( InsertModeSpec ) -- Insertion mode.

Return type

None

Notes

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

SEE ALSO:

setValues , VecSetValuesLocal

Source code at petsc4py/PETSc/Vec.pyx:2951

setValuesStagStencil(indices, values, addv=None)

Not implemented.

Source code at petsc4py/PETSc/Vec.pyx:2880
Return type

None

shift(alpha)

Shift all entries in the vector.

Collective.

This method sets each entry (xₙ) in the vector to xₙ + ɑ.
Parameters

alpha ( Scalar ) -- The shift to apply to the vector values.

Return type

None

SEE ALSO:

scale , VecShift

Source code at petsc4py/PETSc/Vec.pyx:2423

sqrtabs()

Replace each entry (xₙ) in the vector by √|xₙ|.

Logically collective.

SEE ALSO:

VecSqrtAbs

Source code at petsc4py/PETSc/Vec.pyx:2281
Return type

None

strideGather(field, vec, addv=None)

Insert component values into a single-component vector.

Collective.

The current vector is expected to be multi-component (- block_size greater than 1 ) and the target vector is expected to be single-component.
Parameters

	•		field ( int ) -- Component index. Must be between 0 and vec.block_size .
	•		vec ( Vec ) -- Single-component vector to be inserted into.
	•		addv ( InsertModeSpec ) -- Insertion mode.

Return type

None

SEE ALSO:

strideScatter , VecStrideScatter

Source code at petsc4py/PETSc/Vec.pyx:3231

strideMax(field)

Return the maximum of entries in a subvector.

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.
	•		float -- Maximum value.

Return type

tuple [ int , float ]

SEE ALSO:

strideScale , strideSum , strideMin , VecStrideMax

Source code at petsc4py/PETSc/Vec.pyx:3137

strideMin(field)

Return the minimum of entries in a subvector.

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

Source code at petsc4py/PETSc/Vec.pyx:3106

strideNorm(field, norm_type=None)

Return the norm of entries in a subvector.

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.

Return type

float | tuple [ float , float ]

SEE ALSO:

norm , strideScale , strideSum , VecStrideNorm

Source code at petsc4py/PETSc/Vec.pyx:3168

strideScale(field, alpha)

Scale a component of the vector.

Logically collective.
Parameters

	•		field ( int ) -- Component index. Must be between 0 and vec.block_size .
	•		alpha ( Scalar ) -- Factor to multiple the component entries by.

Return type

None

SEE ALSO:

strideSum , strideMin , strideMax , VecStrideScale

Source code at petsc4py/PETSc/Vec.pyx:3062

strideScatter(field, vec, addv=None)

Scatter entries into a component of another vector.

Collective.

The current vector is expected to be single-component (- block_size of 1 ) and the target vector is expected to be multi-component.
Parameters

	•		field ( int ) -- Component index. Must be between 0 and vec.block_size .
	•		vec ( Vec ) -- Multi-component vector to be scattered into.
	•		addv ( InsertModeSpec ) -- Insertion mode.

Return type

None

SEE ALSO:

strideGather , VecStrideScatter

Source code at petsc4py/PETSc/Vec.pyx:3200

strideSum(field)

Sum subvector entries.

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

Source code at petsc4py/PETSc/Vec.pyx:3083

sum()

Return the sum of all the entries of the vector.

Collective.

SEE ALSO:

VecSum

Source code at petsc4py/PETSc/Vec.pyx:2166
Return type

Scalar

swap(vec)

Swap the content of two vectors.

Logically collective.
Parameters

vec ( Vec ) -- The vector to swap data with.

Return type

None

SEE ALSO:

VecSwap

Source code at petsc4py/PETSc/Vec.pyx:2443

tDot(vec)

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

vec ( Vec ) -- Vector to compute the indefinite dot product with.

Return type

Scalar

SEE ALSO:

tDotBegin , tDotEnd , dot , VecTDot

Source code at petsc4py/PETSc/Vec.pyx:1846

tDotBegin(vec)

Begin computing the indefinite dot product.

Collective.

This should be paired with a call to tDotEnd .
Parameters

vec ( Vec ) -- Vector to compute the indefinite dot product with.

Return type

None

SEE ALSO:

tDotEnd , tDot , VecTDotBegin

Source code at petsc4py/PETSc/Vec.pyx:1868

tDotEnd(vec)

Finish computing the indefinite dot product initiated with tDotBegin .

Collective.

SEE ALSO:

tDotBegin , tDot , VecTDotEnd

Source code at petsc4py/PETSc/Vec.pyx:1888
Parameters

vec ( Vec )

Return type

Scalar

toDLPack(mode='rw')

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

Notes

It is important that the access mode is respected by the consumer as this is not enforced internally.

SEE ALSO:

createWithDLPack

Source code at petsc4py/PETSc/Vec.pyx:726

view(viewer=None)

Display the vector.

Collective.
Parameters

viewer ( Viewer | None ) -- A Viewer instance or - None for the default viewer.

Return type

None

SEE ALSO:

load , VecView

Source code at petsc4py/PETSc/Vec.pyx:144

waxpy(alpha, x, y)

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:

axpy , aypx , axpby , maxpy , VecWAXPY

Source code at petsc4py/PETSc/Vec.pyx:2547

zeroEntries()

Set all entries in the vector to zero.

Logically collective.

SEE ALSO:

set , VecZeroEntries

Source code at petsc4py/PETSc/Vec.pyx:2358
Return type

None

Attributes Documentation

array

Alias for array_w .

Source code at petsc4py/PETSc/Vec.pyx:3642

array_r

Read-only ndarray containing the local portion of the vector.

Source code at petsc4py/PETSc/Vec.pyx:3632

array_w

Writeable ndarray containing the local portion of the vector.

Source code at petsc4py/PETSc/Vec.pyx:3623

block_size

The block size.

Source code at petsc4py/PETSc/Vec.pyx:3598

buffer

Alias for buffer_w .

Source code at petsc4py/PETSc/Vec.pyx:3637

buffer_r

Read-only buffered view of the local portion of the vector.

Source code at petsc4py/PETSc/Vec.pyx:3618

buffer_w

Writeable buffered view of the local portion of the vector.

Source code at petsc4py/PETSc/Vec.pyx:3613

local_size

The local vector size.

Source code at petsc4py/PETSc/Vec.pyx:3593

owner_range

The locally owned range of indices in the form [low, high) .

Source code at petsc4py/PETSc/Vec.pyx:3603

owner_ranges

The range of indices owned by each process.

Source code at petsc4py/PETSc/Vec.pyx:3608

size

The global vector size.

Source code at petsc4py/PETSc/Vec.pyx:3588

sizes

The local and global vector sizes.

Source code at petsc4py/PETSc/Vec.pyx:3580

petsc4py.PETSc.Viewer

class petsc4py.PETSc.Viewer

Bases: Object

Viewer object.

Viewer is described in the PETSc manual .

Viewers can be called as functions where the argument specified is the PETSc object to be viewed. See 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:

PetscViewer

Enumerations

Image grohtml-288464-175.png

petsc4py.PETSc.Viewer.DrawSize

class petsc4py.PETSc.Viewer.DrawSize

Bases: object

Window size.

Attributes Summary

Image grohtml-288464-176.png

Attributes Documentation
FULL: int = FULL

Constant FULL of type int

FULL_SIZE: int = FULL_SIZE

Constant FULL_SIZE of type int

HALF: int = HALF

Constant HALF of type int

HALF_SIZE: int = HALF_SIZE

Constant HALF_SIZE of type int

QUARTER: int = QUARTER

Constant QUARTER of type int

QUARTER_SIZE: int = QUARTER_SIZE

Constant QUARTER_SIZE of type int

THIRD: int = THIRD

Constant THIRD of type int

THIRD_SIZE: int = THIRD_SIZE

Constant THIRD_SIZE of type int

petsc4py.PETSc.Viewer.FileMode

class petsc4py.PETSc.Viewer.FileMode

Bases: object

Viewer file mode.

Attributes Summary

Image grohtml-288464-177.png

Attributes Documentation
A: int = A

Constant A of type int

APPEND: int = APPEND

Constant APPEND of type int

APPEND_UPDATE: int = APPEND_UPDATE

Constant APPEND_UPDATE of type int

AU: int = AU

Constant AU of type int

R: int = R

Constant R of type int

READ: int = READ

Constant READ of type int

U: int = U

Constant U of type int

UA: int = UA

Constant UA of type int

UPDATE: int = UPDATE

Constant UPDATE of type int

W: int = W

Constant W of type int

WRITE: int = WRITE

Constant WRITE of type int

petsc4py.PETSc.Viewer.Format

class petsc4py.PETSc.Viewer.Format

Bases: object

Viewer format.

Attributes Summary

Image grohtml-288464-178.png

Attributes Documentation
ASCII_COMMON: int = ASCII_COMMON

Constant ASCII_COMMON of type int

ASCII_CSV: int = ASCII_CSV

Constant ASCII_CSV of type int

ASCII_DENSE: int = ASCII_DENSE

Constant ASCII_DENSE of type int

ASCII_FACTOR_INFO: int = ASCII_FACTOR_INFO

Constant ASCII_FACTOR_INFO of type int

ASCII_GLVIS: int = ASCII_GLVIS

Constant ASCII_GLVIS of type int

ASCII_IMPL: int = ASCII_IMPL

Constant ASCII_IMPL of type int

ASCII_INDEX: int = ASCII_INDEX

Constant ASCII_INDEX of type int

ASCII_INFO: int = ASCII_INFO

Constant ASCII_INFO of type int

ASCII_INFO_DETAIL: int = ASCII_INFO_DETAIL

Constant ASCII_INFO_DETAIL of type int

ASCII_LATEX: int = ASCII_LATEX

Constant ASCII_LATEX of type int

ASCII_MATHEMATICA: int = ASCII_MATHEMATICA

Constant ASCII_MATHEMATICA of type int

ASCII_MATLAB: int = ASCII_MATLAB

Constant ASCII_MATLAB of type int

ASCII_MATRIXMARKET: int = ASCII_MATRIXMARKET

Constant ASCII_MATRIXMARKET of type int

ASCII_PCICE: int = ASCII_PCICE

Constant ASCII_PCICE of type int

ASCII_PYTHON: int = ASCII_PYTHON

Constant ASCII_PYTHON of type int

ASCII_SYMMODU: int = ASCII_SYMMODU

Constant ASCII_SYMMODU of type int

ASCII_VTK: int = ASCII_VTK

Constant ASCII_VTK of type int

ASCII_VTK_CELL: int = ASCII_VTK_CELL

Constant ASCII_VTK_CELL of type int

ASCII_VTK_COORDS: int = ASCII_VTK_COORDS

Constant ASCII_VTK_COORDS of type int

ASCII_XML: int = ASCII_XML

Constant ASCII_XML of type int

BINARY_MATLAB: int = BINARY_MATLAB

Constant BINARY_MATLAB of type int

DEFAULT: int = DEFAULT

Constant DEFAULT of type int

DRAW_BASIC: int = DRAW_BASIC

Constant DRAW_BASIC of type int

DRAW_CONTOUR: int = DRAW_CONTOUR

Constant DRAW_CONTOUR of type int

DRAW_LG: int = DRAW_LG

Constant DRAW_LG of type int

DRAW_LG_XRANGE: int = DRAW_LG_XRANGE

Constant DRAW_LG_XRANGE of type int

DRAW_PORTS: int = DRAW_PORTS

Constant DRAW_PORTS of type int

FAILED: int = FAILED

Constant FAILED of type int

HDF5_MAT: int = HDF5_MAT

Constant HDF5_MAT of type int

HDF5_PETSC: int = HDF5_PETSC

Constant HDF5_PETSC of type int

HDF5_VIZ: int = HDF5_VIZ

Constant HDF5_VIZ of type int

HDF5_XDMF: int = HDF5_XDMF

Constant HDF5_XDMF of type int

LOAD_BALANCE: int = LOAD_BALANCE

Constant LOAD_BALANCE of type int

NATIVE: int = NATIVE

Constant NATIVE of type int

NOFORMAT: int = NOFORMAT

Constant NOFORMAT of type int

VTK_VTR: int = VTK_VTR

Constant VTK_VTR of type int

VTK_VTS: int = VTK_VTS

Constant VTK_VTS of type int

VTK_VTU: int = VTK_VTU

Constant VTK_VTU of type int

petsc4py.PETSc.Viewer.Type

class petsc4py.PETSc.Viewer.Type

Bases: object

Viewer type.

Attributes Summary

Image grohtml-288464-179.png

Attributes Documentation
ADIOS: str = ADIOS

Object ADIOS of type str

ASCII: str = ASCII

Object ASCII of type str

BINARY: str = BINARY

Object BINARY of type str

DRAW: str = DRAW

Object DRAW of type str

EXODUSII: str = EXODUSII

Object EXODUSII of type str

GLVIS: str = GLVIS

Object GLVIS of type str

HDF5: str = HDF5

Object HDF5 of type str

MATHEMATICA: str = MATHEMATICA

Object MATHEMATICA of type str

MATLAB: str = MATLAB

Object MATLAB of type str

SAWS: str = SAWS

Object SAWS of type str

SOCKET: str = SOCKET

Object SOCKET of type str

STRING: str = STRING

Object STRING of type str

VTK: str = VTK

Object VTK of type str

VU: str = VU

Object VU of type str

Methods Summary

Image grohtml-288464-180.png

Methods Documentation
classmethod ASCII(name, comm=None)

Return an ASCII viewer associated with the communicator.

Collective.
Parameters

	•		name ( str ) -- The filename.
	•		comm ( Comm \| None ) -- MPI communicator, defaults to Sys.getDefaultComm .

Return type

Viewer

Source code at petsc4py/PETSc/Viewer.pyx:580

classmethod BINARY(comm=None)

Return the default Type.BINARY viewer associated with the communicator.

Collective.
Parameters

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

Return type

Viewer

Source code at petsc4py/PETSc/Viewer.pyx:601

classmethod DRAW(comm=None)

Return the default Type.DRAW viewer associated with the communicator.

Collective.
Parameters

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

Return type

Viewer

Source code at petsc4py/PETSc/Viewer.pyx:619

classmethod STDERR(comm=None)

Return the standard error viewer associated with the communicator.

Collective.
Parameters

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

Return type

Viewer

Source code at petsc4py/PETSc/Viewer.pyx:562

classmethod STDOUT(comm=None)

Return the standard output viewer associated with the communicator.

Collective.
Parameters

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

Return type

Viewer

Source code at petsc4py/PETSc/Viewer.pyx:544

addASCIITab(tabs)

Increment the ASCII tab level.

Collective.

SEE ALSO:

PetscViewerASCIIAddTab

Source code at petsc4py/PETSc/Viewer.pyx:666
Parameters

tabs ( int )

Return type

None

clearDraw()

Reset graphics.

Not collective.

SEE ALSO:

PetscViewerDrawClear

Source code at petsc4py/PETSc/Viewer.pyx:897
Return type

None

create(comm=None)

Create a viewer.

Collective.
Parameters

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

Return type

Self

SEE ALSO:

Sys.getDefaultComm , PetscViewerCreate

Source code at petsc4py/PETSc/Viewer.pyx:180

createASCII(name, mode=None, comm=None)

Create a viewer of type Type.ASCII .

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:

create , setType , setFileMode , setFileName , Sys.getDefaultComm , setASCIITab , addASCIITab , subtractASCIITab , getASCIITab

Source code at petsc4py/PETSc/Viewer.pyx:201

createBinary(name, mode=None, comm=None)

Create a viewer of type Type.BINARY .

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:

create , setType , setFileMode , setFileName , Sys.getDefaultComm

Source code at petsc4py/PETSc/Viewer.pyx:239

createDraw(display=None, title=None, position=None, size=None,
comm=None)

Create a Type.DRAW viewer.

Collective.
Parameters

	•		display ( str \| None ) -- The X display to use or None for the local machine.
	•		title ( str \| None ) -- The window title or None for no title.
	•		position ( tuple[int, int] \| None ) -- Screen coordinates of the upper left corner, or None for default.
	•		size ( tuple[int, int] \| int \| None ) -- 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 at petsc4py/PETSc/Viewer.pyx:381

createHDF5(name, mode=None, comm=None)

Create a viewer of type Type.HDF5 .

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:

create , setType , setFileMode , setFileName , Sys.getDefaultComm

Source code at petsc4py/PETSc/Viewer.pyx:345

createMPIIO(name, mode=None, comm=None)

Create a viewer of type Type.BINARY supporting MPI-IO.

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:

create , setType , setFileMode , setFileName , Sys.getDefaultComm

Source code at petsc4py/PETSc/Viewer.pyx:272

createVTK(name, mode=None, comm=None)

Create a viewer of type Type.VTK .

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:

create , setType , setFileMode , setFileName , Sys.getDefaultComm

Source code at petsc4py/PETSc/Viewer.pyx:309

destroy()

Destroy the viewer.

Collective.

SEE ALSO:

PetscViewerDestroy

Source code at petsc4py/PETSc/Viewer.pyx:167
Return type

Self

flush()

Flush the viewer.

Collective.

SEE ALSO:

PetscViewerFlush

Source code at petsc4py/PETSc/Viewer.pyx:785
Return type

None

getASCIITab()

Return the ASCII tab level.

Not collective.

SEE ALSO:

setASCIITab , PetscViewerASCIIGetTab

Source code at petsc4py/PETSc/Viewer.pyx:652
Return type

int

getFileMode()

Return the file mode.

Not collective.

SEE ALSO:

setFileMode , PetscViewerFileGetMode

Source code at petsc4py/PETSc/Viewer.pyx:809
Return type

FileMode

getFileName()

Return file name.

Not collective.

SEE ALSO:

setFileName , PetscViewerFileGetName

Source code at petsc4py/PETSc/Viewer.pyx:837
Return type

str

getFormat()

Return the format of the viewer.

Not collective.

SEE ALSO:

pushFormat , popFormat , PetscViewerGetFormat

Source code at petsc4py/PETSc/Viewer.pyx:464
Return type

Format

getSubViewer(comm=None)

Return a viewer defined on a subcommunicator.

Collective.
Parameters

comm ( Comm | None ) -- The subcommunicator. If - None , uses COMM_SELF .

Return type

Viewer

Notes

Users must call restoreSubViewer when done.

SEE ALSO:

restoreSubViewer , PetscViewerGetSubViewer

Source code at petsc4py/PETSc/Viewer.pyx:502

getType()

Return the type of the viewer.

Not collective.

SEE ALSO:

setType , PetscViewerGetType

Source code at petsc4py/PETSc/Viewer.pyx:450
Return type

str

popASCIISynchronized()

Disallow ASCII synchronized calls.

Collective.

SEE ALSO:

printfASCIISynchronized , pushASCIISynchronized , - PetscViewerASCIIPopSynchronized

Source code at petsc4py/PETSc/Viewer.pyx:705
Return type

None

popASCIITab()

Pop an additional tab level pushed via pushASCIITab .

Collective.

SEE ALSO:

pushASCIITab , PetscViewerASCIIPopTab

Source code at petsc4py/PETSc/Viewer.pyx:730
Return type

None

popFormat()

Pop format from the viewer.

Collective.

SEE ALSO:

pushFormat , PetscViewerPopFormat

Source code at petsc4py/PETSc/Viewer.pyx:490
Return type

None

printfASCII(msg)

Print a message.

Collective.

SEE ALSO:

PetscViewerASCIIPrintf

Source code at petsc4py/PETSc/Viewer.pyx:755
Parameters

msg ( str )

Return type

None

printfASCIISynchronized(msg)

Print a synchronized message.

Collective.

SEE ALSO:

pushASCIISynchronized , - PetscViewerASCIISynchronizedPrintf

Source code at petsc4py/PETSc/Viewer.pyx:769
Parameters

msg ( str )

Return type

None

pushASCIISynchronized()

Allow ASCII synchronized calls.

Collective.

SEE ALSO:

printfASCIISynchronized , popASCIISynchronized , - PetscViewerASCIIPushSynchronized

Source code at petsc4py/PETSc/Viewer.pyx:692
Return type

None

pushASCIITab()

Push an additional tab level.

Collective.

SEE ALSO:

popASCIITab , PetscViewerASCIIPushTab

Source code at petsc4py/PETSc/Viewer.pyx:718
Return type

None

pushFormat(format)

Push format to the viewer.

Collective.

SEE ALSO:

popFormat , PetscViewerPushFormat

Source code at petsc4py/PETSc/Viewer.pyx:478
Parameters

format ( Format )

Return type

None

restoreSubViewer(sub)

Restore a viewer defined on a subcommunicator.

Collective.
Parameters

sub ( Viewer ) -- The subviewer obtained from getSubViewer .

Return type

None

SEE ALSO:

getSubViewer , PetscViewerRestoreSubViewer

Source code at petsc4py/PETSc/Viewer.pyx:526

setASCIITab(tabs)

Set ASCII tab level.

Collective.

SEE ALSO:

getASCIITab , PetscViewerASCIISetTab

Source code at petsc4py/PETSc/Viewer.pyx:639
Parameters

tabs ( int )

Return type

None

setDrawInfo(display=None, title=None, position=None, size=None)

Set window information for a Type.DRAW viewer.

Collective.
Parameters

	•		display ( str \| None ) -- The X display to use or None for the local machine.
	•		title ( str \| None ) -- The window title or None for no title.
	•		position ( tuple[int, int] \| None ) -- Screen coordinates of the upper left corner, or None for default.
	•		size ( tuple[int, int] \| int \| None ) -- Window size or None for default.

Return type

None

Source code at petsc4py/PETSc/Viewer.pyx:853

setFileMode(mode)

Set file mode.

Collective.

SEE ALSO:

getFileMode , PetscViewerFileSetMode

Source code at petsc4py/PETSc/Viewer.pyx:797
Parameters

mode ( FileMode | str )

Return type

None

setFileName(name)

Set file name.

Collective.

SEE ALSO:

getFileName , PetscViewerFileSetName

Source code at petsc4py/PETSc/Viewer.pyx:823
Parameters

name ( str )

Return type

None

setType(vwr_type)

Set the type of the viewer.

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

subtractASCIITab(tabs)

Decrement the ASCII tab level.

Collective.

SEE ALSO:

PetscViewerASCIISubtractTab

Source code at petsc4py/PETSc/Viewer.pyx:679
Parameters

tabs ( int )

Return type

None

useASCIITabs(flag)

Enable/disable the use of ASCII tabs.

Collective.

SEE ALSO:

PetscViewerASCIIUseTabs

Source code at petsc4py/PETSc/Viewer.pyx:742
Parameters

flag ( bool )

Return type

None

view(obj=None)

View the viewer.

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

petsc4py.PETSc.ViewerHDF5

class petsc4py.PETSc.ViewerHDF5

Bases: Viewer

Viewer object for HDF5 file formats.

Viewer is described in the PETSc manual .

SEE ALSO:

Viewer

Methods Summary

Image grohtml-288464-181.png

Methods Documentation
create(name, mode=None, comm=None)

Create a viewer of type Type.HDF5 .

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

Source code at petsc4py/PETSc/Viewer.pyx:922

getGroup()

Return the current group.

Not collective.

SEE ALSO:

pushGroup , popGroup , PetscViewerHDF5GetGroup

Source code at petsc4py/PETSc/Viewer.pyx:1049
Return type

str

getTimestep()

Return the current time step.

Not collective.

SEE ALSO:

pushTimestepping , setTimestep , incrementTimestep , - PetscViewerHDF5GetTimestep

Source code at petsc4py/PETSc/Viewer.pyx:982
Return type

int

incrementTimestep()

Increment the time step.

Logically collective.

SEE ALSO:

pushTimestepping , setTimestep , getTimestep , - PetscViewerHDF5IncrementTimestep

Source code at petsc4py/PETSc/Viewer.pyx:1010
Return type

None

popGroup()

Pop the current group from the stack.

Logically collective.

SEE ALSO:

pushGroup , getGroup , PetscViewerHDF5PopGroup

Source code at petsc4py/PETSc/Viewer.pyx:1037
Return type

None

popTimestepping()

Deactivate the timestepping mode.

Logically collective.

SEE ALSO:

pushTimestepping , PetscViewerHDF5PopTimestepping

Source code at petsc4py/PETSc/Viewer.pyx:970
Return type

None

pushGroup(group)

Set the current group.

Logically collective.

SEE ALSO:

popGroup , getGroup , PetscViewerHDF5PushGroup

Source code at petsc4py/PETSc/Viewer.pyx:1023
Parameters

group ( str )

Return type

None

pushTimestepping()

Activate the timestepping mode.

Logically collective.

SEE ALSO:

popTimestepping , PetscViewerHDF5PushTimestepping

Source code at petsc4py/PETSc/Viewer.pyx:958
Return type

None

setTimestep(timestep)

Set the current time step.

Logically collective.

SEE ALSO:

pushTimestepping , getTimestep , incrementTimestep , - PetscViewerHDF5SetTimestep

Source code at petsc4py/PETSc/Viewer.pyx:997
Parameters

timestep ( int )

Return type

None

Exceptions

Image grohtml-288464-182.png

petsc4py.PETSc.Error

exception petsc4py.PETSc.Error

PETSc Error.

ierr

PETSc error code.

Type

int

Functions

Image grohtml-288464-183.png

petsc4py.PETSc.garbage_cleanup

petsc4py.PETSc.garbage_cleanup(comm=None)

Clean up unused PETSc objects.

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:39
Parameters

comm ( Comm | None )

Return type

None

petsc4py.PETSc.garbage_view

petsc4py.PETSc.garbage_view(comm=None)

Print summary of the garbage PETSc objects.

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:63
Parameters

comm ( Comm | None )

Return type

None

Attributes

Image grohtml-288464-184.png

petsc4py.PETSc.DECIDE

petsc4py.PETSc.DECIDE: int = DECIDE

Constant DECIDE of type int

petsc4py.PETSc.DEFAULT

petsc4py.PETSc.DEFAULT: int = DEFAULT

Constant DEFAULT of type int

petsc4py.PETSc.DETERMINE

petsc4py.PETSc.DETERMINE: int = DETERMINE

Constant DETERMINE of type int

petsc4py.PETSc.CURRENT

petsc4py.PETSc.CURRENT: int = CURRENT

Constant CURRENT of type int

petsc4py.PETSc.UNLIMITED

petsc4py.PETSc.UNLIMITED: int = UNLIMITED

Constant UNLIMITED of type int

petsc4py.PETSc.INFINITY

petsc4py.PETSc.INFINITY: float = INFINITY

Object INFINITY of type float

petsc4py.PETSc.NINFINITY

petsc4py.PETSc.NINFINITY: float = NINFINITY

Object NINFINITY of type float

petsc4py.PETSc.PINFINITY

petsc4py.PETSc.PINFINITY: float = PINFINITY

Object PINFINITY of type float

petsc4py.PETSc.COMM_NULL

petsc4py.PETSc.COMM_NULL: Comm = COMM_NULL

Object COMM_NULL of type Comm

petsc4py.PETSc.COMM_SELF

petsc4py.PETSc.COMM_SELF: Comm = COMM_SELF

Object COMM_SELF of type Comm

petsc4py.PETSc.COMM_WORLD

petsc4py.PETSc.COMM_WORLD: Comm = COMM_WORLD

Object COMM_WORLD of type Comm

PETSC PYTHON TYPES

Here we discuss details about Python-aware PETSc types that can be used within the library.

In particular, we discuss matrices, preconditioners, Krylov solvers, nonlinear solvers and ODE integrators.

The low-level, Cython implementation exposing the Python methods is in src/petsc4py/PETSc/libpetsc4py.pyx .

The scripts used here can be found at demo/python_types .

PETSc Python matrix type

PETSc provides a convenient way to compute the action of linear operators coded in Python through the petsc4py.PETSc.Mat.Type.PYTHON type.

In addition to the matrix action, the implementation can expose additional methods for use within the library. A template class for the supported methods is given below.

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 missingDiagonal(self, A: Mat, d: Vec, im: InsertMode) -> tuple[bool, int]:
"""Return a flag indicating if the matrix is missing a diagonal entry and the location."""
...

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)."""
...

In the example below, we create an operator that applies the Laplacian operator on a two-dimensional grid, and use it to solve the associated linear system. The default preconditioner in the script is petsc4py.PETSc.PC.Type.JACOBI which needs to access the diagonal of the matrix.

# ------------------------------------------------------------------------
#
# 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')

PETSc Python preconditioner type

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.

"""
...

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

In the example below, we create a Jacobi preconditioner, which needs to access the diagonal of the matrix. The action of the preconditioner consists of the pointwise multiplication of the inverse diagonal with the input vector.

# 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)

We can run the script used to test our matrix class and use command line arguments to specify that our preconditioner should be used:

$ 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 = precond matrix:
Mat Object: 1 MPI process
type: python
rows=256, cols=256
Python: __main__.Poisson2D

PETSc Python linear solver type

The protocol for the petsc4py.PETSc.KSP.Type.PYTHON Krylov solver is:

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)

PETSc Python ode-integrator type (TODO)

PETSc Python optimization solver type (TODO)

WORKING WITH PETSC OPTIONS

A very powerful feature of PETSc is that objects can be configured via command-line options. In this way, one can choose the method to be used or set different parameters without changing the source code. See the PETSc manual for additional information.

In order to use command-line options in a petsc4py program, it is important to initialize the module as follows:

# 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 one can provide command-line options when running a script:

$ python foo.py -ksp_type gmres -ksp_gmres_restart 100 -ksp_view

When the above initialization method is not possible, PETSc options can be also specified via environment variables or configuration files, e.g.:

$ PETSC_OPTIONS='-ksp_type gmres -ksp_gmres_restart 100 -ksp_view' python foo.py

Command-line options can be read via an instance of the Options class. For instance:

OptDB = PETSc.Options()
n = OptDB.getInt('n', 16)
eta = OptDB.getReal('eta', 0.014)
alpha = OptDB.getScalar('alpha', -12.3)

In this way, if the script is run with

$ python foo.py -n 50 -alpha 8.8

the options, n and alpha will get the values 50 and 8.8 , respectively, while eta will be assigned the value specified as default, 0.014 .

The options database is accessible also as a Python dictionary, so that one can for instance override, insert or delete an option:

OptDB['draw_pause'] = 1
del OptDB['draw_pause']

PETSC4PY DEMOS

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.

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.

Docstring standards

Docstrings are to be written in numpydoc:format 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.

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

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.

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.

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