geoaquacrop_simulate

Gridded AquaCrop-OSPy simulation engine for the GeoAquaCrop toolchain.

Overview

geoaquacrop_simulate runs AquaCrop-OSPy over large regions in gridded format. It takes the harmonised input datasets produced by geoaquacrop_preprocess, runs an independent AquaCrop simulation for every grid cell in parallel, and writes per-cell seasonal and daily results. These outputs can then be visualized by geoaquacrop_visualize.

It is the middle stage of the GeoAquaCrop toolchain:

geoaquacrop_preprocess  ->  geoaquacrop_simulate  ->  geoaquacrop_visualize
(download & harmonise)   (simulate & correct)         (explore results)

Supported crop types

Barley, Cassava, Cotton, Dry Bean, Maize, Paddy Rice (seasons 1 & 2), Potato, Sorghum, Soybean, Sugar Beet, Sugar Cane, Sunflower, Wheat (summer & winter)

Prerequisites

• Miniconda or Anaconda
• Python 3.11+
• Input datasets produced by geoaquacrop_preprocess

Installation

git clone https://github.com/aquacropos/geoaquacrop_simulate
cd geoaquacrop_simulate
conda create -n geoaquacrop python=3.11
conda activate geoaquacrop
python -m pip install -e .

Optional extras: .[dev] (pytest), .[correction] (geopandas, matplotlib), .[plots] (dash, plotly).

Quick start

Option A — edit and run the main script

Open src/geoaquacrop_simulate/run_aquacrop.py, set the configuration dictionary at the top of main(), and run:

conda activate geoaquacrop
python -m geoaquacrop_simulate.run_aquacrop

Key input arguments:

config_dict = {
    'weather_path': '/path/to/geoaquacrop_preprocess/processed',
    'soil_path':    '/path/to/geoaquacrop_preprocess/processed',
    'pheno_path':   '/path/to/geoaquacrop_preprocess/processed',
    'spam_path':    '/path/to/geoaquacrop_preprocess/processed',
    'start_date':   '2008/01/01',
    'end_date':     '2010/12/31',
    'crop':         'Maize',
    'irrigation':   'rainfed',      # 'rainfed' | 'irrigated'
    'output_dir':   'outputs',
}

Option B — Python API

from geoaquacrop_simulate.run_aquacrop import main

summary_file, daily_file = main()

This is also how to run from an IDE console (Spyder, Jupyter). Do not execute module files directly — a module run as a script has no package context and its relative imports fail.

Output files

Written to <output_dir>/:

Yield correction

Optional. Brings modelled yields into line with an observational reference, per year, aggregating the model up to the reference's native support (e.g. counties) rather than rasterising the observations.

'correction': {
    'method': 'scale',            # None | 'scale' | 'calibrate'
    'reference_path': 'reference/high_plains_maize_reference.geojson',
    'scale_mode': 'local',        # 'global' | 'local'
    'lever': 'canopy',            # calibrate: 'canopy' (CCx) | 'biomass' (WP)
    'reuse_results': 'latest',    # scale an existing run with no simulation
}

See the yield correction guide for what each mode does and how to interpret the results.

Documentation

Full documentation: https://geoaquacrop-simulate.readthedocs.io

Tests

python -m pytest -q

License

Apache 2.0 — see LICENSE.