pepflow 0.1.4__tar.gz → 0.1.5__tar.gz

{pepflow-0.1.4 → pepflow-0.1.5}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: pepflow
-Version: 0.1.4
+Version: 0.1.5
 Summary: PEPFlow: A framework for Performance Estimation Problem (PEP) Workflow
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: attrs>=25.3.0
@@ -37,6 +37,7 @@ uv sync; source .venv/bin/activate;
 
 In windows, use `.venv\Scripts\activate` instead.
 
+### Lint & Testing
 We use `ruff` to do the format and lint and `isort` to do the import ordering.
 
 ```bash
@@ -45,12 +46,30 @@ ruff check .;
 isort .;
 ```
 
-### Testing
-
 We use `pytest` framework to do the test. To run all unit tests, run the following command:
 
-```python
+```bash
 pytest -s -vv pepflow
 ```
 
+We have a convenient script to above
+```bash
+scripts/check.sh [format|lint|typecheck|test]
+```
+See the script for the options.
+
+### 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
+scripts/build_doc.sh [--serve-only]
+```
+The argument `--serve-only` is optional for hosting the website locally.
+
+
 

{pepflow-0.1.4 → pepflow-0.1.5}/README.md

@@ -15,6 +15,7 @@ uv sync; source .venv/bin/activate;
 
 In windows, use `.venv\Scripts\activate` instead.
 
+### Lint & Testing
 We use `ruff` to do the format and lint and `isort` to do the import ordering.
 
 ```bash
@@ -23,12 +24,30 @@ ruff check .;
 isort .;
 ```
 
-### Testing
-
 We use `pytest` framework to do the test. To run all unit tests, run the following command:
 
-```python
+```bash
 pytest -s -vv pepflow
 ```
 
+We have a convenient script to above
+```bash
+scripts/check.sh [format|lint|typecheck|test]
+```
+See the script for the options.
+
+### 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
+scripts/build_doc.sh [--serve-only]
+```
+The argument `--serve-only` is optional for hosting the website locally.
+
+
 

{pepflow-0.1.4 → pepflow-0.1.5}/pepflow/__init__.py

@@ -21,6 +21,7 @@
 from .constants import PSD_CONSTRAINT as PSD_CONSTRAINT
 from .constraint import Constraint as Constraint
 from .expression_manager import ExpressionManager as ExpressionManager
+from .expression_manager import represent_matrix_by_basis as represent_matrix_by_basis
 
 # interactive_constraint
 from .interactive_constraint import launch as launch
@@ -28,6 +29,7 @@ from .interactive_constraint import launch as launch
 # pep
 from .pep import PEPBuilder as PEPBuilder
 from .pep import PEPResult as PEPResult
+from .pep import DualPEPResult as DualPEPResult
 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
@@ -35,6 +37,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
@@ -42,8 +45,10 @@ from .scalar import EvaluatedScalar as EvaluatedScalar
 from .scalar import Scalar as Scalar
 
 # Solver
-from .solver import CVXSolver as CVXSolver
+from .solver import CVXPrimalSolver as CVXPrimalSolver
+from .solver import CVXDualSolver as CVXDualSolver
 from .solver import DualVariableManager as DualVariableManager
+from .solver import PrimalVariableManager as PrimalVariableManager
 
 # Others
 from .utils import SOP as SOP

pepflow-0.1.5/pepflow/constraint.py

@@ -0,0 +1,95 @@
+# 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
+
+import attrs
+
+if TYPE_CHECKING:
+    from pepflow.point import Scalar
+
+from pepflow import utils
+
+
+@attrs.frozen
+class Constraint:
+    """A :class:`Constraint` object that represents inequalities and
+    equalities of :class:`Scalar` objects.
+
+    Denote an arbitrary :class:`Scalar` object as `x`. Constraints represent:
+    `x <= 0`, `x >= 0`, and `x = 0`.
+
+    Attributes:
+        scalar (:class:`Scalar`): The :class:`Scalar` object involved in
+            the inequality or equality.
+        comparator (:class:`Comparator`): :class:`Comparator` is an enumeration
+            that can be either `GT`, `LT`, or `EQ`. They represent `>=`, `<=`,
+            and `=` respectively.
+        name (str): The unique name of the :class:`Comparator` object.
+        associated_dual_var_constraints (list[tuple[utils.Comparator, float]]):
+            A list of all the constraints imposed on the associated dual
+            variable of this :class:`Constraint` object.
+    """
+
+    scalar: Scalar | float
+    comparator: utils.Comparator
+    name: str
+
+    # Used to represent the constraint on primal variable in dual PEP.
+    associated_dual_var_constraints: list[tuple[utils.Comparator, float]] = attrs.field(
+        factory=list
+    )
+
+    def dual_lt(self, val: float) -> None:
+        """
+        Denote the associated dual variable of this constraint as `lambd`.
+        This generates a relation of the form `lambd <= val`.
+
+        Args:
+            val (float): The other object in the relation.
+        """
+        if not utils.is_numerical(val):
+            raise ValueError(f"The input {val=} must be a numerical value")
+        self.associated_dual_var_constraints.append((utils.Comparator.LT, val))
+
+    def dual_gt(self, val: float) -> None:
+        """
+        Denote the associated dual variable of this constraint as `lambd`.
+        This generates a relation of the form `lambd >= val`.
+
+        Args:
+            val (float): The other object in the relation.
+        """
+        if not utils.is_numerical(val):
+            raise ValueError(f"The input {val=} must be a numerical value")
+        self.associated_dual_var_constraints.append((utils.Comparator.GT, val))
+
+    def dual_eq(self, val: float) -> None:
+        """
+        Denote the associated dual variable of this constraint as `lambd`.
+        This generates a relation of the form `lambd = val`.
+
+        Args:
+            val (float): The other object in the relation.
+        """
+        if not utils.is_numerical(val):
+            raise ValueError(f"The input {val=} must be a numerical value")
+        self.associated_dual_var_constraint.append((utils.Comparator.EQ, val))

pepflow-0.1.5/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.5/pepflow/e2e_test.py

@@ -0,0 +1,113 @@
+import math
+
+from pepflow import function
+from pepflow import parameter as pm
+from pepflow import 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_primal()
+        expected_opt_value = 1 / (4 * i + 2)
+        assert math.isclose(result.primal_opt_value, expected_opt_value, rel_tol=1e-3)
+
+        dual_result = pep_builder.solve_dual()
+        assert math.isclose(
+            dual_result.dual_opt_value, expected_opt_value, rel_tol=1e-3
+        )
+
+
+def test_gd_diff_stepsize_e2e():
+    pc.PEPContext("gd").set_as_current()
+    pep_builder = pep.PEPBuilder()
+    eta = 1 / pm.Parameter(name="L")
+    N = 4
+
+    f = pep_builder.declare_func(
+        function.SmoothConvexFunction, "f", L=pm.Parameter(name="L")
+    )
+    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}")
+    pep_builder.set_performance_metric(f(x) - f(x_star))
+
+    for l_val in [1, 4, 0.25]:
+        result = pep_builder.solve_primal(resolve_parameters={"L": l_val})
+        expected_opt_value = l_val / (4 * N + 2)
+        assert math.isclose(result.primal_opt_value, expected_opt_value, rel_tol=1e-3)
+
+        dual_result = pep_builder.solve_dual(resolve_parameters={"L": l_val})
+        assert math.isclose(
+            dual_result.dual_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_primal()
+        expected_opt_value = 1 / (4 * i)
+        assert math.isclose(result.primal_opt_value, expected_opt_value, rel_tol=1e-3)
+
+        dual_result = pep_builder.solve_dual()
+        assert math.isclose(
+            dual_result.dual_opt_value, expected_opt_value, rel_tol=1e-3
+        )