pygeoinf 1.0.9__py3-none-any.whl → 1.1.1__py3-none-any.whl

pygeoinf/__init__.py

@@ -8,7 +8,11 @@ from .random_matrix import (
 
 from .hilbert_space import (
     HilbertSpace,
+    DualHilbertSpace,
     EuclideanSpace,
+    HilbertModule,
+    MassWeightedHilbertSpace,
+    MassWeightedHilbertModule,
 )
 
 
@@ -18,7 +22,7 @@ from .operators import (
     DiagonalLinearOperator,
 )
 
-from .forms import (
+from .linear_forms import (
     LinearForm,
 )
 

pygeoinf/direct_sum.py

@@ -1,5 +1,24 @@
 """
-Module for direct sums of Hilbert spaces and related block operators.
+Implements direct sums of Hilbert spaces and corresponding block operators.
+
+This module provides tools for constructing larger, composite Hilbert spaces and
+operators from smaller ones. This is essential for problems involving multiple
+coupled fields or joint inversions where a single model is constrained by
+data from different experiments.
+
+Key Classes
+-----------
+- `HilbertSpaceDirectSum`: A `HilbertSpace` formed by the direct sum of a
+  list of other spaces. Vectors in this space are lists of vectors from the
+  component subspaces.
+- `BlockLinearOperator`: A `LinearOperator` acting between direct sum spaces,
+  represented as a 2D grid (matrix) of sub-operators.
+- `ColumnLinearOperator`: A specialized block operator mapping from a single
+  space to a direct sum space.
+- `RowLinearOperator`: A specialized block operator mapping from a direct sum
+  space to a single space.
+- `BlockDiagonalLinearOperator`: An efficient representation for block
+  operators with zero off-diagonal blocks.
 """
 
 from __future__ import annotations
@@ -9,15 +28,16 @@ import numpy as np
 
 from .hilbert_space import HilbertSpace
 from .operators import LinearOperator
-from .forms import LinearForm
+from .linear_forms import LinearForm
 
 
 class HilbertSpaceDirectSum(HilbertSpace):
     """
     A Hilbert space formed from the direct sum of a list of other spaces.
 
-    Vectors in this space are represented as lists of vectors, where each
-    element of the list is a vector from the corresponding subspace.
+    A vector in this space is represented as a list of vectors, where the i-th
+    element of the list is a vector from the i-th component subspace. The
+    inner product is the sum of the inner products of the components.
     """
 
     def __init__(self, spaces: List[HilbertSpace]) -> None:
@@ -29,22 +49,58 @@ class HilbertSpaceDirectSum(HilbertSpace):
                 in the direct sum.
         """
         self._spaces: List[HilbertSpace] = spaces
-        dim = sum([space.dim for space in spaces])
-        super().__init__(
-            dim,
-            self.__to_components,
-            self.__from_components,
-            self.__inner_product,
-            self.__to_dual,
-            self.__from_dual,
-            add=self.__add,
-            subtract=self.__subtract,
-            multiply=self.__multiply,
-            ax=self.__ax,
-            axpy=self.__axpy,
-            copy=self.__copy,
+        self._dim = sum([space.dim for space in spaces])
+
+    @property
+    def dim(self) -> int:
+        """Returns the dimension of the direct sum space."""
+        return self._dim
+
+    def to_components(self, xs: List[Any]) -> np.ndarray:
+        cs = [space.to_components(x) for space, x in zip(self._spaces, xs)]
+        return np.concatenate(cs, 0)
+
+    def from_components(self, c: np.ndarray) -> List[Any]:
+        xs = []
+        i = 0
+        for space in self._spaces:
+            j = i + space.dim
+            x = space.from_components(c[i:j])
+            xs.append(x)
+            i = j
+        return xs
+
+    def to_dual(self, xs: List[Any]) -> LinearForm:
+        if len(xs) != self.number_of_subspaces:
+            raise ValueError("Input list has incorrect number of vectors.")
+        return self.canonical_dual_isomorphism(
+            [space.to_dual(x) for space, x in zip(self._spaces, xs)]
         )
 
+    def from_dual(self, xp: LinearForm) -> List[Any]:
+        xps = self.canonical_dual_inverse_isomorphism(xp)
+        return [space.from_dual(xip) for space, xip in zip(self._spaces, xps)]
+
+    def add(self, xs: List[Any], ys: List[Any]) -> List[Any]:
+        return [space.add(x, y) for space, x, y in zip(self._spaces, xs, ys)]
+
+    def subtract(self, xs: List[Any], ys: List[Any]) -> List[Any]:
+        return [space.subtract(x, y) for space, x, y in zip(self._spaces, xs, ys)]
+
+    def multiply(self, a: float, xs: List[Any]) -> List[Any]:
+        return [space.multiply(a, x) for space, x in zip(self._spaces, xs)]
+
+    def ax(self, a: float, xs: List[Any]) -> None:
+        for space, x in zip(self._spaces, xs):
+            space.ax(a, x)
+
+    def axpy(self, a: float, xs: List[Any], ys: List[Any]) -> None:
+        for space, x, y in zip(self._spaces, xs, ys):
+            space.axpy(a, x, y)
+
+    def copy(self, xs: List[Any]) -> List[Any]:
+        return [space.copy(x) for space, x in zip(self._spaces, xs)]
+
     def __eq__(self, other: object) -> bool:
         """
         Checks for mathematical equality with another direct sum space.
@@ -55,7 +111,6 @@ class HilbertSpaceDirectSum(HilbertSpace):
         if not isinstance(other, HilbertSpaceDirectSum):
             return NotImplemented
 
-        # This relies on the subspaces having their own __eq__ methods.
         return self.subspaces == other.subspaces
 
     @property
@@ -145,56 +200,6 @@ class HilbertSpaceDirectSum(HilbertSpace):
             i = j
         return xps
 
-    def __to_components(self, xs: List[Any]) -> np.ndarray:
-        cs = [space.to_components(x) for space, x in zip(self._spaces, xs)]
-        return np.concatenate(cs, 0)
-
-    def __from_components(self, c: np.ndarray) -> List[Any]:
-        xs = []
-        i = 0
-        for space in self._spaces:
-            j = i + space.dim
-            x = space.from_components(c[i:j])
-            xs.append(x)
-            i = j
-        return xs
-
-    def __inner_product(self, x1s: List[Any], x2s: List[Any]) -> float:
-        return sum(
-            space.inner_product(x1, x2) for space, x1, x2 in zip(self._spaces, x1s, x2s)
-        )
-
-    def __to_dual(self, xs: List[Any]) -> LinearForm:
-        if len(xs) != self.number_of_subspaces:
-            raise ValueError("Input list has incorrect number of vectors.")
-        return self.canonical_dual_isomorphism(
-            [space.to_dual(x) for space, x in zip(self._spaces, xs)]
-        )
-
-    def __from_dual(self, xp: LinearForm) -> List[Any]:
-        xps = self.canonical_dual_inverse_isomorphism(xp)
-        return [space.from_dual(xip) for space, xip in zip(self._spaces, xps)]
-
-    def __add(self, xs: List[Any], ys: List[Any]) -> List[Any]:
-        return [space.add(x, y) for space, x, y in zip(self._spaces, xs, ys)]
-
-    def __subtract(self, xs: List[Any], ys: List[Any]) -> List[Any]:
-        return [space.subtract(x, y) for space, x, y in zip(self._spaces, xs, ys)]
-
-    def __multiply(self, a: float, xs: List[Any]) -> List[Any]:
-        return [space.multiply(a, x) for space, x in zip(self._spaces, xs)]
-
-    def __ax(self, a: float, xs: List[Any]) -> None:
-        for space, x in zip(self._spaces, xs):
-            space.ax(a, x)
-
-    def __axpy(self, a: float, xs: List[Any], ys: List[Any]) -> None:
-        for space, x, y in zip(self._spaces, xs, ys):
-            space.axpy(a, x, y)
-
-    def __copy(self, xs: List[Any]) -> List[Any]:
-        return [space.copy(x) for space, x in zip(self._spaces, xs)]
-
     def _subspace_projection_mapping(self, i: int, xs: List[Any]) -> Any:
         return xs[i]
 
@@ -213,14 +218,23 @@ class BlockStructure(ABC):
 
     @property
     def row_dim(self) -> int:
+        """
+        Returns the number of rows in the block structure.
+        """
         return self._row_dim
 
     @property
     def col_dim(self) -> int:
+        """
+        Returns the number of columns in the block structure.
+        """
         return self._col_dim
 
     @abstractmethod
     def block(self, i: int, j: int) -> "LinearOperator":
+        """
+        Returns the operator in the (i, j)-th sub-block.
+        """
         pass
 
     def _check_block_indices(self, i: int, j: int) -> None:
@@ -232,8 +246,12 @@ class BlockStructure(ABC):
 
 class BlockLinearOperator(LinearOperator, BlockStructure):
     """
-    A linear operator between direct sums of Hilbert spaces, defined by a
-    matrix of sub-operators (blocks).
+    A linear operator between direct sum spaces, defined by a matrix of sub-operators.
+
+    This operator acts like a matrix where each entry is itself a `LinearOperator`.
+    It maps a list of input vectors `[x_1, x_2, ...]` to a list of output
+    vectors `[y_1, y_2, ...]`. The constructor checks for dimensional
+    consistency between the blocks.
     """
 
     def __init__(self, blocks: List[List[LinearOperator]]) -> None:
@@ -309,8 +327,12 @@ class BlockLinearOperator(LinearOperator, BlockStructure):
 
 class ColumnLinearOperator(LinearOperator, BlockStructure):
     """
-    An operator that maps a single Hilbert space to a direct sum of spaces.
-    It is represented as a column of operators.
+    An operator that maps from a single space to a direct sum space.
+
+    It can be visualized as a column vector of operators, `[A_1, A_2, ...]^T`.
+    It takes a single input vector `x` and produces a list of output vectors
+    `[A_1(x), A_2(x), ...]`. This is often used to represent a joint forward
+    operator in an inverse problem.
     """
 
     def __init__(self, operators: List[LinearOperator]) -> None:
@@ -360,8 +382,12 @@ class ColumnLinearOperator(LinearOperator, BlockStructure):
 
 class RowLinearOperator(LinearOperator, BlockStructure):
     """
-    An operator that maps a direct sum of spaces to a single Hilbert space,
-    structured as a row of operator blocks.
+    An operator that maps from a direct sum space to a single space.
+
+    It can be visualized as a row vector of operators, `[A_1, A_2, ...]`.
+    It takes a list of input vectors `[x_1, x_2, ...]` and produces a single
+    output vector `y = A_1(x_1) + A_2(x_2) + ...`. The adjoint of a
+    `ColumnLinearOperator` is a `RowLinearOperator`.
     """
 
     def __init__(self, operators: List[LinearOperator]) -> None:

pygeoinf/forward_problem.py

@@ -1,10 +1,20 @@
 """
-Module for defining forward problem classes.
-
-This module provides classes to represent inverse problem formulations, which
-relate unknown model parameters to observed data through a forward operator.
-It handles both deterministic (error-free) and statistical (with data errors)
-scenarios.
+Defines the mathematical structure of a forward problem.
+
+This module provides classes that encapsulate the core components of an
+inverse problem. A forward problem describes the physical or mathematical
+process that maps a set of unknown model parameters `u` to a set of observable
+data `d`.
+
+The module handles both the deterministic relationship `d = A(u)` and the more
+realistic statistical model `d = A(u) + e`, where `e` represents random noise.
+
+Key Classes
+-----------
+- `ForwardProblem`: A general class representing the link between a model
+  space and a data space via a forward operator, with an optional data error.
+- `LinearForwardProblem`: A specialization for linear problems where the
+  forward operator is a `LinearOperator`.
 """
 
 from __future__ import annotations
@@ -18,7 +28,7 @@ from .direct_sum import ColumnLinearOperator
 # This block only runs for type checkers, not at runtime, to prevent
 # circular import errors while still allowing type hints.
 if TYPE_CHECKING:
-    from .hilbert_space import HilbertSpace, T_vec
+    from .hilbert_space import HilbertSpace, Vector
     from .operators import LinearOperator
 
 
@@ -33,7 +43,7 @@ class ForwardProblem:
 
     def __init__(
         self,
-        forward_operator: "LinearOperator",
+        forward_operator: LinearOperator,
         /,
         *,
         data_error_measure: Optional["GaussianMeasure"] = None,
@@ -47,7 +57,7 @@ class ForwardProblem:
                 from which data errors are assumed to be drawn. If None, the
                 data is considered to be error-free.
         """
-        self._forward_operator: "LinearOperator" = forward_operator
+        self._forward_operator: LinearOperator = forward_operator
         self._data_error_measure: Optional["GaussianMeasure"] = data_error_measure
         if self.data_error_measure_set:
             if self.data_space != data_error_measure.domain:
@@ -56,7 +66,7 @@ class ForwardProblem:
                 )
 
     @property
-    def forward_operator(self) -> "LinearOperator":
+    def forward_operator(self) -> LinearOperator:
         """The forward operator, mapping from model to data space."""
         return self._forward_operator
 
@@ -88,9 +98,7 @@ class LinearForwardProblem(ForwardProblem):
     Represents a linear forward problem of the form `d = A(u) + e`.
 
     Here, `d` is the data, `A` is the linear forward operator, `u` is the model,
-    and `e` is a random error drawn from a Gaussian distribution. This class
-    provides methods for statistical analysis, such as generating synthetic data
-    and performing chi-squared tests.
+    and `e` is a random error drawn from a Gaussian distribution.
     """
 
     @staticmethod
@@ -100,8 +108,9 @@ class LinearForwardProblem(ForwardProblem):
         """
         Forms a joint forward problem from a list of separate problems.
 
-        This is useful when a single underlying model is observed through
-        multiple, independent measurement systems.
+        This is a powerful tool for joint inversions, where a single underlying
+        model is observed through multiple, independent measurement systems
+        (e.g., different types of geophysical surveys).
 
         Args:
             forward_problems: A list of `LinearForwardProblem` instances that
@@ -110,10 +119,6 @@ class LinearForwardProblem(ForwardProblem):
         Returns:
             A single `LinearForwardProblem` where the data space is the direct
             sum of the individual data spaces.
-
-        Raises:
-            ValueError: If the list of problems is empty or if they do not all
-                share the same model space.
         """
         if not forward_problems:
             raise ValueError("Cannot form a direct sum from an empty list.")
@@ -139,7 +144,7 @@ class LinearForwardProblem(ForwardProblem):
             joint_forward_operator, data_error_measure=data_error_measure
         )
 
-    def data_measure(self, model: "T_vec") -> "GaussianMeasure":
+    def data_measure(self, model: "Vector") -> "GaussianMeasure":
         """
         Returns the Gaussian measure for the data, given a specific model.
 
@@ -160,7 +165,7 @@ class LinearForwardProblem(ForwardProblem):
             translation=self.forward_operator(model)
         )
 
-    def synthetic_data(self, model: "T_vec") -> "T_vec":
+    def synthetic_data(self, model: "Vector") -> "Vector":
         """
         Generates a synthetic data vector for a given model.
 
@@ -177,7 +182,7 @@ class LinearForwardProblem(ForwardProblem):
 
     def synthetic_model_and_data(
         self, prior: "GaussianMeasure"
-    ) -> Tuple["T_vec", "T_vec"]:
+    ) -> Tuple["Vector", "Vector"]:
         """
         Generates a random model and corresponding synthetic data.
 
@@ -211,24 +216,20 @@ class LinearForwardProblem(ForwardProblem):
         """
         return chi2.ppf(significance_level, self.data_space.dim)
 
-    def chi_squared(self, model: "T_vec", data: "T_vec") -> float:
+    def chi_squared(self, model: "Vector", data: "Vector") -> float:
         """
         Calculates the chi-squared statistic for a given model and data.
 
-        If a data error measure with an inverse covariance is defined, this is
-        the weighted misfit: `(d - A(u))^T * C_e^-1 * (d - A(u))`. Otherwise,
-        it is the squared norm of the data residual: `||d - A(u)||^2`.
-
+        This measures the misfit between the predicted and observed data.
+        - If a data error measure with an inverse covariance `C_e^-1` is defined,
+          this is the weighted misfit: `(d - A(u))^T * C_e^-1 * (d - A(u))`.
+        - Otherwise, it is the squared L2 norm of the data residual: `||d - A(u)||^2`.
         Args:
             model: A vector from the model space.
             data: An observed data vector from the data space.
 
         Returns:
             The chi-squared statistic.
-
-        Raises:
-            AttributeError: If a data error measure is set but its inverse
-                covariance (precision operator) is not available.
         """
         residual = self.data_space.subtract(data, self.forward_operator(model))
 
@@ -246,7 +247,7 @@ class LinearForwardProblem(ForwardProblem):
             return self.data_space.squared_norm(residual)
 
     def chi_squared_test(
-        self, significance_level: float, model: "T_vec", data: "T_vec"
+        self, significance_level: float, model: "Vector", data: "Vector"
     ) -> bool:
         """
         Performs a chi-squared test for goodness of fit.