larvaworld.lib.model.agents.larva_robot
=======================================

.. py:module:: larvaworld.lib.model.agents.larva_robot


Classes
-------

.. autoapisummary::

   larvaworld.lib.model.agents.larva_robot.LarvaRobot
   larvaworld.lib.model.agents.larva_robot.ObstacleLarvaRobot


Module Contents
---------------

.. py:class:: LarvaRobot(larva_pars: dict[str, Any], genome: Any | None = None, **kwargs: Any)

   Bases: :py:obj:`larvaworld.lib.model.agents.LarvaSim`


   Virtual larva agent for genetic algorithm optimization.

   Extends LarvaSim with genome-based parameter encoding, enabling
   evolutionary optimization of behavioral parameters via GA. The genome
   represents evolvable traits (locomotor gains, sensor weights, etc.).

   Attributes:
       genome: Parameter genome vector for GA optimization (optional)

   Args:
       larva_pars: Dictionary of larva configuration parameters
       genome: Optional genome encoding of evolvable parameters
       **kwargs: Additional agent configuration

   Example:
       >>> genome = np.array([0.5, 1.2, 0.8])  # Evolvable parameters
       >>> robot = LarvaRobot(larva_pars={'model': 'explorer'}, genome=genome)


   .. py:attribute:: genome
      :value: None



.. py:class:: ObstacleLarvaRobot(larva_pars: dict[str, Any], **kwargs: Any)

   Bases: :py:obj:`LarvaRobot`


   Obstacle-avoiding larva robot with Braitenberg-like sensorimotor coupling.

   Extends LarvaRobot with bilateral proximity sensors and motor controllers
   that implement reactive obstacle avoidance through differential actuation.
   Uses sensor-motor coupling to generate turning away from obstacles.

   Attributes:
       Lmotor: Left motor controller with proximity sensor
       Rmotor: Right motor controller with proximity sensor
       sensor_delta_direction: Angular offset of sensors from midline (radians)
       sensor_saturation_value: Max sensor response value
       obstacle_sensor_error: Sensor noise/error magnitude
       sensor_max_distance: Maximum sensing distance
       motor_coefficient: Motor gain coefficient
       min_actuator_value: Minimum motor output value

   Example:
       >>> robot = ObstacleLarvaRobot(
       ...     larva_pars={'model': 'navigator'},
       ...     sensor_delta_direction=0.4,
       ...     motor_coefficient=8770.0
       ... )
       >>> robot.sense()  # Detect obstacles and adjust motors


   .. py:attribute:: sensor_delta_direction


   .. py:attribute:: sensor_saturation_value


   .. py:attribute:: obstacle_sensor_error


   .. py:attribute:: sensor_max_distance


   .. py:attribute:: motor_coefficient


   .. py:attribute:: min_actuator_value


   .. py:attribute:: Lmotor


   .. py:attribute:: Rmotor


   .. py:method:: sense() -> None

      This method allows the larva robot to sense its environment and act accordingly.
      If there is no collision with an object, it transforms the olfactor position and
      uses the left and right motors to sense and act based on the position and direction.
      It then calculates the torque difference between the right and left motors and
      adjusts the neural oscillator's parameters accordingly. If a collision is detected,
      it sets the collision flag to True and interrupts the locomotion.

      Raises:
          util.Collision: If a collision with an object is detected.



   .. py:method:: draw(v: Any, **kwargs: Any) -> None

      Draws the larva robot and its sensors on the screen.

      Args:
          v (ScreenManager): The screen manager responsible for rendering.
          **kwargs: Additional keyword arguments passed to the drawing method.

      Notes:
          - The method transforms the olfactor position using the screen manager.
          - If the robot has motors, it draws the sensors for both the left and right motors.
          - Finally, it calls the superclass's draw method to render the robot itself.