dolfinx.la.petsc#

Functions for working with PETSc linear algebra objects.

Note

Due to subtle issues in the interaction between petsc4py memory management and the Python garbage collector, it is recommended that the PETSc method destroy() is called on returned PETSc objects once the object is no longer required. Note that destroy() is collective over the object’s MPI communicator.

Functions

`assign`(-> None)	Assign values between arrays and a PETSc vector.
`create_vector`(maps[, kind])	Create a PETSc vector from a sequence of maps and blocksizes.
`create_vector_wrap`(x)	Wrap a distributed DOLFINx vector as a PETSc vector.
`set_diagonal`(A, rows[, diagonal, insert_mode])	Set or add values on the diagonal for given rows of a PETSc matrix.

dolfinx.la.petsc.assign(x0: ndarray[tuple[Any, ...], dtype[inexact]] | Sequence[ndarray[tuple[Any, ...], dtype[inexact]]], x1: Vec) → None[source]#
dolfinx.la.petsc.assign(x0: Vec, x1: ndarray[tuple[Any, ...], dtype[inexact]] | Sequence[ndarray[tuple[Any, ...], dtype[inexact]]]) → None: Assign values between arrays and a PETSc vector.

dolfinx.la.petsc.create_vector(maps: Sequence[tuple[IndexMap, int]], kind: str | None = None) → Vec[source]#

Create a PETSc vector from a sequence of maps and blocksizes.

Three cases are supported:

If maps=[(im_0, bs_0), ..., (im_n, bs_n)] is a sequence of indexmaps and blocksizes and kind is None``or is ``PETSc.Vec.Type.MPI, a ghosted PETSc vector with block structure described by (im_i, bs_i) is created. The created vector b is initialized such that on each MPI process b = [b_0, b_1, ..., b_n, b_0g, b_1g, ..., b_ng], where b_i are the entries associated with the ‘owned’ degrees-of- freedom for (im_i, bs_i) and b_ig are the ‘unowned’ (ghost) entries.

If more than one tuple is supplied, the returned vector has an attribute _blocks that holds the local offsets into b for the (i) owned and (ii) ghost entries for each V[i]. It can be accessed by b.getAttr("_blocks"). The offsets can be used to get views into b for blocks, e.g.:
```
>>> offsets0, offsets1, = b.getAttr("_blocks")
>>> offsets0
(0, 12, 28)
>>> offsets1
(28, 32, 35)
>>> b0_owned = b.array[offsets0[0]:offsets0[1]]
>>> b0_ghost = b.array[offsets1[0]:offsets1[1]]
>>> b1_owned = b.array[offsets0[1]:offsets0[2]]
>>> b1_ghost = b.array[offsets1[1]:offsets1[2]]
```
If V=[(im_0, bs_0), ..., (im_n, bs_n)] is a sequence of function space and kind is PETSc.Vec.Type.NEST, a PETSc nested vector (a ‘nest’ of ghosted PETSc vectors) is created.

Parameters:

maps – Sequence of tuples of IndexMap and the associated block size.
kind – PETSc vector type (VecType) to create.

Returns:

A PETSc vector with the prescribed layout. The vector is not initialised to zero.

dolfinx.la.petsc.create_vector_wrap(x: Vector) → Vec[source]#

Wrap a distributed DOLFINx vector as a PETSc vector.

Parameters:: x – The vector to wrap as a PETSc vector.
Returns:: A PETSc vector that shares data with x.

dolfinx.la.petsc.set_diagonal(A: Mat, rows: ndarray[tuple[Any, ...], dtype[int32]], diagonal: float | complex | ndarray[tuple[Any, ...], dtype[_ScalarT]] = 1.0, insert_mode: InsertMode = InsertMode.INSERT_VALUES) → None[source]#

Set or add values on the diagonal for given rows of a PETSc matrix.

Parameters:

A – Matrix to modify.
rows – Rows, in local indices, to set the diagonal value for.
diagonal – Value to set on the diagonal, either a single value for all rows or an array with diagonal[i] the value for rows[i]. An array must have the same length as rows.
insert_mode – PETSc.InsertMode.INSERT to overwrite the diagonal entry, or PETSc.InsertMode.ADD to add to it. The two agree on rows that assembly has already zeroed, and ADD avoids the flush needed to take the matrix out of add mode.

Note

A row that the calling rank does not own is accumulated into the owner’s entry when the matrix is assembled, so pass owned rows unless that accumulation is intended. A row repeated in rows is likewise written once per occurrence.

Note

The matrix is not assembled.