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

pygeoinf/hilbert_space.py

@@ -1,140 +1,238 @@
 """
-Module defining the core HilbertSpace and EuclideanSpace classes.
+Defines the foundational abstractions for working with Hilbert spaces.
+
+This module provides the core `HilbertSpace` abstract base class (ABC), which
+serves as a mathematical abstraction for real vector spaces equipped with an
+inner product. The design separates abstract vector operations from their
+concrete representations (e.g., as NumPy arrays), allowing for generic and
+reusable implementations of linear operators and algorithms.
+
+The inner product of a space is defined by its Riesz representation map
+(`to_dual` and `from_dual` methods), which connects the space to its dual.
+Concrete subclasses must implement the abstract methods to define a specific
+type of space.
+
+Key Classes
+-----------
+- `HilbertSpace`: The primary ABC defining the interface for all Hilbert spaces.
+- `DualHilbertSpace`: A wrapper class representing the dual of a Hilbert space.
+- `HilbertModule`: An ABC for Hilbert spaces that also support vector multiplication.
+- `EuclideanSpace`: A concrete implementation for R^n using NumPy arrays.
+- `MassWeightedHilbertSpace`: A space whose inner product is weighted by a
+  mass operator relative to an underlying space.
 """
 
 from __future__ import annotations
-from typing import TypeVar, Callable, List, Optional, Any, TYPE_CHECKING
+
+from abc import ABC, abstractmethod
+from typing import (
+    TypeVar,
+    List,
+    Optional,
+    Any,
+    TYPE_CHECKING,
+    final,
+)
 
 import numpy as np
 
 # This block only runs for type checkers, not at runtime
 if TYPE_CHECKING:
     from .operators import LinearOperator
-    from .forms import LinearForm
-
+    from .linear_forms import LinearForm
 
 # Define a generic type for vectors in a Hilbert space
-T_vec = TypeVar("T_vec")
+Vector = TypeVar("Vector")
 
 
-class HilbertSpace:
+class HilbertSpace(ABC):
     """
-    A class for real Hilbert spaces.
+    An abstract base class for real Hilbert spaces.
 
-    This class provides a mathematical abstraction for vector spaces equipped
-    with an inner product. It separates the abstract vector operations from
-    their concrete representation (e.g., as NumPy arrays).
-
-    To define an instance, a user must provide the space's dimension and
-    implementations for converting vectors to/from their component
-    representations, as well as the inner product and Riesz maps.
+    This class provides a mathematical abstraction for a vector space equipped
+    with an inner product. It defines a formal interface that separates
+    abstract vector operations from their concrete representation (e.g., as
+    NumPy arrays). Subclasses must implement all abstract methods to be
+    instantiable.
     """
 
-    def __init__(
-        self,
-        dim: int,
-        to_components: Callable[[T_vec], np.ndarray],
-        from_components: Callable[[np.ndarray], T_vec],
-        inner_product: Callable[[T_vec, T_vec], float],
-        to_dual: Callable[[T_vec], Any],
-        from_dual: Callable[[Any], T_vec],
-        /,
-        *,
-        add: Optional[Callable[[T_vec, T_vec], T_vec]] = None,
-        subtract: Optional[Callable[[T_vec, T_vec], T_vec]] = None,
-        multiply: Optional[Callable[[float, T_vec], T_vec]] = None,
-        ax: Optional[Callable[[float, T_vec], None]] = None,
-        axpy: Optional[Callable[[float, T_vec, T_vec], None]] = None,
-        copy: Optional[Callable[[T_vec], T_vec]] = None,
-        vector_multiply: Optional[Callable[[T_vec, T_vec], T_vec]] = None,
-        base: Optional[HilbertSpace] = None,
-    ):
+    # ------------------------------------------------------------------- #
+    #               Abstract methods that must be provided                #
+    # ------------------------------------------------------------------- #
+
+    @property
+    @abstractmethod
+    def dim(self) -> int:
+        """The finite dimension of the space."""
+
+    @abstractmethod
+    def to_dual(self, x: Vector) -> Any:
         """
-        Initializes the HilbertSpace.
+        Maps a vector to its canonical dual vector (a linear functional).
+
+        This method, along with `from_dual`, defines the Riesz representation
+        map and implicitly defines the inner product of the space.
 
         Args:
-            dim (int): The dimension of the space.
-            to_components (callable): A function mapping vectors to their
-                NumPy component arrays.
-            from_components (callable): A function mapping NumPy component
-                arrays back to vectors.
-            inner_product (callable): The inner product defined on the space.
-            to_dual (callable): The Riesz map from the space to its dual.
-            from_dual (callable): The Riesz map from the dual space back
-                to the primal space.
-            add (callable, optional): Custom vector addition.
-            subtract (callable, optional): Custom vector subtraction.
-            multiply (callable, optional): Custom scalar multiplication.
-            ax (callable, optional): Custom in-place scaling x := a*x.
-            axpy (callable, optional): Custom in-place operation y := a*x + y.
-            copy (callable, optional): Custom deep copy for vectors.
-            base (HilbertSpace, optional): Used internally for creating
-                dual spaces. Should not be set by the user.
-        """
-        self._dim: int = dim
-        self.__to_components: Callable[[T_vec], np.ndarray] = to_components
-        self.__from_components: Callable[[np.ndarray], T_vec] = from_components
-        self.__inner_product: Callable[[T_vec, T_vec], float] = inner_product
-        self.__from_dual: Callable[[Any], T_vec] = from_dual
-        self.__to_dual: Callable[[T_vec], Any] = to_dual
-        self._base: Optional[HilbertSpace] = base
-        self._add: Callable[[T_vec, T_vec], T_vec] = self.__add if add is None else add
-        self._subtract: Callable[[T_vec, T_vec], T_vec] = (
-            self.__subtract if subtract is None else subtract
-        )
-        self._multiply: Callable[[float, T_vec], T_vec] = (
-            self.__multiply if multiply is None else multiply
-        )
-        self._ax: Callable[[float, T_vec], None] = self.__ax if ax is None else ax
-        self._axpy: Callable[[float, T_vec, T_vec], None] = (
-            self.__axpy if axpy is None else axpy
-        )
-        self._copy: Callable[[T_vec], T_vec] = self.__copy if copy is None else copy
-        self._vector_multiply: Optional[Callable[[T_vec, T_vec], T_vec]] = (
-            vector_multiply
-        )
+            x: A vector in the primal space.
 
-    @property
-    def dim(self) -> int:
-        """The dimension of the space."""
-        return self._dim
+        Returns:
+            The corresponding vector in the dual space.
+        """
 
-    @property
-    def has_vector_multiply(self) -> bool:
-        """True if multiplication of elements is defined."""
-        return self._vector_multiply is not None
+    @abstractmethod
+    def from_dual(self, xp: Any) -> Vector:
+        """
+        Maps a dual vector back to its representative in the primal space.
+
+        This is the inverse of the Riesz representation map defined by `to_dual`.
+
+        Args:
+            xp: A vector in the dual space.
+
+        Returns:
+            The corresponding vector in the primal space.
+        """
+
+    @abstractmethod
+    def to_components(self, x: Vector) -> np.ndarray:
+        """
+        Maps a vector to its representation as a NumPy component array.
+
+        Args:
+            x: A vector in the space.
+
+        Returns:
+            The components of the vector as a NumPy array.
+        """
+
+    @abstractmethod
+    def from_components(self, c: np.ndarray) -> Vector:
+        """
+        Maps a NumPy component array back to a vector in the space.
+
+        Args:
+            c: The components of the vector as a NumPy array.
+
+        Returns:
+            The corresponding vector in the space.
+        """
+
+    # ------------------------------------------------------------------- #
+    #            Default implementations that can be overridden           #
+    # ------------------------------------------------------------------- #
 
     @property
     def dual(self) -> HilbertSpace:
         """
-        The dual of the Hilbert space.
+        The dual of this Hilbert space.
 
         The dual space is the space of all continuous linear functionals
-        that map vectors from the Hilbert space to real numbers.
-        """
-        if self._base is None:
-            return HilbertSpace(
-                self.dim,
-                self._dual_to_components,
-                self._dual_from_components,
-                self._dual_inner_product,
-                self.from_dual,
-                self.to_dual,
-                base=self,
-            )
-        else:
-            return self._base
+        (i.e., `LinearForm` objects) that map vectors from this space to
+        real numbers. This implementation returns a `DualHilbertSpace` wrapper.
+        """
+        return DualHilbertSpace(self)
 
     @property
-    def zero(self) -> T_vec:
-        """Returns the zero vector for the space."""
+    def zero(self) -> Vector:
+        """The zero vector (additive identity) of the space."""
         return self.from_components(np.zeros((self.dim)))
 
+    def is_element(self, x: Any) -> bool:
+        """
+        Checks if an object is a valid element of the space.
+
+        Note: The default implementation checks the object's type against the
+        type of the `zero` vector. This may not be robust for all vector
+        representations and can be overridden if needed.
+
+        Args:
+            x: The object to check.
+
+        Returns:
+            True if the object is an element of the space, False otherwise.
+        """
+        return isinstance(x, type(self.zero))
+
+    def duality_product(self, xp: LinearForm, x: Vector) -> float:
+        """
+        Computes the duality product <xp, x>.
+
+        This evaluates the linear functional `xp` (an element of the dual space)
+        at the vector `x` (an element of the primal space).
+
+        Args:
+            xp: The linear functional from the dual space.
+            x: The vector from the primal space.
+
+        Returns:
+            The result of the evaluation xp(x).
+        """
+        return xp(x)
+
+    def add(self, x: Vector, y: Vector) -> Vector:
+        """Computes the sum of two vectors. Defaults to `x + y`."""
+        return x + y
+
+    def subtract(self, x: Vector, y: Vector) -> Vector:
+        """Computes the difference of two vectors. Defaults to `x - y`."""
+        return x - y
+
+    def multiply(self, a: float, x: Vector) -> Vector:
+        """Computes scalar multiplication. Defaults to `a * x`."""
+        return a * x
+
+    def negative(self, x: Vector) -> Vector:
+        """Computes the additive inverse of a vector. Defaults to `-1 * x`."""
+        return -1 * x
+
+    def ax(self, a: float, x: Vector) -> None:
+        """Performs in-place scaling `x := a*x`. Defaults to `x *= a`."""
+        x *= a
+
+    def axpy(self, a: float, x: Vector, y: Vector) -> None:
+        """Performs in-place operation `y := y + a*x`. Defaults to `y += a*x`."""
+        y += a * x
+
+    def copy(self, x: Vector) -> Vector:
+        """Returns a deep copy of a vector. Defaults to `x.copy()`."""
+        return x.copy()
+
+    def random(self) -> Vector:
+        """
+        Generates a random vector from the space.
+
+        The vector's components are drawn from a standard normal distribution.
+
+        Returns:
+            A new random vector.
+        """
+        return self.from_components(np.random.randn(self.dim))
+
+    def __eq__(self, other: object) -> bool:
+        """
+        Defines equality between Hilbert spaces.
+
+        For dual spaces, equality is determined by the equality of their
+        underlying primal spaces. For non-dual spaces, this is not implemented,
+        requiring concrete subclasses to define a meaningful comparison.
+        """
+        if isinstance(self, DualHilbertSpace):
+            return (
+                isinstance(other, DualHilbertSpace)
+                and self.underlying_space == other.underlying_space
+            )
+        return NotImplemented
+
+    # ------------------------------------------------------------------- #
+    #                      Final (Non-Overridable) Methods                #
+    # ------------------------------------------------------------------- #
+
+    @final
     @property
-    def coordinate_inclusion(self) -> "LinearOperator":
+    def coordinate_inclusion(self) -> LinearOperator:
         """
-        Returns the operator mapping coordinate vectors in R^n to vectors
-        in this Hilbert space.
+        The linear operator mapping R^n component vectors into this space.
         """
         from .operators import LinearOperator
 
@@ -144,7 +242,7 @@ class HilbertSpace:
             cp = self.dual.to_components(xp)
             return domain.to_dual(cp)
 
-        def adjoint_mapping(y: T_vec) -> np.ndarray:
+        def adjoint_mapping(y: Vector) -> np.ndarray:
             yp = self.to_dual(y)
             return self.dual.to_components(yp)
 
@@ -156,11 +254,11 @@ class HilbertSpace:
             adjoint_mapping=adjoint_mapping,
         )
 
+    @final
     @property
-    def coordinate_projection(self) -> "LinearOperator":
+    def coordinate_projection(self) -> LinearOperator:
         """
-        Returns the operator mapping vectors in this Hilbert space to their
-        coordinate vectors in R^n.
+        The linear operator projecting vectors from this space to R^n.
         """
         from .operators import LinearOperator
 
@@ -170,7 +268,7 @@ class HilbertSpace:
             c = codomain.from_dual(cp)
             return self.dual.from_components(c)
 
-        def adjoint_mapping(c: np.ndarray) -> T_vec:
+        def adjoint_mapping(c: np.ndarray) -> Vector:
             xp = self.dual.from_components(c)
             return self.from_dual(xp)
 
@@ -182,138 +280,131 @@ class HilbertSpace:
             adjoint_mapping=adjoint_mapping,
         )
 
+    @final
     @property
-    def riesz(self) -> "LinearOperator":
-        """
-        Returns the Riesz map (dual to primal) as a LinearOperator.
-        """
+    def riesz(self) -> LinearOperator:
+        """The Riesz map (dual to primal) as a `LinearOperator`."""
         from .operators import LinearOperator
 
         return LinearOperator.self_dual(self.dual, self.from_dual)
 
+    @final
     @property
-    def inverse_riesz(self) -> "LinearOperator":
-        """
-        Returns the inverse Riesz map (primal to dual) as a LinearOperator.
-        """
+    def inverse_riesz(self) -> LinearOperator:
+        """The inverse Riesz map (primal to dual) as a `LinearOperator`."""
         from .operators import LinearOperator
 
         return LinearOperator.self_dual(self, self.to_dual)
 
-    def inner_product(self, x1: T_vec, x2: T_vec) -> float:
-        """Computes the inner product of two vectors."""
-        return self.__inner_product(x1, x2)
+    @final
+    def inner_product(self, x1: Vector, x2: Vector) -> float:
+        """
+        Computes the inner product of two vectors, `(x1, x2)`.
+
+        This is defined via the duality product as `<R(x1), x2>`, where `R` is
+        the Riesz map (`to_dual`).
+
+        Args:
+            x1: The first vector.
+            x2: The second vector.
+
+        Returns:
+            The inner product as a float.
+        """
+        return self.duality_product(self.to_dual(x1), x2)
+
+    @final
+    def squared_norm(self, x: Vector) -> float:
+        """
+        Computes the squared norm of a vector, `||x||^2`.
 
-    def squared_norm(self, x: T_vec) -> float:
-        """Computes the squared norm of a vector."""
+        Args:
+            x: The vector.
+
+        Returns:
+            The squared norm of the vector.
+        """
         return self.inner_product(x, x)
 
-    def norm(self, x: T_vec) -> float:
-        """Computes the norm of a vector."""
+    @final
+    def norm(self, x: Vector) -> float:
+        """
+        Computes the norm of a vector, `||x||`.
+
+        Args:
+            x: The vector.
+
+        Returns:
+            The norm of the vector.
+        """
         return np.sqrt(self.squared_norm(x))
 
-    def gram_schmidt(self, vectors: List[T_vec]) -> List[T_vec]:
+    @final
+    def gram_schmidt(self, vectors: List[Vector]) -> List[Vector]:
         """
         Orthonormalizes a list of vectors using the Gram-Schmidt process.
+
+        Args:
+            vectors: A list of linearly independent vectors.
+
+        Returns:
+            A list of orthonormalized vectors spanning the same subspace.
+
+        Raises:
+            ValueError: If not all items in the list are elements of the space.
         """
         if not all(self.is_element(vector) for vector in vectors):
             raise ValueError("Not all vectors are elements of the space")
 
-        orthonormalised_vectors: List[T_vec] = []
+        orthonormalised_vectors: List[Vector] = []
         for i, vector in enumerate(vectors):
             vec_copy = self.copy(vector)
             for j in range(i):
                 product = self.inner_product(vec_copy, orthonormalised_vectors[j])
                 self.axpy(-product, orthonormalised_vectors[j], vec_copy)
             norm = self.norm(vec_copy)
+            if norm < 1e-12:
+                raise ValueError("Vectors are not linearly independent.")
             self.ax(1 / norm, vec_copy)
             orthonormalised_vectors.append(vec_copy)
 
         return orthonormalised_vectors
 
-    def to_dual(self, x: T_vec) -> Any:
-        """Maps a vector to its canonical dual vector (a linear functional)."""
-        return self.__to_dual(x)
-
-    def from_dual(self, xp: Any) -> T_vec:
-        """Maps a dual vector to its representative in the primal space."""
-        return self.__from_dual(xp)
-
-    def _dual_inner_product(self, xp1: Any, xp2: Any) -> float:
-        return self.inner_product(self.from_dual(xp1), self.from_dual(xp2))
-
-    def is_element(self, x: Any) -> bool:
+    @final
+    def basis_vector(self, i: int) -> Vector:
         """
-        Checks if an object is an element of the space.
+        Returns the i-th standard basis vector.
 
-        Note: The current implementation checks type against the zero vector.
-        This may not be robust for all vector representations.
-        """
-        return isinstance(x, type(self.zero))
+        This is the vector whose component array is all zeros except for a one
+        at index `i`.
 
-    def add(self, x: T_vec, y: T_vec) -> T_vec:
-        """Adds two vectors."""
-        return self._add(x, y)
-
-    def subtract(self, x: T_vec, y: T_vec) -> T_vec:
-        """Subtracts two vectors."""
-        return self._subtract(x, y)
-
-    def multiply(self, a: float, x: T_vec) -> T_vec:
-        """Performs scalar multiplication, returning a new vector."""
-        return self._multiply(a, x)
-
-    def negative(self, x: T_vec) -> T_vec:
-        """Returns the additive inverse of a vector."""
-        return self.multiply(-1.0, x)
-
-    def ax(self, a: float, x: T_vec) -> None:
-        """Performs the in-place scaling operation x := a*x."""
-        self._ax(a, x)
-
-    def axpy(self, a: float, x: T_vec, y: T_vec) -> None:
-        """Performs the in-place vector operation y := y + a*x."""
-        self._axpy(a, x, y)
-
-    def copy(self, x: T_vec) -> T_vec:
-        """Returns a deep copy of a vector."""
-        return self._copy(x)
+        Args:
+            i: The index of the basis vector.
 
-    def vector_multiply(self, x1: T_vec, x2: T_vec) -> T_vec:
+        Returns:
+            The i-th basis vector.
         """
-        Returns the product of two elements of the space, if defined.
-        """
-        if self._vector_multiply is None:
-            raise NotImplementedError(
-                "Vector multiplication not defined on this space."
-            )
-        return self._vector_multiply(x1, x2)
-
-    def to_components(self, x: T_vec) -> np.ndarray:
-        """Maps a vector to its NumPy component array."""
-        return self.__to_components(x)
-
-    def from_components(self, c: np.ndarray) -> T_vec:
-        """Maps a NumPy component array to a vector."""
-        return self.__from_components(c)
-
-    def basis_vector(self, i: int) -> T_vec:
-        """Returns the i-th standard basis vector."""
         c = np.zeros(self.dim)
         c[i] = 1
         return self.from_components(c)
 
-    def random(self) -> T_vec:
+    @final
+    def sample_expectation(self, vectors: List[Vector]) -> Vector:
         """
-        Returns a random vector from the space.
+        Computes the sample mean of a list of vectors.
 
-        The vector's components are drawn from a standard Gaussian distribution.
-        """
-        return self.from_components(np.random.randn(self.dim))
+        Args:
+            vectors: A list of vectors from the space.
+
+        Returns:
+            The sample mean (average) vector.
 
-    def sample_expectation(self, vectors: List[T_vec]) -> T_vec:
-        """Computes the sample mean of a list of vectors."""
+        Raises:
+            TypeError: If not all items in the list are elements of the space.
+        """
         n = len(vectors)
+        if not n > 0:
+            raise ValueError("Cannot compute expectation of an empty list.")
         if not all(self.is_element(x) for x in vectors):
             raise TypeError("Not all items in list are elements of the space.")
         xbar = self.zero
@@ -321,25 +412,29 @@ class HilbertSpace:
             self.axpy(1 / n, x, xbar)
         return xbar
 
-    def identity_operator(self) -> "LinearOperator":
-        """Returns the identity operator on the space."""
+    @final
+    def identity_operator(self) -> LinearOperator:
+        """Returns the identity operator `I` on the space."""
         from .operators import LinearOperator
 
         return LinearOperator(
             self,
             self,
             lambda x: x,
-            dual_mapping=lambda yp: yp,
             adjoint_mapping=lambda y: y,
         )
 
-    def zero_operator(
-        self, codomain: Optional[HilbertSpace] = None
-    ) -> "LinearOperator":
+    @final
+    def zero_operator(self, codomain: Optional[HilbertSpace] = None) -> LinearOperator:
         """
-        Returns the zero operator from this space to a codomain.
+        Returns the zero operator `0` from this space to a codomain.
 
-        If no codomain is provided, it maps to itself.
+        Args:
+            codomain: The target space of the operator. If None, the operator
+                maps to this space itself.
+
+        Returns:
+            The zero linear operator.
         """
         from .operators import LinearOperator
 
@@ -352,65 +447,246 @@ class HilbertSpace:
             adjoint_mapping=lambda y: self.zero,
         )
 
-    def _dual_to_components(self, xp: "LinearForm") -> np.ndarray:
-        return xp.components
 
-    def _dual_from_components(self, cp: np.ndarray) -> "LinearForm":
-        from .forms import LinearForm
+class DualHilbertSpace(HilbertSpace):
+    """
+    A wrapper class representing the dual of a `HilbertSpace`.
+
+    An element of a dual space is a continuous linear functional, represented
+    in this library by the `LinearForm` class. This wrapper provides a full
+    `HilbertSpace` interface for these `LinearForm` objects, allowing them to be
+    treated as vectors in their own right.
+    """
 
-        return LinearForm(self, components=cp)
+    def __init__(self, space: HilbertSpace):
+        """
+        Args:
+            space: The primal space from which to form the dual.
+        """
+        self._underlying_space = space
 
-    def __add(self, x: T_vec, y: T_vec) -> T_vec:
-        return x + y
+    @property
+    def underlying_space(self) -> HilbertSpace:
+        """The primal `HilbertSpace` of which this is the dual."""
+        return self._underlying_space
 
-    def __subtract(self, x: T_vec, y: T_vec) -> T_vec:
-        return x - y
+    @property
+    def dim(self) -> int:
+        """The dimension of the dual space."""
+        return self._underlying_space.dim
 
-    def __multiply(self, a: float, x: T_vec) -> T_vec:
-        return a * x.copy()
+    @property
+    def dual(self) -> HilbertSpace:
+        """The dual of the dual space, which is the original primal space."""
+        return self._underlying_space
 
-    def __ax(self, a: float, x: T_vec) -> None:
-        x *= a
+    def to_dual(self, x: LinearForm) -> Any:
+        """Maps a dual vector back to its representative in the primal space."""
+        return self._underlying_space.from_dual(x)
 
-    def __axpy(self, a: float, x: T_vec, y: T_vec) -> None:
-        y += a * x
+    def from_dual(self, xp: Vector) -> LinearForm:
+        """Maps a primal vector to its corresponding dual `LinearForm`."""
+        return self._underlying_space.to_dual(xp)
+
+    def to_components(self, x: LinearForm) -> np.ndarray:
+        """Maps a `LinearForm` to its NumPy component array."""
+        return x.components
+
+    def from_components(self, c: np.ndarray) -> LinearForm:
+        """Creates a `LinearForm` from a NumPy component array."""
+        from .linear_forms import LinearForm
+
+        return LinearForm(self._underlying_space, components=c)
+
+    @final
+    def duality_product(self, xp: LinearForm, x: Vector) -> float:
+        """
+        Computes the duality product <x, xp>.
+
+        In this context, `x` is from the primal space and `xp` is the dual
+        vector (a `LinearForm`). This is unconventional but maintains the
+        method signature; it evaluates `x(xp)`.
+        """
+        return x(xp)
 
-    def __copy(self, x: T_vec) -> T_vec:
-        return x.copy()
+
+class HilbertModule(HilbertSpace, ABC):
+    """
+    An ABC for a `HilbertSpace` where vector multiplication is defined.
+
+    This acts as a "mixin" interface, adding the `vector_multiply` requirement
+    to the `HilbertSpace` contract.
+    """
+
+    @abstractmethod
+    def vector_multiply(self, x1: Vector, x2: Vector) -> Vector:
+        """
+        Computes the product of two vectors.
+
+        Args:
+            x1: The first vector.
+            x2: The second vector.
+
+        Returns:
+            The product of the two vectors.
+        """
 
 
 class EuclideanSpace(HilbertSpace):
     """
     An n-dimensional Euclidean space, R^n.
 
-    This is a concrete implementation of HilbertSpace where vectors are
-    represented directly by NumPy arrays.
+    This is a concrete `HilbertSpace` where vectors are represented directly by
+    NumPy arrays, and the inner product is the standard dot product.
     """
 
-    def __init__(self, dim: int) -> None:
+    def __init__(self, dim: int):
         """
         Args:
-            dim (int): Dimension of the space.
+            dim: The dimension of the space.
         """
-        super().__init__(
-            dim,
-            lambda x: x,
-            lambda x: x,
-            self.__inner_product,
-            self.__to_dual,
-            self.__from_dual,
-        )
+        if dim < 1:
+            raise ValueError("Dimension must be a positive integer.")
+        self._dim = dim
+
+    @property
+    def dim(self) -> int:
+        """The dimension of the space."""
+        return self._dim
 
-    def __inner_product(self, x1: np.ndarray, x2: np.ndarray) -> float:
-        return np.dot(x1, x2)
+    def to_components(self, x: np.ndarray) -> np.ndarray:
+        """Returns the vector itself, as it is already a component array."""
+        return x
 
-    def __to_dual(self, x: np.ndarray) -> "LinearForm":
-        return self.dual.from_components(x)
+    def from_components(self, c: np.ndarray) -> np.ndarray:
+        """Returns the component array itself, as it is the vector."""
+        return c
 
-    def __from_dual(self, xp: "LinearForm") -> np.ndarray:
-        cp = self.dual.to_components(xp)
-        return self.from_components(cp)
+    def to_dual(self, x: np.ndarray) -> "LinearForm":
+        """Maps a vector `x` to a `LinearForm` with the same components."""
+        from .linear_forms import LinearForm
 
-    def __eq__(self, other: object) -> bool:
-        """Checks for equality with another EuclideanSpace."""
-        return isinstance(other, EuclideanSpace) and self.dim == other.dim
+        return LinearForm(self, components=x)
+
+    def from_dual(self, xp: "LinearForm") -> np.ndarray:
+        """Maps a `LinearForm` back to a vector via its components."""
+        return self.dual.to_components(xp)
+
+
+class MassWeightedHilbertSpace(HilbertSpace):
+    """
+    A Hilbert space with an inner product weighted by a mass operator.
+
+    This class wraps an existing `HilbertSpace` (let's call it X) and defines a new
+    inner product for a space (Y) as: `(u, v)_Y = (M @ u, v)_X`, where `M` is a
+    self-adjoint, positive-definite mass operator defined on X.
+
+    This is a common construction in numerical methods like the Finite Element
+    Method, where the basis functions are not orthonormal.
+    """
+
+    def __init__(
+        self,
+        underlying_space: HilbertSpace,
+        mass_operator: LinearOperator,
+        inverse_mass_operator: LinearOperator,
+    ):
+        """
+        Args:
+            underlying_space: The original space (X) on which the inner
+                product is defined.
+            mass_operator: The self-adjoint, positive-definite mass
+                operator (M).
+            inverse_mass_operator: The inverse of the mass operator.
+        """
+        self._underlying_space = underlying_space
+        self._mass_operator = mass_operator
+        self._inverse_mass_operator = inverse_mass_operator
+
+    @property
+    def dim(self) -> int:
+        """The dimension of the space."""
+        return self._underlying_space.dim
+
+    @property
+    def underlying_space(self) -> HilbertSpace:
+        """The underlying Hilbert space (X) without mass weighting."""
+        return self._underlying_space
+
+    @property
+    def mass_operator(self) -> LinearOperator:
+        """The mass operator (M) defining the weighted inner product."""
+        return self._mass_operator
+
+    @property
+    def inverse_mass_operator(self) -> LinearOperator:
+        """The inverse of the mass operator."""
+        return self._inverse_mass_operator
+
+    def to_components(self, x: Vector) -> np.ndarray:
+        """Delegates component mapping to the underlying space."""
+        return self.underlying_space.to_components(x)
+
+    def from_components(self, c: np.ndarray) -> Vector:
+        """Delegates vector creation to the underlying space."""
+        return self.underlying_space.from_components(c)
+
+    def to_dual(self, x: Vector) -> "LinearForm":
+        """
+        Computes the dual mapping `R_Y(x) = R_X(M x)`.
+        """
+        from .linear_forms import LinearForm
+
+        y = self._mass_operator(x)
+        yp = self.underlying_space.to_dual(y)
+        return LinearForm(self, components=yp.components)
+
+    def from_dual(self, xp: "LinearForm") -> Vector:
+        """
+        Computes the inverse dual mapping `R_Y^{-1}(xp) = M^{-1} R_X^{-1}(xp)`.
+        """
+        # Note: This implementation relies on the from_dual operator of the
+        # underlying space not checking the domain of its argument. This is
+        # acceptable and avoids an unnecessary copy.
+        x = self.underlying_space.from_dual(xp)
+        return self._inverse_mass_operator(x)
+
+
+class MassWeightedHilbertModule(MassWeightedHilbertSpace, HilbertModule):
+    """
+    A mass-weighted Hilbert space that also supports vector multiplication.
+
+    This class inherits the mass-weighted inner product structure and mixes in
+    the `HilbertModule` interface, delegating the multiplication operation to
+    the underlying space.
+    """
+
+    def __init__(
+        self,
+        underlying_space: HilbertModule,
+        mass_operator: LinearOperator,
+        inverse_mass_operator: LinearOperator,
+    ):
+        """
+        Args:
+            underlying_space: The original space (X) on which the inner
+                product is defined.
+            mass_operator: The self-adjoint, positive-definite mass
+                operator (M).
+            inverse_mass_operator: The inverse of the mass operator.
+        """
+        if not isinstance(underlying_space, HilbertModule):
+            raise TypeError("Underlying space must be a HilbertModule.")
+
+        MassWeightedHilbertSpace.__init__(
+            self, underlying_space, mass_operator, inverse_mass_operator
+        )
+
+    def vector_multiply(self, x1: Vector, x2: Vector) -> Vector:
+        """
+        Computes vector multiplication by delegating to the underlying space.
+
+        Note: This assumes the underlying space provided during initialization
+        is itself an instance of `HilbertModule`.
+        """
+        return self.underlying_space.vector_multiply(x1, x2)