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

pepflow/solver.py

@@ -46,6 +46,14 @@ def evaled_scalar_to_cvx_express(
 
 
 class DualVariableManager:
+    """
+    A class to access the dual variables associated with the constraints
+    of the Primal PEP. Should not be instantiated directly. Automatically
+    generated as a member variable of the :class:`PEPResult` object
+    returned when calling :py:func:`pepflow.PEPBuilder.solve_primal`.
+    """
+
+    # It is used in the primal PEP to get the dual variables.
     def __init__(self, named_constraints: list[tuple[str, cvxpy.Constraint]]):
         self.named_constraints = {}
         for name, c in named_constraints:
@@ -63,6 +71,19 @@ class DualVariableManager:
         self.named_constraints[name] = constraint
 
     def dual_value(self, name: str) -> float | None:
+        """
+        Given the name of a :class:`Constraint` object that represents a
+        constraint in Primal PEP, return the value of its corresponding
+        dual variable.
+
+        Args:
+            name (str): The name of the :class:`Constraint` object whose
+                associated dual variable we want to retrieve.
+
+        Returns:
+            float: The value of the dual variable corresponding to the
+            :class:`Constraint` object associated with the `name` argument.
+        """
         if name not in self.named_constraints:
             return None  # Is this good choice?
         dual_value = self.named_constraints[name].dual_value
@@ -71,7 +92,65 @@ class DualVariableManager:
         return dual_value
 
 
-class CVXSolver:
+class PrimalVariableManager:
+    """
+    A class to access the primal variables of the Dual PEP. The primal
+    variables of the Dual PEP are the dual variables associated with the
+    constraints of the Primal PEP. Should not be instantiated directly.
+    Automatically generated as a member variable of the :class:`PEPResult`
+    object returned when calling :py:func:`pepflow.PEPBuilder.solve_dual`.
+    """
+
+    # It is used in the dual PEP to get the primal variables.
+    def __init__(self, named_variables: list[tuple[str, cvxpy.Variable]]):
+        self.named_variables = {}
+        for name, v in named_variables:
+            self.add_variable(name, v)
+
+    def cvx_variables(self) -> list[cvxpy.Variable]:
+        return list(self.named_variables.values())
+
+    def clear(self) -> None:
+        self.named_variables.clear()
+
+    def add_variable(self, name: str, variable: cvxpy.Variable) -> None:
+        if name in self.named_variables:
+            raise KeyError(f"There is already a variable named {name}")
+        self.named_variables[name] = variable
+
+    def get_variable(self, name: str) -> cvxpy.Variable:
+        if name not in self.named_variables:
+            raise KeyError(f"Cannot find a variable named {name}")
+        return self.named_variables[name]
+
+    def primal_value(self, name: str) -> float | None:
+        """
+        The primal variables of the Dual PEP are the dual variables associated
+        with the constraints of the Primal PEP.
+
+        Given the name of a :class:`Constraint` object that represents a
+        constraint in the Primal PEP, return the value of the corresponding
+        primal variable of the Dual PEP.
+
+        Args:
+            name (str): The name of the :class:`Constraint` object whose
+                corresponding primal variable of the Dual PEP we want to
+                retrieve.
+
+        Returns:
+            float: The value of the primal variable of the Dual PEP
+            corresponding to the :class:`Constraint` object associated with
+            the `name` argument.
+        """
+        if name not in self.named_variables:
+            return None  # Is this good choice?
+        primal_value = self.named_variables[name].value
+        if primal_value is None:
+            return None
+        return primal_value
+
+
+class CVXPrimalSolver:
     def __init__(
         self,
         perf_metric: sc.Scalar,
@@ -83,8 +162,10 @@ class CVXSolver:
         self.dual_var_manager = DualVariableManager([])
         self.context = context
 
-    def build_problem(self) -> cvxpy.Problem:
-        em = exm.ExpressionManager(self.context)
+    def build_problem(
+        self, resolve_parameters: dict[str, utils.NUMERICAL_TYPE] | None = None
+    ) -> cvxpy.Problem:
+        em = exm.ExpressionManager(self.context, resolve_parameters=resolve_parameters)
         f_var = cvxpy.Variable(em._num_basis_scalars)
         g_var = cvxpy.Variable(
             (em._num_basis_points, em._num_basis_points), symmetric=True
@@ -121,3 +202,89 @@ class CVXSolver:
         problem = self.build_problem()
         result = problem.solve(**kwargs)
         return result
+
+
+class CVXDualSolver:
+    def __init__(
+        self,
+        perf_metric: sc.Scalar,
+        constraints: list[ctr.Constraint],
+        context: pc.PEPContext,
+    ):
+        self.perf_metric = perf_metric
+        self.constraints = constraints
+        self.primal_var_manager = PrimalVariableManager([])
+        self.context = context
+
+    def build_problem(
+        self, resolve_parameters: dict[str, utils.NUMERICAL_TYPE] | None = None
+    ) -> cvxpy.Problem:
+        # The primal problem is always the following form:
+        #
+        # max_{F, G}:  <perf.vec, F> + Tr(G perf.Mat) + perf.const
+        # s.t.         <constraint.vec, F> + Tr(G constraint.Mat) + constraint.const <= 0
+        #              G >= 0
+        # Caveat: we use max instead of min in primal problem.
+        #
+        # Dual prob = min_{l, S} [max_{F, G} (<perf.vec, F> + Tr(G perf.Mat) - l * (constraint) + Tr(S*G))]
+        # Note the sign above.
+        # Becaus F is unbounded and the Lagrangian w.r.t. F is linear, the coefficients of F must be 0.
+        # Similarly, the Lagrangian w.r.t. G is linear and G is PSD, the coefficients of G must << 0.
+        dual_constraints = []
+        lambd_constraints = []
+        em = exm.ExpressionManager(self.context, resolve_parameters=resolve_parameters)
+        # The one corresponding to G >= 0
+        S = cvxpy.Variable((em._num_basis_points, em._num_basis_points), PSD=True)
+        evaled_perf_metric_scalar = em.eval_scalar(self.perf_metric)
+
+        extra_constraints = []
+        obj = evaled_perf_metric_scalar.constant
+        F_coef_vec = 0
+        G_coef_mat = 0
+        # l * (Tr(G*eval_s.Matrix) + <F, eval_s.vec> + eval_s.const)
+        for c in self.constraints:
+            lambd = cvxpy.Variable()
+            self.primal_var_manager.add_variable(c.name, lambd)
+            evaled_scalar = em.eval_scalar(c.scalar)
+            if c.comparator == utils.Comparator.GT:
+                sign = 1
+                lambd_constraints.append(lambd >= 0)
+            elif c.comparator == utils.Comparator.LT:
+                sign = -1  # We flip f(x) <=0  into -f(x) >= 0
+                lambd_constraints.append(lambd >= 0)
+            elif c.comparator == utils.Comparator.EQ:
+                sign = 1
+            else:
+                raise RuntimeError(
+                    f"Unknown comparator in constraint {c.anme}: get {c.comparator=}"
+                )
+            G_coef_mat += sign * lambd * evaled_scalar.matrix
+            F_coef_vec += sign * lambd * evaled_scalar.vector
+            obj += sign * lambd * evaled_scalar.constant
+
+            # We can add extra constraints to directly manipulate the primal variable in dual PEP.
+            for comparator, val in c.associated_dual_var_constraints:
+                if c.comparator == utils.Comparator.GT:
+                    extra_constraints.append(lambd >= val)
+                elif c.comparator == utils.Comparator.LT:
+                    extra_constraints.append(lambd <= val)
+                elif c.comparator == utils.Comparator.EQ:
+                    extra_constraints.append(lambd == val)
+                else:
+                    raise RuntimeError(
+                        f"Unknown comparator in constraint {c.anme} associated dual one:"
+                        f"get {c.comparator=}"
+                    )
+
+        dual_constraints.append(F_coef_vec + evaled_perf_metric_scalar.vector == 0)
+        dual_constraints.append(S + evaled_perf_metric_scalar.matrix + G_coef_mat == 0)
+
+        return cvxpy.Problem(
+            cvxpy.Minimize(obj),
+            dual_constraints + lambd_constraints + extra_constraints,
+        )
+
+    def solve(self, **kwargs):
+        problem = self.build_problem()
+        result = problem.solve(**kwargs)
+        return result

pepflow/solver_test.py

@@ -32,7 +32,7 @@ def test_cvx_solver_case1():
         s2 = -(1 + p1 * p1)
         constraints = [(p1 * p1).gt(1, name="x^2 >= 1"), s1.gt(0, name="s1 > 0")]
 
-    solver = ps.CVXSolver(
+    solver = ps.CVXPrimalSolver(
         perf_metric=s2,
         constraints=constraints,
         context=pep_builder.get_context("test"),
@@ -55,7 +55,7 @@ def test_cvx_solver_case2():
         s2 = -p1 * p1 + 2
         constraints = [(p1 * p1).lt(1, name="x^2 <= 1"), s1.gt(0, name="s1 > 0")]
 
-    solver = ps.CVXSolver(
+    solver = ps.CVXPrimalSolver(
         perf_metric=s2,
         constraints=constraints,
         context=pep_builder.get_context("test"),
@@ -68,3 +68,51 @@ def test_cvx_solver_case2():
 
     assert np.isclose(solver.dual_var_manager.dual_value("x^2 <= 1"), 0)
     assert solver.dual_var_manager.dual_value("s1 > 0") == 0
+
+
+def test_cvx_dual_solver_case1():
+    pep_builder = pep.PEPBuilder()
+    with pep_builder.make_context("test"):
+        p1 = pp.Point(is_basis=True, tags=["p1"])
+        s1 = pp.Scalar(is_basis=True, tags=["s1"])
+        s2 = -(1 + p1 * p1)
+        constraints = [(p1 * p1).gt(1, name="x^2 >= 1"), s1.gt(0, name="s1 > 0")]
+
+    dual_solver = ps.CVXDualSolver(
+        perf_metric=s2,
+        constraints=constraints,
+        context=pep_builder.get_context("test"),
+    )
+    problem = dual_solver.build_problem()
+    result = problem.solve()
+    assert abs(-result - 2) < 1e-6
+
+    assert np.isclose(dual_solver.primal_var_manager.primal_value("x^2 >= 1"), 1)
+    assert np.isclose(dual_solver.primal_var_manager.primal_value("s1 > 0"), 0)
+
+
+def test_cvx_dual_solver_case2():
+    pep_builder = pep.PEPBuilder()
+    with pep_builder.make_context("test"):
+        p1 = pp.Point(is_basis=True, tags=["p1"])
+        s1 = pp.Scalar(is_basis=True, tags=["s1"])
+        s2 = -p1 * p1 + 2
+        constraints = [(p1 * p1).lt(1, name="x^2 <= 1"), s1.gt(0, name="s1 > 0")]
+
+    dual_solver = ps.CVXDualSolver(
+        perf_metric=s2,
+        constraints=constraints,
+        context=pep_builder.get_context("test"),
+    )
+
+    # It is a simple `min_x x^2-2; s.t. x^2 <= 1` problem.
+    problem = dual_solver.build_problem()
+    result = problem.solve()
+    assert abs(-result + 2) < 1e-6
+
+    assert np.isclose(
+        dual_solver.primal_var_manager.primal_value("x^2 <= 1"), 0, atol=1e-7
+    )
+    assert np.isclose(
+        dual_solver.primal_var_manager.primal_value("s1 > 0"), 0, atol=1e-7
+    )

pepflow/utils.py

@@ -24,6 +24,7 @@ import numbers
 from typing import TYPE_CHECKING, Any
 
 import numpy as np
+import sympy as sp
 
 if TYPE_CHECKING:
     from pepflow.function import Function
@@ -31,13 +32,17 @@ if TYPE_CHECKING:
     from pepflow.scalar import Scalar
 
 
-def SOP(v, w):
+NUMERICAL_TYPE = numbers.Number | sp.Rational
+
+
+def SOP(v, w, sympy_mode: bool = False) -> np.ndarray:
     """Symmetric Outer Product."""
-    return 1 / 2 * (np.outer(v, w) + np.outer(w, v))
+    coef = sp.S(1) / 2 if sympy_mode else 1 / 2
+    return coef * (np.outer(v, w) + np.outer(w, v))
 
 
-def SOP_self(v):
-    return SOP(v, v)
+def SOP_self(v, sympy_mode: bool = False) -> np.ndarray:
+    return SOP(v, v, sympy_mode=sympy_mode)
 
 
 class Op(enum.Enum):
@@ -54,12 +59,39 @@ class Comparator(enum.Enum):
 
 
 def is_numerical(val: Any) -> bool:
-    return isinstance(val, numbers.Number)
+    return isinstance(val, numbers.Number) or isinstance(val, sp.Rational)
+
+
+def is_numerical_or_parameter(val: Any) -> bool:
+    from pepflow import parameter as param
+
+    return is_numerical(val) or isinstance(val, param.Parameter)
+
+
+def numerical_str(val: Any) -> str:
+    from pepflow import parameter as param
+
+    if not is_numerical_or_parameter(val):
+        raise ValueError(
+            "Cannot call numerical_str for {val} since it is not numerical."
+        )
+    if isinstance(val, param.Parameter):
+        return str(val)
+    return str(val) if isinstance(val, sp.Rational) else f"{val:.4g}"
 
 
 def parenthesize_tag(val: Point | Scalar | Function) -> str:
     tmp_tag = val.tag
     if not val.is_basis:
-        if val.eval_expression.op == Op.ADD or val.eval_expression.op == Op.SUB:
-            tmp_tag = f"({val.tag})"
+        if op := getattr(val.eval_expression, "op", None):
+            if op in (Op.ADD, Op.SUB):
+                tmp_tag = f"({val.tag})"
     return tmp_tag
+
+
+def str_to_latex(s: str) -> str:
+    """Convert string into latex style."""
+    s = s.replace("star", r"\star")
+    s = s.replace("gradient_", r"\nabla ")
+    s = s.replace("|", r"\|")
+    return rf"$\displaystyle {s}$"

{pepflow-0.1.4a1.dist-info → pepflow-0.1.5.dist-info}/METADATA

@@ -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.5.dist-info/RECORD

@@ -0,0 +1,28 @@
+pepflow/__init__.py,sha256=uF-c0NyR8z9sASDj8nvd3Vz1a4gFm7ZcdH-SyR3h0bs,2250
+pepflow/constants.py,sha256=t29CDRE8kw773zgKS0ZZCYGegwagaDDdLfpSaeDpK14,871
+pepflow/constraint.py,sha256=aFcdOprdBc5peT7oL5IXlfnvnGw1qadPLtKsy1Cbrac,3555
+pepflow/constraint_test.py,sha256=6MF__r67NooqOVXHtkeOVcg_ebycMF_xI9OpFDFiV4c,2676
+pepflow/e2e_test.py,sha256=jo4pWoXq9XJFmdfvJeSUdCIlmdmk_Qp2QCjOLelPqMY,3701
+pepflow/expression_manager.py,sha256=AD2AHQGvmjRltsKgXiG9QV5oUZFpQsTgd-dky5uNRi0,17875
+pepflow/expression_manager_test.py,sha256=ZzwZGc-rP5iey8aXMakeq_0PbMW6Tf7DmMxzSeJe2Bg,5493
+pepflow/function.py,sha256=19TocYEjO5Wn24IpJYmzP_UTwyR_Pg3uzE_-zluC3CM,22867
+pepflow/function_test.py,sha256=RBBm_Z6SKD3Vd03eUAO4XPONyXXueT8w1eiRLeA4IuI,8263
+pepflow/interactive_constraint.py,sha256=mB3AQt21kIdRR0yqtvUksoELSLSoTDkMeu07ThKPerE,12757
+pepflow/parameter.py,sha256=yknpFWzj91gfDKjRVgRDMG57mKeKE1Qqcnm4i2tZzok,6246
+pepflow/parameter_test.py,sha256=fLmKvoLKu_-GULDXcpXmoAZA17mx0m9Zm3twfXQUin0,4199
+pepflow/pep.py,sha256=hCB2jXjLCU_5jgykZD6jwch4fDvdvy-aX4jmQpF6jWs,16222
+pepflow/pep_context.py,sha256=Y6JD28TAf39SB8G_FuqQnd4HVgit1viGIOTs4lzdzgg,9184
+pepflow/pep_context_test.py,sha256=B12M4eni0MVL_30v6yAf4ognWc1YxNTaR50_F01iGnI,4052
+pepflow/pep_test.py,sha256=-diI87sk10417oBnPRgWxY6XhiKOPoK7m5-MTkmlTcw,2788
+pepflow/point.py,sha256=pv0yr4oQsfBlzKLPMWPeR6WfdF4W-l_AaR5GFg_Me7o,12570
+pepflow/point_test.py,sha256=Rm-uOvB9GjIwH3XGnWr5UfTRqzlZRb8u-esV5b-bgtY,5667
+pepflow/scalar.py,sha256=oZjsfXZEhofxszk21pmcvNQOh8_N_6G_PfH3STbugH4,18315
+pepflow/scalar_test.py,sha256=fYtKfe-nO4GhAIIrZrW0Lx_fbFHqIxsKbPPA-G5udnE,7082
+pepflow/solver.py,sha256=ZThfiaSDru-gHxn21PC8T71ePzTykAhSRCteOaOBbcQ,11381
+pepflow/solver_test.py,sha256=NuH6yF-NTItkv3x0U40HFJ7xbSNi407qg4QGlVmXqHU,4063
+pepflow/utils.py,sha256=-Uu0TlJyqpGNT4DmdLtvXWNFPHn06zKHF7Jr1NHz7LQ,2743
+pepflow-0.1.5.dist-info/licenses/LICENSE,sha256=na5oVXAps-5f1hLGG4SYnwFdavQeXgYUeN-E3MxOA_s,11361
+pepflow-0.1.5.dist-info/METADATA,sha256=ULyUflh7uT2lqFhobLqMqWxU4uPwfKoBWPa5u7Ojmvc,1867
+pepflow-0.1.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pepflow-0.1.5.dist-info/top_level.txt,sha256=0YEPCZQQa6yIAIwMumzDg4pj7AME8aXu2sXkuq8xM6M,8
+pepflow-0.1.5.dist-info/RECORD,,

pepflow-0.1.4a1.dist-info/RECORD

@@ -1,26 +0,0 @@
-pepflow/__init__.py,sha256=xvtX_jzS-wEqjHicdWWRp-lL71VbGv3vhuvfKncRFsQ,1985
-pepflow/constants.py,sha256=t29CDRE8kw773zgKS0ZZCYGegwagaDDdLfpSaeDpK14,871
-pepflow/constraint.py,sha256=n-01dcQplvsXB7V4fceJBImbwSr-Wa9k9tE7ZcVmi3o,1153
-pepflow/constraint_test.py,sha256=6MF__r67NooqOVXHtkeOVcg_ebycMF_xI9OpFDFiV4c,2676
-pepflow/e2e_test.py,sha256=7FDFUe-TfxiJ5LN57gxO1OzdqnGHgRJe_Eoega6TpMI,2193
-pepflow/expression_manager.py,sha256=94G1PyD-W1uS72AgyeCMwDEcLWwuhdIimuZ1nXjMNJA,7680
-pepflow/expression_manager_test.py,sha256=1NmFZUoxZ3Lf0qP10uYQplWMX4-OYSAnvhiVLBXvt3U,4164
-pepflow/function.py,sha256=bhL8cVX_KctJC9JyT_fgxXM-9HjnNJ0b6SlTBkwdzOw,16305
-pepflow/function_test.py,sha256=RBBm_Z6SKD3Vd03eUAO4XPONyXXueT8w1eiRLeA4IuI,8263
-pepflow/interactive_constraint.py,sha256=mB3AQt21kIdRR0yqtvUksoELSLSoTDkMeu07ThKPerE,12757
-pepflow/pep.py,sha256=cEFhnY-81OZTJ-1rwVReIBehH4S8qF5TOHkYiy02trk,6380
-pepflow/pep_context.py,sha256=p1cN4THwH8WKQfkzp8nw8PiQMRIzhCtSd3lkZqsGBPg,4804
-pepflow/pep_context_test.py,sha256=iNbsr1PRlVBBoKpgmochmdOjpHCNDlY86NPTwSqJrt4,3392
-pepflow/pep_test.py,sha256=-diI87sk10417oBnPRgWxY6XhiKOPoK7m5-MTkmlTcw,2788
-pepflow/point.py,sha256=vSKCuivJL3zyUCnV48rfM5XpAGsVbdQ8YWdO3fKrViI,8514
-pepflow/point_test.py,sha256=vuG8GbEU9vLf-btyax0XWEgiQm5hZMxscYk8HdyKjSE,5270
-pepflow/scalar.py,sha256=8E-D5pgZCDpyEX13VwrFARo87v-HWAUs4gAD_-Ty_g8,9653
-pepflow/scalar_test.py,sha256=mzLJOtNdZd54wJir5uiaEoMtcwEWiYh9C-oRWxbeb_A,6472
-pepflow/solver.py,sha256=WzeN_IWNBs9IpE212jenhYMWFuuwH890h0vaFmJRM6I,4312
-pepflow/solver_test.py,sha256=-aCEe-oQ26xJUWR64b-CIIfFOK_pNJnMlOly2bagk68,2457
-pepflow/utils.py,sha256=Xd-DwtUoUSMw_i6xjYsOxsHmn8l3ZbYCyptXEBfoyZk,1718
-pepflow-0.1.4a1.dist-info/licenses/LICENSE,sha256=na5oVXAps-5f1hLGG4SYnwFdavQeXgYUeN-E3MxOA_s,11361
-pepflow-0.1.4a1.dist-info/METADATA,sha256=NR2LXX5TJWYrEmHVTIIiUrre_n896lnnH0ffbx74Cyc,1752
-pepflow-0.1.4a1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pepflow-0.1.4a1.dist-info/top_level.txt,sha256=0YEPCZQQa6yIAIwMumzDg4pj7AME8aXu2sXkuq8xM6M,8
-pepflow-0.1.4a1.dist-info/RECORD,,