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

pygeoinf/operators.py

@@ -1,5 +1,22 @@
 """
-Module defining the Operator, LinearOperator, and DiagonalLinearOperator classes.
+Defines a class hierarchy for operators between Hilbert spaces.
+
+This module provides the tools for defining and manipulating mappings between
+`HilbertSpace` objects. It distinguishes between general non-linear operators
+and the more structured linear operators, which are the primary focus and
+support a rich algebra.
+
+Key Classes
+-----------
+- `Operator`: A general, potentially non-linear operator defined by a simple
+  mapping function.
+- `LinearOperator`: The main workhorse for linear algebra. It represents a
+  linear map and provides rich functionality, including composition (`@`),
+  adjoints (`.adjoint`), duals (`.dual`), and matrix representations (`.matrix`).
+  It includes numerous factory methods for convenient construction.
+- `DiagonalLinearOperator`: A specialized, efficient implementation for linear
+  operators that are diagonal in their component representation, which supports
+  functional calculus.
 """
 
 from __future__ import annotations
@@ -9,8 +26,7 @@ import numpy as np
 from scipy.sparse.linalg import LinearOperator as ScipyLinOp
 from scipy.sparse import diags
 
-# This import path assumes `pygeoinf` is on the python path.
-# For a local package structure, you might use from ..random_matrix import ...
+
 from .random_matrix import (
     fixed_rank_random_range,
     variable_rank_random_range,
@@ -22,7 +38,7 @@ from .random_matrix import (
 # This block only runs for type checkers, not at runtime
 if TYPE_CHECKING:
     from .hilbert_space import HilbertSpace, EuclideanSpace
-    from .forms import LinearForm
+    from .linear_forms import LinearForm
 
 
 class Operator:
@@ -83,8 +99,14 @@ class LinearOperator(Operator):
     """
     A linear operator between two Hilbert spaces.
 
-    This class is the primary workhorse for linear algebraic operations,
-    supporting composition, adjoints, duals, and matrix representations.
+    This class is the primary workhorse for linear algebraic operations. An
+    operator can be defined "on the fly" from a callable mapping. The class
+    automatically derives the associated `adjoint` and `dual` operators,
+    which are fundamental for solving linear systems and for optimization.
+
+    It supports a rich algebra, including composition (`@`), addition (`+`),
+    and scalar multiplication (`*`). Operators can also be represented as
+    dense or matrix-free (`scipy`) matrices for use with numerical solvers.
     """
 
     def __init__(
@@ -96,7 +118,6 @@ class LinearOperator(Operator):
         *,
         dual_mapping: Optional[Callable[[Any], Any]] = None,
         adjoint_mapping: Optional[Callable[[Any], Any]] = None,
-        formal_adjoint_mapping: Optional[Callable[[Any], Any]] = None,
         thread_safe: bool = False,
         dual_base: Optional[LinearOperator] = None,
         adjoint_base: Optional[LinearOperator] = None,
@@ -110,7 +131,6 @@ class LinearOperator(Operator):
             mapping (callable): The function defining the linear mapping.
             dual_mapping (callable, optional): The action of the dual operator.
             adjoint_mapping (callable, optional): The action of the adjoint.
-            formal_adjoint_mapping (callable, optional): The formal adjoint.
             thread_safe (bool, optional): True if the mapping is thread-safe.
             dual_base (LinearOperator, optional): Internal use for duals.
             adjoint_base (LinearOperator, optional): Internal use for adjoints.
@@ -119,17 +139,12 @@ class LinearOperator(Operator):
         self._dual_base: Optional[LinearOperator] = dual_base
         self._adjoint_base: Optional[LinearOperator] = adjoint_base
         self._thread_safe: bool = thread_safe
-        self.__formal_adjoint_mapping: Optional[Callable[[Any], Any]]
         self.__adjoint_mapping: Callable[[Any], Any]
         self.__dual_mapping: Callable[[Any], Any]
 
         if dual_mapping is None:
             if adjoint_mapping is None:
-                if formal_adjoint_mapping is None:
-                    self.__dual_mapping = self._dual_mapping_default
-                else:
-                    self.__formal_adjoint_mapping = formal_adjoint_mapping
-                    self.__dual_mapping = self._dual_mapping_from_formal_adjoint
+                self.__dual_mapping = self._dual_mapping_default
                 self.__adjoint_mapping = self._adjoint_mapping_from_dual
             else:
                 self.__adjoint_mapping = adjoint_mapping
@@ -156,11 +171,76 @@ class LinearOperator(Operator):
         return LinearOperator(domain, domain, mapping, adjoint_mapping=mapping)
 
     @staticmethod
-    def formally_self_adjoint(
-        domain: "HilbertSpace", mapping: Callable[[Any], Any]
+    def from_formal_adjoint(
+        domain: "HilbertSpace", codomain: "HilbertSpace", operator: LinearOperator
     ) -> LinearOperator:
-        """Creates a formally self-adjoint operator."""
-        return LinearOperator(domain, domain, mapping, formal_adjoint_mapping=mapping)
+        """
+        Constructs an operator on weighted spaces from one on the underlying spaces.
+
+        This is a key method for working with `MassWeightedHilbertSpace`. It takes
+        an operator `A` that is defined on the simple, unweighted underlying spaces
+        and "lifts" it to be a proper operator on the mass-weighted spaces. It
+        correctly defines the new operator's adjoint with respect to the
+        weighted inner products.
+
+        Args:
+            domain: The (potentially) mass-weighted domain of the new operator.
+            codomain: The (potentially) mass-weighted codomain of the new operator.
+            operator: The original operator defined on the underlying,
+                unweighted spaces.
+
+        Returns:
+            A new `LinearOperator` that acts between the mass-weighted spaces.
+        """
+        from .hilbert_space import MassWeightedHilbertSpace
+
+        if isinstance(domain, MassWeightedHilbertSpace):
+            domain_base = domain.underlying_space
+            domain_inverse_mass_operator = domain.inverse_mass_operator
+        else:
+            domain_base = domain
+            domain_inverse_mass_operator = domain.identity_operator()
+
+        if isinstance(codomain, MassWeightedHilbertSpace):
+            codomain_base = codomain.underlying_space
+            codomain_mass_operator = codomain.mass_operator
+        else:
+            codomain_base = codomain
+            codomain_mass_operator = codomain.identity_operator()
+
+        if domain_base != operator.domain:
+            raise ValueError("Domain mismatch")
+        if codomain_base != operator.codomain:
+            raise ValueError("Codomain mismatch")
+
+        return LinearOperator(
+            domain,
+            codomain,
+            operator,
+            adjoint_mapping=domain_inverse_mass_operator
+            @ operator.adjoint
+            @ codomain_mass_operator,
+        )
+
+    @staticmethod
+    def from_formally_self_adjoint(
+        domain: "HilbertSpace", operator: LinearOperator
+    ) -> LinearOperator:
+        """
+        Method to construct LinearOperators on MassWeightedHilbertSpaces
+        that are self-adjoint on the underlying space.
+
+        Args:
+            domain (MassWeightedHilbertSpace): The domain of the operator.
+            operator (LinearOperator): The operator to be converted
+
+        Notes:
+            If the domain is not a MassWeightedHilbertSpace, the underlying
+            domain is taken to be the domain, and the mass operator the identity.
+            In such cases the method is well-defined but pointless as the output
+            operator is identical to the input operator.
+        """
+        return LinearOperator.from_formal_adjoint(domain, domain, operator)
 
     @staticmethod
     def from_linear_forms(forms: List["LinearForm"]) -> LinearOperator:
@@ -203,15 +283,48 @@ class LinearOperator(Operator):
         galerkin: bool = False,
     ) -> LinearOperator:
         """
-        Creates an operator from its matrix representation.
+        Creates a LinearOperator from its matrix representation.
+
+        This factory method allows you to define a `LinearOperator` using a
+        concrete matrix (like a `numpy.ndarray`) that acts on the component
+        vectors of the abstract Hilbert space vectors. The `galerkin` flag
+        determines how this matrix action is interpreted.
 
         Args:
-            domain: The operator's domain.
-            codomain: The operator's codomain.
-            matrix: The matrix representation.
-            galerkin: If False (default), matrix maps components to components.
-                If True, matrix maps components of the domain to dual
-                components of the codomain.
+            domain (HilbertSpace): The operator's domain.
+            codomain (HilbertSpace): The operator's codomain.
+            matrix (MatrixLike): The matrix representation, which can be a dense
+                NumPy array or a SciPy LinearOperator. Its shape must be
+                (codomain.dim, domain.dim).
+            galerkin (bool): Specifies the interpretation of the matrix.
+
+                - **`galerkin=False` (Default): Standard Component Mapping**
+                  This is the most direct interpretation. The matrix `M` maps the
+                  component vector `c_x` of an input vector `x` directly to the
+                  component vector `c_y` of the output vector `y`.
+
+                - **`galerkin=True`: Galerkin (or "Weak Form") Representation**
+                  This interpretation is standard in the finite element method (FEM)
+                  and other variational techniques. The matrix `M` maps the component
+                  vector `c_x` of an input `x` to the component vector `c_yp` of the
+                  *dual* of the output vector `y`.
+
+                  - **Matrix Entries**: The matrix elements are defined by inner
+                    products with basis vectors: `M_ij = inner_product(A(b_j), b_i)`,
+                    where `b_j` are domain basis vectors and `b_i` are codomain
+                    basis vectors.
+                  - **Use Case**: This is critically important for preserving the
+                    mathematical properties of an operator. For example, if an operator
+                    `A` is self-adjoint, its Galerkin matrix `M` will be **symmetric**
+                    (`M.T == M`). This allows the use of highly efficient numerical
+                    methods like the Conjugate Gradient solver or Cholesky
+                    factorization, which rely on symmetry. The standard component
+                    matrix of a self-adjoint operator is generally not symmetric
+                    unless the basis is orthonormal.
+
+        Returns:
+            LinearOperator: A new `LinearOperator` instance whose action is
+                defined by the provided matrix and interpretation.
         """
         assert matrix.shape == (codomain.dim, domain.dim)
 
@@ -361,11 +474,44 @@ class LinearOperator(Operator):
         """
         Returns a matrix representation of the operator.
 
-        By default, returns a matrix-free `scipy.sparse.linalg.LinearOperator`.
+        This method provides a concrete matrix that represents the abstract
+        linear operator's action on the underlying component vectors.
 
         Args:
-            dense: If True, returns a dense `numpy.ndarray`.
-            galerkin: If True, returns the Galerkin representation.
+            dense (bool): Determines the format of the returned matrix.
+                - If `True`, this method computes and returns a dense `numpy.ndarray`.
+                  Be aware that this can be very memory-intensive for
+                  high-dimensional spaces.
+                - If `False` (default), it returns a matrix-free
+                  `scipy.sparse.linalg.LinearOperator`. This object encapsulates
+                  the operator's action (`matvec`) and its transpose action
+                  (`rmatvec`) without ever explicitly forming the full matrix in memory,
+                  making it ideal for large-scale problems.
+
+            galerkin (bool): Specifies the interpretation of the matrix representation. This
+                flag is crucial for correctly using the matrix with numerical solvers.
+
+                - **`galerkin=False` (Default): Standard Component Mapping**
+                  The returned matrix `M` performs a standard component-to-component
+                  mapping.
+                  - **`matvec` action**: Takes the component vector `c_x` of an input `x`
+                    and returns the component vector `c_y` of the output `y`.
+                  - **`rmatvec` action**: Corresponds to the matrix of the **dual operator**, `A'`.
+
+                - **`galerkin=True`: Galerkin (or "Weak Form") Representation**
+                  The returned matrix `M` represents the operator in a weak form, mapping
+                  components of a vector to components of a dual vector.
+                  - **`matvec` action**: Takes the component vector `c_x` of an input `x`
+                    and returns the component vector `c_yp` of the *dual* of the output `y`.
+                  - **`rmatvec` action**: Corresponds to the matrix of the **adjoint operator**, `A*`.
+                  - **Key Property**: This representation is designed to preserve fundamental
+                    mathematical properties. For instance, if the `LinearOperator` is
+                    self-adjoint, its Galerkin matrix will be **symmetric**, which is a
+                    prerequisite for algorithms like the Conjugate Gradient method.
+
+        Returns:
+            Union[ScipyLinOp, np.ndarray]: The matrix representation of the
+                operator, either as a dense array or a matrix-free object.
         """
         if dense:
             return self._compute_dense_matrix(galerkin)
@@ -552,7 +698,7 @@ class LinearOperator(Operator):
         )
 
     def _dual_mapping_default(self, yp: Any) -> "LinearForm":
-        from .forms import LinearForm
+        from .linear_forms import LinearForm
 
         return LinearForm(self.domain, mapping=lambda x: yp(self(x)))
 
@@ -561,13 +707,6 @@ class LinearOperator(Operator):
         x = self.__adjoint_mapping(y)
         return self.domain.to_dual(x)
 
-    def _dual_mapping_from_formal_adjoint(self, yp: Any) -> Any:
-        cyp = self.codomain.dual.to_components(yp)
-        y = self.codomain.from_components(cyp)
-        x = self.__formal_adjoint_mapping(y)
-        cx = self.domain.to_components(x)
-        return self.domain.dual.from_components(cx)
-
     def _adjoint_mapping_from_dual(self, y: Any) -> Any:
         yp = self.codomain.to_dual(y)
         xp = self.__dual_mapping(yp)

pygeoinf/random_matrix.py

@@ -1,12 +1,20 @@
 """
-Module for random matrix factorisations.
-
-This module provides functions for computing low-rank matrix factorisations
-using randomized algorithms. These methods are particularly effective for large
-matrices where deterministic methods would be too slow. The implementations
-are based on the work of Halko, Martinsson, and Tropp (2011).
+Implements randomized algorithms for low-rank matrix factorizations.
+
+This module provides functions for computing approximate, low-rank matrix
+factorizations (SVD, Cholesky, Eigendecomposition) using randomized methods.
+These algorithms are particularly effective for large, high-dimensional matrices
+where deterministic methods would be computationally prohibitive. They work by
+finding a low-dimensional subspace that captures most of the "action" of the
+matrix.
+
+The implementations are based on the seminal work of Halko, Martinsson, and
+Tropp, "Finding structure with randomness: Probabilistic algorithms for
+constructing approximate matrix decompositions" (2011).
 """
 
+from typing import Tuple, Union
+
 import numpy as np
 from scipy.linalg import (
     cho_factor,
@@ -16,7 +24,7 @@ from scipy.linalg import (
     qr,
 )
 from scipy.sparse.linalg import LinearOperator as ScipyLinOp
-from typing import Tuple, Union
+
 
 # A type for objects that act like matrices (numpy arrays or SciPy LinearOperators)
 MatrixLike = Union[np.ndarray, ScipyLinOp]
@@ -26,29 +34,24 @@ def fixed_rank_random_range(
     matrix: MatrixLike, rank: int, power: int = 0
 ) -> np.ndarray:
     """
-    Computes an orthonormal basis for a fixed-rank approximation to the
-    range of a matrix using a randomized method.
+    Computes an orthonormal basis for a fixed-rank approximation of a matrix's range.
 
-    This is a two-stage algorithm that finds a low-dimensional subspace that
-    captures most of the action of the matrix.
+    This randomized algorithm finds a low-dimensional subspace that captures
+    most of the action of the matrix.
 
     Args:
-        matrix (matrix-like): An (m, n) matrix or LinearOperator whose range
-            is to be approximated.
-        rank (int): The desired rank for the approximation. Must be
-            greater than 1.
-        power (int): The exponent for power iterations, used to improve the
-            accuracy of the approximation.
+        matrix: An (m, n) matrix or scipy.LinearOperator whose range is to be approximated.
+        rank: The desired rank for the approximation.
+        power: The number of power iterations to perform. Power iterations
+            (multiplying by `A*A`) improves the accuracy of the approximation by
+            amplifying the dominant singular values, but adds to the computational cost.
 
     Returns:
-        numpy.ndarray: An (m, rank) matrix with orthonormal columns whose
-            span approximates the range of the input matrix.
+        An (m, rank) matrix with orthonormal columns whose span approximates
+        the range of the input matrix.
 
     Notes:
-        If the input matrix is a scipy LinearOperator, it must have the
-        `matmat` and `rmatmat` methods implemented.
-
-        This method is based on Algorithm 4.4 in Halko et al. 2011.
+        Based on Algorithm 4.4 in Halko et al. 2011.
     """
 
     m, n = matrix.shape
@@ -143,19 +146,20 @@ def random_svd(
     matrix: MatrixLike, qr_factor: np.ndarray
 ) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
     """
-    Computes an approximate Singular Value Decomposition (SVD) from a
-    low-rank range approximation.
+    Computes an approximate SVD from a low-rank range approximation.
+
+    This function takes the original matrix and an orthonormal basis for its
+    approximate range (the `qr_factor`) and projects the problem into a smaller
+    subspace where a deterministic SVD is cheap to compute.
 
     Args:
-        matrix (matrix-like): The original (m, n) matrix or LinearOperator.
-        qr_factor (numpy.ndarray): An (m, k) orthonormal basis for the
-            approximate range of the matrix, typically from a
-            `random_range` function.
+        matrix: The original (m, n) matrix or LinearOperator.
+        qr_factor: An (m, k) orthonormal basis for the approximate range,
+            typically from a `random_range` function.
 
     Returns:
-        (numpy.ndarray, numpy.ndarray, numpy.ndarray): A tuple (U, S, Vh)
-            containing the approximate SVD factors, such that A ~= U @ S @ Vh.
-            S is a 1D array of singular values.
+        A tuple `(U, S, Vh)` containing the approximate SVD factors, where S is
+        a 1D array of singular values.
 
     Notes:
         Based on Algorithm 5.1 of Halko et al. 2011.