.. _auto_set_singularity_handling:

set_singularity_handling (Auto Mode)
------------------------------------------

This function configures the robot's **singularity handling policy** for  
**task-space motion execution in Auto mode**.

A singularity occurs when the robot's Jacobian matrix becomes ill-conditioned,  
which may lead to instability or reduced path tracking accuracy.

This function does not generate motion by itself, but defines how the controller  
responds when a singular configuration is encountered during task-space motions  
such as ``movel()`` or ``movec()``.

By default, **automatic avoidance mode** is applied to reduce instability  
near singular regions.

**Available modes**

- SINGULARITY_AVOIDANCE_AVOID: Automatic avoidance (**default**). |br|
- SINGULARITY_AVOIDANCE_STOP: Path-first stop mode. |br|
- SINGULARITY_AVOIDANCE_VEL: Variable velocity mode.

**Definition** |br|
``DRFLEx.h`` within class `CDRFLEx`, public section

.. code-block:: cpp

    bool set_singularity_handling(SINGULARITY_AVOIDANCE eMode) {
        return _set_singularity_handling(_rbtCtrl, eMode);
    };

**Parameter**

.. list-table::
   :widths: 22 20 18 40
   :header-rows: 1

   * - **Parameter Name**
     - **Data Type**
     - **Default Value**
     - **Description**
   * - eMode
     - :ref:`SINGULARITY_AVOIDANCE <enum_singularity_avoidance>`  
     - -
     - Refer to the Definition of Enumeration Type
     
**Return**

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - **Value**
     - **Description**
   * - 0
     - Failed to update singularity handling mode.
   * - 1
     - Successfully applied the new singularity handling policy.

**Example**

.. code-block:: cpp

   float p1[6] = {400.0f, 500.0f, 600.0f, 0.0f, 180.0f, 0.0f};
   float p2[6] = {400.0f, 500.0f, 200.0f, 0.0f, 180.0f, 0.0f};
   float vel1[2] = {50.0f, 50.0f}, acc1[2] = {50.0f, 50.0f};
   float vel2[2] = {30.0f, 30.0f}, acc2[2] = {30.0f, 30.0f};
   float vel3[2] = {40.0f, 40.0f}, acc3[2] = {40.0f, 40.0f};

   // Case 1: Default automatic avoidance mode
   drfl.set_singularity_handling(SINGULARITY_AVOIDANCE_AVOID);
   drfl.movel(p1, vel1, acc1);

   // Case 2: Path-first stop mode for safety near singular points
   drfl.set_singularity_handling(SINGULARITY_AVOIDANCE_STOP);
   drfl.movel(p2, vel2, acc2);

   // Case 3: Variable velocity mode for smooth operation around singularities
   drfl.set_singularity_handling(SINGULARITY_AVOIDANCE_VEL);
   drfl.movel(p1, vel3, acc3);

This example demonstrates how to configure the singularity handling strategy  
to balance **stability and path accuracy** during task-space motions.  
When operating near singular regions, select the appropriate mode based on  
motion priority and application safety requirements.