Tune speed profiles
===================

How fast the arm moves is configuration, not code. It lives in
``<app>_bringup/config/config_parser/ee_tip_specific/parameterization_config.json``,
and applications select a profile by name when they request a motion.

The file
--------

Each entry in ``parameterize_configs`` is one profile:

.. code-block:: json

   {
     "name": "low_speed_parameterize_config",
     "parameterizer": "totg",
     "time_increment": 0.02,
     "joint_velocity_constraint_max":     [0.5, 0.5, 0.5, 0.5, 0.5],
     "joint_acceleration_constraint_max": [0.5, 0.5, 0.5, 0.5, 0.5],
     "use_joint_torque_constraint": false,
     "ee_acceleration_constraint_lin_max": [70, 70, 70]
   }

.. list-table::
   :header-rows: 1
   :widths: 42 58

   * - Key
     - Meaning
   * - ``name``
     - How the application selects the profile. Must match what the caller asks
       for, or the request fails.
   * - ``parameterizer``
     - ``toppra`` or ``totg``. TOPP-RA honours acceleration and torque
       constraints and produces faster trajectories; TOTG is simpler and
       smoother. The shipped high-speed profile uses TOPP-RA, low-speed TOTG.
   * - ``time_increment``
     - Sample spacing of the output trajectory, in seconds. Smaller means more
       points and finer tracking; the shipped profiles use 0.04 (high) and
       0.02 (low).
   * - ``joint_velocity_constraint_max``
     - Per-joint velocity ceiling, rad/s. One entry per joint, in joint order.
   * - ``joint_acceleration_constraint_max``
     - Per-joint acceleration ceiling, rad/s². **This is the value that decides
       whether the arm can track its own trajectory.**
   * - ``use_joint_torque_constraint`` / ``joint_torque_constraint_ratio``
     - Optional torque limiting. Off in both shipped profiles.
   * - ``ee_acceleration_constraint_lin_*`` / ``_ang_*``
     - Cartesian acceleration bounds at the tip. Useful when the payload can
       slip or swing.
   * - ``max_path_deviation``
     - How far parameterization may depart from the planned path.

Array length must equal the arm's joint count. A mismatch is a configuration
error, not a planning failure — and the message may not say so clearly.

How to tune
-----------

Change one thing at a time and measure. The shipped high-speed profile is far
more aggressive than the low-speed one — up to 6 rad/s and 26 rad/s² against a
flat 0.5 for both — so most problems appear when moving between them.

1. **Start from the low-speed profile.** Confirm the cycle completes and the
   collision monitor reports nothing.
2. **Raise velocity before acceleration.** Velocity mostly changes cycle time;
   acceleration is what the arm struggles to track.
3. **Raise acceleration per joint, not globally.** The joints that move furthest
   overshoot first, and a single joint asked for more than it can deliver is
   enough to pull the whole arm off the planned path.
4. **Re-run the same motion after each change** and watch for collision-monitor
   output. See :doc:`debug_a_collision`.

Symptoms and causes
-------------------

.. list-table::
   :header-rows: 1
   :widths: 45 55

   * - Symptom
     - Likely cause
   * - Collides at high speed, clean at low speed
     - Acceleration limits exceed what the arm can track
   * - Motion is jerky or stutters
     - ``time_increment`` too large for the speed
   * - Planning succeeds, parameterization fails
     - Constraint array length does not match the joint count
   * - Cycle time barely improves when limits are raised
     - Another constraint binds — usually the Cartesian bounds

.. warning::

   Tuning against ``drive_mode`` ``kinematic`` proves nothing about speed. In
   kinematic mode the simulated arm follows commanded positions exactly, so
   every profile looks perfect. Validate the final profile in ``velocity`` mode.