Apsim

News
About Us
Products
Support
Bugs & Tasks
Links
Print all Modules

Print RSS The APSIM accum module enables a user to accumulate values for variables over a period of days so that they may be used for management or reporting actions. Any variable from a module included in a simulation can be accumulated over a defined period of time. For a working sample of the Accum module look to the sample provided in the sample directory under Accum. The APSIM-Barley Module - (Barley)
Disclaimer
NOTE: The Barley module is a Prototype only. This module is not to be used in model applications.
BARLEY Module Scope

The APSIM-Barley module simulates the growth and development of a barley crop in a daily timestep on an area basis (per square meter, not single plant). Barley growth and development in this module respond to weather (radiation, temperature), soil water and soil nitrogen. The barley module returns information on its soil water and nitrogen uptake to the soil water and nitrogen modules on a daily basis for reset of these systems. Information on crop cover is also provided to the water balance module for calculation of evaporation rates and runoff. Barley stover and root residues are passed' from barley to the surface residue and soil nitrogen modules respectively at harvest of the barley crop. Approaches used in modelling crop processes balance the need for comprehensive description of the observed variation in crop performance over diverse production environments and the need to avoid reductionist approaches of ever-greater complexity with large numbers of parameters that are difficult to measure.
A list of the module outputs is provided in the Barley module outputs' section below. Basically the module simulates phenological development, leaf area growth, biomass and N concentration of leaves, stems, roots and grains on a daily basis. It also predicts grain size and grain number.
Barley Module History

APSIM-Barley was developed from a combination of the approaches used in previous APSIM barley modules: Asseng et al. 1998a,b, Meinke et al. 1997a,b and Wang et al. 2003. The current version of the model is implemented within the APSIM Plant model framework which is currently used for other crops such as grain legumes and canola. Most of the model constants (species-specific) and parameters (cultivar specific) are externalised from the code.
Barley Module Structure

Figure 1 shows the modular structure of APSIM-Barley.
Barley Module Components

Phenology APSIM-Barley uses 11 crop stages and ten phases (time between stages). It can output stage code and names as well as equivalent Zadok's stage. Table 2 lists the stage code, name and the key processes starting at the commencement of each stage. Table 2: Stages of phenological development simulated in APSIM_Barley.
Stage Code 1 2 3 4 5 6 7 8 9 10 11
Stage Name Sowing Germination Emergence
Starting processes Seed germination Emergence, leaf initiation Vegetative growth (LAI, DM), water/N uptake Photoperiodism
Equivalent Zadok's 0 5 10 10 15 / 30 60 71 87 90 93 100
End of Juvenile Stage Floral Initiation / Spikelet initiation / terminal spikelet* Rapid stem growth Anthesis Setting grain numbers Start of Grain Filling Active grain growth End of Grain Filling Maturity Physiological Grain moisture loss Maturity Harvest Ripe End Crop
*Because the CERES-Wheat phenology approach is used (see text below), terminal spikelet, instead of floral initiation, is simulated in the current barley model. The commencement of each stage (except for sowing to germination, which is driven by soil water content) is determined by accumulation of thermal time. Each day the phenology routines calculate today's thermal time (in degree-days) from 3-hourly air temperatures interpolated from the daily maximum and minimum crown temperatures. Crown temperatures are simulated according to the original routines in CERES-Wheat. Thermal time is calculated using the relationship in Figure 2 with the eight 3-hour estimates averaged to obtain the daily value of thermal time (in degree-days) for the day. These daily thermal time values are cumulated into a thermal time sum, which is used to determine the duration of each phase.
Figure 2. Relationship between crown temperature and thermal time used in APSIM-Barley. Between the stage of emergence and flowering the calculated daily_thermal_time can be reduced by water or nitrogen stresses, resulting in delayed phenology when the plant is under stress. These stress factors can be specified in barley.ini by changing the values of x_sw_avail_ratio/y_swdef_pheno and N_fact_pheno . Currently these values are set so that there are no water and nitrogen stress effects on phenological development. Research showed that moderate water stress may accelerate development, while severe water stress may delay phenology (Angus, 1977). Germination is considered as a quick process. Germination is assumed to occur as long as the extractable soil water in the seed layer is above a given value pesw_germ specified in Barley.ini. pesw_germ is the soil water content above the crop lower limit (mm/mm) in the seed layer inadequate for germination. The default setting is zero, meaning that germination will occur one day after sowing regardless of soil water content. The phase between germination and emergence includes an effect of the depth of sowing on the thermal time target. The phase is comprised of an initial period of fixed thermal time during which shoot elongation is slow (the lag phase) and a linear period, where the rate of shoot elongation towards the soil surface is linearly related to air temperature (measured in o Cd mm -1 ). Most studies on seedling emergence have simply recorded the accumulated thermal time between germination and 50% emergence from a given sowing depth. For the purposes of model parameterisation the value of shoot_lag has been assumed to be around 40 o Cd, while shoot_rate has been derived from studies where thermal time to emergence was measured and where sowing depth was known and it is set to 1.5 o Cd per mm. This means that at a sowing depth of 4 cm emergence occurs 100 o Cd after germination (40+1.5*40). There is the capability of increasing the time taken to reach emergence due to a dry soil layer in which the seed is germinating, through the relationship between fasw_emerg andrel_emerg_rate . Currently this effect is turned off in the Barley.ini file. The phase between emergence and end of juvenile stage is composed of a cultivar-specific period of fixed thermal time, commonly called the basic vegetative or juvenile phase, which is a period when development rate is not affected by photoperiod. The end of the juvenile phase in barley is currently timed as occurring on the day after emergence, because it is known that the development rate of barley is sensitive to photoperiod from emergence. The end of the juvenile phase is included in the model to make the stages compatible with other cereal crops in APSIM that do have a definable juvenile phase.
After the end of the juvenile phase the crop takes 400 o Cdays to reach terminal spikelet stage. The rate at which the crop attains this target depends upon photoperiod and vernalisation. The daily rate of accumulation of thermal development rate is sensitive to photoperiod and accumulation of vernalising days. The sensitivities to photoperiod (photop_sens ) and vernalisation ( vern_sens ) are cultivar-specific. The model assumes that barley, as a long day plant, will have a longer phase (dependent upon cultivar) between the end of the juvenile phase and terminal spikelet under short days. Photoperiod is calculated from day of year and latitude using standard astronomical equations accounting for civil twlight using the parameter twilight, which is assumed to be 6 o . Twilight is defined as the interval between sunrise or sunset and the time when the true centre of the sun is 2.2 degrees below the horizon. Vernalisation is simulated from daily average crown temperature and daily maximum and minimum temperatures using the original CERES approach. Devernalisation can occur if daily maximum temperature is above 30 o C. There are fixed thermal time durations for the subsequent phases between terminal spikelet and flag leaf (3 phyllochrons), from flag leaf to flowering (2 phyllochrons + 80 o C days). In the original CERES phenology routines, 2 phyllochrons from flag leaf marked the end of ear growth and then 80 o C days was required to reach anthesis. From flowering to the start of grain fill the thermal duration is assumed to be 120 o C days (= 200-80 o C days, in CERES 200 o C days was assumed to elapse between the end of ear growth and the start of grain filling). The duration of grain filling ( tt_startgf_to_mat ) is cultivar specific and usually lies between 500 and 800 o C days. Biomass accumulation (Photosynthesis) Radiation interception Radiation interception is calculated from leaf area index and a radiation extinction coefficient ( extinct_coeff ) that varies with row spacing. Radiation Use Efficiency The intercepted radiation is converted to above ground biomass via a RUE (radiation-use efficiency), which is 1.24 g MJ -1 from emergence to the end of grain-filling, and does not vary as a function of daily incident radiation as in NBARLEY. RUE is reduced by extremes of daily mean temperature as sown in the following figure. It is also reduced by a nitrogen stress factor n_fact_photo specified in Barley.ini.
Figure 3: Response of barley radiation-use efficiency to temperature
Water-nonlimiting Under water non-limiting condition, the biomass growth rate is given by: dlt_dm_rue = RUE *radiation_interception eqn 1. Water-limiting Each day two estimates of the daily biomass production are calculated, one limited by available water for transpiration (eqn 2), and the other limited by radiant energy (eqn 1). The minimum of these two estimates is the actual biomass production for the day. dlt_dm_water = soil_ water_ supply * transpiration_efficiency eqn 2. dlt_dm = min(dlt_dm_water, dlt_dm_rue) transpiration_efficiency is derived from the transpiration_efficiency_coefficient (=0.006 kPa) and the vapour pressure deficit (vpd) estimated from daily temperatures. Biomass partitioning and retranslocation Partitioning On the day of emergence, biomass in plant parts (leaf, root, and stem) is initialised to user-specified values. Daily biomass production is then partitioned to different plant parts in different ratios depending on crop stage. In the barley module, leaf includes only leaf blade. Stem is defined in a functional rather than a morphological manner and includes stem proper, leaf sheaths and stem-like petioles. The biomass increase calculated each day only accounts for the above ground organs. The minimum fraction of biomass going to roots is calculated from the stage dependentroot_shoot_ratio specified in Barley.ini. Between emergence and grain filling, the above ground biomass is partitioned to leaf, stem and head based on stage dependant partitioning rules. If, on any day, the estimated specific leaf area (based on leaf biomass and LAI deltas) goes below the minimum specific leaf area, the extra biomass is diverted to stems. At anthesis, the number of grains set per plant is determined by the stem weight. From start to end of grain filling biomass increase is used to meet grain demand first, the rest is put into stems. Grain demand for carbohydrate (biomass) is calculated by multiplying the grain number by the potential grain growth rate ( potential_grain_filling_rate, g/grain/degree day ) specified in Barley.ini . Re-translocation If the supply of assimilate (daily biomass increase) is insufficient to meet grain demand then retranslocation may be used to meet the shortfall. The barley module allows a total retranslocation of no more than 20% of stem biomass present at the start of grainfilling Grain yield on a commercial moisture basis is calculated using the parameter grn_water_cont = 0.125. Leaf initiation/appearance and tillering Leaves appear at a fixed phyllochron of thermal time, currently set to 95 o Cd in the barley.ini. No effect from water and N stress on leaf appearance is accounted for. Leaf area growth On the day of emergence leaf area per plant is initialised to a value of 200 mm 2 per plant. Potential LAI growth rate Potential increase in plant leaf area is calculated from main stem node appearance rate multiplied by the leaf size (as a function of node number) multiplied by the number of leaves per main stem node (i.e. tiller number)
Leaf area growth rate under stress Water and nitrogen limitations affect leaf area development directly rather than via dry matter production. Water and nitrogen limitations result in either a reduction of leaf expansion or in number of tillers produced. Two stress factors are introduced to account for the effect of water and nitrogen stress respectively on leaf area growth. It is assumed that leaf expansion growth is reduced when the supply/demand ratio for water is below 1.1 and stops when supply/demand ratio reaches 0.1. This relationship is specified in Barley.ini in the look-up tablex_sw_demand_ratio/y_swdef_leaf . The nitrogen stress factor is defined as: g_nfact_expansion = N_fact_expansion * n_conc_ratio_leaf where n_conc_ratio_leaf is the relative N concentration in leaves (N_conc_leaf N_conc_leaf_min)/(N_conc_leaf_crit - N_conc_leaf_min). N_fact_expansion is a modifying constant specified in Barley.ini. It is currently set to 1.0, ie. leaf expansion is reduced once leaf N concentration is below the critical N concentration, and stops when leaf minimum concentration is reached. The leaf area growth rate under stress is given by: g_dlt_lai_stressed = g_dlt_LAI_pot * min (g_swdef_expansion, g_nfact_expansion) Actual leaf area growth rate Actual leaf area growth rate differs from stressed leaf area expansion rate (g_dlt_lai_stressed) only if carbon supply is insufficient to meet a maximum specific leaf area for the daily increase in leaf area ( sla_max ). Carbon supply may become limiting, for example, at high plant population densities. The current model specifies sla_max as varying from 27 000 to 22000 mm 2 g -1 t o constrain daily leaf area increase where carbon is limiting. However, as the value of the maximum specific leaf area operates on the daily increase in leaf area it is not readily derived from experimental data and must be calibrated by trial-and error. Root growth and distribution Root depth growth Between germination and start of grain filling, the increase in root depth is a daily rate multiplied by a number of factors. Root depth is constrained by the soil profile depth The optimum rate of elongation is 30mm d -1 . This can be limited by supra- or sub-optimal temperatures. Dry soil can slow roots through a layer if the soil water content is less than 25% of the way between the lower limit and drained upper limit. The increase of root depth through a layer can be constrained by known soil constraints through the use of the 0-1 parameterxf, which is input for each soil layer. Root length density Growth of root biomass is partitioned with depth using a branching function and converted to root length density using a fixed specific root length of 105,000 mm g -1 . Root biomass is grown daily in proportion to the tops production. This proportion ( ratio_root_shoot ) is specified for each growth stage, and varies from 1.0 at emergence, to 0.09 at flowering. Senescence
Root senescence A rate of 0.5% of root biomass and root length is senesced each day and detaches immediately being sent to the soil nitrogen module and distributed as fresh organic matter in the profile. Leaf senescence There are four causes of leaf senescence: age, water stress, nitrogen stress and high temperature stress. The barley senescence routines calculate stress factors for water, N and high temperature. The maximum of these is multiplied by the senesced LAI due to age each day to obtain the day's total senescence. The stress factor for water is calculated from swdef_photo , for N from nfact_photo. Senescence due to frost commences when temperatures decrease below -5 C. Nitrogen in seneseced leaves When leaf is senesced, only a small amount of nitrogen is retained in the senesced leaf, the rest is made available for re-translocation by putting it into stem N pool. The concentration of nitrogen in senesced material is specified in the barley ini file. Crop Water Relations Potential water extraction rate When the Barley module is coupled to APSIM-SOILWAT2, potential soil water uptake is calculated using the approach first advocated by Monteith (1986). It is the sum of root water uptake from each profile layer occupied by roots. If roots are only partially through a layer available soil water is scaled to that portion that contains roots. The potential rate of extraction in a layer is calculated using a rate constant ( kl ), which defines the fraction of available water able to be extracted per day. The kl factor is empirically derived, incorporating both plant and soil factors which limit rate of water uptake. Root water extraction constants ( kl ) must be defined for each combination of crop species and soil type. Crop water demand Following Sinclair (1986) and Monteith (1986), transpiration demand is modelled as a function of the current day's crop growth rate (dlt_dm_rue, see Biomass Accumulation Section), divided by the transpiration efficiency. Transpiration efficiency is related to the daylight averaged vapour pressure deficit ( vpd ). Transpiration demand is calculated from the daily crop growth rate limited by RUE (dlt_dm_rue), vpd , and the transpiration efficiency coefficient. In the model vpd is estimated using the method proposed by Tanner and Sinclair (1983), which requires only daily maximum and minimum temperatures. In this method, it is assumed that the air is saturated at the minimum temperature. The saturated vapour pressure is calculated at both the maximum and minimum temperatures, and the default vapour pressure deficit for the day is taken as 75% of the difference between these two vapour pressures. Crop water demand is capped to below a given multiple of potential ET (taken as Priestly-Taylor Eo from the water balance module) as specified in the barley ini file. This limits water use to reasonable values on days with high VPD or in more arid environments. Water uptake The actual rate of water extraction is the lesser of the potential extraction rate and the transpiration demand. If the computed potential extraction rate from the profile exceeds demand, then the extracted water is removed from the occupied layers in proportion to the values of potential root water uptake in each layer. If the computed potential extraction from the profile is less than the demand then, and the actual root water uptake from a layer is equal to the computed potential uptake. Water stresses affecting plant growth
Soil water deficit factors are calculated to simulate the effects of water stress on different plant growth processes. Three water deficit factors are calculated which correspond to four plant processes each having different sensitivity to water stress i.e. photosynthesis (photo), leafexpansion (expansion), phenology (pheno), and tillering (tiller). A factor of 0 is complete stress and 1 no stress. Leaf expansion is considered more sensitive to stress than photosynthesis. Nitrogen uptake and re-translocation Potential nitrogen supply The model uses a simplified formulation for NO3 uptake somewhat similar in structure to that employed in water uptake. Potential NO3 uptake in a layer is given as Uptake = NO3 kg/ha x (Kln x NO3 ppm x SWFAC) Where Kln is a parameter constant and SWFAC is a soil water content factor based on relative soil water content between lower limit and drained upper limit. Nitrogen demand by vegetative organs The crop has a defined minimum, critical and maximum N concentration for each plant part. These concentration limits change with phenological stages. The maximum and minimum N concentrations can be found in Barley.ini. Demand for N in each part attempts to maintain N at the critical (nonstressed) level. N demand on any day is the sum of the demands from the pre-existing biomass of each part required to reach critical N content, plus the N required to maintain critical N concentrations in that day's produced biomass. For each plant part (leaf, stem, root) the N demand is given by: N_demand = dm_green * (n_conc_critic - n_conc) + dlt_dm_green * n_conc_critic. Where dm_green and dlt_dm_green are the existing live biomass and biomass growth rate today. N_conc and n_conc_critic are the actual and critical N concentration respectively of this plant part. Total crop N demand is the sum of the n demand in all vegetative parts. Nitrogen partition in the plant Daily total nitrogen uptake is distributed to the plant parts in proportion to their individual demands. Grain N demand Grain nitrogen demand starts at anthesis and is calculated from grain number, thermal time and a potential grain nitrogen filling rate (g/grain/degree day). Nitrogen re-translocation If there is insufficient nitrogen supplied from senescing material or soil nitrogen uptake, grain nitrogen demand is met by re-translocating nitrogen from other plant parts. Nitrogen is available for re-translocation from leaves and stems until they reach their defined minimum N concentration. Nitrogen deficits affecting plant growth There are four N availability factors (0-1), one each for the photosynthesis, expansion, phenology and tillering. A N concentration ratio is calculated for the stover (stem + leaf) which is used as a measure of N stress, then different constants are used to convert that ratio to a deficit factor for each of the processes. A factor of 1.5 is used to restrict photosynthesis (reduces rue), 1.0 for expansion (reduces leaf area expansion) and 100 to slow phenological development (effectively disabled). For
tillering a squared n_conc_ratio is used as the stress factor. As a value of 1 is no stress and 0 complete stress, phenology is least sensitive to nitrogen deficiency and grain N the most. N_conc_ratio=(N_conc_stover-N_conc_stover_min)/(N_conc_stover_crit-N_conc_stover_min) Plant death All or some of the plants can be killed due to a variety of stresses. If the crop hasn't germinated within 40 days of sowing, due to lack of germinating moisture, all plants are killed. If the crop does not emerge with 300 o Cdays of sowing, because it was sown too deep, then all plants are killed. If crop is past floral initiation and LAI = 0, then all plants are killed due to total senescence. Detachment The detachment routines in barley are disabled in the barley.ini file, except the detachment of senesced roots. Effects of elevated atmospheric CO 2 Elevated levels of atmospheric CO 2 affect plant growth in this module via three mechanisms. Carbon dioxide concentration can affect radiation use efficiency, transpiration efficiency and critical leaf nitrogen concentration. The following graph shows the relative change in RUE for C4 and C3 plants (at 20 o C), TE and critical nitrogen concentration. More information can be found in Reyenga et al (1999).
Barley Module Parameterisation

Crop lower limit (LL) and water extraction coefficients (KL) and root exploration factors (XF) values are need for each soil layer. The following example is used in the sample run.
sample.barley.parameters uptake_source = calc ! calculate own uptakes. !layer 1 2 3 4 5 6 7 ll = .200 .201 .215 .176 .141 .249 .279 ! Crop lower limit kl = 0.06 0.06 0.06 0.06 0.06 0.06 0.02 ! Water Extraction parameter (0-1) xf = 1.00 1.00 1.00 1.00 1.00 1.00 1.00 ! Root Exploration factor (0-1)
Module Dependencies
The minimum module configuration required to run barley in APSIM is the inclusion of the report, input, manager, soilwat2, soiln2, residue2 and barley modules. In the sample folder, within the manager file the following syntax is used for harvest and planting the barley crop: barley.manager.start_of_day if day = 169 and year = 1992 then barley sow cultivar = hartog, plants = 121.61, sowing_depth = 30 (mm), endif if barley.stage_name = 'harvest_ripe' or barley.plant_status = 'dead' then barley harvest barley end_crop endif
REFERENCES
The APSIM Broccoli Module Transplant

===CropType === = broccoli
Population
Value = 4
Arbitrator
===DMSink=== = Stem
Phenology
===ThermalTime=== Temperature (oC) 5, 25, 35
ThermalTime 0.0, 20.0, 0.0
Shock
Shock extends from Transplanting to EndShock with a fixed thermal time duration of 80 degree.days.
Juvenile
TTTarget 0, 30, 350, 0
Start = EndShock End = FloralInitiation
VDModel
Temperature (oC) 0, 2, 15 VDModel 0.0, 1.0, 0.0
Vegetative
Start = FloralInitiation End = StartBudding RemainingLeaves = 10.
Budding
Budding extends from StartBudding to Buttoning with a fixed thermal time duration of 120 degree.days.
Heading
Heading extends from Buttoning to Maturity with a fixed thermal time duration of 180 degree.days.
Mature
Start = Maturity End = Unused
Leaf
Frgr = 1 PrimaryBudNo = 1 MaxCover = 1.0
ExtinctionCoeff
Leaf.LAI 0, 0.8
ExtinctionCoeff 0.8, 0.5
KDead = 0.5
Height
Stem.LiveWt 0, 300
Height 100.0, 750.0
FrostFraction
0, 0.0, 2, 0.0
Photosynthesis
FT 0, 0.0, 10, 1.0, 22, 1.0, 35, 0.0
FVPD 0, 1.0, 10, 1.0, 50, 1.0, RUE = 1.7
PartitionFraction Early
The value of Early during the period from Transplanting to FloralInitiation is calculated as follows: Function Value = 0.64
Middle
The value of Middle during the period from FloralInitiation to Buttoning is calculated as follows: Function Value = 0.40
Late
The value of Late during the period from Buttoning to Maturity is calculated as follows: Function Value = 0.18
ThermalTime
Temperature (oC) 5, 25, 35 ThermalTime 0.0, 20.0, 0.0
NodeInitiationRate
The value of NodeInitiationRate during the period from Transplanting to FloralInitiation is calculated as follows: Function Value = 15.0 MaxNodeNo = 40
NodeAppearanceRate
The value of NodeAppearanceRate during the period from EndShock to Maturity is calculated as follows: Function Leaf.NodeNo 1, 5, 6, 30
NodeAppearanceRate 30, 30, 30, 30 InitialAreas = 200 1326 990 844 167 InitialAges = 150 120 90 60 30 InitialiseStage = Transplanting InitialLeafPrimordia = 8
ExpansionStress
WaterSupply DemandRatio 0.0, 1.0 ExpansionStress 0, 1
MaxArea
Leaf.NodeNo 1, 2, 5, 11
MaxArea 200, 1800.0, 14700.0, 83000.0
SpecificLeafArea
Leaf.NodeNo 1, 30
SpecificLeafArea 16000.0, 16000.0
GrowthDuration
GrowthDuration 60.0, 210.0, 450.0, 900.0
LagDuration
LagDuration
50.0, 100.0, 250.0, 250.0
SenescenceDuration
Leaf.NodeNo 1, 5, 11, 15 SenescenceDuration 200.0, 200.0, 200.0, 200.0
BranchingRate
Leaf.NodeNo 5, 10, 15 BranchingRate 0.0, 0.0, 0.2
PartitionFractionMax
===Early=== The value of Early during the period from Transplanting to FloralInitiation is calculated as follows: Function Value = 0.60
Middle
Late
Stem
===PartitionFraction===
Early
The value of Early during the period from Transplanting to FloralInitiation is calculated as follows: Function Value = 0.16
Middle
Late
StructuralFraction
Value = 1.0
Root
ll = 0.29 0.29 0.29 0.29 0.3 0.31 0.32 0.33 0.34 0.35 0.36 kl = 0.07 0.07 0.07 0.07 0.05 0.05 0.04 0.04 0.04 0.04 0.04 xf = 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 InitialDM = 0.2 SpecificRootLength = 40000
KLModifier
Leaf.LAI 0.0, 3.0 KLModifier 0.1, 1.0
RootFrontVelocity Shock
The value of Shock during the period from Transplanting to EndShock is calculated as follows: Function Value = 0.0
Active
The value of Active during the period from EndShock to Maturity is calculated as follows: Function Value = 20.0
PartitionFraction
Value = 0.2
TemperatureEffect
Temperature (oC) 0 20 32 TemperatureEffect 0.0 1.0 0.0
Floret
Early
The value of Early during the period from Transplanting to Buttoning is calculated as follows: Function Value = 0.0
HeadGrowth
The value of HeadGrowth during the period from Buttoning to Maturity is calculated as follows: Function Value = 0.65
StructuralFraction
Value = 1.0 RipeStage = Maturity
StageCode
Stages = Transplanting EndShock FloralInitiation FinalLeaf Buttoning Maturity Codes = 1 2 3 4 5 6
Introduction
The canola module was developed by Michael Robertson in conjunction with Chris Smith (CSIRO Land and Water), John Holland (NSW Agriculture) and John Kirkegaard (CSIRO Plant Industry). Further testing has been conducted by Imma Farre (CSIRO Plant Industry). The module is described in the paper by Robertson et al. (1999). The reader is referred to the science document for the plant module for a comprehensive description of the processes simulated by APSIM-Canola. This document outlines some canola-specific issues that are not covered by the plant science document. The canola module simulates canola (Brassica napus) and the related species Indian mustard (Brassica juncea).
Notable features of APSIM-Canola

The phenology of canola cultivars respond to vernalisation and photoperiod (daylength). In the module, all green leaf area senesces soon after flowering and photosynthesis is then conducted by the pods. APSIM-Canola is not phosphorus-responsive, this is currently under development. Crop growth is not sensitive to row spacing Crop growth is not sensitive to waterlogging.
Cultivars and crop classes

There are three crop classes: Conventional canola Triazine tolerant canola this crop class has a radiation use efficiency 20% less than the conventional type Winter canola this is designed to simulate European types, but has received limited testing. It differs from the conventional crop class in that it has a different sensitivity of leaf senescence to frost and a different rate of leaf senescence due to ageing. There are 14 conventional cultivars: PacN145, Monty, Hyola42, Surpass400, Rainbow, Mystic, Narendra, Surpass600, Geordie, Oscar, Marnoo, Eureka, Charlton, Clancy, Dunkeld There are three triazine-tolerant cultivars: Karoo, Drum, Pinnacle There are two mustards: JL1, 397 There are four generic cultivars: early, mid and late maturing, and a mustard NOTE: there is no explicit linking of crop classes with cultivars in APSIM-Canola, so the user must be aware to specify the triazinetolerant class, for instance, if they are using a triazine-tolerant cultivar.
Validation
APSIM-Canola has received testing across the Australian wheat belt, with factors such as cultivars, sowing date, N supply, irrigation, soil type varying. Papers describing validation of APSIM-Canola are by Robertson et al. (1999), Robertson et al. (2001), and Farre et al (2001). The following two figures demonstrate the performance of the module against Australian datasets.
Figure 1: Observed and predicted (a) grain yield (oven-dry) at maturity and, (b) total biomass at maturity for datasets presented by Robertson et al (1999). The line is the 1:1 relationship. The model was tested against independent datasets from Australia (26 to 36o latitude), which varied in terms of nitrogen supply, water supply, sowing date, and variety. Grain yields, ranging from 30 to 500 gm-2, were simulated with a root mean squared deviation of 45 gm-2 (15% of the observed
mean).
Figure 2
: Simulated and observed flowering date and grain yield for different canola cultivars at three sites in Western Australia (Mt Barker, Mullewa and Wongan Hills) in 1998 . The dotted line is the 1:1 line. DOY-day of the year.
References
Farr, M. J. Robertson, G. H. Walton, S. Asseng 2000. Simulating response of canola to sowing date in Western Australia. 10th Australian Agronomy Conference, Hobart, Tasmania. Robertson MJ, Holland JF, Kirkegaard JA, and Smith C J 1999. Simulating growth and development of canola in Australia. Proceedings 10th International Rapeseed Congress. (CD-Rom Proceedings). Robertson MJ, Holland J, Cawley S, Bambach R, Cocks B and Watkinson AR 2001. Phenology of canola
cultivars in the northern region and implications for frost risk. 10th Australian Agronomy Conference, Hobart, Tasmania.
Operation
When a simulation is conducted in APSIM involving light and water competition between crops, the user must plug in the CANOPY module. The CANOPY module arbitrates the competition for intercepted radiation. On a daily basis, the module finds the number of crops in the simulation and their canopy heights. Canopy layers are then defined, with the layer boundaries being defined by the top of each canopy. Thus there are as many layers as canopies. Then each layer in turn is taken from the top, in the combined canopy, to get the combined extinct_coeff*lai value (green + dead) of the canopies present in that layer. The fraction of light transmitted out of the bottom of that layer can be calculated, which is in turn the fraction entering the next layer below. The total radiation intercepted in a layer is divided amongst the canopies occupying the layer, being done on the basis of extinct_coeff * LAI of each canopy. This approach ignores the possibility of different LAI distributions within a layer. LAI is distributed with height in the canopy using normalized height and integration of a function to the power of 5. This results in 47% of the leaf area in the top 10% of height, 27% in the next 10%, 15% in the next 10%, and so on. Arbitration for water and nitrogen uptake is done on the basis of APSIM changing the order each day (on a rotational basis) in which the competing species are given the opportunity to capture soil resources. A maximum of ten crops can be specified for inter cropping.
Introduction
The chickpea module was developed by Peter Carberry, Jill Turpin and Michael Robertson, with contributions of data from Bob Brinsmead and Harry Marcellos. The module is described in the paper by Robertson et al. (2002). This module is being updated by work conducted by Jeremy Whish at APSRU. The reader is referred to the science document for the plant module for a comprehensive description of the processes simulated by APSIM-Chickpea. This document outlines some chickpea-specific issues that are not covered by the plant science document.
Notable features of APSIM-CHICKPEA

The Module simulates dsi types of cultivars The phenology of chickpea cultivars is responsive to temperature and photoperiod, but not vernalisation. Model performance on days to flowering was reported by Carberry (1996) and is repeated in the graph below (Figure 1). The module does not simulate production from second and further flushes of flowers and pods. Under well-watered conditions, chickpea may have a low harvest index due to continued vegetative growth at the expense of reproductive yield. The model does not currently simulate this phenomenon. When chickpea flowers and attempts to set pods under cold conditions, pod set can be delayed until temperatures rise above a critical threshold. This phenomenon is not simulated in this module. APSIM-Chickpea is not phosphorus-responsive, this is currently under development. Crop growth is not sensitive to waterlogging.

There is one crop class. There are 6 cultivars able to be simulated: Amethyst, CPI56288, Dooen, Tyson, CV244-1, CPI56566. Cultivars differ in terms of biomass partitioning to grain and phenology. If users wish to use more modern cultivars they should contact Jeremy Whish at APSRU for advice.
Figure 1: Observed and simulated days to flowering for chickpea.
Figure 2: Performance of the chickpea module (observed versus simulated grain yield in g/m2) against test datasets reported by Robertson et al. (2002).
Validation
APSIM-Chickpea has received testing across the northern Australian wheat belt, with factors such as cultivars, sowing date, irrigation, soil type, row spacing varying. Some testing has occurred in Wa as well. Limited testing has been conducted under dryland conditions in Syria (Moeller 2004). Papers describing validation of APSIM-chickpea are by Carberry (1996) and Robertson et al. (2002). The accompanying figure 2 demonstrates the performance of the module against Australian datasets.
In which environments should this module be used with confidence?
APSIM-Chickpea can be used with most confidence in the semi-arid sub-tropics of northern Australia, the Western Australian wheat belt, and with less confidence in dryland environments of the Mediterranean.
References
Carberry PS 1996 Assessing the opportunity for increased production of grain legumes in the farming system. Final Report to the Grains Research and Development Corporation, Project CSC9, 33pp. Moeller, C 2004. Simulation of chickpea and wheat growth in response to a semi-arid Mediterranean-type environment using APSIM' (Agricultural Production Systems Simulator. PhD Thesis Hohenheim University. Robertson, M.J., Carberry, P.S., Huth, N.I., Turpin, J.E., Probert, M.E., Poulton, P.L., Bell, M., Wright, G.C., Yeates, S.J., and Brinsmead, R.B. 2002. Simulation of growth and development of diverse legume species in APSIM, Australian Journal of Agricultural Research 53:429-446.
Description
The APSIM Clock module has been developed to replace the functionality of progressing through time that was previously contained in the simulation engine and weather file. Encapsulation of this important simulation concept will allow future flexibility in the specification of time and progress through it.
Operation
The APSIM Time Clock module is operated in a way similar to other APSIM modules. The specification of this module in the simulation control file, and its parameters in the parameter files follow normal APSIM module protocols.
Module Output Variables

The APSIM Time Clock Module can provide the values of several state variables for reporting to an output file or use by other modules.
This assumes a 52 week year with the duration of each week is adjusted so that the first week starts on 1 st of January and the last week ends on the 31st of December.
Using Sub-Daily Timesteps

It is possible to use timesteps to one minute in resolution within the current APSIM framework with the following constraints.

The timestep is constant throughout the simulation The timestep is a factor of 1440 mins/day (rational fraction of one day) The met file contains data at the same timestep resolution for all days within the simulation period The simulation will start at the beginning of a day and finish at the end of a day It is the user's responsibility to ensure that all modules with the simulation are both capable and appropriately configured to operate on these timesteps.
all_treatments.clock.parameters start_date = 1/1/1988 ! simulation starting date end_date = 31/12/1988 ! simulation ending date time-step = 60 (min) ! simulation timestep
The example above will specify the clock to step through the simulation essentially with 24 tick cycles per day.
There is no thorough testing for synchrony of modules though some modules will give error messages if they perceive possible timestep errors.
If the timestep parameter is not specified the clock module will default to a timestep of 1 day (1440 mins), that is, one tick cycle per day.
Events
The clock module produces several events that can be useful, particularly when using the TRACKER module.
Introduction
The cowpea module was developed by Peter Carberry and Michael Robertson . The reader is referred to the science document for the plant module for a comprehensive description of the processes simulated by APSIM-Cowpea. This document outlines some cowpea-specific issues that are not covered by the plant science document.
Notable features of APSIM-COWPEA

The module does not simulate production from second and further flushes of flowers and pods. APSIM-Cowpea is not phosphorus-responsive, this is currently under development. Crop growth is not sensitive to waterlogging.

There is one crop class. There are 4 cultivars able to be simulated: Banjo, Red Caloon, CPI28215, spreading. Cultivars differ in terms of biomass partitioning to grain and phenology. The spreading type is typical of that found growing under smallholder conditions in southern Africa.
Validation
APSIM-Cowpea has received testing across the northern Australia , with factors such as cultivars, sowing date, irrigation, soil type, row spacing varying. There are no papers describing validation of APSIM-Cowpea, however the accompanying figures demonstrate the performance of the module against Australian datasets. Table 1 summarises module
performance. Figure 1: Performance of the cowpea module (observed versus simulated grain yield in g/m2) against test datasets from northern Australia .
Figure 2: Time course of crop gowth for cowpea cv. Banjo sown at Gatton , Queensland under
full irrigation. Symbols are observed data and lines are simulated.
Table 1
: Statistics for goodness-of-fit for grain yield and biomass at maturity for cowpea module testing.
IN WHICH ENVIRONMENTS THIS MODULE SHOULD BE USED WITH CONFIDENCE?

APSIM-Cowpea can be used with most confidence in the sub-tropics and tropics of northern Australia. Limited tested has been conducted in southern Africa.
References
Adiku S.K., Carberry P.S. Rose, C. W., McCown, R.L. & Braddock, R. (1993). Assessing the performance of maize (Zea mays - cowpea (Vigna unguiculata) intercrop under variable soil and climate conditions in the tropics. Proceedings of the 7th Australian Society of Agronomy Conference, September 1993, Adelaide , South Australia , p. 382. Carberry, P.S.; Adiku, S.G.K.; McCown, R.L. and Keating, B.A. 1996b. Application of the APSIM cropping systems model to intercropping systems. In: O Ito, C Johansen, JJ Adu-Gyamfi, K Katayama, JVDK Kumar Rao, and TJ Rego (Eds.) Dynamics of Roots and Nitrogen in Cropping Systems of the Semi-Arid Tropics, pp. 637-648. Japan International Research Centre for Agricultural Sciences.
Applicability
The economics module in APSIM was developed primarily to serve as another input to the management module - as an index of farm "stress" that modifies the risk aversion of the farm manager. To this end, it simply maintains a cash balance through the simulation, which monitors all financial activity (eg. income, expenses, loan repayments). The bottom line is that all events that occur on a farm have a cost, and these events MUST be captured by the economics module for a realistic simulation. This includes not only crop income & expenses, but also annual operating expenses and capital replacement.
Operation
As with all apsim modules, the economics module responds to events. The main events of interest are "income" and "expenditure" events. The module will generate an "end_financial_year" event that other modules may have an interest in, internally it will calculate loan repayments on this date. Typically, these events are generated from within the manager module, for instance when sowing or harvesting a crop, preparing a seedbed, spraying for weeds and so on. The events contain parameters; typically most define a rate, category and area. The module will
write a line to the summary file describing the outcome of the event, and alos a line in the cash journal.
Expenditure Events
economics expenditure category = seedcost, name = wheat, rate = 120 (kg/ha), area = 200 (ha)
Here the module will look up the entry "wheat" in its "seedcost" section, multiply by rate by area and subtract the total from the current balance. Note that while units are specified, no unit conversion is performed. As well the paddock area must be specified.
Income Events
cropyieldTONNES = wheat.yield / 1000.0 protein = wheat.grain_protein economics income category= cropprice, name = wheat, yield = cropyieldTONNES, protein = protein, area = 200 (ha)
...
cropyieldTONNES = sorghum.yield / 1000.0 economics income category= cropprice, name = sorghum, yield = cropyieldTONNES, area = 200 (ha)
The first example shows the manager calculating a crop yield in tonnes and grain protein content, then telling the economics module (wheat price is dependant on quality). The second is a simpler version of the same.
Capital replacement
The simulation starts with an initial capital investment loan. All machinery items have an initial age, and are replaced when they exceeds thier useful life. Payments for these loans are made at the end of each financial year.
Additional machinery
Additional machinery is created by duplicating an existing node in the the ApsimUI tree. Simply rename the node, and check that the "Apsim Name" is unique.
Description:
Simulates daily soil erosion, and (optionally) the effect of soil loss on the soil profile. Code and this document derived from PERFECT.
Methods:
The calculation of daily soil loss is performed by one of two submodels: A modified MUSLE (Freebairn and Wockner) cover concentration function determined from QDPI field data to predict soil movement from the inter-contour bank area for clay soils in situations where peak discharge cannot be adequately predicted. It accounts for variation in soil loss with cover and runoff volume
(the main factors that can be managed), and uses the MUSLE slope-length, erodibility and practise factors to provide generality. The model has the following form:
Where;

E: Event soil loss (t/ha) COV: Cover (%) Q: Event runoff (mm) K: Soil erodibility factor (t/ha/EI 30 ) LS: Slope length and steepness factor P: Supporting practice factor
The LS factor from Wishmeier and Smith (1978) is related to catchment slope and length by:
Where;

LS: Slope length and steepness factor S: Sine of slope angle L: Length of catchment (m)
A simplified version of the sediment concentration function contained in GUESS (Carroll). The equation is given as:
Where;

E: Event soil loss (t/ha) S: Sine of slope angle cover: Fractional surface cover (0-1) Q: Event runoff (mm) Factor approximating efficiency of entrainment
The cover term cover in the rose equation does not fully account for the effect of cover. Therefore, the efficiency of entrainment Where;
is further modified by cover by Rose (1985):
Factor approximating efficiency of entrainment
Efficiency of entrainment (bare surface) COV Surface cover (%)
The submodels parameters are (rose_lambda), and the -0.15' exponential term (rose_b2). Feedback from erosion on the soil profile The module is capable of eroding the soil profile as soil loss occurs (see profile_reduction). The module remains ignorant of what other modules may be doing through the profile, all it does is send a delta to whichever module owns dlayer - typically soilwat2. It is the responsibility of other modules to ensure they remain consistent with this new profile. The calculation of "dlt_depth_mm" describing the change in each profile layer for the given amount of soil loss is given by: dlt_depth_mm(i) = (100.0*soil_loss) / (1000.0*bd(i)) Where;

soil_loss Event soil loss (t/ha) bd Bulk density of the respective profile layer (g/cc) The bulk density for each layer is used to maintain mass balance of soil movement up through the (constant) soil layer thicknesses. Erosion continues replacing the lowest profile layer with imaginary material of the same properties until a limit (see bed_depth) is reached. Once the lowest profile layer rests against bedrock, further soil erosion reduces the thickness of this layer until it is a fraction (see profile_layer_merge) of its original thickness. Once this fraction is reached, the layer is merged into the next highest layer. (Currently, many apsim modules cannot sensibly deal with the last scenario.) This process continues until the parameter minimum_depth is reached, at which the simulation stops with a fatal error.
Splitting soil loss into suspended and bed loads. There is provision to split soil loss into two components: suspended and bed loads. This reflects how soil loss is measured. Each soil loss submodel is performed twice: once for suspended ediment, and once for heavy particles. For the modified MUSLE model, the parameter K is replaced by K_bed and K_susp ( NB. It's important to remove or comment out the original K parameter, otherwise the module assumes you are still trying to use a single soil loss equation) For the rose model, parameters lambda and b2 are replaced by lambda_bed, lambda_susp, b2_bed and b2_susp. Once again, you must remove the original definitions of lambda and b2. Reporting the separate losses is through soil_loss_bed, soil_loss_susp, both in units of t/ha, and sed_conc_bed, sed_conc_susp (g/l). soil_loss returns total soil loss, and sed_conc returns total sediment concentration. Communicating with water balance modules As the erosion module was derived substantially from PERFECT (ie. a daily timestep), it does not use the advanced features of APSIM's apswim and surface modules (eg. hydrographs or peak runoff rate). SWIM users should be aware that peak runoff rate is not used in calculation of soil erosion at this time. Surface users should be aware that surface roughness factors do not enter erosion or runoff. The calculation of cover used in the soil loss equation should be the same cover as used in runoff prediction. When soilwat provides water balance, this cover is exported to the system (and thus erosion) as total_cover. However, SWIM does not provide this variable. If the surface module is active, it will provide a variable surf_cover, which is the combined crop and residue covers on the soil surface. To use this cover as the cover term in the soil loss equation, add the following to the manager's rules:
[xxx.manager.init]
total_cover = 0.0
[xxx.manager.start_of_day] total_cover = surface.surf_cover
To use erosion with apswim, add the following rules:
[xxx.manager.init] total_cover = 0.0
[xxx.manager.start_of_day] total_cover = 1.0 (1.0 - crop1.cover_tot) * (1.0 crop2.cover_tot) * * (1.0 - residue2.residue_cover)
Procedures:
The module follows these steps at initialisation:

All variables are set to zero. The parameter file is read, if necessary, ls factor is calculated for the freebairn model. The static parameters are written to the summary file.
During daily processing, the following procedures occur:

The daily state variables are reset. Today's inputs are requested from the system. Soil loss is calculated as a function of cover and runoff. If there is soil loss, the profile is changed and sent back to its owner. The new depth to bedrock is calculated. Control returns to the system.
System interface names Parameter file:
Name model profile_reduction profile_layer_merge Either 'rose' or 'freebairn' Either 'on' or 'off'
Description
Fraction of original size below which the lowest layer is merged into the layer above (0-1)
Name minimum_depth slope slope_length bed_depth cover_extra (optional)
Description If the profile erodes to this depth, the simulation is stopped (mm) Slope of plot (%) length of plot (m) depth to bedrock (mm) fudge factor added to total_cover (-1.0,1.0)
Freebairn specific parameters
p_factor Supporting practise factor (unitless) Either k_factor Soil erodibility factor (t/ha/EI 30 ) or k_factor_bed Soil erodibility factor for bed load (t/ha/EI 30 ) k_factor_susp Soil erodibility factor for suspended load (t/ha/EI 30 )
Rose specific parameters
Either entrain_eff Efficiency of entrainment - bare surface () or entrain_eff _bed Efficiency of entrainment - bare surface - bed load () entrain_eff _susp Efficiency of entrainment - bare surface - suspended load () Either eros_rose_b2 ?? or eros_rose_b2_bed ?? eros_rose_b2_susp ??
Inputs from other modules on a daily timestep:
day year runoff daily runoff (mm) total_cover combined crop and residue cover (0 - 1) bd(mxlayr) moist bulk density of soil (g/cm^3) dlayer(mxlayr) thickness of soil layer i (mm)
Outputs to other modules as requested:
soil_loss todays soil loss (t/ha) soil_loss_bed todays soil loss in bedload (t/ha) soil_loss_susp todays soil loss in suspension (t/ha) soil_loss_mm todays soil loss from the topmost profile layer (mm) sed_conc todays sediment concentration (g/l) sed_conc_bed todays sediment concentration in bedload (g/l) sed_conc_susp todays sediment concentration in suspended load (g/l)
bed_depth todays depth to bedrock (mm) erosion_cover todays cover used to drive soil loss equations (0 - 1)
Resets to other modules:
dlt_dlayr() thickness of soil layer i (mm)

Typical, sample parameters
Dataset slope Slope length P factor soil erodibility K Lambda_bare b2 % M (t/ha/EI30) || Greenmount 6.5 60 1.0 0.38 (1) 0.77 (2) 15 (3) Greenwood 4.5 37 1.0 0.38 (1) 0.70 (3) 15 (3)
[gmtf.erosion.parameters] model = freebairn (1) slope = 6.5 (%) slope_length = 60.0 (m) bed_depth = 1500. (mm) profile_reduction = off profile_layer_merge = 0.05 () minimum_depth = 100.0 (mm) k_factor = 0.38 () p_factor = 1.0 () [gmtr.erosion.parameters] model = rose (2) slope = 6.5 (%) slope_length = 60.0 (m) bed_depth = 1500. (mm) profile_reduction = off profile_layer_merge = 0.05 () minimum_depth = 100.0(mm) entrain_eff = 0.77 ()
eros_rose_b2 = 0.15 () [gwd.erosion.parameters] model = rose (3) slope = 4.5 (%) slope_length = 37.0 (m) bed_depth = 1500. (mm) profile_reduction = off profile_layer_merge = 0.05 () minimum_depth = 100.0(mm) entrain_eff = 0.7 () eros_rose_b2 = 0.15 ()
(1) Freebairn, Silburn & Loch (1989). Aust.J.Soil Res. 27: 199-211 (2) Silburn & Loch (1992) 5th Aust. Soil con. Conf. (3) Rose (1985) Adv. in Soil Science Vol 2
Known bugs and defects

Cover isn't resolved. Currently, erosion gets its cover from total_cover, which soilwat calculates as the total crop and residue cover. This should be runoff_cover, which soilwat doesnt export at the moment.
Bibliography
Carroll, C., Rose, C.W. and Crawford, S.J. (1986). GUESS - Theory Manual. School of Australian Environmental Studies, Griffith University , Queensland , Freebairn, D.F. and Wockner, G.H. (1986). A study of soil erosion on Vertisols of the Eastern Darling Downs, Australian Journal of Soil Research , 19 , 133-46 Littleboy, M., Silburn, D.M., Freebairn, D.M., Woodruff, D.R., and Hammer, G.L. (1989) PERFECT - A computer simulation model of Productivity Erosion Runoff Functions to Evaluate Conservation Techniques. QDPI, Brisbane. Rose, C.W. (1985). Developments in soil erosion and deposition models. Advances in Soil Science , Volume 2 , 1-63. Wischmeier, W.H. and Smith, D.D. (1978). Predicting rainfall erosion losses, a guide to conservation planning. Agricultural Handbook number 537 , USDA, 58pp.
Programmers notes
The calculation of soil loss ends up in two variables, soil_loss_bed and soil_loss_susp. When the user describes a single soil loss equation, the result is left in soil_loss_bed, with soil_loss_susp left at 0. All reporting is done as the sum of these two variables.
Related Material
Nutrient reduction:
Nutrient reduction is represented by "moving" the soil layers downwards through the soil profile (the same as moving the nutrient pools of the soil layers upwards through the soil). Layers take on the nutrient characteristics of the layer below in proportion to the depth increment gained from that layer. If there is no "bedrock", all layers would eventually all end up with the nutrient properties of the subsoil (bottom layer). If the accumulated depth loss due to erosion exceeds the depth between the bottom of the profile and the depth to bedrock (and profile reduction is on), the bottom layer does not contain nutrients from below and its nutrient content will diminish (as nutrients are exported upwards through the soil) The algorithm for "top down" removal is: 1. . determine the loss for each layer. For the top layer, this is given by: conc_kg_kg = variable(1)/(1000.0*bd(1)*dlayr(1)*10.0) loss_kg_ha = soil_loss * 1000.0* enr * conc_kg_kg where; conc_kg_kg = kg of nutrient per kg of soil (kg/kg) variable = content of particular nutrient (kg/ha), bd = bulk density in (g/cm^3) dlayr = depth of layer in (mm) soil_loss = soil loss (t/ha) enr = enrichment ratio. "enr" is calculated from enr = enr_a_coeff * (1000.0 * soil_loss)**(-1.0 * enr_b_coeff) and is bounded to (1.0 < enr < enr_a_coeff): enr = amin1(enr_a_coeff, enr) enr = amax1(enr, 1.0) For the remaining layers, the loss from each layer is that which moved into the layer above; layer_loss = variable(i) * layer_divide(dlt_depth_mm(i), dlayr(i)) where i is the index of the layer we are working on, and layer_divide(a,b) bounds the result of (a/b) to 0.0 -> 1.0. This prevents taking away more than is present in the layer. "dlt_depth_mm(i)" is an array of deltas describing the change in each profile depth for the given amount of soil loss, given by: dlt_depth_mm(i) = (100.0*soil_loss) / (1000.0*bd(i)) The bulk density for each layer is used to maintain mass balance of soil movement up through the (constant) soil layer thicknesses. The gain to each layer is found in a similar manner, ie, the fraction of the layer below that moves into this layer: layer_gain = variable(i+1) * layer_divide(dlt_depth_mm(i+1), dlayr(i+1)) Obviously, the lowest layer cannot use this formula, as there is no layer beneath, and we have to cater for bedrock. The procedure is to assume that the lowest layer gains a fraction of itself, so long as it is not resting on bedrock: layer_gain = variable(i) * layer_divide(dlt_depth_mm(i), dlayr(i))
! check we're not going into bedrock if (suml(dlayr, mxlayr) + dlt_depth_mm(n_layrs) .gt. bed_depth .and. profile_reduction .eq. on ) then layer_gain = 0.0 At this point, we find the new value of the variable for this layer in the new profile: variable(i) = variable(i) + layer_gain - layer_loss Two more steps follow,:2. . If profile reduction is on, check to see if the bottom layer is too thin, and merge it into the next layer up if so. 3. . Perform a mass balance check: \Sum{yesterdays variable} + loss from layer 1 - gain to lowest layer = \Sum{Todays variable} This procedure is repeated for all the nitrogen / carbon variables: snh4(mxlayr) inert_c(mxlayr) biom_c(mxlayr) biom_n(mxlayr) hum_c(mxlayr) hum_n(mxlayr) fom_n(mxlayr) fpool1(mxlayr) fpool2(mxlayr) fpool3(mxlayr) The total amounts of N and C lost on eroded soil is calculated by summing losses from the relevant N and C pools: n_loss_in_sed = snh4_loss + biom_n_loss + hum_n_loss + fom_n_loss c_loss_in_sed = biom_c_loss + hum_c_loss + fpool1_loss + fpool2_loss + fpool3_loss ---4. Finally, reducing the profile layer depth (dlayr) takes place following a similar method to before; by reducing from the bottom until the profile rests against bedrock: tot_depth = suml(dlayr, n_layrs) + dlt_depth_mm(n_layrs) if (tot_depth .gt. bed_depth ) then overrun = tot_depth - bed_depth do 2000 i = n_layrs, 1, -1 if (overrun .gt. 0.0) then if(overrun .le. dlayr(i)) then dlayr(i) = dlayr(i) - overrun overrun = 0.0 else overrun = overrun - dlayr(i) dlayr(i) = 0.0
endif endif 2000 continue endif and the lowest profile layer is merged if necessary. The threshold for merging layers is specified in the parameter file as a proportion of the original layer, so after a merge, this threshold must be recalculated as a proportion of the next upper layer.
Introduction
The fababean module was developed by Michael Robertson and Jill Turpin, with contributions from Bill Bellotti, Ian Rose, Andrew Moore, and KM Siddique. The module is described in the paper by Turpin et al. (2003). The reader is referred to the science document for the plant module for a comprehensive description of the processes simulated by APSIM-Fababean. This document outlines some fababean-specific issues that are not covered by the plant science document.
Notable features of APSIM-FABABEAN

The Module simulates small-seeded types of cultivars The phenology of fababean cultivars is responsive to temperature and photoperiod, but not vernalisation. There is an effect of photoperiod on post-flowering development. Model performance on days to flowering was reported by Turpin et al. (2003) and is repeated in the graph below (Figure 1). The module does not simulate production from second and further flushes of flowers and pods. Under well-watered conditions, fababean may have a low harvest index due to continued vegetative growth at the expense of reproductive yield. The model does not currently simulate this phenomenon. APSIM-Fababean is not phosphorus-responsive, this is currently under development. Crop growth is not sensitive to waterlogging.

There is one crop class. There are 6 cultivars able to be simulated: Amethyst, CPI56288, Dooen, Tyson, CV244-1, CPI56566. Cultivars differ in terms of biomass partitioning to grain and phenology. If usrs wish to use more modern cultivars they should contact Jeremy Whish at APSRU for advice.
Figure 1: Observed and simulated days from sowing to flowering and days to maturity for fababean.
Figure 2: Performance of the fababean module (observed versus simulated grain yield in g/m2) against test datasets reported by Turpin et al. (2003).
Validation
APSIM-Fababean has received testing across the Australian wheat belt, with factors such as cultivars, sowing date, irrigation, soil type, row spacing varying. Some testing has occurred in WA as well as Victoria, Queensland and northern NSW. The accompanying figure 2 demonstrates the performance of the module against Australian datasets.
IN Which environments THIS MODULE should be used with confidence?

APSIM-Fababean can be used with most confidence in the semi-arid sub-tropics of northern Australia, the Western Australian wheat belt, and the dryland environments of the Mediterranean-type regions. The module has received limited testing under irrigation on black cracking clay soils of northern NSW.
References
Turpin JE, Robertson MJ, Haire C, Bellotti WD, Moore AD, Rose I (2003) Simulating fababean development, growth, and yield in Australia. Australian Journal of Agricultural Research 54, 39-52. Robertson, M.J., Carberry, P.S., Huth, N.I., Turpin, J.E., Probert, M.E., Poulton, P.L., Bell, M., Wright, G.C., Yeates, S.J., and Brinsmead, R.B. 2002. Simulation of growth and development of diverse legume species in APSIM, Australian Journal of Agricultural Research 53:429-446.
Description
Within APSIM, the problem of managing farms is a different problem to managing its traditional domain of paddocks. The questions in 'farm' management are of a different order; typically addressing resource allocation issues ahead of operational issues. The APSFARM project is addressing these issues by developing complex tools devoted to managing diverse lists of rules, instead of the current practise of rules embedded in if/then/else logic. These rules, and the data structures that implement them are under active development.
Representation
The farming system as a whole is represented as a directed graph: a paddock's state is represented by a node on this graph, and the system moves between states by following vertices between each node. These vertices have rules (or conditions) that allow the system to change state from one to the next. Each day the system attempts to move from one state to another by finding all paths leading away from the current state, and evaluating the rules for each path. The path with the highest (nonzero) score To move from "sorghum" to "fallow" is simple - it requires that the crop was harvested on that day. However to move from "fallow" to "sorghum" may require several rules to be satisfied, for example: Date within a range Soil water criteria met More than 30 days since last harvest No more than 3 sorghum crops in a row No more than 70% of farm planted to a sorghum crop
Operation
The dynamic nature of these rule types requires a flexible method of interrogating simulations. At this initial stage, a standalone application to display log files is being used, after consultation with users another application may be
developed.
The APSIM fertiliser module allows the user to specify the application of solid fertiliser to an APSIM system using a schedule spanning multiple years. There is also total flexibility for user specification of fertiliser components.
Fertiliser Module Outputs

The Fertiliser module has one output, fertiliser, which is the total amount of fertiliser added on any day (kg/ha).
Michael Robertson 4 th May 2004

Working science document for the fieldpea module
Introductory notes

The fieldpea module is currently under development and has only received testing in South Australia over a range of sowing dates in two seasons under dryland conditions Cultivars currently simulated in order of earliest to latest flowering are: Parvie, Excel, Parafield, Kaspa, Mutka
Green area of stems and tendrils is not explicitly simulated but included as part of the leaf area index There is no explicit differentiation between semi-leafless and conventional types Users are invited to provide feedback on module performance to the convenor, Michael Robertson (Michael.Robertson@csiro.au).
Science notes
The parameters are for the fieldpea module are those for chickpea, unless specified below. Refer to the PLANT module science document for detail on the definition of parameters: Shoot_rate 4 o Cdays per mm Cardinal temperatures for thermal time. 3, 28, 40 o C from Olivier and Annandate (1998) Leaf appearance rates 40 o Cd per leaf: from Olivier and Annandate (1998) Branching parameters complete guess 2.5 leaves per node at 4 nodes onwards Rue of 1.1 g/MJ. From Jamieson, Wilson and Hanson (1984) Node number correction = 1.2 Leaf size vs node number use fababean numbers SLA_max = 30000 mm 2 /g SLA_min = 20000 mm 2 /g Temperature and root advance cardinal temps of 0, 20, 32 o C Initial tpla =1000 mm 2 per plant Transpiration efficiency 0.004 Pa Rate of HI increase (all cultivars) 0.025 per day (Lecoeur and Sinclair 2001)
Relevant references
Jamieson PD, Wilson DR and Hanson R 1984. Analysis of response of field peas to irrigation and sowing date. 2. Models of growth and water use. Proceedings of the NZ Society of Agronomy 1984 75-81. Lecoeur J and Sinclair TR 2001. Harvest index increase during seed growth of field pea. European Journal of Agronomy 14: 173-180. Olivier FC and Annandale JG 1998. Thermal time requirements for the development of green pea (Pisum sativum L.). Field Crops Research 56: 301-307.
Module performance
Figures below show module performance for one cultivar (Parafield) at Roseworthy in South Australia over two seasons. Prediction of flowering is for 5 cultivars (Parv, Excel, Parafield, Kaspa, Mutka) over those same two seasons. Roseworthy 2003 sown 10 th June
Roseworthy 2002 sown 17 th May
Roseworthy 2002 sown 6 th June
Phenology
Agreement for 5 cultivars over 4 sowing dates in South Australia Squares are observed and crosses are simulated
Introduction
The growth module is a simplified plant growth module developed for simulating pasture and forestry systems module. Whilst simplified in many respects, the major processes relating to growth, resource (water and nitrogen) use and responses to climate and resource supply, partitioning of photosynthate and links to the wider carbon and nitrogen balance are captured within the module. This document summarises the functional components of the module.
Notable features of APSIM-Growth

A flexible method of assimilate partitioning is that is able to maintain structural (stem, branch, large roots, etc) and growth (foliage and fine root) pools. A whole plant light use efficiency is used. Soil water demand is provided by the micromet module using a Penman-Monteith formulation. Germination processes are not modelled, swards or plantations are established. Responses to nitrogen supply can be modelled in a simplistic fashion by a single site index' parameter or via a full nitrogen balance and cycle. No phenology' is modelled, although, changes in partitioning rules for photosynthate can change with plant development (i.e. size).
Example Manager Syntax

Module_name establish plants = ppp (/ha), init_section = ssssss This statement will establish the sward/plantation where Module_name is the name of the instance of the growth module within the simulation (e.g. Bambatsi or Egrandis), ppp is the plant population and ssssss is the name of the data section used to initialise the new population of plants. Module_name cut foliage_remove_fr = 0.7, adm_remove_fr = 0.5 This statement will remove 70% of leaves and 50% of stem (adm = above-ground dry matter, refers to structural pools). Biomass is removed from the system. Module_name thin plants_fraction = 0.1, biomass_fraction = 0.05 This statement will remove 10% of population and but only 5% of all above-ground biomass pools (i.e. thinning out of smaller than average sized individuals). Biomass is removed from the system.
Module_name kill
This statement will kill the model, sending any remaining biomass to the residue module.
Model Components
The APSIM Growth module is based on the lessons learned from other APSIM crop (Keating et al, 2003, Robertson et al, 2002, Wang et al, 2002) and forest (Huth et al, 2001, 2002) productivity models as well as other pasture models such as GRASP (McKeon et al). A range of APSIM modules provide daily data for meteorological conditions and uptake of water and nitrogen and so that time step is used for all growth calculations.
The APSIM Growth module contains two major classes of biomass pools: growth and structural pools. Growth pools are responsible for most growth processes (i.e. leaves intercepting radiation) and water uptake (fine roots). Structural pools are provide sinks for assimilate and nutrients and are used to describe plant properties such as plant height. Structural pools are either above or below ground. The number of structural pools for a given plant model can be user-defined but a standard configuration may only contain stem above ground and a tap root below ground. Growth is calculated as, Where ?G is daily growth, R int is daily intercepted solar radiation (MJ/m 2 ), e is the light use efficiency (g/MJ) and F t , F n , F vpd and F w are growth modifiers for temperature, nitrogen, vapour pressure deficit and soil water supply respectively. R int is calculated using crown cover, leaf area, and an assumption of exponential light extinction. F t and F vpd are based on average daily temperature and vapour pressure deficit. Fn is based on leaf nitrogen concentration. Fw is calculated as the ratio of soil water demand and supply.
Partitioning of daily Growth

Unlike other APSIM modules, e is a whole plant (above and below ground) light use efficiency. As a result, the daily growh has to be partitioned into foliage, roots, above-ground structure and below-ground structure. The rules for partitioning are described via two main mechanisms: variation in root:shoot ratio and structural fraction of above-ground growth. Stresses due to deficiency in below ground resources such as water and nutrients is often found to increase the root:shoot ratio. In this module the user can define how increasing severity of stress can increase the proportion of daily growth going into below-ground growth. This extra rooting growth can then assist the plant in accessing scarce resources, depending on the way in which APSIM is configured (e.g. use of the APSIM-SWIM water balance where root length density impacts on root water uptake). Currently, soil water supply, soil water content and plant nitrogen status can all be used to alter the root:shoot ratio of the plants. The partitioning of above-ground growth changes throughout the growth cycle of plants. The result is the often consistent allometry observed in plants. The Growth module will allow the user to specify how the fraction of above-ground growth going into structure changes with mean plant size. For example, small plants may put proportionally more photosynthate into foliage than larger plants relfecting their need to establish a canopy as against compete with other plants via increased structural/height growth. On a daily basis, the above two partitioning rules are evaluated. The model will then backcalculate the partitioning into leaf, roots and structure such that root:shoot ratios and growth:structure ratio are conserved.. Leaf Area growth is calculated from leaf growth and a specific leaf area. Similarly, root length calculations utilise a specific root length, with root length partitioned spatially according to supplies and demands for both water and nitrogen.
Senescence and Detachment of biomass

Each biomass pool undergoes continual senescence and the resultant senesced material is continually detached from the plant. Senescence of growth pools (foliage and roots) is calculated using simple first order decay.
The user specifies a mean residence time ( in days) which is inverted within the model to provide a decay coefficient. Senescence of foliage is often observed to also show a certain seasonality. This is achieved within the model via use of the daily temperature stress factor and the annual sinusoidal temperature curve such that the annual average mean residence time will equate to that provided by the user but that the daily value will vary around that throughout the year. Other processes can be responsible for leaf death. Senescence of foliage can also be triggered by low temperatures (i.e. frosting). In this case, low nightly minimum temperatures can specified to fractionally decrease green leaf area. Alternatively, mutual shading of leaves in dense canopies can be specified to decrease leaf area. If total leaf senescence occurs, a small initial leaf area is maintained on the plant in order to initiate further regrowth when conditions are favourable. Senescence of structural pools is said to follow the patterns in the growth pools. This is achieved by relating the senescence rate of above-ground pools to the senescence rate of foliage and by relating the senescence rate of below-ground pools to the senescence rate of roots. For example, a 1% loss of green leaf may result in a 0.5% loss in live stem mass. All senesced pools (growth or structural, above or below ground) detach via a first order decay function. Above-ground biomass is added to the surface residues. Below-ground biomass is added to soil organic matter.
Plant water use

Plant water demand is calculated using the Micromet module which is developed from the work of Snow et al. 1999 and Kelliher et al. 1995, while plant water supply is calculated using one of the two soil water modules available in APSIM. Please refer to these modules for further information. Plant water uptake is calculated within the Growth module using the assumption that uptake of water from soil follows a simple first order decay with soil drying.
Plant nitrogen
Plant nitrogen demand is based upon the size of the biomass pools and a target nitrogen concentration for each pool. When nitrogen supply is insufficient to meet all this demand, nitrogen is partitioned according to the sink strength in each pool. If this results in a decrease in leaf nitrogen concentration the plant may experience nitrogen stress. In extreme nutritional conditions, or in cases where fertility information is unknown, it is possible to constrain the Growth module via use of a site index. In this case, Fn is maintained at a constant value.
Uptake of nitrogen
Nitrate-nitrogen can be taken up by the plant via the uptake of water from the soil. If this is insufficient to meet daily demand a set fraction of the unmet demand can be taken up via active uptake processes. This active process is further discounted when soil water content is low.
Output Variables
Variable Name adm_dead(num_above*) adm_green(num_above) adm_sen(num_above) Age an_green(num_above) bdm_dead(num_below**) bdm_green(num_below) bdm_sen(num_below) Biomass bn_green(num_below) cover or cover_green cover_tot crop_type dlt_adm_green(num_above) dlt_an_green(num_above) dlt_bn_green(num_below) dlt_dm dlt_foliage_mass dlt_foliage_mass_detached dlt_foliage_mass_sen dlt_foliage_n dlt_foliage_n_detached dlt_lai_sen dlt_lai_sen_age dlt_lai_sen_frost dlt_lai_sen_light dlt_no3(num_layers***) Units kg DM /ha kg DM /ha kg DM /ha years kg DM /ha kg DM /ha kg DM /ha kg DM /ha kg DM /ha kg N /ha 0-1 0-1 Text kg DM /ha kg N /ha kg N /ha kg DM /ha kg DM /ha kg DM /ha kg DM /ha kg N /ha kg N /ha kg DM /ha kg DM /ha kg DM /ha kg DM /ha kg N Description Dry matter in each of the above ground part of dead plants Dry matter in each of the above ground part of live plants Senesced dry matter in each of the above ground part of live plants Age of the plants N in each of the green above ground parts of live plants Dry matter in each of the below ground parts of dead plants Green matter in each of the below ground parts of live plants Senesced matter in each of the below ground parts of live plants Total above ground dry matter N in each of the green below ground parts of live plants Fractional ground cover from green material Fractional ground cover from all material Crop type for looking up properties Change in adm_green today due to photosynthesis Change in an_green today due to N uptake from soil Change in bn_green today due to N uptake from soil Change in total dry matter today Change in foliage_mass today due to photosynthesis Change in foliage_mass_detached today from senesced foliage Change in foliage_mass_sen today due to senescence of live foliage Change in foliage_n today due to N uptake from soil Change in foliage_n today from senesced foliage. Change in lai_sen today due to senescence of live foliage Change in lai_sen today due to age driven senescence of live foliage Change in lai_sen today due to frosting of live foliage Change in lai_sen today due to shading of live foliage Change in no3 today (i.e. uptake of
Variable Name dlt_root_mass dlt_root_mass_sen dlt_root_n dlt_root_n_sen Ep Fage
Units /ha kg DM /ha kg DM /ha kg N /ha kg N /ha Mm 0-1
Fasw Fdl Ff Ffasw Fn foliage_mass foliage_n Frgr Ft Fvpd Fw Height Lai n_demand no3_demand plant_status Plants rld (num_layers) rlv(num_layers) rlv_Growth(num_layers) root_depth root_length(num_layers) root_mass
0-1 0-1 0-1 0-1 0-1 kg DM /ha kg N /ha 0-1 0-1 0-1 0-1 Mm m/m2 kg N /ha kg N /ha Text #/ha mm/mm3 mm/mm3 cm/cm3 mm mm/mm2 kg DM /ha
Description NO3 from each layer by the plant) Change in root_mass today due to photosynthesis Change in root_mass_sen today due to senescence of live fine roots Change in root_n today due to uptake of N from soil. Change in root_n_sen today due to senescence of live fine roots Actual water uptake summed across all soil layers Stress factor for age generic factor used to capture loss of productivity as plant stands mature. Fraction of plant available soil water Stress factor for daylength used to capture increased partitioning to roots prior to winter. Stress factor for frost Stress factor for fasw used to capture increased partitioning to roots in dry conditions.???? Stress factor for nitrogen Mass of foliage N in the foliage Relative growth rate factor for photosynthesis = min(Ft, Fn, Fvpd, Fage) Stress factor for temperature Stress factor for vapour pressure deficit Stress factor for water supply (= supply/demand) Height of the plants Leaf area index Nitrogen demand Nitrate Nitrogen demand in, out, dead etc Number of plants per ha Root length density Root length density corrected for aeration stress Same as rlv but with different units Depth of the root system Root length for each layer (area basis) Mass of live fine roots
Variable Name root_n rue_actual SLA_senescing Slai sw_demand total_n
Units kg N /ha g/MJ mm/g m/m2 Mm kg N /ha
Description N in the live fine root system Radiation use efficiency = RUE * Frgr Specific leaf area of the senescing leaves Senesced leaf area index Soil water demand Total in the plants, above and below
References
Huth, N.I., Snow, V.O. and Keating, B.A. 2001. Integrating a forest modelling capability into an Agric. production systems modelling environment - current applications and future possibilities. Proceedings of the International Congress on Modelling and Simulation, Aust. National University , Dec. 2001. pp. 1895-1900. N. I. Huth, P. S. Carberry, P. L. Poulton, L. E. Brennan, and Brian A. Keating. "A framework for simulation of agroforestry options for the low rainfall areas of Australia using APSIM." European Journal of Agronomy 18 (2002): 171-185. Keating, Brian A., P. S. Carberry, G. L. Hammer, Mervyn E. Probert, M. J. Robertson, D. Holzworth, N. I. Huth, J. N. G. Hargreaves, H. Meinke, Z. Hochman, G. McLean, K. Verburg, V. O. Snow, J. P. Dimes, M. Silburn, E. Wang, Stuart Brown, K. L. Bristow, S. Asseng, S. C. Chapman, R. L. McCown, D. M. Freebairn, and C. J. Smith. "An overview of APSIM, a model designed for farming systems simulation." European Journal of Agronomy 18 (2002): 267-288. Kelliher, F. M., R. Leuning, M. R. Raupach, and E. D. Schulze. 1995. Maximum conductances for evaporation from global vegetation types. Agricultural and Forest Meteorology 73: 1-16. Robertson, M. J., Carberry, P. S., Huth, N. I., Turpin, J. E., Probert, M. E., Poulton, P. L., Bell, M., Wright, G. C., Yeates, S. J. and Brinsmead, R.B. 2002. Simulation of growth and development of diverse legume species in APSIM. Aust. J. Agric. Res. 53, 429-446. Paydar, Z., Huth N. I., and Snow V. O. 2005. Modelling irrigated Eucalyptus for salinity control on shallow watertables. Australian Journal of Soil Research 43: 587-97. Snow, V. O., W. J. Bond, B. J. Myers, S. Theiveyanathan , C. J. Smith, and R. G. Benyon. 1999. Modelling the water balance of effluent-irrigated trees. Agricultural Water Management 39: 47-67. Wang, E., Robertson, M. J., Hammer, G. L., Carberry, P. S., Holzworth, D. P., Meinke, H., Chapman, S. C., Hargreaves, J. N. G., Huth, N. I., and McLean, G. Development of a generic crop module template in the cropping system model APSIM. European Journal of Agronomy. 18 (2002):121-140.
Introduction
The horsegram module was developed by Dr R. Selvaraju, building largely on the mungbean module developed by Peter Carberry and Michael Robertson . The reader is referred to the science document for the plant module for a comprehensive description of the processes simulated by APSIM-horsegram. This document outlines some horsegram-specific issues that are not covered by the plant science document. The horsegram module simulates horsegram (black gram or green gram). Notable features of APSIM-horsegram The phenology of horsegram cultivars are photoperiod
insensitive. The module does not simulate grain weathering, although some users have simulated the number of rainfall events during pod-fill (using the manager module) and used this as a surrogate of weathering damage. The module does not simulate production from second and further flushes of flowers and pods. APSIM-horsegram is not phosphorus-responsive, this is currently under development. Crop growth is not sensitive to waterlogging.
Cultivars
There are 2 cultivars able to be simulated: CO1 and Paiyur. Cultivars differ in terms of biomass partitioning to grain and phenology.
Validation
APSIM-horsegram has received testing in Tamil Nadu, with factors such as cultivars, sowing date, irrigation, soil type, row spacing varying.
In Which Environments Should This Module Be Used With Confidence?

APSIM-horsegram can be used with a high degree of confidence in South India.
References
Robertson, M.J., Carberry, P.S., Huth, N.I., Turpin, J.E., Probert, M.E., Poulton, P.L., Bell, M., Wright, G.C., Yeates, S.J., and Brinsmead, R.B. 2002. Simulation of growth and development of diverse legume species in APSIM, Australian Journal of Agricultural Research 53:429-446. Robertson, M. J.; Carberry, P. S., and Lucy. M. 2000 Evaluation of cropping options using a participatory approach with on-farm monitoring and simulation: a case study of spring-sown mungbeans. Australian Journal of Agricultural Research. 51:1-12.
Introduction
Most simulation require data, other than module parameters to be available to all modules. This service is provided by the APSIM input module. The input module is an instantiable module. This means that APSIM can run zero or more instances of the input module. The instance name met is special. If the input module is running as met , it will read its data from a single section called weather , otherwise it will read its data from a single section called data. There are two types of data that the input module can be used to read, temporal data (eg. weather data), and data that is constant for a given simulation . This is why there are potentially two parts to the input section, an optional constants section followed by an optional temporal data section. Here is an example control section:
apsim.sample_input Module=clock input.par sample Module=report input.par sample Module=input(met) DALBY.MET test Module=manager input.par sample Module=input (input1) input.par test Module=input (sparse) sparse.par test
Here is a corresponding input parameter section. The variables alpha, beta and lumpia are defined in the constants part of the section, while year, day, rug and paxt are defined in the temporal data
section:
test.input1.data alpha = one two three beta = one two three four five six seven Lumpia = -7.11 year day rug(1) rug(2) paxt () () (MJ/m2) (MJ/m2) (oC) 1988 1 20 21 33.0 1988 2 23 24 33.8 1988 3 23 24 32.5 1988 4 19 20 30.8 1988 5 17 18 28.2 1988 6 22 23 29.0 1988 7 22 23 28.4 1988 8 25 26 31.2 1988 9 26 27 33.6 1988 10 25 26 34.4 1988 11 22 23 31.6
Constants part
Data in the constants section must be in the format apsim_name = values .... Where apsim_name is the name of the APSIM variables and values is one value in the case of scalar data and one to 100 values separated by spaces in the case of array data. There is no limit to the number of variables that may be defined here. Each value can be at most 50 characters long, with the added restriction that a given line may be at most 2000 characters long.
Temporal data part

Data in the temporal section is in tabular format, very similar to the output of the report module. This is deliberate, so that the input module can potentially use output from the report module.
Headings line
First there must be a line of space separated headings. In the case of scalar data, a heading is the APSIM name of the variable. In the case of array data is the heading is the APSIM name of the variable immediately followed by the array index in parenthesis (no spaces allowed). For a given APSIM array variable, the array elements must appear in order beginning with element 1.
There may be up to 100 headings, each of which may be up to 35 characters long, with the added restriction that a given line may be at most 2000 characters long. The APSIM variable year must be present in the temporal data table. Either the APSIM variable day (meaning day of year) must be present or the APSIM variables month and day_of_moth must be present.
Units line
Then the units line must follow - a space separated units string for each heading. In the case of array data, the units string belonging to elements of the same APSIM variable must be identical. Each units string may be up to 35 characters long, with the added restriction that a given line may be at most 2000 characters long.
Data lines
Then a line for each day must follow with the space separated data elements corresponding to each of the headings in order. Each units string may be up to 50 characters long, with the added restriction that a given line may be at most 2000 characters long. Normally, each day for the APSIM simulation must be present in order.
Sparse Data
If the constants part of the section has a scalar APSIM variable allow_sparse_data is present, and its value it true, then sparse data is permitted, and each day of the simulation need not be present. An attempt by other modules to get data on a day with no data will normally get the zero elements in its numvals field. Defaults for sparse data can be set in the constants section. In this case, if data is present in the temporal section on that day, the values specified in the temporal section will be returned. Otherwise the data specified in the constants section will be returned.
Met calculated data

If the input module is instantiated as met , then some calculated variables are available: The real scalar day_length is calculated from lattitude and made avalable.
Examples
Example input data can be found in the samples directory of the input module directory.
Bugs
No more than one input module can read sections containing a temporal data part from a given parameter file during a given simulation. A temporal data section cannot be read from a control file.
The APSIM irrigate module allows the user to:-

specify irrigation schedules spanning multiple years configure an automatic irrigation schedule calculated on soil moisture specify both schedules to be turned on or off at any time in a simulation apply solutes in irrigation water for redistribution via the water balance module.
Resetting Schedules
Manual and automatic schedules can be enabled and disabled within a simulation via the message system. The syntax of a standard manager message to turn off the manual irrigation schedule would
be as follows:
irrigation set manual_irrigation = off
Other related data is unaffected by this switch resetting and so, for example, the automatic irrigation scheduling can be set on and off for set windows in time using a pair of if statements in the manager file. Parameters for the automatic irrigation calculations can be reset similarly:
irrigation set crit_fr_asw = 0.9 (0-1) irrigation set asw_depth = 150 (mm)
Working with Irrigation Allocation Budgets

The following example shows how the allocation mechanisms are utilized in the APSIM Irrigate module. Note that only automatic irrigation scheduling and remote scheduling (eg via the manager or operations modules) is taken into account. The mechanism cannot be used in conjunction with a manual irrigation schedule. The example shows an annual allocation set on the first of July each year, which is applied using automatic irrigation scheduling.
user_data_group.irrigate .parameters automatic_irrigation = on crit_fr_asw = 0.66 asw_depth = 600 (on/off) ! switch schedule on or off (0-1) ! critical fraction of ! available soil water ! to trigger irrigation (mm) ! depth for available ! soil water calculations
user_data_group.manager .start_of_day if today = date('1_jul') then irrigation set allocation = 1000 (mm) endif
Working with Irrigation Efficiency

The following example shows how the irrigation efficiency is utilized in the APSIM Irrigate module. The example shows an irrigation_efficiency setting of 75%. This means that only 75% of the irrigation is actually being applied due to approximated losses due to evaporation, wind loss or runoff.
user_data_group.manager .start_of_day
irrigation.irrigation_efficiency = 0.75 if today = date('1_jul') then irrigation apply amount = 50 endif
Using Default Solute Concentrations

Default solute concentrations can be specified by a new "getable" parameter(s) called 'default_XXX_conc' , where XXX is the solute name. The units are ppm, and the parameter(s) is read from the parameter file. Note that solutes are not registered in the system simply by defining default concentrations. If you want to track these solutes through the soil, for example, they must be registered elsewhere to trigger a New_Solute Event, for example in the "solute_names = " line in SOLUTE, or by a number of other modules. When an irrigation is triggered (from MANAGER or from the parameter file) and no specific information on solutes in the irrigation is supplied, then the default solute concentrations will be used if they are supplied. Any specific information however will over-ride the defaults. If specific information is provided, then details of all the solutes must be given, because no defaults will be used. A parameter file example is given below:
sample.irrigate.parameters default_cl_conc = 100.0 default_br_conc = 50.0
sample.solute.parameters solute_names = cl br cl = 0 0 0 0 0 0 0 (kg/ha) br = 0 0 0 0 0 0 0 (kg/ha)
The reportable variable is "irrigation_XXX" where XXX is the solute name. The units are kg/ha.
Using APSIM Irrigate with APSIM WaterStorage

There is an option to use APSIM Irrigate in conjunction with the APSIM WaterStorage module. Please also read the documentation for APSIM WaterStorage. APSIM Irrigate works on a mm' basis, whereas APSIM WaterStorage works on real volumes (Ml). Hence, when an irrigation application is specified in mm, an area of application' must be provided in order to calculate the required volume of water from the specified source instance of WaterStorage. As mentioned previously, whenever WaterStorage is used in a simulation for supply of irrigation
water, a variable called crop_area' (ha) must be specified in the manager logic. Irrigations using water from WaterStorage can only be initiated by using the irrigation apply' action in manager. A new optional argument called source' is added to the apply' command line to trigger the use of water from WaterStorage. The required syntax is as follows:
sample.manager.start_of_day if day = 10 then irrigation apply amount=10 (mm), source = dam bore dam2 () endif
The argument source' specifies the sources from which to obtain the irrigation water, in preferential order. In other words, in the above example, if the dam cannot fully supply the required water, the balance will be taken from the bore. If there is still a shortage of water, then dam2 will be asked next to supply water. There is no limit to the number of sources which can be specified. When the irrigation water is applied to the soil, it will carry the solutes makeup of the water source being used.
Irrigation Module Outputs

The Irrigation module outputs the following variables.
Variable Name irrigation manual_irrigation
Description Total amount of irrigation added to profile during any timestep (mm) Current state of the fixed irrigation schedule (on/off)
automatic_irrigation Current state of the automatic irrigation schedule (on/off) crit_fr_asw asw_depth allocation allocation_ml carry_over carry_over_ml irr_fasw irr_deficit irrig_loss irrig_tot Critical fraction of available soil water (ie. above a 15 bar lower limit) below which irrigation is automatically applied. (0-1) Depth to which available soil water fraction is calculated. (mm) Current amount of irrigation allocation available for use (mm) Current amount of irrigation allocation available for use (ML) Amount of irrigation allocation unused as at reset of allocation (mm) (Value will be zero for days on which allocation is not reset) Amount of irrigation allocation unused as at reset of allocation (ML) Fraction of available soil water within the critical irrigation soil depth Deficit of soil water within the critical irrigation soil depth (mm) Losses resulting from and application of irrigation in conjunction with the irrigation_efficiency mechanism. Total irrigation specified, not including losses due to irrigation efficiency
Variable Name (mm) irrigation_XXX
Description
Applied quantity of solute XXX, (kg/ha)
Michael Robertson/Jacqui Hill Xth May 2004

Working science document for the lablab module
Introductory notes
The lablab module has received testing against four datasets from Queensland and the Northern Territory Cultivars currently simulated are: Highworth (annual) and Endurance (perennial) Users are invited to provide feedback on module performance to the convenors, Michael Robertson ( Michael.Robertson@csiro.au ) and Jacqui Hill ( Jacqueline.Hill@csiro.au ).
Science notes
Refer to the PLANT module science document for detail on the definition of parameters:
Syntax examples
To sow the annual cultivar: if day = 24 and year = 2000 then lablab sow cultivar = highworth, plants = 5 (/m2), sowing_depth = 40 (mm) endif To sow the perennial cultivar: if day = 24 and year = 2000 then lablab sow cultivar = endurance, crop_class = small_leaf, plants = 5 (/m2), sowing_depth = 40 (mm) endif To kill the stems of the perennial cultivar over winter in order to stall progression into higher phenological states: if (mint < 5) and (lai < 0.5) and (day > 120 or day < 240) then lablab kill_stem endif
Relevant references Module performance

Figures below show module performance for both cultivars at Gatton in Qld over one season (sown 24 th Jan 2000) under irrigated and dryland conditions; cultivar Highworth at Katherine in NT over one season (sown 1 st April 1980) under irrigated and dryland conditions; cultivar Highworth at Brian Pastures Research Station near Gayndah in Qld over two seasons (sown 4 th Jan 2000 and 14 th Dec 2000) under dryland conditions. Gatton, Highworth
irrigated Gatton, Highworth
dryland Gatton, Endurance
irrigated Highworth
Katherine,
Brian Pastures, Highworth,
2000 Pastures, Highworth,
Brian
2001
What is the Log Module?

The log module allows the user to track information and message flow through a simulation. The log file is formatted as a simple XML text document. These documents are often used to debug messaging problems within a simulation. Note that turning debug information on, and writing this to the log file, does slow down simulation execution.
Sample Parameterisation
The Log module has only two parameters: The name of the log file name and a flag to specify whether the user wants the detailed log written out for the current execution of the simulation. Setting debug output to off will stop the information being written to the log file.
sample.log.parameters logfile = log.txt debug_output = on
Output Variables
There are no output variables available from the log module.
For detailed information on module development and science please consult the PLANT module science document.
Introduction
The lucerne module was developed by Peter Carberry, Perry Poulton, Merv Probert and Michael Robertson . The module is described in the paper by Robertson et al. (2002). The reader is referred to the science document for the plant module for a comprehensive description of the processes simulated by APSIM-Lucerne. This document outlines some lucerne-specific issues that are not covered by the plant science document.
Notable features of APSIM-LUCERNE

The phenology of only one of the lucerne cultivars is responsive to photoperiod (see Moot et al. 2001), however it is likely that the other cultivars respond to photoperiod as well. Lack of data precludes parameterising this, though. The module does not simulate the well-known decline in biomass production in the autumn (influence of photoperiod on increase partitioning of assimilate below ground). There is module development going on to overcome this deficiency. In the meantime users are suggested to contact Michael Robertson or John Hargreaves at APSRU for a known workaround. The module does not simulate different degrees of winter dormancy in cultivars. Please see Michael Robertson at APSRU on advice on how to parameterise an unknown cultivar. The module operates on the basis of the stem as the unit, rather than the plant. As a rough guide if plant numbers are all that is known then work on 5-10 stems per plant depending upon stand age. APSIM-Lucerne is not phosphorus-responsive, this is currently under development. Crop growth is not sensitive to waterlogging.
Example Syntax
Sowing: lucerne sow cultivar = trifecta, plants = 200 (/m2), sowing_depth = 40 (mm) Harvest (end crop): Lucerne harvest Lucerne kill_crop Lucerne end_crop Harvest (with regrowth): Lucerne harvest plants = 150 (/m2), height = 50 (mm), remove = 0.95 The above harvest statement will cut the lucerne plant at 50 mm and remove 95% of the biomass. The plant density will also be reduced to 150 plants per sq metre from the previous 200 plants per sq metre.

There are two crop classes, representing crops growing from seed (plant) and crops growing after cutting. Crops change automatically from plant to regrowth classes at the first cut after sowing. There are a number of cultivars able to be simulated: Kaituna, Trifecta, Hunter_River, Sceptre, Aquarius. Northern China cultivars Longdong and Dingxi are also included.
Validation
APSIM-Lucerne has received testing in northern Australia (Probert et al. 1998) and New Zealand (Moot et al., 2001), Western Australia (Dolling et al 2004, Robertson et al 2004), New South Wales (Robertson et al 2004, Verberg and Bond 2003) and China (Chen et al 2003) with factors such as cultivar, irrigation, and soil type varying.
IN WHICH ENVIRONMENTS THIS MODULE SHOULD BE USED WITH CONFIDENCE?

APSIM-Lucerne can be used with most confidence throughout the wheat belt of Australia and in cool temperate environments such as New Zealand and northern China. When using the model in these environments, users should consult the module development team on how to simulate their particular cultivar.
References
Chen W, Yu Ying Shen, Michael Robertson, Merv Probert, Bill Bellotti, Zhi Biao Nan. Simulation of Crop Growth and Soil Water for Different Cropping Systems in the Gansu Loess Plateau, China using APSIM. In: "New directions for a diverse planet". Proc. 4th International Crop Science Congress, Brisbane, CDROM ISBN 1 920842 217. Web site www.cropscience.org.au Dolling P.J., Robertson M.J., Asseng S., Ward, P.R., Latta, R.A. (2004) Simulating lucerne growth and water on diverse soil types in a Mediterranean-type environment. Australian Journal of Agricultural Research (submitted). Moot, D., Robertson, M.J. and Pollock, K. (2001). Validation of the APSIM-Lucerne model for phenological development in a cooltemperate climate. 10th Australian Agronomy Conference, Hobart , Tasmania . Probert, M. E.; Robertson, M. J.; Poulton, P. L.; Carberry, P. S.; Weston, E. J., and Lehane, K. J. (1998). Modelling lucerne growth using APSIM. Proceedings of the 9th Australian Agronomy Conference, Wagga Wagga 1998:247-250. Robertson, M.J., Carberry, P.S., Huth, N.I., Turpin, J.E., Probert, M.E., Poulton, P.L., Bell, M., Wright, G.C., Yeates, S.J., and Brinsmead, R.B. (2002). Simulation of growth and development of diverse legume species in APSIM, Australian Journal of Agricultural Research 53:429-446. Robertson M, Gaydon D, Latta R, Peoples M and Swan A (2004) Simulating lucerne/crop companion farming systems in Australia. In: "New directions for a diverse planet". Proc. 4th International Crop Science Congress, Brisbane, CDROM ISBN 1 920842 217. Web site www.cropscience.org.au Verburg K, Bond WJ (2003) Use of APSIM to simulate water balances of dryland farming systems in south eastern Australia. CSIRO Technical Report 50/03, CSIRO, Canberra, Australia.
Introduction
The lupin module it is being developed by CSIRO Plant Industry in Perth (Drs Imma Farre and Senthold Asseng) together with Dr Michael Robertson at APSRU. The reader is referred to the science document for the plant module for a comprehensive description of the processes simulated by APSIM-Lupin. This document outlines some lupin-specific issues that are not covered by the plant science document. The lupin module simulates narrow leaf lupin (Lupinus angustifolius).
Notable features of APSIM-LUPIN:

The lupin model has had only a limited testing. The model is still under development and caution should be taken when using outside conditions it has been validated for (sandplain soils in WA) The phenology parameters have been tested on cultivars Belara, Kalya, Merrit, Myallie, Tallerac, Tanjil, Wodjil and Gungurru in several locations across Western Australia. Crop growth, final yield, LAI and water uptake has been only tested in cultivars Merrit and Gungurru in Moora (sandy soil) and Beverley (duplex soil) in Western Australia, respectively. The phenology of the lupin cultivars tested so far respond to photoperiod (daylength) but not to vernalisation. (The modern cultivars used for calibration and testing do not respond to vernalisation, but some old cultivars do respond to vernalisation) Crop growth is not sensitive to row spacing Crop growth is not sensitive to waterlogging. In the module, pods do not photosynthesise.
Cultivars
There are 8 conventional cultivars of narrow leaf lupin in the lupin.ini file: Belara, Kalya, Merrit, Myallie, Tallerac, Tanjil, Wodjil and Gungurru.
Validation
APSIM-Lupin has received limited testing in the wheatbelt of Western Australian, with factors such as cultivars, sowing date, irrigation, soil type varying. Cultivar Merrit has been tested against observed data (Dracup et al., 1998) on a duplex soil in Beverley (average annual rainfall = 400 mm), under rainfed conditions and supplementary irrigation in 1993. Model outputs have been compared to measurements of time course of total above ground biomass, seed weight, pod wall and LAI. Cultivar Merrit has been tested against observed data (Anderson et al., 1998a, 1998b) on a deep sand soil in Moora (average annual rainfall = 460 mm), under rainfed conditions, in 1995 and 1996. Observed time course of total above ground biomass, final seed yield and daily values of soil water content at different depths were compared to model simulations. Cultivar Gungurru has been tested against observed data (Gregory, 1998; Gregory and Eastham, 1996) on a duplex soil in Beverley, under rainfed conditions, in 2 sowing dates from 1990 to 1993. Because of the limited testing we would caution users taking the model outside WA and sandy soils.
References
Anderson , G.C., Fillery, I.R.P., Dolling, P.J. & Asseng, S. 1998. Nitrogen and water flows under pasture-wheat and lupin-wheat rotations in deep sands in Western Australia . 1. Nitrogen fixation in legumes, net N mineralisation, and utilisation of soil-derived nitrogen. Australian Journal of Agricultural Research , 49, 329-343. Anderson , G.C., Fillery, I.R.P., Dunin, F.X., Dolling, P.J. & Asseng, S. 1998. Nitrogen and water flows under pasture-wheat and lupin-wheat rotations in deep sands in Western Australia . 2. Drainage and nitrate leaching. Australian Journal of Agricultural Research , 49, 345-361. Dracup, M., Reader, M.A. & Palta, J.A. 1998. Variation in yield of narrow-leafed lupin caused by terminal drought. Australian Journal of Agricultural Research , 49, 799-810. Gregory, P.J. 1998. Alternative crops for duplex soils: Growth and water use of some cereal, legume, and oilseed crops, and pastures. Australian Journal of Agricultural Research , 49, 21-32. Gregory, P.J.& Eastham, J. 1996. Growth of shoots and roots, and interception of radiation by wheat and lupin crops on a shallow, duplex soil in response to time of sowing. Australian Journal of Agricultural Research , 47, 427-447.
MAIZE Module Scope

The maize module simulates the growth of a maize crop in a daily time-step (on an area basis not single plant). Maize growth in this model responds to climate (temperature, rainfall and radiation from the input module), soil water supply (from the soilwat module) and soil nitrogen (from the soiln module). The maize module returns information on its soil water and nitrogen uptake to the soilwat and soiln modules on a daily basis for reset of these systems. Information on crop cover is also provided to the soilwat module for calculation of evaporation rates and runoff. Maize stover and root residues are passed' from maize to the residue and soiln module respectively at harvest of the maize crop. A list of the module outputs is provided in the Maize module outputs' section below, but basically the module will predict leaf area development, N% and biomass of stover; depth, N% and biomass of roots; grain N% and biomass; grain yield and N%, grain size and grain number all on a daily basis.
Maize Module History

The maize module was developed from a combination of the approaches used in the CM-KEN (Keating et al., 1991, 1992) and CM-SAT (Carberry et al., 1989; Carberry and Abrecht, 1991) models of maize (both derivatives of CERES-Maize, Jones and Kiniry, 1986), with some features of the maize model of Wilson et al. (1995). The major differences from CERES-Maize are routines which kill crops in response to severe water deficit during the early- to mid-vegetative stage (Carberry and Abrecht, 1991).
Delay silking by severe water or nitrogen stress simulate leaf area development by accounting for relationships between total leaf number and leaf area (Muchow and Carberry, 1989; Keating and Wafula, 1991) allow thermal time to accumulated between 0 and 10 oC, thus permitting the accurate simulation of phenological development in cool temperate environments (Wilson et al., 1995). Determine transpiration based on biomass accumulation, a transpiration efficiency coefficient, daily vapour pressure deficit and a 0-1 soil water deficit factor. Uses a radiation-use efficiency based on above-ground biomass accumulation, and grows root biomass based on fixed root:shoot ratios for different phenological phases (Carberry et al. 1989) The model was validated on many of the same datasets that were originally used to develop CM-KEN and CM-SAT, in addition to new datasets (see Table below).
Maize Module Structure
Maize
Module Components
Phenology
There are 11 crop stages and nine phases (time between stages) in the maize module, and commencement of each stage (except for sowing to germination which is driven by soil moisture) is determined by accumulation of thermal time. Each day the phenology routines calculate today's thermal time (in degee days) from 3-hourly air tempertures interpolated from the daily maximum and minimum temperatures. Thermal time is calculated using the relationship in Figure 1 with the eight 3hour estimates averaged to obtain the daily value of thermal time (in growing degree days) for the day. These daily thermal time values are cumulated into a thermal time sum which is used to determine the duration of each phase. Between the stage of emergence and flowering the calculated daily_thermal_time is reduced by water or nitrogen stresses, resulting in delayed phenology when the plant is under stress.
The thermal time between sowing and germination is dependent upon soil water levels. The phase between germination and emergence includes an effect of the depth of sowing on the thermal time target. The duration between emergence and flag leaf appearance is determined by the total number of leaves destined to appear on the plant, and the rate at which they appear, which is determined by temperature (see below). The total number of leaves is equal to the number in the seed at germination (7) plus the number subsequently initiated at a rate of 21 o Cdays per leaf, until floral initiation is reached. Hence the timing of floral initiation will determine the total leaf number and the timing of the appearance of the flag leaf and flowering (i.e. silking). The phase between emergence and floral initiation is composed of a cultivar-specific period of fixed thermal time, commonly called the basic vegetative or juvenile phase. Between the end of the juvenile phase and floral initiation the thermal development rate is sensitive to photoperiod (calculated as a function of day of year and latitude) if the cultivar is photoperiod sensitive. The model assumes that maize, as a short day plant, will have a longer phase (dependent upon cultivar) between the end of the juvenile phase and initiation if photoperiods exceed 12.5 hours. There are cultivar-specific fixed thermal time durations for the subsequent phases between flowering and the start of grain fill, between the start and end of grainfill, between the end of grainfill and maturity, and between maturity and harvest ripe.
Biomass accumulation (Photosynthesis)

Each day two estimates of the daily biomass production are calculated, one limited by available water for transpiraton (eqn 1), and the other limited by radiant energy (eqn 2). The minimum of these two estimates is the actual biomass production for the day. delta_drymatter_transpiration = soil_ water_ supply * transpiration_efficiency eqn 1. Note: transpiration_efficiency is derived from the transpiration_efficiency_coefficient (=0.009) and the vapour pressure deficit (vpd) estimated from daily temperatures. dlt_drymatter_potential = rue *radiation_interception eqn 2. Note rue (radiation-
use efficiency) is 1.6 g MJ-1 from emergence to the start of grain-filling, and then declines to 1.06 g MJ-1 from the start of grain filling to account for the effects of leaf aging on reduced photosynthetic capacity (Muchow et al. 1990). Radiation interception is calculated from leaf area index and a radiation extinction coefficient of 0.45.
Biomass partitioning
Daily biomass production is partitioned to different plant parts in different ratios depending on crop stage. Until the end of juvenile phase the root:shoot ratio is maintained at 1.0, and then decreases to a value of 0.087 at flowering. Between emergence and flag leaf appearance the proportion of biomass produced that is partioned to leaf increases exponentially as leaves appear. Between the stage floral initiation and flag leaf appearance, the biomass remaining after allocation to leaf is allocated between stem and developing ear in the ration 1:0.30. After leaf growth has ceased at flag leaf appearance, biomass is partitioned between stem and ear only until the start of grain filling, whereuopon partitioning to grain only occurs. The maize module allows a total retranslocation of no more than 15 and 20% of leaf and stem biomass present at the start of grainfilling, respectively Grain demand for carbohydrate (biomass) is calculated by multiplying the grain number by the maximum potential grain growth rate (e.g. for Dekalb_XL82 10 mg/grain/day). The number of grains set per plant is determined by the average daily growth rate per plant between floral initiation and the start of grain filling, using the function developed by Edmeades and Daynard, (1979).
Leaf development
Leaf appearance rate is driven by thermal time, the last 14 leaves before the flag leaf appear each 36 o Cdays, before which a leaf appears every 65 o Cdays (Wilson et al., 1995).
Potential LAI
is a product of leaf number, leaf size, number of plants per m2 and the water stress factor for expansion (see water deficits section below). An adjustment factor is used to account for the area of currently expanding leaves. Leaf size is calculated from final leaf number assuming that it follows a bell-shaped distribution with leaf position along the stalk (Keating and Wafula, 1992). Early in crop development, before floral initiation is reached and hence before final leaf number is known, an estimated date of floral initiation is used to calculate a provisional final leaf number for the purposes of simulating leaf size.
Actual LAI
is less than the potential LAI if there is not sufficient biomass partitioned to leaf on that day. Maximum specific leaf area (SLA_MAX) defines the maximum leaf area (m 2 ) that can be expanded per gram of biomass. SLA_MAX declines with increasing LAI i.e. smaller, younger crops have larger thinner leaves.
Leaf senescence
There are four causes of leaf senesence; age, light competition, water stress and frost. The maize senescence routines calculate a senesced LAI for each stress each day and take the maximum of the four values as the day's total senescence. A fraction of the oldest green leaf dies each day after flowering. This senescence due to age occurs a rate of leaves per day (this is calculated from the day's thermal time divided by a constant leaf-death-rate). This number of dead leaves is then converted to a senesced LAI. Above an LAI of 4.0 light competition causes leaf area to be lost. The LAI senesced because of light competition is related to the amount LAI exceeds 4.0 (see eqns 3 and 4). sensLAI_light_fac = 0.008 *(LAI- 4.0) eqn 3. delta_sensLAI_light = LAI * sensLAI_light_fac eqn 4. Water stress during crop growth will cause leaf senescense (eqns 5 and 6). sensLAI_water_fac = 0.05 * (1 - maize_swdef(photo)) eqn. 5. delta_sensLAI_water = LAI * sensLAI_water_fac eqn 6. Note: the calculation of the water stress factor maize_swdef(photo) is descibed in the water deficits' section below. Frost senescence. Temperatures between 6.0 and 0 o C will cause a linearly increaseing loss of leaf area from 0 to 100% respectively. From the values of senesced LAI the
maize module calculates the biomass and nitrogen in that leaf area that is senesced, however a proportion of the carbon and nitrogen of these leaves is retranslocated to stem before senescence.
Tillering
The potential tiller no. in the maize module has been set to 0, effectively disabling the tillering routine.
Regrowth
There are no regrowth routines in maize .
Water uptake
To determine the amount of water supply to the crop on any day, first the total available water above the lower limit for all soil layers with roots is summed (eqn 7). If roots are only partially through a layer available soil water is scaled to that portion that contains roots. The kl constant (value differs for each soil layer) is then used to limit the amount of water available on any day (eqn 8). The kl factor is emphirically derived, incorporating both plant and soil factors which limit rate of water uptake. do layer = 1, deepest_layer (do loop to calculate available water for all layers) sw_avail = sw(layer) - ll (layer) eqn 7. sw_supply(layer) = sw_avail * kl (layer) eqn 8. Soil water demand is calculated as in the biomass accumulation' section above where potential biomass production is a function of radiation interception and rue . This potential biomass production is converted to water demand using transpiration efficiency. Transpiration efficiency is calculated from the transpiration effieicny coefficient ( transp_eff_cf ), which can vary with growth stage, and vapour pressure deficit. Soil water demand can be capped in the *.ini file by the atmospheric evaporative demand (eo) adjusted by the proportion of green canopy cover (cover_green) and a crop factor (eo_crop_factor) i.e. eo_crop_factor * eo * cover_green . Users wishing to use the eo_crop_factor should consult with the module owner. Water uptake is the minimum of the supply and demand.
Water deficits affecting plant growth

Soil water deficit factors are calculated to simulate the effects of water stress on different plant growth processes. Three water deficit factors are calculated which correspond to four plant processes each having different sensitivity to water stress i.e. photosynthesis (photo), phenology (pheno), and leaf-expansion (expansion). A water availability ratio is calculated by dividing actual soil water supply (sw - ll) by the potential soil water supply (dul - ll). This ratio is used in the relationships illustrated to derive the stress factors for photosynthesis and leaf expansion. A factor of 0 is complete stress and 1 no stress.
A fraction of plants (0.044) will be killed each day due to water stress once the cumulative water stress factor for photosynthesis exceeds 4.6. Nitrogen uptake and retranslocation In order to
calculate nitrogen demand today, first potential biomass production is re-calculated unlimited by water, nitrogen or temperature i.e. as a function of rue and radiation-interception (eqn 2). This dry matter (biomass) is then partition into plant parts according to their current relative weights. The maize module has a defined minimum, critical and maximum N concentration for each plant part. Demand for nitrogen in each part attempts to maintain nitrogen at the critical (non stressed) level. Nitrogen demand on any day is the sum of the demands from the pre-existing biomass of each part required to reach critical N content, plus the N required to maintain critical N concentrations in today's potentially assimilated biomass. A nitrogen uptake maximum is defined as the nitrogen uptake required to bring all plant part N contents to the maximum allowable concentration. Nitrogen supply is the sum of nitrogen available via mass flow (eqn 9) and by diffusion (eqn 10). no3_massflow (layer) = no3_conc * delta_sw (layer) eqn 9. no3_diffusion (layer) = sw_avail_frac *no3_conc eqn 10. note: these layer values are summed to root depth and sw_avail_frac is ratio of extractable soil-water over total soil-water. If nitrogen demand cannot be satisfied by mass flow then it is supplied by diffusion. Demand can only be exceeded by supply from mass flow (up to the nitrogen uptake maximum). If both mass flow and diffusion supplies can't satisfy demand then nitrogen is sought from N fixation (see next section). Nitrogen available for uptake is distributed to plant parts in proportion to their individual demands. Nitrogen for grain is retranslocated from other plant parts, N is not directly taken up from the soil or atmosphere to meet grain demand. Nitrogen is available for retranlocation from all parts except for grain and roots; other plant parts will translocate nitrogen until they reach their defined minimum N concentration. Grain nitrogen demand is again driven by critical N content but this demand is lowered if the plant is under N stress. Grain N demand is also affected by temperature and water stress using eqns 11 and 12 below. N_grain_temp_fac = 0.69 + 0.125 * aver_temp equ 11. N_grain_sw_fac = 1.125 - 0.125 * swdef (expansion) eqn 12. The greatest of these two factors is multiplied by the previously calculated N demand i.e. if temperature is high or sw deficit is low (water stressed) the N demand will be increased above the level required to reach the critical N concentration.
N fixation
There is no nitrogen fixation in the maize module.
Nitrogen deficits affecting plant growth

There are three N availability factors (0-1), one each for the photosynthesis, expansion, phenology and grain filling processes. A N concentration ratio is calculated for the stover (stem + leaf) in eqn 14 which is used as a measure of N stress, then different constants are used to convert that ratio to a deficit factor for each of the processes. A factor of 1 is used for effecting grain N concentration, 1.25 for photosynthesis (reduces rue), 0.8 for expansion (reduces leaf area expansion) and 5.75 to slow phenological development. As a value of 1 is no stress and 0 complete stress, phenology is least sensitive to nitrogen deficiency and grain N the most. N_conc_ratio = (N_conc_stover N_conc_stover_min) / (N_conc_stover_crit - N_conc_stover_min) eqn14.
Root growth and distribution

Root depth is initialised at the depth of sowing. Between emergence and grain filling, the increase in root depth is a daily rate multiplied a soil water availability factor. The daily rate is 10-15 mm/day during emergence and 33mm/day from end-of-juvenile to the start of grain-filling. Root depth is constrained by the soil profile depth. The increase of root depth through a layer can be constrained by known soil constraints through the use of the 0-1 parameter xf, which is input for each soil layer. Growth of root biomass is partitioned with depth using an exponential decay function from the soil surface and converted to root length density using a fixed specific root length. Roots are not senesced during the life of the crop, but are incorporated in the soiln module at harvest and distributed as fresh organic matter in the profile
Temperature stress
There are no generic temperature factors, as for water and nitrogen stress, but as discussed in sections above temperature does influence grain N content, rate of senescence and radiation use efficiency (rue).
Plant death
All or some of the plants can be killed due to a variety of stresses; If the crop hasn't germinated within 40 days of sowing, due to lack of germinating moisture, all plants are killed. If the crop does not emerge with 150 o Cdays of sowing, because it was sown too deep, then all plants are killed. If crop is past floral initiation and LAI = 0, then all plants are killed due to total senescence. If the cumulative phenological water stress factors exceed 25, all plants are killed due to water stress prolonging phenology. A fraction of plants will be killed by high temperatures immediately following emergence.
Detachment
The detachment routines in maize are disabled in the current code.
Maize Module Parameterisation

Crop lower limit and kl values are need for each soil layer test.maize.parameters ll = 0.200 0.200 0.200 0.220 0.250 () ! crop lower limit kl = 012 0.08 0.06 0.04 0.02 () ! kl need calibrating for each crop and soil type Phenology and grainfilling parameters are needed for each cultivar. An example is given below of those for the katumani composite cultivar. Some of the parameters are not used in the current version, as they can be used in alternative options for simulating some processes (e.g. grain filling). (indicated below as option). calibration.maize.katumani
hi_incr 0.018 (1/days) hi_max_pot 0.55 (g/g) head_grain_no_max 450 () grain_gth_rate 10.5 (mg/grain/day) tt_emerg_to_endjuv 150( o C day) est_days_endjuv_to_init20 () pp_endjuv_to_init 10 tt_endjuv_to_init 0.0 ( o C day) photoperiod_crit1 12.5 (hours) photoperiod_crit2 24.0 (hours) photoperiod_slope 10.0 ( o C/hour) tt_flower_to_maturity 660 ! ( o C day) tt_flag_to_flower 10 ( o C day) tt_flower_to_start_grain 120 ( o C day) tt_maturity_to_ripe 1 ( o C day)
!option not used !option not used
=! not used
Module Dependencies
The minimum module configuration required to run maize in APSIM is the inclusion of the report, input, manager, soilwat, soiln and residue and maize modules. Soilwat2, soiln2 and residue2 can be used instead of the original modules.
Crop Sowing and Harvesting Logic

Within the manager file the following syntax is used for harvest and planting the maize crop: if (maize.stage_name = 'harvest_ripe' and maize.plant_status = 'alive') then maize harvest maize
kill_crop maize end_crop endif if (maize.plant_status = 'dead') then report do_output maize harvest maize end_crop endif if (day > 120 and day < 240 and maize.plant_status = 'out' ) then maize sow plants = 15 (p/m2), sowing_depth = 50 (mm), row_spacing = 0.35 (m), cultivar = katumani, fertile_tiller_no = 0 endif (note: row_spacing in sowing command is optional)
Skip Row Planting

maize sow plants = 15 (p/m2), sowing_depth = 50 (mm), row_spacing = 0.35 (m), cultivar = katumani, fertile_tiller_no = 0, skip = single Skip row planting can be specified by using the skip keyword on the sowing command with a value of single, double or solid. A single skip has two crop rows followed by a single unplanted row whereas a double skip has two crop rows followed by two unplanted rows. A solid planting behaves as it no skip row information has been specified. Currently, the change to light interception is the only effect of the skip planting on the crop growth. Maize Module Outputs The following Maize variable can be output through the report module
===Variable Name=== stage stage_code stage_name crop_type leaf_no leaf_no_dead leaf_area (max_leaf = 1000) height root_depth rlv hi plants grain_no grain_size cover_green cover_tot lai_sum tlai slai lai tlai_dead root_wt leaf_wt stem_wt grain_wt grain_wt dm_green (max_part = 6) dm_senesced (max_part = 6) dm_dead (max_part = 6) yield
Units
Description current phenological stage
number of fully expanded leaves no of dead leaves mm 2 leaf area of each leaf mm canopy height mm depth of roots mm.mm -3 root length per volume of soil in each soil layer Harvest index plants/m 2 plant density grains/plant grain number g individual grain wt 0-1 fraction of radiation reaching the canopy that is intercepted by green leaves 0-1 total crop cover fraction leaf area index of all leaf material live + dead tot lai area of leaf that senesces from plant m 2 /m 2 live plant green lai m 2 /m 2 total lai of dead plants g/m 2 root biomass g/m 2 leaf biomass g/m 2 stem biomass g/m 2 grain biomass g/m 2 grain biomass g/m 2 live plant dry weight (biomass) g/m 2 senesced plant dry wt g/m 2 dry wt of dead plants kg/ha grain yield dry wt
biomass stover dlt_dm dlt_dm_green (max_part = 6) n_green (max_part = 6) n_senesced (max_part = 6) n_dead (max_part = 6) dlt_n_green (max_part = 6) dlt_n_retrans (max_part = 6) dlt_n_detached (max_part = 6) dlt_n_dead_detached (max_part = 6) swdef_pheno swdef_photo swdef_expan ep (num_layers) cep sw_demand sw_supply esw_layer (num_layers) n_conc_stover n_conc_crit n_grain_pcnt n_uptake_grain n_uptake n_uptake_stover no3_tot n_demand n_supply n_supply_soil n_fix_pot nfact_photo nfact_grain nfact_photo nfact_expan dlt_tt das
kg/ha kg/ha g/m 2 g/m 2 g/m 2 g/m 2 g/m 2 g/m 2 g/m 2 g/m 2 g/m 2 0-1 0-1 0-1 mm mm mm mm mm % % % g/m 2 g/m 2 g/m 2 g/m 2 g/m 2 g/m 2 g/m 2 g/m 2
total above-ground biomass above-ground biomass not including grain the daily biomass production plant biomass growth plant nitrogen content plant n content of senesced plant plant n content of dead plants actual n uptake into plant nitrogen retranslocated out from parts to grain actual n loss with detached plant actual n loss with detached dead plant water deficit factor for phenology water deficit factor fo photosynthesis water deficit factor for leaf expansion water uptake in each layer cumulative water uptake total crop demand for water total supply over profile plant extractable soil water sum of tops actual n concentration sum of tops critical n concentration grain n concentration percent n uptake by grain cumulative total n uptake by plant n uptake by stover total no3 in the root profile sum n demand for plant parts n supply for grain n supply from soil potential N fixation N deficit factor for photosynthesis N deficit factor for grain N content Nitrogen stress factor for photosynthesis Nitrogen stress factor for cell expansion daily thermal time days after sowing
0-1 0-1 o Cday
Module Instantiation
This is an instantiable module, that is, it can be used in several contexts within the one simulation. For example, this module may be used to simulate a growing crop, while another instance of this module (configured differently) is used simultaneously to represent a weed growing within that crop. There are certain protocols and procedures which must be followed in order to instantiate modules,
and these are described in more detail in the document Module Instantiation , found in C:\apsuite\docs.
Maize Module validation

The maize model was validated against a wide range of datasets originating from tropical and subtropical Australia , semi-arid Kenya and USA (Table 1). Overall model performance with a combined set of this data is presented in the following figure. Overall, model performance was good, particularly for grain yield, usually the most important variable to be simulated. The range in grain yield covered 0 to 17.3 t ha -1 . The r-squared value for observed versus predicted grain yield was 89%. Table 1: Details of datasets used to validate the maize crop module.
Factors
Location
Reference
Sowing date, water Tropical Australia Muchow (1989a,b), Carberry et supply, N fertiliser rate, al., (1989), Sinclair and plant population density Muchow (1995) Sowing date, N fertiliser Sub-tropical rate Australia Sowing date, N fertiliser Semi-arid Kenya rate, variety, water supply, plant population density Sowing date, plant population density USA Wilson , et al. (1995), Muchow (1994) Keating et al. (1992)
Muchow et al. (1990)
Inspection of model performance for individual experiments shows that it is simulating the key responses to major agronomic variables. For example the following figures show the model performance for responss to plant population density under both deficit and favourable water (bmw6
experiment conducted at Katumani, Kenya with both the dryland composite DLC and Katumani composite KCB cultivars) and nitrogen (jmw2 experiment conducted at Kiboko, Kenya with the KCB cultivar) supply.
References
Carberry, P. S.; Muchow, R. C. and McCown, R. L. 1989. Testing the CERES-Maize simulation model in a semi-arid tropical environment. Field Crops Research, 20: 297-315. Carberry, P. S. and Abrecht, D. G., 1991. Tailoring crop models to the semi-arid tropics: In: RC Muchow and JA Bellamy (Eds) Climatic risk in crop production: Models and management in the semi-arid tropics and subtropics. Cab International, Wallingford . P. 157-182.. Edmeades, G. O. and Daynard, T. B. 1979. The relationship between final yield and photosynthesis at flowering in individual maize plants. Canadian Journal of Plant Science 59: 585-601. Jones, C. A.and Kiniry, J. R. 1986. CERES-Maize: A simulation model of maize growth and development. Texas A & M University Press, College Station , texas, 194pp. Keating, B. A.; Godwin, D. C.; Watiki, J. M. 1991. Optimising nitrogen inputs in response to climatic risk. In: RC Muchow and JA Bellamy (Eds) Climatic risk in crop production: Models and management in the semi-arid tropics and sub-tropics. Cab International, Wallingford . P. 329-358.
Keating, B. A. and Wafula, B. M. 1992. Modelling the fully-expanded area of maize leaves. Field crops Research, 29: 163-176. Keating, B. A., Wafula, B. M. and watiki, J. M. 1992. Development of a modelling capability for maize in semi-arid eastern Kenya . In: Probert, M. E. (1992) A search for strategies for sustainable dryland cropping in semi-arid eastern kenya . Proceedings of a Symposium held in Nairobi , kenya , 10-11 December 1990. ACIAR Proceedings No. 41, 138 pp. Muchow, R. C. 1989. Comparative productivity of maize, sorghum and pearl millet in a semi-arid tropical environment. I. Yield potential. Field Crops Research 20: 191-205. Muchow, R. C. 1989. Comparative productivity of maize, sorghum and pearl millet in a semi-arid tropical environment. II. Effect of water deficits. Field Crops Research 20: 207-219. Muchow, R. C. 1994. Effect of nitrogen on yield determination in irrigated maize in tropical and subtropical environments. Field Crops Research 38: 1-13. Muchow, R. C. and Carberry, P. S. 1990. Phenology and leaf area development in a tropically-adapted maize. Field Crops Research, 20: 221236. Muchow, R. C., Sinclair, T. R. and Bennett, J. M. 1990. Temperature and solar radiation effects on potential maize yield across locations. Agronomy Journal 82: 338-343. Sinclair, T. R. and Muchow, R. C. 1995. Effect of nitrogen supply on maize yield: I. Modeling physiological responses. Agronomy Journal 87: 632-641. Wilson, D. R.; Muchow, R. C. and Murgatroyd, C. J. 1995. Model analysis of temperature and solar radiation limitations to maize potential productivity in a cool climate. Field Crops Research, 43: 1-18.
Maise Moule Working Group

Michael Robertson , Peter Carberry, Brian Keating, Neil Huth
What is the manager module?

The manager module provides the capability to specify a set of rules using conditional logic during simulations to control the actions of modules within APSIM. It does this by using if constructs created by the user. It also allows the user to create their own variables and define these as a function of other variables within APSIM. This documentation only gives a brief insight into the possibilities achievable via the APSIM manager module.
How does it manage?

This module manages by issuing messages to modules in the system, many of which are conditional upon states or events within the modules during simulation. For example:-
if (day = 100) then fertilise apply amount = 10 (kg/ha), type = urea (), depth = 50(mm) endif
Here the fertilise module will be sent a message containing a directive to apply (the action) fertiliser when the condition is satisfied. It receives a data string (the underlined text) which further describes the action. As of version 4 of APSIM, the manager module can broadcast a message to all modules by
substituting the keyword 'act_mods' in the place of the module name. This capability is useful for multi-point simulations where a sow message needs to be sent to multiple points.
Mathematical operators
The following mathematical operators and reserved words are allowed in APSIM manager files.
Operator + * / ^ or ** = < > <> <= >= () If then elseif else endif or and
Description Subtraction Addition Multiplication Division Exponent (eg. x**2 is the same as x 2 ) Equality Less than Greater than Not equal to Less than or equal to Greater than or equal to Brackets Logical IF Logical THEN Logical ELSEIF Logical ELSE (for alternate logic) Logical ENDIF Logical OR Logical AND
Rules

Names must begin with a letter. Numbers must begin with a digit. Literals must begin and end with an apostrophe.
Character set
The manager uses the following character set:
Character Description a to z letters case insensitive 0 to 9 Digits _ Underscore
Character % . [] () + * / = < > ^
Description Percent sign Period or decimal point Square brackets Parentheses Minus sign Plus sign Asterisk Slash Apostrophe Equal sign Less than Greater than Blank Caret
Manager Functions
Manager functions may not have any spaces. This applies from the first character of the function name to the terminating bracket. The manager has the following functions:-
Function name date
Description returns the julian day number of specified date. eg. date(1-oct'). The date must be a literal enclosed in single quotes. returns 1 if today's date is within the range specified, otherwise returns 0. eg. date_within('1-oct,31-oct') The pair of dates must be two date literals separated by a comma, and the whole argument must be enclosed in quotes. Note the lack of quotes near the comma. Returns the nearest integer to the value specified. eg. nearest_int(var1). Here var1' must be a numeric variable. It cannot be a literal or an expression.
date_within
nearest_int
Returns 1 if there are no crops in the ground. e.g. if (paddock_is_fallow() = 1 and today = date('1-jun')) then paddock_is_fallow wheat sow ... endif add_months Takes 2 parameters, a date and the number of months to add to the date. The new date is then returned. e.g. gsrDate = date('1/9/2005')
Function name
Description gsrDate = add_months('gsrDate, 1') The whole argument to add_months must be enclosed in single quotes. The number of months can be positive or negative.
Dates may take the following forms:

30/6/95 30/6/1995 Jun 30_Jun 30_Jun_1995 30-jun 30-jun-1995
For example:

date('30/6/95') returns the julian day number for 30 jun 1995 date('Jun') returns the julian day number for 1 jun for current year. date('30_jun') returns the julian day number for 30 jun for current year. date('30_jun_1995') returns the julian day number for 30 jun 1995
For related chronological or date variables which can be used by the manager module, see the documentation for the CLOCK module. For example day - returns the day of the month dd/mm/yyy - returns the day, month and year of the given day. See the CLOCK module for further details.
Using the manager to send actions to other modules

The APSIM manager module can be used to invoke any action available by any module. Possible actions include:

Resetting individual module values Reinitialising all data in modules to a given state Sowing, harvesting or killing crops. Applications of fertiliser, irrigation or tillage to soil.
Refer to the individual module's documentation for a list of available actions and examples of usage. Refer also to the module's sample files for further examples.
How to Use Map

The Map module maps simulation soil layers onto output layers. Numerical simulation of water and solute is likely to require many more layers than the user either wants to know about in the outputs or has data to compare against. Map groups simulation layers into more useful output layers using an array of coefficients.
Output arrays may either be expressed as sums, averages, or concentrations of the contributing simulation layers. Map can map the same array in several different ways (eg. Below nitrate, no3n, is converted to a sum, a concentration, and a concentration in the soil water) but there can be only one layer structure.
Example
[test.map.parameters] arrays2sum_names = no3n nh4n dlayer arrays2ave_names = soil_temp arrays2conc_names = no3n arrays2concsw_names = no3n arrays2satpaste_names = core_start = 0 200 400 600 800 core_end = 200 400 600 800 900
To Use Supply
arrays2sum A list of array names owned by other modules whose elements are to be summed into a more useful output range. The name of the mapped array will be that of the original array but preceded by map_'. Currently a maximum of 10 arrays can be summed.
arrays2ave A list of array names owned by other modules whose elements are to be averaged into a more useful output range. The name of the mapped array will be that of the original array but preceded by map_'. Currently a maximum of 10 arrays can be averaged.
arrays2conc A list of array names owned by other modules whose elements are to be converted into concentrations in the soil volume. The name of the mapped array will be that of theoriginal array but preceded by conc_'. Currently a maximum of 10 arrays can be converted to concentrations.
arrays2concsw As above except the concentrations will be expressed as the concentration in the soil water. The name of the mapped array will be that of the original array but preceded by concsw_'. Currently a maximum of 10 arrays can be converted to concentrations. arrays2satpaste As above except the concentrations will be expressed as the concentration in a saturation paste. Because there is no standard method of estimating the saturation paste water content from the soil's hydraulic properties the user must supply that water content. Map will look for an array, satpaste_wc the saturation paste gravimetric water content units of g /g, to be provided from another module (e.g. Manager, Input). The name of the mapped array will be that of the original array but preceeded by satpaste_'. Currently a maximum of 10 arrays can be converted to saturation paste concentrations.
core_start/core_end A list of the start and end depths (in mm) for each layer for which you want values reported. There can be only one if you want - this is a simple way of finding the total amount of a substance to some depth which is not the simulation depth. The depths do not have to be contiguous, there can be gaps on the layers, the layers do not have to be in increasing depth order, point depths (core_start = core_end) are acceptable (and in this case all Map does is to find the appropriate layer). The only requirements are that there are pairs of core_start and core_end and that for any pair core_start <= core_end.
Description
The APSIM Met module provided daily meteorological information to all modules within an APSIM simulation.
Operation
The APSIM Met Module requires parameters to specify the climate of the site for each APSIM time step. This information is included in a weather' , or met' , file. Climate data can exist in the met file in two ways : As Constants or as Daily (Column) values.
Constant Values
Climate information for the simulation site that is independent of time can be specified at the top of the data section. Examples of how constant values can be specified are the values:
site = toowoomba latitude = -26.8 (degrees)
shown in the example below.
Daily (Column)Values
Information that needs to be specified for each day can be arranged in space-delimited columns. The data columns can be arranged in any order and contain any data of any type. The line following the list of column names must be followed by a line containing the units, in brackets ()' , for the information in each column.
The only restraints are as follows:
column headers must use the standard APSIM state variable names so that the data can be recognised by the module communications.
The list of columns must contain adequate information for identifying time for each row. This means that the list of columns must contain either: day' and year'
OR day_of_month' , month' and year' .
AN EXAMPLE
The file sample.met could then have the following:-
[weather.met.weather] site = toowoomba latitude = -26.8 (degrees) year () 1996 1996 1996 1996 1996 . . . day radn () (MJ/m2) 65 20 66 20 67 20 68 20 69 20 . . . . . . maxt (oC) 29 29 29 22.5 27.5 . . . mint rain (oC) (mm) 20.5 0 20 0 21 0 20 0 18.5 0 . . . . . .
Setting a Daily(Column) Value to a Constant Value

Sometimes you may want to switch off a column in your met file and replace it with a constant value. For example you may want to instead of using the rain column in your met file, you may want to set the rain to always be a constant value of 0mm (so no rainfall). Of course you can always just edit the met file itself and change the column values to be zero, but this is time consuming. A faster way is to just put the constant value,
rain=0 (mm)
at the top of your met file, and then rename the column heading for the rain column to something
that won't be recognised as an APSIM variable,
eg. rain (mm) to xrain (mm)
Resetting Met Variables (eg Climate Change scenario)

The APSIM Met Module can reset the values of any variables specified in the met file. Both constants and column values (apart from the time specification column values) for the current timestep can be reset using standard APSIM communication techniques. However, changing met data dynamically dur ing a simulation must only occur at a predefined stage during daily simulation execution. See example below.
Resetting met variables at 'start_of_day' or 'end_of_day' could result in critical modules (eg Soilwat2) missing the information due to process ordering. Setting met variables at the 'preNewMet' stage (see example) will avoid this risk.
AN EXAMPLE
Most modules in APSIM get their weather data from a newmet event that is produced by the MET module, so we need to change the weather variables before this event gets sent out. The MET module produces an event that makes this easy. It is called prenewmet. This event is fired just before a newmet event. So all we have to do is to trap this event and change the weather variables. From the manager\sample\manager.par file:
modify_met.manager.preNewmet maxt = maxt + 2 mint = mint + 2
When the prenewmet event fires, we increase the maximum and minimum temperature by 2 degrees, which then gets propagated to all other APSIM modules when the newmet event is sent by the MET module.
Module Output Variables

The APSIM Met Module can provide the values of several state variables for reporting to an output file or use by other modules.
Name keyword Column name
Units
Description
as Each keyword climate constant is available for output by the user. specified Each column data field is available for output by the user. The value for as the current simulation timestep will be returned. The time specifiers (ie specified day, year, day_of_month, month) are not available for output. Day length (hours of sunlight) for the current simulation day. This value is calculated using time of year and latitude and assumes a civil twilight angle of 6 degrees.
Day_length hours
MILLET MODULE SCOPE

The millet module simulates the growth and development of a pearl millet crop in a daily time step. The module is specifically designed to deal with the tillering nature of the millet crop. Each axis of the crop is considered to be a different crop, and the competition for resources between the axes is simulated analogous to an intercrop. Pearl millet growth responds to climate (temperature, rainfall, radiation), soil water supply (from soilwat2 module), and soil nitrogen (from soiln2 module)and returns information on soil water and soil nitrogen to the soilwat2 and soiln2 modules on a daily basis for resets of these systems. Information on crop cover is also provided to the soilwat2 module to calculate evaporation rates and runoff. Pearl millet stover and root residues are passed from millet to the residue2 and soiln2 module respectively at harvest of the millet crop. A list of the module outputs is provided in the Millet module outputs' section towards the end of the document. The module simulates biomass (above and below ground), grain yield, leaf area development, N-contenets for individual plant parts, and yield components, all on a daily time step for individual axes.
MILLET MODULE HISTORY

The module was adapted from CERES-MAIZE, and is currently very similar to the Crop template in APSIM. The major difference with any other module in APSIM is that it simulates the growth and development of individual tillers, by considering the entire crop as an intercrop of the different axes. The module has been parameterised based on data from experiments conducted at the ICRISAT research station at Patancheru , India , under optimum growing conditions, covering a range of plant densities and genotypes (van Oosterom et al., 2001a and b). The module adequately predicts biomass, grain yield, and LAI across a range of plant densities, photoperiods, and genotypes. However, all the validation data sets were obtained from experiments conducted at Patancheru. We are currently (December 2000) in the process of collating data sets form other parts of the world to extend the range in maximum LAI, biomass and grain yield in the validation data sets.
MILLET MODULE COMPONENTS Phenology

There are 11 crop stages and ten phases (time between stages) in the millet module. Commencement of each stage is determined by accumulation of thermal time, except for sowing to germination which is driven by soil moisture. Each day the phenology routines calculate today's thermal time (in degree days) from 3-hourly air temperatures interpolated from the daily maximum and minimum temperatures. Thermal time is calculated using 10C, 33C, and 47C as the base, optimum, and maximum temperature, with linear interpolations between these points. The eight 3hourly estimates are averaged to obtain the daily value of thermal time. These daily values are summed into a thermal time sum which is used to determine the duration of each phase. Between the stage of emergence and flag leaf, the calculated daily thermal time is reduced by water or nitrogen stresses, resulting in delayed phenology when the plant is under stress. The duration and timing of most crop phases are determined by genotype- and axis-specific, fixed thermal time values input in the millet.par file. Sowing to germination is dependent on soil water levels; the phase germination_to_emergence includes an effect of sowing depth on the thermal time target; and the phase between end_of_ juvenile and floral initiation is determined by a cultivar's photoperiod (daylength) sensitivity - note that pearl millet is a short-day plant. The crop phases from germination to maturity and their thermal time duration for cv. BJ104 (main shoot) are listed below. tt(germ to emerg) = 10.7 Cd+ (sowing depth * 1.17) Cdays (sowing depth in mm) tt(emerg_end_juvenile) = 239 Cdays tt(end_juvenile_floral-intiation) = 112 * active photoperiod Cdays (base photoperiod 12.9 h) tt(emergence_to_flag leaf) = leaf number * 36.4 Cdays tt(flagleaf_to_flowering) = 66.1 Cdays tt(flowering_to_start-grainfill) = 80 Cdays tt(flowering_to_maturity)= 457 Cdays tt(maturity to harvest-ripe) = 1 Cdays
The period between flowering and maturity is divided into three phases. The first phase, which covers the period from flowering to the start of grain filling, is genotype-specific (see above). The third phase is the period from end of grain filing until maturity, and is set to 5% of the total period. The actual grain growth phase is finally calculated as the difference between the duration of the total period and the other two phases. The final leaf number on the main shoot is calculated as the sum of the number of leaves present in the seed (four) and the product of the time from germination to end juvenile and the leaf initiation rate (27.2 Cd/leaf). For tillers, however, leaf number is estimated from the leaf number on the main shoot, as detailed data on time from initiation to end juvenile are not available for tillers. In general, tiller 1 (which appears from axil of leaf 3) has 4 leaves less than the main shoot.

Each day two estimates of the daily biomass production are calculated, one limited by available water for transpiration (eqn. 1), and the other limited by radiant energy (eqn. 2). The minimum of these two estimates is the actual biomass production for the day dlt_dm_transp = sw_supply_sum * millet_transp_eff (1) In this equation, sw_supply_sum is the total water supply over all soil layers where roots are present. Transpiration efficiency (TE) is derived from the TE coefficient and the vapour pressure deficit (vpd), which in turn is estimated from daily temperatures.
dlt_drymatter_potential = rue *radiation_interception (2) Radiation use efficiency (RUE) is calculated as: rue = rue(current_phase) * millet_rue_reduction (3) rue(current_phase) is 1.9 before anthesis and 1.4 thereafter. The rue reduction is a factor that incorporates temperature and nitrogen stresses. Radiation interception is a function light interception by the crop and daily radiation.
Daily biomass production is partitioned to different plant parts; the ratios depend on the crop stage. Roots are grown daily in a fixed proportion to the tops production. This proportion (root shoot ratio) is specified for each growth stage and declines from 1.0 beforel panicle initiation to 0.0 from the start of grain filling onwards: eme juv PI flag flow 1 1 0.33 0.33 0.087 Between emergence and panicle initiation , 67% of the biomass is allocated to the leaves, and 33% to the stems, which include the leaf sheath. Between panicle initiation and flag leaf , stem elongation and flower development start. Therefore, partitioning to leaves declines linearly from 67% at panicle initiation to 0% at flag leaf. If the amount of carbon partitioned to leaves is more than is required for the calculated increase in leaf area (the leaves have a maximum thickness) then the residual is partitioned to flowers and stems: dlt_dm_green(flower) = (dlt_dm_axis - dlt_dm_green(leaf)) * frac_stem2flower (4) where frac_stem2flower is set to 0.19. dlt_dm_green(stem) = dlt_dm_axis - (dlt_dm_green(leaf) + dlt_dm_green(flower)) (5) If the carbon partitioned to leaves is insufficient to grow the potential increase in leaf area, leaf area increase is reduced (see leaf area development section). Between flag leaf and start of grain filling, only stems and flowers grow. It is assumed that 19% of the produced dry matter is allocated to flowers and 81% to stems. Between the start of grain filling and maturity, biomass is partitioned to grains, whereas stems will continue growing if they can. Grain demand for carbohydrate (biomass) is driven by grain number and grain growth rate. Grain number is a function of the rate of dry matter accumulation between the flag leaf stage and the start of grain filling. Grain growth rate is limited by temperature and drought stress. It is genotype specific and thus accounts for genotypic differences in grain mass and harvest index.
Biomass retranslocation
If the grain demand for carbohydrate cannot be met through partitioning of daily biomass production, it is retranslocated from other plant parts to meet (if possible) this grain demand. The carbohydrate in stem and leaf that is available for transfer, is calculated from the difference between potential and minimum weight for stem and leaf. Dry matter is first translocated from the stems; if not all the demand can be met, the remaining dry matter will be translocated from the leaves.
Leaf development
Potential leaf area. Potential crop leaf area is simulated from the area of individual leaves. Leaf area might be reduced if insufficient dry matter is produced in the subsequent routine on biomass accumulation. First, leaf area is initialised at emergence and the final leaf number (on an axis) is calculated. Final leaf number is calculated at panicle initiation, but an approximate number is set at germination to allow other calculations to proceed until the correct number is known. The number of fully expanded leaves throughout the season is calculated from the appearance rate of fully expanded leaves, which is set at 36.4 Cdays. An adjustment in leaf number is made to account for the area of the expanding leaves. Individual leaf area is calculated from a cubic function: Y=Y 0 exp(a(X-X 0 ) 2 +b(X-X 0 ) 3 ) (6) where Y = mature leaf area of individual leaf, Y 0 = mature area of largest leaf, X 0 = position of largest leaf, a = empirical constant determining the breadth of the leaf area profile curve, b = empirical constant determining the skewness of the leaf area profile. The four coefficients (X 0 , Y 0 , a, b) are functions of final leaf number. Parameter Y 0 is genotype-, density-, and axis-specific, whereas the other parameters are mainly axis-specific. Because of sensitivity of cell expansion to water deficits, leaf area development is reduced under drought stress. Actual leaf area . The actual LAI is less than the potential if there is not sufficient biomass partitioned to leaves on that day. The maximum specific leaf area (sla_max) defines the maximum leaf area (m 2 ) that can be expanded per gram of leaf biomass. The maximum SLA is set to 650 cm 2 /g 1 if LAI (for an individual axis) < 2, and declines linearly to 450 cm 2 /g 1 if LAI (for an individual axis) drops from 2.0 to 5.0. Leaf senescence. The number of senesced leaves on an axis is a linear function of time, although the slope of the function is higher before flag leaf stage (0.0167 leaves/Cd) than after (0.0120 leaves/Cd). The slopes are independent of genotype and axis, but the onset of senescence is later in tillers than in the main shoot. The senesced leaf area (as a function of age) for each axis is calculated from the senesced leaf number. In addition, senesced leaf area is calculated as a function oflight competition, water stress, and temperature stress. The maximum of these four is used as the actual leaf area that has sensesced during that particular day.
Tillering
Tiller appearance . Tillering starts at 150 o Cd, at a rate of 34 o Cd per tiller. Tillers may appear until flag leaf stage, but the maximum tiller number is set to 5. A switch gives the option to make tillering a function of thermal units or dry matter. At the moment, it is driven by thermal units. The rate of tiller appearance is not dependent on genotype, as genotypic differences in tillering are a result of differences in tiller survival, rather than tiller appearance. Tiller death . Tillers that capture insufficient resources to produce a panicle are killed at the start of grain filling. The mechanism employed is barrenness, a condition where the tiller will not set any grain, because the average growth rate between flag leaf and start grain filling is below a critical value, which is currently set at 0.10 g/plant/day.
Regrowth
There are no regrowth routines in millet
Water uptake
To determine the amount of water supply to the crop on any day, first the total available water above the lower limit for all soil layers with roots is summed (eqn. 7). If roots are only partially through a layer, available soil water is scaled to that portion that contains roots. The kl constant (value differs for each soil layer) is then used to limit the amount of water available on any day (eqn. 8). The kl factor is empirically derived, incorporating both plant and soil factors which limit rate of water uptake. Figure 1 shows how kl limits water uptake as soil water approaches the lower limit. do layer = 1, deepest_layer (do loop to calculate available water for all layers) sw_avail = sw(layer) - ll (layer) (7) sw_supply(layer) = sw_avail * kl (layer) (8)
Fig. 1.
Relationship between water availability and rate of water extraction as determined by the kl value. Soil water demand is calculated as in the biomass accumulation' section above where potentail biomass production is a function of light interception and rue (eqn. 3). This potential biomass production is converted to water demand using transpiration efficiency. sw_demand = dlt_dm_pot / millet_transp_eff (9) Water uptake is the minimum of the supply and demand.

Soil water deficit factors are calculated to simulate the effects of water deficits on different plant growth processes. Three water deficit factors are calculated which correspond to three plant processes each having different sensitivity to water stress: photosynthesis (photo), phenology (pheno), and leaf-expansion (expansion). The effect of water deficits on phenology is a function of the water availability ratio, which is calculated by dividing the available soil water (soil water (sw) lower limit (ll)) by the potential available soil water (drained upper limit (dul) - lower limit (ll)) (Fig 2a). A factor of 0 is complete stress and 1 no stress. For photosynthesis and leaf expansion , the effect of water deficits is a function of the soil water demand ratio, which is calculated as the soil water supply divided by the demand (Fig. 2b). The relationships in Fig. 2b reflect the greater sensitivity of leaf expansion (as compared to photosynthesis) to drought.
Fig. 2. a.
Soil water deficit factor for phenology as a function of the soil water availability ratio. b) soil water deficit factors for photosynthesis and leaf expansion as a function of soil water supply/demand ratio.
Nitrogen uptake and retranslocation

In order to calculate nitrogen demand today, first potential biomass production is re-calculated unlimited by water, nitrogen or temperature i.e. as a function of rue and radiation-interception (eqn. 3). This dry matter (biomass) is then partition into plant parts according to their current relative weights. The millet module has a defined minimum, critical and maximum N concentration for each plant part. Demand for nitrogen in each part attempts to maintain nitrogen at the critical (non stressed) level. Nitrogen demand on any day is the sum of the demands from the pre-existing biomass of each part required to reach critical N content, plus the N required to maintain critical N concentrations in today's potentially assimilated biomass. A nitrogen uptake maximum is defined as the nitrogen uptake required to bring all plant part N contents to the maximum allowable concentration. Nitrogen supply is the sum of nitrogen available via mass flow (eqn. 10) and by diffusion (eqn. 11). no3_massflow (layer) = no3_conc * delta_sw (layer) (eqn. 10) no3_diffusion (layer) = no3_conc * sw_avail_frac (eqn. 11) where sw_avail_frac is ratio of extractable soil-water over total soil-water. The layer values are summed to root depth. If nitrogen demand cannot be satisfied by mass flow then it is supplied by diffusion. Uptake of N above the critical concentration can only occur through mass flow. Excess N can be stored in plant parts as concentration above the critical N-concentration but below the maximum concentration. Nitrogen available for uptake is distributed to plant parts in proportion to their individual demands. Nitrogen for grain is retranslocated from other plant parts and is thus not directly taken up from the soil or atmosphere to meet grain demand. Nitrogen is available for retranslocation from all parts except grain and roots; all other plant parts will translocate nitrogen until they reach their defined minimum N concentration. Grain nitrogen demand is again driven by critical N content but this demand is lowered if the plant is under N stress. Grain N demand is also affected by temperature and water stress using eqns. 12
and 13 below: N_grain_temp_fac = 0.69 + 0.0125 * aver_temp (eqn. 12) N_grain_sw_fac = 1.125 0.125 * millet_swdef (expansion) (eqn. 13) The greatest of these two factors is multiplied by the previously calculated N demand i.e. if temperature is high or drought occurs, the N demand will be increased above the level required to reach the critical N concentration.
N fixation
No N fixation is assumed to occur (N fixation rate = 0.0). Nitrogen deficits affecting plant growth N availability factors (0-1) are calculated for the following processed: 1) grain N potential, 2) photosynthesis, 3) leaf senescence, grain N concentration, and cell expansion, 4) grain number. The N-concentration ratio which is calculated for the stover (stem + leaf) in eqn 14 is used as a measure of N stress: N_conc_ratio = (N_conc_stover - N_conc_stover_min) / (N_conc_stover_crit N_conc_stover_min) (eqn.14) Different constants are used to convert this ratio to a deficit factor for each of the processes: N_def = N_fact_(process) * N_conc_ratio (eqn. 15) where N_factor equals 1.25 (photosynthesis), 1.0 (grain concentration), 10.0 (phenology). As lower values of N_deficiency indicate more stress, phenology is least sensitive to nitrogen deficiency and grain N the most.

Root depth is initialised at 110 mm. Between emergence and grain filling, the increase in root depth is a daily rate (20 mm/day) multiplied a soil water availability factor. Root depth is constrained by the soil profile depth. Growth of root biomass is unrelated to depth and is as described in the biomass partitioning' section above. Roots are not senesced during the life of the crop, but are incorporated in the soiln2 module at harvest and distributed as fresh organic matter in the profile according to an exponential relationship of depth and root biomass.
Temperature stress
There are no generic temperature factors, as for water and nitrogen stress, but as discussed in sections above temperature does influence grain N content, rate of senescence and radiation use efficiency (rue).
Plant death
All or some of the plants can be killed due to a variety of stresses; If the crop hasn't germinated within 40 days of sowing, due to lack of germinating moisture, all plants are killed. If the crop does not emerge with 150 o Cdays of germination, because it was sown too deep, then all plants are killed. If crop is past floral initiation and LAI = 0, then all plants are killed due to total senescence. If the cumulative phenological water stress factors exceed 99, all plants are killed due to water stress prolonging phenology. In addition, a fraction of the total number of plants can die due to: high soil surface temperatures immediately following emergence. drought stress, if a critical leaf number (set to 10) has not yet been reached. barrenness at the start of grain filling.
Detachment
The detachment routines in millet are disabled in the current code.
MILLET MODULE PARAMETERISATION

Crop lower limit and kl values are need for each soil layer extraction icrisat_alf1.millet.parameters ll = 0.146 0.207 0.244 0.236 0.218 0.173 0.173 (mm/mm) ! millet lower limit kl = 0.120 0.120 0.120 0.100 0.060 0.055 0.030 () ! rate of soil water extraction extraction icrisat_alf2.millet.parameters ll = 0.066 0.090 0.117 0.123 0.129 0.137 0.148 (mm/mm) ! lower limit extraction jodhpur_aridisol.millet.parameters ll = 0.040 0.043 0.043 0.043 0.040 0.040 0.040 (mm/mm) ! millet lower limit kl values here are same as for icrisat_alf1. Needs to be changed for sandy soil texture of soil at Jodphur. Phenology parameters needed for each cultivar: default.millet.bj104 tt_emerg_to_endjuv = 239.4 (Cd) ! TT from emergence to end of juvenile phase est_days_emerg_to_init = 17 (d) ! estimated days from emergence to floral init. pp_endjuv_to_init = 112.4 ( Cd/h) ! photoperiod sensitivity tt_flower_to_maturity = 457.0 ( Cd) ! TT from flowering to maturity tt_flag_to_flower = 66.1 ( Cd) ! TT from flag leaf to flowering tt_flower_to_start_grain =
80.0 ( Cd) ! TT from flowering to start grain fill tt_maturity_to_ripe = 1 ( Cd) ! TT from maturity to harvest ripe
Leaf area parameters needed for each cultivar:

y0_const = -12390.0 () ! intercept with y-axis of regression of the area of the largest leaf on total leaf number y0_slope = 1710.0 () ! slope of regression of the area of the largest leaf on total leaf number Grain yield parameters needed for each cultivar: hi_incr = 0.0 (1/day) ! rate of HI increase (optional) hi_max_pot = 0.55 () ! maximum harvest index head_grain_no_max = 3300.0 (grain/head) ! potential grains per head grain_gth_rate = 0.61 (mg/grain/d) ! potential grain growth rate All the above parameters are genotype specific, whereas tt_emerg_to_endjuv , y0_const, and y0_slope are also axis dependent.
MODULE DEPENDENCIES
The minimum module configuration required to run millet in APSIM is the inclusion of the report, input, manager, soilwat2, soiln2, canopy, residue2, and millet modules. Operations are desirable in the case of validation runs to input observed data on crop management. Within the manager file, the following syntax is used for the millet crop: if (day = 171 and year = 1995) then millet sow plants = 6.7, sowing_depth = 30, cultivar = wrajpop crop_in = 1 endif if (millet.stage_name = 'initiate' or millet.stage_name = 'emergence') then tiller0_finished = 1 endif if (millet1.stage_name = 'initiate' or millet1.stage_name = 'emergence') then tiller1_finished = 1 endif if (millet2.stage_name = 'initiate' or millet2.stage_name = 'emergence') then tiller2_finished = 1 endif if (millet3.stage_name = 'initiate' or millet3.stage_name = 'emergence') then tiller3_finished = 1 endif if (millet4.stage_name = 'initiate' or millet4.stage_name = 'emergence') then tiller4_finished = 1 endif if (millet5.stage_name = 'initiate' or millet5.stage_name = 'emergence') then tiller5_finished = 1 endif if (millet.stage_name = 'harvest_ripe' and millet.plant_status = 'alive') or (millet.stage_name = 'end_crop' and millet.plant_status = 'dead') or (tiller0_finished = 1 and millet.plant_status = 'out') then millet harvest millet kill_crop millet end_crop residue2 tillage_type = burn tiller0_finished = 2 endif This is repeated for each tiller if (tiller0_finished = 2 and tiller1_finished = 2 and tiller2_finished = 2) and (tiller3_finished = 2 and tiller4_finished = 2 and tiller5_finished = 2) then crop_in = 0 tiller0_finished = 0 tiller1_finished = 0 tiller2_finished = 0 tiller3_finished = 0 tiller4_finished = 0 tiller5_finished = 0 endif
MILLET MODULE OUTPUTS

The following millet variable can be output for each axis through the report module (list needs to be checked for millet) Variable Name Units Description plant_status status of crop stage current phenological stage stage_code stage_name crop_type leaf_no number of fully expanded leaves leaf_no_dead no of dead leaves leaf_area (max_leaf = 1000) mm 2 leaf area of each leaf height mm canopy height root_depth mm depth of roots plants plants/m 2 plant density grain_no grains/plant grain number grain_size g individual grain wt cover_green 0-1 fraction of radiation reaching the canopy that is intercepted by the green leaves of the canopy cover_tot 0-1 total crop cover fraction lai_sum leaf area index of all leaf material live + dead tlai tot lai slai area of leaf that senesces from plant lai m 2 /m 2 live plant green lai tlai_dead m 2 /m 2 total lai of dead plants root_wt g/m 2 root biomass leaf_wt g/m 2 leaf biomass stem_wt g/m 2 stem biomass grain_wt g/m 2 grain biomass dm_green (max_part = 6) g/m 2 live plant dry weight (biomass) dm_senesced (max_part = 6) g/m 2 senesced plant dry wt dm_dead (max_part = 6) g/m 2 dry wt of dead plants yield kg/ha grain yield dry wt biomass kg/ha total above-ground biomass dlt_dm g/m 2 the daily biomass production dlt_dm_green (max_part = 6) g/m 2 plant biomass growth n_green (max_part = 6) g/m 2 plant nitrogen content n_senesced (max_part = 6) g/m 2 plant n content of senesced plant n_dead (max_part = 6) g/m 2 plant n content of dead plants dlt_n_green (max_part = 6) g/m 2 actual n uptake into plant dlt_n_retrans (max_part = 6) g/m 2 nitrogen retranslocated out from parts to
grain dlt_n_detached (max_part = 6) g/m 2 actual n loss with detached plant dlt_n_dead_detached (max_part = 6) g/m 2 actual n loss with detached dead plant swdef_pheno water deficit factor for phenology swdef_photo water deficit factor fo photosynthesis swdef_expan water deficit factor for leaf expansion ep (num_layers) mm water uptake in each layer cep mm cumulative water uptake sw_demand mm total crop demand for water sw_supply mm total supply over profile esw_layr (num_layers) mm plant extractable soil water n_conc_stover % sum of tops actual n concentration n_conc_crit % sum of tops critical n concentration n_grain_pcnt % grain n concentration percent n_uptake_grain kg/ha n uptake by grain n_uptake kg/ha cumulative total n uptake by plant n_uptake_stover kg/ha n uptake by stover no3_tot g/m 2 total no3 in the root profile n_demand g/m 2 sum n demand for plant parts n_supply g/m 2 n supply for grain n_supply_soil g/m 2 n supply from soil nfact_photo N deficit factor for photosynthesis nfact_grain N deficit factor for grain N content
MILLET MODULE VALIDATION

The millet module was developed validated on a limited set of data collated mainly from onstation experiments at ICRISAT research station at Patancheru , India , and the CAZRI research station at Jodhpur , India . The validation data sets were largely independent of the development data set (van Oosterom et al., 2001b). For most of the recent experiments (1995 onwards), soil chemical and physical characteristics are available. For most of the older data sets, however, this was not the case, and experiments were simulated assuming a fixed amount of water or nutrients being available in the soil. Since most of these experiments were supposedly non-limiting in water and nutrients, and since in most experiments received abundant rainfall and fertilizer, this should not have been a major problem.
Fig 3.
Simulation of grain yield, biomass, and LAI for BJ 104, grown at Patancheru in 1982 at densities of 4 (left) and 29 (right) plants /m 2 .
Fig. 4.
Simulation of grain yield, biomass, and LAI for BJ 104, grown at Patancheru in 1986 under normal daylength of 14 h (left) and extended daylength of 15.5 h (right). In general, the model adequately captured the effects of density (Fig. 3), daylength (Fig. 4), genotype (Fig. 5) and Nsupply (Fig. 6) on biomass accumulation, grain yield, and LAI. The results of Fig. 6 are particularly encouraging; whereas as most of the model development work was carried out at Patancheru (alfisols), in de absence of nitrogen and water stress, Fig. 6 shows an adequate simulation of the effects of N-stress at Jodhpur (sandy soils)
MILLET MODULE ISSUES

Biomass partitioning Panicle initiation is used as the trigger for the onset of stem elongation. In reality, however, the onset of stem elongation is not related to panicle initiation; the occurrence of panicle initiation is more sensitive to variation in daylength than the onset of stem elongation. Onset of stem elongation can therefore better be expressed relative to anthesis. Work on this issue is currently (December 2000) ongoing to better pinpoint the trigger for the onset of stem elongation.
Tiller death
Non-productive tillers cease producing leaves during stem elongation, but the size of the leaves that are prodcued is very similar to the leaf size of productive tillers. Hence, the low leaf area of non-productive tillers is a result of a reduction in leaf number, rather than leaf size. In the module, non-productive tillers die at anthesis due to barreness. They thus produce the same number of leaves as productive tillers, and the low leaf area in the module is thus a result of a reduction in leaf size. Although the module simulates the low leaf area of nonproductive tillers adequately (Fig. ), the mechanisms behind the simulation are a simplification of reality.
Tiller number
The millet module simulates a maximum of five tillers. Although more tillers are produced throughout the life cycle of the crop, especially if secondary tillers are considered, most of these tillers become non-productive even at low plant densities (Craufurd and Bidinger, 1988a). Their contribution to total GLAI is expected to be relatively small and that to biomass even smaller, as these non-productive tillers do not elongate. They will hence contribute little to photosynthesis, as their leaves are located at the bottom of the canopy. The number of tillers that can be simulated by APSIM-MILLET can be increased, but the errors introduced by simulating a maximum of five tillers are expected to be minor in most circumstances.
MILLET MODULE WORKING GROUP
Peter Carberry, Erik van Oosterom, John Hargreaves, Garry
O'Leary.
Fig. 5.
Simulation of grain yield, biomass, and LAI for a high-tillering genotype (WRajPop, left) and a low-tillering genotypes (RCB-IC 911, right), grown at Patancheru in 1995
Fig. 6.
Simulation of grain yield, biomass, and LAI for a WRajPop, grown at Jodhpur , Rajathan , India , with N-fertiliser of 0 kg/ha (lefl) and 40 kg/ha (right) applied.
CITATIONS
1. Van Oosterom, E.J., Carberry, P.S., O'Leary, G.J. (2001a). Simulating growth, development, and yield of tillering pearl millet. 1. Modeling leaf area profiles on main shoots and tillers. Field Crops Research (submitted Dec. 2000) 2. Van Oosterom, E.J., Carberry, P.S., Hargreaves, J.N.G., O'Leary, G.J. (2001b). Simulating growth, development, and yield of tillering pearl millet. 2. Simulation of canopy development. Field Crops Research (submitted Dec. 2000)
Additional papers that are in preparation:

biomass accumulation and partitioning (documentation of the biomass accumulation and partitioning parameters in APSIM-MILLET. model validation (description and validation of the millet module) response of plant type to N-fertilisation in three contrastinmg locations in Rajasthan (model application paper, to test how different plant types are adapted regions with contrasting rainfall patterns ). Contribution of yield components to yield stability across environments (analyses that show that low- and high-tillering genotypes have different mechanisms to respond to increased assimilate availability).
Configuration Details

Owner Modified by Erik Van Oosterom Date created April 1998 Current version 1.1 Version history Date 22-Apr-98 Version 1.0 Details 1.1 Updated with latest data First version of documentation 11-Dec-00 Storage Network: Web: Development: Archive:
Introduction
The mucuna module was developed Michael Robertson. The reader is referred to the science document for the plant module for a comprehensive description of the processes simulated by APSIM-Mucuna. The paper by Robertson et al. (2004) outlines the science content of the module, and some testing in Malawi. This document outlines some mucuna-specific issues that are not covered by the plant science document.
Notable features of APSIM-MUCUNA

The module simulates the main variety grown in southern Africa - Kalagonda The module does not simulate production from second and further flushes of flowers and pods. APSIM-Mucuna is not phosphorus-responsive, this is currently under development. Crop growth is not sensitive to waterlogging.

There is one crop class. There is one cultivar able to be simulated: mucuna_gen. This cultivar is typical of that found growing under smallholder conditions in southern Africa.
Validation
APSIM-Mucuna has received testing in Malawi only, with factors such as sowing date and soil types. Table 1 summarises module performance reported by Robertson et al (2004). Table 1: Observed (O) and simulated (S) biomass at flowering and maturity and grain yield for velvet bean crops used for model testing. All variables are in kg/ha.
Location Season
DASa
Grain yield O S 2382 2752 1851 2352 1643
Biomass N at maturity O S 256 314 163 117 257 221 270 211 NM 277
Chitala Chitedze Chitedze Lisasadzi Makoka N'gabu
1998-9 1998-9 1997-8 1998-9 1998-9 1998-9
72 202 202 182 181 173
2126 2820 2187 1343 1852
Grain N at Biomass at maturity flowering O S O S 848 1623 96 102 2374 1791 NMc NM 7640 4747 98 83 2401 2628 60 105 2610 923 83 85 2135 1017
Biomass maturit O 6848 10420 5418 5925 8651
8 9 6 8 5
a=days after sowing of maturity harvest b=crop at Chitala suffered late leaf diseases, therefore only sampling at flowering is recorded c NM=not measured
IN Which environments THIS MODULE should be used with confidence?

APSIM-Mucuna can be used with most confidence in southern Africa. No testing has been done elsewhere.
References
MJ Robertson, Sakala W, Benson T, Shamudzarira Z (2004) Simulating response of maize to previous velvet bean (Mucuna pruriens) crop and nitrogen fertiliser in Malawi. Field Crops Research (in press).
Introduction
The mungbean module was developed by Peter Carberry and Michael Robertson . The module is described in the paper by Robertson et al. (2002). The reader is referred to the science document for the plant module for a comprehensive description of the processes simulated by APSIM-Mungbean. This document outlines some mungbean-specific issues that are not covered by the plant science document.The mungbean module simulates mungbean (black gram or green gram).
Notable features of APSIM-MUNGBEAN
The phenology of mungbean cultivars are photoperiod insensitive.
The module does not simulate grain weathering, although some users have simulated the number of rainfall events during pod-fill (using the manager module) and used this as a surrogate of weathering damage. The module does not simulate production from second and further flushes of flowers and pods. APSIM-Mungbean is not phosphorus-responsive, this is currently under development. Crop growth is not sensitive to waterlogging.

There is one crop class.There are 9 cultivars able to be simulated: King, Berken, Satin, Shantung , Emerald, Green Diamond, Delta, Putland, Celera. Cultivars differ in terms of biomass partitioning to grain and phenology.
Figure 1: Performance of the mungbean module (observed versus simulated grain yield in g/m2) against test datasets reported by Robertson et al. (2002).
Validation
APSIM-Mungbean has received testing across the northern Australian wheatbelt, with factors such as cultivars, sowing date, irrigation, soil type, row spacing varying. Papers describing validation of APSIM-Mungbean are by Robertson et al. (2000) and Robertson et al. (2002). The accompanying figure demonstrates the performance of the module against Australian datasets.
In Which Environments Should This Module Be Used With Confidence?

APSIM-Mungbean can be used with a high degree of confidence in northern Australia.
References
Robertson, M.J., Carberry, P.S., Huth, N.I., Turpin, J.E., Probert, M.E., Poulton, P.L., Bell, M., Wright, G.C., Yeates, S.J., and Brinsmead, R.B. 2002. Simulation of growth and development of diverse legume species in APSIM, Australian Journal of Agricultural Research 53:429-446. Robertson, M. J.; Carberry, P. S., and Lucy. M. 2000 Evaluation of cropping options using a participatory approach with on-farm monitoring and simulation: a case study of spring-sown mungbeans. Australian Journal of Agricultural Research. 51:1-12.
What is the Operations Schedule Module?

The operations module is similar to the APSIM manager module in that it allows the user to specify set day and year timing of simulation actions for modules. It is a fixed schedule manager. The benefit it has over the standard manager in these conditions is speed of execution. Because of its fixed style of specification, criteria can be checked and acted upon much more quickly than parsing of user-defined logic statements. Large fixed schedule management data can be quickly specified by the user and brought into APSIM simulation runs.
Introduction Abstract:
A simple temperature driven model of the fruiting dynamics (Hearn & Da Rosa, 1985) was linked to the widely used Ritchie (1972) soil water balance model. The function describing the processes in the fruiting model were made sensitive to solar radiation, water and nitrogen stress and water logging, and a leaf area generator, a boll growth model and an elementary nitrogen model were included. The model does not simulate fibre quality and can simulate skip-row planting configurations.
The Ozcot cotton model of CSIRO Plant Industry has been adapted to APSIM to form the APSIM Ozcot module.
The source code has been provided by - Dr. A.B. Hearn (1) and Mr. M.P. Bange (2) (1) CSIRO, Division of Plant Industry, Cotton Research Unit, P.O.Box 59 , Narrabri, NSW 2390 AUSTRALIA . (2) CSIRO, Australian Cotton Research Institute, P.O.Box 59 , Narrabri, NSW 2390 AUSTRALIA .
Cultivars
There are 20 cultivars able to be simulated: CS50, CS6S, CS8S, DP16, DP61, DP90, Empr, Kwam, L22, L23, S101, S324, Sc34, Sica, ScV1, ScV2, S189, Si14, Siok, V15
References
Hearn, A.B. & G.D. da Roza, 1985 . A simple model for crop management applications for cotton (Gossypium hirsutum L.). Field Crops Research 12: 49 -69 Hearn, A.B., 1994 .
OZCOT: A simulation model for cotton crop management. Agricultural Systems 44: 257-299
Introduction
Some simulations require weather data (or other types of data) to be patched on certain days. For example, to simulate a grower's paddock for a particular season, it is necessary to patch the nearby weather stations rainfall data with the actual grower's rainfall and temperature data. The PatchInput module does this patching automatically, without the need for running external patching tools. An example of where this functionality is used is in the Yield Prophet project. In this project, a grower does a soil sample on a pre-sowing date e.g. 1 April 2004 . During the wheat season, the grower enters their rainfall (from their rain guage) from the 1 April 2004 to the present
day.
The Yield Prophet project then:

Runs APSIM for the last 100 years. They reset the soil status to the measured value on 1 April every year. They then use the PatchInput module to patch the current year (2004) rainfall (from rain guage) and maxt, mint and radn (from the nearest weather station) values over the last 100 years for dates between 1 April and the present date. All climate data after the present day are not patched but left at the historical values. This then gives provides a yield distribution for what could happen on their paddock for the remainder of the season.
Details
The PatchInput module is a derivative of the Input module and thus reads its own data file in exactly the same way as Input. It is specified in the control file like any other module:
module = PatchInput(patch) patch.dat [test]
The data file looks similar to any other APSIM data file:
[test.patch.data] allow_sparse_data = true patch_all_years = false date patch_rain () (mm) 1988/1/10 55 1988/1/15 66 1988/1/20 77 1988/1/25 88
All variables in the data file (except year,day and date) should be prefixed with patch_'. This indicates that the corresponding variable in the Input module will be overwritten with the value in the patch file. In the above example the Input module's variable called rain' will be overwritten with the values from the patch data file. If a patch data file has a constant of patch_all_years = true, then the data will be overwritten on the specified days for all years. If patch_all_years = false, then the data will only be patched in the specific year mentioned. Sparse data, like in the above example, is supported.
Another optional parameter exists to patch other met variables for all years. Eg
[test.patch.data] allow_sparse_data = true patch_all_years = true patch_variables_long_term = maxt mint radn date patch_rain () (mm) 1988-12-30 55 1988-12-31 66 1989-1-1 77 1989-1-2 88
In this example rainfall will be overwritten on the days 30 Dec through to 2 Jan for all years. In addition, because of the patch_variables_long_term' parameter, the values of maxt, mint and radn will be read from the dates 30/12/1988 through to 2/1/1989 and patched over all other years of the climate record.
Examples
An example of how to use the PatchInput module can be found in the sample directory.
Introduction
The peanut module was developed by Michael Robertson with contributions of data from Graeme Wright, RCN Rao and Mike Bell (QDPI) Kingaroy. The module was developed from the original QNUT model (Hammer et al. 1995) with numerous enhancements. The model is described in the paper by Robertson et al. (2002). The reader is referred to the science document for the plant module for a comprehensive description of the processes simulated by APSIM Peanut. This document outlines some peanut-specific issues that are not covered by the plant science document.
NOTABLE FEATURES OF APSIM-PEANUT

The phenology of peanut cultivars is responsive to temperature, but not to photoperiod and vernalisation However, harvest index of peanut cultivar is adversely sensitive to long photoperiods. Water deficit effects on phenology have been incorporated. Account is taken of the energy cost involved in synthesizing the high-energy content grain in peanut. Oil content is not simulated dynamically in response to any cultivar or environmental effects. APSIM-peanut is not phosphorus-responsive, this is currently under development. Crop growth is not sensitive to waterlogging. The module does not simulate the differences between bunch and runner types in terms of canopy expansion and indeterminacy.
CULTIVARS AND CROP CLASSES

There is one crop class. There are 9 cultivars able to be simulated: Early bunch, Virginia bunch, Streeton, McCubbin, Chico, NC7, VB97, Florunner, Conder. Cultivars differ in terms of biomass partitioning to grain and phenology.
WATER DEFICIT AFFECTING PHENOLOGY

Observations made in Burnett district in the Southeast Queensland, Australia and elsewhere, have shown that severe water deficits delayed flowering and maturity of Virginia peanut cultivars. The APSIM peanut model has been parameterised to account for phenological sensitivity to severe water deficits at different stages and a recovery upon this stress being relieved either by rain or irrigation. A water availability ratio is calculated by dividing actual soil water supply (sw ll) by the potential soil water supply (dul ll). This ratio is used in the relationship illustrated in the Figure 1 to derive a stress factor for phenological development. A factor of 0 is complete stress and 1 no stress. This enables slowing down of thermal time addition whenever water availability ratio declines to less than 0.29.
x_sw_avail_ratio = 0.16 0.29 1.0 () ! water availability y_swdef_pheno = 0.55 1.0 1.0 () ! stress index for phenology x_sw_avail_ratio_flower = 0.16 0.29 1.0 () ! water availability y_swdef_pheno_flower = 0.55 1.0 1.0 ()! stress index for flowering x_sw_avail_ratio_grainfill = 0.16 0.29 1.0 () ! water availability y_swdef_pheno_grainfill = 0.55 1.0 1.0 () ! stress index for grain filling
PHOTOPERIOD AFFECTING HARVEST INDEX

Although peanut has been presumed to be day-neutral with respect to flowering, more recently it has been demonstrated that continuous photoperiod significantly reduces harvest index (Rowell et al. 1999). To account for photoperiod effects on harvest index, changes in maximum potential harvest index have been made. The maximum harvest index (pod yield / biomass) under continuous photoperiod (24 h) has been parameterised as 45% and under 1 h photoperiod as 75%.
VALIDATION
The APSIM Peanut has received testing across northern Australia with factors such as cultivars, sowing date, irrigation, soil type, plant population density, and row spacing varying. Figure 2 demonstrates the performance of the module against Australian datasets.
REFERENCES
Hammer GL, Sinclair TR, Boote, KJ, Wright GC, Meinke H, and Bell MJ 1995 A peanut simulation model: I Model development and testing. Agronomy Journal 87, 1085-93. Robertson MJ., Carberry, PS, Huth NI, Turpin JE, Probert ME, Poulton, PL, Bell M Wright GC, Yeates SJ and Brinsmead, RB 2002 Simulation of growth and development of diverse legume species in APSIM. Australian Journal of Agricultural Research 53, 429-446. Rowell T , Mortley DG, Loretan PA, Bonsi, CK and Hill WA 1999 Continuous daily light period and temperature influence peanut yield in nutrient film technique. Crop Science 39, 11111114.
Introduction
The pigeonpea module was developed by Michael Robertson and Peter Carberry at APSRU, and YS Chauhan, R Ranganathan, and G O'Leary of ICRISAT. APSIM-Pigeonpea belongs to the LEGUME family of crop modules in APSIM. The reader is referred to the science document for the legume module for a comprehensive description of the processes simulated by APSIM-Pigeonpea and to Robertson et al. (2001) for parameter derivation and model testing. This document outlines some pigeonpea-specific issues that are not covered by the legume science document.
Notable features of APSIM-PIGEONPEA

The phenology of pigeonpea cultivars are responsive to temperature and photoperiod, but not vernalisation. APSIM-Pigeonpea is not phosphorus-responsive, this is currently under development. Crop growth is not sensitive to waterlogging.

There is one crop class. There are three generic cultivars able to be simulated: extra short duration, short duration and medium duration. A long duration type was not able to be parameterised due to lack of data, however the module owner would be able to give advice on a long duration type if this were required by a user. Cultivar types differ in terms of biomass partitioning to grain and phenology.
Validation
APSIM-Pigeonpea has received testing in Central India , with factors such as cultivars, sowing date, irrigation, soil type, plant population density, row spacing varying. Validation of APSIMPigeonpea is described by Robertson et al. (2001). The accompanying figure demonstrates the performance of the module for grain yield and biomass.
Figure 1: Performance of the pigeonpea module (observed versus simulated grain yield and final biomass in kg/ha) against test datasets reported by Robertson et al. (2001).
References
Robertson MJ, Silim SN, Chauhan YS, Ranganathan R 2000a Predicting growth and development of pigeonpea: biomass accumulation and partitioning. Field Crops Research 70, 89-100. The APSIM Plant Module - (Plant)
Plant module Scope

The Plant module simulates the growth of a number of different species on a daily time-step (on an area basis not single plant). Plant growth in this model responds to climate (temperature, rainfall and radiation from the Met module), soil water supply (from the Soilwat module) and soil nitrogen (from the SoilN module). The Plant module returns information on its soil water and nitrogen uptake to the Soilwat and SoilN modules on a daily basis for reset of these systems. Information on crop cover is also provided to the Soilwat module for calculation of evaporation rates and runoff. Plant tops and root residues are passed' from Plant to the Residue and SoilN module respectively at harvest of the plant crop. Currently, the crops that are included in the Plant module are chickpea, mungbean, cowpea, soybean, pigeonpea, stylosanthes, peanut, faba bean, lucerne, canola, weed, mucuna, lupin, wheat and navybean (Table 1). A list of the module outputs is provided in the Plant module outputs' section listed below. The module will predict on a daily basis: phenological variables (leaf and node appearance, occurrence of stages of development, thermal time progression), leaf area development, nitrogen content and biomass of plant parts (including grain), depth and distribution of roots in the soil profile, root water and nitrogen uptake, water, oxygen and nitrogen deficit stress factors, and nitrogen fixation from the atmosphere.
Plant module History

The Plant module replaces previous modules covering the relevant crops. The module was developed so that disparate pieces of source code residing with different plant modules could be consolidated into the one module, thus cutting down on on-going maintenance costs, source code management, and version control problems. The underlying premise was that the basic physiological principles needed to be simulated were essentially the same across species and that species differences could be captured successfully through different parameter inputs. The functions on which the crop growth module is based originate from a mixture of sources including;
values/functions from published literature/models (e.g. Sinclair, 1986), functions derived directly from experimental data and model calibration to experimental data sets. While the original intent of the Plant module was to simulate legume species, it now simulates nonlegume species such as canola, wheat and weeds . Ownership of the crop species science remains with the original module owners. Documentation of the history of the evolution of the Plant module is available upon request from the module convener, Michael Robertson. Table 1: Plant species simulated by APSIM-Plant
Plant species Species science owner Current Chickpea Michael Robertson CSIRO / APSRU Mungbean Michael Robertson CSIRO / APSRU Cowpea Michael Robertson CSIRO / APSRU Soybean Michael Robertson CSIRO / APSRU Pigeonpea ICRISAT(Gary O'Leary) & CSIRO / APSRU (Peter Carberry) Stylo Peter Carberry CSIRO / APSRU Navybean Michael Robertson CSIRO / APSRU Graeme Wright QDPI Lucerne Michael Robertson CSIRO / APSRU Peanut Mike Bell QDPI Graeme Wright QDPI Michael Robertson CSIRO / APSRU Fababean Michael Robertson CSIRO / APSRU Lupin Michael Robertson CSIRO / APSRU Mucuna Michael Robertson CSIRO / APSRU Canola Michael Robertson CSIRO / APSRU Weed Michael Robertson CSIRO / APSRU Wheat Neil Huth CSIRO / APSRU
Former APSIM module APSIM-Chickpea (Carberry, 1996; Turpin et al., 1998) APSIM-Mungbean (Carberry, 1996) APSIM-Cowpea (Adiku et al. 1993) APSIM-Soybean (Carberry, 1996) None
APSIM-Stylo (Carberry et al., 1996) None
Probert et al. (1998) QNUT
None None None None None APSIM Wheat, APSIM NWheat, APSIM IWheat
Plant module Structure
Plant module Components
Phenology
There are 11 crop stages and 10 phases (time between stages) in the Plant module (Table 2), and commencement of each stage (except for sowing to germination which is driven by soil moisture) is determined by accumulation of thermal time. Table 2: Stages of crop development simulated in the module
Stage code 1 2 3 4 5 6 7 8 9 10 11
Stage name Sowing germination emergence end_of_juvenile floral_initiation flowering start_grain_fill end_grain_fill maturity harvest_ripe end_crop
Each day the phenology routines calculate today's thermal time (in degree days) from 3-hourly air temperatures interpolated from the daily maximum and minimum temperatures. Thermal time is calculated using the relationship in Figure 1 (base temperature, optimum and maximum) with the eight 3-hour estimates averaged to obtain the daily value of thermal time (in growing degree days) for the day. These daily thermal time values are accumulated into a thermal time sum which is used to determine the duration of each phase. Between the stages of emergence and flowering the calculated daily_thermal_time is reduced by water or nitrogen stresses, resulting in delayed phenology when the plant is under stress.
The duration and timing of 6 of the 10 crop phases are determined by fixed thermal time values input in the parameters section of the ini file. Sowing to germination is dependent on soil water levels. If soil water in the soil layer in which the seed is sown is sufficient (specified by pesw_germ ) then germination takes place one day after sowing. The phase germination to emergence includes an effect of sowing depth on the thermal time target. The thermal time target equals a lag period before linear shoot growth starts (shoot_lag ) plus a shoot elongation rate ( shoot_rate ) which determines the thermal time taken to reach the soil surface and emerge. The thermal duration of the phase emergence to end_of_ juvenile in some species is affected by the number of cumulative vernalising days experienced during the period. The relationship between a fraction of a vernalising day and mean daily temperature is specified by the table x_vernal_temp vs y_vernal_days . The phase between end_of_ juvenile and floral initiation is determined by a cultivar's photoperiod (daylength) sensitivity - note that the Plant module can cope with short-day species (e.g. cowpea), long-day species (e.g. chickpea) and species that exhibit the qualitative response (e.g. pigeonpea). The photoperiod sensitivity is specified in the parameters section of the ini file with a table for the relationship between photoperiod and thermal time between end-of-juvenile and floral intiation

Radiation_interception is a function of the fraction of radiation intercepted and daily radiation. The fraction of radiation intercepted is determined by the leaf area index and the extinction coefficient, which varies as a function of row spacing, inter-row skip-row configuration and intra-row skip-plant' configuration. In crop species that produce a significant layer of green photosynthesising pods (eg canola) it is possible to specify the rue, extinction coefficient and specific pod area (that converts pod weight to area) of the pods ( rue_pod, extinct_coef_pod, spec_pod_area ). Each day two estimates of the daily biomass production are calculated, one limited by available water for transpiration (eqn 1), and the other limited by radiant energy (eqn 2). The minimum of these two estimates is the actual biomass production for the day. delta_drymatter_transpiration = soil_ water_ supply * transpiration_efficiency eqn 1. Note: transpiration_efficiency is derived from the transpiration_efficiency_coefficient and the vapour pressure deficit (vpd) estimated from daily temperatures. dlt_drymatter_potential = rue *radiation_interception eqn 2. Note: rue (radiation use efficiency) incorporates temperature, oxygen deficit (waterlogging) and nitrogen stresses. The value of rue is not limited by temperature over a range between the first and second optima. Temperatures outside this range reduce rue to zero at a base and maximum temperature. Rue is linearly interpolated between the phenological stages specified in a table.
Daily biomass production is partitioned to six different plant parts in different ratios depending on crop stage (Table 3). Table 3: Plant parts and their description in the Plant module.
Element in the plant part array
Plant part
Description
1 2 3 4 5 6
root leaf stem pod meal oil
Below-ground fibrous roots Leaf lamina Stem Hull (or pod wall) Grain (or seed) meal, excluding the oil Oil contained in the grain
Roots are grown daily in a fixed proportion to the tops production. This proportion ( ratio_root_shoot ) is specified for each growth stage. On the day of emergence, biomass (and nitrogen) in plant parts are initialised. Between emergence and flowering a proportion of biomass produced ( frac_leaf ) is partitioned to leaf and the remainder to stem. However, if the amount of carbon partitioned to leaves is more than is required for the calculated increase in leaf area (the leaves have a maximum thickness,sla_min ) then the residual is partitioned to stems. Likewise if the carbon partitioned to leaves is too little to grow the potential increase in leaf area, leaf area increase is reduced (see leaf area development section). Between flowering and start-of-grainfill the same procedure is used for determining leaf biomass ( frac_leaf ). Of the remaining carbon a proportion goes to stem and pod in the ratio specified by the parameter frac_pod . Between the start-of-grainfill and maturity biomass is partitioned between grain, pod and stem. Partitioning to grain depends on calculated grain-demand (see below). The pod wall accounts for a fraction of the grain demand ( frac_pod ). If (because grain demand is lower than supply) there is any biomass remaining it goes to leaf as specified by frac_leaf , with the remainder going to stem. In this way if there is low demand for assimilate by grain during grainfill, leaf area may be produced, as occurs in indeterminate species and cultivars. Grain demand for carbohydrate (biomass) is driven using a cultivar-specific daily rate of harvest index (HI) increase ( hi_incr ). The demand for biomass to be partitioned to grain on any day is calculated using HI i.e. the ratio of grain-biomass to tops-biomass. Each day HI is increased by hi_incr until it reaches a maximum hi_max_pot . In species in which there is an energy cost to grain dry weight synthesis (e.g. oilseeds such as soybean), above that which is standard for grain carbohydrate, account must be taken of the extra assimilate required. This is specified by the parameters grain_oil_conc and carbo_oil_conv_ratio (fractional oil content of grain and carbohydrate:oil conversion ratio respectrively), and these are used to calculate the energy used to produce the oil content and accumulate the oil plant part. Energy is not included in the summing of plant parts to give the weight of biomass, but must be accounted for when calculating grain demand for carbohydrate. Grain weight at commercial moisture content (variable = yield-wet) is calculated using the parameter grn_water_cont . Crop height (mm) is a function of stem weight per plant, as specified for each cultivar.
Biomass retranslocation
If the grain demand for carbohydrate cannot be met through partitioning of daily biomass production it is retranslocated from other plant parts to meet (if possible) this grain demand. The Plant module allows a total retranslocation of no more than leaf_trans_frac of leaf weight, stem_trans_frac of stem weight, and pod_trans_frac of podwall weight that is present at the start of grain filling.
Leaf development
On the day of emergence, leaf area per plant ( initial_tpla ) and leaf number per plant ( leaf_no_at_emerg ) are initialised. Node appearance rate per plant is driven by thermal time, specified by the lookup table between x_node_no_app vs y_node_app_rate . Leaf appearance is driven by a number of leaves appearing per node as specified by the x_node_no_leafvs y_ leaves _per_node relationship. Potential LAI is a product of potential leaf number, leaf-size (which is a function of nodal position) ( x_node_no vs. y_leaf_size (mm 2 )), number of plants per m 2 and the water stress factor for expansion (see water deficits section below). Actual LAI is less than the potential LAI if there is not sufficient biomass partitioned to leaf on that day. Maximum specific leaf area ( sla_max ) defines the maximum leaf area (m 2 ) that can be expanded per gram of biomass. sla_max declines with increasing LAI i.e. smaller, younger crops are able to produce thinner leaves.
Leaf senescence
There are four causes of leaf senescence; age, light competition, water stress and frost. The plant senescence routines calculate a senesced LAI for each stress each day and take the maximum of the four values as the day's total senescence. A fraction of the oldest green leaf dies each day after flowering. This senescence due to age occurs a rate of leaves per day. This is calculated from the day's thermal time, the rate of node senescence per o Cd ( node_sen_rate ) and a fraction of the total green leaves on the plant that senesce for each node that is senescing ( fr_lf_sen_rate ). This number of dead leaves is then converted to a senesced LAI. A rate of senescence of other plant parts can also be specified (such as stems) in terms of a fraction of dry weight senesced for each fraction of canopy senesced. Above an LAI of 4.0 light competition causes leaf area to be lost. The LAI senesced because of light competition is related to the amount LAI exceeding lai_sen_light . Water stress during crop growth will cause leaf senescense sensLAI_water_fac = 0.05 * (1 - plant_swdef(photo)) delta_sensLAI_water = LAI * sensLAI_water_fac Note: the calculation of the water stress factor plant_swdef(photo) is descibed in the water deficits' section below. Frost senescence. Low minimum temperatures will cause a linearly increasing loss of leaf area from 0 to 100% respectively, as defined by the relationship between temp_senescenceand senescence_fac . From the values of senesced LAI the Plant module calculates the biomass and nitrogen in that leaf area that is senesced, however a proportion of the carbon and nitrogen of these leaves is retranslocated to stem before senescence.
Regrowth
Depending upon the relative height of harvesting, differing fractions of leaf and stem can be left remaining ( fr_height_cut vs fr_stem_remain ).
Regrowth routines allow growth after harvest in the Plant module. Regrowth in ensured if the parameter min_tpla is set to a value greater than zero. At present this only occurs in the lucerne module. The phenological stage that the crop is set back to upon harvest is specified by the table stage_code vs stage_stem_reduction_harvest . Re-setting of phenology can also occur when the growing point is killed by a kill_stem action. This could be due to frost damage, grazing, herbicide, insect damage. The stage at which phenology is reset to is specified by stage_code vs stage_stem_reduction_kill_stem . In some species harvesting or similar actions cause the module to use a different set of crop_class parameters listed in a separate section of the ini file. The section(s) of the ini file that are read upon the receipt of a particular action are listed at the top of the ini file. For example in lucerne.ini the table: class_action = harvest kill_stem class_change = regrowth regrowth means that a harvest action will cause a change of crop class to regrowth, while a kill_stem action will cause a similar change of crop class.
Water uptake
To determine the amount of water supply to the crop on any day, first the total available water above the lower limit for all soil layers with roots is summed. If roots are only partially through a layer, available soil water is scaled to that portion that contains roots. The kl constant (value differs for each soil layer) is then used to limit the amount of water available on any day. The kl factor is empirically derived, incorporating both plant and soil factors which limit rate of water uptake - it represents the fraction of available soil water that can potentially be taken up on that day from that layer, and values typically vary between 0.01 for deep layers with low root length densities to 0.10 for surface layers with high root length densities do layer = 1, deepest_layer (do loop to calculate available water for all layers) sw_avail = sw(layer) - ll (layer) sw_supply(layer) = sw_avail * kl (layer) Soil water demand is calculated as in the biomass accumulation' section above where potential biomass production is a function of radiation interception and rue . This potential biomass production is converted to water demand using transpiration efficiency. Transpiration efficiency is calculated from the transpiration effieicny coefficient ( transp_eff_cf ), which can vary with growth stage, and vapour pressure deficit. Soil water demand is capped by the atmospheric evaporative demand (eo) adjusted by the proportion of green canopy cover (cover_green) and a crop factor (eo_crop_factor) i.e. eo_crop_factor * eo * cover_green . Water uptake is the minimum of the supply and demand.

Soil water deficit factors are calculated to simulate the effects of water stress on different plant growth processes. Four water deficit factors are calculated which correspond to four plant processes each having different sensitivity to water stress i.e. photosynthesis (photo), phenology (pheno), leafexpansion (expansion) and nitrogen fixation (fixation). A water availability ratio is calculated by dividing actual soil water supply (sw - ll) by the potential soil water supply (dul - ll). This ratio is used in the relationships illustrated in Figure 3a to derive stress factors for nitrogen fixation and phenological development. A factor of 0 is complete stress and 1 no
stress. Likewise, Figure 3b shows the relationship between the stress factors for photosynthesis and leaf expansion and the ratio of supply to demand for soil water.

In order to calculate nitrogen demand today, first, potential biomass production is re-calculated unlimited by water, nitrogen or temperature i.e. as a function of rue and radiation-interception. This dry matter (biomass) is then partitioned into plant parts according to their current relative weights. The Plant module has a defined minimum, critical and maximum N concentration for each plant part. Demand for nitrogen in each part attempts to maintain nitrogen at the critical (non stressed) level. Nitrogen demand on any day is the sum of the demands from the pre-existing biomass of each part required to reach critical N content, plus the N required to maintain critical N concentrations in today's potentially assimilated biomass.. A nitrogen uptake maximum is defined as the nitrogen uptake required to bring all plant part N contents to the maximum allowable concentration. Nitrogen supply is the sum of nitrogen available via mass flow and by diffusion (otherwise known as active uptake). no3_massflow (layer) = no3_conc * delta_sw (layer) no3_diffusion (layer) = sw_avail_frac *no3_conc note: these layer values are summed to root depth and sw_avail_frac is ratio of extractable soilwater over total soil-water. If nitrogen demand cannot be satisfied by mass flow then it is supplied by either diffusion or fixation. The preference by a species for diffusion or fixation is specified by the parametern_supply_preference (options are active or fixation) . Demand can only be exceeded by supply from mass flow (up to the nitrogen uptake maximum). If both mass flow and diffusion supplies can't satisfy demand then nitrogen is sought from N fixation (see next section). Nitrogen available for uptake is distributed to plant parts in proportion to their individual demands. Nitrogen for grain is retranslocated from other plant parts, N is not directly taken up from the soil or atmosphere to meet grain demand. Nitrogen is available for retranlocation from all parts except for grain and roots; other plant parts will translocate nitrogen until they reach their defined minimum N concentration. Grain nitrogen demand is again driven by critical N content but this demand is
lowered if the plant is under N stress. Grain N demand is also affected by temperature and water stress using eqns below. N_grain_temp_fac = 0.69 + 0.125 * aver_temp N_grain_sw_fac = 1.125 - 0.125 * swdef (expansion) The greatest of these two factors is multiplied by the previously calculated N demand i.e. if temperature is high or swdef(expansion) is low (water stressed) the N demand will be increased above the level required to reach the critical N concentration. During leaf senescence, leaf nitrogen is reduced in the newly senesced leaves and the excess is retranslocated to green stem.
N fixation
The daily rate of nitrogen fixation at potential, is a function of the crop N fixing capacity ( N_fix_rate ), which varies with growth stage, crop biomass (i.e. the size of the crop) and soil water stress. N_fixation = N_fix_rate * biomass * swdef (fixation)

There are three N availability factors (0-1), one each for the photosynthesis, phenology and grain filling processes. A N concentration ratio is calculated for the stover (stem + leaf), which is used as a measure of N stress, then different constants are used to convert that ratio to a deficit factor for each of the processes. A factor of 1 is used for affecting grain N concentration, 1.25 for photosynthesis (reduces rue) and 5.75 to slow phenological development. As a value of 1 is no stress and 0 complete stress, phenology is least sensitive to nitrogen deficiency and grain N the most. N_conc_ratio = (N_conc_stover - N_conc_stover_min) / (N_conc_stover_crit - N_conc_stover_min)

Root depth at emergence is initialised at initial_root_depth . Between emergence and grain filling, the increase in root depth is a daily rate ( root_depth_rate ) multiplied by an exploration factor ( xf ), a soil water availability factor for the layer than the deepest roots are currently passing across, and a temperature factor ( x_temp_root_advance vs.y_rel_root_advance ). In severe water deficit the roots depth increase can be slowed and even stopped by the function between sw_supply_demand_ratio and root depth increase, expressed by x_ws_root vs. y_ws_root_fac . The parameter root_depth_rate varies with growth stage and is typically zero after the start of grain filling. Root depth is constrained by the soil profile depth. The amount of biomass partitioned daily to the root system is described in the biomass partitioning' section above. Root biomass is partitioned among the soil layers currently occupied by roots according to three factors: the exploration factor ( xf ), the soil water availability factor, and the root branching factor ( rel_root_rate ). Root biomass is converted to root length using the parameter specific_root_length (currently assumed as 60000 mm/g for all species). Roots are senesced during the life of the crop (0.005 of the length in each layer per day), and are immediately detached and sent to the SoilN module. At harvest all roots senesce and distributed as fresh organic matter in the profile according to their distribution on the day of harvest.
Oxygen deficits (waterlogging) affecting plant growth
Oxygen deficit (waterlogging) affects photosynthesis. The oxygen deficit stress factor is calculated as the fraction of the whole plant root length that is exposed to water contents above the drained upper limit (i.e. near-saturated soil conditions). Temperature stress There are no generic temperature factors, as for water and nitrogen stress, but as discussed in sections above temperature does influence grain N content, rate of senescence and radiation use efficiency (rue).
Plant death
All or some of the plants can be killed due to a variety of stresses; If the crop hasn't germinated within 40 days of sowing, due to lack of germinating moisture, all plants are killed. If the crop does not emerge with 150 o Cdays of sowing, because it was sown too deep, then all plants are killed. If crop is past floral initiation and LAI = 0, then all plants are killed due to total senescence. If the cumulative phenological water stress factors exceed 25, all plants are killed due to water stress prolonging phenology. A fraction of plants will be killed by high temperatures immediately following emergence. A fraction of plants can be killed by a kill_stem action from the manager to simulate the effect of severe frost. A specified fraction of plants can be killed by a kill_crop action from the manager.
Detachment
In the module the user can specify the fraction detached from each part of a dead plant or senesced pool per day. Currently, only senesced roots are assumed to be detached.
Plant Module Parameterisation

Crop lower limit, kl values, and exploration factor ( xf ) values are need for each soil layer. An optional parameter uptake_source can also be specified for simulations where the uptake of water and solutes (in this case NO 3 ) is calculated by another module in APSIM. The possible setting for this parameter are 'calc' (= calculate own uptakes) or 'apsim' (= get uptake data using the APSIM messaging system). The default value of 'calc' is used in the absence of the parameter specifier. test. cowpea.parameters uptake_source = calc ! calculate uptake of water and nitrate ll = 0.200 0.200 0.200 0.220 0.250 () ! crop lower limit kl = 0.08 0.06 0.04 0.02 0.01 () ! kl need calibrating for each crop and soil type xf = 1.00 1.00 1.00 1.00 1.00 (0-1) ! exploration factor for root growth Cultivar parameters are needed, and are specified in the ini file. The example below is for cowpea cv. Banjo. standard.cowpea.banjo
x_pp_hi_incr y_hi_incr x_hi_max_pot_stress y_hi_max_pot cum_vernal_days
= = = =
1 24 (hours) 0.014 0.014 (1/days) 0.0 1.0 () 0.6 0.6 ()
! photoperiod ! rate of HI increase ! average stress at flowering ! maximum harvest index potential
= 0 100
tt_emerg_to_endjuv est_days_emerg_to_init x_pp_endjuv_to_init y_tt_endjuv_to_init
= 552.0 552.0 (oCd) = 20 = 13.3 18.0 = 0 229 (days) (hours) (oCd)
x_pp_init_to_flower = Y_tt_init_to_flower = x_pp_flower_to_start_grain y_tt_flower_to_start_grain = x_pp_start_to_end_grain y_tt_start_to_end_grain tt_end_grain_to_maturity tt_maturity_to_ripe x_stem_wt y_height Module Dependencies
1 24 (hours) 20.0 20.0 (oCd) 1 24 (hours) 100.0 100.0 (oCd)
= 1 24 (hours) = 280.0 280.0 (oCd) = = = = 20 5.0 0 15 0 1000 (oCd) (oCd) (g/plant) (mm)
! TT from emergence to end of juvenile phase ! estimated days from emergence to floral init. ! photoperiod ! TT from end juvenile to floral initiation ! photoperiod ! TT from initiation to flowering ! photoperiod ! TT from flowering to start grain fill ! photoperiod ! TT from start grain fill to end grain fill ! TT from end grain fill to maturity ! TT from maturity to harvest ripe ! stem weight ! plant height
The minimum module configuration required to run plant in APSIM is the inclusion of the clock, report, met, manager, Soilwat, SoilN and residue modules. Within the manager file the following syntax is used for harvest and planting the plant crop. For example, using the cowpea instantiation of plant: if (cowpea.stage_name = 'harvest_ripe' and cowpea.plant_status = 'alive') then cowpea harvest cowpea kill_crop cowpea end_crop endif if (cowpea.plant_status = 'dead') then report do_output cowpea harvest cowpea end_crop endif if (day > 120 and day < 240 and cowpea.plant_status = status_out ) then cowpea cowpea sow cultivar = banjo, plants = 25 (/m2), sowing_depth = 40 (mm) endif (note: row_spacing in sowing command is optional and the units are mm - the units were m in previous plant modules).
PLANT MODULE OUTPUTS

The following Plant variable can be output through the report module
Variable Name plant_status stage dlt_stage stage_code stage_name crop_type crop_class dlt_tt phase_tt (max_stage = 12) tt_tot (max_stage = 12) days_tot (max_stage = 12) das
flowering_date flowering_das
maturity_date maturity_das
leaf_no (max_node = 1000) node_no (max_stage = 12) dlt_leaf_no dlt_node_no leaf_no_dead (max_node = 1000) leaf_area (max_leaf = 1000) height root_depth plants cover_green cover_tot lai_sum tlai
Units Description characterStatus of crop (e.g. alive, dead, out) Current phenological stage (real value) Daily increase in phenological stage Current phenological stage (integer value) Current phenological stage (description) charactercrop type (e.g. mungbean, chickpea, cowpea, etc) crop class (e.g. plant, regrowth, etc) o Cd Daily increase in thermal time o Cd Thermal time target for each phenological phase o Cd Thermal time elapsed for each phenological phase d days elapsed for each phenological phase days Days since sowing after sowing day of Flowering date year days Flowering date after sowing day of Maturity date year days Maturity date after sowing number of fully expanded leaves during each node development number of nodes on the mainstem, developed in each phase daily increase in number of leaves daily increase in number of nodes no of dead leaves in each phenological phase mm 2 leaf area of each leaf mm canopy height mm depth of roots plants/m plant density 2 0-1 fraction of radiation reaching the canopy that is intercepted by the green leaves of the canopy 0-1 total crop cover fraction m 2 /m 2 leaf area index of all leaf material live + dead m 2 /m 2 total lai (senseced plus green)
slai lai tlai_dead root_wt leaf_wt stem_wt pod_wt grain_wt dm_green (max_part = 6)
m 2 /m 2 area of leaf that senesces from plant m 2 /m 2 live plant green lai m 2 /m 2 total lai of dead plants g/m 2 root biomass g/m 2 leaf biomass g/m 2 stem biomass g/m 2 pod biomass g/m 2 grain biomass g/m 2 live plant dry weight (biomass) of each plant part dm_senesced (max_part = 6) g/m 2 senesced plant dry wt of each plant part dm_dead (max_part = 6) g/m 2 dead plant dry weight of each plant part yield kg/ha grain yield dry wt biomass kg/ha total above-ground biomass green_biomass kg/ha total above-ground biomass of green material biomass_wt g/m 2 total above-ground biomass dlt_dm dlt_dm_green (max_part = 6) dlt_dm_green_retrans (max_part = 6) dlt_dm_detached (max_part = 6) dlt_dm_dead_detached (max_part = 6) n_green (max_part = 6) n_senesced (max_part = 6) n_dead (max_part = 6) dlt_n_green (max_part = 6) dlt_n_retrans (max_part = 6) dlt_n_detached (max_part = 6) dlt_n_dead_detached (max_part = 6) swdef_pheno swdef_photo swdef_expan swdef_fixation oxdef_photo ep cep sw_uptake(max_layer = 100) sw_demand g/m 2 the daily biomass production g/m 2 daily plant biomass growth of each plant part g/m 2 daily plant biomass retranslocation of each plant part g/m 2 daily biomass detached from live plants of each plant part g/m 2 daily biomass detached from dead plants of each plant part g/m 2 plant nitrogen content of each plant part g/m 2 plant n content of senesced plant of each plant part g/m 2 plant n content of dead plants of each plant part g/m 2 actual n uptake into plant of each plant part g/m 2 nitrogen retranslocated out from parts to grain of each plant part g/m 2 actual n loss with detached plant of each plant part g/m 2 actual n loss with detached dead plant of each plant part water deficit factor for phenology water deficit factor fo photosynthesis water deficit factor for leaf expansion water deficit factor for nitrogen fixation oxygen deficit (waterlogging) factor for photosynthesis mm Transpiration (Total water uptake from profile) mm cumulative water uptake mm Water uptake from each profile layer mm total crop demand for water
sw_supply sw_supply_layr(max_layer = 100) esw_layr (max_layer = 100) n_conc_stover
mm mm mm %
Total water supply over profile water supply in each profile layer
plant extractable soil water in each profile layer sum of tops (leaf, stem and pod) actual n concentration n_conc_crit % sum of tops (leaf and stem) critical n concentration n_conc_leaf % actual n concentration in leaf n_conc_stem % actual n concentration in stem n_conc_grain % actual n concentration in grain n_conc_min % minimum n concentration in tops (leaf and stem) n_uptake or biomass_n g/m 2 cumulative total n uptake (minus roots): live, dead & senesced green_biomass_n g/m 2 cumulative total n uptake by live (green) parts (minus roots) n_uptake_stover g/m 2 n uptake by stover (green leaf, stem and pod) no3_tot g/m 2 total no3 in the root profile n_demand g/m 2 sum n demand for plant parts n_supply_soil g/m 2 n supply from soil dlt_n_fixed_pot g/m 2 daily potential N fixation dlt_n_fixed g/m 2 actual daily N fixation n_fixed_tops g/m 2 cumulative N fixed in above-ground biomass nfact_photo N deficit factor for photosynthesis nfact_grain N deficit factor for grain N content rlv (num_layers) mm/mm root length density in soil layer 3 no3_demand kg/ha plant demand for nitrate (when using APSSWIM) root_length (max_layer = 100) mm/mm total root length per unit ground surface area in 2 each profile layer
Validation
The Plant module has been described by Robertson et al. (2002). Previous models covering the species now in the Plant module have been validated by Adiku et al. (1993) (cowpea), Carberry (1996) (chickpea, mungbean, cowpea, soybean), Carberry et al. (1996a,b) (stylosanthes), lucerne (Probert et al. 1998), fababean (Robertson et al., in press), canola (Robertson, et al.,1999) and pigeonpea (Robertson et al., 2002).
This is an instantiable module, that is, it can be used in several contexts within the one simulation. For example, this module may be used to simulate a growing crop, while anotherinstance of this module (configured differently) is used simultaneously to represent a weed growing within that crop. There are certain protocols and procedures that must be followed in order to instantiate modules,
and these are described in more detail in the document Module Instantiation , found in C:\Program Files\Apsim32\docs\shared.
References
Adiku S.K., Carberry P.S. Rose, C. W., McCown, R.L. & Braddock, R. (1993). Assessing the performance of maize (Zea mays - cowpea (Vigna unguiculata) intercrop under variable soil and climate conditions in the tropics. Proceedings of the 7th Australian Society of Agronomy Conference, September 1993, Adelaide , South Australia , p. 382. Carberry, P.S. 1996. Assessing the opportunity for increased production of grain legumes in the farming system. Final Report to the Grains Research and Development Corporation, Project CSC9, 33pp. Carberry, P.S.; Adiku, S.G.K.; McCown, R.L. and Keating, B.A. 1996b. Application of the APSIM cropping systems model to intercropping systems. In: O Ito, C Johansen, JJ Adu-Gyamfi, K Katayama, JVDK Kumar Rao, and TJ Rego (Eds.) Dynamics of Roots and Nitrogen in Cropping Systems of the Semi-Arid Tropics, pp. 637-648. Japan International Research Centre for Agricultural Sciences. Carberry, P.S.; McCown, R.L.; Muchow, R.C.; Dimes, J.P.; Probert, M.E.; Poulton, P.L. and Dalgliesh, N.P. 1996b. Simulation of a legume ley farming system in northern Australia using the Agricultural Production Systems Simulator. Aust. J. Exptl. Agric. 36: 1037-48. Probert, ME, Robertson, MJ, Poulton, PL, Carberry PS, Weston, EJ and Lehane, KJ (1998) Modelling lucerne growth using APSIM. Proceedings of the 1998 Australian Agronomy Conference, Wagga Wagga. Robertson MJ, Carberry PS 1998. Simulating growth and development of soybean in APSIM. Proceedings 10th Australian Soybean Conference, Brisbane 15-17 September, 1998: pp. 130-136. Robertson MJ, Holland JF, Kirkegaard JA, Smith CJ. 1999 Simulating growth and development of canola in Australia . In Proceedings 10th International Rapeseed Congress. 1999 (CD-Rom) (Eds. N. Wratten and P.A. Salisbury). Robertson MJ, Carberry PS, Huth NI, Turpin JE, Probert ME, Poulton PL , Bell M, Wright, GC, Yeates SJ and Brinsmead RB 2002. Simulation of growth and development of diverse plant species in APSIM. Australian Journal of Agricultural Research 53 , 643-651. Sinclair, T.R. 1986. Water and nitrogen limitations in soybean grain production. Field Crops Res. 15: 125-141. J.E. Turpin, M.J. Robertson, C. Haire, W.D. Bellotti, A.D. Moore and I. Rose (in press). Simulating fababean development, growth and yield in Australia . Australian Journal of Agricultural Research.
Operation
The APSIM report module creates a columnar output file to record data from an APSIM simulation. Output files contain data in columns with headers specifying variable names and units. There is an option to create the files in CSV (comma delimited) format, for direct spreadsheet application.
Parameter file settings

The APSIM report module can report the state of any variable available to the system, from any module. The user can specify various reporting parameters and the method for doing this is similar to the initialisation of parameters in any other module.
Instantiation of the Report module
Like all other APSIM modules the report module can be instantiated to allow any number of output files to be created. By specifying an instantiated report module in the control file, you are able to create more output files and populate them with output from your simulation. An example con file may appear as:
[apsim.sample_report] Module=clock report.par[sample]%apsuite\apsim\clock\clock.ini[standard] Module=report (report1) report.par [sample] Module=report (report2) report.par [sample] Module=met DALBY.MET [weather] Module=manager report.par [sample]
This can be referenced in the report.par file as:
[sample.report1.parameters] title = Report Instantiation Sample Simulation file 1 outputfile = report1.out variable = clock.day variable = clock.year variable = met.rain [sample.report2.parameters] title = Report Instantiation Sample Simulation file 2 outputfile = report2.out variable = clock.day variable = clock.year variable = wheat.yield [sample.manager.end_of_day] if days_since_last_report = 5 then report1 do_output report2 do_output endif
Introduction
Some simulations require up to date weather data from a SILO weather station. In the past this meant extracting the required weather file(s) from SILO prior to running the simulation.
This new module automates this process. Now the user can specify the SILOInput module in the control file instead of the INPUT module. In the parameter file the user specifies the SILO station number to use. When APSIM is run, the SILOInput module will then extract the required weather file from SILO and provide the weather data to the APSIM simulation, all without any user intervention.
Here is an example control section

[SILO sample]
title = SILO Sample Simulation module = clock siloinput.par [sample] %apsuite\apsim\clock\clock.ini[standard] module = report siloinput.par [sample] module = siloinput(met) siloinput.par[sample] module = manager siloinput.par [sample] module = SummaryFile siloinput.par[sample] module = Screen siloinput.par[sample]
Note the line specifying SILOInput instead of input. The parameter file for SILOInput looks like this:
[sample.met.parameters] station_number = 15027 ! ROCKHAMPTON DOWNS
See the SILOInput sample for a complete working example.
NOTE:
This module will only work with machines connected to DDCNET in Toowoomba. As a rule of thumb, if you cannot see the machine thor from your windows explorer, you will not be able to use this module.
Description
The APSIM slurp module provides a user-defined sink for soil water that can be used to fill the role of a crop within a simulated system. Inputs for the slurp module consist of plant root (root length profile and extraction potential) and canopy (live LAI, dead LAI, extinction coefficients and canopy height) information. There is also a switch to state whether slurp is to calculate its own soil water uptake or receive this information from another APSIM module. The slurp module can operate in two modes. The first and simplest mode is where the uptake_source is set to 'APSIM'. In this type of operation slurp is simply a provider of information to other modules in the APSIM system that perform extraction of water and solutes (eg APSwim). In the second mode of operation the uptake_source is set to 'calc' and the soil water demand is taken from the soil by SLURP (if adequate reserves exist) and root length is used to partition uptake between layers.
SOI PHASES MODULE

Adding SOI capability to APSIM
Introduction
Many farming decisions are influenced by the long-range climate outlook and specifically by the phases of the SOI (Stone et al., 1996). Examples are, for instance,

the amount of nitrogen fertilizer applied to a crop, deciding whether to double crop or to fallow, investigating if it would be better to grow wheat now or sorghum next spring, investigating if earlier or later sown crops more economical.
There are many more of these decisions. In order to simulate the tactical and strategic responses to SOI conditions, the SOI module was developed that allows conditional systems simulations based on the SOI phases.
Implementation
The SOI Phases module requires an up to date list of soi phases. This is usually comes with your apsim installation as %apsuite\apsim\soi\sample\phases.soi. This source of this file is \\thor\public\met\phases.soi .
To make the module available to APSIM the following line should be added to the configuration (.con) file:
module = soi phases.soi [soi]
Manager Rules
The basic format of the SOI module syntax is:
Soi[<month> or <lag>] = <phase> Where <month> is a month in either numeric format (1,2,3,4.12) or 3-letter month abbreviation (Jan,Feb,Mar.Dec). The full Date will also work, but remember the SOI Phases are monthly values. Where <lag> is a negative or zero numerical value that indicates the number of months prior to the current Date, that we are comparing the SOI Phase to. Eg: -1 is one month prior, -2 is two months prior Where <phase> is the SOI Phase we are comparing to. There are five Phases, 1 to 5: 1 Consistently Negative SOI 2 Consistently Positive SOI 3 Rapidly Falling SOI 4 Rapidly Rising SOI 5 Consistently Near Zero SOI
Examples
! Sow Sorghum if the SOI Phase in February is Consistently Negative </p> If soi[Feb] = 1 then Sorgum sow .. Else Cotton sow . Endif
! Set the Soilwater if the current SOI Phase is Rapidly Rising if soi[0] = 4 then soilwat2 init soilwat2 set sw = 0.344 0.347 0.369 0.33 0.34 0.33 0.345 (mm/mm) endif
Other examples
if soi[-1'] = 1 then ! Notice the inverted commas around the negative value
if soi[15-Oct']= 5 then
if (today = date('15-Oct') AND soi[-2'] = 3) then
Report Rules
The SOI Phases module is used in the Report module as it is in the Manager, with one exception. Because the Report module doesn't use the Manager to parse its variables, lag values (negative numbers) should not be enclosed in inverted commas.
Examples
Module_names = soi Variable_names = soi[Apr] Variable_alias = soi Units = -
Module_names = soi Variable_names = soi[-2] Variable_alias = soi[-2]
Units = -
Description
The SoilN module describes the dynamics of both carbon and nitrogen in soil. The transformations considered in each layer are shown diagramatically in Figure 1. The major difference from the CERES model is that the soil organic matter is divided into two pools ( biom and hum ), the biom pool notionally representing the more labile, soil microbial biomass and microbial products, whilst hum comprises the rest of the soil organic matter. The flows between the different pools are calculated in terms of carbon, the corresponding nitrogen flows depending on the C:N ratio of the receiving pool. The C:N ratios of the various pools are assumed to be constant through time; C:N for biom is specified in the ini file, whilst the C:N ofhum is derived from the C:N ratio of the soil which is an input.
Figure 1. Diagram of transformations occuring in each soil layer Decomposition of biom and hum pools are calculated as first-order processes with the rate constants being modified by factors involving soil temperature and moisture in the layer. The fresh organic matter pool ( fom) is treated as in CERES-Maize (Jones and Kiniry, 1986), and its rate of decomposition also depends on a C:N ratio factor. Mineralisation or immobilisation of mineral-N is determined as the balance between the release of nitrogen during decomposition and immobilisation during microbial synthesis and humification. An inadequate supply of mineral-N to satisfy the immobilisation demand results in a slowing of the decomposition. Both ammonium- and nitrate-N are available for immmobilisation, though ammonium-N is used preferentially. Decomposition of any organic matter pool results in evolution of carbon dioxide to the atmosphere and transfers of carbon to the biom and hum pools. The flows are defined in terms of efficiency coefficients, representing the proportion of carbon retained in the system, and the fraction of the retained carbon that is synthesised into the biom pool (see Table 1 for parameter definitions and values). When biom decomposes there is an internal cycling of carbon (microbes feeding on microbial products). At initialisation, the amounts of hum and biom in each layer are calculated from inputs (oc, finert, fbiom). To allow for slower rates of decomposition of soil organic matter in the deeper soil layers, part of the hum pool is considered to be non-susceptible to decomposition; this is specified as finert,
which typically will increase with depth. Fbiom specifies the biom pool carbon as a fraction of the hum carbon that is subject to decomposition, i.e. fbiom = biom /(hum - inert_c)
Table 1.
Model parameters determining the flows of carbon during the decomposition of the soil organic matter pools and surface residues
Parameter mcn ef_fom fr_fom_biom
Definition C:N ratio of biom pool efficiency of carbon retention when fom decomposes proportion of retained carbon from fom synthesised into biom ef_biom 0.4 efficiency of carbon retention when biom decomposes fr_biom_biom 0.6 proportion of retained carbon from biom resynthesised into biom ef_hum 0.4 efficiency of carbon retention when hum decomposes ef_res 0.4 efficiency of carbon retention when residues decompose fr_res_biom 0.9 proportion of retained carbon from residues synthesised into biom rd_carb 0.2 day -1 maximum decomposition rate for carbohydrate-like C in fom . rd_cell 0.05 day -1 maximum decomposition rate for cellulose-like C in fom rd_lign 0.0095 day -1 maximum decomposition rate for lignin-like C in fom rdbiom 0.0081 day -1 maximum decomposition rate for biom rdhum 0.00015 day - maximum decomposition rate for hum 1
Value 8.0 0.4 0.9
Decomposition of Soil Organic Matter Pools

fom decomposition = Fpool (carbohydrate,cellulose or lignin fraction) X decay rate for a given fraction (rd_carb, rd_cell, rd_lign) X Soil water factor X Soil temperature factor X C:N ratio factor biom decomposition = biom X rd_biom X Soil water factor X Soil temperature factor hum decomposition = ( hum - inert_C) X rd_hum X Soil water factor X Soil temperature factor
The factors affecting the individual decay rates are as follows:

(i) Soil Water.
Figure 2. Water factor affecting mineralisation rates of the various soil organic matter pools.
(ii) Soil Temperature
Figure 3. Temperature factor affecting mineralisation rates of the various soil organic matter pools. C:N ratio
Figure 4. C:N ratio factor affecting mineralisation rate of soil FOM pools is calculated using a modified C:N ratio that includes the mineral nitrogen in the soil layer.
CNR = fom_C / (fom_N + min_N)
Nitrification
Nitrification is assumed to follow Michaelis-Menton kinetics (See Godwin and Jones 1991, though there is error in their equation 14). potential rate = nitrification_pot x NH4 ppm / (NH4 ppm + NH4_at_half_pot) where nitrification_pot (mg N/kg soil/ day) and NH4_at_half_pot (ppm) are specified in the SOILN ini file. Actual daily nitrification is reduced to allow for sub-optimal water, temperature and pH conditions. nitrification rate = potential rate x min (water factor, temperature factor, pH factor) (Unlike CERES, there is no provision for the potential rate of nitrification to change with time to represent a changing microbial population) (i) Soil Water
Figure 5. Water factor affecting the nitrification rate of ammonium in each soil layer.
Figure 6. Temperature factor affecting the nitrification rate of ammonium in each soil layer.
Figure 7. pH factor affecting the nitrification rate of ammonium in each soil layer. Nitrous oxide from nitrification: Note: Nitrous oxide predictions has been tested under a limited range of soil/climate and production systems and although this testing produced sensible results there should still be a higher degree of user caution attached to the predictions. Nitrous oxide (N2O) emission during nitrification (N2Onit) is calculated as a proportion (k2) of nitrified N (Li, 2000; Parton et al., 2001; Li et al., 2007): N2Onit = k2 * Rnit where Rnit is the rate of nitrification (kg N/ha/day). A wide range of values have been adopted for k2 in agricultural soils in other models, potentially reflecting the uncertainty in the process resulting in N2O emissions during nitrification (Li, 2000; Li et al., 2000; Parton et al., 2001; Li et al., 2007). Following Li et al.(2007) we adopt a value of 0.002, but acknowledge that values may be soil-specific. Li, C.S., 2000. Modeling trace gas emissions from agricultural ecosystems, Nutr. Cyc. Agroecosys. 58, 259-276. Li, C., Aber, J., Stange, J., Butterbach-Bahl, K., Papen, H., 2000. A process-oriented model of N2O and NO emissions from forest soils: 1 Model development. J. Geophys. Res. 105(D4). 43694384. Parton, W.J., Holland, E.A., Del Grosso, S.J., Hartman, M.D., Martin, R.E., Mosier, A.R., Ojima, D.S., Schimel, D.S., 2001. Generalized model for NOx and N2O emissions from soils. J. Geophys. Res. 106(D15),17403-17419. Li, Y., White, R.E., Chen, D.L., Zhang, J.B., Li, B.G., Zhang, Y.M., Huang, Y.F. Edis, R., 2007. A spatially referenced water and nitrogen management model (WNMM) for (irrigated) intensive cropping systems in the North China Plain. Ecol. Mod. 203, 395-423.
Denitrification
The code comes from CERES-Maize V1 and has not been modified to allow for biom_c. Under most situations, simulated denitrification rates are small. The sensibleness of the simulations where significant amounts of denitrification occur has not been verified. denitrification rate = 0.0006 x NO 3 x active carbon ppm x water factor x temperature factor where active carbon ppm = 0.0031 x (hum_C ppm + FOM_C ppm ) + 24.5 (i) Soil Water
Figure 8. Water factor affecting the denitrification of nitrate in each soil layer. (ii) Soil Temperature
Figure 9. Temperature factor affecting the denitrification of nitrate in each soil layer.
Nitrous oxide from denitrification:

Note: Nitrous oxide predictions has been tested under a limited range of soil/climate and production systems and although this testing produced sensible results there should still be a higher degree of user caution attached to the predictions. Nitrous oxide (N2O) emission during denitrification (N2Odenit) is calculated by combining predictions of denitrification with the ratio of N2 to N2O emitted during denitrification predicted by the model of Del Grosso et al. (2000): N2/N2Odenit = Max {(0.16 k1), (k1 exp(-0.8 NO3 ppm/CO2)) } * Max {0.1, ((1.5 WFPS) - 0.32) } where, k1 is related to gas diffusivity in soil at field capacity, NO3ppm (g/g) is the nitrate concentration of the soil on a dry weight basis, and CO2 is the heterotrophic CO2 respiration (gC/g soil / day). Del Grosso, S.J., Parton, W.J., Mosier, A.R., Ojima, D.S., Kulmala, A.E., Phongpan, S., 2000. General model for N2O and N-2 gas emissions from soils due to denitrification. Glob. Biogeochem. Cycl. 14, 1045-1060.
Urea hydrolysis:
potential hydrolysis fraction = -1.12 + 1.31xOC + 0.203xpH - 0.155xOCxpH This fraction is bound between 0 and 1. For OC=1% and pH=7 the fraction=0.526 hydrolysis rate = Urea x potential hydrolysis fraction x min (temperature factor, water factor) (i) Soil Water
Figure 10. Water factor affecting the hydrolysis of urea in each soil layer.
Figure 11. Temperature factor affecting hydrolysis of urea in each soil layer.
Soil Temperature
Daily average soil temperature of each soil layer is calculated based on the soil temperature model of EPIC (Williams et al., 1984). A sinusoidal function of day of year is assumed, with subsurface temperature changes lagging behind those at the soil surface. The sinusoidal function is based on mean annual air temperature (tav), annual amplitude in mean monthly air temperature (amp) and latitude (included in met file). The actual surface temperature is calculated from maximum and minimum temperatures, solar radiation and soil albedo. Changes with depth are obtained from an
exponential function of the ratio of depth and a temperature damping depth. This damping depth is a function of the average bulk density of the soil and the amount of water above the lower limit.
Reset
The reset action can be invoked to reset the module to the state specified within the module's input data, which includes the soil's organic carbon components (biom and hum), nitrate, ammonium and urea N, and FOM (specified as root weight). The Reset action is identical to the initialise action used by the simulation engine at the start of the simulation except that a description of the reinitialised state is not printed in the simulation summary file. Where only mineral N concentrations need to be reinitialised the 'set' action is used (See below). APSIM Manager Example: [sample.manager.start_of_day] ! reinitialise soil nitrogen at the beginning of each sowing window If day = 100 then soiln2 reset endif
Initialise
The initialise action has been replaced by the reset action (see above).
Set
The set action is used to reinitialise single mineral N pools within the module (Nitrate, Ammonium or Urea). Only the particular mineral pools are reset. APSIM Manager Example: [sample.manager.start_of_day] ! reinitialise soil mineral nitrogen at given date If day = 100 then soiln2 set no3 = 10 5 1 (kg/ha) soiln2 set nh4 = 10 5 1 (kg/ha) endif or in terms of concentration [sample.manager.start_of_day] If day = 100 then soiln2 set no3ppm = 1.0 1.0 1.0 (ppm) soiln2 set nh4ppm = 1.0 1.0 1.0 (ppm) endif
Summary Report
At initialisation, at series of tables and useful information is printed to the simulation summary file for perusal by the user. These tables can be printed to the summary file at any point during the simulation as a detailed record of the system state at a particular time. APSIM Manager Example: [sample.manager.start_of_day] ! Print out a summary of module state to the summary file If day = 100 then soiln2 sum_report endif
Incorporate FOM
Fresh organic matter can be incorporated into the soil using the incorp_fom action. The amounts of FOM and FON are specified on a layered basis . An optional FOM type can be specified to use any preset fractionations of FOM as specified in the module ini file. A default fractionation is used if type is not specified. FON content can be specified as either an amount or a C:N ratio. APSIM Manager Example: NOTE: actions must be specified as a single line in the manager file rather than as shown below. If day = 100 then soiln2 incorp_fom dlt_fom_type = manure, dlt_fom_wt = 100 50 0 (kg/ha), dlt_fom_n = 4 2 0 (kg/ha) endif or assuming that FOM is 40% carbon we can use a C:N ratio. If day = 100 then soiln2 incorp_fom dlt_fom_type = manure, dlt_fom_wt = 100 50 0 (kg/ha), dlt_fom_cnr = 10 10 0 (kg/ha) endif
SoilP Module Scope

SoilP is a representation of the availability of phosphorus in soil that provides an index for the soil's ability to supply P to crops that can be used in crop modules to modify growth processes under P limiting conditions. The module is designed to handle inputs of fertiliser that are either immediately available or slow acting (e.g. rock phosphate), and the improved effectiveness of fertiliser due to placement effects. To link SoilP with the MANURE model, the MANURE module handles the release of P from manure on the soil surface as a function of time and moisture content. This released P then becomes an input to the SoilP modules in the same manner that fertiliser P is an input. Similarly the corresponding release of N from manure is transferred to the appropriate pools in SoilN.
The dominant processes considered by SoilP are:

loss of availability through time removal by crops addition by crop residues mineralisation / immobilisation of soil organic P. SoilP is a multi-layer module that uses the same soil layer structure as SoilN. This approach has been adopted in order that there can be a full accounting of the organic P components in the system. The availability of P in soil is dominantly influenced by the near-surface layers, and crop response to fertiliser is often adequately described by soil tests, P sorption etc of surface soil samples, i.e. without consideration of subsoils. In most situations, extractable P decreases with depth, P sorption increases, and root density decreases; all three factors contribute to the relative unimportance of the subsoil for P nutrition.

The multi-layer nature of the module requires assumptions to be made as to how P uptake by crops is to be partitioned between layers in the soil profile.
SoilP Module History

Within the CARMASAT Project, there is a need to develop a capability for modelling the nutritional effects of manure, and in particular to accommodate the effects of both nitrogen and phosphorus in manure on crop growth. In order that this can be achieved, an essential stepping stone is the incorporation into crop modules of routines that constrain growth under conditions of limiting P supply. This, in turn, requires a module that specifies the P supply from the soil, namely SoilP.
Citations
Barrow, N.J. (1974). The slow reactions between soil and anions. 1. Effects of time, temperature, and water content of a soil on the decrease in effectiveness of phosphate for plant growth. Soil Science 118, 380-386. Probert, M.E. (1985). A conceptual model for initial and residual responses to phosphorus fertilizers. Fertilizer Research 6 , 131-8. This paper contains the broad principles of how the availability of P is conceptualised in SOILP Probert, M.E. and Okalebo, J.R. (1992). Effects of phosphorus on the growth and development of maize. In A search for strategies for sustainable dryland cropping in semi-arid eastern Kenya. (Ed M.E. Probert). ACIAR Proceedings No 41. pp 55-62.
SoilP Module Structure
Figure 1. Schematic representation of the SoilP module showing the principal processes considered.
SoilP Module Components
Initialising SoilP
Inputs required by the SoilP module are: Labile_p in each layer (ppm) Sorption in each layer. These values are the total P sorbed at an equilibrium concentration of 1 ppm in solution, that is the value of a when the Freudlich equation is used to describe P sorption ( Psorbed = ac b ). Residue_cp which is the C:P ratio of the initial above ground crop residues. Root_cp which is the C:P ratio of the initial roots. Rate_dissol_rock_p which is the rate of dissolution of any rock phosphate present at initialisation. The unavailable_p, banded_p and rock_p pools on a layer basis are optional inputs. In the absence of any of values, banded_p and rock_p will be initialised to zero and the unavailable_p pool will be set such that the labile_p unavailable_p system is at a steady state. Currently labile_p is the only permitted input. In the future, input of extractable soil P (with options for different extractants) could be input and labile_p calculated.
Adding P as Fertiliser
The nature of the P source and how it is placed determines how it modelled: water soluble and broadcast P is added into labile_p, water soluble and placed P is added into banded_p, any non water soluble P (eg rock phosphate) is added into rock_p Applied P fertiliser can be any combination of these three forms.
Processes of P in Soil
Loss of availability with time . The rate for labile_p unavail_P (and banded_p unavail_p) is dependent on temperature and moisture (Barrow). The reverse process, unavail_p labile_p will have a rate constant commensurate with the relative sizes of the two pools under steady state conditions. Dissolution of rock_p labile_p. The rate coefficient depends on the source and the soil type (soil pH, calcium status, etc.). It is an input for any source/soil combination. A typical value is about 0.2 y -1 . Decrease in effect of placement with time , ie banded_p labile_p. The effectiveness of placed P is assumed to decrease with time. Typically 50% of effect is lost in one year. A tillage event results in total transfer of banded_p to labile_p. Mineralisation of organic P sources labile P. This is linked to decomposition of carbon from HUM, BIOM and FOM pools of SoilN module and surface residues in Residue module. SoilP assumes constant C:P ratios in BIOM and HUM but tracks C:P ratios of FOM and surface residues as crops add residues of varying P concentration. Removal of P by crop uptake . P uptake is taken from labile_p and banded_p in proportion to their contributions to effective_p (see below). Addition of P by crop death/senescence . P in above and below ground parts of the plant are returned to the Residue and FOM pools respectively. ===Effective P in Soil=== When P is banded, especially on soils of high sorptivity, it is more effective in increasing P uptake than a corresponding broadcast application. This effect is simulated in SoilP by placing a premium on banded-p. Hence effective_p = labile_p + eff_band * banded_p
where eff_band is the relative effectiveness of banded_p (>1) and would depend on the band spacing and the sorptivity of the soil. Typically it is expected that eff_band has value of 2-3.
Module Interaction
An index of soil P status, as a function of effective_p, sorption, soil water, and rooting depth is made available to crop modules to determine whether the daily demand for P uptake can be met. SoilP receives back the actual P uptake for the day.
SoilP Module Parameterisation

Variable / Parameter labile_p unavail_p (optional) Units kg/ha kg/ha Definition soil P that is available for crop uptake soil P that is not available for crop uptake but can become available with time to replenish P removal by crops. If not specified, then initialised to steady state. water soluble fertiliser P applied as a band. If not specified then initialised to zero. non water soluble fertiliser P. If not specified then initialised to zero. rate coefficient determining release of available P from non water soluble source ratio of available P : unavailable P at a steady state soil's P sorption characteristic C:P ratio of roots at initialisation C:P ratio of surface residues at initialisation
banded_p (optional) rock_p (optional) rate_dissol_rock_p availP_ratio sorption root_cp residue_cp
kg/ha kg/ha yr -1 mg/kg -
SoilP Module Dependencies

SOILP uses an APSIM water balance module (eg SOILWAT) to determine the soil water status. The dynamics of P in organic matter provided by SOILP requires the soil nitrogen (SOILN) and residue (RESIDUE) modules for carbon cycling.
===SoilP Module Outputs=== Variable Name labile_p unavail_p Units kg/ha kg/ha Description soil P that is available for crop uptake soil P that is not available for crop uptake but which can become available with time to replenish P removal by crops water soluble fertiliser P applied as a band
banded_p biom_p hum_p fom_p uptake_p_ cropname
kg/ha Kg/ha kg/ha kg/ha
P uptake for crop cropname
SoilP Module Special Considerations

Simulation of crop growth under conditions of limiting P supply requires crop modules to provide the following: inclusion of P stress factors (derived from P content of the crop or part of crop, optimum and minimum P concentrations which are functions of stage of growth) to restrict growth rates and modify phenological development and partitioning of biomass between tops and roots calculation of daily P uptake by crop which is passed to SoilP so that P can be taken up from appropriate pools/layers when crop residues (tops or roots) cease to be part of the plant and are added to the soil or surface residues (e.g. at harvest or due to senescence), their P content has to be returned, along with mass and N content, to maintain the P balance for the crop/soil system.
SoilP Module Validation

The qualitative response of SoilP in terms of decreasing availability with time, more rapid loss of availability at higher temperature, effect of P sorption on crop uptake (by maize) has been verified. The only data set where SoilP and a modified Maize module (which includes routines to enable the crop to respond to P limitations) have been tested against observed data is for an experiment in Kenya described by Probert and Okalebo (1992).
SoilP Module Working Group

Dr Merv Probert is the leader.
Owner Ivan Hills Modified by Jared Hinz Date created 24-Mar-97 Current version 1.2 Version history
Date Version Details 22-Nov-96 1.0 Initial version based on Dr Merv Probert's documentation and input from Neil Huth and Ivan Hills. 06-May-98 1.1 Revisions by Merv Probert 06-Nov-98 1.2 Revisions by Merv Probert for first APSIM release
General description
Simulates soil temperature given minimal input information using a numerical scheme.
Usage
Soiltemp requires water content information from a water module, air temperature from the input module, and where available will use soil water evaporation and incident net radiation as part of the upper boundary condition. It should be placed after the water module in the module control list.
Theory
The node/element scheme for the numerical simulation is shown in Figure 1 where the circles denote the nodes and the zigzag's show the elements. All heat storage is assumed to occur at the nodes and all resistance to heat transfer is assumed to take place within the elements.
Figure 1. A diagrammatic representation of the node structure of the numerical simulation. T is temperature, Z is depth, K is thermal conductance, S is heat storage, nz is the number of nodes in the simulation, BL stands for boundary layer, Ta is the air temperature, and Tave is the annual average soil temperature. We begin by defining the heat balance at a node i, where i 1 or nz. The decrease in storage of heat at the node over a particular timestep is equal to the amount of heat leaving the node minus the amount of heat coming in all divided by the timestep so that,
, [1] where D stands for a change and t is time (s). Storage of heat is calculated from the change in temperature with time and the volumetric specific heat of the soil so that,
, [2] where i stands for a particular node, j refers to the current timestep and j+1 to the next timestep, T is temperature ( C), C is the volumetric specific heat of the soil (J K-1 m-3 ), A is the cross-sectional
area and is normally taken as 1 m2 , and z is depth (m). Because all heat storage is assumed to occur at the nodes, the appropriate depth interval is half the distance to the node on either side of i . C can be calculated from the specific heats of the soil constituents so that,
, [3] where r is the soil bulk density (Mg m-3 ), r s is the particle density and is usually taken as 2.65 Mg m3 , q is the volumetric water content (m3 m-3 ), the subscripts on C indicate the substance. Cair is usually assumed to be negligible while appropriate values of C for clay minerals and water are 2.39 and 4.18 MJ m-3 K-1 . Where more precise values are required, the equation can be expanded to account for organic matter and other minerals. See Campbell (1985) or Jury et al. (1991) for details on how to calculate C in more detail. Heat transfer is calculated from the standard Fickian equation where the rate of transfer is proportional to the temperature difference divided by the distance,
, [4] where l is the thermal conductivity (J s-1 m-1 K-1 ) and the overbar indicates that an appropriate average in time of temperature should be used. l can either be calculated from measurements of temperature changes in the soil (see Jury et al. , 1991 for an example) or can be approximated from regression equations. Below is given the scheme from Campbell (1985). First four parameters dependent on density, water content, and the amount of clay are calculated. These are,
, [5] where fclay is the fraction of clay in the soil. These parameters are combined into the equation for l so that, . [6] We are now able to put the elements of the equation together.
. [7] Now, in order to make some notational simplifications, define
, [8] and
, [9] and multiply by -1, so that . [10] The average temperature is defined as , [11] where h is an operator controlling the forward/backward averaging of temperature. Expanding the heat balance equation,
, [12] and collecting on the terms of T,
, [13] we can now put the unknown, or future', terms of T on the left hand side,
, [14] the equation can now be expressed in matrix format.
[15] If the three elements of the left-most matrix are expressed as ai , bi , and ci , and the right hand side as di , the equation can be expanded as an example for a simulation of nz nodes,
. [16] We now have a tri-diagonal matrix which can be solved using the Thomas algorithm (Carnahan et al. , 1969). The lower boundary condition is taken as a zero flux condition, ie. constant temperature, in which Tnz+1 equals a constant which is usually taken as the average annual temperature.
[17] The upper boundary condition is more complex. Usually the known temperature is the air temperature at some height above the soil and d1 is expressed as,
, [18] where KBL is the boundary layer conductance (J s-1 m-2 K-1 ), Tair is the temperature at the top of the boundary layer, Rn is the net radiative input (J s-1 m-2 ), and Esoil is the evaporative loss of energy from the soil surface (J s-1 m-2 ).
Implementation
Soiltemp is designed to independent of the Apsim timestep. To allow for the numerical solution, the equations above are solved 48 times within each Apsim timestep. This allows for a half-hourly internal time step when Apsim is running on its customary daily step, which should be more than sufficient for numerical stability. When the Apsim timestep is 24 hours Soiltemp estimates the changes in air temperature, the upper boundary condition, in the following manner.
Figure 2. Diagram showing the interpolation of air temperature within a day based on minimum and maximum temperature.
Air temperatures occurring between midnight and mint_time are linearly interpolated from the air temperature at midnight, calculated at the end of the previous Apsim timestep, and mint. There is a linear rise in temperture from the day's minimum to maximum. After maxt_time until midnight, air temperature is calculated as decreasing at the same rate at which it rose. If the Apsim timestep is less than 24 hours it is assumed that the user is supplying enough detail of the diurnal changes in air temperature that such interpolation is not required. In that case air temperture is taken as the average of mint and maxt for each Apsim timestep.
Initialisation
There are two sections required for initialisation of the Soiltemp module; constants and parameters. Where a variable name is followed by [nz] the variable is an array and the appropriate number of values must be supplied.
Constants Name Unit nu vol_spec_heat_om J m-3 K-1 vol_spec_heat_water J m-3 K-1 vol_spec_heat_clay J m-3 K-1 Parameters Name clay[nz] bound_layer_cond Unit Description proportion of clay J s-1 m-2 K-1 boundary layer conductance Range 0.0 - 1.0 0.0 - 100.0 Description Value forward/backward differencing 0.6 volumetric specific heat of organic matter 5.00e6 volumetric specific heat of water 4.18e6 volumetric specific heat of clay minerals 2.39e6
The higher the value of bound_layer_cond the greater the difference between air and soil surface temperature. If its value is unknown, Campbell (1986) suggests that a value of 20 J s-1m-2 K-1 is an appropriate initial estimate.
A further, optional, parameter is,
soil_temp[nz]
initial soil temperature
-100.0 - 100.0
which used to initialise soil temperature. If it is not supplied the soil temperature array is initialised to the average annual temperature. Simulations will eventually forget' the effect of poor initial guesses of soil temperature, but this may take some time. Testing of this module showed that it took approximately 40 days for the temperature at 1.5 m deep to converge to within 0.5 C of the analytical solution when the initial temperature difference was 7 C. The discrepancy will be greatest deeper in the soil profile, and where C is high or l is low. In general, where soil temperature is only important in the soil surface layers the convergence will occur within the first 10 days or so. Where the time taken to forget' the initial conditions might cause significant error, there are two strategies for overcoming this problem. The first is to run a dummy simulation prior to the start of the real simulation to estimate the starting soil temperature. The second option is to estimate the initial soil temperatures from an analytical solution. A solution for the heat flow equation assuming a sinusoidal upper boundary condition. which might for example be the annual cycle in air temperature, is (Carslaw and Jaeger, 1959),
, [19] where
, [20] T ave is the average annual temperature ( C), T amp is the annual amplitude in temperature ( C), and w is the angular frequency (radians). Thermal conductivity and heat capacity can be estimated, using soil profile averages, from equations 3, 5, and 6.
Time step inputs from other modules

Soiltemp must be accompanied by the input module and a soil water module in order that other inputs are supplied. These inputs are.
Name Unit Description Variables from the Met(Input) module tav C Average annual temperature, used to set the initial soil temperature if soil_temp is not supplied. Also determines the temperature at the lower boundary. mint C Minimum air temperature. maxt C Maximum air temperature. Variables from the Clock module timestep min Simulation timestep, converted to seconds internally. Variables from unknown module maxt_time hours Specifies the hour of the day when the maximum air temperature occurs. Variables from the soil water module dlayer[nz] mm Array of layer depths used to specify the nodes,
sw[nz] bd[nz] eos
m m Mg m-3 mm
-3
es
mm
converted to m internally. Volumetric soil water content. Soil bulk density. Potential soil water evaporation, or the water-depth equivalent of the net radiation reaching the soil surface, converted to J s-1 m-2 K-1 internally. Actual soil water evaporation, or the water-depth equivalent of the evaporation from the soil surface, converted to J s-1 m-2K-1 internally.
To allow compatibility with modules where changes in the soil occur with time, dlayer and bd are requested at every Apsim time step. If eos and es are not available they are assumed equal to zero.
Time step outputs

Name Unit final_soil_temp_surface C final_soil_temp[nz] C Description Soil surface temperature at the end of the final internal Soiltemp timestep. Soil temperature at the end of the final internal Soiltemp timestep. Average soil surface temperature during the Apsim timestep. Average soil temperature during the Apsim timestep. Minimum soil surface temperature found in each layer during the Apsim timestep. Minimum soil temperature found in each layer during the Apsim timestep. Maximum soil surface temperature found in each layer during the Apsim timestep. Maximum soil temperature found in each layer during the Apsim timestep. Thermal conductivity for each layer. Volumetric specific heat for each layer.
Ave_soil_temp_surface C Ave_soil_temp[nz] mint_soil_surface mint_soil[nz] maxt_soil_surface maxt_soil[nz] therm_cond[nz] heat_store[nz] C C C C C J s-1 m-1 K-1 J m-3 K-1
References
Campbell G.S., 1985, Soil Physics with Basic , Elsevier, Amsterdam. Carnahan B., Luther H.A., Wilkes J.O., 1969, Applied Numerical Methods , 1 st Ed. Wiley, New York. Carslaw H.S., Jaeger J.C., 1959, Conduction of Heat in Solids , Oxford University Press, London. Jury W.A., Gardner W.R., Gardner W.H., 1991, Soil Physics , 5 th Ed. Wiley, New York.
Description
The SoilWater module is a cascading water balance model that owes much to its precursors in CERES (Jones and Kiniry, 1986) and PERFECT(Littleboy et al , 1992). The algorithms for redistribution of water throughout the soil profile have been inherited from the CERES family of models. The water characteristics of the soil are specified in terms of the lower limit (ll15), drained upper limit (dul) and saturated (sat) volumetric water contents. Water movement is described using separate algorithms for saturated or unsaturated flow. It is notable that redistribution of solutes, such
as nitrate- and urea-N, is carried out in this module. Modifications adopted from PERFECT include (i) the effects of surface residues and crop cover on modifying runoff and reducing potential soil evaporation, (ii) small rainfall events are lost as first stage evaporation rather than by the slower process of second stage evaporation, and (iii) specification of the second stage evaporation coefficient (cona) as an input parameter, providing more flexibility for describing differences in long term soil drying due to soil texture and environmental effects. The module is interfaced with the RESIDUE and crop modules so that simulation of the soil water balance responds to change in the status of surface residues and crop cover (via tillage, decomposition and crop growth).
Enhancements beyond CERES and PERFECT include

the specification of swcon for each layer, being the proportion of soil water above dul that drains in one day isolation from the code of the coefficients determining diffusivity as a function of soil water (used in calculating unsaturated flow). Choice of diffusivity coefficients more appropriate for soil type have been found to improve model performance. Unsaturated flow is permitted to move water between adjacent soil layers until some nominated gradient in soil water content is achieved, thereby accounting for the effect of gravity on the fully drained soil water profile. SoilWater is called by APSIM on a daily basis, and typical of such models the various processes are calculated consecutively (This contrasts with models such as SWIM that solve simultaneously a set of differential equations that describe the flow processes). Figure 1. The subroutine structure of SoilWater.
Figure 2. A diagram showing the communication between SoilWater and other APSIM modules.
Soil Moisture Properties

An example some soil properties used to configure the SoilWater soil water "bucket" is as follows.
LL15 is the 15Bar lower limit of soil water content . It is approximately the driest water content achievable by plant extraction. This defines the bottom of the bucket. DUL is the drained upper limit of soil water content . It is the content of water retained after gravitational flow. DUL is sometimes referred to as Field Capacity. SAT is the Saturated water content . This defines the top of the bucket
Initial Soil Water
There are five ways to parameterise initial soil water in SoilWater. These can also be specified in the Manager module sections using the set' command e.g SoilWater set insoil = 0.5 () 1. Initial Soil Water as User Specified Soil Water Content The user can initialise soil water content to any initial volumetric soil water content for each layer. This can be done by setting the soil water parameter (sw) for each layer to a value between SAT and LL15. To use this option the insoil parameter must be set to > 1. 2. Initial Soil Water as a Fraction of Available Soil Water distributed evenly down the profile Initial soil water can be set to a fraction of the maximum available soil water in each layer. Setting the insoil parameter to a fraction (0 = LL15, 1 = DUL) initialises the soil water parameter (initial sw values are ignored) to this fraction for each layer. I.e. If 0.0 <= Insoil <= 1.0, then in each layer Soil water (sw) = LL15 + ((DUL-LL15) x Insoil) 3. Initial Soil Water as a Fraction of Available Soil Water filling the profile from the top. Initial soil water can be set to a fraction of the maximum extractable soil water in the whole profile. The profile is filled from the top down until the fraction is reached. Setting the profile_fesw parameter to a fraction of total extractable soil water initialises the soil water for layers starting at the top of the profile to DUL, until the fraction is reached. The remaining layers are set to LL15. This parameter is exclusive of the others. e.g. If the soil profile has layers of 150, 150, 300 and 300 mm, giving a total profile depth of 900 mm with corresponding DUL of 67.5, 67.5, 135, 120 mm and corresponding LL15 of 34.5, 34.5, 72, 75 mm giving ESW of 33, 33, 63, 45 mm with a Total ESW in the profile of 174 mm. And profile_fesw = 0.5, Then The ESW of each layer is set to 33, 33, 21, 0 mm giving A total of 87 mm in the profile. 4. Initial Soil Water as a depth of available Soil Water from the top of the profile. Initial soil water can be set to a depth of available soil water in the whole profile. The profile is filled from the top down until the soilwater depth is reached. Setting the profile_esw_depth parameter to a total available soil water initialises the soil water for layers starting at the top of the profile to DUL, until the amount of water is reached. The remaining layers are set to LL15. This parameter is exclusive of the others. e.g. Using the soil parameters of the previous example and profile_esw_depth = 87mm, Then The ESW of each layer is set to 33, 33, 21, 0 mm.
5. Initial Soil Water as a depth of wet soil, filled to field capacity. Initial soil water can be set to a depth of wet soil. The profile is filled from the top down until the soil depth is reached. Setting the wet_soil_depth parameter to a depth of soil filled to field capacity (DUL) initialises the soil water for layers starting at the top of the profile to DUL, until the soil depth is reached. The remaining layers are set to LL15. This parameter is exclusive of the others. e.g. Using the soil parameters of the previous example and wet_soil_depth = 400 mm, Then The ESW of each layer is set to 33, 33, 21, 0 mm giving A total of 87 mm in the profile.
Runoff
Runoff from rainfall is calculated using the USDA-Soil Conservation Service procedure known as the curve number technique. The procedure uses total precipitation from one or more storms occurring on a given day to estimate runoff. The relation excludes duration of rainfall as an explicit variable, and so rainfall intensity is ignored. When irrigation is applied it is assumed to be at low intensity and therefore no runoff is calculated.
Runoff response curves (ie runoff as a function of total daily rainfall) are specified by numbers from 0 (no runoff) to 100 (all runoff). Response curves for three runoff curve numbers for rainfall varying between 0 and 100 mm per day The user supplies a curve number for average antecedent rainfall conditions (CN2Bare). From this value the wet (high runoff potential) response curve and the dry (low runoff potential) response curve are calculated. The SoilWater module will then use the family of curves between these two extremes for calculation of runoff depending on the daily moisture status of the soil. The effect of soil moisture on runoff is confined to the effective hydraulic depth as specified in the module's ini file and is calculated to give extra weighting to layers closer to the soil surface.
Runoff response curve for average antecedent rainfall condition curve number (CN2) of 75 for a range of soil moisture conditions (0 - dry, 1 - wet).
Residue cover effect on runoff curve number where bare soil curve number is 75 and total reduction in curve number is 20 at 80% cover.
Surface residues inhibit the transport of water across the soil surface during runoff events and so different families of response curves are used according to the amount of crop and residue cover. The extent of the effect on runoff is specified by: a threshold surface cover (CNCov), above which there is no effect, and the corresponding curve number reduction (CNRed). Tillage of the soil surface also reduces runoff potential, and a similar modification of Curve Number is used to represent this process. A tillage event is directed to the module, specifying cn_red, the CN reduction, and cn_rain, the rainfall amount required to remove the tillage roughness. CN2 is immediately reduced and increases linearly with cumulative rain, ie. roughness is smoothed out by rain.
The effect of these processes is seen in the daily output variable CN2_new - the curve number used to calculate runoff on any particular day.
Evaporation
Soil evaporation is assumed to take place in two stages: the constant and the falling rate stages. In the first stage the soil is sufficiently wet for water to be transported to the surface at a rate at least equal to the potential evaporation rate. Potential evapotranspiration is calculated using an equilibrium evaporation concept as modified by Priestly and Taylor(1972). Once the water content of the soil has decreased below a threshold value the rate of supply from the soil will be less than potential evaporation (second stage evaporation). These behaviors are described in SoilWater through the use of two parameters: U and cona. The parameter U (as from CERES) represents the amount of cumulative evaporation before soil supply decreases below atmospheric demand. The rate of soil evaporation during the second stage is specified as a function of time since the end of first stage evaporation. The parameter Cona (from PERFECT) specifies the change in cumulative second stage evaporation against the square root of time. i.e. E s = cona t 1/2 Water lost by evaporation is removed from the surface layer of the soil profile thus this layer can dry below the wilting point or lower limit (LL) to a specified air-dry water content (air_dry). SoilWater uses two parameters, U and CONA, to specify soil evaporation. U (as in CERES) is the amount of cumulative evaporation, since soil wetting, before soil supply becomes limiting. Subsequently soil evaporation is a fraction of the square root of time since the end of first stage evaporation, using the regression coefficient CONA ( from PERFECT).
Cumulative Soil Evaporation through time for U = 6 mm and CONA = 3.5. For t <= t 1 E s = E os For t > t 1
Saturated Water Flow

When water content in any layer is above DUL, a fraction of the water drains to the next deepest layer each day. Flux = SWCON x (SW - DUL)
Infiltration or water movement into any layer that exceeds the saturation capacity of the layer automatically cascades to the next layer.
Unsaturated Water Flow

For water contents below DUL, movement depends upon the water content gradient between adjacent layers and the diffusivity, which is a function of the average water contents of the two layers. Unsaturated flow may occur both towards the surface and downwards, but cannot move water out of the bottom of the deepest layer in the profile. Flow between adjacent layers ceases at a soil water gradient (gravity_gradient) specified in the SoilWater ini file. The diffusivity is defined by two parameters set by the user (diffus_const, diffus_slope) in the SoilWater parameter set (Default values, from CERES, are 88 and 35.4, but 40 and 16 have been found to be more appropriate for describing water movement in cracking clay soils). Diffusivity = diffus_const x exp (diffus_slope x thet_av) where thet_av is the average of SW - LL15 across the two layers. Flow = Diffusivity x Volumetric Soil Water Gradient
Solute Movement
SoilWater can move any solute within the APSIM simulation. Solutes are defined to be either mobile or immobile, according to specifications in the SoilWater module's ini file. The saturated and unsaturated flows of soil water are used to calculate the redistribution of solutes throughout the soil using a mixing algorithm which assumes that all water and solute entering or leaving a layer is completely mixed. This means that solute movement can simply be calculated as the product of the water flow and the solute concentration in that water. Fluxes of solutes are associated with both saturated and unsaturated water fluxes. In both cases a simple mixing algorithm is used whereby incoming water and solute is fully mixed with that already present in any layer to obtain concentrations for solutes that are applied to the water leaving the layer. Efficiency factors (flux_eff and flow_eff) are specified in the SoilWater ini file to adjust the effectiveness of mixing for either saturated or unsaturated flows.
Leaching
The amount of solute dissolved in water can move to the layer below. This is considered by the model to be leaching. Individual solutes leached from each layer can be tracked by reporting the solute leaving the layer. An example may include reporting no3_leach(7). If there are 7 layers defined in the soil profile then this variable will represent the leaching of no3 out of the root zone.
Solutes in Rainfall
Solutes can be applied to the soil via rainfall using the optional parameter 'rainfall_XXX_conc' in parts per million, where 'XXX' is the solute name. As many solutes as desired can be applied in this way, however any solutes used must first be initialised in the system with the SOLUTE module.
Above Saturation Flow

When the soil water rises above Saturation there are two different parameters that can be specified: MWCON or KS. Both of these are layered values, so you need to enter a value for each layer in the soil. MWCON allows you to specify either 1 or 0 for each layer in the soil. A value of 1 means that all water above saturation for that layer immediately flows straight into the layer below. If this layer below is filled above saturation by water coming in from above and MWCON for that layer is 1 then this water then flows to the next layer and so forth for each of the layers below. Eventually water will run out of the bottom layer as drainage (report "drain" to see this). This is the tipping or cascading part of the classical tipping bucket or cascading flow analogy. A value of 0 means that all water above saturation is NOT allowed to flow into the layer below. ie it is an impermeable layer. Water will then begin to backup. Note that depending on how SWCON is set, water will still be able to be lost from the layer via the process of Saturated Flow (the flow that occurs between DUL and SAT). If both MWCON and SWCON prevent the water from flowing out of the layer then the water will begin to back up and will either become a pond on the surface or a water table beneath the surface.
KS allows you to specify a number of millimeters per day that is allowed to drain from the layer when the the soil water is above saturation. Once again depending upon how SWCON is set, Saturated Flow may still occur, and once again if soil water backs up a pond or water table is generated. nb. If neither MWCON or KS is set, then an MWCON value of 1 for each layer is assumed. ie. any water above saturation flows straight into the layer below. If both MWCON and KS are set, then KS overrides MWCON.
Surface Ponding and Water Table Functionality

Soilwat has the functionality of simulating an impermeable layer(s) within the soil profile, above which a water table may perch. The impermeable layer(s) is specified by setting either MWCON or KS (as mentioned in the previous section). If the water-table happens to reach the surface, then Soilwat also has the ability to simulate a surface-storage (or ponding') pool. The surface-water storage capacity is specified by the parameter max_pond, the maximum available surface water storage. This max_pond is applied to both runoff from rainfall events and also to runoff generated by water backing-up above an impermeable layer (mxcon or ks) below. Any surface water backing-up over max_pond' is added to the runoff pool. There is also an output value called "pond_evap" which tells you the evaporation from the pond. This is separate from es which does NOT include pond evaporation in it. MWCON, KS and max_pond are all optional parameters and if not provided, they are set to defaults (0.0 for max_pond). Here is an example of setting up a pond: [black_earth.soilwat2.parameters] !layer 1 2 3 4 5 6 7
dlayer = 150 150 300 300 300 300 300 ! layer thickness mm soil bd = 1.30 1.30 1.29 1.31 1.35 1.36 1.36 ! bulk density gm dry soil/cc moist soil sat = .500 .509 .510 .505 .490 .480 .480 ! saturation mm water/mm soil dul = .450 .459 .45 .44 .42 .41 .41 ! drained upper limit mm water/mm soil sw = .280 .364 .43 .43 .40 .41 .41 ! initial soil water mm water/mm soil ll15 = .230 .240 .240 .250 .260 .270 .280 ! lower limit mm water/mm soil air_dry = .10 .20 .20 .20 .20 .20 .20 ! air dry mm water/ mm soil swcon = 0.02 0.02 0.02 0.02 0.02 0.02 0.02 ! drainage coefficient mwcon = 1.0 0.0 1.0 1.0 1.0 1.0 1.0 max_pond = 15.0 ! maximum depth of surface storage The layer in which mwcon = 0.0 is considered impermeable to cascading' flow, hence water cascading down the soil profile will reach this layer and begin to back-up towards the surface. Drainage is still allowed through this layer unless swcon' is also set to zero.
If the impermeable layer is specified deep down in the soil, then the water table might not reach the surface and pond. The output variable water_table' reports the depth of the water-table below the surface as measured from the ground surface. If there is no water table, water_table' = 10000 by default. NB. There is a Pond module in APSIM. This Pond module calculates all the solute and nitrogen effects of having a pond above your soil. It grows algae etc and modfies the chemical processes going on in the soil (The processes that normally occur in the Soil Nitrogen module SoilN). The ponding we are discussing here are just the parts that effect the water balance and hence are dealt with in this Soil Water module.
Runon, Lateral Inflow and Outflow on a layer basis

Runon Capability Surface 'runon' can now be input from a data file. Soilwat2 does a daily 'get' to retrieve this information from the input module. From a user's point of view this means that 'runon' can be provided on a daily basis from the met file or from a separate input file. For example : [runon.sparse.data] runon = 0 allow_sparse_data = true
year day runon () () (mm) 1988 1 20 1988 5 17 1988 6 22 1988 10 25 1988 11 22
Lateral Inflow Capability Lateral Inflow can be input as a layer-based array via the same method as 'runon'. The parameter name is 'inflow_lat(layer)'. For example:
[runon.sparse.data] runon = 0 allow_sparse_data = true
year day runon inflow_lat(1) inflow_lat(2) inflow_lat(3) () () (mm) (mm) (mm) (mm) 1988 1 20 1 2 2 1988 5 17 2 1 2 1988 6 22 0 0 0 1988 10 25 1 1 1 1988 11 22 1 2 2
Both 'runon' and 'inflow_lat(layer)' are optional inputs to the model. NB. with Lateral Inflow it is assumed that ALL the water goes straight into the layer. Irrespective of the layers ability to hold it. It is like an irrigation. Klat has no effect and does not alter the amount of water coming into the layer. Klat only alters the amount of water flowing out of the layer
Lateral Outflow Capability Lateral Outflow is the flow that occurs as a result of the soil water going above DUL and the soil being on a slope. So if there is no slope and the water goes above DUL there is no lateral outflow. KLAT is just the lateral resistance of the soil to this flow. It is a soil water conductivity. The calculation of lateral outflow on a layer basis is now performed using the equation: Lateral flow for a layer = Klat * d * s/(1+s^2)^0.5 * L/A * unit conversions. Where: Klat = lateral conductivity (mm/day) d = depth of saturation in the layer (mm)= dlayer*(sw-dul)/(sat-dul) if sw > dul. Note this allows lateral flow in any "saturated" layer, not just those inside a water table. s = slope (m/m) L= catchment discharge width. Basically, it's the width of the downslope boundary of the catchment. (m) A = catchment area. (m2)
An example of the new soilwat2 input parameters (optional - if not included, lateral outflow = zero) are : [black_earth.soilwat2.parameters]
slope =0.1 discharge_width = 50 catchment_area = 1000 klat = 0.5
There is a new reportable variable called outflow_lat(layer). This can be summed by reporting outflow_lat(). NB. Lateral outflow only occurs when the soil water for the layer is above Drained Upper Limit (DUL). The above calculation involving klat, slope, discharge width, and catchment area is used to calculate the Lateral Outflow from each layer.
SoilWater Module Outputs

Name Es Eo Eos cn2_new Runoff Drain infiltration eff_rain salb bd esw sw_dep sw dlayer ll15_dep ll15 dul_dep dul sat_dep sat air_dry_dep air_dry flux flow Units Mm Mm mm mm mm mm mm g/cm 3 mm mm mm 3 /mm 3 mm mm mm 3 /mm 3 mm mm 3 /mm 3 mm mm 3 /mm 3 mm mm 3 /mm 3 mm mm Description Daily soil evaporation Daily potential evapotranspiration Daily potential soil evaporation Daily value CN2 adjusted for surface cover Daily runoff Daily drainage from bottom of soil profile Daily infiltration across the soil surface Effective Rainfall (Rainfall - Runoff - Drainage). Bare soil albedo Bulk density of the soil for each layer Extractable soil water in each layer (ie. sw_dep ll15_dep) Amount of water in each layer Volumetric water content in each layer Thickness of each soil layer Amount of water corresponding to a soil potential of 15 bar Volumetric water content for each layer corresponding to a soil potential of 15 bar Amount of water at drained upper limit for each soil layer Volumetric water content at drained upper limit for each soil layer Amount of water in each layer at saturation Volumetric water content at saturation for each soil layer Amount of water retained at air_dry for each layer Volumetric water content for air dry soil in each layer Saturated water flux from each layer to the layer below Unsaturated water movement between layers (+ve up)
nnnn_leach nnnn_up water_table pond
kg/ha kg/ha mm mm
outflow_lat
mm
Amount of solute nnnn in saturated water movement from each layer to the layer below Amount of solute nnnn in unsaturated water movement for each layer (+ve up). Depth of the water table (10000 if no water table present) Surface ponding Lateral outflow from each layer
SoilWater module actions
Reset
The reset action can be invoked to reset the module to the state specified within the module's input data, which includes the soil moisture characteristics, runoff and evaporation parameters and the initial soil water profile. The Reset action is identical to the initialise action used by the simulation engine at the start of the simulation except that a description of the reinitialised state is not printed in the simulation summary file. APSIM Manager Example: [sample.manager.start_of_day] ! reinitialise residues at the beginning of each sowing window If day = 100 then SoilWater reset endif
Initialise
The initialise action has now been replaced by the reset action (see above).
Summary Report
At initialisation, at series of tables and useful information is printed to the simulation summary file for perusal by the user. These tables can be printed to the summary file at any point during the simulation as a detailed record of the system state at a particular time. APSIM Manager Example: [sample.manager.start_of_day] ! Print out a summary of module state to the summary file If day = 100 then SoilWater sum_report endif
References
Jones, C.A., and J.R. Kiniry. 1986. CERES-Maize: A simulation model of maize growth and development. Texas A&M University Press, College Station, Texas. Littleboy, M., D.M. Silburn, D.M. Freebairn, D.R. Woodruff, G.L. Hammer, and J.K. Leslie. 1992. Impact of soil erosion on production in cropping systems. I. Development and validation of a simulation model. Aust. J. Soil Res. 30, 757-774. Priestly, C.H.B., and Taylor, R.J. (1972) On the assessment of surface heat and evaporation using large-scale parameters. Monthly Weather Review . 100 , 81 Ritchie, J.T. (1972) Model for predicting evaporation from a row crop with incomplete cover. Water Resources Research. 8 , 1204. Soil Conservation Service (1972) National Engineering Handbook Section 4: Hydrology, Soil Conservation Service, USDA, Washington.
Description
The Solute module is an APSIM plug-in-pull-out module that keeps a solute balance of up to five different solutes. The Solute module itself does not change the state of the solutes, but lets other modules change the solute information according to their own processes. For example, a solute may have its state changed by a soil water balance module as a result of its leaching calculations.
Things to note when using the Solute module

The Solute module can keep track of Nitrate and Ammonium, but must do so independent of any other soil balance module ( e.g. SoilN2). The Solute module is designed primarily to trace solutes such as Bromide and Chloride through soil layers.
Solute module outputs

The outputs for this module flow on from the input parameters. The module will provide the amount of solute in kg/ha on a layered basis for each of the specified solutes.
For the sample illustrated above, the possible outputs would be "br" or "cl". Additional outputs are: 1. max_xxxx (the maximum amount of solute xxxx in any layer (kg/ha)), 2. maxppm_xxxx (the maximum amount of solute xxxx in any layer (ppm)), and 3. maxlayer_xxxx (the soil layer number corresponding to the maximum solute load for solute xxxx). For Chlorine in the above example, these outputs would be 1. max_cl, 2. maxppm_cl, and 3. maxlayer_cl.
Solute Diffusion
Whilst the mass flow or advection of solutes is provided by the equations within the soil water modules, solute diffusion can be calculated within the solute module by supplying a diffusivity coefficient for an individual solute as follows.
[sample.solute.parameters] solute_names = cl cl = 0 0 0 0 0 0 0 0 (kg/ha) ! Initial Cl profile
d0_cl = 108
The solute flux is calculated as Flux = D0 * **dc/dx Where D0 is the diffusivity in free water, is water content, is the soil water pore space tortuosity (=2/ s2) and dc/dx is the concentration gradient within the soil water solution.
SORGHUM Module Scope

The sorghum module simulates the growth of a sorghum crop in a daily time-step (on an area basis not single plant). Sorghum growth in this model responds to climate (temperature, rainfall and radiation from the met module), soil water supply (from the soilwat module) and soil nitrogen (from the soiln module). The sorghum module returns information on its soil water and nitrogen uptake to the soilwat and soiln modules on a daily basis for reset of these systems. Information on crop cover is also provided to the soilwat module for calculation of evaporation rates and runoff. Sorghum stover and root residues are passed' from sorghum to the residue and soiln module respectively at harvest of the sorghum crop. A list of the module outputs is provided in the Sorghum module outputs' section below, but basically the module will predict leaf area development, N% and biomass of stover; depth, N% and biomass of roots; grain N% and biomass; grain yield and N%, grain size and grain number all on a daily basis.
Sorghum Module History

The sorghum module was originally developed from the QSORG model (Hammer and Muchow 1991) with features of the AUSIM model (Carberry and Arbrecht 1991) but has been extensively revised and improved since then.
Sorghum Module Structure

Figure 1: Order of key simulation steps in the sorghum module.
Sorghum Module Components Phenology

There are 11 crop stages and nine phases (time between stages) in the sorghum module (Table 1), and commencement of each stage (except for sowing to germination which is driven by soil moisture) is determined by accumulation of thermal time. Each day the phenology routines calculate today's thermal time (in degree days) from 3-hourly air temperatures interpolated from the daily maximum and minimum temperatures. Thermal time is calculated using the relationship in Figure 1 with the eight 3-hour estimates averaged to obtain the daily value of thermal time (in growing degree days) for the day. Different thermal time relationships are used for development before and during drain-filling. These daily thermal time values are cumulated into a thermal time sum which is used to determine the duration of each phase. Between the stage of emergence and flowering the calculated daily_thermal_time is reduced by water or nitrogen stresses, resulting in delayed phenology when the plant is under stress.
Figure 2: Relationship between temperature and thermal time accumulation. In the sorghum module different relationships are used for development before and during grainfilling.
Table 1: Phenological stages simulated in the sorghum module.

Stage code Stage name Stage description 1 sow Sowing 2 germ Germination 3 emerg Seedling emergence 4 End_juv End of the juvenile phase 5 fi Floral initiation 6 flag Appearance of the flag leaf 7 Start_grain_fill Start of linear phase of grain filling 8 End_grain_fill End of linear phase of grain filling 9 maturity Physiological maturity 10 Harvest_ripe Ready for harvest
11
End_crop
Crop finished and absent from simulation
The thermal time between sowing and germination is dependent upon soil water status. The phase between germination and emergence includes an effect of the depth of sowing on the thermal time target. The duration between emergence and flag leaf appearance is determined by the total number of leaves destined to appear on the plant, and the rate at which they appear, which is determined by temperature (see below). The total number of leaves is equal to the number in the seed at germination (4) plus the number subsequently initiated at a rate of 21 o Cdays per leaf, until floral initiation is reached. Hence the timing of floral initiation will determine the total leaf number and the timing of the appearance of the flag leaf and flowering. The phase between emergence and floral initiation is composed of a cultivar-specific period of fixed thermal time, commonly called the basic vegetative or juvenile phase. Between the end of the juvenile phase and floral initiation the thermal development rate is sensitive to photoperiod (calculated as a function of day of year and latitude) if the cultivar is photoperiod sensitive. The model assumes that sorghum, as a short day plant, will have a longer phase (dependent upon cultivar) between the end of the juvenile phase and initiation if photoperiods exceed the base photoperiod. There are cultivar-specific fixed thermal time durations for the subsequent phases between flowering and the start of grain fill, between the start and end of grainfill, between the end of grainfill and maturity, and between maturity and harvest ripe. Table 2 gives phenology parameters currently available in the sorghum module.

Each day two estimates of the daily biomass production are calculated, one limited by available water for transpiraton (eqn 1), and the other limited by radiant energy (eqn 2). The minimum of these two estimates is the actual biomass production for the day. delta_drymatter_transpiration = soil_ water_ supply * transpiration_efficiency eqn 1. Note: transpiration_efficiency is derived from the transpiration_efficiency_coefficient (=0.009 kPa) and the vapour pressure deficit (vpd) estimated from daily temperatures. dlt_drymatter_potential = rue *radiation_interception eqn 2. Note rue (radiation-use efficiency) is 1.25 g MJ-1 from emergence to end of grain filling. Radiation interception is calculated from leaf area index and a radiation extinction coefficient, which varies with row spacing (Fig. 3). If row spacing is not supplied in the sowing command, the default row spacing of 0.75 m is used, corresponding to an extinction coefficient of 0.40.
Figure 3: Relationship between the radiation extinction coefficient and row spacing used in the sorghum module.
Daily biomass production is partitioned to different plant parts in different ratios depending on crop stage. Until the end of juvenile phase the root:shoot ratio is maintained at 1.0, and then decreases to a value of 0.087 at flowering. Between emergence and flag leaf appearance the proportion of biomass produced that is partitioned to leaf increases exponentially as leaves appear (Fig. 4).
Between the stage floral initiation and flag leaf appearance, the biomass remaining after allocation to leaf is allocated between stem and developing panicle in the ration 1:0.30. After leaf growth has ceased at flag leaf appearance, biomass is partitioned between stem and panicle only until the start of grain filling, whereupon partitioning to grain only occurs. The sorghum module allows a total retranslocation of no more than 15 and 20% of leaf and stem biomass present at the start of grainfilling, respectively Figure 4: Fraction of daily biomass produced that is partitioned to leaf as a function of leaf number. Grain demand for carbohydrate (biomass) is calculated as a function of grain number. The number of grains set per plant is determined by the average daily growth rate per plant between floral initiation and the start of grain filling.
Leaf development
Leaf appearance rate is driven by thermal time, the last 3.5 leaves before the flag leaf appear each 20 o Cdays, before which a leaf appears every 41 o Cdays. Potential LAI is a product of leaf area per plant, number of plants per m2 and the water stress factor for expansion (see water deficits section below). Leaf area per plant is simulated as a sigmoidal function of thermal time since emergence, the parameters of which are cultivar-specific (see Table 2).
Actual LAI is less than the potential LAI if there is not sufficient biomass partitioned to leaf on that day. Maximum specific leaf area (SLA_MAX) defines the maximum leaf area (m 2 ) that can be expanded per gram of biomass, and is set to a value of 450 cm 2 g -1 . Leaf senescence There are four causes of leaf senesence; age, light competition, water stress and frost. The sorghum senescence routines calculate a senesced LAI for each stress each day and take the maximum of the four values as the day's total senescence. This senescence due to age occurs on a per plant basis and is a function of thermal time elapsed since flowering. The parameters defining the rate of whole-plant leaf area senescence due to age are cultivar-specific. Above an LAI of 4.0 light competition causes leaf area to be lost. The LAI senesced because of light competition is related to the amount LAI exceeds 4.0 (see eqns 3 and 4). sensLAI_light_fac = 0.008 *(LAI- 4.0) eqn 3. delta_sensLAI_light = LAI * sensLAI_light_fac eqn 4. Water stress during crop growth will cause leaf senescence (eqns 5 and 6). sensLAI_water_fac = 0.05 * (1 - sorghum_swdef(photo)) eqn. 5. delta_sensLAI_water = LAI * sensLAI_water_fac eqn 6. Note: the calculation of the water stress factor sorghum_swdef(photo) is descibed in the water deficits' section below. Frost senescence. Temperatures between 6.0 and 0 o C will cause a linearly increasing loss of leaf area from 0 to 100% respectively. From the values of senesced LAI the sorghum module calculates the biomass and nitrogen in that leaf area that is senesced, however a proportion of the carbon and nitrogen of these leaves is retranslocated to stem before senescence.
Tillering
Tiller number is not dynamically-determined in the sorghum module but is set in the sowing command As temperature during the early part of the season and plant density is known to influence the number of tillers produced, it is necessary for the user to set the potential tiller number given an understanding of the likely tiller number produced. As a guideline in cool environments and/or early sowings under low density where maximum tillering would be expected, tiller number would vary between 1.5 and 2 m -2. With low density this would be around 0.3 tillers m -2 . On the other hand in warm environments or late sowings tiller number could vary between 0.75 and 1 m -2 at low population density and around 0.15 m -2 at high density.
Row Configuration
Sorghum row configuration can be set to solid, single skip or double skip. In simulating skip row sorghum the assumption of a horizontally distributed leaf area does not hold. To account for this the equation for calculating the percentage green cover of the plant is changed from equation 1 to equation 2
Eq1 %green cover = where k is the extinction coefficient of the crop at that row spacing and l is the leaf area index
Eq2 % green cover = where k is the extinction coefficient of the crop at that row spacing, l = is the leaf area index and s is the skip index (1 for no skipped rows, 1.5 for one skipped row, and 2 for two skipped rows) With a skip row planting configuration, the wide gap between plants implies that root expansion is multi-directional, allowing more time for the roots to reach the centre of the skip rows. The root expansion front is described by a semi circular front expanding from the base of the plant at a rate of 2 cm per day in all directions. (see the output variable "root_proportion").
Regrowth
Although in practice it is possible to ratoon sorghum, there are no regrowth routines in sorghum .
Water uptake
To determine the amount of water supply to the crop on any day, first the total available water above the lower limit for all soil layers with roots is summed (eqn 7). If roots are only partially through a layer available soil water is scaled to that portion that contains roots. The kl constant (value differs for each soil layer) is then used to limit the amount of water available on any day (eqn 8). The kl factor is emphirically derived, incorporating both plant and soil factors which limit rate of water uptake. do layer = 1, deepest_layer (do loop to calculate available water for all layers) sw_avail = sw(layer) - ll (layer) eqn 7. sw_supply(layer) = sw_avail * kl (layer) eqn 8. Soil water demand is calculated as in the biomass accumulation' section above where potentail biomass production is a function of light interception and rue (eqn 1). This potential biomass production is converted to water demand using transpiration efficiency. Water uptake is the minimum of the supply and demand.

Soil water deficit factors are calculated to simulate the effects of water stress on different plant growth processes. Three water deficit factors are calculated which correspond to four plant processes each having different sensitivity to water stress i.e. photosynthesis (photo), phenology (pheno), and leaf-expansion (expansion) (Figure 5). A water availability ratio is calculated by dividing actual soil water supply (sw - ll) by the potential soil water supply (dul - ll). This ratio is used in the relationships illustrated to derive the stress factors for photosynthesis and leaf expansion. A factor of 0 is complete stress and 1 no stress.
Figure 5: Relationship between daily soil water supply:demand ratio and the level of stress on photosynthesis and leaf expansion. A fraction of plants (0.044) will be killed each day due to water stress once the cumulative water stress factor for photosynthesis exceeds 4.6.

In order to calculate nitrogen demand today, first potential biomass production is re-calculated unlimited by water, nitrogen or temperature i.e. as a function of rue and radiation-interception (eqn 2). This dry matter (biomass) is then partition into plant parts according to their current relative weights. Nitrogen demand by root and flower is the N required to attain a Nitrogen target concentration.
Root Flower Nitrogen target concentration 0.002 0.005 =

Stem Nitrogen demand is N required to achieve a Nitrogen target concentration depending on current phenological stage.
Emergence Flowering Stem Nitrogen target concentration 0.055 0.010 =

Nitrogen demand in the leaf up to Flag leaf stage is N required to keep leaf at target SLN of 1.5. After flag, N Required to maintain SLN. Grain Demand Grain Fill rate 0.001 mg/grain / degreeday for first 100 dd Grain N demand attempts to stay at this fill rate. Nitrogen supply is the sum of nitrogen available via mass flow (eqn 9) and by diffusion (eqn 10). no3_massflow (layer) = no3_conc * delta_sw (layer) eqn 9. no3_diffusion (layer) = sw_avail_frac *no3_conc eqn 10.
note: these layer values are summed to root depth and sw_avail_frac is ratio of extractable soilwater over total soil-water. If nitrogen demand cannot be satisfied by mass flow then it is supplied by diffusion. Demand can only be exceeded by supply from mass flow (up to the nitrogen uptake maximum Nitrogen available for uptake is distributed to plant parts in proportion to their individual demands. Grain N demand is a function of the grain number and a specific N demand per grain.

There are three N availability factors (0-1), one each for the photosynthesis, expansion, phenology and grain filling processes. A N concentration ratio is calculated for the stover (stem + leaf) in eqn 14 which is used as a measure of N stress, then different constants are used to convert that ratio to a deficit factor for each of the processes. A factor of 1 is used for effecting grain N concentration, 1.25 for photosynthesis (reduces rue), 0.8 for expansion (reduces leaf area expansion) and 5.75 to slow phenological development. As a value of 1 is no stress and 0 complete stress, phenology is least sensitive to nitrogen deficiency and grain N the most. N_conc_ratio = (N_conc_stover - N_conc_stover_min) / (N_conc_stover_crit - N_conc_stover_min) eqn14.

Root depth is initialised at the depth of sowing. Between emergence and grain filling, the increase in root depth is a daily rate multiplied a soil water availability factor. The daily rate is 10-15 mm/day during emergence and 33mm/day from end-of-juvenile to the start of grain-filling. Root depth is constrained by the soil profile depth. The increase of root depth through a layer can be constrained by known soil constraints through the use of the 0-1 parameter xf, which is input for each soil layer. Growth of root biomass is partitioned with depth using an exponential decay function from the soil surface and converted to root length density using a fixed specific root length. Roots are not senesced during the life of the crop, but are incorporated in the soiln module at harvest and distributed as fresh organic matter in the profile
Temperature stress
There are no generic temperature factors, as for water and nitrogen stress, but as discussed in sections above temperature does influence the rate of leaf senescence and radiation use efficiency.
Plant death
All or some of the plants can be killed due to a variety of stresses; If the crop hasn't germinated within 40 days of sowing, due to lack of germinating moisture, all plants are killed. If the crop does not emerge with 150 o Cdays of sowing, because it was sown too deep, then all plants are killed. If crop is past floral initiation and LAI = 0, then all plants are killed due to total senescence. If the cumulative phenological water stress factors exceed 25, all plants are killed due to water stress prolonging phenology.
A fraction of plants will be killed by high temperatures immediately following emergence.
Detachment
The detachment routines in sorghum are disabled in the current code.
Sorghum Module Parameterisation

Crop lower limit (ll), root water extraction constants (kl) and root extension factors (0-1, xf) values are needed for each soil layer test.sorghum.parameters ll = 0.200 0.200 0.200 0.220 0.250 () ! crop lower limit kl = 012 0.08 0.06 0.04 0.02 () ! kl need calibrating for each crop and soil type xf = 1.0 1.0 1.0 1.0 1.0 () Phenology, leaf area and grainfilling parameters are needed for each cultivar. An example is given below of those for the three generic maturity classes. Table 2: Cultivar parameters for generic early, mid and late-season cultivars in the sorghum module.
Parameter name
Parameter units tt_emerg_to_endjuv ( o C day) est_days_endjuv_to_init() pp_endjuv_to_init tt_endjuv_to_init ( o C day) photoperiod_crit1 (hours) photoperiod_crit2 (hours) photoperiod_slope ( o C/hour) tt_flower_to_maturity ( o C day) tt_flag_to_flower ( o C day) tt_flower_to_start_grain ( o C day) tt_maturity_to_ripe ( o C day) Main_stem_coeff (1/oC) Tpla_prod_coef (1/oC) Tpla_inflection (oC) Spla_prod_coef (1/oC) Spla_intercept -250 dm_per_seed (g) x_stem_wt vs y_height Mm vs g
Parameter values for cultivars of maturity classes Early Medium Late 100 15 30 115 12.3 14.6 25 695 100 30 1 2.95 0.015 320 0.007 -250 0.00083 0 80 0 2000 100 20 30 120 12.3 14.6 38.4 695 100 30 1 2.88 0.018 355.7 0.007 -280 0.00083 0 80 0 2000 100 20 30 255 12.3 14.6 38.4 695 80 50 1 2.95 0.018 400.8 0.005 -321 0.00083 0 80 0 2000
Module Dependencies
The minimum module configuration required to run sorghum in APSIM is the inclusion of the report, met, manager, soilwat2, soiln2 and residue2 and sorghum modules.
Within the manager file the following syntax is used for harvest and planting the sorghum crop: if (sorghum.stage_name = 'harvest_ripe' and sorghum.plant_status = 'alive') then sorghum harvest sorghum kill_crop sorghum end_crop endif if (sorghum.plant_status = 'dead') then report do_output sorghum harvest sorghum end_crop endif if (day > 120 and day < 240 and sorghum.plant_status = status_out ) then sorghum sow plants = 15 (p/m2), sowing_depth = 50 (mm), row_spacing = 0.35 (m), cultivar = early , fertile_tiller_no = 1.5, skip = double endif (note: row_spacing and skip in sowing command is optional)
Sorghum Module Outputs

Table 3: The following Sorghum variable can be output through the report module
Variable Name stage stage_code stage_name crop_type leaf_no leaf_no_dead leaf_area (max_leaf = 1000) height root_depth rlv hi plants grain_no grain_size cover_green cover_tot lai_sum tlai slai
Units
Description current phenological stage
number of fully expanded leaves no of dead leaves mm 2 leaf area of each leaf mm canopy height mm depth of roots mm.mm -3 root length per volume of soil in each soil layer Harvest index plants/m 2 plant density grains/plant grain number g individual grain wt 0-1 fraction of radiation reaching the canopy that is intercepted by green leaves 0-1 total crop cover fraction leaf area index of all leaf material live + dead tot lai area of leaf that senesces from plant
lai tlai_dead root_wt leaf_wt stem_wt grain_wt grain_wt dm_green (max_part = 6) dm_senesced (max_part = 6) dm_dead (max_part = 6) yield biomass dlt_dm dlt_dm_green (max_part = 6) n_green (max_part = 6) n_senesced (max_part = 6) n_dead (max_part = 6) dlt_n_green (max_part = 6) dlt_n_retrans (max_part = 6) dlt_n_detached (max_part = 6) dlt_n_dead_detached (max_part = 6) swdef_pheno swdef_photo swdef_expan ep (num_layers) cep sw_demand sw_supply esw_layr (num_layers) n_conc_stover n_conc_crit n_grain_pcnt n_uptake_grain n_uptake n_uptake_stover no3_tot n_demand n_supply n_supply_soil n_fix_pot nfact_photo nfact_grain nfact_photo nfact_expan
m 2 /m 2 m 2 /m 2 g/m 2 g/m 2 g/m 2 g/m 2 g/m 2 g/m 2 g/m 2 g/m 2 kg/ha kg/ha g/m 2 g/m 2 g/m 2 g/m 2 g/m 2 g/m 2 g/m 2 g/m 2 g/m 2 0-1 0-1 0-1 mm mm mm mm mm % % % g/m 2 g/m 2 g/m 2 g/m 2 g/m 2 g/m 2 g/m 2 g/m 2
live plant green lai total lai of dead plants root biomass leaf biomass stem biomass grain biomass grain biomass live plant dry weight (biomass) senesced plant dry wt dry wt of dead plants grain yield dry wt total above-ground biomass the daily biomass production plant biomass growth plant nitrogen content plant n content of senesced plant plant n content of dead plants actual n uptake into plant nitrogen retranslocated out from parts to grain actual n loss with detached plant actual n loss with detached dead plant water deficit factor for phenology water deficit factor fo photosynthesis water deficit factor for leaf expansion water uptake in each layer cumulative water uptake total crop demand for water total supply over profile plant extractable soil water sum of tops actual n concentration sum of tops critical n concentration grain n concentration percent n uptake by grain cumulative total n uptake by plant n uptake by stover total no3 in the root profile sum n demand for plant parts n supply for grain n supply from soil potential N fixation N deficit factor for photosynthesis N deficit factor for grain N content Nitrogen stress factor for photosynthesis Nitrogen stress factor for cell expansion
0-1 0-1
dlt_tt das
o Cday
daily thermal time days after sowing
Sorghum Module Validation

The following are some examples of module validation. Katherine effects of water deficit
Gatton differences in applied nitrogen. The rate of 240 kgN/ha is in the LHS graphs and 0 kgN/ha on the RHS.
REFERENCES
Hammer, G. L., & Muchow, R.C. (1991). Quantifying climatic risk to sorghum in Australia's semi-arid tropics and subtropics: model development and simulation. In Climatic Risk in Crop Production: Models and Management for the Semi-arid Tropics and Subtropics, eds R.C. Muchow & J.A. Mellamy. Ch. 16, Wallingford, CAB International, pp 205-32.
Carberry, P.S. & Abrecht, D.G. (1991) Tailoring crop models to the semi-arid tropics. In Climatic Risk in Crop Production: Models and Management for the Semi-arid Tropics and Subtropics, eds R.C. Muchow & J.A. Bellamy. CAB International, Wallingford, pp 157-82.
SORGHUM MOULE WORKING GROUP

Graeme Hammer, Scott Chapman, Greg McLean, Erik van Ooestrom
Introduction
The soybean module was developed Michael Robertson with contributions from Peter Carberry. APSIM-Soybean belongs to the PLANT family of crop modules in APSIM. The reader is referred to the science document for the plant module for a comprehensive description of the processes simulated by APSIM-Soybean. This document outlines some soybean-specific issues that are not covered by the legume science document. Notable features of APSIM-SOYBEAN The phenology of soybean cultivars are responsive to temperature and photoperiod, but not vernalisation. There is no photoperiod effect on post-flowering duration, even though it is known that such an effect exists. There are a limited number of cultivars available and users should consult the module owner if they need advice specifying a new cultivar Account is taken of the energy costs involved in synthesising the high energy content grain in soybean. Oil content is not simulated dynamically in response to any cultivar or environmental effects. APSIM-Soybean is not phosphorus-responsive, this is currently under development. Crop growth is not sensitive to waterlogging. The module does not simulate the differences between determinant and indeterminant types in terms of canopy expansion and flowering.

There are two crop classes. One is the conventional type, and the other is a promiscuous nodulator, often grown in the developing world. The promiscuous crop class has low N fixation capacity. There are 8 cultivars able to be simulated: Davis, Buchanan, CPI26671, Durack, Valiant, Roan, Magoye and Dragon. Cultivars differ in terms of biomass partitioning to grain and phenology. Cultivar Magoye, listed below, is a promiscuous type. It has a lower harvest index.
Validation
APSIM-Soybean has received testing across northern Australia, with factors such as cultivars, sowing date, irrigation, soil type, plant population density row spacing varying. Papers describing validation of APSIM-Soybean are by Robertson and Carberry (1998) and Denner et al. (1998). The accompanying figure demonstrates the performance of the module against Australian datasets.
Figure 1: Performance of the soybean module (observed versus simulated grain yield in g/m2) against test datasets reported by Robertson and Carberry (1998).
References
Denner, M. T.; James, A. T.; Robertson, M. J., and Fukai, S. 1998. Optimum soybean cultivars for possible expansion area: a modelling approach. Proceedings 10th Australian Soybean Conference, Brisbane 15-17 September, 1998:137-141. Robertson, M. J. and Carberry, P. S. 1998. Simulating growth and development of soybean in APSIM. Proceedings 10th Australian Soybean Conference, Brisbane 15-17 September, 1998:130136.
Introduction
The Ausfarm-Stock (Stock) component is used in APSIM to graze APSIM-Plant derived crops, such as Lucerne, Lablab and Wheat. The Ausfarm-Supplement (Supplement) component can also be used as a supplementary feed source for stock. Management operations can be carried out such as buying and selling of stock, supplementary feeding and moving stock to another paddock. Currently the paddock sizes are fixed at one hectare.
To use Stock in an APSIM simulation, three companion APSIMUI components are required StockScienceConverter, StockHerbageConverter and FarmwiseSequencer. e.g.
When Supplement is used, its companion SupplementScienceConverter is also required. e.g.
All of these components are found in the APSIMUI Standard Toolbox in the Animals Folder. E.g.
A sample simulation (Wether_Lucerne_Supplement) of grazing wethers on lucerne with supplementary feeding of wheat is provided under the New menu.
APSIMUI components
'Stock'
The Stock component initialises with default properties and no animals.
StockScienceConverter
The StockScienceConverter initialises with the values specified in its properties grid e.g.
o Debug o Stock_module o Conversion_model o Fraction_faeces_added o Fraction_urine_added

StockHerbageConverter
The StockHerbageConverter initialises with the values specified in its properties grid. E.g.
o Debug o Conversion_model o Herbage_model o Herbage_module_name

FarmwiseSequencer
The FarmwiseSequencer initialises with properties specified in its INI file. These properties translate APSIM events to Ausfarm events and should only be altered after consultation with the SEG.
Supplement
Supplement initialises with the values specified in its properties grid.
o Spoilage_time
Supplement Store
The supplement store properties define the initial values of each supplement being used in the simulation.
SupplementScienceConverter
The SupplementScienceConverter initialises with values specified in its properties grid. E.g.
o Debug o Supplement_module
Management
Pre-defined management rules of stock (cattle and sheep) and supplement feeding are found in the Stock folder under the Management folder in the Standard Toolbox. E.g.
Pre-defined cattle management rules for buying, selling and moving stock.
Pre-defined sheep management rules for buying and selling stock.
Pre-defined supplement management rules for buying, mixing and feeding stock.
Stock Component Description 1. Purpose of Component

The STOCK component encapsulates the GRAZPLAN animal biology model, as described in: Freer M, Moore AD & Donnelly JR (1997). GRAZPLAN: decision support systems for Australian grazing enterprises. II. The animal biology model for feed intake, production and reproduction and the GrazFeed DSS. Agricultural Systems 54 , 77-126. All animals represented in a component instance share a common genotype. The animals represented by a component instance are classified into groups . The members of each animal group have the same age class, but may have a range of ages (for example, an animal group containing mature animals may include four-year-old, five-year-old and six-year-old stock). The members of each animal group also have the same stage of pregnancy and/or lactation; the same number of suckling offspring; and occupy the same paddock. The set of animal groups changes as animals enter and leave the simulation, and as physiological events such as maturation, birth or weaning take place. Animal groups that become sufficiently similar are merged into a single group. Each animal group has a unique, internally-assigned integer index , starting at 1. Because the set of groups present in a component instance is dynamic, the index number associated with a particular group may change over time. Each animal group is also assigned a paddock . Paddocks are referred to by name in the STOCK component. It is the user's responsibility to ensure that paddock names correspond to instances of the PADDOCK component or other sources of necessary driving variables. Each group also has a user-assigned tag and priority , which need not be unique. Tag values are generally used to manage distinct groups of animals in a common fashion. For example, all lactating ewes may be assigned the same tag value, which may then be used in management rules that keep them grazing together. Animal groups with different tag values are not merged even if they are otherwise similar. If tag values are assigned sequentially starting at 1, they can be used to generate summary variables. Priority values are used to allocate animals to paddocks in the draft event.
2. Initialisation Properties
The initialisation variable set is nearly completely optional. The idea is to allow the user to specify a minimal information set as well as a maximally detailed initialisation.
Property breed
Type string
cattle : number : sex : age : weight : max_prev_wt : pregnant : lactating : no_foetuses : no_suckling : birth_cs : calf_wt : paddock : tag : priority
record integer4 string double double double integer4 integer4 integer4 integer4 double double string integer4 integer4
conception
double
death_rate fleece_yield
double double
male_breed
string
Units Required? Description Yes Name of the animal breed. The set of valid breed names is set out below. Implicit in the breed is the animal type (sheep or cattle). d No Initial state of each animal group for cattle. Not meaningful if breed is a sheep breed. kg kg Number of animals. d Feasible values are cow', cows', d heifer', heifers', steer', steers', bull', bulls'. kg Age of the animals. Unfasted live weight of the animals. Highest weight recorded to date. Zero denotes not pregnant; 1 or more denotes the time since conception. Only meaningful for females. Zero denotes not lactating; 1 or more denotes the time since parturition. Only meaningful for females. Number of foetuses. Only meaningful for females with pregnant > 0. Number of suckling calves. Only meaningful for females with lactating > 0. Condition score at parturition. Only meaningful for females with lactating > 0. Unfasted live weight of suckling calves. Only meaningful for females with lactating > 0. Paddock occupied by the animals. Initial tag value for the animal group. Priority accorded the animals in the draft event No Expected rates of conception with 1, 2 and 3 young for mature ewes or cows in average body condition, over a mating period lasting 2.5 oestrus cycles. Only the first two elements are significant for cattle. /yr No Base rate of animal mortality. Default is 0.0. kg/kg No Clean fleece weight as a proportion of greasy fleece weight. Default is 0.70. Only meaningful for sheep. No Name of the breed of rams or bulls to
male_srw
double
kg
No
max_fibre_diam double param_file string
mm
No No
peak_milk
double
kg
No
ref_fleece_wt
double
kg d kg kg kg mm d d kg kg
No No
sheep record : number integer4 : sex string : age double : weight double : max_prev_wt double : fleece_wt double : fibre_diam double : pregnant string : lactating integer4 : no_young integer4 : birth_cs integer4 : lamb_wt integer4 : lamb_fleece_wtdouble : paddock double : tag double : priority
which ewes or cows in this component instance will be mated. The default is breed . The set of valid breed names is set out below. Standard reference weight of the rams or bulls to which ewes or cows in this component instance will be mated.. The default value depends on male_breed . Maximum average wool fibre diameter. The default depends on breed . Name of a file containing genotypic parameters. Default behaviour is to use a default parameter set that is compiled into STOCK.DLL. Potential maximum milk yield per head, in 4% fat-corrected milk equivalents. Only significant for cattle. The default value is 20.0. Breed reference fleece weight. The default value depends on breed . Initial state of each animal group for sheep. Not meaningful if breed is a cattle breed. Number of animals. Feasible values are ewe', ewes', wether', wethers', ram', rams', crypto', cryptos'. Age of the animals. Unfasted live weight of the animals. Highest weight recorded to date. Greasy fleece weight of the animals. Average wool fibre diameter of the animals. Paddock occupied by the animals. Initial tag value for the animal group. Zero denotes not pregnant; 1 or more denotes the time since conception. Only meaningful for ewes. Zero denotes not lactating; 1 or more denotes the time since parturition. Only meaningful for ewes. Number of foetuses or suckling lambs. Only meaningful for ewes. Condition score at parturition. Only meaningful for ewes. Unfasted live weight of suckling lambs.
srw
double
kg
No
Only meaningful for ewes with lactating > 0. Greasy fleece weight of suckling lambs. Only meaningful for ewes with lactating > 0. Breed standard reference weight. The default value depends on breed .
Feasible values for the breed and male_breed properties are:
Sheep breeds black face x white face' border leicester' border leicester x merino' columbia' corriedale' delaine-merino' dorset x merino' dorset' finnsheep' hampshire' large merino' medium merino' merino'
Sheep breeds polwarth' polypay' romney' ryeland' southdown' suffolk' targhee' texel' US corriedale' US romney' US southdown' US suffolk'
Cattle breeds angus' ayrshire' beef shorthorn' brahman' brahman x british' brown swiss' charolais' charolais x british' charolais x friesian' charolais x holstein' chianina' dairy shorthorn'
Cattle breeds friesian' friesian x british' guernsey' hereford' holstein' holstein x british' jersey' limousin' sahiwal' simmental' south devon'
3. Subscribed events sequenced
3.1. do_stock
Default sequencing: 7000 Computes development, intake, growth and reproduction of all animals.
4. Subscribed events other
4.1. buy
Causes a given number and type of animals to enter the simulation.
Parameter number sex
Description Number of animals to be bought Sex of the animals. Feasible values are as for sheep : sex or cattle : sex , as appropriate. age double months Average age of the animals weight double kg Average unfasted live weight of the animals fleece_wt double kg Average greasy fleece weight of the animals. Only meaningful in sheep. pregnant integer4 d Zero denotes not pregnant; 1 or more denotes the time since conception. Only meaningful for females. lactating integer4 d Zero denotes not lactating; 1 or more denotes the time since parturition in lactating animals. Only meaningful for females. no_young integer4 Number of foetuses and/or suckling offspring. young_wt double kg Average unfasted live weight of any suckling lambs or calves. young_fleece_wtdouble kg Average greasy fleece weight of any suckling lambs.
Type integer4 string
Units
4.2. castrate
Converts ram lambs to wether lambs, or bull calves to steers. If the animal group(s) denoted by group has no suckling young, has no effect. If the number of male lambs or calves in a nominated group is greater than the number to be castrated, the animal group will be split; the sub-group with castrated offspring will remain at the original index and the sub-group with offspring that were not castrated will be added at the end of the set of animal groups.
Parameter Type group integer4
Units
number
integer4
Description Index number of the animal group, the lambs or calves of which are to be castrated. A value of zero denotes that each animal group should be processed in turn until the nominated number of offspring has been castrated. Number of male lambs or calves to be castrated.
4.3. draft
Assigns paddocks to animals in such a way that animal groups with the lowest tag values are placed in the paddocks with the best pasture. This event has no parameters.
4.4. dryoff
Ends lactation in cows that have already had their calves weaned. The event has no effect on other animals. If the number of cows in a nominated group is greater than the number to be dried off, the animal group will be split; the sub-group that is no longer lactating will remain at the original index and the sub-group that continues lactating will be added at the end of the set of animal groups.
Parameter
Type
Units
Description
group
integer4
Index number of the animal group for which lactation is to end. A value of zero denotes that each animal group should be processed in turn until the nominated number of cows has been dried off.
number
integer4
4.5. join
Commences mating of a particular group of animals. If the animals are not empty females, or if they are too young, has no effect.
Units
mate_days integer4
Description Index number of the animal group for which mating is to commence. A value of zero denotes that all empty females of sufficient age should be mated. Length of the mating period.
4.6. move
Changes the paddock to which an animal group is assigned.
Parameter Type group integer4 paddock string
Units
Description Index number of the animal group to be moved. Name of the paddock to which the animal group is to be moved.
4.7. sell
Removes animals from the simulation.
Units
number
integer4
Description Index number of the animal group from which animals are to be removed. A value of zero denotes that each animal group should be processed in turn until the nominated number of animals has been removed. Number of animals to remove.
4.8. shear
Shears sheep. The event has no effect on cattle.
Units
sub_group string
Description Index number of the animal group to be shorn. A value of zero denotes that all animal groups should be processed. Denotes whether the main group of animals, suckling lambs, or both should be shorn. Feasible values are the null string (main group), adults' (main group), lambs' (suckling lambs), both' (both).
4.9. sort
Rearranges the list of animal groups in ascending order of tag value. This event has no parameters.
4.10. split
Creates two or more animal groups from the nominated group. One of these groups is placed at the end of the animal group list. The division may only persist until the beginning of the next do_stock step, when sufficiently similar groups of animals are merged.
Parameter Type group integer4 type string
Units
value
double
Description Index number of the animal group to be split. Feasible values are: age' All animals younger than value days are moved to a new group. weight' All animals with live weight less than value kg are moved to a new group. young' Only animals with suckling offspring are affected. Mothers with different sexes of young are divided, with the group with all male offspring remaining in place. For mothers with twins, three groups are created; a group with two male offspring, a group with two female offspring, and a group with one of each. number' value animals remain in place and the remainder form a new group Threshold age or weight, or the number to be split, depending on the value of type . Ignored if type is young'.
4.11. tag
Sets the tag value for an animal group.
Parameter Type group integer4 value integer4
Units
Description Index number of the animal group to be assigned a tag value. Tag value to be assigned.
4.12. wean
Weans some or all of the lambs or calves from an animal group. The newly weaned animals are added to the end of the list of animal groups, with males and females in separate groups.
Units
sex
string
Description Index number of the animal group from which animals are to be removed. A value of zero denotes that each animal group should be processed in turn until the nominated number of lambs or calves has been weaned. Feasible values are: all' Female and male lambs or calves are to be weaned.
number
integer4
female' Only female lambs or calves are to be weaned. male' Only male lambs or calves are to be weaned. Number of lambs or calves to be weaned.
5. Methods
None.
6. Published events 6.1. remove_herbage

Indicates the removal of herbage and seeds. This event is directed to each component instance that provides the Stock instance with a value for the plant2stock driving property.
Parameter Type herbage double seed double
Units Description kg/ha Mass of shoots removed in each of 5 digestibility classes. kg/ha Mass of unripe and ripe seeds removed.
6.2. add_excreta
Indicates the excretion of faeces and urine into a paddock. Different instances of this event are directed to each component subscribing to it, with parameters depending upon the name of the paddock component to which the subscribing component belongs.
Parameter Type faeces_om record : weight double :n double :p double :s double : ash_alk double faeces_inorg record :n double :p double :s double urine record : volume double : urea double : pox double : so4 double : ash_alk double
Units kg/ha kg/ha kg/ha kg/ha mol/ha kg/ha kg/ha kg/ha m 3 /ha kg/ha kg/ha kg/ha mol/ha
Description Organic matter in excreted faeces: Mass (as DM) of faeces to be added. Mass of organic nitrogen in faeces. Mass of organic phosphorus in faeces. Mass of organic sulphur in faeces. Ash alkalinity in faeces. Inorganic nutrients in excreted faeces: Mass of inorganic nitrogen in faeces. Mass of inorganic phosphorus in faeces. Mass of inorganic sulphur in faeces. Excreted urine: Volume of excreted urine. Urea-N in excreted urine. Phosphate-P in excreted urine. Sulphate-S in excreted urine. Ash alkalinity in excreted urine.
7. Driving properties
Property area latitude slope Type double double double Units Event:State Number Description ha 0+ Area of each paddock. deg 1 Latitude (south is negative). deg 0+ Slope of each paddock.
daylength plant2stock : herbage : dm : dmd : cp_conc : p_conc : s_conc : prot_dg : ash_alk : height_ratio : propn_green : legume : select_factor : seed : dm : dmd : cp_conc : p_conc : s_conc : prot_dg : ash_alk : height_ratio : seed_class supp_eaten : paddock : eaten
double record record double double double double double double double double double double double record double double double double double double double double integer4 record string double
hr kg/ha kg/kg kg/kg kg/kg kg/kg mol/kg kg/ha kg/kg kg/kg kg/kg kg/kg mol/kg -
1 0+
Day length including civil twilight. Description of the pasture for use by the ruminant model.
kg
0-1
time : startDay : startSec : startSecPart : endDay : endSec : endSecPart waterlog weather : maxt : mint : rain : snow
record integer4 integer4 double integer4 integer4 double double record double double double double
d s s d s s C C mm/d mm/d MJ/m 2
Consumption of supplementary feed by animals. Name of a paddock Amount of supplementary feed eaten by animals in this paddock. Current time step.
0+ 1
Waterlogging index for each paddock. Weather record.
: radn : vpd : wind
double double double
/d kPa m/s
If the following properties are not found, then alternative properties are subscribed to instead:
Property Alternative Type weather maxt double weather weather weather mint rain wind double double double
Units Event:State Number Description C do_stock :0 1 Maximum air temperature. C do_stock :0 1 Minimum air temperature. mm do_stock :0 1 Precipitation in all forms other than snow. m/s do_stock :0 1 Average wind speed
8. Owned properties
All initialisation properties are readable. In addition, the following owned properties are available: (a) Standard properties
Property name type version author active state
Type string string string string Boolean string
Units
Description Fully-qualified name of the component. Value is Stock. Value is 1.0. Value is CSIRO Plant Industry. Denotes whether or not the component is active. SDML description of the current state.
(b) Component-specific properties Each entry in the following table describes between one and six variables: the named variable and five variants obtained by appending the texts: _ yng , _ all , _ tag , _yng _ all and _yng _ tag . The variable obtained by appending _yng is an array of the same type as the base variable. The array has one element for each animal group. Each element of the array denotes the value of the nominated quantity for unweaned lambs or calves of the corresponding animal group. If the animal group has no unweaned lambs or calves, the value is zero. For example, weight_yng 4 gives the weight of unweaned lambs or calves in the fourth animal group (if any). The variable obtained by appending _all is a scalar that denotes an average or total of the quantity (as appropriate) over all animals in the component. Unweaned lambs or calves are excluded. For example, there is a weight_all variable of double type, which denotes the average weight of all animals, and number_yng_all gives the total number of unweaned lambs or calves. The variable obtained by appending _tag is an array of the same type as the base variable. The size of this array is given by the highest tag value assigned to an animal group. Each element of the array denotes an average or total of the quantity (as appropriate) over all animals that have the corresponding tag value. Animals with tag values less than or equal to zero and all unweaned lambs or calves are excluded. For example, weight_tag 2 denotes the average weight of all animals with a tag value of 2. Note that the animal model will automatically merge and split groups of animals, so that the index position of a particular group of animals in the array variables will not necessarily remain constant.
Property age age_months base_wt birth_cs c_fleece_wt cfleece_growth cond_score cp_intake dse
Type double double double double double double double double double
faeces record : weight double :n double :p double :s double : ash_alk double faeces_inorg record :n double :p double :s double fibre_diam double fibre_growth_diamdouble fleece_wt intake : weight :n :p :s : ash_alk lactating double record double double double double double double
Units Description d Age of animals. - Age of animals, in months. kg Fleece-free, conceptus-free weight. - Condition score at last parturition; zero if lactating =0 kg Current clean fleece weight. kg/d Growth rate of clean fleece. - Condition score of animals (1-5 scale). kg/d Crude protein intake per head. - Dry sheep equivalents, based on potential intake. kg/d Faecal dry matter and nutrients per kg/d head. kg/d kg/d mol/d kg/d Inorganic nutrients excreted in faeces, kg/d per head. kg/d m m Current average wool fibre diameter. m m Fibre diameter of the current day's wool growth. kg Current greasy fleece weight. kg/d Total intake per head of dry matter and kg/d nutrients by each animal group. kg/d kg/d mol/d d If the animals are lactating, the number of days since birth of the lamb or calf; zero otherwise. Maximum previous basal weight (fleece-free, conceptus-free) attained by each animal group. Intake per head of metabolizable energy. Metabolizable energy produced in milk (per head) by each animal group Weight of milk produced per head, on a 4% fat-corrected basis. Number of female animals in each animal group.
_all _tag _yng x x x x x x x x x x x x x x x x x x x x x x x x x x x x x
x x x x
x x x x
x x x x
max_prev_wt
double
kg
me_intake milk_me milk_wt no_female
double double double integer4
MJ/d MJ/d kg/d
x x x x
x x x x
no_foetuses no_groups no_male no_suckling number paddock past_intake : weight :n :p :s : ash_alk pregnant
double
priority retained_n retained_p retained_s sex
supp_eaten : paddock : eaten
supp_intake : weight :n :p :s : ash_alk tag_no trampling
Number of foetuses per head in each animal group. integer4 Number of animal groups. integer4 Number of male animals in each animal group. double Number of unweaned lambs or calves per head in each animal group. integer4 Number of animals in each animal group. string Paddock occupied by each animal group. record kg/d Intake per head of pasture dry matter double kg/d and nutrients by each animal group. double kg/d double kg/d double mol/d double double d If the animals are pregnant, the number of days since conception; zero otherwise. integer4 Priority score assigned to each animal group; used in drafting. double kg/d Nitrogen retained within the animals, on a per-head basis. double kg/d Phosphorus retained within the animals, on a per-head basis. double kg/d Sulphur retained within the animals, on a per-head basis. See the sex field of string the sheep and cattle initialisation variables. Returns heifer for cows under two years of age. record kg Consumption of supplementary feed by string animals. double Name of a paddock Amount of supplementary feed eaten by animals in this paddock. record kg/d Intake per head of supplement dry double kg/d matter and nutrients by each animal double kg/d group. double kg/d double mol/d double integer4 Tag value assigned to each animal group. double kg/ha Mass of grazers per unit area. The
x x x
x x x
x x x
x x x
x x x
urine_n urine_p urine_s weight wt_change
double double double double double
kg/d kg/d kg/d kg kg/d
value returned depends on the requesting component. Urinary nitrogen output per head. Urinary phosphorus output per head. Urinary sulphur output per head. Average live weight of each animal group. Rate of change of base weight of each animal group.
x x x x x
x x x x x
x x x x x
Title: Stock Component Description Created by: A.D. Moore Modified by: A.D. Moore Processor: Microsoft Word 2002 Printed: 15 Dec 2003 Revision History
Version 0.1 0.2 0.3 0.4 0.5
Date 12 Dec 1997 17 Dec 1997 4 Aug 1998 10 Dec 2003 15 Dec 2003
Changes First draft Second draft Third draft Revised to match pre-release version of component. *_tag properties added supp_eaten added
Document Distribution Policy All versions: Internal use only
Drivers for the Stock Component

Environmental information
The Stock component implements alternative interfaces to obtain weather data; I have only provided the APSIM-compatible interface here.
Property
Type
time latitude daylength maxt
record double double double
Units Permitted number of values Exactly 1 deg Exactly 1 hr Exactly 1 C Exactly 1
Description
Current time step in standard format. Latitude (south is negative). Day length including civil twilight. Maximum air temperature.
mint rain wind waterlog
double double double double
C mm m/s -
Exactly 1 Minimum air temperature. Exactly 1 Precipitation in all forms other than snow. Exactly 1 Average wind speed Zero or Waterlogging index for each paddock. more
The first six of these drivers will cause no difficulty. The wind driver is used in computing the energy requirement to maintain body temperature under cold conditions; it can be set to (say) a constant 2.0 m/s if wind speed data are not available. The waterlog driver is an index that describes the degree of waterlogging of the soil (which is modelled as affecting the time spent grazing); it is optional and can be ignored in your context.
Paddock information
Property Type Units Permitted Description number of values ha Zero or Area of each paddock. more deg Zero or Slope of each paddock more
area slope
double double
In the Stock component, each group of animals is taken to reside in a paddock. The list of valid paddock names is obtained by looking for the components that have the area property and then obtaining the names of these components, i.e. a paddock is defined as any entity with an area. If no component in the simulation has the area property, then the Stock component sets itself up with a single paddock that has the null string for its name, an area of 1.0 ha and zero slope. The slope values are used to compute the energy cost associated with movement. The usual configuration is to have the paddock components/systems at the same level in the component tree as the Stock component.
Herbage information
At each time step, the Stock component requests the plant2stock driving property. Each value of plant2stock is allocated to one of the paddocks by parsing the name of the component sending it. The herbage present in each paddock is then summarised before being used in the computations of animal intake. In the case where no paddocks have been identified, all the plant components that provide plant2stock are allocated to the null paddock. Once the intake rates of all animals have been computed, the rates for all animals in a paddock are summed and then allocated between the components in that paddock that provided a value for the plant2stock driver. Each such component is then sent a remove_herbage event that contains the rate of herbage removal for that plant component. The plant2stock driving property is a record with six fields:
Field herbage
Type array of
Units
Description Mass and quality of the herbage on offer. The
records
propn_green legume select_factor
double double double
seed
array of records array of integer4 -
seed_class
herbage is split into a number of pools that are distinguished by their DM digestibility; each of these pools is described by one element of the array. The fields of the sub-records are set out below. Proportion of the total herbage mass that is green Proportion of the total herbage mass that is legume. Usually 0.0 or 1.0 Species-specific effect on the relationship between digestibility and voluntary intake. Typical values are 0.0 for C3 grasses and legumes and 0.16 for C4 grasses. Mass and quality of unripe and ripe seeds (elements 1 and 2, respectively). The fields of the sub-records are the same as for the herbage field. Equivalent digestibility class for unripe and ripe seeds (elements 1 and 2, respectively). Valid values are 1-6 or 0, where 1 denotes that seeds will be selected at the same time as 80% digestible herbage, 2 corresponds to 70% herbage, etc. A zero value denotes that seeds are not grazed.
The fields of the sub-records in plant2stock : herbage and plant2stock : seed are:
Field dm dmd cp_conc p_conc s_conc prot_dg ash_alk height_ratio
Type double double double double double double double double
Units Description kg/ha Mass (dry matter basis) of the herbage or seed pool Dry matter digestibility (0-1, not percentage) kg/kg Crude protein concentration. Can be estimated as 6.25 x N kg/kg Phosphorus concentration. Can reasonably be estimated by assuming a fixed N:P ratio. kg/kg Sulphur concentration. Can reasonably be estimated by assuming a fixed N:S ratio. kg/kg Protein degradability. In the absence of better information, can be estimated as dmd +0.10 mol/kg Ash alkalinity. An index of the bulk density of the herbage. The height ratio for herbage should be computed as 100/(0.03 x BD ), whereBD is the herbage bulk density in g/m 3 . This value should be set to 1.0 for seed pools.
One way to obtain a distribution of herbage mass into DMD classes is given on page 32 of the technical paper on GrazFeed that can be found via http://www.csiro.au/index.asp?type=faq&id=Grazplan .
Supplementary feed information

At each time step, the Stock component requests the supp2stock driving property. This driving property is optional. The supp2stock property returns the amount and quality of supplementary feed that is present in each paddock. All animals resident in a paddock can access the corresponding quantity of supplementary feed (it is allocated between them in proportion to their maximum intake rate). To provide this property, include the Supplement component in the simulation. The supp2stock driving property is an array of records. Each sub-record has the following fields:
Field paddock amount roughage dm_content dmd me_content cp_conc prot_dg p_conc s_conc ee_conc adip2cp
Type string double boolean double double double double double double double double double
Units kg
kg/kg MJ/kg kg/kg kg/kg kg/kg kg/kg kg/kg kg/kg mol/kg kg/kg
ash_alk double max_passage double
Description Name of a paddock Amount of supplementary feed present in the paddock TRUE i.f.f. the feed is a roughage. Dry matter content of the feed. Dry matter digestibility of the feed (not including any portion that passes the gut undamaged). Metabolizable energy content of the feed. Crude protein content of the feed. Protein degradability of the feed. Phosphorus content of the feed. Sulphur content of the feed. Ether-extractable content of the feed. Proportion of crude protein that is insoluble in acid detergent. Ash alkalinity of the feed. Maximum proportion of the feed that will pass undamaged through the gut of ruminants.
DDML definitions
This is for the programmers: plant2stock <type> <field name = "herbage" array="T"> <element> <field name="dm" unit="kg/ha" kind="double"/> <field name="dmd" unit="-" kind="double"/> <field name="cp_conc" unit="kg/kg" kind="double"/> <field name="p_conc" unit="kg/kg" kind="double"/> <field name="s_conc" unit="kg/kg" kind="double"/> <field name="prot_dg" unit="kg/kg" kind="double"/> <field name="ash_alk" unit="mol/kg" kind="double"/> <field name="height_ratio" unit="-" kind="double"/> </element> </field> <field name="propn_green" unit="-" kind="double"/> <field name="legume" unit="-" kind="double"/> <field name="select_factor" unit="-" kind="double"/>
<field name = "seed" array="T"> <element> <field name="dm" unit="kg/ha" kind="double"/> <field name="dmd" unit="-" kind="double"/> <field name="cp_conc" unit="kg/kg" kind="double"/> <field name="p_conc" unit="kg/kg" kind="double"/> <field name="s_conc" unit="kg/kg" kind="double"/> <field name="prot_dg" unit="kg/kg" kind="double"/> <field name="ash_alk" unit="mol/kg" kind="double"/> <field name="height_ratio" unit="-" kind="double"/> </element> </field> <field name = "seed_class" unit="-" kind="integer4" array="T"/> </type> supp2stock <type array="T"> <element> <field name="paddock" kind="string"/>' <field name="amount" unit="kg" kind="double"/>' <field name="roughage" kind="boolean"/>' <field name="dm_content" unit="kg/kg" kind="double"/>' <field name="dmd" unit="-" kind="double"/>' <field name="me_content" unit="MJ/kg" kind="double"/>' <field name="cp_conc" unit="kg/kg" kind="double"/>' <field name="prot_dg" unit="kg/kg" kind="double"/>' <field name="p_conc" unit="kg/kg" kind="double"/>' <field name="s_conc" unit="kg/kg" kind="double"/>' <field name="ee_conc" unit="kg/kg" kind="double"/>' <field name="adip2cp" unit="kg/kg" kind="double"/>' <field name="ash_alk" unit="mol/kg" kind="double"/>' <field name="max_passage" unit="kg/kg" kind="double"/>'; </element> </type>
Introduction
The structure of the APSIM sugar model can be described as follows:
Order of Calculations
For each APSIM time step the calculation of sugar model states and transitions are performed in a set order in different stages of the APSIM cycle through each time step. Phenology and potential growth and demands are calculated during the prepare stage and actual growth and changes to state variables are calculated during the process stage.
Parameterisation Structure of the INI file

There are five separate categories of variables in the sugar module's ini file. They are listed below with some examples of the type of parameters included in each. Constants Upper and lower bounds for met and soil variables Plant_crop Growth and partitioning parameters Water Use Parameters and Water and temperature Stress Factors Frosting Factors Nitrogen Contents and Nitrogen Stress Factors Ratoon_crop Same as Plant crop section but there is the ability to change the parameters between plant and ratoon crops.
Cultivar Plant Crop Leaf Development Parameters Phenology Sucrose and cane stalk Partitioning Parameters Cultivar Ratoon Crop Same as Plant crop section but there is the ability to change the parameters between plant and ratoon crops.
This is an instantiable module, that is, it can be used in several contexts within the one simulation. For example, this module may be used to simulate a growing crop, while anotherinstance of this module (configured differently) is used simultaneously to represent a weed growing within that crop. There are certain protocols and procedures which must be followed in order to instantiate modules, and these are described in more detail in the module instantiation documentation.
Model Components Overview

Crop dry weight accumulation is driven by the conversion of intercepted radiation to biomass, via a radiation-use efficiency (RUE). RUE is reduced whenever extremes of temperature, soil water shortage or excess, or plant nitrogen deficit limit photosynthesis. The crop leaf canopy, which intercepts radiation, expands its area as a function of temperature, and can also be limited by extremes of temperature, soil water shortage or excess, or plant nitrogen deficit. Biomass is partitioned among the various plant components (leaf, cabbage, structural stem, roots and sucrose) as determined by crop phenological stage. Nitrogen uptake is simulated, as is the return of carbon and nitrogen to the soil in trash and roots. In many sugarcane production systems, commercial yield is measured as the fresh weight of sugarcane stems and their sucrose concentration. Hence, the water content in addition to the dry weight of the stem is simulated. Since sugarcane is grown both as a plant and ratoon crop, the model also needs to be able to simulate differences between crop classes based on any known physiological differences between these classes. Crop growth in the absence of nitrogen or water limitation
Thermal time
Thermal time is used in the model to drive phenological development and canopy expansion. In APSIM-Sugarcane, thermal time is calculated using a base temperature of 9 o C, optimum temperature of 32 o C, and maximum temperature of 45 o C. The optimum and maximum temperatures were taken from those used for maize (Jones and Kiniry, 1986). Base temperatures for sugarcane have been variously reported between 8 o C and 15 o C (Inman-Bamber 1994b, Robertson et al , in press). The base of 9 o C used in APSIM sugarcane was chosen to be consistent with those studies which sampled the greatest temperature range, namely Inman-Bamber 1994b and Robertson et al (in press) who identified base temperatures of 10 o C and 8 o C respectively. For thermal time calculations in the model, temperature is estimated every three hours from a sine function fitted to daily maximum and minimum temperatures, using the method described by Jones and Kiniry (1986).
Phenology
The sugar model uses six different stages to define crop growth and status.
Stage sowing sprouting emergence
Description From sowing to sprouting From sprouting to emergence From emergence to the beginning of cane growth begin_cane From the beginning of cane growth to flowering flowering From flowering to the end of the crop end_crop Crop is not currently in the simulated system.
Sprouting occurs after a lag period, set to 350 o Cdays for plant crops and 100 o Cdays for ratoon crops. Provided the soil water content of the layer is adequate, shoots will elongate towards the soil surface at a rate of 0.8 mm per o Cday. The thermal duration between emergence and beginning of stalk growth is a genotype coefficient in the range 1200 to 1800 o Cdays. Although, sugarcane does produce flowers, the number of stalks producing flowers in a field is highly variable, and its physiological basis is not fully understood. While the model structure has been developed to include flowering as a phenological stage, it has been deactivated until a better physiological basis for prediction is available.
Canopy expansion
The experimental basis for the canopy expansion model is described by Robertson et al (in press). Briefly, green leaf area index is the product of green leaf area per stalk and the number of stalks per unit ground area. Green leaf area per stalk is simulated by summing the fully-expanded area of successive leaves that appear on each stalk, and adding a correction factor for the area of expanding leaves (set to 1.6 leaves per stalk). Profiles of leaf area per leaf are input as genotype coefficients. Robertson et al (in press) found leaf appearance rates declined as a continuous function of cumulative thermal time, so that at emergence leaves took 80 o Cd to appear while leaf 40 required 150 o Cd. These responses are reproduced in the model (via a series of linear interpolations) in both plant and ratoon crops. Stalk number rises rapidly to a peak during the first 1400 o Cdays from emergence, thereafter declining to reach a stable stalk number (e.g. Inman-Bamber, 1994b). Ratoon crops commonly reach an earlier peak stalk number than plant crops, with consequently faster early canopy expansion in ratoons (Robertson et al., 1996). In the model, the complexity of simulating the dynamics of tillering in order to predict LAI during early growth is avoided. Instead, the crop is conceived to have a notional constant stalk number throughout growth, usually set at 10 stalks m -2 , although this value can be varied as an input. The additional leaf area associated with tillers that appear and subsequently die, is captured via a calibrated tillering factor, that effectively increases the area of the leaves that are produced over the early tillering period. The known faster early expansion of LAI in ratoon crops is simulated via two effects. Firstly, the lag time for regrowth of shoots after harvest is shorter in a ratoon crop than is the equivalent thermal time for a plant crop to initiate stalk elongation. Secondly, tillering is recognised in the model coefficients as making a larger contribution to leaf area development in a ratoon crop than a plant crop.
The daily rate of senescence of green leaf area is calculated as the maximum of four rates determined by the factors of ageing, light competition, water stress and frost. In the model, ageing causes senescence by not allowing at any time more than 13 fully-expanded green leaves per stalk. Light competition is simulated to induce senescence once fractional radiation interception reaches 0.85. Water stress induces senescence once the soil water deficit factor for photosynthesis declines below 1.0. Frosting removes 10% of the LAI per day if the minimum temperature reaches 0 o C, and 100% if it reaches -5 o C.
Root growth and development

Root biomass is produced independently from the shoot, so that a proportion of daily above-ground biomass production is added to the root system. The proportion decreases from a maximum of 0.30 at emergence and asymptotes to 0.20 at flowering. Root biomass is converted to root length via a specific root length of 18000 mm g -1 . The depth of the root front in plant crops increases by 1.5 cm day -1 (Glover, 1967) from emergence, with the maximum depth of rooting set by the user. At harvest, 17% of roots in all the occupied soil layer die (Ball-Coelho et al., 1992).
Biomass accumulation and partitioning

The sugar model partitions dry matter to five different plant pools. These are as follows:
Plant Part Root Leaf Sstem Cabbage Sucrose
Description Below-ground biomass Leaf Structural component of millable stalk Leaf sheath and tip of growing stalks etc Sucrose content of millable stalk
In addition to the five live biomass pools outlined above, senescent leaf and cabbage is maintained as trash on the plant or progressively detached to become residues on the soil surface. In APSIM, the RESIDUE module (Probert et al., 1996) takes on the role of decomposition of crop residues. LAI is used in the model to intercept incident solar radiation following Beer's Law, using a radiation extinction coefficient of 0.38, determined by Muchow et al. (1994b) and Robertson et al. (1996). Intercepted radiation is used to produce daily biomass production using a radiation-use efficiency (RUE) of 1.80 g MJ -1 for plant crops and 1.65 g MJ -1 for ratoon crops. The values of RUE used in the model are those adjusted upwards from field-measured values (Muchow et al. 1994b; Robertson et al., 1996a) due to the underestimate of biomass production caused by incomplete recovery of senesced leaf material (Evenson et al., 1995; Robertson et al., 1996). In the model, RUE is reduced if the mean daily temperature falls below 15 o C or exceeds 35 o C, and becomes zero if the mean temperature reaches 5 or 50 o C, respectively. These effects are similar to those used in other models of C 4 crop species (e.g. Hammer and Muchow, 1994). Four above-ground biomass pools are modelled: leaf, cabbage, structural stem, stem sucrose, and an additional pool for roots that is simulated separately from above-ground production. Between emergence and the beginning of stalk growth, above-ground biomass is partitioned between leaf and cabbage in the ratio 1.7:1 (Robertson et al., 1996a). After the beginning of stem growth 0.7 of aboveground biomass is partitioned to the stem (Robertson et al., 1996a), with the remainder partitioned between leaf and cabbage in the ratio 1.7:1. After a minimum amount of stem biomass has accumulated, the daily biomass partitioned to stem is divided between structural and sucrose pools, following the framework developed by Muchow et al. (1996a) and Robertson et al. (1996a). Thereafter, the stem biomass is equal to the sum of structural and sucrose pools. If biomass partitioned to leaf is insufficient for growth the leaf area, as determined by a maximum specific leaf
area, then daily leaf area expansion is reduced. If biomass partitioned to leaf is in excess of that required to grow the leaf area on that day, then specific leaf area is permitted to decrease to a lower limit, beyond which the excess biomass is partitioned to sucrose and structural stem. A stalk growth stress factor is calculated as the most limiting of the water, nitrogen and temperature limitations on photosynthesis. This stress factor influences both the onset and rate of assimilate partitioning to sucrose at the expense of structural stem.
Stem water content

A stem water pool is simulated for the purposes of calculating cane fresh weight and CCS%. For every gram of structural stem grown, a weight of water is considered to have been accumulated by the cane stems. This relationship varies with thermal time, ranging from 9 g g -1 initially, to 5 g g -1 late in the crop life cycle. The former represents the water content of young stem (eg. cabbage) while the latter represents a combination of young stem growth and thickening of older stem. Sucrose deposition in the stem removes water content at the rate of 1 g water g -1 sucrose.
Varietal effects
Currently varieties differ in only two respects in the model. Firstly, Inman-Bamber (1991) found that varieties in South Africa differed in the fully-expanded area of individual leaves. The distributions for NCo376 and N14 were taken from Inman-Bamber and Thompson (1989), while that for Q117 and Q96 was those assigned values that gave best fit to the time-course of LAI during the model calibration stage. Secondly, Robertson et al. (1996a) found that varieties from South Africa and Australia differed in terms of partitioning of biomass to sucrose in the stem. There is scope for incorporating other varietal differences as new knowledge becomes available.
Water deficit limitation

Soil water infiltration and redistribution, evaporation and drainage is simulated by other modules in the APSIM framework (Probert et al., 1996, Verburg et al, 1997). Water stress in the model reduces the rate of leaf area expansion and radiation-use efficiency, via two soil water deficit factors, which vary from zero to 1.0, following the concepts embodied in the CERES models (Ritchie, 1986). Soil water deficit factor 1 (SWDEF1), which is less sensitive to soil drying, reduces the radiation-use efficiency (i.e. net photosynthesis) and hence transpiration, below its maximum. Soil water deficit factor 2 (SWDEF2), which is more sensitive to soil drying, reduces the rate of processes governed primarily by cell expansion, i.e. daily leaf expansion rate. SWDEF1 and 2 are calculated as a function of the ratio of potential soil water supply from the root system and the transpiration demand. Following Sinclair (1986) and Monteith (1986), transpiration demand is modelled as a function of the current day's crop growth rate, divided by the transpirationuse efficiency. When soil water supply exceeds transpiration demand, assimilate fixation is a function of radiation interception and radiation use efficiency. When soil water supply is less than transpiration demand, assimilate fixation is a function of water supply and transpiration efficiency and the vapour pressure deficit (VPD). Transpiration-use efficiency has not been directly measured for sugarcane, but calibration of the current model on datasets exhibiting water deficits (Robertson et al, unpubl. data) resulted in the use of a transpiration-use efficiency of 8 g kg -1 at a VPD of 1 kPa. This efficiency declines linearly as a function of VPD (Tanner and Sinclair, 1983). This compares with reported values of 9 g kg -1 kPa -1 for other C 4 species (Tanner and Sinclair 1983), a value that has been used in the models of sorghum (Hammer and Muchow, 1994) and maize (Muchow and Sinclair, 1991).
Potential soil water uptake is calculated using the approach first advocated by Monteith (1986) and subsequently tested for sunflower (Meinke et al., 1993) and grain sorghum (Robertson et al., 1994). It is the sum of root water uptake from each profile layer occupied by roots. The potential rate of extraction in a layer is calculated using a rate constant, which defines the fraction of available water able to be extracted per day. The actual rate of water extraction is the lesser of the potential extraction rate and the transpiration demand. If the computed potential extraction rate from the profile exceeds demand, then the extracted water is removed from the occupied layers in proportion to the values of potential root water uptake in each layer. If the computed potential extraction from the profile is less than the demand then SWDEF2 declines in proportion, and the actual root water uptake from a layer is equal to the computed potential uptake. In addition to the effects on canopy expansion and biomass accumulation, water stress influence biomass partitioning in the stem in two ways. Firstly, the minimum amount of stem biomass required to initiate sucrose accumulation declines with accumulated stress. Secondly, the daily dry weight increment between structural stem and sucrose shifts in favour of sucrose as water deficits develop.
Water excess limitation

The proportion of the root system exposed to saturated or near saturated soil water conditions is calculated and used to calculate a water logging stress factor. This factor reduces photosynthetic activity via an effect on RUE.
Nitrogen limitation
N supply from the soil is simulated in other modules in the APSIM framework (Probert et al., 1996). Crop nitrogen demand is simulated using an approach similar to that used in the CERES models (Godwin and Vlek 1984). Crop N demand is calculated as the product of maximum tissue N concentration and the increment in tissue weight. Separate N pools are described for green leaf, cabbage, millable stalk and dead leaf. The sucrose pool is assumed to have no nitrogen associated with it. Only the leaf N concentrations influence crop growth processes. Growth is unaffected until leaf N concentrations fall below a critical concentration. Sugarcane has been shown to exhibit luxury N uptake (Muchow and Robertson 1994 ; Catchpoole and Keating 1995) and the difference between the maximum and critical N concentrations is intended to simulate this phenomenon. Nitrogen stress is proportional to the extent to which leaf N falls between the critical and the minimum N concentration. Senescing leaves (and the associated leaf sheaths contained in the cabbage pool) are assumed to die at their minimum N concentrations and the balance of the N in these tissues is retranslocated to the green leaf and cabbage pools. Maximum, critical and minimum N concentrations are all functions of thermal time, and were chosen on the basis of the findings of Catchpoole and Keating (1995) and Muchow and Robertson (1994) and subsequently refined during the model calibration. Critical green leaf concentrations used in the model differ between photosynthetic, leaf expansion and stem growth processes. For photosynthesis they begin at 1.2% N at emergence or ratooning and asymptote towards 0.5%N at flowering. For leaf area expansion they are 1.3 and 0.5% N and stem growth, 1.5 and 0.5%N. N uptake cannot exceed N demand by the crop and is simulated to take place by mass flow in the water that is used for transpiration. Should mass flow not meet crop demand and nitrate be available in soil layers, the approach of van Keulen and Seligman (1987) is used to simulate the uptake of nitrate over and above that which can be accounted for by mass flow. While van Keulen and Seligman (1987) referred to this approach as diffusion, the routine more realistically serves as a surrogate for a number of sources of uncertainty in nitrate uptake.
Nitrogen stress also influences biomass partitioning in the stem, in a similar fashion to that described above for water stress.
Other features of the sugar module

APSIM-Sugarcane includes a number of features relevant to sugarcane production systems. Either plant or ratoon crops can be simulated at the outset or a plant crop will regenerate as a ratoon crop if a crop cycle is being simulated. Production systems of plant - multiple ratoon - fallow can be simulated or alternatively other APSIM crop or pasture modules can be included in rotation with sugarcane. Trash can be burnt or retained at harvest time. Insect or other biological or mechanical damage to the canopy can be simulated via graze actions. Many sugarcane crops are hilled-up early in canopy development, an operation that involves the movement of soil from the interrow to the crop row. This operation facilitates irrigation operations and improves the crop's ability to stand upright. APSIM-Sugarcane responds to a management event of hilling-up by removal of lower leaf area and stem from the biomass pools. Lodging is a widespread phenomenon in high-yielding sugarcane crops. The APSIM-MANAGER (McCown et al 1996) can initiate a lodging event in response to any aspect of the system state (eg crop size, time of year and weather). APSIM SUGARCANE responds to lodging via four effects: 1) A low rate of stalk death which has been widely observed in heavily lodged crops (Muchow et al., 1995; Robertson et al., 1996; Singh et al., 2002); 2) A reduction in radiation use efficiency (Singh et al., 1999; Singh et al., 2002); 3) A reduction in the proportion of daily biomass that is partitioned as sucrose (Singh et al., 2002); and 4) A reduction in the maximum number of green leaves to capture the reported reduction in leaf appearance rate and increase in leaf senescence (Singh, 2002; Singh et al., 2002). Sugar Module Outputs
Variable Name Stage_name Stage Crop_status ratoon_no
Description Name of the current crop growth stage Current growth stage number Status of the current crop (alive, dead, out) Ratoon number (0 for plant crop, 1 for 1 st ratoon, 2 for 2 nd ratoon, etc) das Days Days after sowing (ie. crop duration) Ep Mm Crop evapotranspiration (extraction) for each soil layer cep Mm Cumulative plant evapotranspiration rlv mm.mm -3 root length per volume of soil in each soil layer esw mm Extractable Soil water in each soil layer root_depth Mm Root depth sw_demand Mm Daily demand for soil water biomass g.m -2 Total crop above-ground biomass (Green + Trash) green_biomass g.m -2 Total green crop above-ground biomass biomass_n g.m -2 Total Nitrogen in above-ground biomass (Green + Trash) green_biomass_ng.m -2 Amount of Nitrogen in green above-ground biomass dlt_dm g.m -2 Daily increase in plant dry matter (photosynthesis) dm_senesced g.m -2 Senesced dry matter in each plant pool n_senesced g.m -2 Amount of Nitrogen in senesced material for each plant
Units
Canefw ccs Cane_wt leaf_wt root_wt sstem_wt sucrose_wt cabbage_wt n_conc_cane n_conc_leaf n_conc_cabbage n_demand cover_green cover_tot lai tlai slai n_leaf_crit n_leaf_min nfact_photo nfact_expan swdef_photo swdef_expan swdef_phen
t.ha -1 % g.m -2 g.m -2 g.m -2 g.m -2 g.m -2 g.m -2 g.g -1 g.g -1 g.g -1 g.m -2 0-1 0-1 mm -2 .mm -2 mm -2 .mm -2 mm -2 .mm -2 g.m -2 g.m -2 0-1 0-1 0-1 0-1 0-1
pool Fresh Cane weight Commercial Cane Sugar Weight of cane dry matter Weight of plant green leaf Weight of plant roots Weight of plant structural stem Weight of plant sucrose Weight of plant cabbage Nitrogen concentration in cane Nitrogen concentration in green leaf Nitrogen concentration in green cabbage Daily demand for Nitrogen Fractional cover by green plant material Fractional cover by total plant material (Green + Trash) Leaf area index of green leaves Total plant leaf area index (green + senesced) Senesced leaf area index Critical Nitrogen level for the current crop Minimum Nitrogen level for the current crop Nitrogen stress factor for photosynthesis Nitrogen stress factor for cell expansion Soil water stress factor for photosynthesis Soil water stress factor for cell expansion Soil water stress factor for phenology
Sugar Model Validation Examples Crop Growth and Development

The capability of the APSIM sugar model to describe crop growth has been tested widely in a number of areas of current model application. The following show the response of the model in simulating growth of total biomass, cane and sucrose in varying environments. Note : Current simulations of cane water content are unreliable in some regions prior to final harvest.
Nitrogen Uptake and Response

The applicability of the APSIM sugar model under differing nitrogen supply has been tested with several data sets. The following example is for a plant and ratoon crop at Macknade in 1993-1994 for three nitrogen fertiliser rates (0 and 50 kg N/ha and a continuous N non-limiting treatment).
Nitrate Leaching under Sugarcane

(See Evaluation of Nitrogen fertiliser management strategies under sugarcane using APSim-Swim, Verburg et al in the Appendices)
The use of APSIM sugarcane model for nitrogen leaching study has been tested using experimental data from Bundaberg field study. The soil was a red-yellow podsolic with a marked textual change at 0.8m depth. Crop management included 3 nitrogen rates (0, 160 and 320 kg N/ha) for an irrigated first ratoon crop of CP51-21. A bromide tracer was applied to some of the sub-plots.
Soil Water
Bromide
Nitrate
REFERENCES
Ball-Coelho, B. Sampaio, E. V. S. B.; Tiessen, H.; Stewart, J. W. B. (1992). Root dynamics in plant and ratoon crops of sugar cane. Plant and Soil 142:297-305. Evenson, C. I., Muchow, R. C., El-Swaify, S. A., and Osgood, R. V. (1995). Yield accumulation in irrigated sugarcane. I. Effect of crop age and variety. Agron. J . (in press). Glover, J. (1967). The simultaneous growth of sugarcane roots and tops in relation to soil and climate. Proc. S. Afr. Sugar Technol. Assoc ., 143-159. Godwin, D.C. and Vlek, P.L.G. (1984). Simulation of nitrogen dynamics in wheat cropping systems. In : Day, W. and Atkin, R.K. (eds), Wheat growth and modelling. Plenum Press, New York, pp 311332. Hammer, G. L. and Muchow, R. C. (1994). Assessing climatic risk to sorghum production in waterlimited subtropical environments I. Development and testing of a simulation model. Field Crops Research , 36: 221-234. Inman-Bamber NG and Thompson GD (1989). Models of dry matter accumulation by sugarcane. Proc. S. Afr. Sugar Technol. Assoc., 212-216 . Inman-Bamber NG (1994b) Temperature and seasonal effects on canopy development and light interception of sugarcane. Field Crops Research , 36: 41-51.
Jones, C. A., Kiniry, J. R. (1986) (Editors), CERES-Maize: A simulation model of maize growth and development., Texas A&M University Press, PP. 37-48. Catchpoole, V.R. and Keating, B.A. (1995) Sugarcane yield and nitrogen uptake in relation to profiles of mineral-nitrogen in the soil. Proc. 17th Aust. Soc. Sugarcane Technol. , pp 187-192. McCown RL, Hammer GL, Hargreaves JNG, Holzworth DP and Freebairn DM (1995). APSIM: A novel software system for model development, model testing, and simulation in agricultural systems research. Agric. Syst. 50, 255-271 Monteith, J. L. (1986). How do crops manipulate water supply and demand? Phil. Trans. Royal Soc. Lond. A , 316: 245-289. Muchow RC, Robertson MJ, Wood AW, Spillman M F (1994a) Effect of soil fumigation on sugarcane productivity under high-yielding conditions in north Queensland. Proc. Aust. Soc. Sugar Cane Technol. , 1994 Conf., 187-92. Muchow RC, Robertson MJ & Wood AW (1996a) Growth of sugarcane under high input conditions in tropical Australia. II. Sucrose accumulation and partitioning, and commercial yield.Field Crops Research 48:27-36. Muchow, R. C. and Robertson, M. J. (1994). Relating crop nitrogen uptake to sugarcane yield. Proc.Aust. Soc. Sugarcane Technol. , 1994, 122 - 130. Muchow RC, Robertson MJ,Wood AW & Keating BA (1996b) Effect of nitrogen on the time-course of sucrose accumulation in. Field Crops Research 47: 143-153. Muchow RC, Spillman MF, Wood AW & Thomas MR (1994b) Radiation interception and biomass accumulation in a sugarcane crop grown under irrigated tropical conditions. Aust. J. Agric. Research 45, 37-49. Muchow, R. C., Wood, A. W. and Robertson, M. J. (1995) Does stalk death set the yield ceiling in high yielding sugarcane crops? Proc. Aust. Soc. Sugar Cane Technol. 17 , 142 - 148. Muchow RC, Wood AW, Spillman MF, Robertson M J & Thomas MR (1993) Field techniques to quantify the yield-determining processes in sugarcane. I. Methodology. Proc. Aust. Soc. Sugar Cane Technol. , 1993 Conf., 336-343. Probert ME, Dimes JP, Keating BA, Dalal RC, Strong WM (1997). APSIM's water and nitrogen modules and simulation of the dynamics of water and nitrogen in fallow systems. Agric. Syst. (in press). Ritchie, J. T. (1986). In: Jones, C. A., Kiniry, J. R. (1986) (Editors), CERES-Maize: A simulation model of maize growth and development., Texas A&M University Press, PP. 37-48. Robertson MJ, Muchow RC, Inman-Bamber, NG, Wood AW (1996) Relationship between biomass and sucrose accumulation in sugarcane. in Sugarcane: Research Towards Efficient and Sustainable Production Wilson JR, Hogarth DM, Campbell JA and Garside AL (eds). CSIRO Division of Tropical Crops and Pastures, Brisbane. 1996, pp 84-86. Robertson, M.J. Bonnett, G.D. and Campbell. J.A. (in press). Effects of temperature on leaf area expansion in sugarcane: controlled-environment, field and model analyses. Field Crops Research (in prep.) Robertson, M. J., Wood, A. W., and Muchow, R. C. (1996) Growth of sugarcane under high input conditions in tropical Australia. I. Radiation use, biomass accumulation and partitioning.Field Crops Res . 48 , 11 25. Sinclair, T. R. (1986). Water and nitrogen limitations in soybean grain production. I Model development. Field Crops Research , 15: 125-141. Singh, G. (2002) Constraints to High Yield and CCS in Large and Lodged Cane Crops. Ph D Thesis (submitted to James Cook University). Singh, G., Chapman, S. C., Jackson, P. A. and Lawn, R. J. (1999) Yield accumulation in sugarcane under wet tropical conditions - effect of lodging and crop age. Proc. Aust. Soc. Sugar Cane Technol. 21 , 241 - 245. Singh, G., Chapman, S. C., Jackson, P. A. and Lawn, R. J. (2002) Lodging reduces sucrose accumulation of sugarcane in the wet and dry tropics. Aust. J. Agric. Res. 53 , 1183 1195.
Tanner, C. B. and Sinclair, T. R. (1983). Efficient water use in crop production: research or research? in "Limitations to Efficient Water use in Crop Production" (Eds. H. M. Taylor, W. R. Jordan, T. R. Sinclair). pp.1-27. ASA, Madison, Wisconsin. Van Keulen, H. and Seligman, N.G. (1987). Simulation of water use, nitrogen nutrition and growth of a spring wheat crop. Pudoc Wageningen, 310pp. Verburg, K., Ross, P.J. and Bristow, K.L. (1997) SWIMv2 Manual. CSIRO Division of Soils Divisional Report, CSIRO, Australia, 93 pp. (in press).
What does the SURFACE module do?

The Surface module is a small plug-in-pull-out APSim module that communications with the APSwim module to simulate changes in surface seal conductance through time (See the APSwim documentation for more information regarding surface seals within the SWIM water balance model).
The Surface module is able to communicate with APSwim upon each internal SWIM time step to update surface conductance during high intensity rainfall events where SWIM time steps are of short duration.
Essentially, the SURFACE calculations "overwrite" the internal SWIM calculations of surface seal just prior to SWIM's attempt at solving its equations for the time step.
Things to note when using the SURFACE module.

APSwim must be parameterised to use the option for a surface conductance function for the top boundary condition. There are 2 surface seal models available within SURFACE. o The first model replicates the internal surface seal model of SWIM and this option can be used to regression test the operation of the SURFACE module. o The second model is based upon the work of Silburn & Connolly ( Journal of Hydrology , 172 (1995) 87-104.)
In the APSIM v4.0 release, the functionality previously found in the RESIDUE and MANURE modules was incorporated into this new module, SurfaceOM. Description
The processes included in the SurfaceOM module are depicted in Figure 1. Briefly, the above ground material can be burnt (or removed from the system in some other way, e.g. baling), incorporated into the soil during tillage operations, or decomposed.
Above ground residues are considered as consisting of a mixture of one or more different materials (or component parts), each of which is defined in terms of:

Mass (kg/ha) Overall C:N ratio () Overall C:P ratio () Standing Fraction (0-1)
Type (eg wheat, lucerne, eucalyptus leaves etc) from which SURFACEOM will determine the following information: o Overall Carbon fraction (0-1) o Specific Area (ha/kg) o Potential Decomposition Rate (/day) o Mineral Composition (nh4, no3,and po4 (in ppm)) o C,N,P fractions in each of the fresh organic matter (FOM) pools (i.e. carbohydrate, cellulose, lignin)
SURFACEOM module outputs can either refer to the entire mixture of surface materials, or to specific components. When new material is added (e.g. at harvest), the material will either enter an existing surface organic matter component (eg wheat) or may start a new component, if that residue is a new addition to what is already present in the system (for example, wheat trash being added to existing lucerne residues, at harvest). Each component is kept separate for calculations of C:N ratio, decomposition, and specific area. An overall effective cover value (0-1) is calculated using all surface organic matter components present, for the purposes of subsequently calculating surface material effect on soil evaporation and runoff. If a particular surface organic matter type has soluble inorganic N components (NO3-N and NH4-N), these may be transferred to the respective soil pools by leaching due to rainfall or irrigation. The cumulative amount of rain and irrigation to transfer all of the soluble components is specified as an input; the amount leached is proportional to cumulative rain. It is possible to specify that a certain proportion of any particular surface organic matter is 'standing', that is, inert from the processes of decomposition. The default value for this proportion is zero, in other words, all the material is decomposable. See section below on 'Standing/Lying Components'
Tillage results in a transfer of some surface OM into the soil FOM pool. With tillage, surfaceOM N and C is incorporated into soil layers to the nominated tillage depth, and added to the respective soil mineral N and the fresh organic matter pools (FOM). Incorporated surfaceOM C and N is partitioned into the rapid, medium and slowly decomposing FOM pools according to nominated fractions. This fractionation is dependant upon the type of OM and so differences between crop residues and animal manures, for example, can be specified.
Decomposition results in loss of some carbon as CO2 and transfer of carbon and nitrogen to the soil. Decomposition of residues with a high C:N ratio creates an immobilisation demand, which is satisfied from mineral-N in the uppermost soil layers; in extreme situations, inadequate mineral-N in soil restricts decomposition of residues.
Figure 1. Schematic representation of the processes in the SURFACEOM module. (Note that default values of zero are used for mineral N and P components in plant residues)
Surface Organic Material Decomposition

Decomposition of surface OM's is calculated using a simple exponential decay algorithm where the fraction of each component decaying on any day (Fdecomp) is calculated as follows: Fdecomp = Potential Decomposition Rate x Moisture Factor x Temperature Factor x C:N ratio Factor x Contact Factor
From this fraction, potential amounts of carbon and nitrogen to move into the soil are calculated for each component. Any module responsible for soil organic matter pools (such as the SOILN module) can use this potential supply of carbon and nitrogen in its calculations. The actual value of decomposition (that is a final soil limited value) for each component is passed
back to the SURFACEOM module and above-ground component pools are updated using this value of decomposition. Descriptions of the various factors affecting decomposition follows:
The moisture factor for decomposition The moisture factor affecting decomposition in the SURFACEOM module uses cumulative potential soil evaporation (EOS) to capture the effect that dry residues decompose more slowly than wet residues. It is assumes that residues dry out at a rate proportional to Eos, and that a critical cumulative evaporation (cum_eos_max) results in residues becoming so dry that decomposition ceases. Moisture Factor = 1.0 - SEOS/cum_eos_max The factor is constrained to values between 0 and 1.
The temperature factor for decomposition The effect of temperature on residue decomposition is described by: Temperature Factor = (average air temperature / opt_temp)2 where: average air temperature = (maxt + mint) / 2 This factor is then constrained to values between 0 and 1. The resultant relationship is shown in the following figure for three values of optimum temperature. (tf = 20 is the default). If average temperature is less than zero, the temperature factor is zero.
The C:N ratio factor for decomposition
where CN = C:N ratio of surface residues CNopt = Optimum C:N ratio for decomposition k = coefficient determining slope of curve. This factor is calculated for individual residue types rather than for the entire mixture and is constrained to values between 0 and 1. The standard values used with SURFACEOM are k = 0.277 and CNopt = 25. The resultant curve is as follows:
The soil contact factor on decomposition Where large amounts of surface residues are present, overall rates of decomposition will be lower. It is presumed that the material in immediate contact with the soil decomposes more rapidly than that piled on top (a "haystack" effect). To account for this a Contact Factor discounts decomposition according to the amount of residue. The relation currently used is based on work by Thorburn et al.(2001) , and involves the concept of a critical mass of surface organic matter at which the "haystack effect" is deemed to become relevant. It may be summarized as:

If surfaceom_wt < critical mass then cf = 1.0 or If surfaceom_wt > critical mass then cf = critical mass/surfaceom_wt
Not all surface residues contribute to this "haystack effect". Standing residues are excluded, and some residues on the soil surface can be specified to only contribute partially to the effect. For example, course woody debris would not contribute but fine leaf litter would.
Tillage of above-ground residues

Residues are incorporated into the soil profile using a tillage command. For example, the following manager command will incorporate 50% of residues into the top 100mm of soil. (Note: the following information needs to be specified on a single line in APSIM manager logic)
surfaceom tillage type = ''user_defined'', f_incorp = 0.5 (0-1), tillage_depth = 100. (mm)
Alternatively, the user can specify tillage operations in terms of an implement, with the corresponding values of f_incorp and tillage_depth being defined in the SURFACEOM module's constants file. Some examples are:
surfaceom tillage type = disc ()
or
surfaceom tillage type = burn ()
In the "burn" example, the tillage type is specified to incorporate to a zero depth, and the fraction of organic matter specified to be incorporated will be lost from the system. Each time a "tillage" is specified, all surface organic materials are effected.
If the user is wanting to simulate a situation where only one of the surface materials is incorporated (eg. Digging manure into row spaces between existing crop stubbles) leaving the remainder intact, there is a specific command available called "tillage_single". The syntax is as follows:
surfaceom tillage_single name = manure , type = ''disc''()
The "name"refers to the specific name in the system of the surfaceom to be tilled. Subsequent arguments are as for the standard "tillage" command (see above).
SurfaceOM Cover
SurfaceOM cover is calculated by combining the individual masses of surface OM types and their specific areas (i.e. an area of cover per unit mass) Currently, both "standing" and "lying" fractions are considered to contribute to cover. However, increasing amounts of surface OM have diminishing effects due to the additional residue overlaying other residues rather than covering bare soil. This can be described as: dC/dS = 1 - C (1) where C is the effective fractional residue cover, and S is the total surface area of residues per unit area and hence C = 1 - eS (2)
SurfaceOM Input Parameters

Name name type mass cnr cpr (optional)* Units kg/ha Description Individual residue name Specific residue type (referenced to .ini file) Initial amount of surface OM Initial C:N ratio of surface OM Initial C:P ratio of surface OM Standing or inert component of surface material
standing_fraction (optional)* (0-1)
* - if optional parameters are not supplied then defaults from constants file are used. All SurfaceOM module input parameters are arrays, hence several surface OM types can be initially specified as existing in the simulation. For example:
[all.surfaceom.parameters] name = wheat_old wheat_new type = wheat wheat mass = 350.0 2000.0 cnr = 100.0 75.0
lucerne lucerne 400.0 35.0 ()
! ! ! !
name of surface OM material type of surface OM material mass of surface OM (kg/ha) C:N ratio of surface OM
If desired, only a single surface OM may be specified (in similar fashion to the old APSIM RESIDUE2 module), or up to a maximum of 100 materials. The "name" of the surfaceom is a unique identifier of that surfaceom pool. The "type" is the specific type of material, used to reference further information for that type. In other words, there can be several surfaceom's of the same "type" in the system, but only one instance of each "name" is allowed. See the above example, where residues from an old wheat crop are present together with new residues from a more recent wheat crop. They are both of the same "type", but are considered as separate pools, each with an individual "name", wheat_old and wheat_new.
When a crop discards leaves/stems etc, they are added to the SURFACEOM module in a pool with the "name" and "type" equal to the crop name, i.e. wheat, chickpea.
SurfaceOM Standing/Lying Components

For individual surface materials, it is possible to specify how much of that material is "standing" using an optional input parameter called "standing_fraction". If it is not supplied, the default value of 0.0 is applied. The standing fraction is considered to be the inert component of the material, i.e. not subject to daily decomposition. It is however, subject to incorporation during tillage events. Currently there is no algorithm describing the movement of material from the "standing" pool to the "lying" (decomposable) pool, however in future it is planned to convert standing material to lying material on a daily basis as a function of such parameters as time, rainfall, stocking rates, field operations. etc. Information on the "standing" component can be supplied to the SurfaceOM module as follows:
[all.surfaceom.parameters]
name = wheat_old wheat_new type = wheat wheat mass = 350.0 2000.0 cnr = 100.0 75.0 standing_fraction = 0.0
! ! ! !
name of surface OM material type of surface OM mass of surface OM (kg/ha) C:N ratio of surface OM 0.4 ! standing (or inert) fraction
SurfaceOM Phosphorus
It is possible to trace the addition and decomposition of phosphorus through surface residues in conjunction with the APSIM SoilP module. The user is required to provide an extra parameter to state the initial C:P ratio for surface residues.
[all.surfaceom.parameters] name = maize ! name of surface OM material type = maize ! type of surface OM material mass = 2000 (kg/ha) ! mass of surface OM material cnr = 75.0 () ! C:N ratio surface OM material cpr = 250.0 () ! C:P ratio surface OM material
The addition of this extra parameter will result in the SurfaceOM module becoming aware of the need for maintaining a phosphorus balance, and daily interactions with the SoilP module will occur. (Note, if the "cpr" parameter is provided, the SoilP module must be included in the simulation). In the above example, 2000 kg/ha of maize residue is added with a C:P ratio of 250. This will result in 2000kg x 0.4 (kg C/kg biomass)/250 (kg C/kg P) = 3.2 kg P/ha in surface OM.
Resetting SurfaceOM
The reset action can be invoked to reset the module to the state specified within the module's input data, which includes the surfaceom weight, nitrogen and phosphorus contents, and cover. This is identical to the initialise action used by the simulation engine at the start of the simulation except that a description of the reinitialised state is not printed in the simulation summary file. APSIM Manager Example:
[sample.manager.start_of_day] ! reinitialise residues at the beginning of each sowing window If day = 100 then surfaceom reset endif
Summary Report
At initialisation, at series of tables and useful information is printed to the simulation summary file for perusal by the user. These tables can also be printed to the summary file at any instance during the simulation as a
detailed record of the system state at a particular time. For the surfaceom module, this output consists of surfaceom names, types, weights, organic carbon, nitrogen, and phosphorus, mineral components, and standing fraction. APSIM Manager Example:
[sample.manager.start_of_day] ! Print out a summary of module state to the summary file If day = 100 then surfaceom sum_report endif
Addition of Surface Organic Materials

Organic materials can be added to the soil surface using the add_surfaceom action. APSIM Manager Example: NOTE: actions must be specified as a single line in the manager file rather than as shown below.
If day = 100 then surfaceom add_surfaceom name = wheat, type = wheat, mass = 1000. (kg/ha), n = 5 (kg/ha) endif
or to specify nitrogen content using a C:N ratio
If day = 100 then surfaceom add_surfaceom name = wheat, type = wheat, mass = 1000. (kg/ha), cnr = 80 () endif
If the simulation is to contain a phosphorus balance then the phosphorus content of the added residue must also be added. For the examples above the user would add the extra information as follows:
If day = 100 then
surfaceom add_surfaceom name = wheat,type = wheat,mass = 1000. (kg/ha),n = 5 (kg/ha),p = 2 (kg/ha) endif
or to specify phosphorus content using a C:P ratio
If day = 100 then surfaceom add_surfaceom name = wheat,type = wheat,mass = 1000. (kg/ha),n = 5 (kg/ha),cpr = 200 (kg/ha) endif
An example of how a source of manure (named FYM which will have its C content specified in the surfaceOM.ini file) would be applied at 10 t ha-1 and incorporated using the C:N and C:P ratios to specify the N and P contents is:
If day = 100 then surfaceom add_surfaceom name = fym1,type = fym,mass = 10000. (kg/ha),cnr = 15 (),cpr = 30 () surfaceom tillage_single name = fym1, type = hoe () endif
Note that the "tillage_single" action will only incorporate the surface OM specified by "name" as fym1. Guidelines on characterization of manures are provided in Appendix 1.
Use of variables in user-defined manager commands

APSIM Manager Example:
if surfaceom.surfaceom_wt > 4.0 then remove_amount = surfaceom.surfaceom_wt - 4.0 remove_fraction = remove_amount/surfaceom.surfaceom_wt surfaceom tillage type=user_defined, f_incorp = remove_fraction , tillage_depth=0.0
endif
SurfaceOM module outputs

TOTAL Surface OM
Name surfaceom_wt surfaceom_c surfaceom_n surfaceom_p surfaceom_no3 surfaceom_nh4
Units kg/ha kg/ha kg/ha kg/ha kg/ha kg/ha
Description Total mass of all surface organic materials Total mass of organic carbon Total mass of organic nitrogen Total mass of organic nitrogen Total mass of nitrate Total mass of ammonium Total mass of labile phosphorus Fraction of ground covered by all surface OM's Temperature factor for decomposition Water factor for decomposition Contact factor for decomposition
surfaceom_labile_p kg/ha surfaceom_cover tf wf cf 0-1 0-1 0-1 0-1
INDIVIDUAL Surface Om's
Name surfaceom_wt_xxxx surfaceom_c_xxxx surfaceom_n_xxxx surfaceom_p_xxxx surfaceom_no3_xxxx surfaceom_nh4_xxxx
Units kg/ha kg/ha kg/ha kg/ha kg/ha kg/ha
Description Mass of the SurfaceOM named "xxxx" * Mass of organic carbon in "xxxx" Mass of organic nitrogen in "xxxx" Mass of organic nitrogen in "xxxx" Mass of nitrate in "xxxx" Mass of ammonium in "xxxx" Mass of labile phosphorus in "xxxx"
surfaceom_labile_p_xxxx kg/ha
Name surfaceom_c1_xxxx surfaceom_c2_xxxx surfaceom_c3_xxxx surfaceom_n1_xxxx surfaceom_n2_xxxx surfaceom_n3_xxxx surfaceom_p1_xxxx surfaceom_p2_xxxx surfaceom_p3_xxxx pot_c_decomp_xxxx pot_n_decomp_xxxx pot_p_decomp_xxxx standing_fraction_xxxx surfaceom_cover_xxxx cnrf_xxxx
Units kg/ha kg/ha kg/ha kg/ha kg/ha kg/ha kg/ha kg/ha
Description Mass of organic carbon in "xxxx" Mass of organic carbon in "xxxx" in fpool2 Mass of organic carbon in "xxxx" in fpool3 Mass of organic nitrogen in "xxxx" in fpool1 Mass of organic nitrogen in "xxxx" in fpool2 Mass of organic nitrogen in "xxxx" in fpool3 Mass of organic phosphorus in "xxxx" in fpool1 Mass of organic phosphorus in "xxxx" in fpool2
kg/ha< Mass of organic phosphorus in "xxxx" in fpool3 kg/ha kg/ha kg/ha 0-1 0-1 0-1 Potential organic C decomposition in "xxxx" Potential organic N decomposition in "xxxx" Potential organic P decomposition in "xxxx" Fraction of "xxxx" which is inert, ie not in contact with the ground Fraction of ground covered by "xxxx" C:Nratio factor for decomposition for "xxxx"
* - "xxxx" is the "name" of an individual surface organic material, for example "wheat" , "lucerne", "ox_manure" etc.
References
Probert M.E., Dimes J.P., Keating B.A., Dalal R.C., Strong W.M. APSIM's water and nitrogen modules and simulation of the dynamics of water and nitrogen in fallow systems, Agric. Syst. 56 (1998), pp 1-28. Thorburn P.J., Probert M.E., Robertson F.A. Modelling decomposition of sugar cane surface residues with APSIM-Residue, Field Crops Research 70 (2001), pp 223-232.
APPENDIX Guidelines for characterizing manure

In APSIM the organic forms of C, N and P in OM additions are distributed between three pools.
Upon incorporation these pools are added to the corresponding FPOOLs (i.e. carbohydrate, cellulose, lignin) that comprise FOM (fresh organic matter) in the SoilN module. To date all efforts to simulate the effects of manure have been for situations where the manure has been fully incorporated soon after application. The minimum data required to specify a manure source are the same as those required for any other OM source: a name (to specify a particular batch of manure), a type (to distinguish the type of manure), its composition (C, N and P) and the allocation of C, N and P to the three pools. The fraction of C in the manure and the allocation of C, N and P between the pools is stipulated for the particular manure type in the SurfaceOM.ini file (as in the example below) but the contents of N and P are input as part of the manager command when manure is added to the system (either as amounts (kg/ha) or as C:N and C:P ratios) as shown in the previous sections of this document.
[standard.surfaceom.fym] fom_type = fym fraction_C = 0.30 ! The fraction of carbon in HQM (0-1) pot_decomp_rate = 0.01 ! Decomposition rate (day-1) for manure on soil surface fr_c = 0.1 0.5 0.4! The fractional allocation of carbon to each of the three pools fr_n = 0.1 0.5 0.4 ! The fractional allocation of nitrogen to each of the three pools fr_p = 0.1 0.5 0.4 ! The fractional allocation of phosphorus to each of the three pools po4ppm = 10.0 ! labile P concentration (ppm) nh4ppm = 100.0 ! ammonium-N concentration (ppm) no3ppm = 10.0 ! nitrate-N concentration (ppm) specific_area = 0.0001 ! specific area (ha/kg) cf_contrib = 1
In this example, the allocation of C, N and P to the three pools is identical and so the C:N and C:P ratios of all three pools will be equal to those based on the total C, N and P concentrations.
Modelling short-term dynamics

Using data from laboratory incubation studies, it has been shown that the assumption of the same allocation of C and N across all three pools is not consistent with the observed pattern of mineralization for a range of manures (Probert et al. 2005).
The initial period of immobilization of N (in the first few weeks) and the period before the system showed net mineralization could be simulated only if the FPOOLs had different C:N ratios. Probert et al. (2005) used information from proximate analysis of the manures to distribute C and N between the pools. They identified FPOOL1 with the soluble C and N components, FPOOL3 with the lignin carbon (ADL), and FPOOL3 by difference. An example:
fr_c = 0.10 0.70 0.20 three pools fr_n = 0.04 0.86 0.10 the three pools
! The fractional allocation of carbon to each of the ! The fractional allocation of nitrogen to each of
In this example there is relatively less N than C in pool 1 so that this pool will have a wider C:N ratio than the whole manure. Because pool 1 is the fraction that decomposes fastest, there will be greater initial immobilization than if C:N ratio was the same in all three pools.
Modelling long-term multi-season dynamics

To date, modelling exercises have not been done to investigate whether distribution of C, N and P between the pools affects the effectiveness of manures as sources of nutrients for crops in the longerterm. Experimental data to explore such effects are also lacking.
Simulation of short-term effects suggest that the consequence of different allocation of C and N between the pools diminishes over time so that the longer-term effects can be expected to be dependent more on the overall C:N ratio than the C:N ratios of the different pools.
In modelling field studies of the response by crops to inputs of manure (Dimes and Revanuru 2004), the quality aspect has been limited to varying the distribution of OM between the three pools, with the C:N being the same in each pool.
Lower quality manures are assumed to have a greater proportion of C in FPOOL3 thereby releasing its nutrients more slowly. The values used to simulate the high (HQM) and low (LQM) quality manures were as shown in the Table.
Table. Values used by Dimes and Revanuru (2004) to simulate high and low quality manures.
Quality HQM
fract_C 0.16
cnr 22
Allocation to pools fr_c = 0.0 0.20 fr_n = 0.0 0.20
LQM
0.25
35
fr_c = 0.0 0.01 fr_n = 0.0 0.01
HQM - High Quality Manure LQM - Low Quality Manure
References
Dimes, J.P. and Revanuru, S. (2004). Evaluation of APSIM to simulate plant growth response to applications of organic and inorganic N and P on an Alfisol and Vertisol in India. In "Modelling Nutrient Management in Tropical Cropping Systems" (eds R.J. Delve and M.E. Probert) pp 118-125. ACIAR Proceedings No. 114. (ACIAR: Canberra). Probert, M.E., Delve, R.J., Kimani, S.K. and Dimes, J.P. (2005). Modelling nitrogen mineralization from manures: representing quality aspects by varying C:N ratios of sub-pools. Soil Biology & Biochemistry 37, 279-287.
How to use APSIM SWIM
Table of Contents
1. Introduction 1.1 What is APSIM SWIM? 1.2 How does SWIM operate within APSIM? 3. The effects of cover upon the water balance 3.1 Potential Soil Evaporation 3.2 Effective Rainfall Energy
2. Initialisation 2.1 The APSIM SWIM Parameter File 2.2 Configuration Section 2.3 Soil Type Description Sections 2.4 Solute Specific Information Section 2.5 APSIM SWIM Calculation Parameters 2.6 Climatic Inputs Section 2.7 Runoff Functions Section 2.8 Bottom Boundary Conditions Section 2.9 Top Boundary Conditions Section 2.10 Bypass Flow Section 2.11 Crop Parameters Section 2.12 Rainfall and Potential Evaporation Data 2.13 Irrigation Data
4. Water and Solute flows for bottom boundary conditions in SWIM 4.1 Specified matric potential gradient 4.2 User-Specified potential 4.3 Zero flux 4.4 Seepage with threshold suction 4.5 Responsive Water Table 4.6 Runtime alterations to the bottom boundary condition 5. Subsurface Flows 5.1 Subsurface Drains 6. APSIM SWIM Interface 6.1 Crop Interface to APSIM SWIM 6.2 Solute Interface to APSIM SWIM 6.3 APSIM SWIM module actions
Introduction
What is APSIM SWIM?

APSIM SWIM is the result of adapting SWIM Version 2.0 to communicate with APSIM. SWIM (Soil Water Infiltration and Movement) is a soil water and nutrient balance model written by P. J. Ross of C.S.I.R.O. Division of Land and Water. APSIM (Agricultural Production Systems Simulator) is a cropping systems modelling environment specially designed to allow a plug-in-pull-out approach for the integration of various simulation models. It is a product of the Agricultural Production Systems Research Unit (APSRU). APSIM SWIM is designed to run within APSIM and calculate all flows of water and nutrients through, in, and out, of soil for a given simulation. These flows include infiltration, runoff, plant uptakes, movement through soil, etc, and the related nutrient flows.
Back To Top
How does SWIM operate within APSIM?

To simultaneously solve the water flow equations SWIM increments its way through time using time steps small enough to allow the solution of its equations within given tolerance levels. APSIM uses a fixed time step, usually one day in duration. For these two approaches to exist together SWIM is forced to perform its equations for a time frame within the current APSIM time step. As APSIM cycles through all the active modules, allowing each to perform its own time step processes, SWIM will be allowed, during its own process step, to (including infiltration, runoff, drainage, and crop water uptake) and all solute flows (including solutes in infiltration, uptake of all solutes by all crops in the
system). Transformational flows of solutes, such as with nitrogen, will take place on a daily time step in the module that owns that variable, such as the soil nitrogen balance.
Back To Top
Initialisation APSIM SWIM uses the standard APSIM input file capabilities and structure. Please refer to the APSIM documentation for specifics on the formatting of APSIM input files.
Back To Top
The APSIM SWIM Parameter File

The structure of an APSIM SWIM data set is shown on the following page. There are a series of predefined sections containing related data. The structure shown here could be reproduced many times within one file as each data set lies within the one logical grouping of data sections.
Back To Top
Configuration Section
The main section of the APSIM SWIM parameter file(s) is the configuration section. Contained in this are all configuration switches, for specifying all SWIM sub-models, and descriptions of the soil profile required for model initialisation.
[sample.apswim.init] ! -------------------- initial layer information ---------------------!----------------------------------------------------------! 1 2 3 4 5 6 7 8 9 !----------------------------------------------------------x = 0.0 50.0 100.0 300.0 500.0 750.0 1000. 1600 2000 (mm) soil_type = soil1 - - - - - - - soil2 psi = -1500 -1500 -1500 -1500 -1500 -1000 -1000 -1000 -500 (cm) !----------------------------------------------------------slmin = -3.0 () slmax = 7.0 () ! slmin and slmax are the minimum and maximum ! log suction values used for specifying ! moisture characteristic and hydraulic ! conductivity curves in the soil descriptions bypass_flow =on (on/off) ! Bypass Flow - On/Off ! runoff = 2 () ! Runoff Flag - 0) No ponding (all runoff) ! ----------- 1) All ponded (no runoff) ! 2) Use runoff functions ! top_boundary_condition = 2 () ! Surface Flag - 0) infinite surface conductance ! ------------ 1) constant potential ! 2) conductance function ! bottom_boundary_condition = 0 () ! Bottom Flag - 0) constant gradient ! ----------- 1) water table ! 2) zero flux ! 3) free drainage (seepage) vapour_conductivity = off (on/off) ! Vapour Conductivity flag (0=off, 1=on) ! -----------------------run_solutes = br cl no3 ! List of solutes SWIM is required to move.
solute_exclusion = on (on/off) ! switch to specify if solute in soil water is ! taken in excess of the crop solute demand. extra_solute_supply = on (on/off) ! switch to specify if extra solute, above that ! received in the extracted soil water, is to taken ! up using a simple empirical method) echo_directives = on (on/off) ! choice to echo the receipt of directives such
! as irrigation or tillage.
The SWIM module contains many components and sub-models that can be specified to behave in different ways. Examples of this may be the equations for runoff or behaviour at the top and bottom soil boundaries. Switches for these are contained in the main model configuration section above and the in-line documentation in the example above explains the meaning of each one. When configuring APSIM SWIM one is required to specify all solutes to be redistributed within the APSIM simulation. To do this we specify, in this section, the names of all solutes that are to be moved (referred to above as run_solutes). APSIM SWIM will then find out the states of each of these pools and communicate with their owner modules. Some modules may potentially own solutes that will play no part within the simulation. The user is informed during initialisation, via the summary file, of any solutes owned by individual modules that are not included in the list of "run_solutes". The user can decide if any of these should also be added to the list of solutes to be parameterised and used by APSIM SWIM. The user can alternatively choose to have no "run_solutes" by setting the parameter to "none". The soil profile specification (at the beginning of the section - though order is not important) describes the nodal structure for the current simulation and the soil type at each of these nodes. Each soil type is referred to by a unique user-defined name. The user can also specify a gradual change in soil type from one node to another by not defining nodes between them. A single dash () is used for this purpose. The above example will linearly interpolate, according to depth, the soil for each node so that the soil properties will gradually change from soil type one at the surface to soil type two at the bottom boundary. The actual properties of each soil type are described in a soil specification section for each soil type. The name for each section is the same as the unique name given in the soil profile description above. The parameters extra_solute_supply and solute_exclusion allow the user to specify the response to situations where total uptake of solute does not match the solute demand of the crop. Extra solute can be excluded or taken up empirically, depending on the situation. This functionality is not part of the original SWIMV2 model but has been included to allow flexibility in responses to crop modules depending upon APSwim for uptake of solutes. The specification of these parameters is optional and default to off. The last parameter, echo_directives, is used to verify the communications between APSwim and other modules within APSIM. If this value is set to on, all tillage and application of surface water messages will be reported to the screen and to the simulation summary file.
Back To Top
Soil Type Description Sections

For SWIM to calculate all water and solute movements it needs to know certain soil-water and soilsolute relations. This information is given as follows:
! ---------------------soil type information ------------------------[sample.apswim.soil1] sl = -3.000000 0.400000 1.000000 1.386233 1.538325 4.355526 7.000000 () wc = 0.255000 0.254882 0.253123 0.243884 0.232800 0.078951 0.028610 (cc/cc) wcd = -0.000000 -0.000545 -0.008644 -0.051190 -0.089358 -0.030304 -0.010982 ()
hkl = -0.551294 -0.554319 -0.599416 -0.841595 -1.144555 -8.187840 -14.799289 () hkld = -0.000000 -0.013938 -0.222431 -1.367128 -2.500100 -2.500100 -2.500100 () bulk_density = 1.0 (g/cc) ! --------------------------solute_name = cl br no3 !--------------------------exco = 0 0 0 () fip = 1 1 1 () dis = 0 0 0 () !---------------------------
()
sl is log suction where suction has units of cm. For each value of sl there are corresponding values of volumetric water content (wc). These values define a series of points on the moisture characteristic curve for this soil type. SWIM uses these points to interpolate all values on this characteristic curve using piece-wise cubic approximations. To enable this we must also supply the slope of the moisture characteristic curve at each of these points as well (wcd). wcd is the derivative of the log suction vs water content curve at this point. A similar approach is used for the specification of the hydraulic conductivity curve. Here log hydraulic conductivity (hkl) (conductivity in units of cm/h) is supplied as well as the corresponding slope (hkld). These soil characteristic curves can be specified using the HYPROPS program. Solute-Soil interactions are specified for each solute in a separate table. For each solute SWIM requires:exco - freundlich exchange isotherm coefficient fip - freundlich exchange isotherm power term such that adsorbed concentration = exco xsolute_concfip dis - is the dispersivity of the solute in the soil. Bulk Density is to be expressed as g soil per cubic centimetre.
Back To Top
Solute Specific Information Section

There are some solute parameters required by SWIM that are not related to soil type but are only specific to a particular solute.
! ---------------------- solute information --------------------------[sample.apswim.solute] ! ---------------------------solute_name = cl br no3 ! ----------------------------
slupf = 0 0 1 slos = 0.001 0.001 0.001 d0 = 0 .072 0 a= 0 1 0 dthc = 0 0 0 dthp = 1 1 1 disp = 1 1 1 ground_water_conc = 0 0 0 (ppm) ! ----------------------------
slos is defined as the osmotic pressure per unit solute concentration. (NOTE: All solute concentrations are expressed as ppm. ie. g solute per g water) d0 is the diffusion coefficient. Tortuosity is calculated with SWIM as: a. (theta - dthc)dthp where theta is volumetric soil water content. Hydrodynamic dispersion is: dispersivity. |velocity|disp where dispersivity is the value of dis given for each soil type. Ground water concentrations are specified for use during simulation whenever the bottom boundary condition is set to allow water entry via the bottom of the profile.
Back To Top
APSIM SWIM Calculation Parameters
! ------------------ swim calculation parameters --------------------[sample.apswim.calc] dtmin = 0.0 (min) ! min time step dtmax = 1440. (min) ! max time step dtmax_sol = 60 (min) ! max time step during solute uptake max_water_increment=1. (mm) ! max water increment slcerr = 0.000001 () ! ersoil= 0.000001 () ! ernode= 0.000001 () ! errex = 0.01 () ! dppl = 2 dpnl = 1 swt = 0.0 () () () ! ! ! Space Weighting Factor (gravity flow)
! ------------------------------------! 0.5 -> 1.0 (central to fully upstream) ! < -1 (central diffs by factor of -1*SWF) slswt = 0.0 ()
The only point of note for this section that is not covered in the SWIMV2 documentation is the parameter dtmax_sol. This parameter was not part of the original SWIMV2 but works in tandem with the crop-solute interaction parameter, solute_exclusion (included in the init section). This maximum timestep specification determines the maximum timestep allowablewhen the solute_exclusion flag is set to true and there is a non-zero crop solute demand for the current APSwim timestep. Specifying a small maximum timestep forces APSwim to work slowly through time whilst solute demand is not satisfied, thus minimising the magnitude of any over-supply of solute as calculated via the flow of solute with soil water extraction. Once the supply of solute is met this extra constraint is removed and the normal maximum timestep (dtmax) is used. These two timestep constraints allow for differing levels of precision depending upon the processes taking place.
Back To Top
Climatic Inputs Section

At present there are three climatic inputs - soil albedo and the rainfall and potential evapotranspiration data sources. If the user specifies either source as "file" they will then need to provide a file name (see example below). If these files are to be found in a directory other than the current directory then a full file name including path will be required. The user can also direct apswim to get rainfall and evaporation information from other modules within APSIM, such as the input module, by simply typing in the name of the variable to use for that data (e.g. 'rain' or 'pan' from met module). The user can also direct apswim to calculate evaporation data from daily meteorological data. This is achieved by using the keyword calc for the evaporation data source.
! ------------------------ climatic inputs --------------------------[sample.climate] salb = 0.23 () rainfall_source = rain () ! use apsim variable called 'rain' evap_source = calc () ! calculate own potential evaporation rate
or
[sample.climate] salb = 0.23 () rainfall_source = file () ! get rainfall from a file rainfall_file = c:\work\myrain.dat evap_source = file () evap_file = c:\work\myevap.dat
Back To Top
Runoff Functions Section

As explained in the configuration section information earlier the runoff sub-model can be configured as follows:-
runoff
=2
() ! Runoff Flag - 0) No ponding (all runoff) ! --- 1) All ponded (no runoff) ! 2) Use runoff functions
If the user chooses option number two then runoff functions are to be used for the calculation of runoff. In this case, extra information needs to be supplied to APSIM SWIM and this is to be placed in the runoff section.
! ------------------------ runoff functions -------------------------[sample.apswim.runoff] maximum_surface_storage = 20 ! (mm) minimum_surface_storage = 10 ! (mm) initial_surface_storage = 15 ! (mm) precipitation_constant = 50 ! (mm) runoff_rate_factor = .2 ! (mm/h)/mm^P runoff_rate_power = 2 ! =P ______/
Runoff occurs when the surface water depth is greater than the surface storage. For a water depth that is dH above the storage, the runoff rate is equal to
Runoff Rate = Runoff Rate Factor . dHP
To allow for a reduction of surface roughness due to rainfall, the storage decreases exponentially with precipitation energy from the given initial value towards the given minimum. The equation for the exponential decrease in storage is of the form
S = Smin + (Sinitial - Smin).exp(-E/Espc) where E is cumulative rainfall energy and Espc is energy in an amount of rain equal to the given storage precipitation constant falling at 25mm/h. The user can specify the initial surface storage available to rainfall as any value between the maximum and minimum surface storages.
Back To Top
Bottom Boundary Conditions Section

There is only one parameter required for one of the possible settings for bottom boundary conditions. If the user chooses to set a constant gradient for the bottom boundary then it is input as follows.
! ------------------- bottom boundary conditions -------------------[sample.bottom_boundary] constant_gradient = 0 or constant_potential = 0
If the user chooses zero flux then no inputs are required from this section. If a the bottom boundary is to be a user defined potential (eg water table is said to exist at the bottom boundary) then constant potential will need to be supplied in this section. If the user wishes to enforce a constant gradient at the base of the profile then this parameter needs to be specified. If the user specifies free drainage at the bottom boundary then a value for a constant potential is required to describe the flow at the bottom of the profile.
Back To Top
Top Boundary Conditions Section

The soil may have a thin surface layer that impedes water entry. The water flux through this layer is equal to the surface conductance multiplied by the matric potential difference across this layer. A soil layer of thickness dx and saturated hydraulic conductivity Ks would represent a conductance of Ks/dx at saturation. To allow for a reduction of surface conductance due to formation of a crust caused by rainfall, the conductance decreases exponentially with cumulative precipitation energy from the given initial value towards the given minimum.
! --------------------- top boundary conditions --------------------[sample.apswim.top_boundary] maximum_conductance = 4.0 (/h) ! initial soil surface conductance minimum_conductance = .02 (/h) ! minimum soil surface conductance initial_conductance = 1.0 (/h) ! initial soil surface conductance precipitation_constant = 2.5 (mm) ! used to define rate of surface sealing
The equation for the exponential decrease in conductance is of the form
G = Gmin + (Ginitial - Gmin).exp(-E/Ecpc)
where E is cumulative rainfall energy and Ecpc is energy in an amount of rain equal to the given conductance precipitation constant falling at 25mm/h.
Back To Top
Bypass Flow Section
If bypass flow has been enabled, within the initialisation section, the following parameters need to be specified.
! -------------------------- bypass flow --------------------------[sample.apswim.bypass_flow]
depth =4 conductance = .10 storage = .10
! (node number) ! (/h) ! (cm water/cm of +ve Psi)
Depth is, of course, the macropore depth within the soil profile. It is expressed in terms of node number.
Back To Top
Crop Parameters Section
[sample.apswim.crop] ! -----------------------------------------------------crop_name = wheat barley maize ! -----------------------------------------------------min_xylem_potential = -15000. -15000. -15000. (cm) root_radius = 0.25 0.25 0.25 (mm) root_conductance = .4d-7 1.4d-7 1.4d-7 (cm3/h) ! -------------------------------------------------------
At present the only crop specifications required from the user are the minimum xylem potential, root radius and root conductance for particular crops. Other day-to-day values such as soil water demands and root distribution are provided by APSIM during the simulation run.
Back To Top
Rainfall and Potential Evaporation Data
As chosen by the user(see climate data specification section above), APSwim allows two methods of supplying specified rainfall and potential evaporation data. The first method utilises the APSIM inter-module communications. In this simple approach, the data for rainfall or evaporation is described as one homogeneous event. An amount, a starting time and a duration or intensity is obtained via a general request of all modules for this information just prior to processing the timestep calculations. This information is generally described in the APSIM weather file as follows. The values returned to APSwim have been highlighted. In this example rainfall will always fall at an intensity of 15 mm/h starting at 3:00 p.m. and 5 mm of potential evaporation is said
to lie between 6:00 a.m. and 6:00 p.m. each day. Alteratively the rainfall could be said to alway fall between 3:00 p.m. and 4:00 p.m. by using the alternative suggested below.
[user-defined..nput.weather] site = Gatton latitude = -27.0 (degrees)
rain_time = 15:00 (hh:mm) rain_int = 15.0 (mm/h)
(or rain_durn = 60 (min))
eo = 5 (mm) eo_durn = 720 (min) eo_time = 6:00 (hh:mm) year day radn maxt mint rain () () (MJ) (oC) (oC) (mm) 1995 1 20.0 25.0 15.0 5 1995 2 20.0 25.0 15.0 0 1995 3 20.0 25.0 15.0 10 1995 4 20.0 25.0 15.0 0
The second method uses a simple data log file. At the present stage of development APSIM SWIM uses a fixed format input file structure for rainfall and potential evaporation data. Later releases will contain more flexible and more powerful mechanisms for the input of this data. The input format for rainfall is as follows:-
1991 121 00:00 5. 6 1991 122 00:00 20. 120 1991 122 2:00 10. 600 1991 129 14:00 25. 600
The columns, from left to right, contain year (4 digit specification), day of year, time (24 hour notation), amount of rainfall, and the time duration* for this record. For example the first line records an event at 12:00 am on the 121st day of 1991 in which 5 mm fell in 6 minutes. The last line records an event in which 25 mm fell at 2:00pm on 129th day of 1991 and lasted for 10 hours. Evaporation data follow the exact same format. * Time duration has highest resolution of 1 min.
Back To Top
Irrigation Data
There are two ways of accessing the one mechanism for application of irrigation. APSIM SWIM responds to a low level add_water message. The format of this is:-
apswim add_water amount=20(mm), time=12:00(hh:mm), duration=60 (min), intensity = 20 (mm/h), no3=10.0(kg/ha) (Note: implementation would require text on a single line)
This message tells SWIM that 20 mm of irrgation is to be added at midday today. The irrigation takes 60 minutes to complete and ten kg/ha of nitrate was in that irrigation water. SWIM will then incorporate all this information into its cumulative water and solute addition with time curves. Any combination of amount, duration and intensity information will suffice as long as an overall amount and duration can be calculated from the information given. The APSIM systems manager or operations manager modules will allow the user to set up various irrigation schedules using this message format. However, the APSIM system also contains an irrigation module that has added features such as automatic irrigation rules and tabular input format. It is highly recommended that users apply irrigation using the IRRIGATE module. This module will convert the irrigation information into the necessary format for APSIM SWIM. See documentation of these modules for further assistance.
Back To Top The effects of cover upon the water balance
Potential Soil Evaporation

The algorithm for cover effects on potential soil water evaporation is taken from that derived for the soilwat2 module.
Where Ep is total potential evapotransipiration Canopy_coeff is a coefficient for the effect of canopy cover on potential soil water evaporation Residue_coeff is a coefficient for the effect of residue cover on potential soil water evaporation
Back To Top
Effective Rainfall Energy

Surface residues are said to protect the soil from rainfall energy by shielding the soil surface from rainfall impact according to the level of residue cover.
Where rKE is a measure of the energy in an amount of precipitation if intensity I compared with that of the same amount of precipitation of intensity Ir. Eff is an efficiency parameter Coverresidue is a 0 to 1 measure of surface residue cover.
Back To Top Water and Solute flows for bottom boundary conditions in SWIM The following describes the flow of water and solutes across the bottom boundary for the four boundary conditions supported by the SWIM model. The relevant flow equations are as follows
Richards' Equation
- See equation 4 in Swimv2.1 manual or
Advection-dispersion equation
- See equation 50 in Swimv2.1 manual or
See the SWIMv2.1 User manual for more information and definitions of terms. We shall now look how the elements of the flow equations above are calculated for the four different bottom boundary conditions.
Back To Top
Specified matric potential gradient

Water Flow The flow equations for water in the profile are solved with the matric potential gradient term, shown in the Richards equation above, set to the user specified value at the lowest node in the profile. The actual value of the matric potential () may vary in time but that same gradient will apply until it is changed by the user. If the matric potential gradient is set to zero then drainage will proceed simply due to gravity (z/x which is usually 1). This is often referred to as a unit (hydraulic) gradient. Flow can only proceed downward, at the rate of the hydraulic conductivity. If the matric potential gradient is set to -gravity (ie -1) the net results is one of zero flux. If matric gradient is negative (and greater than gravity,ie <-1) then water will pushed up into the profile. Note that, unless the user changes the gradient, the bottom boundary potential will continue to rise indefinitely until ultimately upward flow was offset by runoff! If matric gradient is positive then water will be drawn down out of the profile. Once again, unless the user alters the gradient, the potential of the lowest node will move toward extremely dry conditions. Solute Flow The solute flux calculations for the deepest soil node differ slightly to that for the rest of the profile. As knowledge of space effectively ceases past this node, swim makes no assumptions regarding diffusion or dispersion. As can be seen in the equations above, dispersion calculations would require some assumptions regarding the spatial gradient of solute concentration. As a result, only convection is calculated for the bottom boundary. The solute concentration in the water flowing across the bottom boundary in either direction is dependant on the direction of water flow. Thus:
If the water flow is downward, solutes will progress down across the deepest node. Once solute has passed the node it cannot return to the profile. Bulges may move across this node, but as we calculate convection only for this node the concentration gradient, or shape of the bulge, is not considered at this node. If the water flow is upward then it is assumed that the solute concentration in the water entering the profile is the same as the specified ground water concentration. This will act as a supply of solute into the profile in the same manner as the user-specified potential boundary condition below.
Back To Top
User-Specified potential
Water Flow The flow equations for water are solved with the potential (hydraulic head = sum of matric and gravity components) specified within the solution. This matric potential is specified by the user in the input file for SWIMv2.1. In APSIM SWIM the potential is set initially and can be manipulated at runtime via the APSIM manager. The potential gradient above this node will fluctuate through time due to the influence of this fixed potential and the nodes above. This boundary condition is often used for the simulation of the entry of water tables into the section of the soil profile being modelled.
If the potential is zero or positive then there is effectively a water table entering the base of the profile. The magnitude of the potential would represent the height of water above the lowest node. Increasing this potential does not instantly 'flood' the soil to this height. It may take some time, depending upon the soil properties, for the upward flow to achieve this and for the soil to equilibrate. Similarly, it may take some time for drainage if there is any decrease in the specified potential. Note that drainage will still occur during the presence of the water table. Any infiltration that may tend to increase the height of the water table will cause a subsequent drainage such that the specified water table height is maintained. The flows of water across the bottom boundary for a negative boundary condition are similar to the case above. This boundary condition may perhaps be used for situations where a water table is known to drop a little below the specified profile, provided the conductivity is not too low.
Solute Flow
In situations where the bottom boundary potential is maintained it is assumed that the solute concentration of the water at that boundary is also maintainedIf the potential is zero or positive then the solute concentration of the deepest node is maintained at a constant concentration. In APSIM SWIM this concentration is the concentration of solutes in ground water. In SWIMv2.1 the concentration is held at the value, csl(n), specified by the user in the input file. This represents the fact that the ground water has entered the profile. It is assumed that the solute concentration within the ground water is spatially homogeneous. Any water that enters the profile from the ground water will contain solutes at this given concentration. The solute concentration within water draining out of the profile will be determined via the normal solute flux calculations. Note that if the bottom boundary is changed to such a condition there will be a sudden change to the solute balance as solute is removed or added (over the time step) to the deepest node as the new concentration is applied. If the potential is negative the solute concentration is held constant as described above. In this case though, the user will have to decide on the possible implications of the behavior of the solute balance at this base node.
Back To Top
Zero flux
There is no flux of water or solute across the bottom boundary when using this boundary condition. The flow equations are solved with the flux term at the base of the profile set to zero. The matric potential and potential gradients will fluctuate due to the influence of higher nodes. Water may pond above this boundary. Solutes will move in response to the water flows and concentration gradients. No special conditions need to be considered by the user.
Back To Top
Seepage with threshold suction

The seepage boundary condition acts as a combination of the zero flux and constant potential boundary conditions. This condition is useful for simulating the operation of some field and laboratory apparatus or the effective functioning of particular boundary interfaces (e.g. drainage into gravel). Water Flow If the potential at the deepest node is below a critical value specified by the user then the water balance calculations are identical to the zero flux bottom boundary condition. No flux will occur out of the profile until the potential at the deepest node has reached the user-defined value. When the potential does reach the user-defined value the boundary condition changes to follow the behaviour of the "user-specified potential" condition. The flow equations are solved with the potential of the deepest node set to the specified value. No upward flux can occur. If the specified potential is zero or positive then drainage will not occur until the water table within the profile reaches the described height. This condition can be used to simulate apparatus where water tables can build up to a maximum height. If the specified potential is negative then water is removed from the profile until the deepest node equilibrates with the applied suction. This can be used to simulate core experiments where the base of the profile has an applied suction. Solute Flow Solute flows across the bottom boundary follow those for water. As implied by the nature of the boundary condition, there can be no dispersion for flux of solutes out of the profile (the profile is discontinuous at this point). Fluxes out of the profile, therefore, are calculated using convection only. If the specified potential is zero or positive solute will accumulate at the base of the profile as is the case for the accumulation of the perched water table. When drainage does occur, the solute concentration of the drainage water will equal that of the water at the deepest node. If the specified potential is negative then solute will be extracted with the soil water until the soil equilibrates. The absence of the dispersion term will lead to the extraction of water from the profile being 100% efficient at removing the solute in that water. Once again, the concentration of solute in drainage water will equal that of the water at the deepest node. Back To Top
Responsive Water Table

The responsive water table condition acts like a water table with a user-specified level of "responsiveness", where responsiveness refers to the time required for the water table depth to equilibrate with the piezometric pressure. This condition is useful for simulating the situations where local management might temporarily alter the effective water table depth. For example, irrigation might temporarily raise a water table or plant water use might lower a water table from that which would correspond to the ground water pressure. Water Flow
Water flow (in or out) is calculated based upon the difference between the piezometric pressure and the actual pressure at the base of the profile. If the pressure is above the ground water pressure, water will flow out of the profile. If the pressure is below the ground water pressure, water will flow into the profile. The rate of water flow is calculated as follows:
q = (W - (-X)) x gw
where q is flow at the base of the profile, W is the depth to ground water, is pressure head at the bottom of the profile, X is the depth to the bottom of the profile and gw is a ground water table "conductance". gw has units of per hour. Therefore, a value of 1 would provide an flow of 1 cm per hour for every cm of pressure difference at the base of the profile. This same calculation is used to provide flows of water into or out of the profile. The sign of the pressure difference term will dictate the direction of flow. Solute Flow Solute flows across the bottom boundary follow those for water. As implied by the nature of the boundary condition, there can be no dispersion for flux of solutes out of the profile (the profile is discontinuous at this point). Fluxes out of the profile, therefore, are calculated using convection only.
In situations where a water table is maintained it is assumed that the solute concentration of the water at the bottom of the profile is also maintained at a constant concentration. In APSIM SWIM this concentration is the concentration of solutes in ground water. It is assumed that the solute concentration within the ground water is spatially homogeneous. Any water that enters the profile from the ground water will contain solutes at this given concentration. The solute concentration within water draining out of the profile will be determined via the normal solute flux calculations (convection only).
Back To Top
Runtime alterations to the bottom boundary condition

The user can change the bottom boundary condition and/or value at runtime via the setting of the state of the bottom boundary condition at any time via the messaging system. The following manager code will change the bottom boundary to a water table for five days before reverting to a constant gradient at the end of this period.
If day = 1 then Apswim.bbc_potential = 50 Elseif day = 6 then Apswim.bbc_gradient = 0 Endif
In this example days 1 to 5 will have a water table 50 cm above the bottom of the soil profile. Day 6 will be the start of a gradual drainage event out of this state. Currently, these are the only two boundary condition state changes supported for alteration at runtime. Back To Top
Subsurface Flows
Subsurface Drains
The flux of water and solutes into subsurface tile drains can be calculated using a formulation of the Hooghoudt equation as utilised in the DrainMod model. The basic geometry of the system is as follows:
The flow into the drain (q) is calculated q = (8.0 Ke de m + 4Ke m2)/L2 where Ke is the effective lateral conductivity of the soil profile, m is the height of the water table above the drains, d is the height of the drains above the impermeable soil horizon, L is the drain spacing, r is the drain radius and de is the effective depth of impermeable soil horizon which takes into effect the convergence near to the drains. de is calculated as: de = L*/(8 log (L/r) - 1.15) , where d/L >= 0.3
de = d/(1.0+d/L*(8 log (d/r) - )), where d/L < 0.3, = 3.55 - 1.6(d/L) + 2(d/L)2 The user specifies the system via input parameters for the various aspects of the geometry as follows: [sample.apswim.drain] drain_depth = 1000. (mm) drain_spacing = 30000 (mm) drain_radius = 50 (mm) Klat = 1000. (mm/d) imperm_depth = 3000. Back To Top
! depth of the drain below the soil surface ! distance between subsurface drains ! radius of each tile drain ! lateral conductivity ! depth of the impermeable soil profile below the soil surface
APSIM SWIM Interface
Crop Interface to APSIM SWIM

All uptake of water and/or solutes by crops is handled by SWIM. The uptake of these substances in built into the SWIM flow equations. Competition between crops for resources such as water and solute is intrinsic to the solution of the flow equations and APSIM takes full advantage of this. Competition of other resources such as light must be allowed for in another module. Such modules are currently available within APSIM. The crop module must also have been created from a template that allows for uptake calculation external to the module. To enable SWIM to calculate crop uptakes each crop must be able to provide
Name crop_type sw_demand nnnn_demand cover_tot rlv
Units -
Description name of crop type eg. wheat (not module name) mm potential plant transpiration kg/ha crop solute demand (where nnnn is the solute name) 0-1 fraction total crop cover mm/mm3 root length volume (on a layer basis)
With this information SWIM will calculate the uptake of water and all solutes for each crop. These are available to the crop using the uptake_nnnn_cccc variable as described in the output section. To be able to provide information such as potential plant transpiration for the current APSIM time step the crops will need to calculate these values in preparation for the time step (the PREPARE stage). Also, SWIM will have to be included in the module list ahead of any crop or solute modules to allow SWIM to calculate ALL flows before the owner modules perform their daily time step. Back To Top
Solute Interface to APSIM SWIM

The interface between solute owner modules and APSIM SWIM is very simple. The APSIM SWIM parameter file must contain the names of all solutes the user is wanting SWIM to move for the current simulation. APSIM SWIM will then ask all modules for the states of these pools, as does any other module requiring that information, and will receive that information via the standard message passing system in APSIM. Only the amount of solute in each layer (kg/ha) is required. All movement parameters are included in the APSIM SWIM parameter file. APSIM SWIM will notify the user if it has been parameterised to move solutes that do not exist within the simulation, or if solutes exist for which it is not parameterised. To receive back updated values of solute, after solute flows are accounted for by SWIM, the solute owner module needs to be able to respond to the standard SET message. This should also already be implemented in the solute owner module. The solute module does not need to provide any solute flow information. As is shown, almost no effort is required to couple a solute module to APSIM SWIM.
NOTE: For those interested in the flow of simple solute tracers, without solute transformations, there is a simple solute module within APSIM that will allow the addition of any solute into the APSIM modelling system. Back To Top
APSIM SWIM module actions

Reset The reset action can be invoked to reset the module to the state specified within the module's input data, which includes the soil moisture characteristics, runoff and boundary condition parameters and the initial soil water profile. The Reset action is identical to the initialise action used by the simulation engine at the start of the simulation except that a description of the reinitialised state is not printed in the simulation summary file. APSIM Manager Example: [sample.manager.start_of_day] ! reinitialise apsim swim at the beginning of each sowing window
If day = 100 then apswim reset endif
Initialise
The initialise action has now been replaced by the reset action (see above).
Summary Report At initialisation, at series of tables and useful information is printed to the simulation summary file for perusal by the user. These tables can be printed to the summary file at any point during the simulation as a detailed record of the system state at a particular time.
APSIM Manager Example:
[sample.manager.start_of_day]
! Print out a summary of module state to the summary file
If day = 100 then apswim sum_report endif
Back To Top
Description
This module provides a simple link between apsim and TCL interpreters. Variables are exchanged through a Get/Set mechanism.
Settings
Rules are defined just like the manager: the rules in [xyz.tcllink.init] will be evaluated at the simulation's initialisation. The other rules of interest are init, prepare, start_of_day, process, post, end_of_day, and "exit".
Apsim messages are generated with the TCL procedure apsimSendMessage. It has two mandatory arguments, the destination module, the message name, and optional message name/value pairs are encoded as list elements. For example,
apsimSendMessage wheat sow {cultivar hartog} {plants 120} {sowing_depth 30}
Apsim variables are set/get with apsimGet, apsimSet. The procedure apsimWriteToSummaryFile sends a log message to the current summary file
Command Line Debugger

A simple command line debugger is provided in the sample directory. It demonstrates the ability to examine apsim variables, step through simulations and set breakpoints.
nb. In the following samples, 1. On the first line, the "(Sample) # %" (where # is just a number) part is just the command prompt. It is what comes after that is important. It is the command. 2. Also the next line underneath (if it exists) is the result or output(or the echo) of doing the command above. 3. The final line (if it exists) is an explanation of the result or output(or echo).
(Sample) 1 % link clock.day day Link the apsim variable clock.day to the tcl variable day.
(Sample) 2 % b {$day == 182} {$day == 182} Set a breakpoint for day 182. Equivalent to b {[apsimGet clock.day] == 182}
(Sample) 3 % c -1 Continue. Control returns after a crop is planted
(Sample) 4 % p wheat.biomass 12.874 Print an apsim variable
(Sample) 5 % s 1 Single step
(Sample) 6 % p wheat.biomass 14.095 etc..
(Sample) 7 %
Missing features
Cannot uncrack messageData structures (eg newmet)
What is the Data Tracker Module?

The tracker module allows the user to track information through a simulation and perform simple statistics to that data prior to recording it in an APSIM output file. For example, tracker can record and accumulate flows of matter (e.g. rainfall, irrigation, drainage, fertiliser) between simulation outputs.
2 Definition of statistical types

Statistics can be provided on either events or the states of variables within simulation execution. In both cases, the statistic can be based upon a single spot sample at some defined point or it can be based upon an accumulated sample of values for a defined timeframe within model execution. In all cases the statistical variable is defined in the parameter file via a specification of the form, variable = specification where specification is a description of the statistic via a predefined grammar.
2.1 Event Statistics

2.1.1 Spot Sample Variable = Statistic of Event as Alias
where: Statistic : is the type of statistic to be applied. Currently the only option here is date. Event : is the event on which the statistic is to be applied. This can be any event within the APSIM simulation. Alias : is the tracker output variable alias to be applied to this statistic. This is the name by which other modules can access the value of this statistic. Sample 1 Report the sowing date of the last wheat crop
variable = date of wheat.sowing as wheat_sowing_date
Sample 2 Report the harvesting date of the last wheat crop

variable = date of wheat.harvesting as wheat_harvest_date
2.1.2 Accumulated Samples Variable = Statistic of Event from Start_event to End_event as Alias
where Statistic : is the type of statistic to be applied. Currently the only option here is count. Event : is the event on which the statistic is to be applied. This can be any event within the APSIM simulation. Start_event : is the APSIM event which signals the start of the sampling window. End_event : is the APSIM event which signals the start of the sampling window. Alias : is the tracker output variable alias to be applied to this statistic. This is the name by which other modules can access the value of this statistic. Sample 1 Count the number of lucerne cuts since the last report to the output file.
variable = count of lucerne.harvesting from reported to now as number_of_cuts
Sample 2 Count the number of days since chickpea was last sown
variable = count of tick from chickpea.sowing to now as days_since_chickpea_sowing
2.2 State Variable Statistics

2.2.1 Spot Sample Variable = Statistic of Variable on Event as Alias
where Statistic : is the type of statistic to be applied. Currently the only option for the user is value. Variable : is the APSIM state variable upon which statistics are calculated. This can be any variable within the APSIM simulation. Event : is the event on which the statistic is to be applied. This can be any event within the APSIM simulation. Alias : is the tracker output variable alias to be applied to this statistic. This is the name by which other modules can access the value of this statistic. Sample 1 Report the yield of the last wheat crop
variable = value of wheat.yield on wheat.harvesting as wheat_yield
Sample 2 Report the total soil water at the sowing of the last wheat crop
variable = value of sw_dep() on wheat.sowing as wheat_sowing_sw
2.2.2 Accumulated Samples
Variable = Statistic of Variable on [ last nnn ] Event [from Start_event to End_event] as Alias where Statistic : is the type of statistic to be applied. Currently the user can choose from sum, average, maximum and minimum. Variable : is the APSIM state variable upon which statistics are calculated. This can be any variable within the APSIM simulation. last nnn : is an optional specification to allow the user to specify a moving sample set. Event : is the event on which the statistic is to be applied. This can be any event within the APSIM simulation. Start_event : is the APSIM event which signals the start of the sampling window. End_event : is the APSIM event which signals the start of the sampling window. Alias : is the tracker output variable alias to be applied to this statistic. This is the name by which other modules can access the value of this statistic. Note: the from start_event to end_event" is optional only if the last nnn is specified. Sample 1 Report the accumulated rainfall since the last report to the output file
variable = sum of rain on start_of_day from reported to now as rainfall
Sample 2 Report the accumulated rainfall for the last 3 days

variable = sum of rain on last 3 start_of_day as rain3
Sample 3 Report the accumulated lucerne harvest since the last report to the output file
variable = sum of lucerne.biomass on lucerne.harvesting from reported to now as cut_biomass
Sample 4 Report the in-crop rainfall for the last wheat crop
variable = sum of met.rain on met.newmet from wheat.sowing to wheat.harvesting as wheat_incrop_rain
Sample 5 Report the 7 day moving average of the wheat crop water stress factor
variable = average of wheat.swdef_photo on last 7 end_of_day from wheat.sowing to wheat.harvesting as wheat_weekly_stress
Linking APSIM and VENSIM using the Venlink module

Patrick Smith and Dean Holzworth
Overview
The ability to integrate diverse modules through the so-called plug-in-pull-out approach is one of APSIM's key strengths. This guide describes an enhancement of this functionality through the
linkage of APSIM with VENSIM, an off the shelf' modelling package produced by Ventana Systems Inc. Enabling APSIM to call and execute VENSIM models allows researchers to quickly and easily develop new modules for APSIM, making full use of the functionality and intuitive icon-based interface of VENSIM. New VENSIM based modules fully interact with the APSIM Manager in the same manner as existing modules, but may be developed by the user without the need for significant interaction with the APSIM software engineers.
Procedure for producing a VENSIM-based module

To produce a new VENSIM-based module for APSIM the following three steps are recommended: 1. Construct and test a fully functional stand-alone model in VENSIM 2. Convert the shared' variables within the VENSIM model to APSIM settable' types 3. Add the necessary sections and commands to the APSIM files.
Step 1. Construct and test a fully functional stand-alone model in VENSIM

VENSIM is quite intuitive to use and previous users of icon-type modelling software should have little difficulty getting up to speed with it. New users are recommended to do the tutorials provided under VENSIM Help. As you design and build your model distinguish between two types of variables those variables that will be used exclusively within the VENSIM module, and those variable that will be passed from VENSIM to APSIM and vice versa. It may be helpful to visually identify the latter shared variables in your VENSIM model diagram by using a special font, colour or outline. Before attempting to link a VENSIM model to APSIM it is important to ensure that the model is working properly in isolation. This means that all variables that eventually will be shared between the programs will initially need to have values allocated within VENSIM. For constants this is simply a matter of specifying a value in the VENSIM equation editor. For variables that require sequential data it may be useful to dynamically link VENSIM to a spreadsheet using the GET XLS DATA or GET 123 DATA functions in VENSIM. Doing a dummy APSIM run may be a convenient way to generate the data you need to test your VENSIM model, and in many cases it may be the same data that is eventually passed to VENSIM by APSIM (e.g. daily rainfall, soil moisture or crop biomass). The only rule that must be followed when constructing your VENSIM model is that: The initial value of all levels' (= stocks' or state variables') in VENSIM must be set indirectly by means of a constant linked to the level with a connecting arrow. This is because APSIM cannot set VENSIM levels directly. In addition to the rule concerning levels, the following naming convention is encouraged: Names of variables in VENSIM models should be as descriptive as possible to assist other users and to help self document' the model. Spaces are permitted in VENSIM and these will be automatically converted within APSIM to underscores (eg. initial htt in VENSIM will become initial_htt in APSIM..
Step 2. Convert the shared' variables within the VENSIM model to APSIM settable' types
Having established that your VENSIM model is working properly it is a simple matter to enable communication with APSIM. Variables that need to be set by APSIM during the course of a run should be converted to one of two variable types:
1. Variables that require only the initial value to be set by APSIM (namely constants, including those that specify the initial values of levels (as described in Step 1)) should be set to Constant and Normal under the variable type selectors in the equation editor 2. Variables that are required to be set by APSIM on a daily basis should be set to Auxiliary and Gaming under the variable type selectors in the equation editor. Note that variables owned exclusively by VENSIM do not need to be changed from Auxiliary/Normal or Constant/Normal types. Such variables can still be retrieved by APSIM for calculations and reporting.
Step 3. Add necessary sections to the APSIM files

Control / Parameter file instructions To call and execute a VENSIM module within APSIM various commands need to be added to the APSIM .par', .man', .ini' and .con' files. The manager logic in the .par' or .man' file should specify the VENSIM model file ( .vmf) and the vensim variables that APSIM will get or set during the simulation.
[all.venlink.parameters] model_filename = HTTcalculator.vmf variable = st1 variable = sw1 variable = daily htt variable = sum htt
Also, any variables that APSIM needs to set on a daily basis should be mapped as in the following example:
[venlink.manager.start_of_day] venlink.st1 = st(1) venlink.sw1 = sw(1)
An .ini' file should list all VENSIM constants that need to be set by APSIM as in the following example:
[standard.venlink.constants] initial_sum_htt = 0 soil_moisture_threshold = -0.9 ll15 = 0.5
soil_temp_threshold = 20
The control file should invoke the Venlink module and point to the appropriate sections in the .par/.man and .ini files described above, e.g.
Module = venlink venlink.par [all] venlink.ini [standard]
User interface instructions Firstly you need to drag and drop a VenLink component from the standard toolbox and drop it on your paddock. Next you need to specify the model file name and the VENSIM variable names that you want to access from APSIM. This can be done by clicking on VenLink and editing the parameters on the right hand side. Next you need to give the VENSIM "constants" an initial value. Click on the ini node under VenLink and browse to a .ini file. The contents of the .ini file should look something like the following example:
[standard.venlink.constants] initial_sum_htt = 0 soil_moisture_threshold = -0.9 ll15 = 0.5 soil_temp_threshold = 20
Finally, VENSIM variables that need to be set every day must be done through a logic component. After dropping a Logic component from the standard toolbox onto your paddock enter script in the "Start_of_day" tab that looks like this example:
venlink.st1 = st(1) venlink.sw1 = sw(1)
The APSIM Vine Module

CropType = vine
Population
Value = 14
Arbitrator
DMSink = Reserve
Phenology
ThermalTime
Temperature (oC) 7, 22, 30, 35 ThermalTime 0.0, 15.0, 15.0, 0.0
Dormant
Dormant extends from StartDormancy to EndDormancy with a Chilling Days Target of 30 days.
Budding
Budding extends from EndDormancy to BudBurst with a fixed thermal time duration of 200 degree.days.
ShootGrowth
ShootGrowth extends from BudBurst to Flowering with a fixed thermal time duration of 442 degree.days.
FlowerDevelopment
FlowerDevelopment extends from Flowering to Set with a fixed thermal time duration of 150 degree.days.
BerryDevelopment
BerryDevelopment extends from Set to Veraison with a fixed thermal time duration of 600 degree.days.
Ripening
Ripening extends from Veraison to Ripe with a fixed thermal time duration of 510 degree.days.
Senescent
Start = Ripe End = LeafFall
Rewind
Start = LeafFall End = Unused
Leaf
InitialiseStage = BudBurst Frgr = 1 PrimaryBudNo = 1 MaxCover = 0.5
ExtinctionCoeff
Value = 0.5 KDead = 0.5 InitialLeafPrimordia = 1 InitialAreas = 1000 InitialAges = 1
Height
Stem.LiveWt 0, 500 Height 1800.0, 1800.0
FrostFraction 0, 0.0, 2, 0.0
Photosynthesis
FT 5, 0.0, 20, 1.0, 30, 1.0, 45, 0.0 FVPD 0, 1.0, 10, 1.0, 50, 1.0 RUE = 0.8
ThermalTime
Temperature (oC) 7 0.0 22 15.0 30 15.0 35 0.0
ThermalTime 0.0, 15.0, 15.0, 0.0
NodeInitiationRate
The value of NodeInitiationRate during the period from BudBurst to Veraison is calculated as follows: Function Value = 30.0 MaxNodeNo = 24
NodeAppearanceRate
The value of NodeAppearanceRate during the period from BudBurst to Veraison is calculated as follows: Function Value = 30.0
MaxArea
Leaf.NodeNo 1, 4, 30 MaxArea 5000.0, 15000.0, 10000.0
SpecificLeafArea
Leaf.NodeNo 1, 30 SpecificLeafArea 20000.0, 19000.0
GrowthDuration
Leaf.NodeNo 4, 5 GrowthDuration 150.0, 150.0
LagDuration
Leaf.NodeNo 5, 20 LagDuration 1500.0, 2500.0
SenescenceDuration
Leaf.NodeNo 5, 30 SenescenceDuration 500.0, 500.0
BranchingRate
Leaf.NodeNo 5, 10, 11 BranchingRate 0.0, 0.0, 0.0
PartitionFraction
===Early=== The value of Early during the period from BudBurst to Veraison is calculated as follows: Function Value = 0.4
ExpansionStress
WaterSupplyDemandRatio 0.0, 1.0 ExpansionStress 1, 1
Stem
Early
The value of Early during the period from BudBurst to Veraison is calculated as follows: Function Value = 0.4
StructuralFraction
===PreFlowering=== The value of PreFlowering during the period from BudBurst to Flowering is calculated as follows: Function Value = 1.0
PostFlowering
The value of PostFlowering during the period from Flowering to Veraison is calculated as follows: Function Value = 1.0
Root
ll = 0.29 0.29 0.29 0.29 0.3 0.31 0.32 0.33 0.34 0.35 0.36 kl = 0.07 0.07 0.07 0.07 0.05 0.05 0.04 0.04 0.04 0.04 0.04 xf = 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 KLModifier Value = 1.0 InitialDM = 0.01 SpecificRootLength = 105000 RootFrontVelocity Value = 10.0 PartitionFraction Value = 0.2 TemperatureEffect
Temperature (oC) 0 26 35 TemperatureEffect 0.0, 1.0, 0.0
Berry
MaximumSize = 0.33 RipeStage = Ripe NumberFunction
Stem.LiveWt 0, 1000 NumberFunction 0, 150000
FillingRate
EarlyBerryGrowth The value of EarlyBerryGrowth during the period from Flowering to Veraison is calculated as follows: Function
Temperature (oC) 7, 22, 30, 35 EarlyBerryGrowth 0.0, 0.00133, 0.00133, 0.0 LateBerryGrowth The value of LateBerryGrowth during the period from Veraison to Ripe is calculated as follows: Function
Temperature (oC) 7, 22, 30, 35 LateBerryGrowth 0.0, 0.0072, 0.0072, 0.0
WaterContent
Stages = StartDormancy EndDormancy BudBurst Flowering Set Veraison Ripe LeafFall Codes = 0.93, 0.93, 0.93, 0.93, 0.93, 0.85, 0.7, 0.7
Reserve
InitialDM = 100 DailyRetransFraction = 0.1
StageCode
Stages = StartDormancy EndDormancy BudBurst Flowering Set Veraison Ripe LeafFall Codes = 1, 2, 7, 23, 27, 35, 38, 47
Description
APSIM WaterSupply is an instantiable module, capable of performing the role of water-source for the APSIM Irrigate module. The module can be configured to simulate a dam, sump, river, bore or effluent source. In any given APSIM simulation, different instances of WaterSupply can be configured to represent one or more of these water sources, at the same time.
For example:
version = 3.1 [apsim.sample_soilwat2] title=Soilwat2 Sample Simulation module = clock soilwat2.par [sample] module = report soilwat2.par [sample] module = Input(Met) %apsuite\apsim\met\sample\dalby.met[weather]
module module module module module module module module module module
= = = = = = = = = =
manager soilwat2.par [sample] soilwat2 soilwat2.par [black_earth] soilwat2.ini [standard] soiln2 soilwat2.par [black_earth]oiln2.ini [standard] solute soilwat2.par [sample]solute.ini [standard] Screen soilwat2.par [sample] SummaryFile soilwat2.par [sample] WaterSupply(dam) soilwat2.par [sample] dam.ini [standard] WaterSupply(bore) soilwat2.par[sample]bore.ini [standard] WaterSupply(sump) soilwat2.par[sample] sump.ini [standard] irrigate
In the above simulation, WaterSupply is being instantiated to simulate a dam, a bore, and a sump. Each instance of this module is capable of maintaining an available pool of water, with a dynamic solute composition, able to provide water or receive water as required. Transfers of water between WaterSupply and Irrigate, or between WaterSupply and other instances of itself (eg dam and sump), are driven by commands from the APSIM Manager module. The WaterSupply module is subject to various internal daily processes which produce a dynamic balance of both water and solutes in storage. Depending on type of storage (eg dam or bore), these processes include direct capture of rainfall, capture of surface runoff (both local and catchment), evaporation and seepage losses, and renewal of allocations.
WaterSupply Parameterisation
The first and most critical piece of information required by the APSIM WaterSupply module during configuration is a parameter called "storage_type". There are six discrete categories available, and each instance of this module must be configured as one of these: 1. 2. 3. 4. 5. 6. dam_gully - a open surface storage formed by damming a watercourse dam_ring - a open-surface ring-tank into which water is pumped for storage dam_exc - an open-surface excavated storage sump - an open sump which generally collects local and/or catchment runoff river - a watercourse from which an annual pumping allocation is granted bore - a underground water-source from which similar allocation is granted
nb. An Effluent Source would best be configured as type "bore", since it will not be subject to daily processes such as evaporation, seepage etc. (see later).
Depending on which "storage_type" is configured, the following parameters are required by APSIM WaterSupply: For Dams and sumps
[sample.watersupply.parameters] source_type = dam_ring ! type of water source
receive_catchment_runoff = yes ! use "yes" if dam collects runoff from larger catchment area catchment_area = 120.0 ! catchment area (ha) (required only if "receive_catchment_runoff" equals "yes") catchment_runoff_factor = 0.5 ! multiplier for soilwat2.runoff, applied to catchment area (required only if "receive_catchment_runoff" equals "yes") receive_crop_runoff = yes ! use "yes" if dam collects runoff from simulated crop area max_available_water = 150.0 ! capacity (ML) max_area = 20 ! storage water surface area at capacity (ha) init_available_water = 144.0 ! supply volume available at start of simulation (ML) max_pump = 20.0 ! maximum pump delivery volume per day (ML/day) min_volume = 5.0 ! minimum volume in storage below which pump cannot access permeability = 0.00007 ! permeability of sealing layer (m/day) seal_thickness = 0.5 ! thickness of low permeability seal (m) init_br_conc = 100.0 ! initial bromide concentration (ppm)
For Bores and Rivers

[sample.watersupply.parameters] source_type = bore max_available_water = 400.0 (ML) init_available_water = 200.0 max_pump = 20.0 (ML/day) min_volume = 0.0 cannot access annual_allocation = 200.0 allocation_renewal_day = 270 init_br_conc = 100.0 init_cl_conc = 8.0 ! type of water supply ! maximum allocation including carry-overs ! volume available at start of simulation (ML) ! maximum pump delivery volume per day ! minimum volume in storage below which pump ! ! ! ! Annual Allocation in ML Day of year on which allocation is granted initial bromide concentration (ppm) initial chloride concentration (ppm)
Parameterising Solutes As can be seen in of the above examples, initial concentrations of solutes in the storage water can be specified using the parameter "init_xxx_conc" in parts-per-million, where "xxx" is the name of the solute. All solutes used in the system must also be initialized in the APSIM Solute module and given an initial distribution in the soil layers, even if this is zero in all layers. As water is transferred between various elements in the simulation (sumps, dams, bores, irrigation, soil), solutes will be transferred accordingly.
WaterSupply Processes
Rainfall Capture
For open surface dams and sumps, rainfall results in a storage gain, expressed by:
rain_capture = (area* rain)/100 (1) where, rain_capture = storage gain from rainfall event (Ml) area = capture surface area of dam (ha) rain = precipitation (mm) Bore and river allocations are not affected by precipitation.
Runoff Capture For open dams and sumps,
if the input parameter

receive_crop_runoff = yes
then local runoff (soilwat2.runoff) will be added to the storage water.
Soilwat2.runoff is calculated in mm, hence crop_area (ha) must be provided as a manager variable whenever WaterSupply is being used, to convert to ML.
If the input parameter

receive_catchment_runoff = yes
then the user must also supply two further parameters catchment_area (ha) and catchment_runoff_factor (0-1). The latter of these two subsequent inputs is a multiplier to the soilwat2.runoff parameter, effectively describing the water-shedding potential of the catchment in comparison to the cropped area.
If none of the instances of WaterSupply in a given simulation are configured to receive runoff, then runoff is lost from the system.
Runoff capture is calculated on a daily basis. Evaporation For open dams and sumps, loss of water to the atmosphere through evaporation is a daily occurrence. Evaporation is calculated in a two stage process as follows: From CERES maize soil evaporation
soil_evaporation = radn*23.8846*(0.000204-(0.000183*0.1)) *(29+(0.6* maxt+0.4* mint)) (2) where radn = incident solar radiation (Mj/m2) maxt = maximum daily temperature (oC) mint = minimum daily temperature (oC) The evaporation from the surface of the dam/sump is then calculated according to:
evaporation = vol-(area*((d-(0.7*se/1000))** b)) (3) where vol = current storage volume (Ml) area = dam surface area at capacity (ha) d = current storage depth (m) se = soil evaporation (as calculated above) b = geometry factor for dam type (from ini file) Seepage For open dams and sumps, loss of water through seepage out the base and sides is also a daily occurrence. Seepage is calculated as follows:
seepage = vol-(area*((d-(k*(d/st)/365.0))** b)) (4) where vol = current storage volume (Ml) area = dam surface area at capacity (ha) d = current storage depth (m) k = permeability of base (m/day) st = seal thickness (m) b = geometry factor for dam type (from ini file) Overflow For open dams and sumps, incoming water which takes the storage volume above capacity is reported daily as "overflow" (ML).
Allocation Renewal
For bores and rivers, an allocation renewal check is made every day, and on the day specified as "renewal day" in the input parameters, the "annual_allocation" is credited to the available storage volume. The amount of carry-over allowed is specified by the user in setting "max_available water".
Using WaterSupply with APSIM Irrigate

APSIM Irrigate works on a "mm" basis, whereas APSIM WaterSupply works on real volumes (ML). Hence, when an irrigation application is specified in mm, an "area of application" must be provided in order to calculate the required volume of water from the specified source instance of WaterSupply. As mentioned previously, whenever WaterSupply is used in a simulation for supply of irrigation water, a variable called "crop_area" (ha) must be specified in the manager logic. Irrigations using water from WaterSupply can only be initiated by using the "irrigate apply" action in manager. A new optional argument called "source" is added to the "apply" command line to trigger the use of water from WaterSupply. The required syntax is as follows:
[sample.manager.start_of_day] if day = 10 then irrigate apply amount=10 (mm), source = dam bore dam2 () endif
The argument "source" specifies the sources from which to obtain the irrigation water, in preferential order. In other words, in the above example, if the dam cannot fully supply the required water, the balance will be taken from the bore. If there is still a shortage of water, then dam2 will be asked next to supply water. There is no limit to the number of sources which can be specified.
When the irrigation water is applied to the soil, it will carry the solutes makeup of the water source being used.
Transfering Water between Instances of WaterSupply

In the general operation of an irrigation and water-storage system, there may be numerous occasions where the farmer wishes to transfer water between a sump and the dam, or to pump water from a bore or river into a dam. This is easily achieved in APSIM WaterSupply by employing the "TOP_UP" command from manager:
To transfer 5 megalitres of water from a sump to a dam, for example:
[sample.manager.start_of_day] if day = 15 then dam top_up amount=5 (Ml), source= sump endif
Or else, the dam (say, capacity =150 Ml) may need to be filled from the bore, without knowing the exact amount required:
[sample.manager.start_of_day] dam_deficit = 150-dam.available_water if day = 15 then dam top_up amount=dam_deficit, source= bore endif
Or else, the farmer may wish to pump to the dam whenever the sump is full:
[sample.manager.start_of_day] sump_volume = sump.available_water sump_deficit = sump.max_available_water - sump_volume if sump_deficit = 0 then dam top_up amount=sump_volume, source= sump endif
The preferential ordering of sources is available with the "top_up" command, as for the Irrigate "apply" command. In all of these examples, the "top_up" command will transfer the specified water from the source to the destination and calculate the new solute figures in the destination pool.
WaterSupply Actions and Events
Figure 1: UML diagram for an Irrigate "apply" action (specifying "source = dam") showing responses from modules concerned.
Figure 2: UML diagram for a WaterSupply (dam) "top_up" action (specifying "source = bore") showing responses from modules concerned.
Figure 3: UML diagram for a WaterSupply (dam) "top_up" action (specifying "source = sump bore") in the situation where the first specified source is not capable of supplying all of the water required. In this case supplementary water is required from the second specified source.
WaterSupply Module Outputs

Name available_water available_depth max_available_water min_volume max_pump annual_allocation allocation_renewal_day rain_capture evaporation seepage overflow runoff_input storage_xxx Units Ml m Ml Ml Description Current storage volume Current storage depth Storage capacity or max allocation carry-over Storage volume below which pumping not allowed
Ml/day Maximum daily pump delivery Ml doy Ml Ml Ml Ml Ml ppm Annual water allocation (bores, rivers) Day of year for renewal of allocation (bores, rivers) Rainfall captured by dam area Daily water loss to atmosphere Dam seepage loss through base and sides Input water above storage capacity Daily runoff added to storage Storage concentration of solute "xxx", eg storage_cl Water supplied from storage at request of APSIM Irrigate Flag indicating whether a storage is full (1) or not full(0)
irrigation_water_supplied ML full (0-1)
Name filling_event
Units (0-1)
Description Flag indicating whether a filling event occurred today
References
Jones, C.A., and J.R. Kiniry. 1986. CERES-Maize: A simulation model of maize growth and development. Texas A&M University Press, College Station, Texas. Don Gaydon Module Developer CSIRO Sustainable Ecosystems 306 Carmody Road ST LUCIA Q 4067 Email: don.gaydon@csiro.au Phone: +61 (0)7 3214 2230
WEED Module Scope

The weed module simulates the growth of a weed crop in a daily time-step (on an area basis not single plant). Weed growth in this model responds to climate (temperature, rainfall and radiation from the input module), soil water supply (from the soilwat module) and soil nitrogen (from the soiln module). The weed module returns information on its soil water and nitrogen uptake to the soilwat and soiln modules on a daily basis for reset of these systems. Information on crop cover is also provided to the soilwat module for calculation of evaporation rates and runoff. Weed stover and root residues are passed' from weed to the residue and soiln module respectively at harvest of the weed crop. The module predicts leaf area development, N% and biomass of stover; depth, N% and biomass of roots; grain N% and biomass; grain yield and N%, grain size and grain number all on a daily basis.
Weed Module History

There are a range of APSIM applications that have an emerging need for a simulation capability for weeds. For example: Weed competition is becoming recognised as an important part of the low-input cropping systems of smallholder agriculture, and must be simulated when, for instance, accounting for responses to fertility inputs Examining the risks of releasing herbicide-tolerant crop cultivars and associated spread of herbicide tolerant weeds In studies of soil water balance accounting for water use by fallow-growing weeds has been crucial in some circumstances The weedy component of some vegetation types we simulate can be significant at some situations (eg annual ryegrass in lucerne stands) Across the spectrum of applications there is a need to be able to specify the weed component to various levels of detail. In some circumstances it is necessary to specify the weed's biology and
lifecycle, and for a selection of well-studied weeds this ought to be possible. In other circumstances all that may be required is something to use water and nitrogen in about the right amounts. Currently, where weeds are being simulated users are using an existing crop module that is most like the dominant weed in the system. While this has proved satisfactory for those cases, it is not a sustainable situation. In particular, for users of APSFRONT, who do not have the capability to engineer a weed on the run, there is a need to provide a ready-made weeds capability. APSIM_Weed provides that capability. APSIM_Weed is based upon APSIM-Plant. APSIM-Plant was used because of a number of features: Its documented ability to simulate a range of vegetation types, from cool-season to warmseason adaptation, annuals and perennials, broadleaf and gramineacious crops. The crop_class feature coupled with the inheritance capability of APSIM crop modules means that a range of weed types can be configured ready-made for users, as well as set up easily on the run by more experienced users. The inheritance feature means that only those parameters known to differ from the base class parameters set need to be specified.
Weed Module Science

As the Weed module is an instantiation of the plant module the science is identical. Users are referred to APSIM-Plant documentation for details on science.
Weed types
At present four generic types of weeds can be grown in the module, as different crop_classes. They are listed below with their distinguishing characteristics. A grassy, C 3 annual weed designed to represent annual ryegrass. Parameters have been taken from the wheat module, with some additions from the literature on ryegrass. A grassy, C 4 annual weed designed to represent Johnson grass. Parameters have largely been taken from the sorghum module. A broadleaf, C 3 annual weed designed to represent wild radish. Parameters have been taken from the canola module. A broadleaf, C 3 N-fixing perennial weed designed to represent volunteer lucerne or similar legume.
Table 1:
Functionalities possible for the weed types in APSIM-Weed and how these are operationalised through parameters.
Desired functionality Perenniality
Temperature sensitivity (cool-season vs warmseason adaptation)
How this is achieved operationally in APSIM-Weed The crop either dies or regrows after a harvest operation or complete leaf senescence Tolerance to low/high temperature through thermal time vs temperature relationship rue vs temperature leaf senescence vs minimum temperature
Parameters
Min_tpla
y_tt vs x_temp y_rue vs x_temp x_temp_senescence vs y_senescence_fac
Broadleaf versus grasstype Nitrogen requirements
Crop has small/large individual leaf sizes Leaf_size n_conc_crit_leaf, stem Critical N requirements etc
Table 2:
The four weed crop_classes (i.e. types) and their differing characteristics.
Parameter
Winter_dicot 0 0.50 to 0.33 0 0.50 to 0.33
Summer_grass Perennial_legume 0 0.50 to 0.33 0 0 0.009 50 1.0 to 0.53 0.2 0.2 0.005
Perenniality
min_tpla ratio_root_shoot
Determinacy
frac_leaf_post_flower0 0 frac_leaf_grain_fill 0 0 C 3 vs C 4 transp_eff_cf 0.005 0.005 Legume vs nonlegume N_fix_rate 0 0 n_conc_crit_leaf 0.039 to 0.018 0.039 to 0.018 n_init_conc (root, 0.018 0.06 leaf, stem) 0.060 leaf_size 1400 to 6000 1000 to 20000 Temperature sensitivity ave_temp vs 15.0 30.0 15.0 30.0 stress_photo 40.0 40.0 0.0 1.0 1.0 0.0 0.0 1.0 1.0 0.0 Cardinal temps for tt 0.0 30.0 40.0 0.0 30.0 40.0 Minimum temps for -5 to -15 o C -5 to 15 o C leaf senescence
0 0.002 0.039 to 0.018 0.060 to 0.020 0.025 0.060 0.060 1000 to 60000 400 to 1200 15.0 30.0 40.0 0.0 1.0 1.0 0.0 0.0 30.0 40.0 -5 to -15 o C
8.0 25.0 35.0 40.0 0.0 1.0 1.0 0.0 10.0 35.0 45.0 6 to 0 o C
Issues that users should be aware of

Due to the way that crop residues are handles in APSIM, it is possible to only pass one fixed value for residue specific_areas regardless of the weed type being simulated. Cultivars would differ in terms of height (and hence competitive ability) and short/long season. Using the module parameter inheritance characteristics of APSIM-Legume, it is possible to create other permutations eg a warm-season dicot.
Weed Module Parameterisation

As with APSIM-Legume, crop lower limit (LL) and water extraction coefficients (KL) and root exploration factors (XF) values are need for each soil layer. test.weed.parameters
ll = 0.200 0.200 0.200 0.220 0.250 () ! crop lower limit kl = 012 0.08 0.06 0.04 0.02 () ! kl need calibrating for each crop and soil type xf = 1 1 1 1 0.5 () ! root exploration factor Phenology, grainfilling and crop height parameters are needed for each cultivar. An example is given below of those for the early culltivar. At present the module contains two cultivars only early and late. standard.weed.early hi_incr = 0.010 (1/days) x_hi_max_pot_stress = 0.00 1.00 () y_hi_max_pot = 0.15 0.15 () cum_vernal_days = 0 100 tt_emerg_to_endjuv = 400 700 est_days_emerg_to_init = 83.0 (d) photoperiod = 1 24 phase_tt_init = 500 500 tt_flower_to_maturity = 500.0 (oCd) tt_init_to_flower = 50.0 (oCd) tt_flower_to_start_grain = 120.0 (oCd) tt_maturity_to_ripe = 1.0 (oCd) x_stem_wt = 0 300 (g/m2) y_height = 0 800 (mm)
Module Dependencies
The minimum module configuration required to run weed in APSIM is the inclusion of the report, input, manager, soilwat2, soiln2, residue2 and weed modules. Within the manager file the following syntax is used for harvest and planting the weed crop: if (weed.stage_name = 'harvest_ripe' and weed.plant_status = 'alive') then weed harvest weed kill_crop weed end_crop endif if (weed.plant_status = 'dead') then report do_output weed harvest weed end_crop endif if (day > 120 and day < 240 and weed.plant_status = 'out' ) then weed sow plants = 15 (p/m2), crop_class=winter_grass, sowing_depth = 50 (mm), row_spacing = 0.35 (m), cultivar = late endif (note: row_spacing in sowing command is optional) As with any of the PLANT crop modules it is possible to kill a fraction of plants upon a manager action, for instance killing by herbicide. The following line in the manager module: weed kill_crop, kill_fr = 0.6 would kill 60% of plants
This is an instantiable module, that is, it can be used in several contexts within the one simulation. For example, this module may be used to simulate one weed, while another instanceof this module (configured differently) is used simultaneously to represent another growing with the first weed. There are certain protocols and procedures which must be followed in order to instantiate modules, and these are described in more detail in the document Module Instantiation , found in C:\apsuite\docs.
WEED MOULE WORKING GROUP

Michael Robertson
WHEAT Module Scope

APSIM-Wheat module simulates the growth and development of a wheat crop in a daily time-step on an area basis (per square meter, not single plant). Wheat growth and development in this module respond to weather (radiation, temperature), soil water and soil nitrogen. The wheat module returns information on its soil water and nitrogen uptake to the soil water and nitrogen modules on a daily basis for reset of these systems. Information on crop cover is also provided to the water balance module for calculation of evaporation rates and runoff. Wheat stover and root residues are passed' from wheat to the surface residue and soil nitrogen modules respectively at harvest of the wheat crop. Approaches used in modelling crop processes balance the need for comprehensive description of the observed variation in crop performance over diverse production environments and the need to avoid reductionist approaches of ever-greater complexity with large numbers of parameters that are difficult to measure. A list of the module outputs is provided in the Wheat module outputs' section below. Basically the module simulates phenological development, leaf area growth, biomass and N concentration of leaves, stems, roots and grains on a daily basis. It also predicts grain size and grain number.
Wheat Module History

APSIM-Wheat was developed from a combination of the approaches used in previous APSIM wheat modules: Asseng et al. 1998a,b, Meinke et al. 1997a,b and Wang et al. 2003. The current version of the model is implemented within the APSIM Plant model framework which is currently used for other crops such as grain legumes and canola. Most of the model constants (species-specific) and parameters (cultivar specific) are externalised from the code.
Wheat Module Structure

Figure 1 shows the modular structure of APSIM-Wheat.
Wheat Module Components Phenology

APSIM-Wheat uses 11 crop stages and ten phases (time between stages). It can output stage code and names as well as equivalent Zadok's stage. ===Table 2:=== lists the stage code, name and the key processes starting at the commencement of each stage. Table 2: Stages of phenological development simulated in APSIM_Wheat.
Stage Code 1 2 3 4 5 6 7 8 9 10 11
Stage Name Sowing Germination Emergence
Starting processes Seed germination Emergence, leaf initiation Vegetative growth (LAI, DM), water/N uptake Photoperiodism
Equivalent Zadok's 0 5 10 10 15 / 30 60 71 87 90 93 100
End of Juvenile Stage Floral Initiation / Spikelet initiation / terminal spikelet* Rapid stem growth Anthesis Setting grain numbers Start of Grain Filling Active grain growth End of Grain Filling Maturity Physiological Grain moisture loss Maturity Harvest Ripe End Crop
*Because the CERES-Wheat phenology approach is used (see text below), terminal spikelet, instead of floral initiation, is simulated in the current wheat model. The commencement of each stage (except for sowing to germination, which is driven by soil water content) is determined by accumulation of thermal time. Each day the phenology routines calculate today's thermal time (in degree-days) from 3-hourly air temperatures interpolated from the daily maximum and minimum crown temperatures. Crown temperatures are simulated according to the original routines in CERES-Wheat. Thermal time is calculated using the relationship in Figure 2 with the eight 3-hour estimates averaged to obtain the daily value of thermal time (in degree-days) for the day. These daily thermal time values are cumulated into a thermal time sum, which is used to determine the duration of each phase.
Figure 2. Relationship between crown temperature and thermal time used in APSIM-Wheat Between the stage of emergence and flowering the calculated daily_thermal_time can be reduced by water or nitrogen stresses, resulting in delayed phenology when the plant is under stress. These stress factors can be specified in wheat.ini by changing the values of x_sw_avail_ratio/y_swdef_pheno and N_fact_pheno . Currently these values are set so that there are no water and nitrogen stress effects on phenological development. Research showed that moderate water stress may accelerate development, while severe water stress may delay phenology (Angus, 1977). Germination is considered as a quick process. Germination is assumed to occur as long as the extractable soil water in the seed layer is above a given value pesw_germ specified in Wheat.ini. pesw_germ is the soil water content above the crop lower limit (mm/mm) in the seed layer inadequate for germination. The default setting is zero, meaning that germination will occur one day after sowing regardless of soil water content. The phase between germination and emergence includes an effect of the depth of sowing on the thermal time target. The phase is comprised of an initial period of fixed thermal time during which shoot elongation is slow (the lag phase) and a linear period, where the rate of shoot elongation towards the soil surface is linearly related to air temperature (measured in o Cd mm -1 ). Most studies on seedling emergence have simply recorded the accumulated thermal time between germination and 50% emergence from a given sowing depth. For the purposes of model parameterisation the value of shoot_lag has been assumed to be around 40 o Cd, while shoot_rate has been derived from studies where thermal time to emergence was measured and where sowing depth was known and it is set to 1.5 o Cd per mm. This means that at a sowing depth of 4 cm emergence occurs 100 o Cd after germination (40+1.5*40). There is the capability of increasing the time taken to reach emergence due to a dry soil layer in which the seed is germinating, through the relationship between fasw_emerg andrel_emerg_rate . Currently this effect is turned off in the Wheat.ini file. The phase between emergence and end of juvenile stage is composed of a cultivar-specific period of fixed thermal time, commonly called the basic vegetative or juvenile phase, which is a period when development rate is not affected by photoperiod. The end of the juvenile phase in wheat is currently timed as occurring on the day after emergence, because it is known that the development rate of wheat is sensitive to photoperiod from emergence. The end of the juvenile phase is included in the model to make the stages compatible with other cereal crops in APSIM that do have a definable juvenile phase.
After the end of the juvenile phase the crop takes 400 o Cdays to reach terminal spikelet stage. The rate at which the crop attains this target depends upon photoperiod and vernalisation. The daily rate of accumulation of thermal development rate is sensitive to photoperiod and accumulation of vernalising days. The sensitivities to photoperiod (photop_sens ) and vernalisation ( vern_sens ) are cultivar-specific. The model assumes that wheat, as a long day plant, will have a longer phase (dependent upon cultivar) between the end of the juvenile phase and terminal spikelet under short days. Photoperiod is calculated from day of year and latitude using standard astronomical equations accounting for civil twlight using the parameter twilight, which is assumed to be 6 o . Twilight is defined as the interval between sunrise or sunset and the time when the true centre of the sun is 2.2 degrees below the horizon. Vernalisation is simulated from daily average crown temperature and daily maximum and minimum temperatures using the original CERES approach. Devernalisation can occur if daily maximum temperature is above 30 o C. There are fixed thermal time durations for the subsequent phases between terminal spikelet and flag leaf (3 phyllochrons), from flag leaf to flowering (2 phyllochrons + 80 o C days). In the original CERES phenology routines, 2 phyllochrons from flag leaf marked the end of ear growth and then 80 o C days was required to reach anthesis. From flowering to the start of grain fill the thermal duration is assumed to be 120 o C days (= 200-80 o C days, in CERES 200 o C days was assumed to elapse between the end of ear growth and the start of grain filling). The duration of grain filling ( tt_startgf_to_mat ) is cultivar specific and usually lies between 500 and 800 o C days.
Biomass accumulation (Photosynthesis) Radiation interception

Radiation interception is calculated from leaf area index and a radiation extinction coefficient ( extinct_coeff ) that varies with row spacing.
Radiation Use Efficiency

The intercepted radiation is converted to above ground biomass via a RUE (radiation-use efficiency), which is 1.24 g MJ -1 from emergence to the end of grain-filling, and does not vary as a function of daily incident radiation as in NWHEAT. RUE is reduced by extremes of daily mean temperature as sown in the following figure. It is also reduced by a nitrogen stress factor n_fact_photo specified in Wheat.ini.
Figure 3: Response of wheat radiation-use efficiency to temperature
Water-nonlimiting
Under water non-limiting condition, the biomass growth rate is given by: dlt_dm_rue = RUE *radiation_interception eqn 1.
Water-limiting
Each day two estimates of the daily biomass production are calculated, one limited by available water for transpiration (eqn 2), and the other limited by radiant energy (eqn 1). The minimum of these two estimates is the actual biomass production for the day. dlt_dm_water = soil_ water_ supply * transpiration_efficiency eqn 2. dlt_dm = min(dlt_dm_water, dlt_dm_rue) transpiration_efficiency is derived from the transpiration_efficiency_coefficient (=0.006 kPa) and the vapour pressure deficit (vpd) estimated from daily temperatures.
Biomass partitioning and retranslocation Partitioning

On the day of emergence, biomass in plant parts (leaf, root, and stem) is initialised to user-specified values. Daily biomass production is then partitioned to different plant parts in different ratios depending on crop stage. In the wheat module, leaf includes only leaf blade. Stem is defined in a functional rather than a morphological manner and includes stem proper, leaf sheaths and stem-like petioles. The biomass increase calculated each day only accounts for the above ground organs. The minimum fraction of biomass going to roots is calculated from the stage dependentroot_shoot_ratio specified in Wheat.ini. Between emergence and grain filling, the above ground biomass is partitioned to leaf, stem and head based on stage dependant partitioning rules. If, on any day, the estimated specific leaf area (based on leaf biomass and LAI deltas) goes below the minimum specific leaf area, the extra biomass is diverted to stems. At anthesis, the number of grains set per plant is determined by the stem weight. From start to end of grain filling biomass increase is used to meet grain demand first, the rest is put into stems. Grain demand for carbohydrate (biomass) is calculated by multiplying the grain number by the potential grain growth rate ( potential_grain_filling_rate, g/grain/day ) specified in Wheat.ini .
Re-translocation
If the supply of assimilate (daily biomass increase) is insufficient to meet grain demand then retranslocation may be used to meet the shortfall. The wheat module allows a total retranslocation of no more than 20% of stem biomass present at the start of grainfilling Grain yield on a commercial moisture basis is calculated using the parameter grn_water_cont = 0.125.
Leaf initiation/appearance and tillering

Leaves appear at a fixed phyllochron of thermal time, currently set to 95 o Cd in the wheat.ini. No effect from water and N stress on leaf appearance is accounted for.
Leaf area growth

On the day of emergence leaf area per plant is initialised to a value of 200 mm 2 per plant.
Potential LAI growth rate

Potential increase in plant leaf area is calculated from main stem node appearance rate multiplied by the leaf size (as a function of node number) multiplied by the number of leaves per main stem node (i.e. tiller number)
Leaf area growth rate under stress

Water and nitrogen limitations affect leaf area development directly rather than via dry matter production. Water and nitrogen limitations result in either a reduction of leaf expansion or in number of tillers produced. Two stress factors are introduced to account for the effect of water and nitrogen stress respectively on leaf area growth. It is assumed that leaf expansion growth is reduced when the supply/demand ratio for water is below 1.1 and stops when supply/demand ratio reaches 0.1. This relationship is specified in Wheat.ini in the look-up tablex_sw_demand_ratio/y_swdef_leaf . The nitrogen stress factor is defined as: g_nfact_expansion = N_fact_expansion * n_conc_ratio_leaf where n_conc_ratio_leaf is the relative N concentration in leaves (N_conc_leaf N_conc_leaf_min)/(N_conc_leaf_crit - N_conc_leaf_min). N_fact_expansion is a modifying constant specified in Wheat.ini. It is currently set to 1.0, ie. leaf expansion is reduced once leaf N concentration is below the critical N concentration, and stops when leaf minimum concentration is reached. The leaf area growth rate under stress is given by: g_dlt_lai_stressed = g_dlt_LAI_pot * min (g_swdef_expansion, g_nfact_expansion)
Actual leaf area growth rate

Actual leaf area growth rate differs from stressed leaf area expansion rate (g_dlt_lai_stressed) only if carbon supply is insufficient to meet a maximum specific leaf area for the daily increase in leaf area ( sla_max ). Carbon supply may become limiting, for example, at high plant population densities. The current model specifies sla_max as varying from 27 000 to 22000 mm 2 g -1 t o constrain daily leaf area increase where carbon is limiting. However, as the value of the maximum specific leaf area operates on the daily increase in leaf area it is not readily derived from experimental data and must be calibrated by trial-and error.
Root growth and distribution Root depth growth

Between germination and start of grain filling, the increase in root depth is a daily rate multiplied by a number of factors. Root depth is constrained by the soil profile depth The optimum rate of elongation is 30mm d -1 . This can be limited by supra- or sub-optimal temperatures. Dry soil can slow roots through a layer if the soil water content is less than 25% of the way between the lower limit and drained upper limit. The increase of root depth through a layer can
be constrained by known soil constraints through the use of the 0-1 parameterxf, which is input for each soil layer.
Root length density

Growth of root biomass is partitioned with depth using a branching function and converted to root length density using a fixed specific root length of 105,000 mm g -1 . Root biomass is grown daily in proportion to the tops production. This proportion ( ratio_root_shoot ) is specified for each growth stage, and varies from 1.0 at emergence, to 0.09 at flowering.
Senescence Root senescence

A rate of 0.5% of root biomass and root length is senesced each day and detaches immediately being sent to the soil nitrogen module and distributed as fresh organic matter in the profile.
Leaf senescence
There are four causes of leaf senescence: age, water stress, nitrogen stress and high temperature stress. The wheat senescence routines calculate stress factors for water, N and high temperature. The maximum of these is multiplied by the senesced LAI due to age each day to obtain the day's total senescence. The stress factor for water is calculated from swdef_photo , for N from nfact_photo. Senescence due to frost commences when temperatures decrease below -5 C.
Nitrogen in seneseced leaves

When leaf is senesced, only a small amount of nitrogen is retained in the senesced leaf, the rest is made available for re-translocation by putting it into stem N pool. The concentration of nitrogen in senesced material is specified in the wheat ini file.
Crop Water Relations Potential water extraction rate

When the Wheat module is coupled to APSIM-SOILWAT2, potential soil water uptake is calculated using the approach first advocated by Monteith (1986). It is the sum of root water uptake from each profile layer occupied by roots. If roots are only partially through a layer available soil water is scaled to that portion that contains roots. The potential rate of extraction in a layer is calculated using a rate constant ( kl ), which defines the fraction of available water able to be extracted per day. The kl factor is empirically derived, incorporating both plant and soil factors which limit rate of water uptake. Root water extraction constants ( kl ) must be defined for each combination of crop species and soil type.
Crop water demand

Following Sinclair (1986) and Monteith (1986), transpiration demand is modelled as a function of the current day's crop growth rate (dlt_dm_rue, see Biomass Accumulation Section), divided by the transpiration efficiency. Transpiration efficiency is related to the daylight averaged vapour pressure deficit ( vpd ). Transpiration demand is calculated from the daily crop growth rate limited by RUE (dlt_dm_rue), vpd , and the transpiration efficiency coefficient. In the model vpd is estimated using
the method proposed by Tanner and Sinclair (1983), which requires only daily maximum and minimum temperatures. In this method, it is assumed that the air is saturated at the minimum temperature. The saturated vapour pressure is calculated at both the maximum and minimum temperatures, and the default vapour pressure deficit for the day is taken as 75% of the difference between these two vapour pressures. Crop water demand is capped to below a given multiple of potential ET (taken as Priestly-Taylor Eo from the water balance module) as specified in the wheat ini file. This limits water use to reasonable values on days with high VPD or in more arid environments.
Water uptake
The actual rate of water extraction is the lesser of the potential extraction rate and the transpiration demand. If the computed potential extraction rate from the profile exceeds demand, then the extracted water is removed from the occupied layers in proportion to the values of potential root water uptake in each layer. If the computed potential extraction from the profile is less than the demand then, and the actual root water uptake from a layer is equal to the computed potential uptake.
Water stresses affecting plant growth

Soil water deficit factors are calculated to simulate the effects of water stress on different plant growth processes. Three water deficit factors are calculated which correspond to four plant processes each having different sensitivity to water stress i.e. photosynthesis (photo), leafexpansion (expansion), phenology (pheno), and tillering (tiller). A factor of 0 is complete stress and 1 no stress. Leaf expansion is considered more sensitive to stress than photosynthesis.
Nitrogen uptake and re-translocation Potential nitrogen supply

The model uses a simplified formulation for NO3 uptake somewhat similar in structure to that employed in water uptake. Potential NO3 uptake in a layer is given as Uptake = NO3 kg/ha x (Kln x NO3 ppm x SWFAC) Where Kln is a parameter constant and SWFAC is a soil water content factor based on relative soil water content between lower limit and drained upper limit.
Nitrogen demand by vegetative organs

The crop has a defined minimum, critical and maximum N concentration for each plant part. These concentration limits change with phenological stages. The maximum and minimum N concentrations can be found in Wheat.ini. Demand for N in each part attempts to maintain N at the critical (nonstressed) level. N demand on any day is the sum of the demands from the pre-existing biomass of each part required to reach critical N content, plus the N required to maintain critical N concentrations in that day's produced biomass. For each plant part (leaf, stem, root) the N demand is given by: N_demand = dm_green * (n_conc_critic - n_conc) + dlt_dm_green * n_conc_critic.
Where dm_green and dlt_dm_green are the existing live biomass and biomass growth rate today. N_conc and n_conc_critic are the actual and critical N concentration respectively of this plant part. Total crop N demand is the sum of the n demand in all vegetative parts.
Nitrogen partition in the plant

Daily total nitrogen uptake is distributed to the plant parts in proportion to their individual demands.
Grain N demand
Grain nitrogen demand starts at anthesis and is calculated from grain number, thermal time and a potential grain nitrogen filling rate (g/grain/degree day).
Nitrogen re-translocation
If there is insufficient nitrogen supplied from senescing material or soil nitrogen uptake, grain nitrogen demand is met by re-translocating nitrogen from other plant parts. Nitrogen is available for re-translocation from leaves and stems until they reach their defined minimum N concentration.

There are four N availability factors (0-1), one each for the photosynthesis, expansion, phenology and tillering. A N concentration ratio is calculated for the stover (stem + leaf) which is used as a measure of N stress, then different constants are used to convert that ratio to a deficit factor for each of the processes. A factor of 1.5 is used to restrict photosynthesis (reduces rue), 1.0 for expansion (reduces leaf area expansion) and 100 to slow phenological development (effectively disabled). For tillering a squared n_conc_ratio is used as the stress factor. As a value of 1 is no stress and 0 complete stress, phenology is least sensitive to nitrogen deficiency and grain N the most. N_conc_ratio=(N_conc_stover-N_conc_stover_min)/(N_conc_stover_crit-N_conc_stover_min)
Plant death
All or some of the plants can be killed due to a variety of stresses. If the crop hasn't germinated within 40 days of sowing, due to lack of germinating moisture, all plants are killed. If the crop does not emerge with 300 o Cdays of sowing, because it was sown too deep, then all plants are killed. If crop is past floral initiation and LAI = 0, then all plants are killed due to total senescence.
Detachment
The detachment routines in wheat are disabled in the wheat.ini file, except the detachment of senesced roots.
Effects of elevated atmospheric CO 2

Elevated levels of atmospheric CO 2 affect plant growth in this module via three mechanisms. Carbon dioxide concentration can affect radiation use efficiency, transpiration efficiency and critical leaf nitrogen concentration. The following graph shows the relative change in RUE for C4 and C3 plants (at 20 o C), TE and critical nitrogen concentration. More information can be found in Reyenga et al (1999).
Wheat Module Parameterisation

Crop lower limit (LL) and water extraction coefficients (KL) and root exploration factors (XF) values are need for each soil layer. The following example is used in the sample run. sample.wheat.parameters uptake_source = calc ! calculate own uptakes. !layer 1 2 3 4 5 6 7 ll = .200 .201 .215 .176 .141 .249 .279 ! Crop lower limit kl = 0.06 0.06 0.06 0.06 0.06 0.06 0.02 ! Water Extraction parameter (0-1) xf = 1.00 1.00 1.00 1.00 1.00 1.00 1.00 ! Root Exploration factor (0-1)
Module Dependencies
The minimum module configuration required to run wheat in APSIM is the inclusion of the report, input, manager, soilwat2, soiln2, residue2 and wheat modules. In the sample folder, within the manager file the following syntax is used for harvest and planting the wheat crop: wheat.manager.start_of_day if day = 169 and year = 1992 then wheat sow cultivar = hartog, plants = 121.61, sowing_depth = 30 (mm), endif if wheat.stage_name = 'harvest_ripe' or wheat.plant_status = 'dead' then wheat harvest wheat end_crop endif
REFERENCES
Angus, 1977. Water stress and phenology in wheat. Australian Journal of Agricultural Research 28:177-181. Asseng, S., Fillery, I.R.P, Anderson, G.C., Dolling, P.J., Dunin, F.X., Keating, B.A. 1998a. Use of the ASPIM wheat model to predict yield, drainage, and NO3 leaching for a deep sand. Australian Journal of Agricultural Research 49: 363-377. Asseng, S., Keating, B.A., Gregory, P.J., Fillery, I.R.P, Bowden, J.W., Turner, N.C., Palta, J.A., Abrecht, D.G. 1998b. Performance of the APSIM wheat model in Western Australia. Field Crops Research 57:163-179. Asseng, S, van Keulen, H, Stol, W. 2000. Performance and application of the APSIM Nwheat model in the Netherlands. European Journal of Agronomy 12: 37-54. Gallagher, J N, 1979. Field Studies of Cereal Leaf Growth: I. Initiation and expansion in relation to temperature and ontogeny. Journal of Experimental Botany 30: 625-636. Meinke, H, Rabbinge, R., Hammer, G.L., van Keulen, H., Jamieson, P.D. 1997a. Improving wheat simulation capabilities in Australia from a cropping systems perspective. II. Testing simulation capabilities of wheat growth. European Journal of Agronomy 8: 83-99. Meinke,H, Hammer, G.L., van Keulen, H., Rabbinge, R., 1997b. Improving wheat simulation capabilities in Australia from a cropping systems perspective. III. The integrated wheat model (I_WHEAT). European Journal of Agronomy 8: 101-116. Monteith, J.L., 1986. How do crops manipulate water supply and demand? Philos. Trans. R. Soc. London A, 316:245-259. Otter-Nacke, S., Godwin, D.G., Ritchie, J.T 1986. Testing and validating the CERES-Wheat model in diverse environments. AGRISTARS Yield Model Development. USDA-ARS, Temple, TX. Reyenga, P.J., Howden, S. M., Meinke, H., McKeon, G.M., 1999. Modelling global change impacts on wheat cropping in south-east Queensland, Australia. Environmental Modelling & Software 14: 297-306. Sinclair, T.R. 1986. Water and nitrogen limitations in soybean grain production. Field Crops Research 15:125-141. Sinclair, T.R. and Amir, J. 1992. A model to assess nitrogen limitations on the growth and yield of spring wheat. Field Crops Research 30: 63-78. Strong, W.M., R. C. Dalal, E. J. Weston, J. E. Cooper, K. J. Lehane, A. J. King, C. J. Chicken, 1996. Sustaining productivity of a Vertisol at Warra, Queensland, with fertilisers, no-tillage or legumes. 2. Long-term fertiliser nitrogen needs to enhance wheat yields and grain protein. Australian Journal of Experimental Agriculture 36: 665-674. Tanner, C.B. and Sinclair, T.R., 1983. Efficient water use in crop production: research or re-search? In: H.M. Taylor, W.R. Jordan and T. R. Sinclair (Eds), Limitations to Efficient Water Use in Crop Production. American Socieity of Agronomy. Madison, WI, pp1-27. Wang, E., van Oosterom, E. J., Meinke, H., Asseng, S., Robertson, M. J., Huth, N. I., Keating, B. A., and Probert, M. E. The new APSIM-Wheat model - performance and future improvements. Solutions for a better environment: Proceedings of the 11th Australian Agronomy Conference Geelong, Victoria. (794). 2003. Zadoks, J.C., Chang, T.T., Konzak, C.F. 1974. A decimal code for the growth stages of cereals. Weed Research 14: 415-421. SiteSearch, Login/Logout, Account Settings, Create a new Page

Apsim

Enviado por

Dados do documento

Descrição original:

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Apsim

Enviado por

Direitos autorais:

Formatos disponíveis

News

Bugs & Tasks

Print all Modules

BARLEY Module Scope

Barley Module History

Barley Module Structure

Barley Module Components

Stage Name Sowing Germination Emergence

Equivalent Zadok's 0 5 10 10 15 / 30 60 71 87 90 93 100

Figure 3: Response of barley radiation-use efficiency to temperature

Barley Module Parameterisation

The APSIM Broccoli Module Transplant

ThermalTime 0.0, 20.0, 0.0

Start = EndShock End = FloralInitiation

ExtinctionCoeff 0.8, 0.5

Height 100.0, 750.0

FT 0, 0.0, 10, 1.0, 22, 1.0, 35, 0.0

FVPD 0, 1.0, 10, 1.0, 50, 1.0, RUE = 1.7

MaxArea 200, 1800.0, 14700.0, 83000.0

SpecificLeafArea 16000.0, 16000.0

GrowthDuration 60.0, 210.0, 450.0, 900.0

50.0, 100.0, 250.0, 250.0

Notable features of APSIM-Canola

Cultivars and crop classes

Notable features of APSIM-CHICKPEA

Cultivars and crop classes

Figure 1: Observed and simulated days to flowering for chickpea.

In which environments should this module be used with confidence?

Module Output Variables

Using Sub-Daily Timesteps

Notable features of APSIM-COWPEA

Cultivars and crop classes

IN WHICH ENVIRONMENTS THIS MODULE SHOULD BE USED WITH CONFIDENCE?

is further modified by cover by Rose (1985):

Factor approximating efficiency of entrainment

Efficiency of entrainment (bare surface) COV Surface cover (%)

[xxx.manager.start_of_day] total_cover = surface.surf_cover

To use erosion with apswim, add the following rules:

[xxx.manager.init] total_cover = 0.0

[xxx.manager.start_of_day] total_cover = 1.0 (1.0 - crop1.cover_tot) * (1.0 crop2.cover_tot) * * (1.0 - residue2.residue_cover)

During daily processing, the following procedures occur:

System interface names Parameter file:

Name minimum_depth slope slope_length bed_depth cover_extra (optional)

Freebairn specific parameters

dlt_dlayr() thickness of soil layer i (mm)

Known bugs and defects

Notable features of APSIM-FABABEAN

Cultivars and crop classes

IN Which environments THIS MODULE should be used with confidence?

Fertiliser Module Outputs

Michael Robertson 4 th May 2004

Roseworthy 2002 sown 17 th May

Roseworthy 2002 sown 6 th June

Notable features of APSIM-Growth

Example Manager Syntax

Partitioning of daily Growth

Senescence and Detachment of biomass

Plant water use

Variable Name dlt_root_mass dlt_root_mass_sen dlt_root_n dlt_root_n_sen Ep Fage

Units /ha kg DM /ha kg DM /ha kg N /ha kg N /ha Mm 0-1

Variable Name root_n rue_actual SLA_senescing Slai sw_demand total_n

Units kg N /ha g/MJ mm/g m/m2 Mm kg N /ha

In Which Environments Should This Module Be Used With Confidence?