larvaworld.lib.model.modules.intermitter

Classes

`Intermitter`	Intermitter module for run/pause/feed behavioral state control.
`OfflineIntermitter`	Offline intermitter with fixed-frequency stride/feed detection.
`BranchIntermitter`	Branch intermitter with critical dynamics for pause/run generation.
`FittedIntermitter`	Fitted intermitter using reference dataset parameters.

Functions

`get_EEB_poly1d`(→ numpy.poly1d)	Compute polynomial fit of EEB vs mean feeding frequency.
`get_EEB_time_fractions`(→ pandas.DataFrame)	Compute time fractions for behavioral states across EEB range.

Module Contents

class larvaworld.lib.model.modules.intermitter.Intermitter(**kwargs: Any)

Bases: larvaworld.lib.model.modules.oscillator.Timer

Intermitter module for run/pause/feed behavioral state control.

Manages transitions between locomotor states (running, pausing, feeding) using stochastic bout generators. Controls exploitation-exploration balance (EEB) for feeding decisions and tracks behavioral statistics.

Attributes:

EEB: Exploitation-exploration balance (0=exploit, 1=explore) EEB_decay: Exponential decay of EEB when no food detected crawl_freq: Default crawling frequency (Hz) feed_freq: Default feeding frequency (Hz) run_mode: Generation mode (‘stridechain’ or ‘exec’) feeder_reoccurence_rate: Feed reoccurrence probability feed_bouts: Whether feeding epochs are generated pause_dist: Temporal distribution params for pause epochs stridechain_dist: Stride-number distribution for run epochs run_dist: Temporal distribution for run epochs cur_state: Current behavioral state (‘exec’, ‘pause’, or ‘feed’)

Example:

>>> intermitter = Intermitter(EEB=0.3, crawl_freq=1.42, feed_freq=2.0)
>>> state = intermitter.step(stride_completed=True, on_food=False)

EEB

EEB_decay

crawl_freq

feed_freq

run_mode

feeder_reoccurence_rate

feed_bouts

pause_dist

stridechain_dist

run_dist

cur_state = None

pause_generator

Nstrides = 0

Nstridechains = 0

Nruns = 0

Npauses = 0

Nfeeds = 0

Nfeedchains = 0

Nfeeds_success = 0

Nfeeds_fail = 0

base_EEB

exp_Nstrides = None

cur_Nstrides = 0

exp_Trun = None

exp_Tpause = None

cur_Nfeeds = None

stridechain_lengths = []

stridechain_durs = []

feedchain_lengths = []

feedchain_durs = []

pause_durs = []

run_durs = []

feed_durs = []

stride_durs = []

property pause_completed: bool

property run_completed: bool

property stridechain_completed: bool

alternate_crawlNpause(stride_completed: bool = False) → None

property feed_repeated: bool

alternate_exploreNexploit(feed_motion: bool = False, on_food: bool = False) → None

register(bout: str | None = None) → None

update_state(stride_completed: bool = False, feed_motion: bool = False, on_food: bool = False) → str | None

step(**kwargs: Any) → str | None

generate_stridechain() → int

generate_run() → float

interrupt_locomotion() → None

trigger_locomotion(force: bool = False) → None

generate_pause() → float

build_dict() → dict[str, Any]

save_dict(path: str | None = None, dic: dict[str, Any] | None = None) → None

property active_bouts: tuple[int | None, int | None, float | None, float | None]

property mean_feed_freq: float

class larvaworld.lib.model.modules.intermitter.OfflineIntermitter(**kwargs: Any)

Bases: Intermitter

Offline intermitter with fixed-frequency stride/feed detection.

Extends Intermitter with tick-based stride and feed detection at fixed intervals (offline mode, no real-time physics).

Example:

>>> offline_int = OfflineIntermitter(EEB=0.5, crawl_freq=1.5, dt=0.1)
>>> state = offline_int.step(on_food=True)

crawl_ticks

step(stride_completed: bool | None = None, feed_motion: bool | None = None, on_food: bool = True) → str | None

class larvaworld.lib.model.modules.intermitter.BranchIntermitter(**kwargs: Any)

Bases: Intermitter

Branch intermitter with critical dynamics for pause/run generation.

Extends Intermitter using exponential (exp_bout) and critical (critical_bout) distributions for more realistic behavioral branching. No feeding bouts in this mode.

Attributes:

feed_bouts: Fixed to False (no feeding) beta: Beta coefficient for exponential bout distribution c: Critical parameter for criticality function sigma: ISING branching coefficient

Example:

>>> branch_int = BranchIntermitter(beta=4.7, c=0.7, sigma=1.0, dt=0.1)
>>> state = branch_int.step(stride_completed=True)

feed_bouts

beta

c

sigma

generate_stridechain() → int

generate_pause() → float

class larvaworld.lib.model.modules.intermitter.FittedIntermitter(refID: str, **kwargs: Any)

Bases: OfflineIntermitter

Fitted intermitter using reference dataset parameters.

Constructs OfflineIntermitter from stored reference dataset configurations (crawl/feed frequencies, bout distributions).

Args:

refID: Reference dataset ID to load intermitter config from **kwargs: Override parameters (optional)

Example:

>>> fitted_int = FittedIntermitter(refID='exploration')
>>> state = fitted_int.step(on_food=False)

larvaworld.lib.model.modules.intermitter.get_EEB_poly1d(max_dur: float = 60 * 60, **kws: Any) → numpy.poly1d

Compute polynomial fit of EEB vs mean feeding frequency.

Simulates intermitter across EEB range (0-1) and fits polynomial to map feeding frequency back to EEB parameter.

Args:

max_dur: Maximum simulation duration (seconds) **kws: Intermitter configuration keyword arguments

Returns:

Polynomial (degree 5) mapping feed frequency to EEB

Example:

>>> poly = get_EEB_poly1d(crawl_freq=1.42, feed_freq=2.0, dt=0.1)
>>> eeb_estimate = poly(0.15)  # For feed_freq=0.15

larvaworld.lib.model.modules.intermitter.get_EEB_time_fractions(refID: str | None = None, dt: float | None = None, max_dur: float = 60 * 60, **kwargs: Any) → pandas.DataFrame

Compute time fractions for behavioral states across EEB range.

Simulates intermitter across EEB values (0-1) and computes duration ratios for crawl/pause/feed states. Returns DataFrame for analysis and visualization.

Args:

refID: Reference dataset ID for intermitter config (optional) dt: Time step override (optional) max_dur: Maximum simulation duration (seconds) **kwargs: Intermitter configuration if refID not provided

Returns:

DataFrame with EEB values and corresponding time fraction ratios

Example:

>>> df = get_EEB_time_fractions(refID='exploration', dt=0.1)
>>> print(df[['EEB', 'crawl ratio', 'pause ratio']])