pepflow 0.1.0__py3-none-any.whl → 0.1.3a1__py3-none-any.whl

pepflow/__init__.py

@@ -0,0 +1,50 @@
+# 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.
+
+# isort: skip_file
+from .constants import PSD_CONSTRAINT as PSD_CONSTRAINT
+from .constraint import Constraint as Constraint
+from .expression_manager import ExpressionManager as ExpressionManager
+
+# interactive_constraint
+from .interactive_constraint import launch as launch
+
+# pep
+from .pep import PEPBuilder as PEPBuilder
+from .pep import PEPResult as PEPResult
+from .pep_context import PEPContext as PEPContext
+from .pep_context import get_current_context as get_current_context
+from .pep_context import set_current_context as set_current_context
+
+# Function, Point, Scalar
+from .function import Function as Function
+from .function import SmoothConvexFunction as SmoothConvexFunction
+from .function import Triplet as Triplet
+from .point import EvaluatedPoint as EvaluatedPoint
+from .point import Point as Point
+from .scalar import EvaluatedScalar as EvaluatedScalar
+from .scalar import Scalar as Scalar
+
+# Solver
+from .solver import CVXSolver as CVXSolver
+from .solver import DualVariableManager as DualVariableManager
+
+# Others
+from .utils import SOP as SOP
+from .utils import SOP_self as SOP_self

pepflow/constants.py

@@ -0,0 +1,20 @@
+# 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.
+
+PSD_CONSTRAINT = "PSD of Grammian Matrix"

pepflow/constraint.py

@@ -1,3 +1,22 @@
+# 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
 
 from typing import TYPE_CHECKING

pepflow/expression_manager.py

@@ -1,3 +1,22 @@
+# 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.
+
 import functools
 
 import numpy as np

pepflow/function.py

@@ -1,140 +1,303 @@
+# 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 uuid
 
 import attrs
 
+from pepflow import pep_context as pc
 from pepflow import point as pt
 from pepflow import scalar as sc
 from pepflow import utils
 
 
+@attrs.frozen
+class Triplet:
+    point: pt.Point
+    function_value: sc.Scalar
+    gradient: pt.Point
+    name: str | None
+    uid: uuid.UUID = attrs.field(factory=uuid.uuid4, init=False)
+
+
+@attrs.frozen
+class AddedFunc:
+    """Represents left_func + right_func."""
+
+    left_func: Function
+    right_func: Function
+
+
+@attrs.frozen
+class ScaledFunc:
+    """Represents scale * base_func."""
+
+    scale: float
+    base_func: Function
+
+
+@attrs.mutable
 class Function:
-    def __init__(
-        self,
-        is_basis: bool,
-        reuse_gradient: bool,
-        composition: dict | None = None,
-        tag: str | None = None,
-    ):
-        self.is_basis = is_basis
-        self.reuse_gradient = reuse_gradient
-        self.tag = tag
-        self.uid = attrs.field(factory=uuid.uuid4, init=False)
-        self.triplets = []  #: list[("point", "scalar", "point")] = []
-        self.constraints = []  #: list["constraint"] = []
-
-        if is_basis:
-            assert composition is None
-            self.composition = {self: 1}
+    is_basis: bool
+    reuse_gradient: bool
+
+    composition: AddedFunc | ScaledFunc | None = None
+
+    # Human tagged value for the function
+    tags: list[str] = attrs.field(factory=list)
+
+    # Generate an automatic id
+    uid: uuid.UUID = attrs.field(factory=uuid.uuid4, init=False)
+
+    def __attrs_post_init__(self):
+        if self.is_basis:
+            assert self.composition is None
         else:
-            assert isinstance(composition, dict)
-            self.composition = composition  #: dict[{"function": float})] = []
+            assert self.composition is not None
+
+    @property
+    def tag(self):
+        if len(self.tags) == 0:
+            raise ValueError("Function should have a name.")
+        return self.tags[-1]
 
     def add_tag(self, tag: str) -> None:
-        self.tag = tag
-        return None
+        self.tags.append(tag)
+
+    def __repr__(self):
+        if self.tags:
+            return self.tag
+        return super().__repr__()
 
     def get_interpolation_constraints(self):
         raise NotImplementedError(
             "This method should be implemented in the children class."
         )
 
-    def add_triplet(self, triplet: tuple) -> None:
-        return NotImplemented
+    def add_triplet_to_func(self, triplet: Triplet) -> None:
+        pep_context = pc.get_current_context()
+        if pep_context is None:
+            raise RuntimeError("Did you forget to create a context?")
+        pep_context.triplets[self].append(triplet)
+
+    def add_point_with_grad_restriction(
+        self, point: pt.Point, desired_grad: pt.Point
+    ) -> Triplet:
+        # todo find a better tagging approach.
+        if self.is_basis:
+            function_value = sc.Scalar(is_basis=True)
+            function_value.add_tag(f"{self.tag}({point.tag})")
+            triplet = Triplet(
+                point,
+                function_value,
+                desired_grad,
+                name=f"{point.tag}_{function_value.tag}_{desired_grad.tag}",
+            )
+            self.add_triplet_to_func(triplet)
+        else:
+            if isinstance(self.composition, AddedFunc):
+                left_triplet = self.composition.left_func.generate_triplet(point)
+                next_desired_grad = desired_grad - left_triplet.gradient
+                next_desired_grad.add_tag(
+                    f"gradient_{self.composition.right_func.tag}({point.tag})"
+                )
+                right_triplet = (
+                    self.composition.right_func.add_point_with_grad_restriction(
+                        point, next_desired_grad
+                    )
+                )
+                triplet = Triplet(
+                    point,
+                    left_triplet.function_value + right_triplet.function_value,
+                    desired_grad,
+                    name=f"{point.tag}_{self.tag}_{desired_grad.tag}",
+                )
+            elif isinstance(self.composition, ScaledFunc):
+                next_desired_grad = desired_grad / self.composition.scale
+                next_desired_grad.add_tag(
+                    f"gradient_{self.composition.base_func.tag}({point.tag})"
+                )
+                base_triplet = (
+                    self.composition.base_func.add_point_with_grad_restriction(
+                        point, next_desired_grad
+                    )
+                )
+                triplet = Triplet(
+                    point,
+                    base_triplet.function_value * self.composition.scale,
+                    desired_grad,
+                    name=f"{point.tag}_{self.tag}_{desired_grad.tag}",
+                )
+            else:
+                raise ValueError(
+                    f"Unknown composition of functions: {self.composition}"
+                )
+        return triplet
 
-    def add_stationary_point(self) -> pt.Point:
+    def add_stationary_point(self, name: str) -> pt.Point:
+        # assert we can only add one stationary point?
         point = pt.Point(is_basis=True)
-        _, _, grad = self.generate_triplet(point)
-        self.constraints.append(
-            (grad**2).eq(0, name=str(self.__hash__) + " stationary point")
-        )
+        point.add_tag(name)
+        desired_grad = 0 * point
+        desired_grad.add_tag(f"gradient_{self.tag}({name})")
+        self.add_point_with_grad_restriction(point, desired_grad)
         return point
 
-    def generate_triplet(self, point: pt.Point) -> tuple:
-        func_value = 0
-        grad = 0
+        # The following the old gradient(opt) =  0 constraint style.
+        # It is mathamatically correct but hard for solver so we abandon it.
+        #
+        # triplet = self.generate_triplet(point)
+        # pep_context = pc.get_current_context()
+        # pep_context.add_opt_condition(
+        #     self,
+        #     ((triplet.gradient) ** 2).eq(
+        #         0, name=f"{self.tags[0]}({point.tags[0]}) optimality condition"
+        #     ),
+        # )
+        # return point
+
+    def generate_triplet(self, point: pt.Point) -> Triplet:
+        pep_context = pc.get_current_context()
+        if pep_context is None:
+            raise RuntimeError("Did you forget to create a context?")
 
         if self.is_basis:
             generate_new_basis = True
-            for triplet in self.triplets:
-                if triplet[0].uid == point.uid and self.reuse_gradient:
-                    func_value = triplet[1]
-                    grad = triplet[2]
+            instances_of_point = 0
+            for triplet in pep_context.triplets[self]:
+                if triplet.point.uid == point.uid:
+                    instances_of_point += 1
                     generate_new_basis = False
-                    break
-                elif triplet[0].uid == point.uid and not self.reuse_gradient:
-                    func_value = triplet[1]
-                    grad = pt.Point(is_basis=True)
-                    generate_new_basis = False
-                    self.triplets.append((point, func_value, grad))
-                    break
+                    previous_triplet = triplet
+
             if generate_new_basis:
-                func_value = sc.Scalar(is_basis=True)
-                grad = pt.Point(is_basis=True)
-                self.triplets.append((point, func_value, grad))
+                function_value = sc.Scalar(is_basis=True)
+                function_value.add_tag(f"{self.tag}({point.tag})")
+                gradient = pt.Point(is_basis=True)
+                gradient.add_tag(f"gradient_{self.tag}({point.tag})")
+
+                new_triplet = Triplet(
+                    point,
+                    function_value,
+                    gradient,
+                    name=f"{point.tag}_{function_value.tag}_{gradient.tag}",
+                )
+                self.add_triplet_to_func(new_triplet)
+            elif not generate_new_basis and self.reuse_gradient:
+                function_value = previous_triplet.function_value
+                gradient = previous_triplet.gradient
+            elif not generate_new_basis and not self.reuse_gradient:
+                function_value = previous_triplet.function_value
+                gradient = pt.Point(is_basis=True)
+                gradient.add_tag(f"gradient_{self.tag}({point.tag})")
+
+                new_triplet = Triplet(
+                    point,
+                    previous_triplet.function_value,
+                    gradient,
+                    name=f"{point.tag}_{function_value.tag}_{gradient.tag}_{instances_of_point}",
+                )
+                self.add_triplet_to_func(new_triplet)
         else:
-            for function, weights in self.composition.items():
-                _, func_value_slice, grad_slice = function.generate_triplet(point)
-                func_value += weights * func_value_slice
-                grad += weights * grad_slice
+            if isinstance(self.composition, AddedFunc):
+                left_triplet = self.composition.left_func.generate_triplet(point)
+                right_triplet = self.composition.right_func.generate_triplet(point)
+                function_value = (
+                    left_triplet.function_value + right_triplet.function_value
+                )
+                gradient = left_triplet.gradient + right_triplet.gradient
+            elif isinstance(self.composition, ScaledFunc):
+                base_triplet = self.composition.base_func.generate_triplet(point)
+                function_value = self.composition.scale * base_triplet.function_value
+                gradient = self.composition.scale * base_triplet.gradient
+            else:
+                raise ValueError(
+                    f"Unknown composition of functions: {self.composition}"
+                )
 
-        return (point, func_value, grad)
+        return Triplet(point, function_value, gradient, name=None)
 
     def gradient(self, point: pt.Point) -> pt.Point:
-        _, _, grad = self.generate_triplet(point)
-        return grad
+        triplet = self.generate_triplet(point)
+        return triplet.gradient
 
     def subgradient(self, point: pt.Point) -> pt.Point:
-        _, _, subgrad = self.generate_triplet(point)
-        return subgrad
+        triplet = self.generate_triplet(point)
+        return triplet.gradient
 
     def function_value(self, point: pt.Point) -> sc.Scalar:
-        _, func_value, _ = self.generate_triplet(point)
-        return func_value
+        triplet = self.generate_triplet(point)
+        return triplet.function_value
 
     def __add__(self, other):
         assert isinstance(other, Function)
-        merged_composition = utils.merge_dict(self.composition, other.composition)
-        pruned_composition = utils.prune_dict(merged_composition)
         return Function(
             is_basis=False,
             reuse_gradient=self.reuse_gradient and other.reuse_gradient,
-            composition=pruned_composition,
-            tag=None,
+            composition=AddedFunc(self, other),
+            tags=[f"{self.tag}+{other.tag}"],
         )
 
     def __sub__(self, other):
-        return self.__add__(-other)
+        assert isinstance(other, Function)
+        return Function(
+            is_basis=False,
+            reuse_gradient=self.reuse_gradient and other.reuse_gradient,
+            composition=AddedFunc(self, -other),
+            tags=[f"{self.tag}-{other.tag}"],
+        )
 
     def __mul__(self, other):
-        return self.__rmul__(other=other)
+        assert utils.is_numerical(other)
+        return Function(
+            is_basis=False,
+            reuse_gradient=self.reuse_gradient,
+            composition=ScaledFunc(scale=other, base_func=self),
+            tags=[f"{other:.4g}*{self.tag}"],
+        )
 
     def __rmul__(self, other):
         assert utils.is_numerical(other)
-        scaled_composition = dict()
-        for key, value in self.composition.items():
-            scaled_composition[key] = value * other
-        pruned_composition = utils.prune_dict(scaled_composition)
         return Function(
             is_basis=False,
             reuse_gradient=self.reuse_gradient,
-            composition=pruned_composition,
-            tag=None,
+            composition=ScaledFunc(scale=other, base_func=self),
+            tags=[f"{other:.4g}*{self.tag}"],
         )
 
     def __neg__(self):
-        return self.__mul__(other=-1)
+        return Function(
+            is_basis=False,
+            reuse_gradient=self.reuse_gradient,
+            composition=ScaledFunc(scale=-1, base_func=self),
+            tags=[f"-{self.tag}"],
+        )
 
     def __truediv__(self, other):
         assert utils.is_numerical(other)
-        scaled_composition = dict()
-        for key, value in self.composition.items():
-            scaled_composition[key] = value / other
-        pruned_composition = utils.prune_dict(scaled_composition)
         return Function(
             is_basis=False,
             reuse_gradient=self.reuse_gradient,
-            composition=pruned_composition,
-            tag=None,
+            composition=ScaledFunc(scale=1 / other, base_func=self),
+            tags=[f"1/{other:.4g}*{self.tag}"],
         )
 
     def __hash__(self):
@@ -154,30 +317,50 @@ class SmoothConvexFunction(Function):
         self.L = L
 
     def smooth_convex_interpolability_constraints(self, triplet_i, triplet_j):
-        point_i, func_value_i, grad_i = triplet_i
-        point_j, func_value_j, grad_j = triplet_j
-        func_diff = func_value_j - func_value_i
+        point_i = triplet_i.point
+        function_value_i = triplet_i.function_value
+        grad_i = triplet_i.gradient
+
+        point_j = triplet_j.point
+        function_value_j = triplet_j.function_value
+        grad_j = triplet_j.gradient
+
+        func_diff = function_value_j - function_value_i
         cross_term = grad_j * (point_i - point_j)
         quad_term = 1 / (2 * self.L) * (grad_i - grad_j) ** 2
 
         return (func_diff + cross_term + quad_term).le(
-            0,
-            name=str(self.__hash__())
-            + ":"
-            + str(point_i.__hash__())
-            + ","
-            + str(point_j.__hash__()),
+            0, name=f"{self.tag}:{point_i.tag},{point_j.tag}"
         )
 
-    def get_interpolation_constraints(self):
+    def get_interpolation_constraints(self, pep_context: pc.PEPContext | None = None):
         interpolation_constraints = []
-        for i in range(len(self.triplets)):
-            for j in range(len(self.triplets)):
+        if pep_context is None:
+            pep_context = pc.get_current_context()
+        if pep_context is None:
+            raise RuntimeError("Did you forget to create a context?")
+        for i in pep_context.triplets[self]:
+            for j in pep_context.triplets[self]:
                 if i == j:
                     continue
                 interpolation_constraints.append(
-                    self.smooth_convex_interpolability_constraints(
-                        self.triplets[i], self.triplets[j]
-                    )
+                    self.smooth_convex_interpolability_constraints(i, j)
                 )
         return interpolation_constraints
+
+    def interpolate_ineq(
+        self, p1_tag: str, p2_tag: str, pep_context: pc.PEPContext | None = None
+    ) -> pt.Scalar:
+        """Generate the interpolation inequality scalar by tags."""
+        if pep_context is None:
+            pep_context = pc.get_current_context()
+        if pep_context is None:
+            raise RuntimeError("Did you forget to specify a context?")
+        # TODO: we definitely need a more robust tag system
+        x1 = pep_context.get_by_tag(p1_tag)
+        x2 = pep_context.get_by_tag(p2_tag)
+        f1 = pep_context.get_by_tag(f"{self.tag}({p1_tag})")
+        f2 = pep_context.get_by_tag(f"{self.tag}({p2_tag})")
+        g1 = pep_context.get_by_tag(f"gradient_{self.tag}({p1_tag})")
+        g2 = pep_context.get_by_tag(f"gradient_{self.tag}({p2_tag})")
+        return f2 - f1 + g2 * (x1 - x2) + 1 / 2 * (g1 - g2) ** 2