openscvx 0.5.3.dev49__tar.gz → 0.5.3.dev50__tar.gz

{openscvx-0.5.3.dev49/openscvx.egg-info → openscvx-0.5.3.dev50}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscvx
-Version: 0.5.3.dev49
+Version: 0.5.3.dev50
 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.5.3.dev49 → openscvx-0.5.3.dev50}/docs/UsersGuide/01_hello_world_brachistochrone.md

@@ -164,6 +164,35 @@ Here, we do _not_ specify an initial or final value for the control but we _do_
 The initial guess must be of shape $(n_u \times n_{\mathrm{nodes}})$, providing an initial guess for each control at every node.
 Technically, we can also provide a `.guess` for states. However, these default to a linear interpolation between initial and final conditions which is sufficient in most cases.
 
+#### Symbolic initial guesses
+
+`.guess` accepts three forms, on both states and controls:
+
+- an array of shape $(n_{\mathrm{nodes}} \times n)$, as above;
+- a **symbolic expression** in other states and controls;
+- a **callable of `tau`**, the normalized node coordinate, returning a symbolic expression.
+
+A guess expression is evaluated at every node, with each referenced variable at its guess value and `tau` running $0 \to 1$ across the grid — the same per-node mental model as dynamics and constraints.
+
+```python
+# Cross-variable: the speed guess follows whatever velocity's guess is
+speed.guess = ox.linalg.Norm(velocity)
+
+# Along the grid: a straight line from p0 to pf
+position.guess = lambda tau: p0 + (pf - p0) * tau
+```
+
+References between guesses are the dependency graph: `speed` above is resolved after `velocity`, and a circular reference raises. Everything is evaluated once, when the `Problem` is built (and again on `reset()` if you assign a new expression between solves), so the solver only ever sees ordinary arrays.
+
+Because evaluation is per node, guess expressions cannot express trajectory-level constructions such as finite differences or cumulative sums. Build those eagerly with NumPy instead:
+
+```python
+velocity.guess = np.gradient(position.guess, axis=0)
+```
+
+!!! Note
+    `time.guess` accepts all three forms, but `time_dilation_guess` remains array-only.
+
 ### Dynamics
 
 Dynamics are defined as a dictionary mapping state names to their time derivatives using symbolic expressions:

{openscvx-0.5.3.dev49 → openscvx-0.5.3.dev50}/openscvx/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.5.3.dev49'
-__version_tuple__ = version_tuple = (0, 5, 3, 'dev49')
+__version__ = version = '0.5.3.dev50'
+__version_tuple__ = version_tuple = (0, 5, 3, 'dev50')
 
-__commit_id__ = commit_id = 'g02b83a786'
+__commit_id__ = commit_id = 'g7ab51dee3'

{openscvx-0.5.3.dev49 → openscvx-0.5.3.dev50}/openscvx/problem.py

@@ -75,6 +75,7 @@ from openscvx.symbolic.expr.control import Control
 from openscvx.symbolic.expr.state import State
 from openscvx.symbolic.expr.time import Time
 from openscvx.symbolic.lower import lower_symbolic_problem
+from openscvx.symbolic.preprocessing import resolve_guess_exprs
 from openscvx.symbolic.problem import SymbolicProblem
 from openscvx.utils import printing, profiling
 from openscvx.utils.caching import (
@@ -958,7 +959,8 @@ class Problem:
         This method reads the current `.guess` values from the original State and
         Control objects and updates the unified representations. This enables warm-starting
         workflows where the initial trajectory guess is updated between solves (e.g., shifting
-        the previous solution).
+        the previous solution). Guesses re-assigned symbolically between solves are
+        evaluated on the node grid first.
 
         Note:
             This only updates the unified representation. The AlgorithmState is
@@ -968,6 +970,8 @@ class Problem:
         if self._lowered is None:
             return
 
+        resolve_guess_exprs(self.symbolic.states, self.symbolic.controls, self.symbolic.N)
+
         # Sync optimization state guesses
         for state in self.symbolic.states:
             if state.guess is not None:

{openscvx-0.5.3.dev49 → openscvx-0.5.3.dev50}/openscvx/symbolic/builder.py

@@ -48,6 +48,7 @@ from openscvx.symbolic.preprocessing import (
     collect_and_assign_slices,
     convert_dynamics_dict_to_expr,
     fill_default_guesses,
+    resolve_guess_exprs,
     validate_and_normalize_constraint_nodes,
     validate_boundary_conditions,
     validate_bounds,
@@ -220,8 +221,9 @@ def preprocess_symbolic_problem(
         states = list(states) + [time]
         time_state = time
 
-    # Fill in default guess if needed (for Time instances)
-    if isinstance(time_state, Time) and time_state.guess is None:
+    # Fill in default guess if needed (for Time instances); a symbolic time guess
+    # is resolved in Phase 2, so it must not be overwritten here.
+    if isinstance(time_state, Time) and time_state.guess is None and time_state._guess_expr is None:
         time_state.guess = time_state._generate_default_guess(N)
 
     # Add CTCS constraints for time bounds
@@ -287,6 +289,9 @@ def preprocess_symbolic_problem(
     # ==================== PHASE 2: Expression Validation ====================
     # Validate all expressions (use unsorted constraints)
     collect_and_assign_slices(states, controls)
+    # Evaluate symbolic guesses now that slices exist and time has been added, and
+    # before augmentation derives the time-dilation guess from time's guess numerically.
+    resolve_guess_exprs(states, controls, N)
     validate_constraints_at_root(constraints.unsorted)
     validate_and_normalize_constraint_nodes(constraints.unsorted, N)
     validate_dynamics_dimension(dynamics_concat, states)
@@ -521,6 +526,17 @@ def add_propagation_states(
 
     # ==================== PHASE 1: Validate Extra States ====================
 
+    # Propagation-only states are integrated from their initial condition, never
+    # seeded from a guess trajectory, so a symbolic guess has nothing to resolve on.
+    for state in states_extra:
+        if state._guess_expr is not None:
+            raise ValueError(
+                f"State '{state.name}': symbolic initial guesses are not supported for "
+                f"propagation-only states. These states are integrated forward from "
+                f"their initial condition after the solve, so they carry no guess "
+                f"trajectory."
+            )
+
     # Validate that extra states don't conflict with optimization state names
     opt_state_names = {s.name for s in states_opt}
     extra_state_names = {s.name for s in states_extra}

{openscvx-0.5.3.dev49 → openscvx-0.5.3.dev50}/openscvx/symbolic/expr/time.py

@@ -1,11 +1,57 @@
-from typing import Any, List, Optional, Union
+from typing import Any, List, Optional, Tuple, Union
 
 import numpy as np
 from pydantic import ConfigDict, field_validator
 
+from openscvx.symbolic.expr.expr import Expr, Leaf
 from openscvx.symbolic.expr.state import State, StateSpec
 from openscvx.symbolic.expr.variable import Variable
 
+#: Key under which the normalized node grid is passed to a lowered guess expression.
+TAU_PARAM = "__tau__"
+
+
+class Tau(Leaf):
+    """Normalized node coordinate, running 0 at the first node to 1 at the last.
+
+    ``Tau`` is internal plumbing for initial guesses, not part of the user-facing
+    vocabulary. A user who needs the node coordinate writes their guess as a
+    callable of one argument::
+
+        pos.guess = lambda tau: p0 + (pf - p0) * tau
+
+    and the library applies that callable once, at assignment, with a ``Tau``
+    instance. The result is an ordinary expression that the guess-resolution pass
+    evaluates node by node (see
+    :func:`openscvx.symbolic.preprocessing.resolve_guess_exprs`).
+
+    Physical time is a ``Time`` state; ``Tau`` is the dimensionless grid
+    coordinate the trajectory is discretized on, and is meaningful only while
+    building a guess.
+    """
+
+    def __init__(self):
+        super().__init__("tau", shape=())
+
+    def check_shape(self) -> Tuple[int, ...]:
+        """Reject tau outside of an initial-guess expression.
+
+        Raises:
+            ValueError: Always. Dynamics, constraints, and costs are shape-checked
+                eagerly, so this fires exactly when a captured ``tau`` has leaked
+                out of the guess it was created for.
+        """
+        raise ValueError(
+            "tau is only meaningful inside initial-guess expressions. It was received "
+            "by a `guess = lambda tau: ...` callable and then used in dynamics, a "
+            "constraint, or a cost, where there is no node grid to evaluate it on. "
+            "Use the `time` state for physical time, or index nodes explicitly with "
+            "`.at(k)`."
+        )
+
+    def __repr__(self) -> str:
+        return "Tau()"
+
 
 class Time(State):
     """Time state variable for trajectory optimization.
@@ -92,15 +138,17 @@ class Time(State):
             min: Minimum time bound.
             max: Maximum time bound.
             guess: Initial guess for the time trajectory. 1D array of shape
-                (N,) or 2D of shape (N, 1). If not provided, a linear
+                (N,), 2D of shape (N, 1), or any symbolic form accepted by
+                :attr:`Variable.guess`. If not provided, a linear
                 interpolation from initial to final is generated.
             time_dilation_min: Absolute minimum bound for time dilation.
                 Defaults to `0.3 * time_final` if not set.
             time_dilation_max: Absolute maximum bound for time dilation.
                 Defaults to `3.0 * time_final` if not set.
             time_dilation_guess: Initial guess for time dilation.
-                1D array of shape (N,) or 2D of shape (N, 1). Overrides
-                the default finite-difference computation.
+                1D array of shape (N,) or 2D of shape (N, 1) — arrays only,
+                symbolic guesses are not accepted here. Overrides the default
+                finite-difference computation.
             uniform_time_grid: If True, constrain the time dilation to be
                 the same across all nodes (uniform time steps). Defaults
                 to False.
@@ -125,11 +173,7 @@ class Time(State):
 
         super().__init__("time", shape=(1,), min=min, max=max, initial=initial, final=final)
 
-        # guess: normalize 1D → 2D before assigning
         if guess is not None:
-            guess = np.asarray(guess, dtype=float)
-            if guess.ndim == 1:
-                guess = guess.reshape(-1, 1)
             self.guess = guess
         if time_dilation_min is not None:
             self.time_dilation_min = time_dilation_min
@@ -167,12 +211,25 @@ class Time(State):
         State.final.fset(self, val)
 
     @Variable.guess.setter
-    def guess(self, arr):
-        """Set the time guess. Accepts 1D (N,) or 2D (N, 1) arrays."""
-        arr = np.asarray(arr, dtype=float)
-        if arr.ndim == 1:
-            arr = arr.reshape(-1, 1)
-        Variable.guess.fset(self, arr)
+    def guess(self, value):
+        """Set the time guess.
+
+        Accepts everything :attr:`Variable.guess` accepts — an array, a symbolic
+        expression, or a callable of tau — and additionally reshapes a 1D ``(N,)``
+        array to ``(N, 1)`` since Time is always shape ``(1,)``. A symbolic guess
+        resolving to one value per node is reshaped the same way at build time::
+
+            time.guess = lambda tau: t0 + (tf - t0) * tau**2
+
+        Note:
+            ``time_dilation_guess`` is a separate, array-only setting; it is not
+            resolved from expressions.
+        """
+        if not isinstance(value, Expr) and not callable(value):
+            value = np.asarray(value, dtype=float)
+            if value.ndim == 1:
+                value = value.reshape(-1, 1)
+        Variable.guess.fset(self, value)
 
     @property
     def time_dilation_min(self) -> Optional[float]:
@@ -199,7 +256,7 @@ class Time(State):
 
     @property
     def time_dilation_guess(self) -> Optional[np.ndarray]:
-        """Initial guess for time dilation, shape (N, 1)."""
+        """Initial guess for time dilation, shape (N, 1). Arrays only."""
         return self._time_dilation_guess
 
     @time_dilation_guess.setter

{openscvx-0.5.3.dev49 → openscvx-0.5.3.dev50}/openscvx/symbolic/expr/variable.py

@@ -4,7 +4,7 @@ from typing import List, Optional, Tuple
 import numpy as np
 from pydantic import BaseModel, ConfigDict
 
-from .expr import Leaf
+from .expr import Expr, Leaf
 
 
 class Variable(Leaf):
@@ -32,6 +32,8 @@ class Variable(Leaf):
         _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)
+        _guess_expr (Expr | None): Symbolic initial guess awaiting resolution to an
+            array at problem-build time; None once resolved
 
     Example:
             # Typically, use State or Control instead of Variable directly:
@@ -51,6 +53,7 @@ class Variable(Leaf):
         self._min = None
         self._max = None
         self._guess = None
+        self._guess_expr = None
 
     def __repr__(self) -> str:
         return f"Var({self.name!r})"
@@ -189,14 +192,16 @@ class Variable(Leaf):
 
     @property
     def guess(self) -> Optional[np.ndarray]:
-        """Get the initial guess for the variable trajectory.
+        """Get the initial guess for the variable trajectory, as an array.
 
         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.
+            over time, or None if no guess is provided. A guess assigned symbolically
+            also reads back as None until the problem is built and the expression has
+            been evaluated on the node grid.
 
         Example:
                 x = Variable("x", shape=(2,))
@@ -207,20 +212,36 @@ class Variable(Leaf):
         return self._guess
 
     @guess.setter
-    def guess(self, arr):
+    def guess(self, value):
         """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.
+        Three forms are accepted:
+
+        - **Array** — a 2D ``(N, n)`` array, one row per trajectory node, validated
+          immediately.
+        - **Expression** — a symbolic expression in other states and controls. It is
+          evaluated once per node at build time, with every referenced variable at its
+          own guess value, so ``speed.guess = ox.linalg.Norm(vel)`` gives the per-node speed
+          of the velocity guess. The expression itself is the dependency graph:
+          referenced guesses are resolved first, and circular references raise.
+        - **Callable of tau** — a one-argument function returning an expression, called
+          once here with a symbolic normalized node coordinate running 0 → 1, for
+          guesses shaped along the grid rather than by other variables:
+          ``pos.guess = lambda tau: p0 + (pf - p0) * tau``.
+
+        Symbolic forms are evaluated node-by-node, so they cannot express
+        trajectory-level constructions (finite differences, cumulative sums). Build
+        those eagerly with numpy instead, e.g. ``vel.guess = np.gradient(pos.guess,
+        axis=0)``.
 
         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.
+            value: An ``(N, n)`` array, an ``Expr``, or a callable taking tau and
+                returning an ``Expr``.
 
         Raises:
-            ValueError: If the array is not 2D or if the second dimension doesn't
-                match the variable dimension
+            ValueError: If an array guess is not 2D or its second dimension doesn't
+                match the variable dimension, or if a callable returns a non-Expr.
+                Shape errors in symbolic guesses surface when the problem is built.
 
         Example:
                 pos = Variable("pos", shape=(3,))
@@ -228,7 +249,29 @@ class Variable(Leaf):
                 n_points = 50
                 pos.guess = np.linspace([0, 0, 0], [10, 5, 3], n_points)
         """
-        arr = np.asarray(arr, dtype=float)
+        if callable(value):
+            from .time import Tau
+
+            expr = value(Tau())
+            if not isinstance(expr, Expr):
+                raise ValueError(
+                    f"{self.__class__.__name__} '{self.name}': guess callable returned "
+                    f"{type(expr).__name__}, not a symbolic expression. The callable "
+                    f"receives the normalized node coordinate as an Expr and must return "
+                    f"one built from openscvx operations, e.g. "
+                    f"lambda tau: p0 + (pf - p0) * tau. Computing on tau with numpy or "
+                    f"jax.numpy will not work — the guess is composed symbolically and "
+                    f"only evaluated on the node grid later. For a purely numeric guess, "
+                    f"assign the array itself."
+                )
+            value = expr
+
+        if isinstance(value, Expr):
+            self._guess_expr = value
+            self._guess = None
+            return
+
+        arr = np.asarray(value, dtype=float)
         if arr.ndim != 2:
             raise ValueError(
                 f"{self.__class__.__name__} '{self.name}': guess expected 2D array of shape"
@@ -240,6 +283,7 @@ class Variable(Leaf):
                 f" {self.shape[0]}, got {arr.shape[1]}"
             )
         self._guess = arr
+        self._guess_expr = None
 
     def append(
         self,
@@ -267,6 +311,9 @@ class Variable(Leaf):
             guess: Initial guess value for the new dimension (only used if other is None).
                 Defaults to 0.0.
 
+        Raises:
+            ValueError: If either variable still carries an unresolved symbolic guess.
+
         Example:
             Create a 2D variable and extend it to 3D:
 
@@ -285,6 +332,15 @@ class Variable(Leaf):
                 pos.append(vel)  # Now pos has shape (6,)
         """
 
+        for var in (self, other):
+            if isinstance(var, Variable) and var._guess_expr is not None:
+                raise ValueError(
+                    f"{var.__class__.__name__} '{var.name}' has a symbolic initial guess "
+                    f"that has not been evaluated yet, so it cannot be concatenated. "
+                    f"Symbolic guesses are resolved when the problem is built; append "
+                    f"dimensions first, or assign an array guess."
+                )
+
         def process_array(val, is_guess=False):
             """Process input array to ensure correct shape and type.
 

{openscvx-0.5.3.dev49 → openscvx-0.5.3.dev50}/openscvx/symbolic/lowerers/jax/state.py

@@ -1,16 +1,18 @@
 """JAX visitors for state/time expressions.
 
-Visitors: State, Time
+Visitors: State, Time, Tau
 
 Lowers a ``State`` leaf to a JAX function that slices the corresponding entries
 out of the unified state vector ``x``, using the slice assigned during
 unification. ``Time`` is a ``State`` subclass and shares the same visitor;
 lowering a state whose slice is still unset is a usage error and raises.
+``Tau`` — the normalized node coordinate used by initial-guess expressions —
+reads its value off the node grid carried in ``params``.
 """
 
 # Expression types to handle — uncomment as you paste visitors:
 from openscvx.symbolic.expr.state import State
-from openscvx.symbolic.expr.time import Time
+from openscvx.symbolic.expr.time import TAU_PARAM, Tau, Time
 from openscvx.symbolic.lowerers.jax._registry import visitor  # noqa: F401
 
 
@@ -35,3 +37,19 @@ def _visit_state(lowerer, node: State):
     if sl is None:
         raise ValueError(f"State {node.name!r} has no slice assigned")
     return lambda x, u, node, params: x[sl]
+
+
+@visitor(Tau)
+def _visit_tau(lowerer, node: Tau):
+    """Lower the normalized node coordinate to a JAX function.
+
+    The tau grid is supplied by the guess-resolution pass under the reserved
+    ``params`` key, so tau is read at the node currently being evaluated.
+
+    Args:
+        node: Tau expression node
+
+    Returns:
+        Function (x, u, node, params) -> tau at that node
+    """
+    return lambda x, u, node, params: params[TAU_PARAM][node]

{openscvx-0.5.3.dev49 → openscvx-0.5.3.dev50}/openscvx/symbolic/preprocessing.py

@@ -687,7 +687,8 @@ def fill_default_guesses(states: List[State], N: int) -> None:
     """Fill in default linspace guesses for states with guess=None.
 
     For states with both initial and final conditions set, generates a linear
-    interpolation from initial to final values.
+    interpolation from initial to final values. States carrying a symbolic guess
+    are left alone — theirs is filled by :func:`resolve_guess_exprs`.
 
     This function modifies states in-place.
 
@@ -698,6 +699,8 @@ def fill_default_guesses(states: List[State], N: int) -> None:
     from openscvx.init import linspace
 
     for state in states:
+        if state._guess_expr is not None:
+            continue
         if state.guess is None and state.initial is not None and state.final is not None:
             # state.initial and state.final are already numpy arrays of values
             # (the setter handles parsing tuples like ("free", value))
@@ -707,6 +710,151 @@ def fill_default_guesses(states: List[State], N: int) -> None:
             )
 
 
+def resolve_guess_exprs(states: List[State], controls: List[Control], N: int) -> None:
+    """Evaluate symbolic initial guesses on the node grid, in dependency order.
+
+    A symbolic guess (``speed.guess = ox.linalg.Norm(vel)``, ``pos.guess = lambda tau: ...``)
+    defines the guess *per node*: the expression is evaluated at every node with each
+    referenced variable at its own guess value and tau running 0 → 1 across the grid —
+    the same mental model as dynamics and constraints. Guesses that reference other
+    symbolic guesses are resolved first; the expressions themselves are the dependency
+    graph.
+
+    Each resolved variable has its ``_guess`` array filled and its pending expression
+    cleared, so everything downstream sees an ordinary eager guess. Variables without
+    a symbolic guess are untouched, and the function returns immediately when there
+    are none.
+
+    This function modifies variables in-place, and requires slices to have been
+    assigned (see :func:`collect_and_assign_slices`).
+
+    Args:
+        states: State objects whose guesses may be referenced or resolved
+        controls: Control objects whose guesses may be referenced or resolved
+        N: Number of discretization nodes
+
+    Raises:
+        ValueError: If a guess references a variable outside this problem, if the
+            guesses reference each other circularly, or if an evaluated guess does
+            not have shape ``(N, n)``.
+    """
+    import jax
+    import jax.numpy as jnp
+
+    from openscvx.symbolic.expr.parameter import Parameter
+    from openscvx.symbolic.expr.time import TAU_PARAM
+    from openscvx.symbolic.lower import lower_to_jax
+
+    variables = list(states) + list(controls)
+    pending = [var for var in variables if var._guess_expr is not None]
+    if not pending:
+        return
+
+    known = {id(var) for var in variables}
+    dependencies = {id(var): _guess_dependencies(var, known) for var in pending}
+
+    # Kahn's algorithm over the pending variables: a guess is ready once every
+    # pending variable it references has been resolved.
+    order, resolved, unordered = [], set(), list(pending)
+    while unordered:
+        ready = [
+            var
+            for var in unordered
+            if all(
+                id(dep) not in dependencies or id(dep) in resolved for dep in dependencies[id(var)]
+            )
+        ]
+        if not ready:
+            raise ValueError(
+                f"Circular initial-guess dependency among "
+                f"{sorted(var.name for var in unordered)}. Each guess expression is "
+                f"evaluated from the guesses it references, so the references cannot "
+                f"form a cycle — break it by giving one of them an array guess."
+            )
+        order.extend(ready)
+        resolved.update(id(var) for var in ready)
+        unordered = [var for var in unordered if id(var) not in resolved]
+
+    tau = jnp.linspace(0.0, 1.0, N)
+    nodes = jnp.arange(N)
+    for var in order:
+        expr = var._guess_expr
+        params = {TAU_PARAM: tau}
+
+        def bind_parameter(node, params=params):
+            if isinstance(node, Parameter):
+                params[node.name] = node.value
+
+        traverse(expr, bind_parameter)
+        fn = lower_to_jax(expr)
+        values = jax.vmap(fn, in_axes=(0, 0, 0, None))(
+            _guess_trajectory(states, N), _guess_trajectory(controls, N), nodes, params
+        )
+
+        guess = np.asarray(values, dtype=float)
+        if guess.ndim == 1 and var.shape[0] == 1:
+            guess = guess.reshape(-1, 1)
+        if guess.shape != (N, var.shape[0]):
+            raise ValueError(
+                f"{var.__class__.__name__} '{var.name}': guess expression evaluated to "
+                f"shape {guess.shape}, expected ({N}, {var.shape[0]}). The expression is "
+                f"evaluated once per node, so it must produce one row of "
+                f"{var.shape[0]} value(s) per node."
+            )
+        var._guess = guess
+        var._guess_expr = None
+
+
+def _guess_dependencies(var: Variable, known: Set[int]) -> List[Variable]:
+    """Collect the variables a symbolic guess reads, in first-seen order.
+
+    Args:
+        var: Variable carrying the pending guess expression
+        known: Ids of the variables belonging to this problem
+
+    Raises:
+        ValueError: If the expression references a variable outside the problem
+    """
+    dependencies = {}
+
+    def visit(node):
+        if not isinstance(node, Variable):
+            return
+        if id(node) not in known:
+            raise ValueError(
+                f"{var.__class__.__name__} '{var.name}': guess expression references "
+                f"{node.__class__.__name__} '{node.name}', which is not one of this "
+                f"problem's states or controls. Guess expressions may only reference "
+                f"variables passed to Problem."
+            )
+        dependencies.setdefault(id(node), node)
+
+    traverse(var._guess_expr, visit)
+    return list(dependencies.values())
+
+
+def _guess_trajectory(variables: List[Variable], N: int) -> np.ndarray:
+    """Assemble the (N, n) guess trajectory for a set of states or controls.
+
+    Columns of variables whose guess is not yet resolved are left at zero;
+    dependency ordering guarantees the columns a guess expression reads are filled.
+    """
+    n = max((var._slice.stop for var in variables), default=0)
+    trajectory = np.zeros((N, n))
+    for var in variables:
+        if var._guess is None:
+            continue
+        if var._guess.shape[0] != N:
+            raise ValueError(
+                f"{var.__class__.__name__} '{var.name}': guess spans "
+                f"{var._guess.shape[0]} nodes but the problem has N={N}. Guess "
+                f"expressions are evaluated node by node, so every guess they read "
+                f"must cover the whole grid."
+            )
+        trajectory[:, var._slice] = var._guess
+    return trajectory
+
+
 def validate_boundary_conditions(states: List[State]) -> None:
     """Validate that all states have initial and final boundary conditions set.
 
@@ -908,6 +1056,9 @@ def validate_propagation_input_types(
 def validate_guesses(variables: List[Variable]) -> None:
     """Validate that all variables have initial guesses set.
 
+    A guess assigned symbolically counts as set even though it has not been
+    evaluated to an array yet.
+
     Args:
         variables: List of Variable objects (State or Control) to validate
 
@@ -915,12 +1066,16 @@ def validate_guesses(variables: List[Variable]) -> None:
         ValueError: If any variable is missing a guess
     """
     for var in variables:
-        if var.guess is None:
+        if var.guess is None and var._guess_expr is None:
             if isinstance(var, Control):
                 raise ValueError(
                     f"Control '{var.name}' is missing initial guess. "
-                    f"Please set {var.name}.guess (controls require explicit guesses)"
+                    f"Please set {var.name}.guess to an array, an expression in other "
+                    f"states and controls, or a callable of tau "
+                    f"(controls require explicit guesses)"
                 )
             raise ValueError(
-                f"State '{var.name}' is missing initial guess. Please set {var.name}.guess"
+                f"State '{var.name}' is missing initial guess. Please set {var.name}.guess "
+                f"to an array, an expression in other states and controls, or a "
+                f"callable of tau"
             )

{openscvx-0.5.3.dev49 → openscvx-0.5.3.dev50/openscvx.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscvx
-Version: 0.5.3.dev49
+Version: 0.5.3.dev50
 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