geoaquacrop_simulate

Gridded AquaCrop-OSPy simulation engine for the GeoAquaCrop toolchain.

Install

pip install geoaquacrop_simulate

Or install the whole toolchain in one go:

pip install geoaquacrop

Optional extras:

pip install "geoaquacrop_simulate[correction]"

Requires Python 3.11+ and the harmonised input datasets produced by geoaquacrop_preprocess.

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-OSPy simulation for every grid cell in parallel, and writes per-cell seasonal and daily results. Those outputs can then be explored with geoaquacrop_visualize.

It is the middle stage of the GeoAquaCrop toolchain:

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

Quick start

import geoaquacrop_simulate as simulate

summary_file, daily_file = simulate.run(
    data_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',
)

data_path fills the four input paths at once. Set weather_path, soil_path, pheno_path and spam_path individually if they live in different places.

The same call through the unified toolchain façade:

import geoaquacrop as gac

summary_file, daily_file = gac.simulate.run(data_path='...', crop='Maize')

To see every available setting:

import geoaquacrop_simulate as simulate

print(simulate.example_config())        # the full settings dictionary
print(simulate.input_requirements())    # the input files each stage expects

This works from a script, a notebook or an IDE console (Spyder, Jupyter).

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).

Output files

Written to <output_dir>/:

Load them back with simulate.load_results().

Yield correction

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

First build the reference from any boundary file and any table of yields per region per year:

simulate.build_reference(
    regions='provinces.geojson', region_id='NAME_LATN',
    table='wheat_yields.csv', table_id='region',
    year_col='year', value_col='yield_t_ha',
    out='reference.geojson',
)

Then pass a correction block to run():

correction = {
    'method': 'scale',                    # None | 'scale' | 'calibrate'
    'reference_path': 'reference.geojson',
    'scale_mode': 'local',                # 'global' | 'local'
    'lever': 'canopy',                    # calibrate: 'canopy' (CCx) | 'biomass' (WP)
    'reuse_results': 'latest',            # correct an existing run, no re-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/en/latest/

Development

To work on the package itself:

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 ".[dev,correction]"

Run the tests:

python -m pytest -q

From a checkout you can also set the configuration dictionary at the top of main() in src/geoaquacrop_simulate/run_aquacrop.py and run the module directly:

python -m geoaquacrop_simulate.run_aquacrop

Do not execute module files directly — a module run as a script has no package context and its relative imports fail.

Licence

Apache 2.0 — see LICENSE.