cropemu 0.1.0__tar.gz

cropemu-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+build/
+dist/
+.pytest_cache/
+.coverage
+htmlcov/
+.DS_Store
+
+# local data and simulation outputs (published separately on Zenodo)
+/data/
+/runs/
+/cache/
+*.parquet

cropemu-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fabrício Correia de Oliveira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cropemu-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: cropemu
+Version: 0.1.0
+Summary: Fast, validated emulators of process-based crop models
+Author: Fabrício Correia de Oliveira
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Python: >=3.10
+Requires-Dist: numpy<2; sys_platform == 'darwin' and platform_machine == 'x86_64'
+Requires-Dist: numpy>=1.24
+Requires-Dist: onnxruntime>=1.16
+Requires-Dist: pandas>=2.0
+Provides-Extra: soil
+Requires-Dist: rasterio>=1.3; extra == 'soil'
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# cropemu
+
+Fast emulators of process-based crop models, usable anywhere on the globe without
+installing the models. An emulator is a neural network trained on ~118,000 simulated
+seasons at ~2,000 points of the soybean area of the world. It predicts a whole season
+(phenology dates, yield, biomass, water balance) in about 10 µs instead of the 0.1–1 s
+of the crop model.
+
+| Emulator | Crop model | Inputs | Outputs |
+|---|---|---|---|
+| `dssat-soybean-v1` | DSSAT 4.8 CROPGRO-Soybean (official executable) | weather, soil, sowing date, 14 cultivar coefficients, water regime, CO₂ | 41 |
+| `aquacrop-soybean-v1` | FAO AquaCrop 7.3 (official executable) | weather, soil, sowing date, 13 crop parameters, water regime, CO₂ | 44 |
+
+Both emulators ship inside the package (~1.3 MB each) and run with `onnxruntime` only.
+
+## Install
+
+```bash
+pip install cropemu            # emulators + NASA POWER weather
+pip install "cropemu[soil]"    # + SoilGrids soil profiles (rasterio)
+```
+
+On Intel Macs, add `--prefer-binary` (the newest rasterio has no wheel for them).
+
+## Quick start
+
+```python
+import cropemu
+from cropemu.weather import fetch, fill_gaps
+from cropemu.soil import soilgrids
+
+lat, lon = -23.19, -51.18                                   # Londrina, Brazil
+weather = fill_gaps(fetch(lat, lon, "2000-01-01", "2024-12-31"))   # NASA POWER, cached
+soil = soilgrids.fetch(lat, lon)                            # SoilGrids 2.0 profile, cached
+
+emu = cropemu.load("dssat-soybean-v1")
+emu.describe()                                              # outputs, units, validation error, level
+
+res = emu.predict(weather, lat=lat, elev=600, soil=soil,
+                  sowing=["2020-10-15", "2021-10-15", "2022-10-15"],
+                  cultivar=emu.cultivar(mg=6.5))
+res.outputs[["MDAT_dap", "HWAM", "ETCM"]]                    # maturity (days after sowing), yield (kg/ha), ET (mm)
+res.recommended("caution")                                  # only outputs that passed validation
+res.out_of_domain, res.rare_inputs                          # inputs outside the training data
+```
+
+Climate scenarios as in training: `emu.predict(..., dt=2.0, rain_factor=0.9, co2=550)`.
+Irrigated (no water stress): `irrigated=True`.
+
+## What every prediction tells you
+
+- **Acceptance level of each output**, from a 5-fold cross-validation by 5° spatial blocks
+  (the emulator never saw the region it is tested on):
+  - *recommended*: dates with RMSE ≤ 5 days; other outputs with RMSE < 0.25 of the
+    within-site standard deviation;
+  - *caution*: relative error < 0.5;
+  - *not recommended*: everything else.
+- **`out_of_domain`**: inputs outside the range of the training data (do not trust).
+- **`rare_inputs`**: inputs outside the 0.5–99.5 % range of the training data (less trust).
+
+Validation, by spatial blocks:
+
+| | Maturity date | Yield | Evapotranspiration |
+|---|---|---|---|
+| DSSAT | 3.3 d (R² 0.98) | 454 kg/ha (R² 0.94) | 32 mm (R² 0.96) |
+| AquaCrop | 4.4 d (R² 0.99) | 0.58 t/ha (R² 0.91) | 52 mm (R² 0.90) |
+
+## Inputs, as in training
+
+- **Weather:** NASA POWER daily data, gaps filled. The emulator summarises it in windows from
+  30 days before to 130 days after sowing.
+- **Soil:** SoilGrids 2.0 (1 km, 3 × 3 km median, 6 layers to 2 m). Water retention:
+  Reichert et al. (2009) with field capacity at 10 kPa up to 30° latitude, Saxton & Rawls
+  (2006) from 40°, and a linear blend in between.
+- **Cultivar:**
+  - `emu.cultivar(mg=...)` gives the DSSAT default coefficients of a maturity group.
+  - For AquaCrop it gives the middle of the training range of every crop parameter. The cycle
+    length comes from the local climate: `emu.cultivar(weather=..., sowing=..., cycle_days=...)`.
+  - Any value can be overridden: `emu.cultivar(mg=6, LFMAX=1.1)`.
+- **Fixed in training:** 30 plants/m², 50 cm rows, no nitrogen stress, 50 % of the available
+  water at the start of the simulation (30 days before sowing).
+
+## Limitations
+
+- An emulator reproduces its crop model, not the field: model errors are inherited.
+- Soybean only (maize planned).
+- Pre-alpha: the output names follow the crop models and may change.
+
+## License
+
+MIT. Data sources: NASA POWER, SoilGrids 2.0 (CC-BY 4.0), GGCMI Phase 3 crop calendar.

cropemu-0.1.0/README.md

@@ -0,0 +1,91 @@
+# cropemu
+
+Fast emulators of process-based crop models, usable anywhere on the globe without
+installing the models. An emulator is a neural network trained on ~118,000 simulated
+seasons at ~2,000 points of the soybean area of the world. It predicts a whole season
+(phenology dates, yield, biomass, water balance) in about 10 µs instead of the 0.1–1 s
+of the crop model.
+
+| Emulator | Crop model | Inputs | Outputs |
+|---|---|---|---|
+| `dssat-soybean-v1` | DSSAT 4.8 CROPGRO-Soybean (official executable) | weather, soil, sowing date, 14 cultivar coefficients, water regime, CO₂ | 41 |
+| `aquacrop-soybean-v1` | FAO AquaCrop 7.3 (official executable) | weather, soil, sowing date, 13 crop parameters, water regime, CO₂ | 44 |
+
+Both emulators ship inside the package (~1.3 MB each) and run with `onnxruntime` only.
+
+## Install
+
+```bash
+pip install cropemu            # emulators + NASA POWER weather
+pip install "cropemu[soil]"    # + SoilGrids soil profiles (rasterio)
+```
+
+On Intel Macs, add `--prefer-binary` (the newest rasterio has no wheel for them).
+
+## Quick start
+
+```python
+import cropemu
+from cropemu.weather import fetch, fill_gaps
+from cropemu.soil import soilgrids
+
+lat, lon = -23.19, -51.18                                   # Londrina, Brazil
+weather = fill_gaps(fetch(lat, lon, "2000-01-01", "2024-12-31"))   # NASA POWER, cached
+soil = soilgrids.fetch(lat, lon)                            # SoilGrids 2.0 profile, cached
+
+emu = cropemu.load("dssat-soybean-v1")
+emu.describe()                                              # outputs, units, validation error, level
+
+res = emu.predict(weather, lat=lat, elev=600, soil=soil,
+                  sowing=["2020-10-15", "2021-10-15", "2022-10-15"],
+                  cultivar=emu.cultivar(mg=6.5))
+res.outputs[["MDAT_dap", "HWAM", "ETCM"]]                    # maturity (days after sowing), yield (kg/ha), ET (mm)
+res.recommended("caution")                                  # only outputs that passed validation
+res.out_of_domain, res.rare_inputs                          # inputs outside the training data
+```
+
+Climate scenarios as in training: `emu.predict(..., dt=2.0, rain_factor=0.9, co2=550)`.
+Irrigated (no water stress): `irrigated=True`.
+
+## What every prediction tells you
+
+- **Acceptance level of each output**, from a 5-fold cross-validation by 5° spatial blocks
+  (the emulator never saw the region it is tested on):
+  - *recommended*: dates with RMSE ≤ 5 days; other outputs with RMSE < 0.25 of the
+    within-site standard deviation;
+  - *caution*: relative error < 0.5;
+  - *not recommended*: everything else.
+- **`out_of_domain`**: inputs outside the range of the training data (do not trust).
+- **`rare_inputs`**: inputs outside the 0.5–99.5 % range of the training data (less trust).
+
+Validation, by spatial blocks:
+
+| | Maturity date | Yield | Evapotranspiration |
+|---|---|---|---|
+| DSSAT | 3.3 d (R² 0.98) | 454 kg/ha (R² 0.94) | 32 mm (R² 0.96) |
+| AquaCrop | 4.4 d (R² 0.99) | 0.58 t/ha (R² 0.91) | 52 mm (R² 0.90) |
+
+## Inputs, as in training
+
+- **Weather:** NASA POWER daily data, gaps filled. The emulator summarises it in windows from
+  30 days before to 130 days after sowing.
+- **Soil:** SoilGrids 2.0 (1 km, 3 × 3 km median, 6 layers to 2 m). Water retention:
+  Reichert et al. (2009) with field capacity at 10 kPa up to 30° latitude, Saxton & Rawls
+  (2006) from 40°, and a linear blend in between.
+- **Cultivar:**
+  - `emu.cultivar(mg=...)` gives the DSSAT default coefficients of a maturity group.
+  - For AquaCrop it gives the middle of the training range of every crop parameter. The cycle
+    length comes from the local climate: `emu.cultivar(weather=..., sowing=..., cycle_days=...)`.
+  - Any value can be overridden: `emu.cultivar(mg=6, LFMAX=1.1)`.
+- **Fixed in training:** 30 plants/m², 50 cm rows, no nitrogen stress, 50 % of the available
+  water at the start of the simulation (30 days before sowing).
+
+## Limitations
+
+- An emulator reproduces its crop model, not the field: model errors are inherited.
+- Soybean only (maize planned).
+- Pre-alpha: the output names follow the crop models and may change.
+
+## License
+
+MIT. Data sources: NASA POWER, SoilGrids 2.0 (CC-BY 4.0), GGCMI Phase 3 crop calendar.

cropemu-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cropemu"
+version = "0.1.0"
+description = "Fast, validated emulators of process-based crop models"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Fabrício Correia de Oliveira" }]
+dependencies = [
+    "numpy>=1.24",
+    # the last onnxruntime wheels for Intel Macs are built against numpy 1
+    "numpy<2; sys_platform == 'darwin' and platform_machine == 'x86_64'",
+    "pandas>=2.0",
+    "onnxruntime>=1.16",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+]
+
+[project.optional-dependencies]
+soil = ["rasterio>=1.3"]
+test = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cropemu"]

cropemu-0.1.0/src/cropemu/__init__.py

@@ -0,0 +1,16 @@
+"""cropemu: fast, validated emulators of process-based crop models.
+
+>>> import cropemu
+>>> cropemu.available()
+['aquacrop-soybean-v1', 'dssat-soybean-v1']
+>>> emu = cropemu.load("dssat-soybean-v1")
+>>> emu.describe()                       # outputs, units, acceptance levels
+
+Weather (NASA POWER) and soil (SoilGrids) helpers are in ``cropemu.weather`` and ``cropemu.soil``.
+"""
+
+from .emulator import Emulator, Prediction, available, load, season_gdd
+
+__all__ = ["Emulator", "Prediction", "available", "load", "season_gdd"]
+
+__version__ = "0.1.0"

cropemu-0.1.0/src/cropemu/data/__init__.py

@@ -0,0 +1 @@
+"""Data files shipped with cropemu."""