openscvx 0.3.2.dev170__py3-none-any.whl

openscvx/symbolic/expr/stl.py

@@ -0,0 +1,136 @@
+"""Signal Temporal Logic (STL) operations for trajectory optimization.
+
+This module provides symbolic expression nodes for Signal Temporal Logic (STL)
+operations, enabling the specification of complex temporal and logical constraints
+in optimization problems. STL is particularly useful for robotics and autonomous
+systems where tasks involve temporal reasoning.
+"""
+
+from typing import Tuple
+
+import numpy as np
+
+from .expr import Expr, to_expr
+
+
+class Or(Expr):
+    """Logical OR operation for disjunctive constraints.
+
+    Represents a logical disjunction (OR) between multiple constraint expressions.
+    This is particularly useful in STL-based trajectory optimization for expressing
+    choices or alternatives in task specifications. The Or operation is typically
+    relaxed using smooth approximations (e.g., LogSumExp) during optimization.
+
+    The Or operation allows expressing constraints like:
+
+    - "Reach either goal A OR goal B"
+    - "Avoid obstacle 1 OR obstacle 2" (at least one must be satisfied)
+    - "Use path 1 OR path 2 OR path 3"
+
+    During optimization, the disjunction is typically approximated using:
+        Or(φ₁, φ₂, ..., φₙ) ≈ LSE(φ₁, φ₂, ..., φₙ) ≥ 0
+
+    where LSE is the LogSumExp (smooth maximum) function.
+
+    Attributes:
+        operands: List of expressions representing the disjunctive clauses
+
+    Example:
+        Use Or STL operator to enforce that robot must reach either of two goal regions:
+
+            import openscvx as ox
+            x = ox.State("x", shape=(2,))
+            goal_a = ox.Parameter("goal_a", shape=(2,), value=[1.0, 1.0])
+            goal_b = ox.Parameter("goal_b", shape=(2,), value=[-1.0, -1.0])
+            # Robot is within 0.5 units of either goal
+            reach_a = 0.25 - ox.Norm(x - goal_a)**2
+            reach_b = 0.25 - ox.Norm(x - goal_b)**2
+            reach_either = ox.Or(reach_a, reach_b)
+
+    Note:
+        The Or operation produces a scalar result even when operands are vector
+        expressions, as it represents a single logical proposition.
+
+    See Also:
+        LogSumExp: Common smooth approximation for OR operations
+        Max: Hard maximum (non-smooth alternative)
+    """
+
+    def __init__(self, *operands):
+        """Initialize a logical OR operation.
+
+        Args:
+            *operands: Two or more expressions to combine with logical OR.
+                      Each operand typically represents a constraint or condition.
+
+        Raises:
+            ValueError: If fewer than two operands are provided
+        """
+        if len(operands) < 2:
+            raise ValueError("Or requires at least two operands")
+        self.operands = [to_expr(op) for op in operands]
+
+    def children(self):
+        return self.operands
+
+    def canonicalize(self) -> "Expr":
+        """Canonicalize by flattening nested Or expressions.
+
+        Flattens nested Or operations into a single flat Or with all clauses
+        at the same level. For example: Or(a, Or(b, c)) → Or(a, b, c).
+        Also canonicalizes all operands recursively.
+
+        Returns:
+            Expr: Canonical form of the Or expression. If only one operand
+                  remains after canonicalization, returns that operand directly.
+        """
+        operands = []
+
+        for operand in self.operands:
+            canonicalized = operand.canonicalize()
+            if isinstance(canonicalized, Or):
+                # Flatten nested Or: Or(a, Or(b, c)) -> Or(a, b, c)
+                operands.extend(canonicalized.operands)
+            else:
+                operands.append(canonicalized)
+
+        # Return simplified Or expression
+        if len(operands) == 1:
+            return operands[0]
+        return Or(*operands)
+
+    def check_shape(self) -> Tuple[int, ...]:
+        """Validate operand shapes and return result shape.
+
+        Checks that all operands have compatible (broadcastable) shapes. The Or
+        operation supports broadcasting, allowing mixing of scalars and vectors.
+
+        Returns:
+            tuple: Empty tuple () indicating a scalar result, as Or represents
+                   a single logical proposition
+
+        Raises:
+            ValueError: If fewer than two operands exist
+            ValueError: If operand shapes are not broadcastable
+        """
+        if len(self.operands) < 2:
+            raise ValueError("Or requires at least two operands")
+
+        # Validate all operands and get their shapes
+        operand_shapes = [operand.check_shape() for operand in self.operands]
+
+        # For logical operations, all operands should be broadcastable
+        # This allows mixing scalars with vectors for element-wise operations
+        try:
+            result_shape = operand_shapes[0]
+            for shape in operand_shapes[1:]:
+                result_shape = np.broadcast_shapes(result_shape, shape)
+        except ValueError as e:
+            raise ValueError(f"Or operands not broadcastable: {operand_shapes}") from e
+
+        # Or produces a scalar result (like constraints)
+        return ()
+
+    def __repr__(self):
+        operands_repr = " | ".join(repr(op) for op in self.operands)
+        return f"Or({operands_repr})"

openscvx/symbolic/expr/variable.py

@@ -0,0 +1,321 @@
+import hashlib
+
+import numpy as np
+
+from .expr import Leaf
+
+
+class Variable(Leaf):
+    """Base class for decision variables in optimization problems.
+
+    Variable represents decision variables (free parameters) in an optimization problem.
+    These are values that the optimizer can adjust to minimize the objective function
+    while satisfying constraints. Variables can have bounds (min/max) and initial guesses
+    to guide the optimization process.
+
+    Unlike Parameters (which are fixed values that can be changed between solves),
+    Variables are optimized by the solver. In trajectory optimization, Variables typically
+    represent discretized state or control trajectories.
+
+    Note:
+        Variable is typically not instantiated directly. Instead, use the specialized
+        subclasses State (for state variables with boundary conditions) or Control
+        (for control inputs). These provide additional functionality specific to
+        trajectory optimization.
+
+    Attributes:
+        name (str): Name identifier for the variable
+        _shape (tuple[int, ...]): Shape of the variable as a tuple (typically 1D)
+        _slice (slice | None): Internal slice information for variable indexing
+        _min (np.ndarray | None): Minimum bounds for each element of the variable
+        _max (np.ndarray | None): Maximum bounds for each element of the variable
+        _guess (np.ndarray | None): Initial guess for the variable trajectory (n_points, n_vars)
+
+    Example:
+            # Typically, use State or Control instead of Variable directly:
+            pos = openscvx.State("pos", shape=(3,))
+            u = openscvx.Control("u", shape=(2,))
+    """
+
+    def __init__(self, name, shape):
+        """Initialize a Variable object.
+
+        Args:
+            name: Name identifier for the variable
+            shape: Shape of the variable as a tuple (typically 1D like (3,) for 3D vector)
+        """
+        super().__init__(name, shape)
+        self._slice = None
+        self._min = None
+        self._max = None
+        self._guess = None
+
+    def __repr__(self):
+        return f"Var({self.name!r})"
+
+    def _hash_into(self, hasher: "hashlib._Hash") -> None:
+        """Hash Variable using its slice (canonical position, name-invariant).
+
+        Instead of hashing the variable name, we hash the _slice attribute
+        which represents the variable's canonical position in the unified
+        state/control vector. This ensures that two problems with the same
+        structure but different variable names produce the same hash.
+
+        Args:
+            hasher: A hashlib hash object to update
+        """
+        hasher.update(self.__class__.__name__.encode())
+        hasher.update(str(self._shape).encode())
+        # Hash the slice (canonical position) - this is name-invariant
+        if self._slice is not None:
+            hasher.update(f"slice:{self._slice.start}:{self._slice.stop}".encode())
+        else:
+            raise RuntimeError(
+                f"Cannot hash Variable '{self.name}' without _slice attribute. "
+                "Hashing should only be called on preprocessed problems where "
+                "all Variables have been assigned canonical slice positions."
+            )
+
+    @property
+    def min(self):
+        """Get the minimum bounds (lower bounds) for the variable.
+
+        Returns:
+            Array of minimum values for each element of the variable, or None if unbounded.
+
+        Example:
+                pos = Variable("pos", shape=(3,))
+                pos.min = [-10, -10, 0]
+                print(pos.min)  # [-10., -10., 0.]
+        """
+        return self._min
+
+    @min.setter
+    def min(self, arr):
+        """Set the minimum bounds (lower bounds) for the variable.
+
+        The bounds are applied element-wise to each component of the variable.
+        Scalars will be broadcast to match the variable shape.
+
+        Args:
+            arr: Array of minimum values, must be broadcastable to shape (n,)
+                where n is the variable dimension
+
+        Raises:
+            ValueError: If the shape of arr doesn't match the variable shape
+
+        Example:
+                pos = Variable("pos", shape=(3,))
+                pos.min = -10  # Broadcasts to [-10, -10, -10]
+                pos.min = [-5, -10, 0]  # Element-wise bounds
+        """
+        arr = np.asarray(arr, dtype=float)
+        if arr.ndim != 1 or arr.shape[0] != self.shape[0]:
+            raise ValueError(
+                f"{self.__class__.__name__} min must be 1D with shape ({self.shape[0]},), got"
+                f" {arr.shape}"
+            )
+        self._min = arr
+
+    @property
+    def max(self):
+        """Get the maximum bounds (upper bounds) for the variable.
+
+        Returns:
+            Array of maximum values for each element of the variable, or None if unbounded.
+
+        Example:
+                vel = Variable("vel", shape=(3,))
+                vel.max = [10, 10, 5]
+                print(vel.max)  # [10., 10., 5.]
+        """
+        return self._max
+
+    @max.setter
+    def max(self, arr):
+        """Set the maximum bounds (upper bounds) for the variable.
+
+        The bounds are applied element-wise to each component of the variable.
+        Scalars will be broadcast to match the variable shape.
+
+        Args:
+            arr: Array of maximum values, must be broadcastable to shape (n,)
+                where n is the variable dimension
+
+        Raises:
+            ValueError: If the shape of arr doesn't match the variable shape
+
+        Example:
+                vel = Variable("vel", shape=(3,))
+                vel.max = 10  # Broadcasts to [10, 10, 10]
+                vel.max = [15, 10, 5]  # Element-wise bounds
+        """
+        arr = np.asarray(arr, dtype=float)
+        if arr.ndim != 1 or arr.shape[0] != self.shape[0]:
+            raise ValueError(
+                f"{self.__class__.__name__} max must be 1D with shape ({self.shape[0]},), got"
+                f" {arr.shape}"
+            )
+        self._max = arr
+
+    @property
+    def slice(self):
+        """Get the slice indexing this variable in the unified state/control vector.
+
+        After preprocessing, each variable is assigned a canonical position in the
+        unified optimization vector. This property returns the slice object that
+        extracts this variable's values from the unified vector.
+
+        This is particularly useful for expert users working with byof (bring-your-own
+        functions) who need to manually index into the unified x and u vectors.
+
+        Returns:
+            slice: Slice object for indexing into unified vector, or None if the
+                variable hasn't been preprocessed yet.
+
+        Example:
+                velocity = ox.State("velocity", shape=(3,))
+                # ... after Problem construction ...
+                print(velocity.slice)  # slice(2, 5) (for example)
+
+                # Use in byof functions
+                def my_constraint(x, u, node, params):
+                    vel = x[velocity.slice]  # Extract velocity from unified state
+                    return jnp.sum(vel**2) - 100  # |v|^2 <= 100
+        """
+        return self._slice
+
+    @property
+    def guess(self):
+        """Get the initial guess for the variable trajectory.
+
+        The guess provides a starting point for the optimizer. A good initial guess
+        can significantly improve convergence speed and help avoid local minima.
+
+        Returns:
+            2D array of shape (n_points, n_vars) representing the variable trajectory
+            over time, or None if no guess is provided.
+
+        Example:
+                x = Variable("x", shape=(2,))
+                # Linear interpolation from [0,0] to [10,10] over 50 points
+                x.guess = np.linspace([0, 0], [10, 10], 50)
+                print(x.guess.shape)  # (50, 2)
+        """
+        return self._guess
+
+    @guess.setter
+    def guess(self, arr):
+        """Set the initial guess for the variable trajectory.
+
+        The guess should be a 2D array where each row represents the variable value
+        at a particular time point or trajectory node.
+
+        Args:
+            arr: 2D array of shape (n_points, n_vars) where n_vars matches the
+                variable dimension. Can be fewer points than the final trajectory -
+                the solver will interpolate as needed.
+
+        Raises:
+            ValueError: If the array is not 2D or if the second dimension doesn't
+                match the variable dimension
+
+        Example:
+                pos = Variable("pos", shape=(3,))
+                # Create a straight-line trajectory from origin to target
+                n_points = 50
+                pos.guess = np.linspace([0, 0, 0], [10, 5, 3], n_points)
+        """
+        arr = np.asarray(arr, dtype=float)
+        if arr.ndim != 2:
+            raise ValueError(
+                f"Guess must be a 2D array of shape (n_guess_points, {self.shape[0]}), got shape"
+                f" {arr.shape}"
+            )
+        if arr.shape[1] != self.shape[0]:
+            raise ValueError(
+                f"Guess must have second dimension equal to variable dimension {self.shape[0]}, got"
+                f" {arr.shape[1]}"
+            )
+        self._guess = arr
+
+    def append(self, other=None, *, min=-np.inf, max=np.inf, guess=0.0):
+        """Append a new dimension to this variable or merge with another variable.
+
+        This method extends the variable's dimension by either:
+        1. Appending another Variable object (concatenating their dimensions)
+        2. Adding a single new scalar dimension with specified bounds and guess
+
+        The bounds and guesses of both variables are concatenated appropriately.
+
+        Args:
+            other: Another Variable object to append. If None, adds a single scalar
+                dimension with the specified min/max/guess values.
+            min: Minimum bound for the new dimension (only used if other is None).
+                Defaults to -np.inf (unbounded below).
+            max: Maximum bound for the new dimension (only used if other is None).
+                Defaults to np.inf (unbounded above).
+            guess: Initial guess value for the new dimension (only used if other is None).
+                Defaults to 0.0.
+
+        Example:
+            Create a 2D variable and extend it to 3D:
+
+                pos_xy = Variable("pos", shape=(2,))
+                pos_xy.min = [-10, -10]
+                pos_xy.max = [10, 10]
+                pos_xy.append(min=0, max=100)  # Add z dimension
+                print(pos_xy.shape)  # (3,)
+                print(pos_xy.min)  # [-10., -10., 0.]
+                print(pos_xy.max)  # [10., 10., 100.]
+
+            Merge two variables:
+
+                pos = Variable("pos", shape=(3,))
+                vel = Variable("vel", shape=(3,))
+                pos.append(vel)  # Now pos has shape (6,)
+        """
+
+        def process_array(val, is_guess=False):
+            """Process input array to ensure correct shape and type.
+
+            Args:
+                val: Input value to process
+                is_guess: Whether the value is a guess array
+
+            Returns:
+                Processed array with correct shape and type
+            """
+            arr = np.asarray(val, dtype=float)
+            if is_guess:
+                return np.atleast_2d(arr)
+            return np.atleast_1d(arr)
+
+        if isinstance(other, Variable):
+            self._shape = (self.shape[0] + other.shape[0],)
+
+            if self._min is not None and other._min is not None:
+                self._min = np.concatenate([self._min, process_array(other._min)], axis=0)
+
+            if self._max is not None and other._max is not None:
+                self._max = np.concatenate([self._max, process_array(other._max)], axis=0)
+
+            if self._guess is not None and other._guess is not None:
+                self._guess = np.concatenate(
+                    [self._guess, process_array(other._guess, is_guess=True)], axis=1
+                )
+
+        else:
+            self._shape = (self.shape[0] + 1,)
+
+            if self._min is not None:
+                self._min = np.concatenate([self._min, process_array(min)], axis=0)
+
+            if self._max is not None:
+                self._max = np.concatenate([self._max, process_array(max)], axis=0)
+
+            if self._guess is not None:
+                guess_arr = process_array(guess, is_guess=True)
+                if guess_arr.shape[1] != 1:
+                    guess_arr = guess_arr.T
+                self._guess = np.concatenate([self._guess, guess_arr], axis=1)

openscvx/symbolic/hashing.py

@@ -0,0 +1,112 @@
+"""Structural hashing for symbolic problems.
+
+This module provides name-invariant hashing for symbolic optimization problems.
+Two problems with the same mathematical structure will produce the same hash,
+regardless of the variable names used.
+
+This enables efficient caching: if a problem has already been compiled with
+the same structure, the cached compiled artifacts can be reused.
+"""
+
+import hashlib
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from openscvx._version import __version__
+
+if TYPE_CHECKING:
+    from openscvx.symbolic.problem import SymbolicProblem
+
+
+def hash_symbolic_problem(problem: "SymbolicProblem") -> str:
+    """Compute a structural hash of a symbolic optimization problem.
+
+    This function computes a hash that depends only on the mathematical structure
+    of the problem, not on variable names or runtime values. Two problems with the same:
+    - Dynamics expressions (using _slice for canonical variable positions)
+    - Constraints
+    - State/control shapes and boundary condition types
+    - Parameter shapes
+    - Configuration (N, etc.)
+
+    will produce the same hash, regardless of what names are used for variables.
+
+    Notably, the following are NOT included in the hash (allowing solver reuse):
+    - Boundary condition values (initial/final state values)
+    - Bound values (min/max for states and controls)
+    - Parameter values (only shapes are hashed)
+
+    Args:
+        problem: A SymbolicProblem (should be preprocessed for best results,
+                 so that _slice attributes are set on states/controls)
+
+    Returns:
+        A hex string representing the SHA-256 hash of the problem structure
+    """
+    hasher = hashlib.sha256()
+
+    # Include library version to invalidate cache on version changes
+    hasher.update(f"openscvx:{__version__}:".encode())
+
+    # Hash the dynamics
+    hasher.update(b"dynamics:")
+    problem.dynamics._hash_into(hasher)
+
+    # Hash propagation dynamics if present
+    if problem.dynamics_prop is not None:
+        hasher.update(b"dynamics_prop:")
+        problem.dynamics_prop._hash_into(hasher)
+
+    # Hash all constraints (order-invariant within each category)
+    # We compute individual hashes and sort them so that the same set of
+    # constraints produces the same hash regardless of definition order.
+    hasher.update(b"constraints:")
+    for constraint_list in [
+        problem.constraints.ctcs,
+        problem.constraints.nodal,
+        problem.constraints.nodal_convex,
+        problem.constraints.cross_node,
+        problem.constraints.cross_node_convex,
+    ]:
+        # Compute individual hashes for each constraint
+        constraint_hashes = sorted(c.structural_hash() for c in constraint_list)
+        # Hash the count and sorted hashes
+        hasher.update(len(constraint_hashes).to_bytes(4, "big"))
+        for h in constraint_hashes:
+            hasher.update(h)
+
+    # Hash all states and controls explicitly to capture metadata (boundary
+    # condition types) that may not appear in expressions. For example, a state
+    # with dynamics dx/dt = 1.0 doesn't appear in the expression tree, but its
+    # boundary condition types still affect the compiled problem structure.
+    hasher.update(b"states:")
+    for state in problem.states:
+        state._hash_into(hasher)
+
+    hasher.update(b"controls:")
+    for control in problem.controls:
+        control._hash_into(hasher)
+
+    # Hash parameter shapes (not values) from the problem's parameter dict.
+    # This allows the same compiled solver to be reused across parameter sweeps -
+    # only the structure matters for compilation, not the actual values.
+    hasher.update(b"parameters:")
+    hasher.update(str(len(problem.parameters)).encode())  # Hash count for structure
+    for name in sorted(problem.parameters.keys()):
+        value = problem.parameters[name]
+        # Only hash shape, not name - maintains name-invariance
+        if isinstance(value, np.ndarray):
+            hasher.update(str(value.shape).encode())
+        else:
+            hasher.update(b"scalar")
+
+    # Hash configuration
+    hasher.update(f"N:{problem.N}".encode())
+
+    # Hash node intervals for CTCS
+    hasher.update(b"node_intervals:")
+    for interval in problem.node_intervals:
+        hasher.update(f"{interval}".encode())
+
+    return hasher.hexdigest()