dolfinx.la#

Linear algebra functionality.

Functions

`is_orthonormal`(basis[, eps])	Check that list of vectors are orthonormal.
`matrix_csr`(sp, block_mode, dtype, ...)	Create a distributed sparse matrix.
`norm`(x[, type])	Compute a norm of the vector.
`orthonormalize`(basis)	Orthogonalise set of vectors in-place.
`sparsity_pattern`(comm, maps, bs)	Create a sparsity pattern for a matrix.
`sparsity_pattern_blocked`(comm, patterns, ...)	Create a sparsity pattern from a rectangular array of patterns.
`vector`(map, bs, scatterer, *, dtype, ...)	Create a distributed vector.

Classes

`InsertMode`(*values)
`MatrixCSR`(A)	Distributed compressed sparse row matrix.
`Norm`(*values)
`SparsityPattern`(sp)	Sparsity pattern of a distributed sparse matrix.
`Vector`(x)	Distributed vector object.

class dolfinx.la.InsertMode(*values)#

Bases: Enum

add = 0#

insert = 1#

class dolfinx.la.MatrixCSR(A: MatrixCSR_float32 | MatrixCSR_float64 | MatrixCSR_complex64 | MatrixCSR_complex128)[source]#

Bases: Generic[Scalar]

Distributed compressed sparse row matrix.

Create a distributed compressed sparse row matrix.

Note

Objects of this type should be created using matrix_csr() and not created using this initialiser.

Parameters:: A – The C++/nanobind matrix object.

add(x: ndarray[tuple[Any, ...], dtype[Scalar]], rows: ndarray[tuple[Any, ...], dtype[int32]], cols: ndarray[tuple[Any, ...], dtype[int32]], bs: int = 1) → None[source]#: Add a block of values in the matrix.

property block_size: list#: Block sizes for the matrix.

property data: ndarray[tuple[Any, ...], dtype[Scalar]]#: Underlying matrix entry data.

eliminate_zeros(tol: float = 0) → None[source]#

Remove explicitly-stored entries that are within a tolerance.

This compacts the underlying storage: entries with abs(value) <= tol are dropped, and the column indices and row pointers are updated accordingly. Entries with abs(value) > tol are left untouched.

Note

This is a terminal, finalizing operation. It can reduce the matrix’s sparsity, which invalidates the precomputed communication pattern used to accumulate ghost row contributions. After calling this, the matrix can no longer be modified: further calls to add(), set(), or scatter_reverse() will raise a RuntimeError. Only call this once, after the matrix is fully assembled (i.e. after the final scatter_reverse()).

Parameters:: tol – Entries with magnitude less than or equal to tol are removed from storage. Defaults to removing only exact zeros.

index_map(i: int) → IndexMap[source]#

Index map for row/column.

Parameters:: i – 0 for row map, 1 for column map.

property indices: ndarray[tuple[Any, ...], dtype[int32]]#: Local column indices.

property indptr: ndarray[tuple[Any, ...], dtype[int64]]#: Local row pointers.

matmul(B: MatrixCSR[Scalar]) → MatrixCSR[Scalar][source]#

Compute matrix product A * B, where A is this matrix.

Parameters:: B – Input Matrix to multiply by

mult(x: Vector[Scalar], y: Vector[Scalar], transpose: bool = False) → None[source]#

Compute y += Ax or y += A^T x.

Parameters:

x – Input Vector
y – Output Vector
transpose – if True, compute y += A^T x

scatter_reverse() → None[source]#: Scatter and accumulate ghost values.

set(x: ndarray[tuple[Any, ...], dtype[Scalar]], rows: ndarray[tuple[Any, ...], dtype[int32]], cols: ndarray[tuple[Any, ...], dtype[int32]], bs: int = 1) → None[source]#: Set a block of values in the matrix.

set_value(x: Scalar) → None[source]#

Set all non-zero entries to a value.

Parameters:: x – The value to set all non-zero entries to.

squared_norm() → float[source]#: Compute the squared Frobenius norm.

Note

This operation is collective and requires communication.

to_dense() → ndarray[tuple[Any, ...], dtype[Scalar]][source]#: Copy to a dense 2D array.

Note

Typically used for debugging.

to_scipy(ghosted: bool = False) → _sparse.csr_matrix | _sparse.bsr_matrix[source]#

Convert to a SciPy CSR/BSR matrix. Data is shared.

Note

SciPy must be available.

Parameters:: ghosted – If True rows that are ghosted in parallel are included in the returned SciPy matrix, otherwise ghost rows are not included.
Returns:: SciPy compressed sparse row (both block sizes equal to one) or a SciPy block compressed sparse row matrix.

transpose() → MatrixCSR[Scalar][source]#: Compute transpose matrix.

class dolfinx.la.Norm(*values)#

Bases: Enum

frobenius = 3#

l1 = 0#

l2 = 1#

linf = 2#

class dolfinx.la.SparsityPattern(sp: SparsityPattern)[source]#

Bases: object

Sparsity pattern of a distributed sparse matrix.

A pattern is built by inserting (row, column) index pairs and then finalizing. Once finalized, it defines the nonzero structure and the parallel distribution of a MatrixCSR.

Create a sparsity pattern.

Note

Objects of this type should be created using sparsity_pattern(), sparsity_pattern_blocked() or dolfinx.fem.create_sparsity_pattern(), and not using this initialiser.

Parameters:: sp – The C++/nanobind sparsity pattern object.

finalize() → None[source]#

Finalize the pattern.

The pattern cannot be modified after finalizing, and it must be finalized before a matrix can be created from it.

property graph: tuple[ndarray[tuple[Any, ...], dtype[int32]], ndarray[tuple[Any, ...], dtype[int64]]]#: Finalized pattern as a (column indices, row offsets) pair.

Note

The returned arrays are read-only views into the pattern.

index_map(dim: int) → IndexMap[source]#

Index map for the rows (dim=0) or columns (dim=1).

Parameters:: dim – 0 for the row map, 1 for the column map.

insert(rows: int | ndarray[tuple[Any, ...], dtype[int32]], cols: int | ndarray[tuple[Any, ...], dtype[int32]]) → None[source]#

Insert entries into the pattern.

Given arrays of rows and columns, an entry is inserted for every (row, column) pair. Given a single row and column, the one entry is inserted.

Parameters:

rows – Row index/indices.
cols – Column index/indices.

insert_diagonal(rows: ndarray[tuple[Any, ...], dtype[int32]]) → None[source]#

Insert the diagonal entry for each of rows.

Parameters:: rows – Rows to insert the diagonal entry for.

property num_nonzeros: int#: Number of nonzeros in the finalized pattern.

Bases: Generic[_T]

Distributed vector object.

Create a distributed vector.

Parameters:: x – C++ Vector object.

Note

This initialiser is intended for internal library use only. User code should call vector() to create a vector object.

property array: ndarray[tuple[Any, ...], dtype[_T]]#: Local representation of the vector.

property block_size: int#: Block size for the vector.

property index_map: IndexMap[source]#: Index map that describes size and parallel distribution.

Note

This is a cached property. The wrapper is built on first access and the same object is returned thereafter.

property petsc_vec: PETSc.Vec[source]#

PETSc vector holding the entries of the vector.

Upon first access, this creates a PETSc Vec object that wraps the degree-of-freedom data. The Vec object is cached and the cached Vec is returned on subsequent accesses.

Note

When the object is destroyed it will destroy the underlying petsc4py vector automatically.

scatter_forward() → None[source]#: Update ghost entries.

scatter_reverse(mode: InsertMode) → None[source]#

Scatter ghost entries to owner.

Parameters:: mode – Control how scattered values are set/accumulated by owner.

property scatterer: Scatterer[source]#: Scatterer used for ghost communication.

Note

This is a cached property. The wrapper is built on first access and the same object is returned thereafter.

dolfinx.la.is_orthonormal(basis: list[Vector[_T]], eps: float = 1e-12) → bool[source]#: Check that list of vectors are orthonormal.

dolfinx.la.matrix_csr(sp: SparsityPattern, block_mode: BlockMode = BlockMode.compact, dtype: type[~typing.Any] | ~numpy.dtype[~typing.Any] | ~numpy._typing._dtype_like._SupportsDType[~numpy.dtype[~typing.Any]] | tuple[~typing.Any, ~typing.Any] | list[~typing.Any] | ~numpy._typing._dtype_like._DTypeDict | str | None=<class 'numpy.float64'>) → MatrixCSR[source]#

Create a distributed sparse matrix.

The matrix uses compressed sparse row storage.

Parameters:

sp – The sparsity pattern that defines the nonzero structure of the matrix the parallel distribution of the matrix.
block_mode – Block mode to use.
dtype – Scalar type.

Returns:

A sparse matrix.

dolfinx.la.norm(x: Vector[_T], type: Norm = Norm.l2) → float[source]#

Compute a norm of the vector.

Parameters:

x – Vector to measure.
type – Norm type to compute.

Returns:

Computed norm.

dolfinx.la.orthonormalize(basis: list[Vector[_T]]) → None[source]#: Orthogonalise set of vectors in-place.

dolfinx.la.sparsity_pattern(comm: Comm, maps: Sequence[IndexMap], bs: Sequence[int]) → SparsityPattern[source]#

Create a sparsity pattern for a matrix.

Parameters:

comm – MPI communicator that the pattern is distributed over.
maps – Row and column index maps.
bs – Row and column block sizes.

Returns:

An empty sparsity pattern. Insert entries into it and call SparsityPattern.finalize() before creating a matrix.

dolfinx.la.sparsity_pattern_blocked(comm: Comm, patterns: Sequence[Sequence[SparsityPattern | None]], maps: Sequence[Sequence[tuple[IndexMap, int]]], bs: Sequence[Sequence[int]]) → SparsityPattern[source]#

Create a sparsity pattern from a rectangular array of patterns.

The blocks are concatenated into a single pattern, as required for a monolithic matrix assembled from a block form.

Parameters:

comm – MPI communicator that the pattern is distributed over.
patterns – Sparsity pattern of each block. None marks a structurally zero block.
maps – Index map and block size of each block row, and of each block column.
bs – Row and column block sizes of the assembled pattern.

Returns:

An unfinalized sparsity pattern spanning all blocks.

Create a distributed vector.

Parameters:

map – Index map the describes the size and distribution of the vector.
bs – Block size.
scatterer – Scatterer compatible with map. If None, a new scatterer is created.
dtype – The scalar type.

Returns:

A distributed vector.