pepflow 0.1.3a1__tar.gz → 0.1.4a1__tar.gz

{pepflow-0.1.3a1 → pepflow-0.1.4a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pepflow
-Version: 0.1.3a1
+Version: 0.1.4a1
 Summary: PEPFlow: A framework for Performance Estimation Problem (PEP) Workflow
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -53,4 +53,22 @@ We use `pytest` framework to do the test. To run all unit tests, run the followi
 pytest -s -vv pepflow
 ```
 
+### Build doc website
+
+Install the required library (one-time) and `pandoc` in order to build ipynb.
+```bash
+pip install -r docs/requirements.txt
+```
+
+To build the website, run
+```bash
+cd docs; make html
+```
+Make sure it succeeded, then examine it locally through
+```bash
+cd build/html; python -m http.server
+```
+
+
+
 

{pepflow-0.1.3a1 → pepflow-0.1.4a1}/README.md

@@ -31,4 +31,22 @@ We use `pytest` framework to do the test. To run all unit tests, run the followi
 pytest -s -vv pepflow
 ```
 
+### Build doc website
+
+Install the required library (one-time) and `pandoc` in order to build ipynb.
+```bash
+pip install -r docs/requirements.txt
+```
+
+To build the website, run
+```bash
+cd docs; make html
+```
+Make sure it succeeded, then examine it locally through
+```bash
+cd build/html; python -m http.server
+```
+
+
+
 

{pepflow-0.1.3a1 → pepflow-0.1.4a1}/pepflow/__init__.py

@@ -35,6 +35,7 @@ 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 ConvexFunction as ConvexFunction
 from .function import Triplet as Triplet
 from .point import EvaluatedPoint as EvaluatedPoint
 from .point import Point as Point

pepflow-0.1.4a1/pepflow/constraint_test.py

@@ -0,0 +1,71 @@
+# 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
+
+from pepflow import expression_manager as exm
+from pepflow import pep as pep
+from pepflow import pep_context as pc
+from pepflow import scalar, utils
+
+
+@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_constraint(pep_context: pc.PEPContext):
+    s1 = scalar.Scalar(is_basis=True, tags=["s1"])
+    s2 = scalar.Scalar(is_basis=True, tags=["s2"])
+    s3 = 2 * s1 + s2 / 4 + 5
+
+    c1 = s3.le(5, name="c1")
+    c2 = s3.lt(5, name="c2")
+    c3 = s3.ge(5, name="c3")
+    c4 = s3.gt(5, name="c4")
+    c5 = s3.eq(5, name="c5")
+
+    pm = exm.ExpressionManager(pep_context)
+
+    np.testing.assert_allclose(pm.eval_scalar(c1.scalar).vector, np.array([2, 0.25]))
+    np.testing.assert_allclose(pm.eval_scalar(c1.scalar).constant, 0)
+    assert c1.comparator == utils.Comparator.LT
+
+    np.testing.assert_allclose(pm.eval_scalar(c2.scalar).vector, np.array([2, 0.25]))
+    np.testing.assert_allclose(pm.eval_scalar(c2.scalar).constant, 0)
+    assert c2.comparator == utils.Comparator.LT
+
+    np.testing.assert_allclose(pm.eval_scalar(c3.scalar).vector, np.array([2, 0.25]))
+    np.testing.assert_allclose(pm.eval_scalar(c3.scalar).constant, 0)
+    assert c3.comparator == utils.Comparator.GT
+
+    np.testing.assert_allclose(pm.eval_scalar(c4.scalar).vector, np.array([2, 0.25]))
+    np.testing.assert_allclose(pm.eval_scalar(c4.scalar).constant, 0)
+    assert c4.comparator == utils.Comparator.GT
+
+    np.testing.assert_allclose(pm.eval_scalar(c5.scalar).vector, np.array([2, 0.25]))
+    np.testing.assert_allclose(pm.eval_scalar(c5.scalar).constant, 0)
+    assert c5.comparator == utils.Comparator.EQ

pepflow-0.1.4a1/pepflow/e2e_test.py

@@ -0,0 +1,69 @@
+import math
+
+from pepflow import function, pep
+from pepflow import pep_context as pc
+
+
+def test_gd_e2e():
+    ctx = pc.PEPContext("gd").set_as_current()
+    pep_builder = pep.PEPBuilder()
+    eta = 1
+    N = 9
+
+    f = pep_builder.declare_func(function.SmoothConvexFunction, "f", L=1)
+    x = pep_builder.set_init_point("x_0")
+    x_star = f.add_stationary_point("x_star")
+    pep_builder.set_initial_constraint(
+        ((x - x_star) ** 2).le(1, name="initial_condition")
+    )
+
+    # We first build the algorithm with the largest number of iterations.
+    for i in range(N):
+        x = x - eta * f.gradient(x)
+        x.add_tag(f"x_{i + 1}")
+
+    # To achieve the sweep, we can just update the performance_metric.
+    for i in range(1, N + 1):
+        p = ctx.get_by_tag(f"x_{i}")
+        pep_builder.set_performance_metric(
+            f.function_value(p) - f.function_value(x_star)
+        )
+        result = pep_builder.solve()
+        expected_opt_value = 1 / (4 * i + 2)
+        assert math.isclose(result.primal_opt_value, expected_opt_value, rel_tol=1e-3)
+
+
+def test_pgm_e2e():
+    ctx = pc.PEPContext("pgm").set_as_current()
+    pep_builder = pep.PEPBuilder()
+    eta = 1
+    N = 1
+
+    f = pep_builder.declare_func(function.SmoothConvexFunction, "f", L=1)
+    g = pep_builder.declare_func(function.ConvexFunction, "g")
+
+    h = f + g
+
+    x = pep_builder.set_init_point("x_0")
+    x_star = h.add_stationary_point("x_star")
+    pep_builder.set_initial_constraint(
+        ((x - x_star) ** 2).le(1, name="initial_condition")
+    )
+
+    # We first build the algorithm with the largest number of iterations.
+    for i in range(N):
+        y = x - eta * f.gradient(x)
+        y.add_tag(f"y_{i + 1}")
+        x = g.proximal_step(y, eta)
+        x.add_tag(f"x_{i + 1}")
+
+    # To achieve the sweep, we can just update the performance_metric.
+    for i in range(1, N + 1):
+        p = ctx.get_by_tag(f"x_{i}")
+        pep_builder.set_performance_metric(
+            h.function_value(p) - h.function_value(x_star)
+        )
+
+        result = pep_builder.solve()
+        expected_opt_value = 1 / (4 * i)
+        assert math.isclose(result.primal_opt_value, expected_opt_value, rel_tol=1e-3)

{pepflow-0.1.3a1 → pepflow-0.1.4a1}/pepflow/expression_manager.py

@@ -18,6 +18,7 @@
 # under the License.
 
 import functools
+import math
 
 import numpy as np
 
@@ -27,6 +28,17 @@ from pepflow import scalar as sc
 from pepflow import utils
 
 
+def tag_and_coef_to_str(tag: str, v: float) -> str:
+    coef = f"{abs(v):.3g}"
+    sign = "+" if v >= 0 else "-"
+    if math.isclose(abs(v), 1):
+        return f"{sign} {tag} "
+    elif math.isclose(v, 0):
+        return ""
+    else:
+        return f"{sign} {coef}*{tag} "
+
+
 class ExpressionManager:
     def __init__(self, pep_context: pc.PEPContext):
         self.context = pep_context
@@ -48,12 +60,18 @@ class ExpressionManager:
         self._num_basis_points = len(self._basis_points)
         self._num_basis_scalars = len(self._basis_scalars)
 
-    def get_index_of_basis_point(self, point: pt.Point):
+    def get_index_of_basis_point(self, point: pt.Point) -> int:
         return self._basis_point_uid_to_index[point.uid]
 
-    def get_index_of_basis_scalar(self, scalar: sc.Scalar):
+    def get_index_of_basis_scalar(self, scalar: sc.Scalar) -> int:
         return self._basis_scalar_uid_to_index[scalar.uid]
 
+    def get_tag_of_basis_point_index(self, index: int) -> str:
+        return self._basis_points[index].tag
+
+    def get_tag_of_basis_scalar_index(self, index: int) -> str:
+        return self._basis_scalars[index].tag
+
     @functools.cache
     def eval_point(self, point: pt.Point | float | int):
         if utils.is_numerical(point):
@@ -130,3 +148,55 @@ class ExpressionManager:
             ) / self.eval_scalar(scalar.eval_expression.right_scalar)
 
         raise ValueError("This should never happen!")
+
+    @functools.cache
+    def repr_point_by_basis(self, point: pt.Point) -> str:
+        assert isinstance(point, pt.Point)
+        repr_array = self.eval_point(point).vector
+
+        repr_str = ""
+        for i, v in enumerate(repr_array):
+            ith_tag = self.get_tag_of_basis_point_index(i)
+            repr_str += tag_and_coef_to_str(ith_tag, v)
+
+        # Post processing
+        if repr_str == "":
+            return "0"
+        if repr_str.startswith("+ "):
+            repr_str = repr_str[2:]
+        if repr_str.startswith("- "):
+            repr_str = "-" + repr_str[2:]
+        return repr_str.strip()
+
+    @functools.cache
+    def repr_scalar_by_basis(self, scalar: sc.Scalar) -> str:
+        assert isinstance(scalar, sc.Scalar)
+        evaluated_scalar = self.eval_scalar(scalar)
+
+        repr_str = ""
+        if not math.isclose(evaluated_scalar.constant, 0):
+            repr_str += f"{evaluated_scalar.constant:.3g}"
+
+        for i, v in enumerate(evaluated_scalar.vector):
+            # Note the tag is from scalar basis.
+            ith_tag = self.get_tag_of_basis_scalar_index(i)
+            repr_str += tag_and_coef_to_str(ith_tag, v)
+
+        for i in range(evaluated_scalar.matrix.shape[0]):
+            for j in range(i, evaluated_scalar.matrix.shape[0]):
+                ith_tag = self.get_tag_of_basis_point_index(i)
+                v = evaluated_scalar.matrix[i, j]
+                if i == j:
+                    repr_str += tag_and_coef_to_str(f"|{ith_tag}|^2", v)
+                    continue
+                jth_tag = self.get_tag_of_basis_point_index(j)
+                repr_str += tag_and_coef_to_str(f"<{ith_tag}, {jth_tag}>", 2 * v)
+
+        # Post processing
+        if repr_str == "":
+            return "0"
+        if repr_str.startswith("+ "):
+            repr_str = repr_str[2:]
+        if repr_str.startswith("- "):
+            repr_str = "-" + repr_str[2:]
+        return repr_str.strip()

pepflow-0.1.4a1/pepflow/expression_manager_test.py

@@ -0,0 +1,116 @@
+# 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
+
+from pepflow import expression_manager as exm
+from pepflow import function as fc
+from pepflow import pep as pep
+from pepflow import pep_context as pc
+from pepflow import point as pt
+
+
+@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_repr_point_by_basis(pep_context: pc.PEPContext) -> None:
+    x = pt.Point(is_basis=True, tags=["x_0"])
+    f = fc.Function(is_basis=True, tags=["f"])
+    L = 0.5
+    for i in range(2):
+        x = x - L * f.gradient(x)
+        x.add_tag(f"x_{i + 1}")
+
+    em = exm.ExpressionManager(pep_context)
+    np.testing.assert_allclose(em.eval_point(x).vector, [1, -0.5, -0.5])
+    assert (
+        em.repr_point_by_basis(x) == "x_0 - 0.5*gradient_f(x_0) - 0.5*gradient_f(x_1)"
+    )
+
+
+def test_repr_point_by_basis_with_zero(pep_context: pc.PEPContext) -> None:
+    x = pt.Point(is_basis=True, tags=["x_0"])
+    _ = pt.Point(is_basis=True, tags=["x_unused"])  # Add this extra point.
+    f = fc.Function(is_basis=True, tags=["f"])
+    L = 0.5
+    for i in range(2):
+        x = x - L * f.gradient(x)
+        x.add_tag(f"x_{i + 1}")
+
+    em = exm.ExpressionManager(pep_context)
+    # Note the vector representation of point is different from previous case
+    # But the string representation is still the same.
+    np.testing.assert_allclose(em.eval_point(x).vector, [1, 0, -0.5, -0.5])
+    assert (
+        em.repr_point_by_basis(x) == "x_0 - 0.5*gradient_f(x_0) - 0.5*gradient_f(x_1)"
+    )
+
+
+def test_repr_point_by_basis_heavy_ball(pep_context: pc.PEPContext) -> None:
+    x_prev = pt.Point(is_basis=True, tags=["x_{-1}"])
+    x = pt.Point(is_basis=True, tags=["x_0"])
+    f = fc.Function(is_basis=True, tags=["f"])
+
+    beta = 0.5
+    for i in range(2):
+        x_next = x - f.gradient(x) + beta * (x - x_prev)
+        x_next.add_tag(f"x_{i + 1}")
+        x_prev = x
+        x = x_next
+
+    em = exm.ExpressionManager(pep_context)
+    np.testing.assert_allclose(em.eval_point(x).vector, [-0.75, 1.75, -1.5, -1])
+    assert (
+        em.repr_point_by_basis(x)
+        == "-0.75*x_{-1} + 1.75*x_0 - 1.5*gradient_f(x_0) - gradient_f(x_1)"
+    )
+
+
+def test_repr_scalar_by_basis(pep_context: pc.PEPContext) -> None:
+    x = pt.Point(is_basis=True, tags=["x"])
+    f = fc.Function(is_basis=True, tags=["f"])
+
+    s = f(x) + x * f.gradient(x)
+    em = exm.ExpressionManager(pep_context)
+    assert em.repr_scalar_by_basis(s) == "f(x) + <x, gradient_f(x)>"
+
+
+def test_repr_scalar_by_basis_interpolation(pep_context: pc.PEPContext) -> None:
+    xi = pt.Point(is_basis=True, tags=["x_i"])
+    xj = pt.Point(is_basis=True, tags=["x_j"])
+    f = fc.SmoothConvexFunction(is_basis=True, L=1)
+    f.add_tag("f")
+    fi = f(xi)  # noqa: F841
+    fj = f(xj)  # noqa: F841
+    interp_scalar = f.interpolate_ineq("x_i", "x_j")
+    em = exm.ExpressionManager(pep_context)
+    expected_repr = "-f(x_i) + f(x_j) + <x_i, gradient_f(x_j)> - <x_j, gradient_f(x_j)> + 0.5*|gradient_f(x_i)|^2 - <gradient_f(x_i), gradient_f(x_j)> + 0.5*|gradient_f(x_j)|^2"
+    assert em.repr_scalar_by_basis(interp_scalar) == expected_repr
+
+
+# TODO add more tests about repr_scalar_by_basis