irsim.lib.behavior.group_behavior
=================================

.. py:module:: irsim.lib.behavior.group_behavior


Attributes
----------

.. autoapisummary::

   irsim.lib.behavior.group_behavior.logger


Classes
-------

.. autoapisummary::

   irsim.lib.behavior.group_behavior.GroupBehavior


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

.. py:data:: logger

.. py:class:: GroupBehavior(members: list[irsim.world.object_base.ObjectBase], **behavior_dict: Any)

   Group behavior facade.

   - If a class-based handler is registered, it is instantiated once and reused.
   - Otherwise, a function-based behavior is invoked each step.

   Create a group behavior wrapper.

   :param members: Current group members to control.
   :param \*\*behavior_dict: Behavior configuration. Must include:
                             - name: behavior action (e.g., "orca").
                             - optional behavior-specific parameters.

   .. rubric:: Notes

   - If a class-based group behavior is registered for (kinematics, name),
     it will be instantiated once and reused.
   - Otherwise, a function-based behavior is used each step.


   .. py:attribute:: members


   .. py:attribute:: behavior_dict


   .. py:attribute:: kinematics
      :type:  str | None


   .. py:attribute:: name
      :type:  str | None


   .. py:method:: update_members(members: list[irsim.world.object_base.ObjectBase]) -> None

      Update the current group members.

      Call this if the composition of the group changes at runtime. The
      class-based handler (if any) is expected to adapt on next call; no
      forced re-instantiation is performed here.



   .. py:method:: gen_group_vel() -> list[Any]

      Generate per-member actions for one step.

      :returns:

                A list of actions aligned with `members`. Each element is
                      behavior-specific (e.g., 2x1 numpy arrays for velocity).
      :rtype: list

      Behavior:
          - Uses a class-based handler if one was registered and initialized.
          - Otherwise looks up a function behavior in the registry.
          - If no behavior is configured, returns `[None]` (one sentinel
            element) and logs a warning periodically in auto mode.



   .. py:method:: load_group_behaviors(group_behaviors: str = '.group_behavior_methods')

      Dynamically import user/group behavior methods.

      :param group_behaviors: Dotted module path (relative to
                              `irsim.lib.behavior`) that contains group behavior registrations.

      .. note::

         Importing this module should register additional behaviors or
         behavior classes via the behavior registry decorators.