CMLS98B Use
Purpose | Processes
and Assumptions | Installation |
Use | Example |
References | Acknowledgements
Program Structure |
Platform Dependencies | File
Structures
RUNNING THE PROGRAM
The software is designed to be totally run from the command line. This permits it to be run on a variety of computer platforms and to be incorporated into program shells where it is just one piece of a larger system. The program is executed by typing the name of the executable code followed by a space and the name of the input data file. For example
CMLS98B caddo.in
instructs the system to run the program 'CMLS98B' and use file 'caddo.in'
as its input file. Program output goes to a file (or device) specified in
the input file. The following pages describe the structure of the input file.
Sample input and output files are then presented and discussed.
Input File: All parameters needed for simulating movement are contained in an input file. One group of parameters defines the overall simulation parameters. This is called the General Block. A second group defines the specific soil-chemical systems to be simulated. It is called the Systems Block. General Block / System Block pairs can be repeated within one input file.
The first block in the file is the general block. It defines the overall scenario of interest. Here the user specifies the following:
- the name of the output file and the desired output
- the source of infiltration data
- the source of evapotranspiration data
- the crop grown, its window of planting dates, and its crop coefficients if evapotranspiration is estimated
- irrigation methods
- dates simulations begin and end
- the number of different weather sequences to be simulated
-
the units of length for input and output depths and for irrigation
amounts
The second block or systems block defines the soil - chemical systems of interest. The following parameters for each system are included.
- rooting depth and curve number for this soil
- soil properties for each layer
- partition coefficient and half-life for each chemical
- application window, application depth, and application amount for each chemical
The user can include as many of these soil-chemical data sets as desired.
The parameters specified in the General Block are applied to each set. This
is convenient for screening many chemicals and for simulating many soils
as needed for studies over large areas and for GIS applications.
The input file consists of a series of lines beginning with a keyword and
followed by appropriate parameters. The keywords are explained in the following
tables.
Keywords in General Block(s) |
|
| Comment | The information on this line is for the user only. The contents of the line are ignored by the software. This keyword can be used in the systems block also. |
| CheckFile | This keyword is followed by a filename. If this keyword and file name are present, the system writes all input parameters to this file. This file enables the user to verify that the system read the input data correctly. |
| OutputFile | This keyword is followed by the file name which will be used for storing results of simulations. Normally this output is one line per simulation. The standard output includes few labels so the file can be easily processed by additional programs. If the word WithHeader follows the file name, labels are displayed throughout the file and the file is formatted for 80 character lines. If the word ArcView follows the file name, a comma delimited file formatted for use with ArcView is created. |
| LengthUnits | Depths specified by the user when specifying output depths, root depth, application depth, and soil layer depths can have units of meters (m) or inches (in). The first string on this line specifies this depth unit. Precipitation, infiltration, evapotranspiration, and irrigation also have units associated with them. Those units may be millimeters (mm) or inches (in). The second string on this line specifies the units associated with irrigation. (Units associated with infiltration, precipitation, and evapotranspiration are stored in those files.) |
| Infiltration | This line specifies the source of daily infiltration data for the simulation.
One of the following lines must be present in the file.
Infiltration Actual filename |
| Evapotranspiration | This line specifies the source of daily evapotranspiration (ET) data
for the simulation. ET can be read from a file if actual values are known
for the days to be simulated. ET can also be estimated from pan evaporation
data or from weather data. One of the following lines must be present
in the file. ET Actual filename This line instructs the system to read the specified file to obtain the evapotranspiration amount on each day of the simulation period. The structure of the file is described in the File Structure section. ET Historical filename FAOBlaneyCriddle a-value b-value This line instructs the system to estimate daily evapotranspiration from historical weather data stored in the specified file. The FAO Blaney-Criddle estimator should be used with values of a and b in eqn. 18 specified as a-value and b-value, respectively. The weather file must contain data for each day to be simulated. The structure of the weather files is described under File Structures. ET Historical filename SCSBlaneyCriddle k-value This line instructs the system to use Historical weather data to estimate ET by means of the SCS Blaney-Criddle method with the constant K in eqn. 17 equal to k-value. The weather file must contain data for each day to be simulated. The structure of the weather files is described under File Structures. ET Generated filename FAOBlaneyCriddle a-value b-value This line instructs the system to estimate evapotranspiration using the FAOBlaneyCriddle method after generating weather using WGEN and the stochastic parameters required by WGEN which are stored in the designated file. See File Structures for details on the parameter file. ET Generated filename SCSBlaneyCriddle k-value This line instructs the system to estimate evapotranspiration using the SCSBlaneyCriddle method after generating weather using WGEN. Stochastic parameters required by WGEN are stored in the designated file. See File Structures for details on the parameter file. ET Pan filename k-value This line instructs the system to calculate reference crop evapotranspiration using the specified k-value and daily values of pan evaporation stored in the specified file with equation 16. The format of the pan evapotranspiration data file is presented in the File Structures section. |
| Irrigation | The software includes functions for supplemental irrigation. This keyword
is used to specify the type of irrigation desired. If this line is missing,
no irrigation will be applied. Specific options are listed below. Irrigation None No irrigation is used. Irrigation Actual filename This specifies that the irrigation amounts for the simulation period are stored in the specified file. See File Structures for format details. Irrigation Periodic begin-day end-day period amount This line states that amount of irrigation water is applied every period days starting on begin-day of each year and ending on end-day. Irrigation Demand begin-day end-day critical-depletion appl-efficiency min-amount This line states that the irrigation season ranges from begin-day to end-day each year. Irrigation occurs whenever the amount of available water in the root zone has been reduced to less than the critical-depletion percent of its maximum amount. The amount of water required to bring the root zone back to field capacity is calculated and divided by the application efficiency, appl-efficiency. This calculated amount represents the amount of irrigation applied on this day unless the calculated amount is less than the minimum amount, min-amount, which can be applied at one time. If the minimum amount exceeds the required amount, the minimum amount is applied. |
| Seed | A random number generator is used to generate weather and to select planting and application dates from the specified windows. Normally a seed for the random number generator will be taken from the system clock. However, the user can specify a particular seed by including this keyword followed by a negative whole number. |
| Crop | This line specifies the name of the crop being grown on the site. Following the name of the crop is a file name which contains the crop coefficients. The crop name must match a crop name in the crop coefficient file. The crop name cannot include blanks and must be less than 20 characters in length. See File Structures for details on the crop coefficient file. If evapotranspiration is read from a file for each day instead of being estimated, this line can be omitted. |
| PlantingDate | This line contains the first and last days (expressed as day of year) in which this crop is normally planted. For each year simulated, the system randomly selects a day from within this window as the planting day for that year. If the first and last days of the window are the same, the crop will be planted on that one day each year. This line can be omitted if actual evapotranspiration is read from a file. |
| BeginSimulation | This line contains the year and day of year when simulation begins. |
| EndSimulation | This line contains the year and day of year when simulation ends. The number of years simulated cannot exceed 100 years for UNIX versions or 40 years for DOS versions. |
| NumberOfSimulations | This line contains an integer representing the number of times the soil-chemical systems in the systems block will be simulated. If this line is missing a value of 1 is assumed. The number of simulations can be greater than one only if both infiltration and evapotranspiration are generated. |
| Mode | When weather is generated, the default mode of operation is to generate
a sequence of weather to cover the span of time simulated. That weather is
then used for one simulation on each of the soil-chemical systems present
in the systems block of the input file. If more than one simulation is specified
in the NumberOfSimulations line, a new weather set is generated for each
succeeding pass through the system block. Another approach is to generate
new weather for each soil-chemical system in the system block. If this mode
of operation is wanted, the following line must be present in the general
information block: Mode NewWeatherEachSystem |
| Output | Information on this line specifies type of output desired. Output is
of the form of time - depth data pairs or time - depth - amount data triplets.
The user may specify depths of interest and the system will calculate the
travel time to those depths. The user may also specify times of interest
and the system will calculate the depth of the chemical at those times. Possible
forms of this line are described below. All three of the lines can be
present in one file.
Output Depth time(1) time(2) time(3) ...
time(10)
Output TravelTime depth(1) depth(2) depth(3) ... depth(10)
Output InfiltrationET |
Keywords in Systems Block |
|
| Comment | Comments for the benefit of the user can be inserted into this section of the file although they cannot separate consecutive lines beginning with SoilProperty or ChemicalProperty. |
| SystemIndex | Each soil - chemical - management system to be simulated must include an identifier. This is a string of 20 characters or less. This index serves as an identifier for model output for the soil - chemical - management system so it should be unique. |
| Chemical | This line is used to specify chemical properties. It must take one
of the following forms. Chemical Calendar application-year earliest-day latest-day application-depth application-amount Koc half-life chemical-name or
Chemical Relative application-year earliest-day latest-day
application-depth application-amount Koc half-life chemical-name
|
| ChemicalProperty | By default, CMLS98B calculates the partition coefficient, Kd,
as the product of Koc and the fractional organic carbon content.
The half-life of the chemical is assumed constant with depth. If the user
does not want to use these estimates, the ChemicalProperty keyword can be
used to define other parameters. The line takes the form
ChemicalProperty index Kd half-life where index represents the layer number in the soil profile, Kd represents the partition coefficient of the chemical (ml g-1) for this layer, and half-life represents the degradation half-life (days) for the chemical for this layer. If this keyword is used, it must be used repeatedly for each soil layer defined with the SoilProperty keyword. If it is used, the Koc and half-life values entered with the Chemical keyword are not used. If this keyword is used, it must precede the SoilProperty keywords for this soil-chemical system. |
| SoilName | This is a one-line description for the soil. It is an optional parameter for the benefit of the user. Sometimes it is convenient to include the county and mapping unit identifier. |
| CurveNoRootDepth | This line contains the curve number and the root depth for this soil system. The curve number is needed if infiltration is estimated from weather data. This line must precede the SoilProperty lines described below. |
| Resample | Hornsby et al. (1990) developed a method of generating soil profiles
from a limited set of measured profiles for the purpose of incorporating
spatial variability of soil properties into estimates of chemical leaching.
This technique was incorporated into CMLS98B and can be used by including
this keyword inside a system index block. The line takes the form
Resample n-times n-layers depth(1) depth(2) ... depth(n) where n-times represents the number of profiles to be generated and used in each simulation pass, n-layers represents the number of layers in each generated profile, and depth(1), ..., depth(n) represent the depths of the bottoms of each of the layers. If this option is used, this keyword must precede the SoilProperty section and the SoilProperty section must contain sequential lists of soil properties for 3 or more sites. |
| SoilProperty | This line contains the soil properties for one soil horizon. It must
be repeated for each horizon or layer in the soil system being simulated.
The line has the form
SoilProperty index depth oc bd fc pwp sat The index specifies the number of the soil layer being entered on the current line. It goes from 1 to the number of layers in the soil profile. The depth of the bottom of the current layer is stored in depth. Depth units are meters or `inches as specified in LengthUnits. Organic carbon content(%) and bulk density (Mg m-3) of the layer take on the values stored in oc and bd, respectively. Water contents (on a volume percentage basis) at "field capacity", "permanent wilting point", and saturation are specified as fc, pwp, and sat, respectively. |
