Components and Interfaces

components

Building blocks for prior components.

Classes:

Name	Description
PETScComponent	ABC interface for PETSc-based components.
PETScComponentComposition	Composition of variable number of PETSc components.
InterfaceComponent	Wrapper for PETSc component for numpy-based interface.
Matrix	Simple PETSc matrix wrapper.
InverseMatrixSolverSettings	Settings for the inverse matrix representation via Krylov subspace solver.
InverseMatrixSolver	Inverse matrix representation via Krylov subspace solver.

ls_prior.components.PETScComponent

Bases: ABC

ABC Interface for PETSc components.

This class describes the common interface for all PETSc-based components in this package. The idea is that any such component mimics the interface of a PETSc Matrix (with a more pythonic interface). Under the hood, this could be the composition of several matrices, or the representation of a matrix inverse through a matrix solver. This allows to easily combine different components in a flexible manner. The main functionality of a PETSc component is its apply method, which resembles a matrix-vector product. Furthermore, the interface provides methods to create input and output PETSc vectors that match the dimensionality of the component (when thinking of it as a matrix).

Methods:

Name	Description
apply	Apply component to input vector, store result in output vector.
create_input_vector	Create PETSc vector that could be applied to component from the right.
create_output_vector	Create PETSc vector that could be applied to component from the left.

Attributes:

Name	Type	Description
shape	tuple[int, int]	Shape of the component (thought of as a matrix).

shape abstractmethod property

shape: tuple[int, int]

Return the shape of the component (as a matrix).

Returns:

Type	Description
tuple[int, int]	tuple[int, int]: Shape of the component, as a matrix this would be (num_rows, num_cols).

apply abstractmethod

apply(input_vector: PETSc.Vec, output_vector: PETSc.Vec) -> None

Apply component to input vector, store result in output vector.

Parameters:

Name	Type	Description	Default
input_vector	PETSc.Vec	Vector to apply to component from the right.	required
output_vector	PETSc.Vec	Vector to store result of component application in.	required

create_input_vector abstractmethod

create_input_vector() -> PETSc.Vec

Create PETSc vector that could be applied to component from the right.

Returns:

Type	Description
PETSc.Vec	PETSc.Vec: PETSc vector of correct size.

create_output_vector abstractmethod

create_output_vector() -> PETSc.Vec

Create PETSc vector that could be applied to component from the left.

Returns:

Type	Description
PETSc.Vec	PETSc.Vec: PETSc vector of correct size.

_check_dimensions

_check_dimensions(input_vector: PETSc.Vec, output_vector: PETSc.Vec) -> None

Checks correct dimensionalities in apply method, should be utilized in subclasses.

ls_prior.components.PETScComponentComposition

Bases: PETScComponent

Composition of variable number of PETSc components.

The operators we require for the prior, namely covariance, precision and sampling factor, are compositions of several simpler, matrix-like components. This class provides the functionality to combine an arbitrary number of PETSc components into a new, composite component. The idea is very simple: Given a list of components \([M_1, M_2, ..., M_n]\), which can be applied to a PETSc vector, the composition will apply them in the given sequence.

Methods:

Name	Description
apply	Apply composition of components to input, store result in output vector.
create_input_vector	Create PETSc vector that could be multiplied with composition from the right.
create_output_vector	Create PETSc vector that could be multiplied with composition from the left.

Attributes:

Name	Type	Description
shape	tuple[int, int]	Shape of the component (thought of as a matrix).

shape property

shape: tuple[int, int]

Get the shape of the component, i.e. number of rows and columns of the composition.

Returns:

Type	Description
tuple[int, int]	tuple[int, int]: (num_rows, num_cols)

__init__

__init__(*components: PETScComponent) -> None

Initialize component as the composition of several PETSc components.

Parameters:

Name	Type	Description	Default
*components	PETScComponent	Components to compose, applied in the given order.	()

Raises:

Type	Description
ValueError	If less than two components are given, or if the dimensions of the components do not match for composition.

apply

apply(input_vector: PETSc.Vec, output_vector: PETSc.Vec) -> None

Apply the composition of components to input, store result in output vector.

Parameters:

Name	Type	Description	Default
input_vector	PETSc.Vec	Vector to apply composition to.	required
output_vector	PETSc.Vec	Vector to store result in.	required

create_input_vector

create_input_vector() -> PETSc.Vec

Create PETSc vector that could be multiplied with composition from the right.

Returns:

Type	Description
PETSc.Vec	PETSc.Vec: PETSc vector of correct size.

create_output_vector

create_output_vector() -> PETSc.Vec

Create PETSc vector that could be multiplied with composition from the left.

Returns:

Type	Description
PETSc.Vec	PETSc.Vec: PETSc vector of correct size.

ls_prior.components.InterfaceComponent

Wrapper for PETSc component for numpy-based interface.

The prior PETScComponents handle matrix representations and vectors in standard PETSc format. To allow for a more Pythonic interface, this class wraps a given PETSc component and provides methods to apply numpy arrays to the component, returning numpy arrays. These arrays are also copied to avoid modification of the original underlying data structures, which are handled as references only.

Methods:

Name	Description
apply	Apply input array to component, return result as numpy array.

Attributes:

Name	Type	Description
shape	tuple[int, int]	Shape of the component (thought of as a matrix).

shape property

shape: tuple[int, int]

Get the shape of the component.

Returns:

Type	Description
tuple[int, int]	tuple[int, int]: Input and output dimension, as a matrix this would be (num_rows, num_cols).

__init__

__init__(component: PETScComponent) -> None

Initialize interface component.

Parameters:

Name	Type	Description	Default
component	PETScComponent	PETSc component to wrap.	required

apply

apply(
    input_vector: np.ndarray[tuple[int], np.dtype[np.float64]],
) -> np.ndarray[tuple[int], np.dtype[np.float64]]

Apply input array to component, also return result as numpy array.

Parameters:

Name	Type	Description	Default
input_vector	np.ndarray[tuple[int], np.dtype[np.float64]]	Input vector to apply to component.	required

Raises:

Type	Description
ValueError	If input vector does not have correct shape.

Returns:

Type	Description
np.ndarray[tuple[int], np.dtype[np.float64]]	np.ndarray[tuple[int], np.dtype[np.float64]]: Result of the application to the underlying component. Will be copied from internal buffer to avoid modification of internal state.

ls_prior.components.Matrix

Bases: PETScComponent

Simple PETSc matrix wrapper.

This class does nothing more than wrapping a PETSc matrix, to match the more Pythonic interface defined in the PETScComponent ABC. It is purely for convenience.

Methods:

Name	Description
apply	Perform matrix-vector multiplication with input, store result in output vector.
create_input_vector	Create PETSc vector that could be multiplied with matrix from the right.
create_output_vector	Create PETSc vector that could be multiplied with matrix from the left.

Attributes:

Name	Type	Description
shape	tuple[int, int]	Shape of the PETSc matrix (n_rows, n_cols).

shape property

shape: tuple[int, int]

Get the shape of the component, i.e. number of rows and columns of the matrix.

Returns:

Type	Description
tuple[int, int]	tuple[int, int]: (num_rows, num_cols)

__init__

__init__(petsc_matrix: PETSc.Mat) -> None

Initialize component, simply store PETSc matrix internally.

Parameters:

Name	Type	Description	Default
petsc_matrix	PETSc.Mat	PETSc matrix to wrap, should be sparse.	required

apply

apply(input_vector: PETSc.Vec, output_vector: PETSc.Vec) -> None

Perform matrix-vector multiplication with input, store result in output vector.

Parameters:

Name	Type	Description	Default
input_vector	PETSc.Vec	Vector to perform Matrix-vector multiplication with.	required
output_vector	PETSc.Vec	Vector to store the result of the multiplication.	required

create_input_vector

create_input_vector() -> PETSc.Vec

Create PETSc vector that could be multiplied with matrix from the right.

Returns:

Type	Description
PETSc.Vec	PETSc.Vec: PETSc vector of correct size.

create_output_vector

create_output_vector() -> PETSc.Vec

Create PETSc vector that could be multiplied with matrix from the left.

Returns:

Type	Description
PETSc.Vec	PETSc.Vec: PETSc vector of correct size.

ls_prior.components.InverseMatrixSolverSettings dataclass

Settings for the inverse matrix representation via Krylov subspace solver.

All combinations of solvers and preconditioners provided in PETSc are supported. It is the user's responsibility to choose a suitable combination.

Attributes:

Name	Type	Description
solver_type	str	Type of the PETSc KSP solver.
preconditioner_type	str	Type of the PETSc preconditioner.
relative_tolerance	Annotated[Real, Is[lambda x: x > 0]] | None	Relative tolerance for the solver.
absolute_tolerance	Annotated[Real, Is[lambda x: x > 0]] | None	Absolute tolerance for the solver.
max_num_iterations	Annotated[int, Is[lambda x: x > 0]] | None	Maximum number of iterations to perform.

ls_prior.components.InverseMatrixSolver

Bases: PETScComponent

Inverse matrix representation via Krylov subspace solver.

This class resembles the inverse of a given PETSc matrix, through an iterative solver. This allows for matrix-free representation and efficient application of the inverse to PETSc vectors.

Methods:

Name	Description
apply	Apply inverse matrix to input, store result in output vector.
create_input_vector	Create PETSc vector that could be multiplied with inverse matrix from the right.
create_output_vector	Create PETSc vector that could be multiplied with inverse matrix from the left.

Attributes:

Name	Type	Description
shape	tuple[int, int]	Shape of the inverse matrix (n_rows, n_cols).

shape property

shape: tuple[int, int]

Get the shape of the component, i.e. number of rows and columns of the inverse matrix.

Returns:

Type	Description
tuple[int, int]	tuple[int, int]: (num_rows, num_cols)

__init__

__init__(solver_settings: InverseMatrixSolverSettings, petsc_matrix: PETSc.Mat) -> None

Initialize solver with given system matrix and solver config.

Parameters:

Name	Type	Description	Default
solver_settings	InverseMatrixSolverSettings	Settings for the solver.	required
petsc_matrix	PETSc.Mat	System matrix to solve with, should be sparse.	required

apply

apply(input_vector: PETSc.Vec, output_vector: PETSc.Vec) -> None

Apply inverse matrix to input, store result in output vector.

Parameters:

Name	Type	Description	Default
input_vector	PETSc.Vec	Vector to apply inverse to.	required
output_vector	PETSc.Vec	Vector to store result in.	required

create_input_vector

create_input_vector() -> PETSc.Vec

Create PETSc vector that could be multiplied with inverse matrix from the right.

Returns:

Type	Description
PETSc.Vec	PETSc.Vec: PETSc vector of correct size.

create_output_vector

create_output_vector() -> PETSc.Vec

Create PETSc vector that could be multiplied with matrix from the left.

Returns:

Type	Description
PETSc.Vec	PETSc.Vec: PETSc vector of correct size.