Introduction¶

This key module simulates all the possible crop cycles to find the best crop cycle that produces maximum yield for a particular grid. During the simulation process for each grid, 365 crop cycle simulations are performed. Each simulation corresponds to cycles that start from each day of the year (starting from Julian date 0 to Julian date 365). Similarly, this process is performed by the program for each grid in the study area.

The attainable yields under irrigated and rain-fed conditions, during each crop cycle, are calculated with the help of several deterministic and empirical models as follows. ? Total biomass (de Wit, 1965): This model calculates total biomass produced by photosynthesis activities of plants under radiation condition of each grid. For more detailed calculations, refer to Chapter 4 of the GAEZ v4 Model Documentation (Fischer et al., 2021).

Crop yield from total biomass: Crop yield is obtained as a portion of useful harvest from the total biomass. This portion is defined by an index call Harvest Index (HI). Harvest index is defined as the amount of useful harvest divided by the total above ground biomass. For more detailed calculations, refer to Chapter 4 of the GAEZ v4 Model Documentation (Fischer et al., 2021).
Effects of water limitation on the crop yield: This component is carried out for the rain-fed yield calculation only. In the case of irrigated conditions, this component is abandoned, as we are assuming that the water is not a limiting factor for crop growth. To address the water limitation on the crop yield, two major models are considered:
- Reference Evapotranspiration - the Penman-Monteith equation (Doorenbos and Pruitt, 1977). A description of the implementation of the Penmann-Monteith equations is provided in Appendix 3-1 of Fischer et al. (2021);
- Water balance calculation, together with applying the yield reduction factors based on water limitation (Smith, 1992).
- Effects of temperature during crop cycle and screening of crop cycles based on temperature requirements (termed Thermal Screening).

Figure: Overview of Module II: Crop Simulation Alt text

Figure: Overview of Crop Simulation Routine Alt text

Mandatory Settings¶

Initialization of M2 Object Class Creation¶

Similar to Module 1, we have to import and initiate the class for the crop simulation module named as 'CropSimulation'. The way to import the object class is as below:

M2 Object Class Creation
from pyaez import CropSimulation 
aez = CropSimulation.CropSimulation()

Setting up Geographical and Terrain Data¶

After initial object class creation, the next step is to import the geographic extent and elevation information of the area of interest into the object class by using the following setting:

Setting up latitudes and elevation
# Load geographical location and elevation data into object class
clim_reg.setLocationTerrainData(lat_min, _lat_max, elevation)

Input

Arguments	Description	Unit	Data Format
lat_min	minimum latitude extent	Decimal Degrees	float
lat_max	maximum latitude extent	Decimal Degrees	float
elevation	Elevation	meters	2D NumPy Array

Output

Arguments	Description	Unit	Data Format
None	-	-	-

Uploading the Climatic Data and Soil Water Information¶

You will need to upload all the climatic variables and soil water information necessary for the AEZ crop simulation. Depending on the daily/monthly time dimension, users need to run either function for daily or monthly climate data. Note that AEZ crop simulation assess crop productivity using daily value; which in monthly data input scenario, the monthly values will be interpolated into daily values by the system. For daily input case, the interpolation is not necessary.

Daily ClimateMonthly Climate

# For daily input
aez.setDailyClimateAndWaterData(min_temp, max_temp, precipitation, short_rad, wind_speed, rel_humidity, Sa, D)

# For monthly input
aez.setMonthlyClimateAndWaterData(min_temp, max_temp, precipitation, short_rad, wind_speed, rel_humidity, Sa, D)

Input

Arguments	Description	Unit	Data Format	Time
min_temp	Minimum temperature	°C	3D-NumPy Array	Daily (365, 366)/Monthly (12)
max_temp	Maximum temperature	°C	3D-NumPy Array	Daily (365, 366)/Monthly (12)
precipitation	Total precipitation	mmday^-1	3D-NumPy Array	Daily (365, 366)/Monthly (12)
short_rad	Shortwave radiation	Wm^-2	3D-NumPy Array	Daily (365, 366)/Monthly (12)
wind_speed	Wind speed measured at 2-meter height	ms^-1	3D-NumPy Array	Daily (365, 366)/Monthly (12)
rel_humidity	Relative humidity	Decimal (0-1)	3D-NumPy Array	Daily (365, 366)/Monthly (12)
Sa	Soil Water Holding Capacity	mm/m	Int/float/2D-NumPy Array	None
D	Rooting Depth	m	Int/float	None

Output

Arguments	Description	Unit	Data Format	Time
None	-	-	-	-

Importing the Crop Parameters¶

Crop parameters are necessary componenets of AEZ crop simulation. These scientific parameterization will be incorporated into the system by means of excel data sheet input. The crop parameters are defined in AEZ methodology that comprises:

Crop-specific phenological characteristics
Crop-specific water requirement factors
Crop-specific thermal characteristics
Land utilization type characteristics

For the excel sheet setting, see here.

The following functionality will be used to upload all these parameters prepared in excel sheet into M2 object class as follows:

Crop Parameter Setting
# Crop parameter excel sheet setting
aez.readCropandCropCycleParameters(file_path, crop_name)

Input

Arguments	Description	Unit	Data Format
file_path	The full file path of the crop parameter excel sheet	-	String
crop_name	The crop name specified to identify for crop simulation. Corresponding to Crop_name column. Make sure the crop name provided in the excel sheet and the function setting the same.	-	String

Input

Arguments	Description	Unit	Data Format
None	-	-	-

Additional Information

If users are simulating the hibernation crops (winter wheat, winter barley, winter rye, winter rape), the crop_name setting in the excel sheet must provide the name either one from this provided list ['winter_wheat', 'winter_barley', 'winter_rye', 'winter_rape'] as python is case-sensitive, and the routine for hibernating crops requires to provide the name the exact name provided in the list.

Importing LGP and LGPT¶

This sections corresponds to the minimum cycle length checking routine. For each individual pixel, the algorithm checks whether the location has sufficient growing days to support the minimally required cycle length to sustain plant growth. The logic is done separately for rainfed and irrigated conditions, also for perennials and non-perennials. If the minimum cycle length requirement is not satisfactory, the yield simulation will not proceed and skip to next pixel.

For the annuals, LGP_t5 is used to compared with the minimum cycle length for irrigated condition, while LGP is used for rainfed condition.

For perennials, an extensive flow of checking is implemented and cycle will be adjusted based on the concept of effective crop cycle length implemented by perennial crop adjustments. After the adjustment the effective cycle length is compared with the minimum cycle length. If the condition is met, the next yield estimation will continue; otherwise, the cycle will be skipped.

Perennial crop adjustment

If a perennail crop is introduced (based on perennial flag being positive), PyAEZ will perform LAI and HI adjustment based on effective growing period. The perennial crop adjustment is uniquely activated to perennial crops by the following principles.

Crop Cycle Length Adjustment with Temperature Growing Period (LGP_t) and LGP
- Irrigated Condition
Perennials for irrigated crops will compare LGP_t with the reference cycle length based on user-defined minimum temperature (described in crop parameter excel). For minimum temperature greater than 8°C, LGP_t10 is used to compare while for minimum temperature less than or equal to 8°C, LGP_t5 is applied. If selected LGP_t is less than the minimum cycle length, LGP_tx will be selected as effective cycle length (CYC_eff) for the yield simulation. Otherwise, CYC_eff will be set as user-defined reference cycle length. CYC_eff cannot be more than reference cycle length.
- Rainfed Condition
For rainfed perennials, the cycle length is compared with LGP. If LGP is less than minimum cycle length, LGP will be CYC_eff. However, CYC_eff cannot be more than reference cycle length.
**Leaf Area Index (LAI) and Harvest Index (HI) Adjustment **

The calculated CYC_eff is used to adjust the LAI and HI using two threshold values \(\alpha\) and \(\beta\) parameterization. The existing function of adjusted LAI and HI are calculated in GAEZ v4 documentation as follows:

\({\displaystyle fP_{HI} = \frac{CYC_{eff}- \alpha_{HI}}{\beta_{HI}}}\)

\({\displaystyle fP_{LAI} = \frac{CYC_{eff}- \alpha_{LAI}}{\beta_{LAI}}}\)

This is a mandatory setting to activate these algorithms by importing LGP and LGP_t agro-climatic indicators as below:

Setting LGP and LGPT
# agro-climatic indicator settings
aez.ImportLGPandLGPT(lgp, lgpt5, lgpt10)

Input

Arguments	Description	Unit	Data Format
lgp	Length of Growing Period	Days	2D-NumPy Array
lgpt5	Temperature Growing Period (5°C threshold)	Days	2D-NumPy Array
lgpt10	Temperature Growing Period (10°C threshold)	Days	2D-NumPy Array

Output

Arguments	Description	Unit	Data Format
None	---	---	---

Optional Settings¶

Setting the Study Area Inputs¶

Users can provide the study area mask to omit unnecessary pixels calculations.

Setting Study Area
# Study Area Mask
aez.setStudyAreaMask(admin_mask, no_data_value=0)

Input

Arguments	Description	Unit	Data Format
admin_mask	Mask Layer/Region of Interest	Binary(0,1)/Categorical(1,2,...)	2D NumPy Array
no_data_value	Value of mask layer to skip calculation	Mask value from the layer. Default to 0	Integer

Output

Arguments	Description	Unit	Data Format
None	---	---	---

Thermal Screening¶

The functions in this sections apply thermal suitability asssessmet to indiviual grid-cells for the possible presence of indiviual LUTs. The crops' temperature requirements will be matched with the prevailing thermal conditions. A variety of thermal screening critera are available in PyAEZ for thermal sutability assessment as below:

Thermal Climate Screening¶

PyAEZ's screening of crop/LUT's about thermal climate results in a 'yes/no' flag for further calculation, with user-defined list of thermal climate classes considered for the specific crop as Not-suitable. The screening utilizes thermal climate output from Module I.

Setting Thermal Climate Screening
aez.setThermalClimateScreening(tclimate, no_t_climate)

Input

Arguments	Description	Data Format
tclimate	Thermal Climate	2D NumPy Array
no_t_climate	python list of unsuitable thermal climate classes	python list of integers

Output

Arguments	Description	Data Format
None	---	---

Permafrost Screening¶

This screening procedure fully refers to GAEZ v4 documentation stating that areas considered as continuous or discontinouous permafrost classes are considered not suitable (Fischer et al., 2021). In PyAEZ, permafrost screening results in 'yes/no' filter for further calculations using permafrost class output from Module I.

Setting Permafrost Screening
aez.setPermafrostScreening(permafrost_class)

Input

Arguments	Description	Data Format
permafrost_class	Permafrost Class	2D NumPy Array

Output

Arguments	Description	Data Format
None	---	---

TSUM Screening¶

The matching of the individual crop LUT heat unit requirements with the prevailing temperature sum is the purpose of temperature summation screening. TSUM is evaluated from base temperature of 0 ℃ for each individual cycle length duration. Starting from version 2.1.0, the new algorithm for TSUM screening is introduced which is implemented with different inputs.

TSUM screening works to evaluate three conditions, each deciding the TSUM suitability termed as: “Optimum”, “Sub-optimum" and "Not-suitable”. Optimum condition requires no reduction factor to the calculated yield, while the rest of two conditions calculates the TSUM related reduction factor. Each condition has upper and lower boundaries (See Figure 6); defined as threshold points for the users to provide as below:

LO : Lower boundary of optimum threshold
HO : Upper boundary of optimum threshold
LsO : Lower boundary of sub-optimum threshold
HsO : Upper boundary of sub-optimum threshold
LnS : Lower boundary of not-suitable threshold
HnS : Upper boundary of not-suitable threshold

Any TSUM values within the optimum threshold range (green line) are considered as inducive to plant growth; thus, no reduction factor will be applied. TSUM values between sub-optimum threshold has two components (illustrated as yellow and blue lines). Within yellow range (between LsO – LO or HO – HsO), reduction factor is calculated up to maximum 25%, obtained by linear interpolation between two end points of user-defined thresholds. Within brown range (between LnS – LsO or HsO – HnS), substantial amount of reduction factor up to maximum of 75% are obtained, from linear interpolation. Any TSUM lower than LnS threshold or beyond HnS threshold are considered as temperature too high or too low for plant growth, giving rise to 100% reduction to calculated yield.

Additional Information

TSUM setting is done in the excel sheet from data preparation. TSUM screening requires providing all six thresholds to activate. If one of the thresholds is missing, TSUM screening will not be activated. If users do not want to apply TSUM screening, provide nan value to all six variables.

Figure: Implementation of TSUM Screening Alt text

Crop-Specific Rule Screening¶

The previous temperature profile screening in version 2.1.0 is substituted with renamed routine called “Crop-Specific Rule”. This screening specifies conditions for crop cycle duration in terms of classes of daily mean temperature in 5℃ intervals (See Temperature profiles). For activation, users require providing the external excel sheet to provide with corresponding column names. Similar to TSUM screening, users need to provide thresholds for three conditions: “Optimal”, “Sub-Optimal” and “Not-Suitable”. The unique combination of several temperature profile classes is to be provided as expressions as unique rules for a particular crop type. In PyAEZ, notations for temperature profile classes are revised according to the newly introduced routine: vernalization calculation and hibernating crops. The description of the updated temperature profiles are as below:

Mean Daily Temperature (°C)	Increasing Temperature Trend	Decreasing Temperature Trend	Total
>=35	L0a/N0a	L0b/N0b	L0/N0
30 - 35	L1a/N1a	L1b/N1b	L1/N1
25 - 30	L2a/N2a	L2b/N2b	L2/N2
20 - 25	L3a/N3a	L3b/N3b	L3/N3
15 - 20	L4a/N4a	L4b/N4b	L4/N4
10 - 15	L5a/N5a	L5b/N5b	L5/N5
5 - 10	L6a/N6a	L6b/N6b	L6/N6
0 - 5	L7a/N7a	L7b/N7b	L7/N7
-5 - 0	L8a/N8a	L8b/N8b	L8/N8
< -5	L9a/N9a	L9b/N9b	L9/N9

Two notations N and L are applied based on growth cycle duration; N for year-round growth cycle (perennials for 365 days) and L for crop-specific growth cycle of annual crops. The crop-specific threshold setting is done by preparing an excel sheet with the follwing column settings described as below and provide the file path into the M2 object class. The excel sheet settings for the crop specific rule settings are as follows:

Abbreviation	Description	Data Type
Crop	Unique crop name	String
Constant	Expression of different temperature profile classes combination. (For instance, L6a + L4a). Users must use the mathematical symbols used in python (+, -, *, , /, etc.,).	String
Type	Constraint type. Must be [≥, ≤, ==]	String
Optimal	Threshold value point for optimal condition	Numerical
Sub-Optimal	Threshold value point for sub-optimal condition	Numerical
Not-Suitable	Threshold value point for not-suitable condition	Numerical

Once prepared, users must active the crop-specific rule setting as below in python environment below:

Setting Crop-Specific Rule Screening
aez.setupCropSpecificRule(file_path, crop_name)

Input

Arguments	Description	Data Format
file_path	The file path where the crop-specific rules are provided	String
crop_name	Unique ID of crop name to apply crop-specific rule	String

Output

Arguments	Description	Data Format
None	---	---

Crop Simulation¶

With all the mandatory and optional settings run, users can start off the crop simulation for the desired crop. In v2.3, the core simulations are split up into two separate functions: one for irrigated, one for rainfed conditions which handles simulation for annuals, perennials and hibernating crops.

The general schematic of the crop simulation is implemented as shown in figure below.

Figure: Procedure of Calculation of Module 2 Outputs (Irrigated and Rainfed) Alt text

A newly implemented crop simulation routine for sugarcane is introduced as below:

Figure: Procedure of Calculation of Module 2 Outputs (Irrigated and Rainfed) for Sugarcane Alt text

Irrigated Crop Simulation¶

This is a specific function to initialize irrigated crop simulation.

Starts irrigated crop simulation
aez.simulateIrrigatedCropCycle(start_doy =1, end_doy = 365, step_doy = 1, leap_year = False)

Input

Arguments	Description	Data Format
start_doy	A single value, corresponding to crop simulation starting Julian date. Default value is 1.	Numerical
end_doy	A single value, corresponding to crop simulation ending Julian date. Default value is 365.	Numerical
step_doy	A single value, corresponding to spacing (in days) between two adjacent crop simulations. Optional argument. Default value is 1.	Numerical
leap_year	True for leap year, False for non-leap year. This setting is relevant for monthly climate data as the value is used in interpolation processes.	Boolean

Output

Arguments	Description	Data Format
None	---	---

Rainfed Crop Simulation¶

This is a specific function to initialize rainfed crop simulation.

Starts rainfed crop simulation
aez.simulateRainfedCropCycle(start_doy =1, end_doy = 365, step_doy = 1, leap_year = False)

Input

Arguments	Description	Data Format
start_doy	A single value, corresponding to crop simulation starting Julian date. Default value is 1.	Numerical
end_doy	A single value, corresponding to crop simulation ending Julian date. Default value is 365.	Numerical
step_doy	A single value, corresponding to spacing (in days) between two adjacent crop simulations. Optional argument. Default value is 1.	Numerical
leap_year	True for leap year, False for non-leap year. This setting is relevant for monthly climate data as the value is used in interpolation processes.	Boolean

Output

Arguments	Description	Data Format
None	---	---

(Experimental) Irrigated Sugarcane Simulation¶

This is an experimental function to initialize irrigated sugarcane simulation using FORTRAN workflow. Note that this is in experimental stage, the outputs from this functions are not validated.

Starts irrigated sugarcane simulation
aez.simulateIrrigatedSugarcane()

Input

Arguments	Description	Data Format
None	-	-

Output

Arguments	Description	Data Format
None	-	-

(Experimental) Rainfed Sugarcane Simulation¶

This is an experimental function to initialize rainfed sugarcane simulation using FORTRAN workflow. Note that this is in experimental stage, the outputs from this functions are not validated.

Starts rainfed crop simulation
aez.simulateRainfedSugarcane()

Input

Arguments	Description	Data Format
None	-	-

Output

Arguments	Description	Data Format
None	-	-

Module II Outputs¶

These sets of functions can be called once the simulations are completed.

Estimated Irrigated Yield¶

This function returns the maximum attainable yield under provided climate conditions in irrigated condition. The unit of the output is kilogram per hectare (kg/ha).

Get Estimated Irrigated Yield
yld_irr = aez.getEstimatedYieldIrrigated()

Input

Arguments	Description	Data Format
None	-	-

Output

Arguments	Description	Data Format
yld_irr	Maximum attainable yield under provided climate conditions, under irrigated conditions.(Unit: kg/ha)	2D NumPy Array

Estimated Rainfed Yield¶

This function returns the maximum attainable yield under provided climate conditions in rainfed condition. The unit of the output is kilogram per hectare (kg/ha).

Get Estimated Rainfed Yield
yld_rain = aez.getEstimatedYieldRainfed()

Input

Arguments	Description	Data Format
None	-	-

Output

Arguments	Description	Data Format
yld_rain	Maximum attainable yield under provided climate conditions, under rainfed conditions.(Unit: kg/ha)	2D NumPy Array

Optimum Crop Calendar Irrigated¶

This functions generates the optimum crop calendar starting date under provided climate conditions, under irrigated condition. Unit is Julian Day.

Get Irrigated Crop Calendar
ccd_irr = aez.getOptimumCycleStartDateIrrigated()

Input

Arguments	Description	Data Format
None	-	-

Output

Arguments	Description	Data Format
ccd_irr	Optimum crop cycle starting date within user-defined time length for simulation(Unit: Julian Day)	2D NumPy Array

Optimum Crop Calendar Rainfed¶

This functions generates the optimum crop calendar starting date under provided climate conditions, under rainfed condition. Unit is Julian Day.

Get Rainfed Crop Calendar
ccd_rain = aez.getOptimumCycleStartDateRainfed()

Input

Arguments	Description	Data Format
None	-	-

Output

Arguments	Description	Data Format
ccd_rain	Optimum crop cycle starting date within user-defined time length for simulation(Unit: Julian Day)	2D NumPy Array

Thermal Suitability Factor (fc1) Irrigated¶

This function generates the thermal suitability factor due to thermal constraints derived from thermal screening procedures under irrigated condition. Values ranges from 0 (most limiting) to 1 (very suitable).

Get Fc1 Irrigated
fc1_irr = aez.getThermalReductionFactorIrrigated()

Input

Arguments	Description	Data Format
None	-	-

Output

Arguments	Description	Data Format
fc1_irr	Thermal suitability factor (fc1) for irrigated condition.	2D NumPy Array

Thermal Suitability Factor (fc1) Rainfed¶

This function generates the thermal suitability factor due to thermal constraints derived from thermal screening procedures under rainfed condition. Values ranges from 0 (most limiting) to 1 (very suitable).

Get Fc1 Rainfed
fc1_rain = aez.getThermalReductionFactorRainfed()

Input

Arguments	Description	Data Format
None	-	-

Output

Arguments	Description	Data Format
fc1_rain	Thermal suitability factor (fc1) for rainfed condition.	2D NumPy Array

Moisture Suitability Factor (fc2) Irrigated¶

This function generates the yield reduction factor due to water deficit under irrigated condition. Values ranges from 0 (most limiting) to 1 (very suitable).

Get Fc2 Irrigated
fc2_irr = aez.getMoistureReductionFactorIrrigated()

Input

Arguments	Description	Data Format
None	-	-

Output

Arguments	Description	Data Format
fc2_irr	Moisture suitability factor (fc2) for irrigated condition.	2D NumPy Array

Moisture Suitability Factor (fc2) Rainfed¶

This function generates the yield reduction factor due to water deficit under rainfed condition. Values ranges from 0 (most limiting) to 1 (very suitable).

Get Fc2 Rainfed
fc2_rain = aez.getMoistureReductionFactorRainfed()

Input

Arguments	Description	Data Format
None	-	-

Output

Arguments	Description	Data Format
fc2_rain	Moisture suitability factor (fc2) for rainfed condition.	2D NumPy Array

Actual Evapotranspiration (ETA) Irrigated¶

This function generates the total actual crop evapotranspiration (ETa) from precipitation (excluding irrigation) under irrigated condition. Unit is mm.

Get ETA Irrigated
eta_irr = aez.getETAIrrigated()

Input

Arguments	Description	Data Format
None	-	-

Output

Arguments	Description	Data Format
eta_irr	Actual Evapotranspiration (ETa) for irrigated condition. (Unit: mm)	2D NumPy Array

Actual Evapotranspiration (ETA) Rainfed¶

This function generates the total actual crop evapotranspiration (ETa) from precipitation (excluding irrigation) under rainfed condition. Unit is mm.

Get ETA Rainfed
eta_rain = aez.getETARainfed()

Input

Arguments	Description	Data Format
None	-	-

Output

Arguments	Description	Data Format
eta_rain	Actual Evapotranspiration (ETa) for rainfed condition. (Unit: mm)	2D NumPy Array

Water Deficit/Net Irrigation Requirement (Irrigated)¶

This function generates crop-specific net irrigation requirement under irrigated condition. Unit is mm.

Get WDE Irrigated
wde_irr = aez.getWDEIrrigated()

Input

Arguments	Description	Data Format
None	-	-

Output

Arguments	Description	Data Format
wde_irr	Net irrigation requirement for irrigated condition. (Unit: mm)	2D NumPy Array

Water Deficit/Net Irrigation Requirement (Rainfed)¶

This function generates crop-specific water deficit under rainfed condition. Unit is mm.

Get WDE Rainfed
wde_rain = aez.getWDERainfed()

Input

Arguments	Description	Data Format
None	-	-

Output

Arguments	Description	Data Format
wde_rain	Water deficit under rainfed condition. (Unit: mm)	2D NumPy Array