pepflow 0.1.4a1__tar.gz → 0.1.5__tar.gz

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

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: pepflow
-Version: 0.1.4a1
+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,14 +46,18 @@ 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.
@@ -62,13 +67,9 @@ 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
+scripts/build_doc.sh [--serve-only]
 ```
-
+The argument `--serve-only` is optional for hosting the website locally.
 
 
 

{pepflow-0.1.4a1 → 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,14 +24,18 @@ 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.
@@ -40,13 +45,9 @@ 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
+scripts/build_doc.sh [--serve-only]
 ```
-
+The argument `--serve-only` is optional for hosting the website locally.
 
 
 

{pepflow-0.1.4a1 → 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
@@ -43,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.4a1 → pepflow-0.1.5}/pepflow/e2e_test.py

@@ -1,6 +1,8 @@
 import math
 
-from pepflow import function, pep
+from pepflow import function
+from pepflow import parameter as pm
+from pepflow import pep
 from pepflow import pep_context as pc
 
 
@@ -28,10 +30,47 @@ def test_gd_e2e():
         pep_builder.set_performance_metric(
             f.function_value(p) - f.function_value(x_star)
         )
-        result = pep_builder.solve()
+        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()
@@ -64,6 +103,11 @@ def test_pgm_e2e():
             h.function_value(p) - h.function_value(x_star)
         )
 
-        result = pep_builder.solve()
+        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
+        )