larvaworld.lib.model.modules.crawler
====================================

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


Classes
-------

.. autoapisummary::

   larvaworld.lib.model.modules.crawler.Crawler
   larvaworld.lib.model.modules.crawler.StrideOscillator
   larvaworld.lib.model.modules.crawler.GaussOscillator
   larvaworld.lib.model.modules.crawler.SquareOscillator
   larvaworld.lib.model.modules.crawler.PhaseOscillator


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

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

   Bases: :py:obj:`larvaworld.lib.model.modules.basic.StepEffector`


   Base crawler module for peristaltic locomotion.

   Abstract base class for crawling behavior modules that generate
   forward locomotion through peristaltic waves. Extends StepEffector
   to provide stride-based movement with oscillatory patterns.

   Example:
       >>> # Use concrete subclasses like StrideOscillator, GaussOscillator
       >>> crawler = GaussOscillator(freq=1.5, stride_dst_mean=0.25)


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

   Bases: :py:obj:`Crawler`, :py:obj:`larvaworld.lib.model.modules.basic.StepOscillator`


   Stride-based oscillatory crawler with variable step length.

   Implements peristaltic crawling using frequency-based oscillation
   with stochastic stride lengths. Each stride distance is sampled
   from a normal distribution, providing realistic locomotion variability.

   Attributes:
       freq: Oscillation frequency in Hz (0.5-3.0)
       stride_dst_mean: Mean stride distance (fraction of body length)
       stride_dst_std: Stride distance standard deviation
       step_to_length: Current stride distance (resampled each stride)

   Example:
       >>> crawler = StrideOscillator(freq=1.42, stride_dst_mean=0.23, stride_dst_std=0.04)
       >>> velocity = crawler.step()


   .. py:attribute:: freq


   .. py:attribute:: stride_dst_mean


   .. py:attribute:: stride_dst_std


   .. py:attribute:: step_to_length


   .. py:property:: new_stride
      :type: float



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



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


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


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

   Bases: :py:obj:`StrideOscillator`


   Gaussian-windowed oscillatory crawler.

   Extends StrideOscillator with gaussian-shaped velocity modulation
   within each stride cycle. Provides smooth, biologically realistic
   acceleration/deceleration profiles during peristaltic crawling.

   Attributes:
       std: Standard deviation of gaussian window (fraction of cycle, 0-1)
       gauss_w: Precomputed 360-point gaussian window for cycle modulation

   Example:
       >>> crawler = GaussOscillator(freq=1.5, std=0.6, stride_dst_mean=0.25)
       >>> velocity = crawler.step()


   .. py:attribute:: std


   .. py:attribute:: gauss_w


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



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

   Bases: :py:obj:`StrideOscillator`


   Square-wave oscillatory crawler.

   Extends StrideOscillator with square-wave velocity modulation,
   creating distinct power/recovery phases in each stride cycle.

   Attributes:
       duty: Duty cycle fraction (0-1) for square wave modulation
             Controls percentage of time at maximum velocity

   Example:
       >>> crawler = SquareOscillator(freq=1.2, duty=0.6, stride_dst_mean=0.20)
       >>> velocity = crawler.step()


   .. py:attribute:: duty


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



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


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

   Bases: :py:obj:`StrideOscillator`


   Phase-modulated oscillatory crawler with realistic velocity profile.

   Extends StrideOscillator with cosine-based phase modulation,
   producing the most biologically realistic peristaltic crawling patterns.
   Velocity peaks at a configurable phase within each stride cycle.

   Attributes:
       max_vel_phase: Phase angle (radians) where velocity is maximum
       max_scaled_vel: Maximum scaled forward velocity coefficient

   Example:
       >>> crawler = PhaseOscillator(freq=1.42, max_vel_phase=3.49, max_scaled_vel=0.51)
       >>> velocity = crawler.step()


   .. py:attribute:: max_vel_phase


   .. py:attribute:: max_scaled_vel


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



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