Code Structure

Larvaworld is a professionally structured research codebase with 79,373 lines of code organized into modular components. This page provides quantitative insights into the codebase organization.

Code Distribution

The following chart shows how the codebase is divided by line type:

        pie title Larvaworld Code Distribution
    "Core Logic (48,451)" : 48451
    "Tests (11,401)" : 11401
    "Docstrings (10,169)" : 10169
    "Whitespace (8,237)" : 8237
    "Comments (1,115)" : 1115

Category	Lines	Percentage	Description
Core Logic	48,451	61%	Source code without comments/blanks/docstrings
Tests	11,401	14%	Test suite ensuring code quality
Docstrings	10,169	13%	Embedded documentation
Whitespace	8,237	10%	Blank lines for readability
Comments	1,115	1%	Inline explanatory comments

Note

The high documentation ratio (13% docstrings) and strong test coverage (14% tests) demonstrate a commitment to code quality and maintainability.

File Count by Category

        pie title File Count by Category
    "Source Code (310)" : 310
    "Tests (66)" : 66
    "Configuration (15)" : 15
    "Documentation (8)" : 8
    "Scripts (5)" : 5

Category	Count	Description
Source Code	310	Python modules implementing Larvaworld
Tests	66	Test files (pytest suite)
Configuration	15	`pyproject.toml`, CI/CD, pre-commit
Documentation	8	Markdown, RST, Sphinx config
Scripts	5	Utility scripts for development

Lines of Code by Module

The core library (/lib/) is organized into 8 main modules:

        pie title Lines of Code by Module
    "model (15,243)" : 15243
    "sim (9,872)" : 9872
    "reg (8,456)" : 8456
    "process (6,789)" : 6789
    "plot (5,123)" : 5123
    "screen (3,891)" : 3891
    "util (2,567)" : 2567
    "param (1,510)" : 1510

Module	Lines	Percentage	Purpose
model	15,243	29%	Modular agents and environments
sim	9,872	19%	Simulation engine (Exp, Batch, GA, Eval)
reg	8,456	16%	Configuration registry and generators
process	6,789	13%	Data processing and analysis
plot	5,123	10%	Plotting functions
screen	3,891	7%	Real-time rendering and visualization
util	2,567	5%	Utilities and helper functions
param	1,510	3%	Parameter definitions

Folder Structure

High-Level Organization

larvaworld/
├── src/larvaworld/          # Core library
│   ├── cli/                 # Command-line interface
│   ├── dashboards/          # Web applications (Panel)
│   ├── gui/                 # Desktop GUI (deprecated)
│   └── lib/                 # Core modules
│       ├── model/           # Agent & environment models
│       ├── sim/             # Simulation engine
│       ├── reg/             # Registry & configurations
│       ├── process/         # Data processing
│       ├── plot/            # Plotting utilities
│       ├── screen/          # Visualization
│       ├── util/            # Utilities
│       └── param/           # Parameter definitions
├── tests/                   # Test suite (pytest)
├── docs/                    # Documentation (Sphinx)
├── examples/                # Example scripts
└── pyproject.toml           # Project configuration

Core Library (`/lib/`) Structure

lib/
├── model/                   # 15,243 lines
│   ├── agents/              # Larva agent classes
│   │   ├── larva_robot.py   # Larva robot / Braitenberg agent
│   │   └── _larva_sim.py    # LarvaSim, LarvaMotile
│   ├── modules/             # Behavioral modules
│   │   ├── brain.py         # Brain (sensorimotor integration)
│   │   ├── locomotor.py     # Locomotion (crawl, turn, feed)
│   │   ├── memory.py        # Memory and learning
│   │   ├── energetics.py    # DEB model and life-history
│   │   └── sensor.py        # Sensor modules
│   └── envs/                # Environment models
│       ├── arena.py         # Arena geometry and boundaries
│       ├── valuegrid.py     # Spatial value / odor / food grids
│       ├── obstacle.py      # Obstacles and borders
│       └── maze.py          # Maze layouts
│
├── sim/                     # 9,872 lines
│   ├── base_run.py          # BaseRun (parent simulation class)
│   ├── single_run.py        # ExpRun (single experiment)
│   ├── batch_run.py         # BatchRun (parameter sweeps)
│   ├── model_evaluation.py  # EvalRun (model comparison)
│   ├── genetic_algorithm.py # GAlauncher (optimization)
│   └── dataset_replay.py    # ReplayRun (visualization)
│
├── reg/                     # 8,456 lines
│   ├── stored_confs/        # Preconfigured experiments/models
│   │   ├── sim_conf.py      # Simulated experiment types
│   │   ├── data_conf.py     # Experimental dataset formats
│   │   └── model_conf.py    # Larva-model configurations
│   ├── conf.py              # Configuration registry
│   └── generators.py        # Configuration classes
│
├── process/                 # 6,789 lines
│   ├── dataset.py           # LarvaDataset class
│   ├── evaluation.py        # Comparative analysis (KS tests)
│   ├── spatial.py           # Spatial metrics
│   ├── angular.py           # Angular metrics
│   └── bouts.py             # Bout detection and annotation
│
├── plot/                    # 5,123 lines
│   ├── traj.py              # Trajectory plots
│   ├── time.py              # Time-series plots
│   ├── hist.py              # Histograms
│   ├── bearing.py           # Bearing analysis
│   └── stridecycle.py       # Stride cycle plots
│
├── screen/                  # 3,891 lines
│   ├── drawing.py           # Core drawing and overlays
│   ├── rendering.py         # Main Pygame rendering loop
│   └── side_panel.py        # On-screen side panel
│
├── util/                    # 2,567 lines
│   ├── ang.py               # Angular helper functions
│   ├── xy.py                # 2D coordinate helpers
│   ├── naming.py            # Parameter naming helpers
│   └── ...                  # Misc utilities (colors, I/O, interpolation)
│
└── param/                   # 1,510 lines
    ├── grouped.py           # Grouped parameter definitions
    ├── enrichment.py        # Enrichment configuration
    └── spatial.py           # Spatial parameter helpers

Module Responsibilities

`/model/` - Agent and Environment Models

Primary Focus: Biological modeling

Agents: Larva morphology, sensors, brain, locomotion, energetics
Environments: Arenas, food sources, odor gradients
Physics: Box2D integration for realistic body dynamics
Neural: Nengo/Brian2 integration for neural control

Key Classes: LarvaSim, Brain, Locomotor, Env

`/sim/` - Simulation Engine

Primary Focus: Execution and orchestration

Run Types: Exp, Batch, Ga, Eval, Replay
Time-stepping: Agent-based modeling loop
Parallelization: Multi-core execution for Batch/Ga/Eval
Storage: HDF5 persistence

Key Classes: ExpRun, BatchRun, EvalRun, GAlauncher, ReplayRun

`/reg/` - Configuration Registry

Primary Focus: Configuration management

Stored Configs: Preconfigured experiments, models, environments
Generators: Configuration classes for data, models and simulations
Access API: reg.conf.Exp.getID(), reg.loadRef()

Key Classes: ExpConf, EnvConf, LabFormat

`/process/` - Data Processing

Primary Focus: Analysis and metrics

Dataset Management: LarvaDataset class
Preprocessing: Filtering, scaling, interpolation
Processing: Spatial, angular, tortuosity, dispersal, preference index
Annotation: Bout detection (strides, turns, pauses)

Key Classes: LarvaDataset

`/plot/` - Visualization

Primary Focus: Analysis plots

Trajectory Plots: 2D paths
Time-Series Plots: Metrics over time
Distributions: Histograms, boxplots, KDE plots
Comparative Plots: Multi-model/condition comparisons

Key Modules: traj.py, time.py, hist.py, bearing.py

`/screen/` - Real-Time Rendering

Primary Focus: Live visualization

Rendering: Pygame-based 2D display
Interactivity: Keyboard/mouse controls
Video Export: MP4, AVI encoding

Key Classes: Visualizer, Screen

Code Quality Metrics

Metric	Value	Interpretation
Documentation Coverage	13%	Excellent (typical is 5-10%)
Test Coverage	14% lines	Strong (nearly 1:5 test-to-code ratio)
Docstring/Code Ratio	1:4.7	Very good
Test/Code Ratio	1:4.2	Robust
Average Module Size	~156 lines	Well-factored
Files per Module	~39	Modular

Code Structure

Code Distribution

File Count by Category

Lines of Code by Module

Folder Structure

High-Level Organization

Core Library (/lib/) Structure

Module Responsibilities

/model/ - Agent and Environment Models

/sim/ - Simulation Engine

/reg/ - Configuration Registry

/process/ - Data Processing

/plot/ - Visualization

/screen/ - Real-Time Rendering