openscvx 0.3.2.dev315__tar.gz → 0.3.2.dev317__tar.gz

{openscvx-0.3.2.dev315 → openscvx-0.3.2.dev317}/.github/workflows/_docs.yml

@@ -60,7 +60,7 @@ jobs:
 
     - name: Build documentation (check only)
       if: ${{ !inputs.version }}
-      run: mkdocs build
+      run: mkdocs build --strict
 
     - name: Fetch gh-pages branch
       if: inputs.version

{openscvx-0.3.2.dev315/openscvx.egg-info → openscvx-0.3.2.dev317}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscvx
-Version: 0.3.2.dev315
+Version: 0.3.2.dev317
 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.dev315 → openscvx-0.3.2.dev317}/docs/UnderTheHood/vectorization_and_vmapping.md

@@ -511,8 +511,5 @@ for state in problem.states:
 
 ## See Also
 
-- [Basic Problem Setup](../Usage/basic_problem_setup.md) - How to define problems
-- [API: State](../Usage/api_state.md) - State class documentation
-- [API: Control](../Usage/api_control.md) - Control class documentation
-- [API: Problem](../Usage/api_problem.md) - Main problem class
-- [Discretization](../Overview/discretization.md) - How discretization works in OpenSCvx
+- [Hello world tutorial](../UsersGuide/01_hello_world_brachistochrone.md) - How to define problems
+- [Discretization](../Foundations/discretization.md) - How discretization works in OpenSCvx

openscvx-0.3.2.dev317/docs/UsersGuide/00_introduction.md

@@ -0,0 +1,44 @@
+# Users Guide
+
+Welcome to the OpenSCvx Users Guide. This section aims to provides a progressive and useful introduction to trajectory optimization with OpenSCvx, starting from first principles and building toward complex, representative problems.
+
+## Learning Path
+
+The tutorials are designed to be read in order. Each builds on concepts from the previous, introducing new features in the context of increasingly realistic problems.
+
+| Tutorial | Problem | You Will Learn |
+|----------|---------|----------------|
+| [01 Hello Brachistochrone](01_hello_world_brachistochrone.md) | Minimum-time descent curve | Core API: states, controls, dynamics, time, CTCS constraints, solving |
+| [02 Drone Racing](02_drone_racing_constraints.md) | Racing through gates | Nodal constraints, `.at()`, `.over()`, `.convex()`, keyframe initialization |
+| [03 Obstacle Avoidance](03_obstacle_avoidance_vmap.md) | 6-DOF navigation | Quaternion dynamics, spatial utilities, `ox.Parameter`, `ox.Vmap` |
+| [04 Viewpoint Constraints](04_viewpoint_constraints.md) | Perception-constrained racing | Custom symbolic functions, Vmap with custom functions, attitude initialization |
+| [05 Visualization](05_visualization.md) | — | 2D plots with Plotly, 3D interactive visualization with viser, Plotly-in-viser |
+| [06 Dubin's Car](06_logic.md) | Conditional path planning | Conditional statements, signal temporal logic (STL) |
+| [07 Multi-Link Arms](07_lie.md) | Articulated robot control | Lie algebra, propagated states |
+
+## Quick Start
+
+If you're new to OpenSCvx, start with [Hello Brachistochrone](01_hello_world_brachistochrone.md). By the end of that tutorial you will have solved your first trajectory optimization problem and understand the core workflow:
+
+1. Define states and controls with `ox.State` and `ox.Control`
+2. Specify dynamics as a dictionary of symbolic expressions
+3. Add constraints using `ox.ctcs()` for continuous enforcement
+4. Create a `Problem`, initialize, solve, and post-process
+
+From there, each subsequent tutorial introduces new capabilities while reinforcing the fundamentals.
+
+## Interactive Notebooks
+
+Some tutorials include Google Colab notebooks for interactive learning:
+
+- [03 6-DOF Obstacle Avoidance ![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1xLPC_UJWC35oPRIAY3vkxi8WEYnHCysQ?usp=sharing)
+- [04 Viewpoint Constraints ![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1b3NEx288h4r4HuvCOj-fexmt90PPhKUw?usp=sharing)
+
+These notebooks let you run the examples without local setup and experiment with parameters in real-time.
+
+## Beyond the Tutorials
+
+After completing the tutorials, explore:
+
+- [Examples](../Examples/abstract/brachistochrone.md) — Complete problem implementations across domains
+- [API Reference](../Reference/problem.md) — Detailed documentation for all classes and functions

openscvx-0.3.2.dev317/docs/UsersGuide/01_hello_world_brachistochrone.md

@@ -0,0 +1,320 @@
+# 01 Hello Brachistochrone
+
+In this _hello world_ tutorial we will introduce the reader to the fundamental concepts and API needed to define and solve a problem using OpenSCvx as well as how the results can be accessed.
+Our example of choice in this endeavor is the _Brachistochrone problem_, which we briefly describe below before delving into the implementation.
+Finally, we will lay out some further reading and tease the next tutorial for the interested reader.
+
+This tutorial covers:
+
+- Problem creation
+- Variable instantiation
+- Dynamics and constraint definition
+- Solving the problem
+- Accessing results
+
+## The Brachistochrone Problem
+
+The [Brachistochrone problem](https://en.wikipedia.org/wiki/Brachistochrone_curve) is concerned with finding the fastest path between 2 points under the influence of gravity and without friction.
+Bernouli originally posed the problem as:
+
+> _Given two points A and B in a vertical plane, what is the curve traced out by a point acted on only by gravity, which starts at A and reaches B in the shortest time._
+
+As with most good things in life, this can be written as an optimal control problem in the Mayer form as:
+
+$$
+\begin{align}
+\min_{\mathbf{x}, \mathbf{u}, t_f}\ &t_f & \\
+\mathrm{s.t.}\ &\dot{\mathbf{x}}(t) = f(\mathbf{x}(t), \mathbf{u}(t)) & \forall t\in[0, t_f], \quad &\textrm{dynamics} \\
+&\mathbf{x}_{\min} \leq \mathbf{x}(t) \leq \mathbf{x}_{\max} & \forall t\in[0, t_f], \quad &\textrm{state bounds} \\
+&\mathbf{u}_{\min} \leq \mathbf{u}(t) \leq \mathbf{u}_{\max} & \forall t\in[0, t_f], \quad &\textrm{control bounds} \\
+&\mathbf{x}(0) = \mathbf{x}_{\mathrm{init}}, & & \textrm{initial}\\
+&\mathbf{p}(t_f) = \mathbf{p}_{\mathrm{final}} & & \textrm{terminal}
+\end{align}
+$$
+
+where the state $\mathbf{x} = [x, y, v]^\top$ consists of 2D position $\mathbf{p} = [x, y]^\top$ and speed $v$, the control $\mathbf{u} = \theta$ is the angle from vertical, and the dynamics are given by:
+
+$$
+f(\mathbf{x}, \mathbf{u}) = \begin{bmatrix} v \sin(\theta) \\ -v \cos(\theta) \\ g \cos(\theta) \end{bmatrix}
+$$
+
+Note that the terminal velocity is unconstrained.
+
+This problem is particularly interesting to us because of two main reasons: 
+
+1. It is a very nice, small toy problem we can use to introduce the core concepts of OpenSCvx. It is quick to formulate and quick to solve.
+2. _It has an analytical solution._ The Brachistochrone problem was solved by none other than Isaac Newton in 1697, who showed that the optimal path is given by a cycloid, the curve traced by a point on the rim of a rolling wheel:
+
+$$
+\begin{align}
+x(\phi) &= r(\phi - \sin\phi) \\
+y(\phi) &= r(1 - \cos\phi)
+\end{align}
+$$
+
+where $\phi \in [0, \phi_f]$ is the curve parameter and $r$ is the radius of the generating circle, determined by the boundary conditions. The minimum time of descent is:
+
+$$
+t_f^* = \sqrt{\frac{r}{g}} \phi_f
+$$
+
+Because of these advantageous properties the Brachistochrone problem is extensively leveraged as a [unit test](https://github.com/OpenSCvx/OpenSCvx/blob/main/tests/test_brachistochrone.py).
+We would highly recommend that anyone setting out to develop some kind of optimization software do the same.
+It may not be necessary _nor_ sufficient, but a lot of things have to be working properly to solve Brachistochrone problem.
+
+## Creating an OpenSCvx Problem
+
+During the development of OpenSCvx we spent a great deal of time trying to make the library as easy to work with as possible.
+If it isn't easy to use, people will just write their own.
+For that reason, we took inspiration from fantastic libraries such as [NumPy](https://github.com/numpy/numpy), [JAX](https://github.com/jax-ml/jax), and [CVXPY](https://github.com/cvxpy/cvxpy) and developed a symbolic expression system.
+
+This not only allows us to keep the syntax close to the mathematical notation but also enables us to do lots of preprocessing, validation, canonicalization, and augmentation under the hood without the user ever having to know about it if they choose not to.
+It also means that we can keep the syntax similar to popular libraries such as Numpy and JAX to reduce the learning curve for new users.
+
+Before we begin defining our problem we can take care of our imports as well as some high-level parameters.
+Typically, OpenSCvx is imported as `ox` for brevity. This will be the standard throughout these tutorials
+
+```python
+import openscvx as ox
+```
+
+Next, we can define our number of discrete decision nodes `n`, our initial guess for the completion time `total_time`, and define the gravitational acceleration `g`
+
+```python
+n = 2
+total_time = 2.0
+g = 9.81
+```
+
+Note that `total_time` is an _initial guess_ for the time. We will solve this as a free final-time problem and find the optimal solution.
+
+### Variable Definition
+
+Now, we can start implementing the Brachistochrone problem, starting by creating the necessary state and control variables.
+Each `ox.State` can be instantiated with a name and shape such as
+
+```python
+position = ox.State("position", shape=(2,))  # 2D position [x, y]
+```
+
+Then, we need to define the bounds. In this example we arbitrarily choose a 10 by 10 box for our position
+
+```python
+position.max = [10.0, 10.0]
+position.min = [0.0, 0.0]
+```
+
+Finally, we must define the initial and final conditions. In this case we will find the Brachistochrone curve from $[0, 10]$ to $[10, 5]$ and set the values accordingly:
+
+```python
+position.initial = np.array([0.0, 10.0])
+position.final = [10.0, 5.0]
+```
+
+All of these values can be either raw Python lists, NumPy or JAX arrays.
+We can then similarly define the velocity state and it's bounds, resulting in the following code defining both states:
+
+```python
+# Define state components
+position = ox.State("position", shape=(2,))  # 2D position [x, y]
+position.max = np.array([10.0, 10.0])
+position.min = np.array([0.0, 0.0])
+position.initial = np.array([0.0, 10.0])
+position.final = [10.0, 5.0]
+
+velocity = ox.State("velocity", shape=(1,))  # Scalar speed
+velocity.max = np.array([10.0])
+velocity.min = np.array([0.0])
+velocity.initial = np.array([0.0])
+velocity.final = [("free", 10.0)]
+
+# Define list of all states (needed for Problem and constraints)
+states = [position, velocity]
+```
+
+The `.final` value of Velocity is defined as a tuple `("free", 10.0)`. This sets the corresponding value as "free" for the optimizer to choose.
+This is how we can encode that the final velocity is unconstrained. The numerical value is necessary as an initial guess.
+When only a value is specified as in the case of `position`, the values are assumed to be fixed.
+
+To summarize, we can use the following syntax to define the initial and final conditions:
+
+- Fixed value: `value` or `("fixed", value)`
+- Free variable: `("free", guess)` - Can be optimized within bounds
+- Minimize: `("minimize", guess)` - Variable to be minimized
+- Maximize: `("maximize", guess)` - Variable to be maximized
+
+For our control `theta` we can follow a similar syntax to define the symbolic `ox.Control` object:
+
+```python
+# Define control
+theta = ox.Control("theta", shape=(1,))  # Angle from vertical
+theta.max = np.array([100.5 * jnp.pi / 180])
+theta.min = np.array([0.0])
+theta.guess = np.linspace(5 * jnp.pi / 180, 100.5 * jnp.pi / 180, n).reshape(-1, 1)
+
+controls = [theta]
+```
+
+Here, we do _not_ specify an initial or final value for the control but we _do_ need to specify an initial guess.
+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.
+
+### Dynamics
+
+Dynamics are defined as a dictionary mapping state names to their time derivatives using symbolic expressions:
+
+```python
+# Define dynamics as dictionary mapping state names to their derivatives
+dynamics = {
+    "position": ox.Concat(
+        velocity[0] * ox.Sin(theta[0]),  # x_dot
+        -velocity[0] * ox.Cos(theta[0]),  # y_dot
+    ),
+    "velocity": g * ox.Cos(theta[0]),
+}
+```
+
+!!! Note
+    Every state passed to the problem must have a matching element in the dynamics dictionary under the same name.
+
+The symbolic expressions support standard Python operators:
+
+- Arithmetic: `+`, `-`, `*`, `/`, `**`
+- Matrix multiplication: `@`
+- Comparisons: `<=`, `>=`, `==` (for constraint definitions, see below)
+- Indexing: `[...]`
+- Transpose: `.T`
+
+Common symbolic functions include:
+
+- `ox.Concat()`: Concatenation
+- `ox.Sin()`/`ox.Cos()`: Trigonometric functions
+- `ox.linalg.Norm()`: Vector/matrix norms
+
+!!! Note
+    Under the hood, symbolic expressions are compiled using JAX, so use `jax.numpy` for numerical constants and functions when needed.
+
+### Constraints (Continuous)
+
+We already defined the box constraints when we instantiated the variables.
+These are enforced at the discrete decision nodes automatically.
+However, OpenSCvx offers another way to enforce constraints: we can also enforce the constraints _between_ the discrete nodes.
+We call this continuous-time constraint-satisfaction (CTCS).
+While the full description of CTCS is beyond the scope of this tutorial, what's important is that this is handled internally without user interaction.
+
+We can define the boundary constraints as inequalities _i.e._ `state.min <= state` and `state <= state.max`.
+To mark these as CTCS constraints we simply wrap them in `ox.ctcs(...)`
+
+```python
+# Generate box constraints for all states
+constraints = []
+for state in states:
+    constraints.extend(
+        [
+            ox.ctcs(state <= state.max),
+            ox.ctcs(state.min <= state)
+        ]
+    )
+```
+
+This style of constraint definition as a list should feel familiar to CVXPY users.
+Note that we do not need to specify continuous box constraints for the controls.
+This is because, by default, the controls are interpolated using first-order hold.
+Therefore, by constraining the discrete nodes to lie within the bounds we can trivially see that the continuous case is guaranteed as well.
+
+We will explore the various forms of constraints supported by OpenSCvx more in the [next tutorial](02_drone_racing_constraints.md)
+
+### Time
+
+The last remaining piece we need is `Time`. OpenSCvx allows for free final-time problems with non-constant spacing.
+We can define our time object similar to a `State` object, including the initial and final values as well as the min. and max. bounds.
+Similar to the states the `final` value is defined as a tuple indicating that the final time is to be minimized as well as providing an initial guess for the total time.
+
+```python
+time = ox.Time(
+    initial=0.0,
+    final=("minimize", total_time),
+    min=0.0,
+    max=total_time,
+)
+```
+
+OpenSCvx treats the `Time` object like any other state; it can be used to formulate time-dependent dynamics or constraints.
+This is a more advanced subject for later tutorials.
+
+### Defining the Problem
+
+Now we have everything we need to instantiate the `Problem` with our `dynamics`, `states`, `controls`, `time`, `constraints`, as well as the number of nodes `N`
+
+```python
+problem = ox.Problem(
+    dynamics=dynamics,
+    states=states,
+    controls=controls,
+    time=time,
+    constraints=constraints,
+    N=n,
+)
+```
+
+### Solving the Problem
+
+Solving the problem is split into three steps:
+
+1. `problem.initialize()` initializes the problem, validating, preprocessing, canonicalizing, and augmenting the symbolic expressions before lowering them to JAX and CVXPY code.
+2. `problem.solve()` iteratively solves the OCP and generates the discrete state and control solution at the decision nodes.
+3. `problem.post_process()` propagates the nodal solution at high temporal fidelity. This lets us generate high resolution trajectories decoupled from the number of optimization nodes.
+
+```python
+problem.initialize()
+results = problem.solve()
+results = problem.post_process()
+```
+
+Both `.solve()` and `.post_process()` return an `OptimizationResults` object with the former containing only the nodal solution while the latter also includes the high-fidelity trajectories.
+
+### Accessing the results
+
+But how can we easily access the results? Could we _somehow_ leverage the symbolic variables to make this easy?
+
+Fear not; once a problem has been solved and post-processed we can access the results using the exact same variable names we defined earlier for our states and controls.
+We can do so both for the discrete decision nodes in `results.nodes` and the high-resolution `results.trajectory` _e.g._
+
+```python
+pos_nodes = results.nodes["position"]
+theta_traj = results.trajectory["theta"]
+```
+
+### Visualizing the Results
+
+OpenSCvx provides built-in plotting utilities for quick visualization of your results. The simplest way to see your solution is with `plot_states()` and `plot_controls()`:
+
+```python
+from openscvx.plotting import plot_states, plot_controls
+
+# Plot all state trajectories in a subplot grid
+plot_states(results, ["position", "velocity"]).show()
+
+# Plot control trajectories
+plot_controls(results, ["theta"]).show()
+```
+
+These functions create interactive Plotly figures showing:
+
+- **Green lines**: High-fidelity propagated trajectory
+- **Cyan markers**: Discrete optimization nodes
+- **Red dashed lines**: Variable bounds
+
+For the Brachistochrone problem, you'll see the position trace out the characteristic cycloid curve, while the control angle `theta` smoothly varies from near-vertical at the start to nearly horizontal at the end.
+
+For more advanced visualization options including 3D interactive plots, see [Tutorial 05: Visualization](05_visualization.md).
+
+## Further Reading
+
+- [Complete Brachistochrone Example](../Examples/abstract/brachistochrone.md)
+- [Drone Racing: Constraints and 3DoF Dynamics](02_drone_racing_constraints.md)
+- [Visualization: 2D Plots and 3D Interactive](05_visualization.md)
+
+At this point you are well-equipped to go out and start constructing trajectory optimization problems.
+If you are so-inclined you can dive into the [API reference documentation](../Reference/problem.md) or the [examples](../Examples/drone/drone_racing.md) and figure the rest out yourself.
+For the interested reader, we will continue our guided tour of the various features in OpenSCvx by examining a slightly more interesting example which shows off different kinds of constraints we can define.

openscvx-0.3.2.dev317/docs/UsersGuide/02_drone_racing_constraints.md

@@ -0,0 +1,289 @@
+# 02 Drone Racing: Constraints and 3-DOF Dynamics
+
+In this tutorial we build on the concepts from [Hello Brachistochrone](01_hello_world_brachistochrone.md) to tackle a more interesting problem: time-optimal drone racing through gates.
+We will introduce 3D double-integrator dynamics and explore the various constraint types available in OpenSCvx.
+
+This tutorial covers:
+
+- 3DoF double-integrator (point mass) dynamics
+- Nodal constraints with `.at()`
+- Convex constraint marking with `.convex()`
+- Keyframe-based initialization with `ox.init.linspace()`
+
+## The Drone Racing Problem
+
+We consider a simplified drone racing scenario where a point-mass drone must fly through a sequence of gates in minimum time, returning to its starting position (loop closure).
+
+$$
+\begin{align}
+\min_{\mathbf{x}, \mathbf{u}, t_f}\ &t_f & \\
+\mathrm{s.t.}\ &\dot{\mathbf{x}}(t) = f(\mathbf{x}(t), \mathbf{u}(t)) & \forall t\in[0, t_f], \quad &\textrm{dynamics} \\
+&\mathbf{x}_{\min} \leq \mathbf{x}(t) \leq \mathbf{x}_{\max} & \forall t\in[0, t_f], \quad &\textrm{state bounds} \\
+&\mathbf{u}_{\min} \leq \mathbf{u}(t) \leq \mathbf{u}_{\max} & \forall t\in[0, t_f], \quad &\textrm{control bounds} \\
+&\lVert A_i \mathbf{p}(t_i) - \mathbf{c}_i \rVert_\infty \leq 1 & \forall i \in [1, N_{\mathrm{gates}}], \quad &\textrm{gate constraints} \\
+&\mathbf{x}(0) = \mathbf{x}_{\mathrm{init}}, & & \textrm{initial}\\
+&\mathbf{p}(t_f) = \mathbf{p}_{\mathrm{init}} & & \textrm{loop closure}
+\end{align}
+$$
+
+where the state $\mathbf{x} = [\mathbf{p}^\top, \mathbf{v}^\top]^\top$ consists of 3D position and velocity, and the control $\mathbf{u} = \mathbf{f}$ is the force vector. The double-integrator dynamics are:
+
+$$
+f(\mathbf{x}, \mathbf{u}) = \begin{bmatrix} \mathbf{v} \\ \frac{1}{m}\mathbf{f} + \mathbf{g} \end{bmatrix}
+$$
+
+The gate constraints use an infinity-norm formulation: the drone must pass through an ellipsoidal region defined by the matrix $A_i$ centered at $\mathbf{c}_i$ at specific times $t_i$.
+
+## Implementation
+
+### Variables
+
+The state and control definitions follow the same pattern as the Brachistochrone problem, now in 3D:
+
+```python
+import openscvx as ox
+
+# 3D position and velocity states
+position = ox.State("position", shape=(3,))
+position.max = np.array([200.0, 100, 50])
+position.min = np.array([-200.0, -100, 15])
+position.initial = np.array([10.0, 0, 20])
+position.final = [10.0, 0, 20]  # Loop closure: return to start
+
+velocity = ox.State("velocity", shape=(3,))
+velocity.max = np.array([100, 100, 100])
+velocity.min = np.array([-100, -100, -100])
+velocity.initial = np.array([0, 0, 0])
+velocity.final = [("free", 0), ("free", 0), ("free", 0)]
+
+# 3D force control
+force = ox.Control("force", shape=(3,))
+f_max = 4.179 * 9.81
+force.max = np.array([f_max, f_max, f_max])
+force.min = np.array([-f_max, -f_max, -f_max])
+force.guess = np.repeat(np.array([[0.0, 0, 10]]), n, axis=0)
+
+states = [position, velocity]
+controls = [force]
+```
+
+Note that `position.final` equals `position.initial`. This enforces loop closure, requiring the drone to return to its starting position.
+
+### Dynamics
+
+The double-integrator dynamics are straightforward: velocity is the derivative of position, and acceleration (force/mass plus gravity) is the derivative of velocity:
+
+```python
+m = 1.0  # Mass
+g_const = -9.81  # Gravity (negative z)
+
+dynamics = {
+    "position": velocity,
+    "velocity": (1 / m) * force + np.array([0, 0, g_const]),
+}
+```
+
+This is simpler than the Brachistochrone dynamics because there's no angle—we directly control the force vector.
+
+### Path Constraints
+
+As before, we enforce box constraints on states continuously:
+
+```python
+constraints = []
+for state in states:
+    constraints.extend([
+        ox.ctcs(state <= state.max),
+        ox.ctcs(state.min <= state)
+    ])
+```
+
+With our states now in 3D it becomes clear to us why such constraints are also referred to as _path constraints_; we are enforcing the entire path to follow the constraints, not just the discrete nodes.
+
+### Discrete Constraints: Gate Passage
+
+The key new concept is **nodal constraints**, constraints enforced at specific nodes rather than continuously.
+Gate passage constraints are a perfect example: the drone must be within each gate at a specific node.
+
+We use the `.at([node])` method to specify which nodes the constraint applies to:
+
+```python
+# Gate passage constraint at a specific node
+gate_constraint = (
+    ox.linalg.Norm(A_gate @ position - c_gate, ord="inf") <= 1.0
+).at([node])
+```
+
+The infinity norm $\lVert \cdot \rVert_\infty$ defines a box-shaped region, which when combined with the scaling matrix `A_gate` creates an ellipsoidal gate region.
+
+It should be noted that by default constraints are interpreted as nodal constraints, however they are applied to _all_ nodes when not otherwise noted. Writing
+
+```python
+gate_constraint = (
+    ox.linalg.Norm(A_gate @ position - c_gate, ord="inf") <= 1.0
+)
+```
+
+would result in all nodes being constrained to lie within the gate.
+
+There is a similar syntax for defining CTCS constraints: we can use the `.over((k, j))` method to define a continuous interval between nodes where a constraint should be enforced:
+
+```python
+# Enforce altitude constraint continuously between nodes 0 and 5
+altitude_constraint = (position[2] >= 15.0).over((0, 5))
+
+# Enforce obstacle avoidance only during the approach phase
+obstacle_center = np.array([50, -20, 20])
+safe_distance = 5.0
+diff = position - obstacle_center
+obstacle_constraint = (diff.T @ diff >= safe_distance**2).over((5, 10))
+```
+
+The `.over()` method also accepts optional parameters for the penalty function type (`penalty`), grouping index (`idx`), and whether to also check nodally (`check_nodally`).
+
+!!! note
+    You can also directly instantiate `NodalConstraint` or `CTCS` objects if you prefer:
+
+    ```python
+    from openscvx.symbolic.expr.constraint import NodalConstraint, CTCS
+
+    # Equivalent to (position[2] >= 15.0).at([5, 10])
+    altitude_nodal = NodalConstraint(position[2] >= 15.0, nodes=[5, 10])
+
+    # Equivalent to (position[2] >= 15.0).over((0, 15))
+    altitude_ctcs = CTCS(position[2] >= 15.0, nodes=(0, 15))
+    ```
+
+#### Marking Convex Constraints
+
+When a constraint is convex, we can mark it with `.convex()`:
+
+```python
+gate_constraint = (
+    ox.linalg.Norm(A_gate @ position - c_gate, ord="inf") <= 1.0
+).convex().at([node])
+```
+
+This tells OpenSCvx that no successive convexification is needed for this constraint, it is then lowered directly as a CVXPY constraint when the problem is lowered.
+This helps improve numerical performance as the solver is operating directly on the true constraint, not a linearized version thereof.
+
+#### Full Gate Setup
+
+Here's the complete gate constraint setup for multiple gates:
+
+```python
+n_gates = 10
+gate_centers = [
+    np.array([59.436, 0.000, 20.0]),
+    np.array([92.964, -23.750, 25.524]),
+    # ... more gate centers
+]
+
+# Assign nodes to gates (evenly spaced)
+nodes_per_gate = 2
+gate_nodes = np.arange(nodes_per_gate, n, nodes_per_gate)
+
+# Add gate constraints
+for node, center in zip(gate_nodes, gate_centers):
+    A_gate_scaled = A_gate @ center  # Pre-scaled center
+    gate_constraint = (
+        ox.linalg.Norm(A_gate @ position - A_gate_scaled, ord="inf") <= 1.0
+    ).convex().at([node])
+    constraints.append(gate_constraint)
+```
+
+### Keyframe Initialization
+
+For problems with waypoints or gates, a linear interpolation between start and end isn't a good initial guess.
+In fact, the start and end positions are identical to enforce loop closure. We need a more customized initial guess.
+
+In this drone racing example the gate ordering is not free. There is a specific order in which the gates must be traversed.
+We can use this _a priori_ knowledge to construct our initial guess; placing the required nodes directly in the center of the corresponding gate and linearly interpolating at the nodes in between gates.
+
+To facilitate such initial guesses, OpenSCvx provides `ox.init.linspace()` for keyframe-based initialization:
+
+```python
+position.guess = ox.init.linspace(
+    keyframes=[position.initial] + gate_centers + [position.final],
+    nodes=[0] + list(gate_nodes) + [n - 1],
+)
+```
+
+This lets us specify lists of key values, or `keyframes` to borrow an animation term and the corresponding nodes. At the nodes in between the keyframes the values will just be linearly interpolated.
+This creates an initial trajectory that passes through each gate center at the appropriate node, giving the solver a much better starting point.
+
+OpenSCvx also provides similar `ox.init.slerp(...)` and `ox.init.nlerp(...)` functions for _spherical linear interpolation_ (SLERP) and _normalized linear interpolation_ (NLERP) for quaternion initialization.
+
+### Problem Definition and Solution
+
+```python
+time = ox.Time(
+    initial=0.0,
+    final=("minimize", total_time),
+    min=0.0,
+    max=total_time,
+)
+
+problem = ox.Problem(
+    dynamics=dynamics,
+    states=states,
+    controls=controls,
+    time=time,
+    constraints=constraints,
+    N=n,
+)
+
+problem.initialize()
+results = problem.solve()
+results = problem.post_process()
+```
+
+### Visualizing 3D Trajectories
+
+With our drone now flying in 3D, simple time series plots don't capture the full picture. The `plot_projections_2d()` function shows XY, XZ, and YZ plane views:
+
+```python
+from openscvx.plotting import plot_states, plot_projections_2d
+
+# Time series of states
+plot_states(results, ["position", "velocity"]).show()
+
+# 2D projections colored by velocity
+plot_projections_2d(
+    results,
+    var_name="position",
+    velocity_var_name="velocity"
+).show()
+```
+
+For fully interactive 3D visualization with animated playback, gates, and thrust vectors, OpenSCvx integrates with [viser](https://viser.studio/). See [Tutorial 05: Visualization](05_visualization.md) for details on building rich 3D visualizations.
+
+## Constraint Types Summary
+
+| Type | Syntax | Use Case |
+|------|--------|----------|
+| Continuous (all nodes) | `ox.ctcs(expr)` | Path constraints enforced between all nodes |
+| Continuous (interval) | `expr.over((start, end))` | Path constraints over a specific interval |
+| Nodal (specific) | `expr.at([nodes])` | Waypoints, gate passage, events |
+| Nodal (all) | `expr` | Constraint at every node |
+| Convex | `expr.convex()` | Mark convex constraints for direct CVXPY lowering |
+| Combined | `expr.convex().at([nodes])` | Convex nodal constraints |
+
+!!! note "Cross-Node Constraints"
+    OpenSCvx also supports **cross-node constraints** that couple values at different nodes within a single constraint expression. These are created by using `.at(k)` on variables (not constraints):
+
+    ```python
+    # Rate limit: position change between consecutive nodes
+    rate_limit = position.at(5) - position.at(4) <= max_step
+    ```
+
+    Cross-node constraints are automatically detected and handled differently from nodal constraints—they operate on the full trajectory arrays rather than being evaluated node-by-node. We will cover these in a more advanced tutorial.
+
+## Further Reading
+
+- [Complete Drone Racing Example](../Examples/drone/dr_double_integrator.md)
+- [Full 6-DOF Drone Racing](../Examples/drone/drone_racing.md) — adds attitude dynamics
+- [API Reference: Constraints](../Reference/symbolic/expr/constraint.md)
+- [Obstacle Avoidance: 6-DOF Dynamics, Parameters, and Vmap](03_obstacle_avoidance_vmap.md)
+- [Viewpoint Constraints: Custom Functions and Perception](04_viewpoint_constraints.md)
+- [Visualization: 2D Plots and 3D Interactive](05_visualization.md)