Architecture Overview

Larvaworld follows a layered architecture pattern that separates concerns and enables flexible extension. This design allows users to access the platform through multiple interfaces while maintaining a unified core engine for simulation and analysis.

Five-Layer Architecture

Larvaworld is organized into five interconnected layers, each with distinct responsibilities:

        graph TB
    UI[User Interfaces<br/>CLI • Web • GUI]
    Sim[Simulation Engine<br/>Exp • Batch • GA • Eval]
    Model[Models<br/>Agents • Envs • Modules]
    Data[Data Layer<br/>Import • Storage • Analysis]
    Viz[Visualization<br/>Plots • Video • Dashboards]

    UI --> Sim
    Sim --> Model
    Model --> Data
    Data --> Viz
    Viz --> UI

    style UI fill:#2196f3,stroke:#1976d2,stroke-width:2px,color:#fff
    style Sim fill:#4caf50,stroke:#388e3c,stroke-width:2px,color:#000
    style Model fill:#9c27b0,stroke:#7b1fa2,stroke-width:2px,color:#fff
    style Data fill:#f44336,stroke:#d32f2f,stroke-width:2px,color:#fff
    style Viz fill:#ff9800,stroke:#f57c00,stroke-width:2px,color:#000

Layer 1: User Interfaces

Command-Line Interface (CLI)

Location: /src/larvaworld/cli/

The CLI provides direct access to all simulation modes through an argparse-based interface:

larvaworld Exp dish -N 5 -duration 3.0
larvaworld Eval -refID exploration.30controls --modelIDs explorer navigator
larvaworld Batch PItest_off -N 10

Key Components:

main.py: Entry point with main() function
argparser.py: SimModeParser class for argument parsing
Modes: Exp, Batch, Ga, Eval, Replay

Use case: Quick simulation launching

Web Dashboards

Location: /src/larvaworld/dashboards/

Interactive web applications built with Panel (Holoviz stack) and Bokeh:

Dashboard	Purpose
Experiment Viewer	View experiment results interactively
Track Viewer	Inspect larva trajectories
Larva-model Inspector	Explore larva models
Module Inspector	Inspect behavioral modules

Launch with:

larvaworld-app

Access via: http://localhost:5006

Use case: Interactive exploration, parameter tuning, visualization

GUI (Deprecated)

Location: /src/larvaworld/gui/

Warning

The desktop GUI built with PySimpleGUI is deprecated but still present for backward compatibility. It is not included in the accessible entry points and may not be fully supported in current releases. Use CLI or Web apps instead.

Layer 2: Simulation Engine

Location: /src/larvaworld/lib/sim/

The simulation engine provides five specialized modes, each optimized for different workflows:

Mode	Class	File	Purpose
Exp	`ExpRun`	`single_run.py`	Single experiment run
Batch	`BatchRun`	`batch_run.py`	Multiple parallel experiments
Ga	`GAlauncher`	`genetic_algorithm.py`	Genetic algorithm optimization
Eval	`EvalRun`	`model_evaluation.py`	Model evaluation vs. real data
Replay	`ReplayRun`	`dataset_replay.py`	Replay recorded trajectories

Common base classes:

BaseRun: Base class for ExpRun, GAlauncher, and ReplayRun
SimConfiguration / AgentPy Experiment: Used by modes like EvalRun and BatchRun
ABModel: AgentPy-based agent-based model implementation used by BaseRun

Key entry points (vary by mode):

simulate(): Run the simulation loop
store(): Save results to HDF5
analyze(): Perform data analysis
plot(): Generate analysis plots

For detailed information on simulation modes, see Simulation Modes.

Layer 3: Models

Location: /src/larvaworld/lib/model/

This layer contains the agent models (larvae) and environment models (arenas).

Agent Models

Key Classes:

LarvaSim: Complete larva agent (inherits from LarvaMotile and BaseController)
LarvaMotile: Core agent step-by-step behavior (inherits from LarvaSegmented)
LarvaSegmented: Morphology (shape, segments, sensors)
Brain: Sensory integration and locomotor control
Locomotor: Unified crawling, turning, and feeding

Modules (in modules/):

Sensors: Olfactor, Toucher, Windsensor, Thermosensor (and variants, e.g. OSN olfaction via remote Brian2)
Brain: DefaultBrain, NengoBrain
Locomotor: Crawler, Turner, Feeder, Interference
Energetics: DEB (Dynamic Energy Budget)

For detailed architecture, see Larva Agent Architecture and Brain Module Architecture.

Environment Models

Key Classes:

Arena: Arena with food/odor sources, borders
Source: Single/distributed food/odor sources
Odorscape: Gaussian or diffusion-generated gradients

Configuration:

Configurable via EnvConf registry entries
Pre-configured arenas (e.g., 'dish', 'arena_200mm')

For details, see Arenas and Substrates.

Layer 4: Data Layer

Location: /src/larvaworld/lib/process/ and /src/larvaworld/lib/reg/

This layer handles data import, storage, processing, and analysis.

Dataset Management

LarvaDataset (dataset.py):

Time-series data: Pose, velocity, acceleration, orientation
Endpoint data: Summary statistics per larva
Bout data: Annotated behavioral events (strides, turns, pauses)
Storage: HDF5 format for efficient I/O

Methods:

preprocess(): Filtering, scaling, alignment
process(): Compute metrics (angular, spatial, tortuosity)
annotate(): Detect bouts (strides, turns, pauses)

For detailed workflows, see Data Processing.

Data Import

LabFormat (reg/generators.py):

Import experimental datasets from diverse tracking systems
Registered lab-specific formats: Schleyer, Jovanic, Berni, Arguello

Note

At the moment, LabFormat.import_dataset() is fully supported for the Schleyer and Jovanic formats. Berni and Arguello formats are registered in the configuration system but are not yet wired via import_dataset().

For details, see Lab-Specific Data Import.

Registry

Configuration Registry (/src/larvaworld/lib/reg/):

stored_confs/: Preconfigured experiments, models, environments
reg.conf: Access configurations (Env, Model, Exp, Batch, Ga)
reg.gen: Generators for configurations and datasets

For details, see Experiment Configuration Pipeline.

Layer 5: Visualization

Location: /src/larvaworld/lib/plot/ and /src/larvaworld/lib/screen/

This layer provides plotting, real-time rendering, and video export.

Plotting

Modules (in plot/):

traj.py: Trajectory plots
time.py: Time-series plots
hist.py: Histograms and distributions
bearing.py: Bearing plots (odor navigation)
stridecycle.py: Stride cycle analysis
deb.py: DEB energetics plots

For details, see Plotting.

Real-Time Visualization

Screen (screen/):

Real-time 2D rendering using Pygame
Configurable drawing (midline, contour, trails)
Interactive controls (zoom, pause, snapshot)
Video export (MP4, AVI)

For keyboard controls, see Keyboard Controls.

Mapping to Codebase

Layer	Primary Folders	Key Classes/Files
User Interfaces	`/cli`, `/dashboards`, `/gui`	`cli/main.py`, `dashboards/main.py`
Simulation Engine	`/lib/sim`	`ExpRun`, `BatchRun`, `EvalRun`, `GAlauncher`, `ReplayRun`
Models	`/lib/model`	`LarvaSim`, `Brain`, `Locomotor`, `Env`
Data Layer	`/lib/process`, `/lib/reg`	`LarvaDataset`, `LabFormat`, `reg.conf`
Visualization	`/lib/plot`, `/lib/screen`	`plot/traj.py`, `screen/drawing.py`

Data Flow

Experiment Execution Flow

1. User Input (CLI/Web/Python)
   ↓
2. Configuration Loading (reg.conf)
   ↓
3. Simulation Setup (ExpRun/BatchRun/EvalRun)
   ↓
4. Agent Creation (LarvaSim × N)
   ↓
5. Simulation Loop (AgentPy `Model.run()` / `BaseRun.sim_step()`)
   ↓
6. Data Collection (`LarvaDatasetCollection` → `LarvaDataset`)
   ↓
7. Storage (HDF5)
   ↓
8. Analysis & Plotting (dataset.process(), LarvaDatasetCollection.plot())
   ↓
9. Visualization (Screen / Video / Dashboards)

For detailed runtime interactions, see Module Interaction.