openscvx 0.4.1.dev148__tar.gz → 0.4.1.dev149__tar.gz

{openscvx-0.4.1.dev148/openscvx.egg-info → openscvx-0.4.1.dev149}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscvx
-Version: 0.4.1.dev148
+Version: 0.4.1.dev149
 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.4.1.dev148 → openscvx-0.4.1.dev149}/docs/UsersGuide/06_logic.md

@@ -7,6 +7,5 @@
 
 - [API Reference: Logic operators](../Reference/symbolic/expr/logic.md)
 - [API Reference: STL operators](../Reference/symbolic/expr/stl.md)
-- [Dubin's Car with conditional logic Example](../Examples/car/dubins_car_conditional.md)
-- [Dubin's Car with direct STL implementation Example](../Examples/car/dubins_car_disjoint.md)
-- [Dubin's Car with STLJAX Example](../Examples/car/dubins_car_stljax.md)
+- [Dubin's Car with obstacle avoidance (conditional) Example](../Examples/car/dubins_car_obstacle_conditional.md)
+- [Dubin's Car with direct STL implementation Example](../Examples/car/dubins_car_disjoint.md)

openscvx-0.4.1.dev149/examples/abstract/stl_integer_variable.py

@@ -0,0 +1,102 @@
+"""Simple example using `ox.stl.IntegerVariable` to enforce discrete-valued states.
+
+This example sets up a 1D integrator where a second "gear" state must always
+take one of three discrete values {-1, 0, 1}. The control drives the position
+state `x`, while the gear state `g` is itself a continuous variable that is
+penalized whenever it deviates from the allowed discrete set.
+
+- State `x`: position, driven by control `u`
+- State `g`: gear-like variable constrained to {-1, 0, 1} at every node
+- `u` also acts as the rate of change for `g` (both share the same control)
+- The IntegerVariable STL constraint is enforced over the full horizon
+
+Run it directly to solve and print the resulting trajectory.
+"""
+
+import os
+import sys
+
+import numpy as np
+
+import openscvx as ox
+from openscvx import Problem
+
+current_dir = os.path.dirname(os.path.abspath(__file__))
+project_root = os.path.dirname(os.path.dirname(current_dir))
+if project_root not in sys.path:
+    sys.path.append(project_root)
+
+
+# Discretization parameters
+N = 10
+total_time = 10.0
+
+# Scalar position state
+x = ox.State("x", shape=(1,))
+x.min = np.array([0.0])
+x.max = np.array([5.0])
+x.initial = np.array([0.0])
+x.final = [5.0]
+
+
+# Control: drives position; gear integrates toward chosen discrete level
+u = ox.Control("u", shape=(1,))
+u.min = np.array([0.0])
+u.max = np.array([10.0])
+u.guess = np.ones((N, 1)) * 8.0
+
+states = [x]
+controls = [u]
+
+# Dynamics: x_dot = u, g_dot = v
+dynamics = {
+    "x": u,
+}
+
+# Box constraints on states and controls
+constraints = []
+for state in states:
+    constraints.extend(
+        [
+            ox.ctcs(state <= state.max),
+            ox.ctcs(state.min <= state),
+        ]
+    )
+
+# IntegerVariable: g must equal one of the allowed levels at every node
+allowed_levels = [0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0]
+levels = ox.stl.IntegerVariable(u, allowed_levels, c=1e-8)
+constraints.append(levels.over((0, N - 1)))
+
+
+# Time configuration
+time = ox.Time(
+    initial=0.0,
+    final=ox.Minimize(total_time),
+    min=0.0,
+    max=total_time,
+    uniform_time_grid=True,
+    time_dilation_min=0.2,
+    time_dilation_max=2.0,
+)
+
+problem = Problem(
+    dynamics=dynamics,
+    constraints=constraints,
+    states=states,
+    controls=controls,
+    N=N,
+    time=time,
+    algorithm={"autotuner": ox.ConstantProximalWeight(), "ep_vc": 1e-3, "lam_cost": 1e1},
+    discretizer={"dis_type": "ZOH"},
+    float_dtype="float64",
+)
+
+problem.settings.prp.dt = 0.001
+
+
+
+if __name__ == "__main__":
+    problem.initialize()
+    results = problem.solve()
+    results = problem.post_process()

openscvx-0.4.1.dev149/examples/abstract/stl_or.py

@@ -0,0 +1,108 @@
+"""Very simple example using the GMSR-based STL `Or` operator (`ox.stl.Or`).
+
+This example sets up a 1D integrator with a single STL reachability specification:
+
+- State `x` must reach either goal position `x_a` OR `x_b` by the final node.
+- The STL formula is built with `ox.stl.Or` and enforced via `.at(N - 1)`.
+
+The example is intentionally minimal and does not use any plotting utilities.
+Run it directly to solve and print the resulting trajectory statistics.
+"""
+
+import os
+import sys
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+import openscvx as ox
+from openscvx import Problem
+from openscvx.plotting import plot_states, plot_controls, plot_virtual_control_heatmap
+
+# Ensure examples can be run directly by adding project root to path
+current_dir = os.path.dirname(os.path.abspath(__file__))
+project_root = os.path.dirname(os.path.dirname(current_dir))
+if project_root not in sys.path:
+    sys.path.append(project_root)
+
+
+# Discretization parameters
+N = 20
+total_time = 2.0
+
+# Scalar state: position x
+x = ox.State("x", shape=(1,))
+x.min = np.array([-2.0])
+x.max = np.array([2.0])
+x.initial = np.array([0.0])
+x.final = [ox.Free(0.1)]
+
+# Scalar control: acceleration u
+u = ox.Control("u", shape=(1,))
+u.min = np.array([-1.0])
+u.max = np.array([1.0])
+u.guess = np.zeros((N, 1))
+
+states = [x]
+controls = [u]
+
+# Simple integrator dynamics: x_dot = u
+dynamics = {
+    "x": u,
+}
+
+# Box constraints for state bounds
+constraints = []
+for state in states:
+    constraints.extend(
+        [
+            ox.ctcs(state <= state.max),
+            ox.ctcs(state.min <= state),
+        ]
+    )
+
+# STL reachability specification: at the final node, be near either
+# goal position x_a OR goal position x_b.
+x_a = np.array([-1.0])
+x_b = np.array([1.0])
+radius = np.array([0.1])
+
+reach_a = ox.linalg.Norm(x - x_a) <= radius
+reach_b = ox.linalg.Norm(x - x_b) <= radius
+
+reach_either = ox.stl.Or(reach_a, reach_b)
+# Enforce the STL Or condition over the whole horizon
+constraints.append(reach_either.over((N - 2, N - 1), penalty="squared_relu"))
+
+# Time configuration (auto-created "time" trajectory)
+time = ox.Time(
+    initial=0.0,
+    final=("minimize", total_time),
+    min=0.0,
+    max=total_time,
+    uniform_time_grid=True,
+)
+
+problem = Problem(
+    dynamics=dynamics,
+    constraints=constraints,
+    states=states,
+    controls=controls,
+    N=N,
+    time=time,
+    algorithm={"autotuner": ox.ConstantProximalWeight()},
+    float_dtype="float64",
+)
+
+problem.algorithm.lam_vb = 1e2
+
+problem.algorithm.lam_vc = 1e1
+
+if __name__ == "__main__":
+    problem.initialize()
+    results = problem.solve()
+    results = problem.post_process()
+
+    plot_states(results).show()
+    plot_controls(results).show()
+    plot_virtual_control_heatmap(results).show()

openscvx-0.4.1.dev149/examples/car/dubins_car_obstacle_stl.py

@@ -0,0 +1,154 @@
+"""Dubins car path planning with conditional velocity constraint using Cond operator.
+
+This example demonstrates the use of the Cond operator for conditional logic
+in constraints. The car has different maximum velocity limits based on proximity
+to the obstacle:
+
+- When far from obstacle: higher maximum velocity (10.0)
+- When near obstacle: lower maximum velocity (5.0) for safer navigation
+
+This showcases how to use ox.Cond for JAX-traceable conditional branching
+in constraint expressions.
+"""
+
+import os
+import sys
+
+import jax.numpy as jnp
+import numpy as np
+
+# Add grandparent directory to path to import examples.plotting
+current_dir = os.path.dirname(os.path.abspath(__file__))
+grandparent_dir = os.path.dirname(os.path.dirname(current_dir))
+sys.path.append(grandparent_dir)
+
+import openscvx as ox
+from examples.plotting import plot_dubins_car, plot_velocity_vs_distance
+from openscvx.plotting import plot_states, plot_controls
+from openscvx import Problem
+
+n = 8
+total_time = 0.8  # Total simulation time
+
+# Define state components
+position = ox.State("position", shape=(2,))  # 2D position [x, y]
+position.min = np.array([-5.0, -5.0])
+position.max = np.array([5.0, 5.0])
+position.initial = np.array([0, -2])
+position.final = np.array([0, 2])
+
+theta = ox.State("theta", shape=(1,))  # Heading angle
+theta.min = np.array([-2 * jnp.pi])
+theta.max = np.array([2 * jnp.pi])
+theta.initial = np.array([0])
+theta.final = [ox.Free(0)]
+
+speed = ox.State("speed", shape=(1,))  # Forward speed
+speed.min = np.array([0])
+speed.max = np.array([10])
+speed.initial = [ox.Free(10)]
+speed.final = [ox.Free(10)]
+speed.guess = np.ones((n, 1)) * 10.0
+
+# Define control components
+acceleration = ox.Control("acceleration", shape=(1,))  # Acceleration
+acceleration.min = np.array([-10])
+acceleration.max = np.array([10])
+acceleration.guess = np.zeros((n, 1))
+
+angular_rate = ox.Control("angular_rate", shape=(1,))  # Angular velocity
+angular_rate.min = np.array([-5])
+angular_rate.max = np.array([5])
+angular_rate.guess = np.zeros((n, 1))
+
+# Define list of all states and controls
+states = [position, speed, theta]
+controls = [acceleration, angular_rate]
+
+# Define Parameters with initial values for obstacle radius and center
+obs_center = ox.Parameter("obs_center", shape=(2,), value=np.array([-0.25, 0.0]))
+obs_radius = ox.Parameter("obs_radius", shape=(), value=1.0)
+
+# Safety distance threshold for conditional velocity constraint
+safety_threshold = 1.1  # Distance from obstacle where we reduce max velocity
+
+# Generate box constraints for all states
+constraints = []
+for state in states:
+    constraints.extend([ox.ctcs(state <= state.max), ox.ctcs(state.min <= state)])
+
+# Add obstacle avoidance constraint
+constraints.append(ox.ctcs(obs_radius <= ox.linalg.Norm(position - obs_center)))
+
+# Add the conditional velocity constraint as an STL specification:
+# - If the car is within safety_threshold of the obstacle, then speed <= 5.0
+# - If the car is farther than safety_threshold, then speed <= 10.0
+distance_to_obstacle = ox.linalg.Norm(position - obs_center)
+
+near_obstacle = distance_to_obstacle <= safety_threshold
+
+# Use the scalar speed magnitude so the IfThen residuals are 0-D scalars
+slow_speed = ox.linalg.Norm(speed) <= 5.0
+
+velocity_rule = ox.stl.IfThen(near_obstacle, slow_speed, c = 1e-12)
+
+constraints.append(
+    velocity_rule.over(
+        (0, n - 1),
+    )
+)
+
+
+# Define normal dynamics (no conditional logic here)
+dynamics = {
+    "position": ox.Concat(
+        speed * ox.Sin(theta),  # x_dot
+        speed * ox.Cos(theta),  # y_dot
+    ),
+    "speed": acceleration,
+    "theta": angular_rate,
+}
+
+
+# Build the problem (parameters auto-collected from Parameter objects)
+time = ox.Time(
+    initial=0.0,
+    final=ox.Minimize(total_time),
+    min=0.0,
+    max=5.0,
+)
+
+problem = Problem(
+    dynamics=dynamics,
+    states=states,
+    controls=controls,
+    time=time,
+    constraints=constraints,
+    N=n,
+    float_dtype="float64",
+)
+
+plotting_dict = {
+    "obs_radius": problem.parameters["obs_radius"],
+    "obs_center": problem.parameters["obs_center"],
+    "safety_threshold": safety_threshold,
+}
+
+if __name__ == "__main__":
+    print("Dubins Car with Conditional Velocity Constraint (using Cond operator)")
+    print("=" * 70)
+    print("Max velocity is 5.0 when within 2.0 units of obstacle, else 10.0")
+    print("=" * 70)
+
+    problem.initialize()
+    results = problem.solve()
+    results = problem.post_process()
+    results.update(plotting_dict)
+
+    # Plot trajectory
+    plot_dubins_car(results, problem.settings).show()
+    plot_states(results).show()
+    plot_controls(results).show()
+
+    # Plot velocity vs distance to obstacle
+    plot_velocity_vs_distance(results, problem.settings).show()

openscvx-0.4.1.dev148/examples/car/dubins_car_stljax.py → openscvx-0.4.1.dev149/examples/car/dubins_car_stl_or.py

@@ -93,7 +93,7 @@ wp2_pred = ox.linalg.Norm(position - wp2_center) <= wp2_radius
 
 # Visit waypoint constraints using symbolic Or
 # Note: visit_wp_or_expr is already a constraint, so we can use .over() directly
-constraints.append(ox.stl.Or(wp1_pred, wp2_pred).over((3, 5)))
+constraints.append(ox.stl.Or(wp1_pred, wp2_pred).over((3, 5), penalty="squared_relu"))
 
 # Build the problem
 constraints.append((time.at(5) - time.at(3) == 1.23).convex())
@@ -105,7 +105,7 @@ problem = Problem(
     time=time,  # Time is already defined above as ox.Time
     constraints=constraints,
     N=n,
-    algorithm={"lam_vc": 6e2},
+    float_dtype="float64",
 )
 
 # Extract parameter values from problem.parameters (not Parameter objects)
@@ -122,4 +122,5 @@ if __name__ == "__main__":
     results = problem.solve()
     results = problem.post_process()
     results.update(plotting_dict)
-    plot_dubins_car_disjoint(results, problem.settings).show()
+
+    plot_dubins_car_disjoint(results, problem.settings).show()

openscvx-0.4.1.dev149/examples/car/dubins_car_waypoint_stl.py

@@ -0,0 +1,163 @@
+"""Dubins car path planning with STL waypoint inside a 2-norm ball.
+
+This example demonstrates the use of GMSR-based STL operators to encode a
+waypoint specified as a 2-norm ball, together with a time-windowed speed
+restriction:
+
+- At nodes 10–14, the position must stay inside a 2-norm ball (the waypoint)
+- While in this waypoint window, the speed is restricted to a lower value
+  (here, from the global max 10.0 down to 1.0)
+
+This showcases how to use `ox.stl` operators over a specific node interval to
+impose waypoint and speed-profile constraints.
+"""
+
+import os
+import sys
+
+import jax.numpy as jnp
+import numpy as np
+
+# Add grandparent directory to path to import examples.plotting
+current_dir = os.path.dirname(os.path.abspath(__file__))
+grandparent_dir = os.path.dirname(os.path.dirname(current_dir))
+sys.path.append(grandparent_dir)
+
+import openscvx as ox
+from examples.plotting import plot_dubins_car, plot_velocity_vs_waypoint
+from openscvx.plotting import plot_states, plot_controls
+from openscvx import Problem
+
+n = 20
+total_time = 3.0  # Total simulation time
+
+# Define state components
+position = ox.State("position", shape=(2,))  # 2D position [x, y]
+position.min = np.array([-5.0, -5.0])
+position.max = np.array([5.0, 5.0])
+position.initial = np.array([0, -2])
+position.final = np.array([0, 2])
+
+theta = ox.State("theta", shape=(1,))  # Heading angle
+theta.min = np.array([-2 * jnp.pi])
+theta.max = np.array([2 * jnp.pi])
+theta.initial = np.array([0])
+theta.final = [ox.Free(0)]
+
+speed = ox.State("speed", shape=(1,))  # Forward speed
+speed.min = np.array([0])
+speed.max = np.array([10])
+speed.initial = [ox.Free(10)]
+speed.final = [ox.Free(10)]
+
+# Define control components
+acceleration = ox.Control("acceleration", shape=(1,))  # Acceleration
+acceleration.min = np.array([-10])
+acceleration.max = np.array([10])
+acceleration.guess = np.zeros((n, 1))
+
+
+angular_rate = ox.Control("angular_rate", shape=(1,))  # Angular velocity
+angular_rate.min = np.array([-5])
+angular_rate.max = np.array([5])
+angular_rate.guess = np.zeros((n, 1))
+
+# Define list of all states and controls
+states = [position, speed, theta]
+controls = [acceleration, angular_rate]
+
+# Define Parameters with initial values for obstacle radius and center
+obs_center = ox.Parameter("obs_center", shape=(2,), value=np.array([-2.0, 0.0]))
+obs_radius = ox.Parameter("obs_radius", shape=(), value=1.0)
+
+# Generate box constraints for all states
+constraints = []
+for state in states:
+    constraints.extend([ox.ctcs(state <= state.max), ox.ctcs(state.min <= state)])
+
+# Define a waypoint as a 2-norm ball and enforce it only over nodes 10–14,
+# together with a stronger speed restriction in that same window.
+waypoint_region = ox.linalg.Norm(position - obs_center) <= obs_radius
+
+safety_region = ox.linalg.Norm(position - obs_center) <= 1.6
+
+# Use the scalar speed magnitude so the STL residuals are 0-D scalars.
+# Globally the control bound is 10.0; inside the waypoint window we restrict to 1.0.
+slow_speed_in_waypoint = ox.linalg.Norm(speed) <= 1.0
+
+speed_constraint = ox.stl.IfThen(safety_region, slow_speed_in_waypoint, c = 1e-18)
+
+constraints.append(
+    speed_constraint.over(
+        (0, n-1),
+    )
+)
+
+constraints.append(
+    ox.ctcs(waypoint_region).over(
+        (8, 12),
+    )
+)
+    
+
+# Define normal dynamics (no conditional logic here)
+dynamics = {
+    "position": ox.Concat(
+        speed * ox.Sin(theta),  # x_dot
+        speed * ox.Cos(theta),  # y_dot
+    ),
+    "speed": acceleration,
+    "theta": angular_rate,
+}
+
+
+# Build the problem (parameters auto-collected from Parameter objects)
+time = ox.Time(
+    initial=0.0,
+    final=ox.Minimize(total_time),
+    min=0.0,
+    max=5.0,
+)
+
+problem = Problem(
+    dynamics=dynamics,
+    states=states,
+    controls=controls,
+    time=time,
+    constraints=constraints,
+    N=n,
+    algorithm={"autotuner": ox.RampProximalWeight()},
+    float_dtype="float64",
+    licq_max=1e-8,
+)
+
+problem.algorithm.ep_vc = 1e-6
+problem.algorithm.ep_tr = 5e-4
+problem.algorithm.lam_vc = 1e3
+
+plotting_dict = {
+    "obs_radius": problem.parameters["obs_radius"],
+    "obs_center": problem.parameters["obs_center"],
+    "safety_threshold": 1.6,
+    "reduced_speed": 1.0,
+}
+
+if __name__ == "__main__":
+    print("Dubins Car with STL Waypoint and Time-Windowed Speed Constraint")
+    print("=" * 70)
+    print("Max velocity is 10.0 globally, but at nodes 10–14 the car must")
+    print("be inside the 2-norm waypoint ball and its speed is restricted to 1.0.")
+    print("=" * 70)
+
+    problem.initialize()
+    results = problem.solve()
+    results = problem.post_process()
+    results.update(plotting_dict)
+
+    # Plot trajectory
+    plot_dubins_car(results, problem.settings).show()
+    plot_states(results).show()
+    plot_controls(results).show()
+
+    # Plot velocity vs distance to waypoint, using safety radius and reduced speed
+    plot_velocity_vs_waypoint(results, problem.settings).show()