larvaworld.lib.model.modules.basic
==================================

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


Classes
-------

.. autoapisummary::

   larvaworld.lib.model.modules.basic.Effector
   larvaworld.lib.model.modules.basic.StepEffector
   larvaworld.lib.model.modules.basic.StepOscillator
   larvaworld.lib.model.modules.basic.SinOscillator
   larvaworld.lib.model.modules.basic.NengoEffector


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

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

   Bases: :py:obj:`larvaworld.lib.model.modules.oscillator.Timer`


   Base effector module for behavioral output generation.

   Abstract base class for all behavioral modules that produce motor
   outputs (crawlers, turners, feeders, sensors). Provides noise
   application, activation control, and input/output processing.

   Attributes:
       input_noise: Gaussian noise magnitude applied to input (0-1)
       output_noise: Gaussian noise magnitude applied to output (0-1)
       input_range: Valid input range (min, max)
       output_range: Valid output range (min, max)
       input: Current input value
       output: Current output value
       active: Whether effector is currently active

   Example:
       >>> # Use concrete subclasses like StepEffector, Crawler, Turner
       >>> effector = StepEffector(amp=0.5, input_noise=0.1)
       >>> output = effector.step(A_in=0.3)


   .. py:attribute:: input_noise


   .. py:attribute:: output_noise


   .. py:attribute:: input_range


   .. py:attribute:: output_range


   .. py:attribute:: input
      :value: 0



   .. py:attribute:: output
      :value: 0



   .. py:method:: update_output(output: Any) -> Any


   .. py:method:: update_input(input: Any) -> Any


   .. py:method:: apply_noise(value: Any, noise: float = 0, range: Any | None = None) -> Any


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


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


   .. py:method:: act(**kwargs: Any) -> None


   .. py:method:: inact(**kwargs: Any) -> None


   .. py:method:: step(A_in: float = 0, **kwargs: Any) -> Any


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

   Bases: :py:obj:`Effector`


   Step-based effector with amplitude control.

   Extends Effector with amplitude-based activation (Act = amp × phase).
   Base class for step-driven behaviors (crawling, constant turning).

   Attributes:
       amp: Oscillation amplitude coefficient
       Act_coef: Activation coefficient (returns amp)
       Act_Phi: Activation phase modulation (returns 1 for constant)
       Act: Total activation (Act_coef × Act_Phi)

   Example:
       >>> step_eff = StepEffector(amp=0.8)
       >>> output = step_eff.step()


   .. py:attribute:: amp


   .. py:property:: Act_coef
      :type: float



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



   .. py:property:: Act
      :type: float



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


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


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


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


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

   Bases: :py:obj:`larvaworld.lib.model.modules.oscillator.Oscillator`, :py:obj:`StepEffector`


   Step oscillator combining oscillation with step-based activation.

   Merges Oscillator phase tracking with StepEffector amplitude control.
   Base class for oscillatory behaviors (peristaltic crawling, sinusoidal turning).

   Example:
       >>> step_osc = StepOscillator(freq=1.5, amp=0.7)
       >>> output = step_osc.step()


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


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

   Bases: :py:obj:`StepOscillator`


   Sinusoidal oscillator with sine-wave phase modulation.

   Extends StepOscillator with sinusoidal activation (Act_Phi = sin(φ)).
   Used for smooth oscillatory behaviors like sinusoidal turning.

   Example:
       >>> sin_osc = SinOscillator(freq=0.58, amp=0.4)
       >>> output = sin_osc.step()


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



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

   Bases: :py:obj:`StepOscillator`


   Nengo-compatible effector with frequency-based activation control.

   Extends StepOscillator with automatic frequency setting on start/stop.
   Used for Nengo neural simulator integration.

   Example:
       >>> nengo_eff = NengoEffector(freq=1.2, amp=0.5)
       >>> nengo_eff.start_effector()  # Sets freq to initial_freq
       >>> nengo_eff.stop_effector()   # Sets freq to 0


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


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