openscvx 0.3.2.dev328__tar.gz → 0.3.2.dev333__tar.gz

{openscvx-0.3.2.dev328/openscvx.egg-info → openscvx-0.3.2.dev333}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscvx
-Version: 0.3.2.dev328
+Version: 0.3.2.dev333
 Summary: A general Python-based successive convexification implementation which uses a JAX backend.
 Author-email: Chris Hayner and Griffin Norris <haynec@uw.edu>
 License: Apache Software License

{openscvx-0.3.2.dev328 → openscvx-0.3.2.dev333}/openscvx/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.3.2.dev328'
-__version_tuple__ = version_tuple = (0, 3, 2, 'dev328')
+__version__ = version = '0.3.2.dev333'
+__version_tuple__ = version_tuple = (0, 3, 2, 'dev333')
 
-__commit_id__ = commit_id = 'g63a14061a'
+__commit_id__ = commit_id = 'g298f4bc4f'

openscvx-0.3.2.dev333/openscvx/symbolic/lowerers/cvxpy/__init__.py

@@ -0,0 +1,35 @@
+"""CVXPy backend for lowering symbolic expressions to disciplined convex programs.
+
+This package implements the CVXPy lowering backend that converts symbolic
+expression AST nodes into CVXPy expressions and constraints for convex
+optimization.  The lowering uses a visitor pattern where each expression
+type has a corresponding visitor function registered via ``@visitor``.
+
+The visitor functions are split across submodules that mirror the
+``openscvx.symbolic.expr`` package structure.  Importing this package
+triggers registration of all visitors.
+
+Example::
+
+    from openscvx.symbolic.lowerers.cvxpy import CvxpyLowerer
+
+    lowerer = CvxpyLowerer(variable_map={"x": cvx_x, "u": cvx_u})
+    cvx_expr = lowerer.lower(expr)
+"""
+
+# Import visitor modules to trigger @visitor registration.
+# Each module populates _CVXPY_VISITORS as a side effect of import.
+from openscvx.symbolic.lowerers.cvxpy import (
+    arithmetic,  # noqa: F401
+    array,  # noqa: F401
+    constraint,  # noqa: F401
+    control,  # noqa: F401
+    expr,  # noqa: F401
+    linalg,  # noqa: F401
+    logic,  # noqa: F401
+    math,  # noqa: F401
+    state,  # noqa: F401
+)
+from openscvx.symbolic.lowerers.cvxpy._lowerer import CvxpyLowerer, lower_to_cvxpy
+
+__all__ = ["CvxpyLowerer", "lower_to_cvxpy"]

openscvx-0.3.2.dev333/openscvx/symbolic/lowerers/cvxpy/_lowerer.py

@@ -0,0 +1,111 @@
+"""CvxpyLowerer class definition.
+
+The visitor methods that populate the registry live in sibling modules
+(``arithmetic``, ``math``, ``linalg``, etc.) and are registered via
+``@visitor`` at import time.
+"""
+
+from typing import Dict
+
+import cvxpy as cp
+
+from openscvx.symbolic.expr import Expr
+from openscvx.symbolic.lowerers.cvxpy._registry import dispatch
+
+
+class CvxpyLowerer:
+    """CVXPy backend for lowering symbolic expressions to disciplined convex programs.
+
+    This class implements the visitor pattern for converting symbolic expression
+    AST nodes to CVXPy expressions and constraints. Each expression type has a
+    corresponding visitor function decorated with @visitor that handles the
+    lowering logic.
+
+    The lowering process is recursive: each visitor lowers its child expressions
+    first, then composes them into a CVXPy operation. CVXPy will validate DCP
+    (Disciplined Convex Programming) compliance when the problem is constructed.
+
+    Attributes:
+        variable_map (dict): Dictionary mapping variable names to CVXPy expressions.
+            Must include "x" for states and "u" for controls. May include parameter
+            names mapped to CVXPy Parameter objects or constants.
+
+    Example:
+        Lower an expression to CVXPy::
+
+            import cvxpy as cp
+            lowerer = CvxpyLowerer(variable_map={
+                "x": cp.Variable(3),
+                "u": cp.Variable(2),
+            })
+            expr = ox.Norm(x)**2 + 0.1 * ox.Norm(u)**2
+            cvx_expr = lowerer.lower(expr)
+
+    Note:
+        The lowerer is stateful (stores variable_map) unlike JaxLowerer which
+        is stateless. Variables must be registered before lowering expressions
+        that reference them.
+    """
+
+    def __init__(self, variable_map: Dict[str, cp.Expression] = None):
+        """Initialize the CVXPy lowerer.
+
+        Args:
+            variable_map: Dictionary mapping variable names to CVXPy expressions.
+                For State/Control objects, keys should be "x" and "u" respectively.
+                For Parameter objects, keys should match their names. If None, an
+                empty dictionary is created.
+        """
+        self.variable_map = variable_map or {}
+
+    def register_variable(self, name: str, value: cp.Expression):
+        """Register a variable in the variable map.
+
+        Args:
+            name: Variable name (e.g., "x", "u", or parameter name)
+            value: CVXPy expression to associate with the name
+        """
+        self.variable_map[name] = value
+
+    def lower(self, expr: Expr) -> cp.Expression:
+        """Lower a symbolic expression to a CVXPy expression.
+
+        Main entry point for lowering. Delegates to dispatch() which looks up
+        the appropriate visitor method based on the expression type.
+
+        Args:
+            expr: Symbolic expression to lower (any Expr subclass)
+
+        Returns:
+            CVXPy expression or constraint
+
+        Raises:
+            NotImplementedError: If no visitor exists for the expression type
+            ValueError: If required variables are missing from variable_map
+        """
+        return dispatch(self, expr)
+
+
+def lower_to_cvxpy(expr: Expr, variable_map: Dict[str, cp.Expression] = None) -> cp.Expression:
+    """Lower symbolic expression to CVXPy expression or constraint.
+
+    Convenience wrapper that creates a CvxpyLowerer and lowers a single
+    symbolic expression to a CVXPy expression. The result can be used in
+    CVXPy optimization problems.
+
+    Args:
+        expr: Symbolic expression to lower (any Expr subclass)
+        variable_map: Dictionary mapping variable names to CVXPy expressions.
+            Must include "x" for states and "u" for controls. May include
+            parameter names mapped to CVXPy Parameters or constants.
+
+    Returns:
+        CVXPy expression for arithmetic expressions (Add, Mul, Norm, etc.)
+        or CVXPy constraint for constraint expressions (Equality, Inequality)
+
+    Raises:
+        NotImplementedError: If the expression type is not supported
+        ValueError: If required variables are missing from variable_map
+    """
+    lowerer = CvxpyLowerer(variable_map)
+    return lowerer.lower(expr)

openscvx-0.3.2.dev333/openscvx/symbolic/lowerers/cvxpy/_registry.py

@@ -0,0 +1,75 @@
+"""Visitor registry for the CVXPy lowerer.
+
+This module holds the shared visitor dictionary, the ``@visitor`` decorator,
+and the ``dispatch`` function.  It is deliberately kept free of heavyweight
+imports (no CVXPy, no expression subclasses beyond the base ``Expr``) so that
+the visitor modules can import from it without circular-dependency issues.
+"""
+
+from typing import Any, Callable, Dict, Type
+
+from openscvx.symbolic.expr import Expr
+
+_CVXPY_VISITORS: Dict[Type[Expr], Callable] = {}
+"""Registry mapping expression types to their visitor functions."""
+
+
+def visitor(expr_cls: Type[Expr]) -> Callable[[Callable], Callable]:
+    """Decorator to register a visitor function for an expression type.
+
+    This decorator registers a visitor method to handle a specific expression
+    type during CVXPy lowering. The decorated function is stored in
+    _CVXPY_VISITORS and will be called by dispatch() when lowering that
+    expression type.
+
+    Args:
+        expr_cls: The Expr subclass this visitor handles (e.g., Add, Mul, Norm)
+
+    Returns:
+        Decorator function that registers the visitor and returns it unchanged
+
+    Example:
+        Register a visitor function for the Add expression::
+
+            @visitor(Add)
+            def _visit_add(lowerer, node: Add):
+                ...
+
+    Note:
+        Multiple expression types can share a visitor by stacking decorators::
+
+            @visitor(Equality)
+            @visitor(Inequality)
+            def _visit_constraint(lowerer, node: Constraint):
+                ...
+    """
+
+    def register(fn: Callable[[Any, Expr], Any]):
+        _CVXPY_VISITORS[expr_cls] = fn
+        return fn
+
+    return register
+
+
+def dispatch(lowerer: Any, expr: Expr) -> Any:
+    """Dispatch an expression to its registered visitor function.
+
+    Looks up the visitor function for the expression's type and calls it.
+    This is the core of the visitor pattern implementation.
+
+    Args:
+        lowerer: The CvxpyLowerer instance (provides context for visitor methods)
+        expr: The expression node to lower
+
+    Returns:
+        The result of calling the visitor function (CVXPy expression or constraint)
+
+    Raises:
+        NotImplementedError: If no visitor is registered for the expression type
+    """
+    fn = _CVXPY_VISITORS.get(type(expr))
+    if fn is None:
+        raise NotImplementedError(
+            f"{lowerer.__class__.__name__!r} has no visitor for {type(expr).__name__}"
+        )
+    return fn(lowerer, expr)

openscvx-0.3.2.dev333/openscvx/symbolic/lowerers/cvxpy/arithmetic.py

@@ -0,0 +1,149 @@
+"""CVXPy visitors for arithmetic expressions.
+
+Visitors: Add, Sub, Mul, Div, MatMul, Neg, Power
+"""
+
+import cvxpy as cp
+
+# Expression types to handle — uncomment as you paste visitors:
+from openscvx.symbolic.expr.arithmetic import Add, Div, MatMul, Mul, Neg, Power, Sub
+from openscvx.symbolic.lowerers.cvxpy._registry import visitor  # noqa: F401
+
+
+@visitor(Add)
+def _visit_add(lowerer, node: Add) -> cp.Expression:
+    """Lower addition to CVXPy expression.
+
+    Recursively lowers all terms and composes them with element-wise addition.
+    Addition is affine and always DCP-compliant.
+
+    Args:
+        node: Add expression node with multiple terms
+
+    Returns:
+        CVXPy expression representing the sum of all terms
+    """
+    terms = [lowerer.lower(term) for term in node.terms]
+    result = terms[0]
+    for term in terms[1:]:
+        result = result + term
+    return result
+
+
+@visitor(Sub)
+def _visit_sub(lowerer, node: Sub) -> cp.Expression:
+    """Lower subtraction to CVXPy expression (element-wise left - right).
+
+    Subtraction is affine and always DCP-compliant.
+
+    Args:
+        node: Sub expression node
+
+    Returns:
+        CVXPy expression representing left - right
+    """
+    left = lowerer.lower(node.left)
+    right = lowerer.lower(node.right)
+    return left - right
+
+
+@visitor(Mul)
+def _visit_mul(lowerer, node: Mul) -> cp.Expression:
+    """Lower element-wise multiplication to CVXPy expression.
+
+    Element-wise multiplication is DCP-compliant when at least one operand
+    is constant. For quadratic forms, use MatMul instead.
+
+    Args:
+        node: Mul expression node with multiple factors
+
+    Returns:
+        CVXPy expression representing element-wise product
+
+    Note:
+        For convex optimization, typically one factor should be constant.
+        CVXPy will raise a DCP error if the composition violates DCP rules.
+    """
+    factors = [lowerer.lower(factor) for factor in node.factors]
+    result = factors[0]
+    for factor in factors[1:]:
+        result = result * factor
+    return result
+
+
+@visitor(Div)
+def _visit_div(lowerer, node: Div) -> cp.Expression:
+    """Lower element-wise division to CVXPy expression.
+
+    Division is DCP-compliant when the denominator is constant or when
+    the numerator is constant and the denominator is concave.
+
+    Args:
+        node: Div expression node
+
+    Returns:
+        CVXPy expression representing left / right
+
+    Note:
+        CVXPy will raise a DCP error if the division violates DCP rules.
+    """
+    left = lowerer.lower(node.left)
+    right = lowerer.lower(node.right)
+    return left / right
+
+
+@visitor(MatMul)
+def _visit_matmul(lowerer, node: MatMul) -> cp.Expression:
+    """Lower matrix multiplication to CVXPy expression using @ operator.
+
+    Matrix multiplication is DCP-compliant when at least one operand is
+    constant. Used for quadratic forms like x.T @ Q @ x.
+
+    Args:
+        node: MatMul expression node
+
+    Returns:
+        CVXPy expression representing left @ right
+    """
+    left = lowerer.lower(node.left)
+    right = lowerer.lower(node.right)
+    return left @ right
+
+
+@visitor(Neg)
+def _visit_neg(lowerer, node: Neg) -> cp.Expression:
+    """Lower negation (unary minus) to CVXPy expression.
+
+    Negation preserves DCP properties (negating convex gives concave).
+
+    Args:
+        node: Neg expression node
+
+    Returns:
+        CVXPy expression representing -operand
+    """
+    operand = lowerer.lower(node.operand)
+    return -operand
+
+
+@visitor(Power)
+def _visit_power(lowerer, node: Power) -> cp.Expression:
+    """Lower element-wise power (base**exponent) to CVXPy expression.
+
+    Power is DCP-compliant for specific exponent values:
+    - exponent >= 1: convex (when base >= 0)
+    - 0 <= exponent <= 1: concave (when base >= 0)
+
+    Args:
+        node: Power expression node
+
+    Returns:
+        CVXPy expression representing base**exponent
+
+    Note:
+        CVXPy will verify DCP compliance at problem construction time.
+        Common convex cases: x^2, x^3, x^4 (even powers)
+    """
+    base = lowerer.lower(node.base)
+    exponent = lowerer.lower(node.exponent)
+    return cp.power(base, exponent)

openscvx-0.3.2.dev333/openscvx/symbolic/lowerers/cvxpy/array.py

@@ -0,0 +1,152 @@
+"""CVXPy visitors for array expressions.
+
+Visitors: Index, Concat, Stack, Hstack, Vstack, Block
+"""
+
+import cvxpy as cp
+
+# Expression types to handle — uncomment as you paste visitors:
+from openscvx.symbolic.expr.array import Block, Concat, Hstack, Index, Stack, Vstack
+from openscvx.symbolic.lowerers.cvxpy._registry import visitor  # noqa: F401
+
+
+@visitor(Index)
+def _visit_index(lowerer, node: Index) -> cp.Expression:
+    """Lower indexing/slicing operation to CVXPy expression.
+
+    Indexing preserves DCP properties (indexing into convex is convex).
+
+    Args:
+        node: Index expression node
+
+    Returns:
+        CVXPy expression representing base[index]
+    """
+    base = lowerer.lower(node.base)
+    return base[node.index]
+
+
+@visitor(Concat)
+def _visit_concat(lowerer, node: Concat) -> cp.Expression:
+    """Lower concatenation to CVXPy expression.
+
+    Concatenates expressions horizontally along axis 0. Scalars are
+    promoted to 1D arrays before concatenation. Preserves DCP properties.
+
+    Args:
+        node: Concat expression node
+
+    Returns:
+        CVXPy expression representing horizontal concatenation
+
+    Note:
+        Uses cp.hstack for concatenation. Scalars are reshaped to (1,).
+    """
+    exprs = [lowerer.lower(child) for child in node.exprs]
+    # Ensure all expressions are at least 1D for concatenation
+    exprs_1d = []
+    for expr in exprs:
+        if expr.ndim == 0:  # scalar
+            exprs_1d.append(cp.reshape(expr, (1,), order="C"))
+        else:
+            exprs_1d.append(expr)
+    return cp.hstack(exprs_1d)
+
+
+@visitor(Stack)
+def _visit_stack(lowerer, node: Stack) -> cp.Expression:
+    """Lower vertical stacking to CVXPy expression.
+
+    Stacks expressions vertically using cp.vstack. Preserves DCP properties.
+
+    Args:
+        node: Stack expression node with multiple rows
+
+    Returns:
+        CVXPy expression representing vertical stack of rows
+
+    Note:
+        Each row is stacked along axis 0 to create a 2D array.
+    """
+    rows = [lowerer.lower(row) for row in node.rows]
+    # Stack rows vertically
+    return cp.vstack(rows)
+
+
+@visitor(Hstack)
+def _visit_hstack(lowerer, node: Hstack) -> cp.Expression:
+    """Lower horizontal stacking to CVXPy expression.
+
+    For 1D arrays, uses cp.hstack (concatenation). For 2D+ arrays, uses
+    cp.bmat with a single row to achieve proper horizontal stacking along
+    axis 1, matching numpy.hstack semantics.
+
+    Args:
+        node: Hstack expression node with multiple arrays
+
+    Returns:
+        CVXPy expression representing horizontal stack of arrays
+    """
+    arrays = [lowerer.lower(arr) for arr in node.arrays]
+
+    # Check dimensionality from the symbolic node's shape
+    shape = node.check_shape()
+    if len(shape) == 1:
+        # 1D: simple concatenation
+        return cp.hstack(arrays)
+    else:
+        # 2D+: use bmat with single row for proper horizontal stacking
+        return cp.bmat([arrays])
+
+
+@visitor(Vstack)
+def _visit_vstack(lowerer, node: Vstack) -> cp.Expression:
+    """Lower vertical stacking to CVXPy expression.
+
+    Stacks expressions vertically using cp.vstack. Preserves DCP properties.
+
+    Args:
+        node: Vstack expression node with multiple arrays
+
+    Returns:
+        CVXPy expression representing vertical stack of arrays
+    """
+    arrays = [lowerer.lower(arr) for arr in node.arrays]
+    return cp.vstack(arrays)
+
+
+@visitor(Block)
+def _visit_block(lowerer, node: Block) -> cp.Expression:
+    """Lower block matrix construction to CVXPy expression.
+
+    Assembles a block matrix from nested lists of expressions using cp.bmat.
+    This is the CVXPy equivalent of numpy.block() for block matrix construction.
+
+    Args:
+        node: Block expression node with 2D nested structure of expressions
+
+    Returns:
+        CVXPy expression representing the assembled block matrix
+
+    Raises:
+        NotImplementedError: If any block has more than 2 dimensions
+
+    Note:
+        cp.bmat preserves DCP properties when all blocks are DCP-compliant.
+        Block matrices are commonly used for constraint aggregation.
+        For 3D+ tensors, use JAX lowering instead.
+    """
+    # Check for 3D+ blocks - CVXPy's bmat only supports 2D
+    for i, row in enumerate(node.blocks):
+        for j, block in enumerate(row):
+            block_shape = block.check_shape()
+            if len(block_shape) > 2:
+                raise NotImplementedError(
+                    f"CVXPy does not support Block with tensors of dimension > 2. "
+                    f"Block[{i}][{j}] has shape {block_shape} ({len(block_shape)}D). "
+                    f"For N-D tensor block assembly, use JAX lowering instead."
+                )
+
+    # Lower each block expression
+    block_exprs = [[lowerer.lower(block) for block in row] for row in node.blocks]
+    return cp.bmat(block_exprs)

openscvx-0.3.2.dev333/openscvx/symbolic/lowerers/cvxpy/constraint.py

@@ -0,0 +1,122 @@
+"""CVXPy visitors for constraint expressions.
+
+Visitors: Equality, Inequality, CrossNodeConstraint, CTCS
+"""
+
+import cvxpy as cp
+
+# Expression types to handle — uncomment as you paste visitors:
+from openscvx.symbolic.expr.constraint import (
+    CTCS,
+    CrossNodeConstraint,
+    Equality,
+    Inequality,
+)
+from openscvx.symbolic.lowerers.cvxpy._registry import visitor  # noqa: F401
+
+
+@visitor(Equality)
+def _visit_equality(lowerer, node: Equality) -> cp.Constraint:
+    """Lower equality constraint to CVXPy constraint (lhs == rhs).
+
+    Equality constraints require affine expressions on both sides for
+    DCP compliance.
+
+    Args:
+        node: Equality constraint node
+
+    Returns:
+        CVXPy equality constraint object
+
+    Note:
+        For DCP compliance, both lhs and rhs must be affine. CVXPy will
+        raise a DCP error if either side is non-affine.
+    """
+    left = lowerer.lower(node.lhs)
+    right = lowerer.lower(node.rhs)
+    return left == right
+
+
+@visitor(Inequality)
+def _visit_inequality(lowerer, node: Inequality) -> cp.Constraint:
+    """Lower inequality constraint to CVXPy constraint (lhs <= rhs).
+
+    Inequality constraints must satisfy DCP rules: convex <= concave.
+
+    Args:
+        node: Inequality constraint node
+
+    Returns:
+        CVXPy inequality constraint object
+
+    Note:
+        For DCP compliance: lhs must be convex and rhs must be concave.
+        Common form: convex_expr(x) <= constant
+    """
+    left = lowerer.lower(node.lhs)
+    right = lowerer.lower(node.rhs)
+    return left <= right
+
+
+@visitor(CrossNodeConstraint)
+def _visit_cross_node_constraint(lowerer, node: CrossNodeConstraint) -> cp.Constraint:
+    """Lower CrossNodeConstraint to CVXPy constraint.
+
+    CrossNodeConstraint wraps constraints that reference multiple trajectory
+    nodes via NodeReference (e.g., rate limits like x.at(k) - x.at(k-1) <= r).
+
+    For CVXPy lowering, this simply lowers the inner constraint. The NodeReference
+    nodes within the constraint will handle extracting values from the full
+    trajectory arrays (which must be provided in variable_map as "x" and "u").
+
+    Args:
+        node: CrossNodeConstraint expression wrapping the inner constraint
+
+    Returns:
+        CVXPy constraint object
+
+    Note:
+        The variable_map must contain full trajectory arrays:
+            - "x": (N, n_x) CVXPy expression (e.g., cp.vstack(x_nonscaled))
+            - "u": (N, n_u) CVXPy expression (e.g., cp.vstack(u_nonscaled))
+
+        NodeReference visitors will index into these arrays using the fixed
+        node indices baked into the expression.
+
+    Example:
+        For constraint: position.at(5) - position.at(4) <= max_step
+
+        With variable_map = {"x": cp.vstack([x[k] for k in range(N)])}
+
+        The lowered constraint evaluates:
+            x[5, pos_slice] - x[4, pos_slice] <= max_step
+    """
+    # Simply lower the inner constraint - NodeReference handles indexing
+    return lowerer.lower(node.constraint)
+
+
+@visitor(CTCS)
+def _visit_ctcs(lowerer, node: CTCS) -> cp.Expression:
+    """Raise NotImplementedError for CTCS constraints.
+
+    CTCS (Continuous-Time Constraint Satisfaction) constraints are handled
+    through dynamics augmentation using JAX, not CVXPy. They represent
+    non-convex continuous-time constraints.
+
+    Args:
+        node: CTCS constraint node
+
+    Raises:
+        NotImplementedError: Always raised since CTCS uses JAX, not CVXPy
+
+    Note:
+        CTCS constraints are lowered to JAX during dynamics augmentation.
+        They add virtual states and controls to enforce constraints over
+        continuous time intervals. See JaxLowerer.visit_ctcs() instead.
+    """
+    raise NotImplementedError(
+        "CTCS constraints are for continuous-time constraint satisfaction and "
+        "should be handled through dynamics augmentation with JAX lowering, "
+        "not CVXPy lowering. CTCS constraints represent non-convex dynamics "
+        "augmentation."
+    )