pepflow 0.1.4a1__py3-none-any.whl → 0.1.5__py3-none-any.whl

pepflow/point.py

@@ -27,37 +27,65 @@ import numpy as np
 
 from pepflow import pep_context as pc
 from pepflow import utils
-from pepflow.scalar import EvalExpressionScalar, Scalar
+from pepflow.scalar import Scalar, ScalarRepresentation
 
 
 def is_numerical_or_point(val: Any) -> bool:
-    return utils.is_numerical(val) or isinstance(val, Point)
+    return utils.is_numerical_or_parameter(val) or isinstance(val, Point)
 
 
 def is_numerical_or_evaluatedpoint(val: Any) -> bool:
-    return utils.is_numerical(val) or isinstance(val, EvaluatedPoint)
+    return utils.is_numerical_or_parameter(val) or isinstance(val, EvaluatedPoint)
 
 
 @attrs.frozen
-class EvalExpressionPoint:
+class PointRepresentation:
     op: utils.Op
     left_point: Point | float
     right_point: Point | float
 
 
+@attrs.frozen
+class ZeroPoint:
+    """A special class to represent 0 in Point."""
+
+    pass
+
+
 @attrs.frozen
 class EvaluatedPoint:
+    """
+    The concrete representation of the abstract :class:`Point`.
+
+    Each abstract basis :class:`Point` object has a unique concrete
+    representation as a unit vector. The concrete representations of
+    linear combinations of abstract basis :class:`Point` objects are
+    linear combinations of the unit vectors. This information is stored
+    in the `vector` attribute.
+
+    :class:`EvaluatedPoint` objects can be constructed as linear combinations
+    of other :class:`EvaluatedPoint` objects. Let `a` and `b` be some numeric
+    data type. Let `x` and `y` be :class:`EvaluatedPoint` objects. Then, we
+    can form a new :class:`EvaluatedPoint` object: `a*x+b*y`.
+
+    Attributes:
+        vector (np.ndarray): The concrete representation of an
+            abstract :class:`Point`.
+    """
+
     vector: np.ndarray
 
+    @classmethod
+    def zero(cls, num_basis_points: int):
+        return EvaluatedPoint(vector=np.zeros(num_basis_points))
+
     def __add__(self, other):
         if isinstance(other, EvaluatedPoint):
             return EvaluatedPoint(vector=self.vector + other.vector)
         elif utils.is_numerical(other):
             return EvaluatedPoint(vector=self.vector + other)
         else:
-            raise ValueError(
-                f"Unsupported add operation between EvaluatedPoint and {type(other)}"
-            )
+            return NotImplemented
 
     def __radd__(self, other):
         return self.__add__(other)
@@ -68,9 +96,7 @@ class EvaluatedPoint:
         elif utils.is_numerical(other):
             return EvaluatedPoint(vector=self.vector - other)
         else:
-            raise ValueError(
-                f"Unsupported sub operation between EvaluatedPoint and {type(other)}"
-            )
+            return NotImplemented
 
     def __rsub__(self, other):
         if isinstance(other, EvaluatedPoint):
@@ -78,30 +104,51 @@ class EvaluatedPoint:
         elif utils.is_numerical(other):
             return EvaluatedPoint(vector=other - self.vector)
         else:
-            raise ValueError(
-                f"Unsupported sub operation between EvaluatedPoint and {type(other)}"
-            )
+            return NotImplemented
 
     def __mul__(self, other):
-        assert utils.is_numerical(other)
+        if not utils.is_numerical(other):
+            return NotImplemented
         return EvaluatedPoint(vector=self.vector * other)
 
     def __rmul__(self, other):
-        assert utils.is_numerical(other)
+        if not utils.is_numerical(other):
+            return NotImplemented
         return EvaluatedPoint(vector=other * self.vector)
 
     def __truediv__(self, other):
-        assert utils.is_numerical(other)
+        if not utils.is_numerical(other):
+            return NotImplemented
         return EvaluatedPoint(vector=self.vector / other)
 
 
 @attrs.frozen
 class Point:
+    """
+    A :class:`Point` object represents an element of a pre-Hilbert space.
+    Examples include a point or a gradient.
+
+    :class:`Point` objects can be constructed as linear combinations of
+    other :class:`Point` objects. Let `a` and `b` be some numeric data type.
+    Let `x` and `y` be :class:`Point` objects. Then, we can form a new
+    :class:`Point` object: `a*x+b*y`.
+
+    The inner product of two :class:`Point` objects can also be taken.
+    Let `x` and `y` be :class:`Point` objects. Then, their inner product is
+    `x*y` and returns a :class:`Scalar` object.
+
+    Attributes:
+        is_basis (bool): `True` if this point is not formed through a linear
+            combination of other points. `False` otherwise.
+        tags (list[str]): A list that contains tags that can be used to
+            identify the :class:`Point` object. Tags should be unique.
+    """
+
     # If true, the point is the basis for the evaluations of G
     is_basis: bool
 
-    # How to evaluate the point.
-    eval_expression: EvalExpressionPoint | None = None
+    # The representation of point used for evaluation.
+    eval_expression: PointRepresentation | ZeroPoint | None = None
 
     # Human tagged value for the Point
     tags: list[str] = attrs.field(factory=list)
@@ -120,13 +167,27 @@ class Point:
             raise RuntimeError("Did you forget to create a context?")
         pep_context.add_point(self)
 
+    @staticmethod
+    def zero() -> Point:
+        return Point(is_basis=False, eval_expression=ZeroPoint(), tags=["0"])
+
     @property
     def tag(self):
+        """Returns the most recently added tag.
+
+        Returns:
+            str: The most recently added tag of this :class:`Point` object.
+        """
         if len(self.tags) == 0:
             raise ValueError("Point should have a name.")
         return self.tags[-1]
 
     def add_tag(self, tag: str) -> None:
+        """Add a new tag for this :class:`Point` object.
+
+        Args:
+            tag (str): The new tag to be added to the `tags` list.
+        """
         self.tags.append(tag)
 
     def __repr__(self):
@@ -135,18 +196,15 @@ class Point:
         return super().__repr__()
 
     def _repr_latex_(self):
-        s = repr(self)
-        s = s.replace("star", r"\star")
-        s = s.replace("gradient_", r"\nabla ")
-        s = s.replace("|", r"\|")
-        return rf"$\\displaystyle {s}$"
+        return utils.str_to_latex(repr(self))
 
     # TODO: add a validator that `is_basis` and `eval_expression` are properly setup.
     def __add__(self, other):
-        assert isinstance(other, Point)
+        if not isinstance(other, Point):
+            return NotImplemented
         return Point(
             is_basis=False,
-            eval_expression=EvalExpressionPoint(utils.Op.ADD, self, other),
+            eval_expression=PointRepresentation(utils.Op.ADD, self, other),
             tags=[f"{self.tag}+{other.tag}"],
         )
 
@@ -154,72 +212,78 @@ class Point:
         # TODO: come up with better way to handle this
         if other == 0:
             return self
-        assert isinstance(other, Point)
+        if not isinstance(other, Point):
+            return NotImplemented
         return Point(
             is_basis=False,
-            eval_expression=EvalExpressionPoint(utils.Op.ADD, other, self),
+            eval_expression=PointRepresentation(utils.Op.ADD, other, self),
             tags=[f"{other.tag}+{self.tag}"],
         )
 
     def __sub__(self, other):
-        assert isinstance(other, Point)
+        if not isinstance(other, Point):
+            return NotImplemented
         tag_other = utils.parenthesize_tag(other)
         return Point(
             is_basis=False,
-            eval_expression=EvalExpressionPoint(utils.Op.SUB, self, other),
+            eval_expression=PointRepresentation(utils.Op.SUB, self, other),
             tags=[f"{self.tag}-{tag_other}"],
         )
 
     def __rsub__(self, other):
-        assert isinstance(other, Point)
+        if not isinstance(other, Point):
+            return NotImplemented
         tag_self = utils.parenthesize_tag(self)
         return Point(
             is_basis=False,
-            eval_expression=EvalExpressionPoint(utils.Op.SUB, other, self),
+            eval_expression=PointRepresentation(utils.Op.SUB, other, self),
             tags=[f"{other.tag}-{tag_self}"],
         )
 
     def __mul__(self, other):
-        # TODO allow the other to be point so that we return a scalar.
-        assert is_numerical_or_point(other)
+        if not is_numerical_or_point(other):
+            return NotImplemented
         tag_self = utils.parenthesize_tag(self)
-        if utils.is_numerical(other):
+        if utils.is_numerical_or_parameter(other):
+            tag_other = utils.numerical_str(other)
             return Point(
                 is_basis=False,
-                eval_expression=EvalExpressionPoint(utils.Op.MUL, self, other),
-                tags=[f"{tag_self}*{other:.4g}"],
+                eval_expression=PointRepresentation(utils.Op.MUL, self, other),
+                tags=[f"{tag_self}*{tag_other}"],
             )
         else:
             tag_other = utils.parenthesize_tag(other)
             return Scalar(
                 is_basis=False,
-                eval_expression=EvalExpressionScalar(utils.Op.MUL, self, other),
+                eval_expression=ScalarRepresentation(utils.Op.MUL, self, other),
                 tags=[f"{tag_self}*{tag_other}"],
             )
 
     def __rmul__(self, other):
-        # TODO allow the other to be point so that we return a scalar.
-        assert is_numerical_or_point(other)
+        if not is_numerical_or_point(other):
+            return NotImplemented
         tag_self = utils.parenthesize_tag(self)
-        if utils.is_numerical(other):
+        if utils.is_numerical_or_parameter(other):
+            tag_other = utils.numerical_str(other)
             return Point(
                 is_basis=False,
-                eval_expression=EvalExpressionPoint(utils.Op.MUL, other, self),
-                tags=[f"{other:.4g}*{tag_self}"],
+                eval_expression=PointRepresentation(utils.Op.MUL, other, self),
+                tags=[f"{tag_other}*{tag_self}"],
             )
         else:
             tag_other = utils.parenthesize_tag(other)
             return Scalar(
                 is_basis=False,
-                eval_expression=EvalExpressionScalar(utils.Op.MUL, other, self),
+                eval_expression=ScalarRepresentation(utils.Op.MUL, other, self),
                 tags=[f"{tag_other}*{tag_self}"],
             )
 
     def __pow__(self, power):
-        assert power == 2
+        if power != 2:
+            return NotImplemented
         return Scalar(
             is_basis=False,
-            eval_expression=EvalExpressionScalar(utils.Op.MUL, self, self),
+            eval_expression=ScalarRepresentation(utils.Op.MUL, self, self),
             tags=[rf"|{self.tag}|^{power}"],
         )
 
@@ -227,17 +291,19 @@ class Point:
         tag_self = utils.parenthesize_tag(self)
         return Point(
             is_basis=False,
-            eval_expression=EvalExpressionPoint(utils.Op.MUL, -1, self),
+            eval_expression=PointRepresentation(utils.Op.MUL, -1, self),
             tags=[f"-{tag_self}"],
         )
 
     def __truediv__(self, other):
-        assert utils.is_numerical(other)
+        if not utils.is_numerical_or_parameter(other):
+            return NotImplemented
         tag_self = utils.parenthesize_tag(self)
+        tag_other = f"1/{utils.numerical_str(other)}"
         return Point(
             is_basis=False,
-            eval_expression=EvalExpressionPoint(utils.Op.DIV, self, other),
-            tags=[f"1/{other:.4g}*{tag_self}"],
+            eval_expression=PointRepresentation(utils.Op.DIV, self, other),
+            tags=[f"{tag_other}*{tag_self}"],
         )
 
     def __hash__(self):
@@ -249,6 +315,20 @@ class Point:
         return self.uid == other.uid
 
     def eval(self, ctx: pc.PEPContext | None = None) -> np.ndarray:
+        """
+        Return the concrete representation of this :class:`Point`.
+        Concrete representations of :class:`Point` objects are
+        :class:`EvaluatedPoint` objects.
+
+        Args:
+            ctx (:class:`PEPContext` | None): The :class:`PEPContext` object
+                we consider. `None` if we consider the current global
+                :class:`PEPContext` object.
+
+        Returns:
+            :class:`EvaluatedPoint`: The concrete representation of
+            this :class:`Point`.
+        """
         from pepflow.expression_manager import ExpressionManager
 
         # Note this can be inefficient.
@@ -258,3 +338,29 @@ class Point:
             raise RuntimeError("Did you forget to create a context?")
         em = ExpressionManager(ctx)
         return em.eval_point(self).vector
+
+    def repr_by_basis(self, ctx: pc.PEPContext | None = None) -> str:
+        """
+        Express this :class:`Point` object as the linear combination of
+        the basis :class:`Point` objects of the given :class:`PEPContext`.
+        This linear combination is expressed as a `str` where, to refer to
+        the basis :class:`Point` objects, we use their tags.
+
+        Args:
+            ctx (:class:`PEPContext`): The :class:`PEPContext` object
+                whose basis :class:`Point` objects we consider. `None` if
+                we consider the current global :class:`PEPContext` object.
+
+        Returns:
+            str: The representation of this :class:`Point` object in terms of
+            the basis :class:`Point` objects of the given :class:`PEPContext`.
+        """
+        from pepflow.expression_manager import ExpressionManager
+
+        # Note this can be inefficient.
+        if ctx is None:
+            ctx = pc.get_current_context()
+        if ctx is None:
+            raise RuntimeError("Did you forget to create a context?")
+        em = ExpressionManager(ctx)
+        return em.repr_point_by_basis(self)

pepflow/point_test.py

@@ -162,3 +162,15 @@ def test_expression_manager_eval_point_large_scale(pep_context):
         pm.eval_point(pp)
 
     assert (time.time() - t) < 0.5
+
+
+def test_zero_point(pep_context):
+    _ = point.Point(is_basis=True, tags=["p1"])
+    p0 = point.Point.zero()
+
+    pm = exm.ExpressionManager(pep_context)
+    np.testing.assert_allclose(pm.eval_point(p0).vector, np.array([0]))
+
+    _ = point.Point(is_basis=True, tags=["p2"])
+    pm = exm.ExpressionManager(pep_context)
+    np.testing.assert_allclose(pm.eval_point(p0).vector, np.array([0, 0]))