# abson-dev/aquacrop-grid architecture

> Architecture diagram of the GitHub repository abson-dev/aquacrop-grid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abson-dev/aquacrop-grid
- Repository: https://github.com/abson-dev/aquacrop-grid

## Overview

AquaCrop-Grid runs one rainfed AquaCrop season per raster pixel, accepting daily climate and per-pixel sowing dates, with an optional soil raster. The principal workflow validates the zarr inputs, prepares crop and soil parameters, processes spatial tiles through a shared runner and CPU or GPU kernels, then writes final results and optional daily series to zarr. The CLI also generates synthetic input data and reports throughput. The graph follows the README and indexed references; unsampled code limits detail on tile internals and the benchmark implementation.

Main entry points: [`src/aquacrop_grid/pipeline.py`](https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/pipeline.py) (Tiled pipeline), [`src/aquacrop_grid/cli.py`](https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/cli.py) (CLI commands), [`src/aquacrop_grid/io/synthetic.py`](https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/io/synthetic.py) (Synthetic data), [`src/aquacrop_grid/kernels/constants.py`](https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/kernels/constants.py) (Kernel array layout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_benchmark["Throughput benchmark<br/>[bench.py]"]
end

subgraph group_inputs["Raster preparation"]
  node_synthetic["Synthetic data<br/>[synthetic.py]"]
  node_schema["Input validation<br/>[schema.py]"]
  node_soilio["Soil raster I/O<br/>[soil.py]"]
  node_pipeline["Tiled pipeline<br/>[pipeline.py]"]
end

subgraph group_simulation["Simulation engine"]
  node_params["Crop parameters<br/>[params.py]"]
  node_soilgrid["Soil profile builder<br/>[soil_grid.py]"]
  node_runner["Array runner<br/>[run.py]"]
  node_cpu["CPU backend<br/>[cpu.py]"]
  node_gpu["GPU backend<br/>[gpu.py]"]
  node_loader["Kernel compiler<br/>[loader.py]"]
  node_kernels["Daily AquaCrop step<br/>[impl.py]"]
  node_constants["Kernel array layout<br/>[constants.py]"]
end

subgraph group_outputs["Results"]
  node_output[("Results zarr")]
end

node_user(("CLI user"))
node_climate[("Climate zarr")]
node_sowing[("Sowing zarr")]
node_soilstore[("Soil zarr")]

node_user -->|"invokes"| node_cli
node_cli -->|"runs simulation"| node_pipeline
node_cli -->|"generates inputs"| node_synthetic
node_cli -->|"measures throughput"| node_benchmark
node_synthetic -->|"writes"| node_climate
node_synthetic -->|"writes"| node_sowing
node_synthetic -->|"writes"| node_soilstore
node_climate -->|"supplies weather"| node_pipeline
node_sowing -->|"supplies dates"| node_pipeline
node_soilstore -->|"supplies soil"| node_pipeline
node_pipeline -->|"opens inputs"| node_schema
node_pipeline -->|"opens soil"| node_soilio
node_pipeline -->|"prepares parameters"| node_params
node_pipeline -->|"builds soil profiles"| node_soilgrid
node_pipeline -->|"runs tile arrays"| node_runner
node_pipeline -->|"writes results"| node_output
node_runner -->|"dispatches CPU"| node_cpu
node_runner -->|"dispatches GPU"| node_gpu
node_cpu -->|"loads kernels"| node_loader
node_gpu -->|"loads kernels"| node_loader
node_loader -->|"compiles source"| node_kernels
node_kernels -->|"uses indices"| node_constants
node_cpu -->|"uses output indices"| node_constants
node_gpu -->|"uses output indices"| node_constants
node_soilgrid -->|"consumes soil grid"| node_soilio
node_params -->|"packs parameters"| node_constants

click node_cli "https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/cli.py"
click node_benchmark "https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/bench.py"
click node_synthetic "https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/io/synthetic.py"
click node_schema "https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/io/schema.py"
click node_soilio "https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/io/soil.py"
click node_pipeline "https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/pipeline.py"
click node_params "https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/params.py"
click node_soilgrid "https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/soil_grid.py"
click node_runner "https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/engine/run.py"
click node_cpu "https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/engine/cpu.py"
click node_gpu "https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/engine/gpu.py"
click node_loader "https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/kernels/loader.py"
click node_kernels "https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/kernels/impl.py"
click node_constants "https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/kernels/constants.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_benchmark,node_user toneBlue
class node_synthetic,node_schema,node_soilio,node_pipeline,node_climate,node_sowing,node_soilstore toneAmber
class node_params,node_soilgrid,node_runner,node_cpu,node_gpu,node_loader,node_kernels,node_constants toneMint
class node_output toneRose
```

## Components

### User interface

- [CLI commands](https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/cli.py): `src/aquacrop_grid/cli.py`
- [Throughput benchmark](https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/bench.py): `src/aquacrop_grid/bench.py`

### Raster preparation

- [Synthetic data](https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/io/synthetic.py): `src/aquacrop_grid/io/synthetic.py`
- [Input validation](https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/io/schema.py): `src/aquacrop_grid/io/schema.py`
- [Soil raster I/O](https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/io/soil.py): `src/aquacrop_grid/io/soil.py`
- [Tiled pipeline](https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/pipeline.py): `src/aquacrop_grid/pipeline.py`

### Simulation engine

- [Crop parameters](https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/params.py): `src/aquacrop_grid/params.py`
- [Soil profile builder](https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/soil_grid.py): `src/aquacrop_grid/soil_grid.py`
- [Array runner](https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/engine/run.py): `src/aquacrop_grid/engine/run.py`
- [CPU backend](https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/engine/cpu.py): `src/aquacrop_grid/engine/cpu.py`
- [GPU backend](https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/engine/gpu.py): `src/aquacrop_grid/engine/gpu.py`
- [Kernel compiler](https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/kernels/loader.py): `src/aquacrop_grid/kernels/loader.py`
- [Daily AquaCrop step](https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/kernels/impl.py): `src/aquacrop_grid/kernels/impl.py`
- [Kernel array layout](https://github.com/abson-dev/aquacrop-grid/blob/main/src/aquacrop_grid/kernels/constants.py): `src/aquacrop_grid/kernels/constants.py`

### Results

- **Results zarr**

### Other components

- **CLI user**
- **Climate zarr**
- **Sowing zarr**
- **Soil zarr**

## Connections

- CLI user → CLI commands: invokes (evidence: `README.md`)
- CLI commands → Tiled pipeline: runs simulation (evidence: `src/aquacrop_grid/cli.py`)
- CLI commands → Synthetic data: generates inputs (evidence: `src/aquacrop_grid/cli.py`)
- CLI commands → Throughput benchmark: measures throughput (evidence: `src/aquacrop_grid/cli.py`)
- Synthetic data → Climate zarr: writes (evidence: `src/aquacrop_grid/io/synthetic.py`)
- Synthetic data → Sowing zarr: writes (evidence: `src/aquacrop_grid/io/synthetic.py`)
- Synthetic data → Soil zarr: writes (evidence: `src/aquacrop_grid/io/synthetic.py`)
- Climate zarr → Tiled pipeline: supplies weather (evidence: `README.md`)
- Sowing zarr → Tiled pipeline: supplies dates (evidence: `README.md`)
- Soil zarr → Tiled pipeline: supplies soil (evidence: `README.md`)
- Tiled pipeline → Input validation: opens inputs (evidence: `src/aquacrop_grid/pipeline.py`)
- Tiled pipeline → Soil raster I/O: opens soil (evidence: `src/aquacrop_grid/pipeline.py`)
- Tiled pipeline → Crop parameters: prepares parameters (evidence: `src/aquacrop_grid/pipeline.py`)
- Tiled pipeline → Soil profile builder: builds soil profiles (evidence: `src/aquacrop_grid/pipeline.py`)
- Tiled pipeline → Array runner: runs tile arrays (evidence: `README.md`)
- Tiled pipeline → Results zarr: writes results (evidence: `README.md`)
- Array runner → CPU backend: dispatches CPU (evidence: `src/aquacrop_grid/engine/run.py`)
- Array runner → GPU backend: dispatches GPU (evidence: `src/aquacrop_grid/engine/run.py`)
- CPU backend → Kernel compiler: loads kernels (evidence: `src/aquacrop_grid/engine/cpu.py`)
- GPU backend → Kernel compiler: loads kernels (evidence: `src/aquacrop_grid/engine/gpu.py`)
- Kernel compiler → Daily AquaCrop step: compiles source (evidence: `src/aquacrop_grid/kernels/loader.py`)
- Daily AquaCrop step → Kernel array layout: uses indices (evidence: `src/aquacrop_grid/kernels/impl.py`)
- CPU backend → Kernel array layout: uses output indices (evidence: `src/aquacrop_grid/engine/cpu.py`)
- GPU backend → Kernel array layout: uses output indices (evidence: `src/aquacrop_grid/engine/gpu.py`)
- Soil profile builder → Soil raster I/O: consumes soil grid (evidence: `src/aquacrop_grid/soil_grid.py`)
- Crop parameters → Kernel array layout: packs parameters (evidence: `src/aquacrop_grid/params.py`)
