joshpy

Python client for Josh ecological simulations

joshpy enables parameter sweeps, experiment tracking, and result analysis for Josh agent-based ecological simulations.

Features

Orchestration: Define parameter sweeps with Jinja templating and execute simulations
Tracking: DuckDB-backed registry for experiment management
Analysis: Query results across parameter values and replicates
Visualization: Quick matplotlib diagnostics + R/ggplot2 for publication-quality figures

Get Started

Installation - Install joshpy
Quickstart - Run your first simulation
Architecture - How GridSpec, JobConfig, SweepManager, RunRegistry, and ProjectCatalog fit together
Tutorials - Step-by-step guides

Tutorials

Getting Started

Single Run & Iteration - Run, tweak, compare: the daily research workflow
SweepManager Workflow - Systematic parameter sweeps
Analysis & Visualization - Explore results with queries, plots, and R/ggplot2

External Data

Preprocessing - Convert geospatial data to Josh’s .jshd format
External Data Sweeps - Sweep over different input data files
Timestep Interventions - Single-time data for initialization and discrete events

Project Structure

Project Organization - Directory layout, model templating, GridSpec
Multi-Session Sweeps - Track sweeps across sessions with ProjectCatalog

Advanced

Adaptive Optimization - Bayesian parameter optimization with Optuna
Low-Level Components - JobExpander, manual registry, internals
Debug Output Inspection - Trace agent behavior with structured debug log analysis
Finding Bottlenecks - Find and fix slow attributes in simulations
Switching Josh Versions - Stable vs development builds
Remote Execution - Distribute simulations across Josh Cloud

Links