# 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) | A distributed sparse matrix that uses compressed sparse row storage.
`Norm`(*values) |
`Vector`(x) | A 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)

  Bases: `object`

  A distributed sparse matrix that uses compressed sparse row storage.

  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[floating]], rows: ndarray[tuple[Any, ...], dtype[int32]], cols: ndarray[tuple[Any, ...], dtype[int32]], bs: int = 1) → None

    Add a block of values in the matrix.

  property block_size: list

    Block sizes for the matrix.

  property data: ndarray[tuple[Any, ...], dtype[floating]]

    Underlying matrix entry data.

  index_map(i: int) → IndexMap

    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.

  mult(x: Vector, y: Vector) → None

    Compute `y += Ax`.

    Parameters:

      - x – Input Vector

      - y – Output Vector

  scatter_reverse() → None

    Scatter and accumulate ghost values.

  set(x: ndarray[tuple[Any, ...], dtype[floating]], rows: ndarray[tuple[Any, ...], dtype[int32]], cols: ndarray[tuple[Any, ...], dtype[int32]], bs: int = 1) → None

    Set a block of values in the matrix.

  set_value(x: floating) → None

    Set all non-zero entries to a value.

    Parameters:

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

  squared_norm() → floating

    Compute the squared Frobenius norm.

    Note

    This operation is collective and requires communication.

  to_dense() → ndarray[tuple[Any, ...], dtype[floating]]

    Copy to a dense 2D array.

    Note

    Typically used for debugging.

  to_scipy(ghosted: bool = False)

    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.

class dolfinx.la.Norm(*values)

  Bases: `Enum`

  frobenius = 3
  l1 = 0
  l2 = 1
  linf = 2

class dolfinx.la.Vector(x: Vector_float32 | Vector_float64 | Vector_complex64 | Vector_complex128 | Vector_int8 | Vector_int32 | Vector_int64)

  Bases: `object`

  A distributed vector object.

  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

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

    Update ghost entries.

  scatter_reverse(mode: InsertMode) → None

    Scatter ghost entries to owner.

    Parameters:

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

dolfinx.la.is_orthonormal(basis: list[Vector], eps: float = 1e-12) → bool

  Check that list of vectors are orthonormal.

dolfinx.la.matrix_csr(sp: ~dolfinx.cpp.la.SparsityPattern, block_mode=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

  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.

    - dtype – The scalar type.

  Returns:

    A sparse matrix.

dolfinx.la.norm(x: Vector, type: Norm = Norm.l2) → floating

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

  Orthogonalise set of vectors in-place.

dolfinx.la.vector(map, bs=1, 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'>) → Vector

  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.