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.
`vector`(map, bs, dtype, ...)	Create a distributed vector.

Classes

`InsertMode`(*values)
`MatrixCSR`(A)	Distributed compressed sparse row matrix.
`Norm`(*values)
`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#

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#: Index map that describes size and parallel distribution.

property petsc_vec: PETSc.Vec#

PETSc vector holding the entries of the vector.

Upon first call, this function creates a PETSc Vec object that wraps the degree-of-freedom data. The Vec object is cached and the cached Vec is returned upon subsequent calls.

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.

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.

Create a distributed vector.

Parameters:

map – Index map the describes the size and distribution of the vector.
bs – Block size.
dtype – The scalar type.

Returns:

A distributed vector.