Cycles

Cycles: An Agroecosystems Simulation Model

User Reference Guide

Prepared by Charles M. White, Yuning Shi, and Armen R. Kemanian

Introduction to Using Cycles

Input Files

Simulation Control File
Weather File
Soil File
Crop Description File
Management Operations File
Re-initialization File
Multi-mode File
Calibration File

Output Files

Bug Report Guidelines

Introduction to Using Cycles

Cycles is a daily time-step agroecosystem model that simulates the biophysical processes and management practices occurring in a conceptual field that subtends a sequence of crops and operations or cropping system. Processes include fluxes in the water and energy balance and the coupled cycling of carbon and nitrogen including vegetation growth. The model can simulate a wide range of agricultural management practices such as tillage, inorganic and organic nutrient additions, annual and perennial crops, crop harvests as grain or forages, polycultures and relay cropping, grazing, and irrigation. Crop growth is represented with a generalizable framework such that a nearly limitless variety of agricultural crop species can be specified by the user.

Cycles is written in C and the executables for different operating systems are released from the Cycles GitHub repository release page. Text-based input files that specify the simulation control parameters, a soil profile description, crop descriptions, the sequence of management operations, and weather drive each user-defined simulation. An optional re-initialization file can be used to reset model variables to desired values as described in the re-initialization file. An optional calibration file can be used in calibration mode to provide an interface for calibrating hard-coded model variables. Outputs for various pools and fluxes in the agro-ecosystem are written to tab-delimited text files that can be opened by most spreadsheet programs.

To get started running the model, download the package based on your operating system from the release page under the “Assets” menu and decompress the package to a working directory of your choice. For Windows users, please use Cycles_win_XXX.zip, Mac users Cycles_macos_XXX.zip, and Linux/Unix users Cycles_debian_XXX.zip.

The input directory is where you store the various input files needed to drive each simulation. Each simulation needs a control file (*.ctrl), an operation file (*.operation), a soil profile description file (*.soil), a crop description file (*.crop), and a weather file (*.weather). A re-initialization file (*.reinit) and a calibration file (*.nudge) are optional. Each simulation you run should have a uniquely-named control file, but it is possible to share a single operation file, soil description file, crop description file, or weather file across multiple simulations.

Each of the input files is described in more detail below, but assuming that the input files are prepared and located in the input directory, Cycles is launched as follows.

Navigate to the Cycles working directory.
Once you are in the directory, type the following into the command line and hit enter:
```
./Cycles <simulation name>
```
or, in Windows:
```
Cycles_win.exe <simulation name>
```
The string <simulation name> should correspond to the file name of the simulation control file, not including the .ctrl suffix. For instance, the command used to run the simulation specified by the ContinuousCorn.ctrl file is
```
./Cycles ContinuousCorn
```
or in Windows,
```
Cycles_win.exe ContinuousCorn
```
You can also specify whether to run the model in brief mode, verbose mode, or debugging mode, by adding -b, -v or -d parameters, respectively, as in:
```
./Cycles [-bvd] <simulation name>
```
or, in Windows:
```
Cycles_win.exe [-bvd] <simulation name>
```
Brief mode has minimal screen output. Verbose mode has verbose screen output for users to understand the simulation processes. Debugging mode is the most useful in Unix operating systems, stopping the simulation when NAN or overflow errors occur.
Cycles includes a “multi-mode” feature that enables users to run batch simulations. In multi-mode, a master control file (or multi-mode file) in the input folder is required. To start batch simulation as described in the multi-mode file:
```
./Cycles -m <multi-mode file name>
```
or, in Windows:
```
Cycles_win.exe -m <multi-mode file name>
```
Note that when running a multi-mode file, the suffix should be included in the command line.
Cycles includes a spin-up feature that enables users to run the model to equilibrium. In spin-up mode, the model recycles the weather forcing and operations between the specified simulation start year and end year, until the model reaches equilibrium (i.e., the change in total soil organic carbon before and after the simulation is below 1%). The spin-up is followed by a simulation starting from equilibrium. No output file is written during the spin-up. Only the last simulation from equilibrium produces model output. The spin-up simulation also generates a <simulation name>_ss file in the input directory, which contains the soil conditions at equilibrium, and can be used to drive other simulations. To start a simulation with spin-up:
```
./Cycles -s <simulation name>
```
or, in Windows:
```
Cycles_win.exe -s <simulation name>
```
Cycles includes a grain growth model. To use the grain growth model:
```
./Cycles -g <simulation name>
```
or, in Windows:
```
Cycles_win.exe -g <simulation name>
```
Cycles includes a “baseline simulation” mode. The baseline simulation generates a re-initialization file at specified day of year (DOY) when it runs. The generated re-initialization file can be used to for other simulations, resetting model variables to the “baseline” values. To start a baseline simulation that generates re-initialization for a specified DOY:
```
./Cycles -l <DOY> <simulation name>
```
or, in Windows:
```
Cycles_win.exe -l <DOY> <simulation name>
```
The baseline simulation can also spin-up. Only the equilibrium simulation will generate re-initialization variables.
Cycles includes a “calibration” mode. In calibration mode, a calibration file named <simulation name>.nudge in the input folder is required. The calibration multipliers and parameters are used to nudge the hard-coded parameter values in Cycles. To run Cycles in calibration mode:
```
./Cycles -c <simulation name>
```
or, in Windows:
```
Cycles_win.exe -c <simulation name>
```
Cycles output file extension is defaulted to .txt, but can be customized by users using the -e command line option. For example, to change the output file extension to .dat:
```
./Cycles -e dat <simulation name>
```
or, in Windows:
```
Cycles_win.exe -e dat <simulation name>
```
The option can be useful if a simulation needs to be run multiple times without overwriting previous results. For example, running first with “-e 1.txt”, and then “-e 2.txt” will give generate *.1.txt and *.2.txt in the same directory without overwriting.

Multiple command line options can be used at the same time. For example, to run a simulation in verbose mode with spin-up and output extension .dat:

./Cycles -vse dat <simulation name>

or, in Windows:

Cycles_win.exe -vse dat <simulation name>

Outputs from the model are written to files located in a subdirectory named output. If the output subdirectory does not already exist within your working directory, the program will create it. To keep your outputs organized, the program creates a new subdirectory within the output directory with the same name as the simulation control file. In baseline mode the generated re-initialization file can be found in the output directory as reinit.txt. If you run the same simulation control file multiple times, the program will overwrite output files in the folder each time, unless the -e option is used to customize the output file extension.

Windows users: It is important to note that if any of the output files are open in a spreadsheet software when a new simulation is run, those files will not be overwritten successfully. To save an existing output file within the output subdirectory and prevent the results from being overwritten by subsequent simulation runs, you can manually change the name of the file in Windows Explorer, for instance by appending a keyword of your choice to the filename.

The remainder of the manual will describe the structure of the input files needed to run a simulation and provide documentation of the results printed to the various output files.

(Back to top)

Input Files

Simulations in Cycles are driven by a series of ASCII-text input files. However, the simulation control file (*.ctrl) is the only input file explicitly specified when executing Cycles in the command prompt terminal or command line. The names of inputs files for the crop descriptions, management operations, soil profile description, and weather records are specified within the control file. Generally speaking, the input files must be written in exactly the same format as the master template. Users can write custom annotations within input files, however. Any text following a # mark will not be read by the program. Blank lines are also not read by the program To create input files for a new simulation, it’s easiest to make a copy of existing template files, rather than retype each file from scratch.

(Back to top)

Simulation Control File (*.ctrl)

The simulation control files have a suffix of .ctrl. For each simulation, the name of the control file is submitted when invoking Cycles at the command prompt and is also used as the directory name where output files are stored following each simulation. In the control file, keyword tags are on the left and the value for each tag is separated by spaces or tabs on the right. The control file contains information about the starting and ending years of the simulation, simulation options, including the specific output files to be written, and the names of other input files. Simulation options are represented as on/off switches, where 0 stands for off and 1 stands for on. The meaning of each keyword in the control file is described below.

`SIMULATION_START_YEAR`

The year to start the simulation. All simulations start on January 1 of the given year. There must be records in the weather file starting from January 1 of this year.

`SIMULATION_END_YEAR`

The year to end the simulation. All simulations run to December 31 of the given year. There must be records in the weather file through December 31 of this year.

`ROTATION_SIZE`

The number of years in the crop rotation specified in the operation input file. The specified rotation will automatically repeat itself as many times as needed over the duration of the simulation spanning from SIMULATION_START_YEAR to SIMULATION_END_YEAR.

`CROP_FILE`

The name of the crop description file. This file must be located in a directory titled input that is within the Cycles working directory.

`OPERATION_FILE`

The name of the operation file. This file must be located in a directory titled input that is within the Cycles working directory.

`SOIL_FILE`

The name of the soil profile description file. This file must be located in a directory titled input that is within the Cycles working directory.

`WEATHER_FILE`

The name of the weather file. This file must be located in a directory titled input that is within the Cycles working directory.

`REINIT_FILE`

The name of the reinitialization file. This file must be located in a directory titled input that is within the Cycles working directory. Note that it cannot be left as blank, even if reinitialization is not needed. Use N/A if reinitialization is not needed.

`CO2_LEVEL`

Atmospheric CO₂ concentration (ppm). Set to -999 to use annual CO₂ concentrations in the co2.txt file.

`USE_REINITIALIZATION`

Set to 1 if reinitialization of carbon, nitrogen or water variables are desired on a specific day of simulation year. A re-initialization file is required in this case. Set to 0 if re-initialization is not needed.

`ADJUSTED_YIELDS`

This keyword is currently not activated. Enter 0.

`HOURLY_INFILTRATION`

Controls whether water infiltration and redistribution between soil layers is calculated using the daily cascade method (set value to 0) or a finite difference numerical integration at an hourly time-step (set value to 1). The cascade method is the most computationally efficient, but does not allow for water contents greater than field capacity or soil wetting from the bottom up. Cascade method can miss denitrification badly, but does a good job with the water balance.

`AUTOMATIC_NITROGEN`

Set to 0 for crops to be grown based on N available from N fertilizer additions and N cycling processes. Set to 1 for all crops in the simulation to be grown without nitrogen limitations. For this selection to work, the autoN flag in the planting operation of a given crop (operation file) needs to be set to 1. This allows running crops with and without N limitation in the same simulation.

`AUTOMATIC_PHOSPHORUS`

Crops grow with no phosphorus limitations. (Note: phosphorus cycling is currently not represented in the model, so this switch does not activate anything.)

`AUTOMATIC_SULFUR`

Crops grow with no sulfur limitations. (Note: sulfur cycling is currently not represented in the model, so this switch does not activate anything.)

`DAILY_WEATHER_OUT`

Set to 1 to write an output file named weather.txt with the average temperature, reference evapotranspiration, and precipitation for each day of the simulation.

`DAILY_CROP_OUT`

Set to 1 to write an output file named for each crop used in the rotation (e.g., Maize.txt) with daily values for growing degree day accumulation, crop biomass production, biomass N content, crop N stress and water stress, and potential transpiration.

`DAILY_RESIDUE_OUT`

Set to 1 to write an output file named residue.txt with daily values associated with the residue pools, including radiation interception by surface residues, surface residue moisture content, shoot and root residue biomass and N content in the entire soil profile, and manure C and N content at the surface and in the soil profile.

`DAILY_WATER_OUT`

Set to 1 to write an output file named water.txt with daily values for the water budget, including inputs from irrigation and rainfall, and outputs of drainage, runoff, evaporation, transpiration, and sublimation.

`DAILY_NITROGEN_OUT`

Set to 1 to write an output file named N.txt with daily values for pools and fluxes in the N cycle, including soil profile stocks of organic N, nitrate N, and ammonium N, and rates of N mineralization and immobilization, nitrification, gaseous N losses, and N leaching losses.

`DAILY_SOIL_CARBON_OUT`

Set to 1 to write an output file named soilC.txt with daily values for pools and fluxes in the C cycle, including soil profile stocks of organic C, the C from decomposed organic matter that becomes humified in microbial and stabilized C pools, and C respired from decomposed residues or soil organic matter.

`DAILY_SOIL_LYR_CN_OUT`

Set to 1 to write an output file named soilLayersCN.txt with daily values for C and N pool sizes by soil layer. Included are nitrate and ammonium concentrations, the composite environmental factor regulating decomposition rates, residue C and C:N ratio, microbial biomass C and C:N ratio, stabilized organic C and C:N ratio, soil water content, and soil layer thickness and bulk density.

`ANNUAL_SOIL_OUT`

Set to 1 to write an output file named annualSOM.txt with annual values for soil carbon pool sizes and carbon saturation ratios by soil layer.

`ANNUAL_PROFILE_OUT`

Set to 1 to write an output file named annualSoilProfileC.txt with annual values of carbon pools by soil layer.

`ANNUAL_NFLUX_OUT`

Set to 1 to write and output file named annualN.txt with annual values of nitrogen fluxes, including fertilization, fixation, leaching, denitrification, nitrification, and volatilization.

(Back to top)

Weather File (*.weather)

The weather files typically have a suffix of .weather, but any suffix or file naming convention can be used so long as the name of the weather file listed in the control file exactly matches the name of the weather file to be used in the input directory.

Weather files contain three lines at the beginning with the keyword tags LATITUDE, ALTITUDE, and SCREENING_HEIGHT, each followed by a tab-delimited value. Altitude and screening height values should be entered in meters. Screening height is the height of the weather station instruments above the land surface. Following these three lines is a row of tab-delimited column headers in the order YEAR, DOY, PP, TX, TN, SOLAR, RHX, RHN, WIND, with daily values for each weather variable listed in rows below. YEAR and DOY are the year and numerical day of the year, respectively, for each daily weather record. PP is precipitation in mm day^-1. TX and TN are the maximum and minimum daily temperatures in degrees Celsius. SOLAR is the daily solar radiation in MJ m^-2 day^-1. RHX and RHN are the maximum and minimum relative humidity in %. WIND is the average wind speed in m s^-1.

(Back to top)

Soil File (*.soil)

Similar to the weather input file, soil files typically have a suffix of .soil, but any naming convention can be used as long as it matches the soil file name listed in the control file.

The soil file starts with three lines at the beginning with the keyword tags CURVE_NUMBER, SLOPE, and TOTAL_LAYERS, with each keyword followed by a tab-delimited value.

The CURVE_NUMBER refers to the United States Department of Agriculture Natural Resources Conservation Service Curve Number method to calculate runoff from watersheds. The curve number is used in an equation to predict the volume of water from precipitation or irrigation that is necessary to generate runoff from a field. Lower values indicate faster infiltration rates, meaning that a greater volume of precipitation is needed to generate runoff. The exact value to use in a soil input file for a given simulation depends on the soil texture and crop rotation characteristics, as described in the NRCS technical report TR-55, “Urban Hydrology for Small Watersheds”. Table 2.2 in the document suggests curve numbers to use for different hydrologic soil groups (A, B, C, or D) under different crop rotations. If the hydrologic soil group is not known for a soil, Appendix A of TR-55 provides qualitative descriptions of the different hydrologic groups and assigns a hydrologic soil group rating to different soil texture classes (i.e., loams, silt loams, sandy loams, etc.). The curve number rating will affect the water budget in a simulation, which can affect crop yields and other processes, so its value should be given due consideration, especially if you are attempting to compare simulation outputs with results from a real field experiment.

The SLOPE value is in %, or units of rise per 100 units of run. The TOTAL_LAYERS value is simply the total number of soil layers described in the profile.

Below the first three keyword tags is a row of column headers for soil properties in the order LAYER, THICK, CLAY, SAND, SOC, BD, FC, PWP, SON, NO3, NH4, BYP_H, and BYP_V. The values of each soil property are listed below in a separate row for each soil layer. The variable LAYER is simply the layer number, starting at 1 and increasing by one unit for each additional layer. THICK is the thickness of each soil layer in meters. Because of the important processes occurring in the topsoil layers, such as gas and energy exchange with the atmosphere and incorporation of crop residues, it is necessary to have the topsoil layers simulated with greater depth resolution than the subsoils. An optimal depth for the first soil layer is 0.05 m, with subsequent topsoil layers entered in increments between 0.05 m and 0.10 m depth. Below the topsoil layers, we suggest that soil layers be defined based on depth segments corresponding to changes in soil horizonation for the soil type to be simulated.

The keyword tags CLAY and SAND are the clay particle size fraction and sand particle size fraction of each soil layer in %.

SOC is the soil organic carbon concentration of each layer in %. The organic carbon concentration of each layer is used to calculate N concentration to initialize the stabilized soil C and N pools when the simulation is started, using a soil organic C:N ratio of 10:1. The microbial biomass C and N pools are also initialized as 3% of the pool sizes of stabilized soil C and N.

BD is bulk density in Mg/m³, and FC and PWP are the field capacity and permanent wilting point volumetric water contents, respectively, in m³/m³. If any of these values are not known for a soil layer, you can enter -999 and the model will estimate the values using pedotransfer functions.

SON is the soil organic nitrogen mass in kg/ha for each soil layer. You can also enter -999 for SON, in which case the model starts with a fixed C:N ratio of 9.

NO3 and NH4 are the nitrate and ammonium masses in kg/ha for each soil layer (important: the values are absolute masses, not concentrations).

BYP_H and BYP_V are the fractions of horizontal and vertical bypass flows in each soil layer.

(Back to top)

Crop Description File (*.crop)

The crop description file defines physiological and management parameters that control the growth and harvest of crops used in the simulation. Each crop used in the simulation must have an entry in the crop description file. Each crop entry begins with the keyword tag NAME and is followed by the keywords listed in exactly the order below.

`NAME`

The name of the crop. This entry is used as the reference for crop management practices listed in the operation file, such as planting and harvesting.

`THERMAL_TIME_TO_EMERGENCE`

The thermal time accumulates between when a crop is planted and when it emerges from the soil and begins intercepting radiation, transpiring, accruing biomass, etc.

`FLOWERING_TT`

The thermal time to flowering, in growing degree C days, calculated using the base, optimum, and maximum temperatures for development listed in BASE_TEMPERATURE_FOR_DEVELOPMENT, OPTIMUM_TEMPERATURE_FOR_DEVELOPEMENT, and MAX_TEMPERATURE_FOR_DEVELOPMENT.

`MATURITY_TT`

The thermal time to maturity in growing degree C days.

`BASE_TEMPERATURE_FOR_DEVELOPMENT`

The base temperature (degree C) for phenological development and accumulation of thermal time. Air temperatures below this value will not add to cumulative thermal time. Air temperatures above this value and below OPTIMUM_TEMPERATURE_FOR_DEVELOPMENT will accumulate thermal time according to air temperature – BASE_TEMPERATURE_FOR_DEVELOPMENT.

`OPTIMUM_TEMPERATURE_FOR_DEVELOPMENT`

When air temperatures are above this value (degree C) and below MAX_TEMPERATURE_FOR_DEVELOPMENT, the accumulation of thermal time is calculated as (MAX_TEMPERATURE_FOR_DEVELOPMENT – air temperature) / (MAX_TEMPERATURE_FOR_DEVELOPMENT - OPTIMUM_TEMPERATURE_FOR_DEVELOPMENT) * (OPTIMUM_TEMPERATURE_FOR_DEVELOPMENT – BASE_TEMPERATURE_FOR_DEVELOPMENT)

`MAX_TEMPERATURE_FOR_DEVELOPMENT`

Air temperatures above this value (degree C) will not add to cumulative thermal time.

`INITIAL_PARTITIONING_TO_SHOOT`

The fraction of growth partitioned to aboveground biomass (as opposed to roots) at the beginning of crop phenological development (seedling emergence). Values can range from 0 to 1. Perennials have lower values than annuals.

`FINAL_PARTITIONING_TO_SHOOT`

The fraction of growth partitioned to aboveground biomass (as opposed to roots) at the end of crop phenological development (physiological maturity). Values can range from 0 to 1. Perennials have lower values than annuals.

`MAXIMUM_HARVEST_INDEX`

The maximum harvest index possible (H_x), used in the calculation of actual harvest index described below. It is an asymptotic value that can be much higher than the actual maximum HI observed (e.g., 0.8 for corn). Use default values if needed.

`MINIMUM_HARVEST_INDEX`

The minimum harvest index possible (H_n), used in the calculation of actual harvest index described below. It has some semblance to the fraction of water soluble carbohydrates at flowering or in the first week after flowering in grain crops. Values range from 0 to 0.3.

`HARVEST_INDEX_SLOPE_MULTIPLIER`

A slope multiplier (m) between 0.01 and 1 used in the calculation of harvest index. The harvest index is calculated based on the proportion of aboveground crop biomass growth occurring post-anthesis relative to total aboveground growth over the entire duration of crop development (f_G) as follows:

HI = Hx - (Hx - Hn) * exp(-Hk * fG),

where Hk = m * (1 - Hn) / (Hx - Hn).

`N_MAX_CONCENTRATION_GRAIN`

The maximum allowable grain N concentration (%), used in nitrogen harvest index calculation.

`N_MIN_CONCENTRATION_GRAIN`

The minimum allowable grain N concentration (%), used in nitrogen harvest index calculation.

`N_MAX_CONCENTRATION_STRAW`

The maximum allowable straw N concentration at harvest (%), used in nitrogen harvest index calculation.

`N_MIN_CONCENTRATION_STRAW`

The minimum allowable straw N concentration at harvest (%), used in nitrogen harvest index calculation.

`N_PARTITIONING_FACTOR`

An empirical constant in N partitioning (-) used in nitrogen harvest index calculation.

`MAXIMUM_ROOTING_DEPTH`

The maximum depth to which crop roots can grow in meters.

`RADIATION_USE_EFFICIENCY`

The radiation use efficiency of the crop in g/MJ. Units in MJ of solar radiation (not PAR).

`TRANSPIRATION_USE_EFFICIENCY`

The transpiration use efficiency of the crop in g/kg of water when the VPD = 1 kPa.

`MIN_TEMPERATURE_FOR_TRANSPIRATION`

The air temperature (daily average, degree C) below which transpiration by the plant virtually ceases (transpiration is 1% of potential transpiration). This value can constrain crop growth at low temperatures because crop growth is calculated as the minimum of Transpiration Use Efficiency * Transpiration or Radiation Use Efficiency * Radiation Interception. Therefore, if transpiration does not occur, plant biomass accrual does not occur.

`THRESHOLD_TEMPERATURE_FOR_TRANSPIRATION`

The threshold temperature (daily average, degree C) below which potential transpiration is multiplied by a linear temperature reduction factor, where the reduction factor is calculated as: (daily average temperature – MIN_TEMPERATURE_FOR_TRANSPIRATION)/ (THRESHOLD_TEMPERATURE_FOR_TRANSPIRATION – MIN_TEMPERATURE_FOR_TRANSPIRATION).

`KC`

The crop transpiration coefficient, used to convert reference evapotranspiration based on environmental conditions into crop transpiration.

`LWP_STRESS_ONSET`

The leaf water potential (J/kg) threshold for the onset of stress, below which stomatal closure begins, reducing transpiration rates.

`LWP_WILTING_POINT`

The leaf water potential (J/kg) at wilting point, where transpiration stops.

`TRANSPIRATION_MAX`

The maximum crop transpiration rate in mm/day.

`MIN_TEMPERATURE_FOR_COLD_DAMAGE`

The minimum temperature (degree C) used in the calculation of the cold damage factor described below. If the daily minimum temperature is below this value, the cold damage factor is set to 0.99.

`THRESHOLD_TEMPERATURE_FOR_COLD_DAMAGE`

The threshold temperature (degree C) used in the calculation of the cold damage factor. If the daily minimum temperature falls below this threshold value, a cold damage factor is calculated as:

1 – (daily minimum temperature – MIN_TEMPERATURE_FOR_COLD_DAMAGE) / (THRESHOLD_TEMPERATURE_FOR_COLD_DAMAGE - MIN_TEMPERATURE_FOR_COLD_DAMAGE)

The cold damage factor reduces the aboveground crop biomass (moving it to the surface residue pools), reduces radiation interception by the canopy, and delays phenology development. Aboveground biomass and radiation interception is reduced by a factor calculated as 1 – cold damage factor^3. As an example, a daily minimum temperature below the MIN_TEMPERATURE_FOR_COLD_DAMAGE will cause the existing aboveground biomass and radiation interception to be multiplied by 0.03 (1-0.99³), with the 97% of existing biomass that was killed added to the residue pools. So for a crop with an aboveground biomass of 1000 kg/ha, a day in the simulation with a minimum temperature below the MIN_TEMPERATURE_FOR_COLD_DAMAGE will reduce the aboveground biomass to 30 kg/ha and add 970 kg/ha of biomass to the residue pools.

Important Note: The THRESHOLD_TEMPERATURE_FOR_COLD_DAMAGE value can also trigger a grain harvest of a growing crop. If the crop is an annual species and the cumulative thermal time of crop development is greater than the FLOWERING_TT value, the crop will be automatically harvested as a grain crop.

`N_MAX_CONCENTRATION`

The maximum N concentration in crop tissue (g/g), a feature that regulates the N requirements for growth through the N dilution curve.

`N_DILUTION_SLOPE`

A parameter that controls the slope of the N dilution curve, which regulates crop N requirements as biomass accrues.

`ANNUAL`

Whether the crop is annual (value = 1) or perennial (value = 0).

`LEGUME`

Whether the crop is a legume (value = 1) or a non-legume (value = 0).

`C3`

Whether the crop has a C3 photosynthetic pathway (value = 1) or a C4 pathway (value = 0).

`MAXIMUM_SOIL_COVERAGE`

The maximum crop cover in % is a proxy for light interception potential given by row spacing and other features. This value can be set to less than 100% if the crop canopy does not have the potential to provide full cover, or if the crop is planted with a row spacing such that there will be bare ground present between crop rows (e.g., horticultural production or dry areas).

`STANDING_RESIDUE_AT_HARVEST`

The percent of aboveground crop residues remaining in the field that are left in the standing position (i.e., in minimal contact with the soil surface and therefore decomposing at a slower rate). The reminder of the reside will lay flat on the ground.

`RESIDUE_REMOVED`

For crops harvested as grain, the percent of non-grain crop biomass that is removed with the harvested grain. For crops harvested as forages or grazed through the clipping controls, the percent of harvestable aboveground plant biomass that is removed by the harvest. For clipping events, this value also controls the fraction of root biomass that is killed at each clipping event and the extent to which the thermal time of crop development is set back at each clipping event.

Interactions: The harvestable aboveground plant biomass is the biomass quantity above the CLIPPING_BIOMASS_THRESHOLD_LOWER value.

`CLIPPING_BIOMASS_THRESHOLD_LOWER`

The aboveground plant biomass threshold (in Mg/ha), which remains un-harvestable during clipping events. This value represents the mass of living plant biomass that would remain in the field after a clipping event with a RESIDUE_REMOVED value of 100.

`CLIPPING_BIOMASS_THRESHOLD_UPPER`

The aboveground plant biomass threshold (in Mg/ha) that will trigger a clipping event or forage harvest.

Interactions: Clipping will only be allowed if the clipping date window for the crop, which is defined in the operation file, is open. The HARVEST_TIMING value also controls clipping events, and clipping will occur when either the biomass threshold or the HARVEST TIMING threshold is reached, whichever occurs first. The destination of clippings, either returned to the soil surface, harvested, or grazed is controlled by the CLIPPING_BIOMASS_DESTINY option. The percent of aboveground biomass that is clipped is controlled by the RESIDUE_REMOVED value.

`CLIPPING_BIOMASS_DESTINY`

This value controls the destiny of biomass cut by clipping events, with options of REMOVE, RETURN, or GRAZING. REMOVE will treat the clipped biomass as a harvested crop. RETURN will treat the clipped biomass as a residue returned to the soil surface, with the allocation to standing versus flattened residue pools controlled by the STANDING_RESIDUE_AT_HARVEST value. GRAZING will treat the clipped biomass as being consumed by livestock, with 50% of the carbon in clipped biomass returned to the soil surface manure C pool and 50% of the carbon respired by livestock as CO₂, and with 50% of the nitrogen in clipped biomass returned to the soil surface in the manure N pool and 50% of the nitrogen returned as urine to the NH₄⁺ pool of the first soil layer.

`HARVEST_TIMING`

The percent of thermal time to crop maturity that will trigger a clipping event or grain harvest. As an example, if HARVEST_TIMING is set to 90, and the MATURITY_TT is 1000, the crop will be clipped when the cumulative thermal time of crop development reaches 900 growing degree days. If the harvest timing is less than 100, the crop will be clipped as a forage and will continue to regrow. If the harvest timing is greater than 100, the crop will have reached physiological maturity and will be harvested as a grain crop and killed after harvested. A value of -999 can be entered to trigger a default value of 101, which will result in the crop being harvested for grain on the first day after it reaches physiological maturity.

Interactions: The CLIPPING_BIOMASS_THRESHOLD_UPPER value also controls if and when a crop will be clipped. If the HARVEST_TIMING value is greater than 100, indicating a desire to harvest the crop for grain, but the CLIPPING_BIOMASS_THRESHOLD_UPPER value is set within a range of biomass production levels that will be achieved during growth of the crop, the crop will get clipped as a forage. Therefore, when programming a crop to be grown as a grain crop, the CLIPPING_BIOMASS_THRESHOLD_UPPER value should be set to a very high value, such as 999, so that clipping will not be triggered before physiological maturity is reached.

`KILL_AFTER_HARVEST`

Whether to kill the crop after automatic grain or forage harvests. Note that crops will not be killed after scheduled harvests in the operation files. To kill the crops after scheduled harvests, KILL_CROP tillage operations need to be scheduled.

(Back to top)

Management Operations File (*.operation)

The management operation file sets the daily management operations to be used in a simulated crop rotation. Each operation is indicated by one of five possible headers, PLANTING, TILLAGE, FIXED_FERTILIZATION, FIXED_IRRIGATION, or AUTO_IRRIGATION. For each operation type, subsequent keywords tags followed by a tab-delimited value are required in a specific order. Each operation includes an entry for the YEAR, and DOY (numerical day of the year) in which the operation is to be performed. YEAR refers to a generic year in the rotation cycle, starting with year 1, rather than an actual calendar year. The rotation will start in the calendar year specified in the control file under SIMULATION_START_YEAR and will repeat itself as many times as possible until the simulation reaches the end of the calendar year specified under SIMULATION_END_YEAR in the control file. In this manner, the rotation in an operation file can be started in any calendar year specified by the control file and can run for as many rotation cycles as desired, given that a weather file with a sufficient time span is available.

It is important that entries in the operation file are listed in chronological order by YEAR and DOY. If operations are listed out of order, they will be read into the management array in the wrong order and may not be executed with the proper timing in the simulation.

`PLANTING`

The PLANTING operation plants a crop. The following keyword tags are needed after the PLANTING header.

`YEAR`

The year in the rotation in which the planting operation is to be performed.

`DOY`

The numerical day of the year (0 to 365 or 366) on which the planting operation is to be performed. If conditional planting is activated (i.e., MIN_SMC and MIN_SOIL_TEMP are not -999), this is the beginning of the planting window.

`END_DOY`

The last numerical day of the year (0 to 365 or 366) on which the planting operation is to be performed when conditional planting is activated. Set the value to -999 to disable conditional planting.

`MAX_SMC`

Maximum soil moisture (fraction between PWP and FC) allowed to perform planting. A value of 0 represents PWP and a value of 1 represents FC. Set the value to -999 to disable maximum soil moisture control on conditional planting.

`MIN_SMC`

Minimum soil moisture (fraction between PWP and FC) required to perform planting. A value of 0 represents PWP and a value of 1 represents FC. Set the value to -999 to disable minimum soil moisture control on conditional planting.

`MAX_SOIL_TEMP`

Maximum 7-day moving average soil temperature required to perform planting in degree Celsius. Set the value to -999 to disable maximum soil temperature control on conditional planting.

`MIN_SOIL_TEMP`

Minimum 7-day moving average soil temperature required to perform planting in degree Celsius. Set the value to -999 to disable minimum soil temperature control on conditional planting.

`CROP`

The name of the crop to be planted. This must match the name of one of the crops described in the crop description file (*.crop). If the automatic irrigation feature is activated below, the crop name here must match the crop name in the AUTO_IRRIGATION operation entry.

`USE_AUTO_IRR`

Whether or not the crop should be grown with automatic irrigation. Yes = 1, No = 0. If automatic irrigation is activated, there must be an associated AUTO_IRRIGATION entry in the operation file with the same crop name as is used in the CROP keyword here.

`USE_AUTO_FERT`

Whether or not the crop should be grown with automatic fertilization (growth unrestricted by nutrient limitations). Yes = 1, No = 0.

`DENSITY`

The planting density (0 to 1), where 1 is a monoculture planting rate and < 1 indicates a proportionally reduced seeding rate. This feature allows for the planting of multiple species in a plant community at different initial densities.

`CLIPPING_START`

The numerical day of the year on which the clipping time window begins. Set the value to -999 to disable automated harvesting of the corresponding crop. A value of -999, however, cannot disable scheduled harvests.

`CLIPPING_END`

The numerical day of the year on which the clipping time window ends.

`TILLAGE`

The tillage operation can cause soil disturbances of varying intensity, for instance ranging from the slight disturbance of disc openers on a no-till planter to full-scale inversion tillage. Tillage operations can also be used to harvest or kill planted crops. The following keyword tags are needed after the TILLAGE header.

`YEAR`

The year in the rotation in which the tillage operation is to be performed.

`DOY`

The numerical day of the year (0 to 365) on which the tillage operation is to be performed.

`TOOL`

A descriptive name of the tillage tool described by the operation entry. This can be any user defined string of text and does not affect the simulation, with some exceptions. The string Kill_Crop is used to kill a crop without harvesting any residues; the string Grain_Harvest is used to perform a grain harvest; the string Forage_Harvest is used to perform a forage harvest; and the string Burn_Residue is used to burn residue that is aboveground. Note that scheduled grain harvests do not kill crops, and scheduled harvests are performed even if CLIPPING_START is set to -999. When burning residue, the MIXING_EFFICIENCY parameter is used to determine the fraction burned.

To kill a crop after a harvest, a Kill_Crop tillage operation should be used.

`DEPTH`

The soil depth (in meters) to which the tillage operation will cause mixing and disturbance induced increases in microbial respiration.

`SOIL_DISTURB_RATIO`

A relative value that indicates the extent to which the tillage operation speeds up decomposition rate of the soil microbial biomass and stabilized soil C pools.

`MIXING_EFFICIENCY`

A factor used to control the extent to which soil layers and residue pools mix with each other during a tillage event (range is 0 to 1). The MIXING_EFFICIENCY value specifies the mass fraction of the soil mineral and organic pools in each soil layer within the depth range of the operation that will be mixed together and redeposited in each soil layer. Pools that are mixed include clay and sand fractions, stabilized soil C and N, microbial biomass C and N, crop residue biomass and N, manure C and N, nitrate and ammonium, water content, and surface residues. The mixing efficiency will also flatten a fraction of the standing crop residue equal to the square root of the mixing efficiency.

When using the Burn_Residue option, the MIXING_EFFICIENCY value specifies the fraction of aboveground residue that is burned.

`CROP_NAME`

If the TILLAGE operation is being used to harvest or kill a crop, this tag indicates the crop name to be harvested or killed. To kill all the crops in a planted community, use All or N/A. To harvest a crop, use the crop name exactly as written in the PLANTING operation and crop description file.

`FRAC_THERMAL_TIME`

This keyword is not activated in the current version of Cycles, so leave the value as 0. In future versions, this keyword will be used to program tillage events at specific times relative to crop phenological development.

`KILL_EFFICIENCY`

This keyword is not activated in the current version of Cycles, so leave the value as 0. In future versions, this keyword will be used to generate an incomplete kill of a crop in order to simulate the effect of competition from a crop previous crop that was not completely killed.

`FIXED_FERTILIZATION`

The fixed fertilization operation is used to apply organic and inorganic soil fertility inputs in a simulation. The following keyword tags are needed after the FIXED_FERTILIZATION header.

`YEAR`

The year in the rotation in which the fixed fertilization operation is to be performed.

`DOY`

The numerical day of the year (0 to 365) on which the tillage operation is to be performed.

`SOURCE`

A descriptive name of the fertility input described by the entry. This can be any user defined string of text and does not affect the simulation.

`MASS`

The total mass of the input in kg/ha.

`FORM`

This keyword is not currently activated. Enter any string.

`METHOD`

This keyword is not currently activated. Enter any string.

`DEPTH`

The soil depth (in meters) to which the fertilizer input is added. To specify surface applied fertilizer applications, use a value of 0. Organic components of surface applied fertilizer inputs will be added to the surface manure C and N pools, while inorganic components of the surface applied inputs will be added to the nitrate or ammonium pools of the first soil layer.