.. _control-abstractions:

====================
Control Abstractions
====================

Agents in BiguaSim are controlled through various abstractions that determine how input commands are translated into movement. Unlike older versions that used integer-based ``control_scheme``, the current system primarily utilizes the ``control_abstraction`` string in the agent configuration:

.. code-block:: json

   "agents":[
        {
         "agent_name": "auv0",
         "agent_type": "BlueROV2",
         "control_abstraction": "cmd_vel",
         "dynamics": { "batch_size": 1 }
        } 
    ]

Standard Control Abstractions
=============================

Most agents in BiguaSim (BlueROV2, etc.) follow a standardized control architecture. These abstractions allow users to choose the level of control complexity, from raw motor speeds to high-level position targets.

Control Abstractions
====================

The following abstractions represent the standardized control interfaces available for most agents in BiguaSim. These schemes determine how command vectors are interpreted by the simulator's internal physics and control loops.

Velocity Control (``cmd_vel``)
------------------------------
This is a standard abstraction for autonomous navigation using internal PID controllers to reach target linear velocities.

* **Format**: A 3-length vector :math:`[vx, vy, vz]`.
* **Units**: Meters per second (m/s).

Velocity with Heading Rate (``cmd_vel_yaw``)
--------------------------------------------
Maintains target linear velocities while simultaneously controlling the agent's heading rate.

* **Format**: A 4-length vector :math:`[vx, vy, vz, yaw_rate]`.
* **Units**: m/s for linear velocity and rad/s for angular rate (:math:`yaw_rate`).

Position & Orientation (``cmd_pos_yaw``)
----------------------------------------
A high-level position controller designed for waypoint navigation or station-keeping (hovering).

* **Format**: A 4-length vector :math:`[vx, vy, vz, yaw]`.
* **Note**: This abstraction applies internal forces to reach specific global coordinates and a target yaw heading.

Direct Actuator Control (``thrusters``)
---------------------------------------
Provides raw, low-level access to the propulsion system, bypassing any internal stabilization or PID controllers.

* **Format**: A vector of length :math:`N`, where :math:`N` is the number of thrusters (e.g., a 6-length vector ``[r1, r2, r3, r4, r5, r6]`` for specific AUVs).
* **Use Case**: Developing custom control allocation laws or researching low-level actuator dynamics.

Acceleration Control (``scheme_accel``)
---------------------------------------
Directly applies linear and angular accelerations to the agent within the global frame. 

* **Format**: A 6-length vector :math:`[lin_accel_x, lin_accel_y, lin_accel_z, ang_accel_x, ang_accel_y, ang_accel_x]`.
* **Note**: When using this scheme, environmental forces like gravity and buoyancy are typically disabled to allow for custom physics implementation.

The TorpedoAUV Exception
========================

The **TorpedoAUV** uses a specialized set of control abstractions due to its unique physical design, which relies on a single rear propeller and movable control surfaces (rudders and stern planes) for steering.

Acceleration Control (``scheme_accel``)
---------------------------------------
Directly applies linear and angular accelerations to the TorpedoAUV in the global frame.

* **Format**: A 6-length vector :math:`[lin_accel_x, lin_accel_y, lin_accel_z, ang_accel_x, ang_accel_y, ang_accel_x]`.
* **Note**: This is a "physics-override" mode, useful for testing pure kinematic trajectories without considering fluid dynamics.

Actuator Control (``scheme_rudders_sterns_motor_speed``)
--------------------------------------------------------
This is the primary low-level abstraction for the TorpedoAUV. It controls the deflection of the fins and the propeller speed.

* **Format**: A 5-length vector ``[rudder_top, rudder_bottom, stern_left, stern_right, rpm]``.
* **Dynamics**: Steering is achieved through lift generated by the fins. Therefore, the vehicle **must be moving forward** (positive RPM) to have maneuverability.

Depth, Heading & Surge (``scheme_depth_heading_rpm_surge``)
-----------------------------------------------------------
A high-level controller that simplifies navigation by managing depth and orientation automatically.

* **Format**: A 4-length vector :math:`[depth, heading, rpm, surge]`.
* **Note**: This abstraction uses internal PID loops to translate target depth and heading into fin deflections and motor thrust. It is ideal for long-range survey missions.

Custom Dynamics
===============

For users who require total control over the vehicle's motion model, BiguaSim allows for Custom Dynamics. By disabling internal forces like buoyancy and gravity, users can implement their own hydrodynamics models in Python.

To assist in this, the :ref:`dynamics-sensor` provides ground-truth pose, velocity, and acceleration.