larvaworld.lib.model.modules.oscillator
=======================================

.. py:module:: larvaworld.lib.model.modules.oscillator


Classes
-------

.. autoapisummary::

   larvaworld.lib.model.modules.oscillator.Timer
   larvaworld.lib.model.modules.oscillator.Oscillator


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

.. py:class:: Timer(**kwargs: Any)

   Bases: :py:obj:`param.Parameterized`


   Base timer module for time tracking and activation control.

   Provides time-step counting, activation state management, and
   iteration tracking. Base class for all time-dependent modules.

   Attributes:
       dt: Simulation time step in seconds
       ticks: Current elapsed ticks since last reset
       total_ticks: Total ticks since initialization
       active: Whether timer/module is currently active
       complete_iteration: Flag for iteration completion

   Example:
       >>> timer = Timer(dt=0.1)
       >>> timer.count_time()
       >>> print(f"Elapsed: {timer.t} seconds")


   .. py:attribute:: dt


   .. py:attribute:: ticks
      :value: 0



   .. py:attribute:: total_ticks
      :value: 0



   .. py:attribute:: active
      :value: True



   .. py:attribute:: complete_iteration
      :value: False



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


   .. py:property:: t
      :type: float



   .. py:property:: total_t
      :type: float



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


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


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


.. py:class:: Oscillator(random_phi: bool = True, **kwargs: Any)

   Bases: :py:obj:`Timer`


   Oscillator module for phase-based periodic behaviors.

   Extends Timer with phase tracking and oscillation mechanics.
   Manages phase progression, iteration detection, and frequency control
   for all oscillatory behavioral modules.

   Attributes:
       freq: Oscillation frequency in Hz
       phi: Current oscillation phase in radians (0-2π)
       initial_freq: Frequency at initialization (stored for reset)
       iteration_counter: Number of completed oscillation cycles
       complete_iteration: True when phase completes full 2π cycle

   Args:
       random_phi: If True, randomize initial phase (default: True)
       **kwargs: Additional keyword arguments passed to parent Timer

   Example:
       >>> oscillator = Oscillator(freq=1.5, random_phi=False)
       >>> oscillator.oscillate()
       >>> print(f"Phase: {oscillator.phi}, Completed: {oscillator.complete_iteration}")


   .. py:attribute:: freq


   .. py:attribute:: phi


   .. py:attribute:: initial_freq


   .. py:attribute:: iteration_counter
      :value: 0



   .. py:method:: set_freq(v: float) -> None


   .. py:method:: get_freq(t: float) -> float


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


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


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


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


   .. py:method:: phi_in_range(phi_range: tuple[float, float]) -> bool


   .. py:property:: Act_Phi
      :type: float