Cropbox

Cropbox is a declarative framework for building and running crop models in Julia. You describe model components, variables, equations, data sources, and update rules. Cropbox orders those calculations, carries configuration and time through the model, and collects simulation output into data frames.

using Cropbox

@system Growth(Controller) begin
    rate: growth_rate => 1.5 ~ preserve(parameter, u"g/hr")
    mass(rate)               ~ accumulate(u"g")
end

result = simulate(Growth; stop = 3u"hr")

4×3 DataFrame

Row	time	rate	mass
	Quantity…	Quantity…	Quantity…
1	0//1 hr	1.5 g hr^-1	0.0 g
2	1//1 hr	1.5 g hr^-1	1.5 g
3	2//1 hr	1.5 g hr^-1	3.0 g
4	3//1 hr	1.5 g hr^-1	4.5 g

This is a small example, but the same workflow is used in coupled leaf gas exchange, garlic growth, SimpleCrop, layered soil, and root architecture models.

Choose a path

New to Cropbox: start with Quick Start.
Building a model: read How Cropbox Works, then Weather-driven Phenology.
Using an existing model: go directly to the Leaf Gas Exchange, Garlic, SimpleCrop, Soil Water Transport, or CropRootBox tutorial.
Looking up syntax: use DSL Syntax and Behaviors and Tags.
Maintaining or extending a model package: combine Systems and Composition, DSL Syntax, Inspection, and Dynamic Hierarchies as needed.
Debugging or optimizing a model: see Frequently Asked Questions, Common Mistakes, and Performance and Reproducibility.

The normal workflow

Cropbox follows the same three-phase workflow used in Cropbox courses:

Phase	Goal	Main tools
Specification	Define processes, states, inputs, and dependencies.	`@system`, behaviors, tags, units
Simulation	Apply scenarios, advance state, and collect selected output.	`parameters`, `@config`, `instance`, `simulate`
Visualization and evaluation	Explore predictions and compare them with observations.	`visualize`, `evaluate`, `calibrate`

Cropbox deliberately separates model equations from scenario configuration. One model definition can therefore be reused with different weather data, cultivars, management settings, and parameter combinations. See How Cropbox Works for the complete workflow diagram and the role of each phase.

Model examples

The worked tutorials progress from framework mechanics to coupled applications:

Tutorial	What it demonstrates
Logistic Growth	translating a differential equation into states, rates, and configuration
Weather-driven Phenology	calendar time, tabular weather input, thermal time, and a biological stop condition
Predator–Prey Model	Lotka–Volterra equations, coupled accumulated states, mixin extension, and observation-based fitting
Leaf Gas Exchange	inspecting a coupled biochemical model across configured environmental ranges
Garlic Growth Model	whole-plant composition, daily output, and dynamic organs
SimpleCrop	running a compact crop model and reading development, growth, and environmental output
Soil Water Transport	layered storage and fluxes, pedotransfer functions, and a test-suite simulation
Root System Architecture	stochastic configuration, dynamic systems, geometry, and custom summaries

These examples are drawn from Cropbox tests, courses, and workshops. The Model Gallery links their package repositories and additional workshop material.

After a model can be simulated and visualized, continue with Evaluate and Calibrate Models. It belongs to the workflow that compares predictions with observations, rather than to the sequence of model examples.

Citation

When using Cropbox in your work, please cite the following paper:

Yun K, Kim S-H (2023) “Cropbox: a declarative crop modelling framework.” in silico Plants 5(1), diac021. doi:10.1093/insilicoplants/diac021

@article{Cropbox2023,
    title = {Cropbox: a declarative crop modelling framework},
    author = {Yun, Kyungdahm and Kim, Soo-Hyung},
    journal = {in silico Plants},
    volume = {5},
    number = {1},
    year = {2023},
    doi = {10.1093/insilicoplants/diac021}
}

The repository also keeps this entry in CITATION.bib.