Control Physics Traffic

Control, physics, and traffic

Use this sub-skill for the three simulation components that close the motion loop:

• Controller: planar dynamic-bicycle vehicle state, linear/nonlinear MPC, trajectory tracking, and the controller gRPC session.
• Physics: Warp ground-mesh intersection that corrects vehicle/object poses; it is not a collision engine or a replacement for vehicle dynamics.
• Traffic: the CATK-backed traffic gRPC service, including session history, logged replay, handover, prediction batching, and failure statuses.

Do not use this sub-skill to compose a wizard deployment, choose a driver policy, or edit protobufs. Route those to simulation-wizard, drivers-and-plugins, or grpc-and-developer-tools, respectively. Use runtime-services for the runtime's event loop and service orchestration, and evaluation-and-logs for post-run logs and metrics.

Start with a capability and backend check

1. Identify the service being changed or queried. Record the simulation time unit, coordinate frame, scene identifier, and whether the request is replay or closed-loop inference.

2. Run the bundled, read-only probe before debugging imports or optional backends:

   Read backend compatibility, then run the bundled backend checker before debugging imports or optional backends:

   python scripts/check_backend.py
   python scripts/check_backend.py --usdz-folder /data/scenes \
       --model-config /models/catk/config.yaml \
       --checkpoint /models/catk/latest.ckpt \
       --token-dir /models/tokens

   The second form only inspects supplied paths; it never downloads or changes them. Treat warnings about CUDA, PyG extensions, USDZ, or model assets as capability limits, not as proof of a working CATK service.

3. For a controller-only CPU smoke test, use the package's focused tests or instantiate LinearMPC with an 8-element state and a time-stamped Trajectory. For a nonlinear smoke test, ensure do_mpc and CasADi are importable before the first compute_control call.

4. For physics, use a small valid PLY ground mesh and positive AABB dimensions. PhysicsBackend constructs Warp mesh data and launches CUDA kernels during update_pose; a successful Python import is not a physics execution test.

5. For CATK, verify the scene directory contains .usdz files and that the model config, checkpoint, token directory, CUDA device, and matching PyG compiled extensions are all available. Never substitute a static traffic trajectory for a failed post-handover prediction.

See backend compatibility before installing optional packages and troubleshooting when a check fails.

Choose and use the controller

1. Represent the current vehicle state in the documented order [x, y, yaw, vx_cg, vy_cg, yaw_rate, steering, accel]. The position and yaw are for the rig origin in the temporary inertial frame; vx_cg and vy_cg are body-frame CG velocities. Do not silently treat rig-frame lateral speed as CG lateral speed.
2. Use linear MPC (mpc_implementation: linear) as the normal fast choice. It linearizes the bicycle model about the current state and solves an OSQP QP. Use nonlinear MPC for aggressive maneuvers or tight turns when the slower do_mpc/CasADi/IPOPT solve is acceptable. This is a modeling trade-off, not a claim that nonlinear is always more stable.
3. Keep n_horizon and dt_mpc consistent with the trajectory sampling. The defaults are 20 steps and 0.1 seconds. Tracking cost begins at gains.idx_start_penalty (default 10), while actuator regularization applies to command changes.
4. In a service session, call start_session before the first run, provide a non-empty planned trajectory, advance to a strictly later future_time_us, and close the session exactly once. The first run lazily constructs the system and creates a CSV controller log.
5. Set coerce_dynamic_state when current ground-truth dynamic state should replace the model's velocity, yaw rate, and acceleration before solving. The system converts rig-frame velocity to CG-frame velocity and preserves the integrated pose origin.

The exact dataclasses, solver bounds, frame conversion, service invariants, and standalone server flags are in controller API.