.. _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 (line 983)

.. 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>`  
     - SINGULARITY_AVOIDANCE_AVOID
     - 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

       CDRFLEx drfl;

       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};

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

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

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

       return 0;
   }

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.