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

pepflow/function.py

@@ -36,6 +36,19 @@ if TYPE_CHECKING:
 
 @attrs.frozen
 class Triplet:
+    """
+    A data class that represents, for some given function :math:`f`,
+    the tuple :math:`\\{x, f(x), \\nabla f(x)\\}`. We can also consider
+    a subgradient :math:`\\widetilde{\\nabla} f(x)` instead of the gradient.
+
+    Attributes:
+        point (:class:`Point`): The point :math:`x`.
+        function_value (:class:`Scalar`): The function value :math:`f(x)`.
+        gradient (:class:`Point`): The gradient :math:`\\nabla f(x)` or
+            a subgradient :math:`\\widetilde{\\nabla} f(x)`.
+        name (str): The unique name of the :class:`Triplet` object.
+    """
+
     point: pt.Point
     function_value: sc.Scalar
     gradient: pt.Point
@@ -53,7 +66,7 @@ class AddedFunc:
 
 @attrs.frozen
 class ScaledFunc:
-    """Represents scale * base_func."""
+    """Represents scalar * base_func."""
 
     scale: float
     base_func: Function
@@ -61,6 +74,25 @@ class ScaledFunc:
 
 @attrs.mutable
 class Function:
+    """A :class:`Function` object represents a function.
+
+    :class:`Function` objects can be constructed as linear combinations
+    of other :class:`Function` objects. Let `a` and `b` be some numeric
+    data type. Let `f` and `g` be :class:`Function` objects. Then, we
+    can form a new :class:`Function` object: `a*f+b*g`.
+
+    A :class:`Function` object should never be explicitly constructed. Only
+    children of :class:`Function` such as :class:`ConvexFunction` or
+    :class:`SmoothConvexFunction` should be constructed. See their respective
+    documentation to see how.
+
+    Attributes:
+        is_basis (bool): `True` if this function is not formed through a linear
+            combination of other functions. `False` otherwise.
+        tags (list[str]): A list that contains tags that can be used to
+            identify the :class:`Function` object. Tags should be unique.
+    """
+
     is_basis: bool
 
     composition: AddedFunc | ScaledFunc | None = None
@@ -79,11 +111,21 @@ class Function:
 
     @property
     def tag(self):
+        """Returns the most recently added tag.
+
+        Returns:
+            str: The most recently added tag of this :class:`Function` object.
+        """
         if len(self.tags) == 0:
             raise ValueError("Function should have a name.")
         return self.tags[-1]
 
     def add_tag(self, tag: str) -> None:
+        """Add a new tag for this :class:`Function` object.
+
+        Args:
+            tag (str): The new tag to be added to the `tags` list.
+        """
         self.tags.append(tag)
 
     def __repr__(self):
@@ -93,7 +135,7 @@ class Function:
 
     def _repr_latex_(self):
         s = repr(self)
-        return rf"$\\displaystyle {s}$"
+        return rf"$\displaystyle {s}$"
 
     def get_interpolation_constraints(self):
         raise NotImplementedError(
@@ -161,6 +203,18 @@ class Function:
         return triplet
 
     def add_stationary_point(self, name: str) -> pt.Point:
+        """
+        Return a stationary point for this :class:`Function` object.
+        A :class:`Function` object can only have one stationary point.
+
+        Args:
+            name (str): The tag for the :class:`Point` object which
+                 will serve as the stationary point.
+
+        Returns:
+            :class:`Point`: The stationary point for this :class:`Function`
+            object.
+        """
         # assert we can only add one stationary point?
         pep_context = pc.get_current_context()
         if pep_context is None:
@@ -171,7 +225,7 @@ class Function:
             )
         point = pt.Point(is_basis=True)
         point.add_tag(name)
-        desired_grad = 0 * point
+        desired_grad = pt.Point.zero()  # zero point
         desired_grad.add_tag(f"gradient_{self.tag}({name})")
         triplet = self.add_point_with_grad_restriction(point, desired_grad)
         pep_context.add_stationary_triplet(self, triplet)
@@ -195,6 +249,9 @@ class Function:
         if pep_context is None:
             raise RuntimeError("Did you forget to create a context?")
 
+        if not isinstance(point, pt.Point):
+            raise ValueError("The Function can only take point as input.")
+
         if self.is_basis:
             for triplet in pep_context.triplets[self]:
                 if triplet.point.uid == point.uid:
@@ -232,14 +289,50 @@ class Function:
         return Triplet(point, function_value, gradient, name=None)
 
     def gradient(self, point: pt.Point) -> pt.Point:
+        """
+        Returns a :class:`Point` object that is the gradient of the
+        :class:`Function` at the given :class:`Point`.
+
+        Args:
+            point (:class:`Point`): Any :class:`Point`.
+
+        Returns:
+            :class:`Point`: The gradient of the :class:`Function` at the
+            given :class:`Point`.
+        """
         triplet = self.generate_triplet(point)
         return triplet.gradient
 
     def subgradient(self, point: pt.Point) -> pt.Point:
+        """
+        Returns a :class:`Point` object that is the subgradient of the
+        :class:`Function` at the given :class:`Point`.
+
+        Args:
+            point (:class:`Point`): Any :class:`Point`.
+
+        Returns:
+            :class:`Point`: The subgradient of the :class:`Function` at the
+            given :class:`Point`.
+
+        Note:
+            The method `gradient` is exactly the same.
+        """
         triplet = self.generate_triplet(point)
         return triplet.gradient
 
     def function_value(self, point: pt.Point) -> sc.Scalar:
+        """
+        Returns a :class:`Scalar` object that is the function value of the
+        :class:`Function` at the given :class:`Point`.
+
+        Args:
+            point (:class:`Point`): Any :class:`Point`.
+
+        Returns:
+            :class:`Point`: The function value of the :class:`Function` at the
+            given :class:`Point`.
+        """
         triplet = self.generate_triplet(point)
         return triplet.function_value
 
@@ -247,7 +340,8 @@ class Function:
         return self.function_value(point)
 
     def __add__(self, other):
-        assert isinstance(other, Function)
+        if not isinstance(other, Function):
+            return NotImplemented
         return Function(
             is_basis=False,
             composition=AddedFunc(self, other),
@@ -255,7 +349,8 @@ class Function:
         )
 
     def __sub__(self, other):
-        assert isinstance(other, Function)
+        if not isinstance(other, Function):
+            return NotImplemented
         tag_other = other.tag
         if isinstance(other.composition, AddedFunc):
             tag_other = f"({other.tag})"
@@ -266,7 +361,8 @@ class Function:
         )
 
     def __mul__(self, other):
-        assert utils.is_numerical(other)
+        if not utils.is_numerical(other):
+            return NotImplemented
         tag_self = self.tag
         if isinstance(self.composition, AddedFunc):
             tag_self = f"({self.tag})"
@@ -277,7 +373,8 @@ class Function:
         )
 
     def __rmul__(self, other):
-        assert utils.is_numerical(other)
+        if not utils.is_numerical(other):
+            return NotImplemented
         tag_self = self.tag
         if isinstance(self.composition, AddedFunc):
             tag_self = f"({self.tag})"
@@ -298,7 +395,8 @@ class Function:
         )
 
     def __truediv__(self, other):
-        assert utils.is_numerical(other)
+        if not utils.is_numerical(other):
+            return NotImplemented
         tag_self = self.tag
         if isinstance(self.composition, AddedFunc):
             tag_self = f"({self.tag})"
@@ -318,6 +416,22 @@ class Function:
 
 
 class ConvexFunction(Function):
+    """
+    The :class:`ConvexFunction` class is a child of :class:`Function.`
+    The :class:`ConvexFunction` class represents a closed, convex, and
+    proper (CCP) function, i.e., a convex function whose epigraph is a
+    non-empty closed set.
+
+    A CCP function typically has no parameters. We can instantiate a
+    :class:`ConvexFunction` object as follows:
+
+    Example:
+        >>> import pepflow as pf
+        >>> ctx = pf.PEPContext("example").set_as_current()
+        >>> pep_builder = pf.PEPBuilder()
+        >>> g = pep_builder.declare_func(pf.ConvexFunction, "g")
+    """
+
     def __init__(
         self,
         is_basis=True,
@@ -365,7 +479,16 @@ class ConvexFunction(Function):
     def interpolate_ineq(
         self, p1_tag: str, p2_tag: str, pep_context: pc.PEPContext | None = None
     ) -> sc.Scalar:
-        """Generate the interpolation inequality scalar by tags."""
+        """Generate the interpolation inequality :class:`Scalar` by tags.
+        The interpolation inequality between two points :math:`p_1, p_2` for a
+        CCP function :math:`f` is
+
+        .. math:: f(p_2) - f(p_1) + \\langle \\nabla f(p_2), p_1 - p_2 \\rangle.
+
+        Args:
+            p1_tag (str): A tag of the :class:`Point` :math:`p_1`.
+            p2_tag (str): A tag of the :class:`Point` :math:`p_2`.
+        """
         if pep_context is None:
             pep_context = pc.get_current_context()
         if pep_context is None:
@@ -379,6 +502,29 @@ class ConvexFunction(Function):
         return f2 - f1 + g2 * (x1 - x2)
 
     def proximal_step(self, x_0: pt.Point, stepsize: numbers.Number) -> pt.Point:
+        """ Define the proximal operator as
+
+        .. math:: \\text{prox}_{\\gamma f}(x_0) := \\arg\\min_x \\left\\{ \\gamma f(x) + \\frac{1}{2} \\|x - x_0\\|^2 \\right\\}.
+
+        This function performs a proximal step with respect to some
+        :class:`Function` :math:`f` on the :class:`Point` :math:`x_0`
+        with stepsize :math:`\\gamma`: 
+
+        .. math::
+            :nowrap:
+
+            \\begin{eqnarray}
+                x := \\text{prox}_{\\gamma f}(x_0) & := & \\arg\\min_x \\left\\{ \\gamma f(x) + \\frac{1}{2} \\|x - x_0\\|^2 \\right\\}, \\\\
+                & \\Updownarrow & \\\\
+                0 & = & \\gamma \\partial f(x) + x - x_0,\\\\
+                & \\Updownarrow & \\\\
+                x & = & x_0 - \\gamma \\widetilde{\\nabla} f(x) \\text{ where } \\widetilde{\\nabla} f(x)\\in\\partial f(x).
+            \\end{eqnarray}
+
+        Args:
+            x_0 (:class:`Point`): The initial point.
+            stepsize (int | float): The stepsize.
+        """
         gradient = pt.Point(is_basis=True)
         gradient.add_tag(
             f"gradient_{self.tag}(prox_{{{stepsize}*{self.tag}}}({x_0.tag}))"
@@ -398,6 +544,21 @@ class ConvexFunction(Function):
 
 
 class SmoothConvexFunction(Function):
+    """
+    The :class:`SmoothConvexFunction` class is a child of :class:`Function.`
+    The :class:`SmoothConvexFunction` class represents a smooth,
+    convex function.
+
+    A smooth, convex function has a smoothness parameter :math:`L`.
+    We can instantiate a :class:`SmoothConvexFunction` object as follows:
+
+    Example:
+        >>> import pepflow as pf
+        >>> ctx = pf.PEPContext("example").set_as_current()
+        >>> pep_builder = pf.PEPBuilder()
+        >>> f = pep_builder.declare_func(pf.SmoothConvexFunction, "f", L=1)
+    """
+
     def __init__(
         self,
         L,
@@ -445,7 +606,16 @@ class SmoothConvexFunction(Function):
     def interpolate_ineq(
         self, p1_tag: str, p2_tag: str, pep_context: pc.PEPContext | None = None
     ) -> sc.Scalar:
-        """Generate the interpolation inequality scalar by tags."""
+        """Generate the interpolation inequality :class:`Scalar` by tags.
+        The interpolation inequality between two points :math:`p_1, p_2` for a
+        smooth, convex function :math:`f` is
+
+        .. math:: f(p_2) - f(p_1) + \\langle \\nabla f(p_2), p_1 - p_2 \\rangle + \\tfrac{1}{2} \\lVert \\nabla f(p_1) - \\nabla f(p_2) \\rVert^2.
+
+        Args:
+            p1_tag (str): A tag of the :class:`Point` :math:`p_1`.
+            p2_tag (str): A tag of the :class:`Point` :math:`p_2`.
+        """
         if pep_context is None:
             pep_context = pc.get_current_context()
         if pep_context is None:

pepflow/parameter.py

@@ -0,0 +1,187 @@
+# Copyright: 2025 The PEPFlow Developers
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+from __future__ import annotations
+
+import attrs
+
+from pepflow import utils
+
+# Sentile of no found of resolving parameters
+NOT_FOUND = "__NOT_FOUND__"
+
+
+@attrs.frozen
+class ParameterRepresentation:
+    op: utils.Op
+    left_param: utils.NUMERICAL_TYPE | Parameter
+    right_param: utils.NUMERICAL_TYPE | Parameter
+
+
+def eval_parameter(
+    param: Parameter | utils.NUMERICAL_TYPE,
+    resolve_parameters: dict[str, utils.NUMERICAL_TYPE],
+) -> utils.NUMERICAL_TYPE:
+    if isinstance(param, Parameter):
+        return param.get_value(resolve_parameters)
+    if utils.is_numerical(param):
+        return param
+    raise ValueError(f"Encounter the unknown parameter type: {param} ({type(param)})")
+
+
+@attrs.frozen
+class Parameter:
+    # If name is None, it is a composite parameter.
+    name: str | None
+
+    eval_expression: ParameterRepresentation | None = None
+
+    def __attrs_post_init__(self):
+        if self.name is None and self.eval_expression is None:
+            raise ValueError(
+                "For a parameter, must specify a name or an eval_expression"
+            )
+        if self.name is None or self.eval_expression is None:
+            return
+
+        raise ValueError(
+            "For a parameter, only one of name or eval_expression should be None."
+        )
+
+    def __repr__(self):
+        if self.eval_expression is None:
+            return self.name
+
+        op = self.eval_expression.op
+        left_param = self.eval_expression.left_param
+        right_param = self.eval_expression.right_param
+        # TODO having a better parentheses handling.
+        if op == utils.Op.ADD:
+            return f"({left_param}+{right_param})"
+        if op == utils.Op.SUB:
+            return f"({left_param}-{right_param})"
+        if op == utils.Op.MUL:
+            return f"({left_param}*{right_param})"
+        if op == utils.Op.DIV:
+            return f"({left_param}/{right_param})"
+
+    def get_value(
+        self, resolve_parameters: dict[str, utils.NUMERICAL_TYPE]
+    ) -> utils.NUMERICAL_TYPE:
+        if self.eval_expression is None:
+            val = resolve_parameters.get(self.name, NOT_FOUND)
+            if val is NOT_FOUND:
+                raise ValueError(f"Cannot resolve Parameter named: {self.name}")
+            return val
+        op = self.eval_expression.op
+        left_param = eval_parameter(self.eval_expression.left_param, resolve_parameters)
+        right_param = eval_parameter(
+            self.eval_expression.right_param, resolve_parameters
+        )
+
+        if op == utils.Op.ADD:
+            return left_param + right_param
+        if op == utils.Op.SUB:
+            return left_param - right_param
+        if op == utils.Op.MUL:
+            return left_param * right_param
+        if op == utils.Op.DIV:
+            return left_param / right_param
+
+        raise ValueError(f"Encountered unknown {op=} when evaluation the point.")
+
+    def __add__(self, other):
+        if not utils.is_numerical_or_parameter(other):
+            return NotImplemented
+        return Parameter(
+            name=None,
+            eval_expression=ParameterRepresentation(
+                op=utils.Op.ADD, left_param=self, right_param=other
+            ),
+        )
+
+    def __radd__(self, other):
+        if not utils.is_numerical_or_parameter(other):
+            return NotImplemented
+        return Parameter(
+            name=None,
+            eval_expression=ParameterRepresentation(
+                op=utils.Op.ADD, left_param=other, right_param=self
+            ),
+        )
+
+    def __sub__(self, other):
+        if not utils.is_numerical_or_parameter(other):
+            return NotImplemented
+        return Parameter(
+            name=None,
+            eval_expression=ParameterRepresentation(
+                op=utils.Op.SUB, left_param=self, right_param=other
+            ),
+        )
+
+    def __rsub__(self, other):
+        if not utils.is_numerical_or_parameter(other):
+            return NotImplemented
+        return Parameter(
+            name=None,
+            eval_expression=ParameterRepresentation(
+                op=utils.Op.SUB, left_param=other, right_param=self
+            ),
+        )
+
+    def __mul__(self, other):
+        if not utils.is_numerical_or_parameter(other):
+            return NotImplemented
+        return Parameter(
+            name=None,
+            eval_expression=ParameterRepresentation(
+                op=utils.Op.MUL, left_param=self, right_param=other
+            ),
+        )
+
+    def __rmul__(self, other):
+        if not utils.is_numerical_or_parameter(other):
+            return NotImplemented
+        return Parameter(
+            name=None,
+            eval_expression=ParameterRepresentation(
+                op=utils.Op.MUL, left_param=other, right_param=self
+            ),
+        )
+
+    def __truediv__(self, other):
+        if not utils.is_numerical_or_parameter(other):
+            return NotImplemented
+        return Parameter(
+            name=None,
+            eval_expression=ParameterRepresentation(
+                op=utils.Op.DIV, left_param=self, right_param=other
+            ),
+        )
+
+    def __rtruediv__(self, other):
+        if not utils.is_numerical_or_parameter(other):
+            return NotImplemented
+        return Parameter(
+            name=None,
+            eval_expression=ParameterRepresentation(
+                op=utils.Op.DIV, left_param=other, right_param=self
+            ),
+        )

pepflow/parameter_test.py

@@ -0,0 +1,128 @@
+# Copyright: 2025 The PEPFlow Developers
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+from typing import Iterator
+
+import numpy as np
+import pytest
+import sympy as sp
+
+from pepflow import pep_context as pc
+from pepflow.expression_manager import ExpressionManager
+from pepflow.parameter import Parameter
+from pepflow.point import Point
+from pepflow.scalar import Scalar
+
+
+@pytest.fixture
+def pep_context() -> Iterator[pc.PEPContext]:
+    """Prepare the pep context and reset the context to None at the end."""
+    ctx = pc.PEPContext("test").set_as_current()
+    yield ctx
+    pc.set_current_context(None)
+
+
+def test_parameter_interact_with_scalar(pep_context: pc.PEPContext):
+    pm1 = Parameter("pm1")
+    s1 = Scalar(is_basis=True, tags=["s1"])
+
+    _ = pm1 + s1
+    _ = s1 + pm1
+    _ = pm1 - s1
+    _ = s1 - pm1
+    _ = s1 * pm1
+    _ = pm1 * s1
+    _ = s1 / pm1
+
+
+def test_parameter_interact_with_point(pep_context: pc.PEPContext):
+    pm1 = Parameter("pm1")
+    p1 = Point(is_basis=True, tags=["p1"])
+
+    _ = p1 * pm1
+    _ = pm1 * p1
+    _ = p1 / pm1
+
+
+def test_parameter_composition_with_point_and_scalar(pep_context: pc.PEPContext):
+    pm1 = Parameter("pm1")
+    pm2 = Parameter("pm2")
+    p1 = Point(is_basis=True, tags=["p1"])
+    s1 = Scalar(is_basis=True, tags=["s1"])
+
+    s2 = s1 + pm1 + pm2 * p1**2
+    assert str(s2) == "s1+pm1+pm2*|p1|^2"
+
+
+def test_parameter_composition(pep_context: pc.PEPContext):
+    pm1 = Parameter("pm1")
+    pm2 = Parameter("pm2")
+
+    pp = (pm1 + 2) * pm2
+    assert str(pp) == "((pm1+2)*pm2)"
+    assert pp.get_value({"pm1": 3, "pm2": 6}) == 30
+
+    pp2 = (pm1 + sp.Rational(1, 2)) * pm2
+    assert str(pp2) == "((pm1+1/2)*pm2)"
+    assert pp2.get_value({"pm1": sp.Rational(1, 3), "pm2": sp.Rational(6, 5)}) == 1
+
+
+def test_expression_manager_eval_with_parameter(pep_context: pc.PEPContext):
+    pm1 = Parameter("pm1")
+    p1 = Point(is_basis=True, tags=["p1"])
+    p2 = Point(is_basis=True, tags=["p2"])
+    p3 = pm1 * p1 + p2 / 4
+
+    em = ExpressionManager(pep_context, {"pm1": 2.3})
+    np.testing.assert_allclose(em.eval_point(p3).vector, np.array([2.3, 0.25]))
+
+    em = ExpressionManager(pep_context, {"pm1": 3.4})
+    np.testing.assert_allclose(em.eval_point(p3).vector, np.array([3.4, 0.25]))
+
+
+def test_expression_manager_eval_with_parameter_scalar(pep_context: pc.PEPContext):
+    pm1 = Parameter("pm1")
+    pm2 = Parameter("pm2")
+    p1 = Point(is_basis=True, tags=["p1"])
+    p2 = Point(is_basis=True, tags=["p2"])
+    s1 = Scalar(is_basis=True, tags=["s1"])
+    s2 = pm1 * p1 * p2 + pm2 + s1
+
+    em = ExpressionManager(pep_context, {"pm1": 2.4, "pm2": 4.3})
+    assert np.isclose(em.eval_scalar(s2).constant, 4.3)
+    np.testing.assert_allclose(em.eval_scalar(s2).vector, np.array([1]))
+    np.testing.assert_allclose(
+        em.eval_scalar(s2).matrix, np.array([[0, 1.2], [1.2, 0]])
+    )
+
+
+def test_expression_manager_eval_composition(pep_context: pc.PEPContext):
+    pm1 = Parameter("pm1")
+    pm2 = Parameter("pm2")
+    p1 = Point(is_basis=True, tags=["p1"])
+    p2 = Point(is_basis=True, tags=["p2"])
+    s1 = Scalar(is_basis=True, tags=["s1"])
+
+    s2 = 1 / pm1 * p1 * p2 + (pm2 + 1) * s1
+    em = ExpressionManager(pep_context, {"pm1": 0.5, "pm2": 4.3})
+    assert np.isclose(em.eval_scalar(s2).constant, 0)
+    np.testing.assert_allclose(em.eval_scalar(s2).vector, np.array([5.3]))
+    np.testing.assert_allclose(
+        em.eval_scalar(s2).matrix, np.array([[0, 1.0], [1.0, 0]])
+    )