B4_Crop Plant Date Design Document
The Design Document page provides a description of the algorithms, implementation and planned testing including unit, verification, validation and performance testing. Please read Step 1.3 Performance Expectations that explains feature documentation requirements from the performance group point of view.
Design Document
In the table below 4.Equ means Equations and Algorithms, 5.Ver means Verification, 6.Perf - Performance, 7. Val - Validation, 
- competed, 
- in progress, 
- not done
Overview table for the owner and an approver of this feature
1.Description | Integrate Crop Planting Date |
| 2.Owner | Beth Drewniak |
| 3.Created | |
| 4.Equ | |
| 5.Ver | |
| 6.Perf | |
| 7.Val | |
| 8.Approver | Katherine Calvin (Unlicensed) |
| 9.Approved Date |
Title: bbye/lnd/add_crop_planting_date: Climate driven crop planting date
Requirements and Design
E3SM Land Group
Date:
Summary
Crop models need an accurate method to predict plant date to allow these models to: 1) capture changes in crop management to adapt to climate change, 2) accurately model the timing of crop phenology, and 3) improve crop simulated influences on carbon, nutrient, energy, and water cycles. Plant date in ELM is determined by temperature thresholds. This has an undesired effect of restricting crops to temperate latitudes (between 30°N and 30°S) because temperature thresholds are not appropriate for use in tropical zones. This limits the area where crops are grown to a much smaller region than observed. Tropical regions typically have temperature ranges that can support crop production year-round; however, the growing season in many areas of the tropics and sub-tropics is limited by water availability. In these regions, precipitation should be considered when establishing planting date. Therefore, a new planting date scheme that takes into account temperature and precipitation seasonality is applied to determine plant date for crops. The more robust plant date in ALM meets two requirements: 1) the planting trigger functions globally, and 2) the plant date can change over time. Furthermore, because the method requires no additional inputs, adding new cropland to grid cells is a straightforward task.
Requirements
Requirement: determine seasonality of region
Date last modified:
Contributors: Beth Drewniak
Determine whether a grid cell has a temperature, precipitation, or no seasonal cycle using the coefficient of variance.
Requirement: calculate plant month based
Date last modified:
Contributors: Beth Drewniak
Determine the month of planting by calculating the main warm or wet season.
Requirement: calculate plant day
Date last modified:
Contributors: Beth Drewniak
Use temperature or rain thresholds to determine plant day.
Algorithmic Formulations
Design solution: establish climate driven plant dates
Date last modified:
Contributors: Beth Drewniak
The new planting algorithm is calculated in three parts: 1) establish the type of climate seasonality exists in a grid cell, 2) determine a plant month based on that seasonality (i.e., warm season or wet season), and 3) determine the plant day (i.e. temperature or precipitation thresholds). The type of seasonality of a region can be determined by monthly coefficients of variation (CV) of temperature and precipitation (Waha et al., 2012). The CV is calculated for each year (j) by:
where the standard deviation (σ) of temperature or precipitation and the annual mean temperature or precipitation (μ) of year j are determined by:
is the exponential weighted moving average (ewma) temperature or precipitation of month m in year j with a weighting decrease (α) of 0.05.
The ewma captures past climate in order to account for farmer experiences, but gives more importance to recent experiences and less weight to past years. Precipitation seasonality occurs when the CV of precipitation is above 0.4 (Waha et al, 2012); temperature seasonality occurs when CV of temperature is at or above 0.01. The final seasonality determination for a given region can be determined using a decision tree. In cases where a region has both temperature and precipitation seasonality, the presence of a cold season is the deciding factor for seasonality classification used to trigger planting. A cold season occurs if the average temperature of the coldest month is less than 10°C. In regions with a cold season, the grid cell is classified as having temperature seasonality; otherwise the grid cell has precipitation seasonality. The seasonality map is updated annually.
In regions with temperature seasonality, the month of planting is determined when the average monthly temperatures are above a threshold similar to the current model. The day of planting occurs when the 10-day average temperature and the 10-day minimum average temperature are above a threshold (again, similar to the current implementation). In areas with precipitation seasonality, the month of planting is determined by largest ratio of precipitation to potential evapotranspiration (PET), summed over 4-months. PET is calculated with the Penman-Monteith method (Monteith, 1965). Plant day is the first day of rain above 0.1 mm on the first month of the wet season. A minimum and maximum soil moisture threshold are also required to ensure the soil is not to dry or wet for planting conditions. Areas that do not have temperature or precipitation seasonality are assigned a plant date of January 1st.
Design and Implementation
Implementation: create new plant date subroutine
Date last modified:
Contributors: Beth Drewniak
I will add the required subroutines to perform the above calculations. This will involve a new module that can house the crop model calculations, and can act to hold more crop-related subroutines in the future. The development will have no influence on other parts of the code. It will also not require any new inputs to the model, although some parameter values may need to be updated. The git branch is bbye/lnd/add_crop_planting_date.
Planned Verification and Unit Testing
Verification and Unit Testing: Algorithm already tested by Waha et al., 2012
Date last modified:
Contributors: Beth Drewniak
The algorithm has already been verified in another land surface model by the developers (Waha et al., 2012). In this case, the only update is to the PET calculator, which now uses the Penman-Monteith method, which is considered more accurate. The current crop test should catch any problems in temperate zones, but not in tropical ones. There is no test that can be easily established for a more robust testing purposes, but should be considered for the future.
Planned Validation Testing
Validation Testing: validate against plant date records
Date last modified:
Contributors: Beth Drewniak
Plant dates will be compared against:
- Crop Calendar Dataset (Sacks et al., 2010)
- MIRCA2000 dataset (Portman et al., 2010)
Planned Performance Testing
Performance Testing: determine performance with and without crops
Date last modified:
Contributors: Beth Drewniak
This function cannot be turned off as it replaces the current plant calculator. However, the impact is limited to the crop model only as the function is called only when crops are active.