# 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: ```{mermaid} 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 ```{mermaid} 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**: ```{mermaid} 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 | --- ## Related Documentation - {doc}`architecture_overview` - Layered architecture - {doc}`dependencies` - Third-party dependencies - {doc}`module_interaction` - Runtime interactions - {doc}`experiment_configuration_pipeline` - Configuration system