Abstract

TRIS_COMdll

TRIS_COMdll (Dynamic Link Library) is a MS Windows library implementing the TRIS micrometeorological model proposed by Confalonieri et al. (2005) for simulating the floodwater effect on vertical thermal profile in paddy rice fields. The knowledge of the micrometeorological conditions in flooded rice fields is in fact crucial for better modelling the behaviour of the crop in mid and high latitudes, where the thermal mitigation provided by water layer is significant against the climatic risk of low temperatures in spring and early summer.

The DLL can be used in MS Excel spreadsheets, and in code developed using a visual Windows programming language (Visual Basic 6, C++, Delphi, etc.). The DLL can be freely used and distributed by users in their own applications.

TRIS_COMdll was developed by Roberto Confalonieri, Luigi Mariani, Marcello Donatelli, Marco Acutis, Gabriele Cola.

The programming was made by Roberto Confalonieri.

This Help system was created using a trial version of RoboHelp. Files generated with the trial version are intended for evaluation purposes only and may not be used or distributed for any other purpose.


Model documentation

The modellization of the floodwater effect on vertical thermal profile is based on the TRIS model (Confalonieri et al., 2005). Two strategies are implemented for water temperature: an empirical one, developed on the estimation of the water temperature on the basis of the air temperatures of some past days and a mechanistic one funded on the resolution of the energy balance equation adopting as storage term the heat accumulation into the water.

Preliminary elaborations

If other data are not available, TRIS is able to work only with daily values of maximum and minimum air temperature and global solar radiation.

If solar radiation data are missing it is possible approximate them on the base of the air temperature by means of the algorithm proposed by Donatelli and Campbell (1998).

Daily relative humidity (RH) is modelled with the algorithm described by Mc Vicar and Jupp (1999), based on the assumption that minimum air temperature is equal to dew point temperature and that the mixing ratio remain constant during the day.

The above mentioned daily meteorological variables feed the Denison and Loomis (1989) hourly generator that produces hourly values necessary to run TRIS.

Hourly values of Wind Velocity are obtained as a function of hourly air temperature.

Description of the mechanistic algorithm

Simulation of temperature at the water surface

TRIS is based on the resolution of the energy balance equation of a water surface (Oke, 1978) (eq. 1):

[J m-2 h-1]

Where the flux terms are respectively the net radiation (Rn), the heat stored into the water (G), the latent heat (LE) and the sensible heat flux. The storage term G acts practically as the only source of energy at night and a considerable sink of energy during daytime (Geiger, 1961).

The term H can be expressed as (eq. 2):

[J m-2 h-1]

Were Ts [°C] is water surface temperature, Ta [°C] is air temperature and hu is the turbulent transfer coefficient of sensible heat.

The short period variability of hu has been neglected, in similarity with the approach adopted by Makin (1999) for sea surface, assuming a constant value when LAI is null while it decreases proportionally to LAI when the canopy is growing (eq. 3):

[J m-2 h-1 °C-1]

Where z1 = 106 and z2 = 4·105.

Substituting equation (2) in equation (1) we can obtain water surface temperature as follows (eq. 4):

[°C]

In this equation the term Rn is obtained from (eq. 5):

[J m-2 h-1]

Where Rg is the global solar radiation.

In absence of a significant canopy effect, a constant value of 0.08 was adopted for the albedo, as suggested for shallow water by Uchijima (1976).

RL is the net outgoing long wave radiation obtained with Brunt’s semi-empirical solution of the Stefan – Bolzmann’s law (Sutton, 1953) (eq. 6).

[J m-2 h-1]

Where σ is the Stefan - Bolzmann constant, TK is the air temperature [K], ea is the vapour pressure.

a, b, an are empirical parameters (values of 0.44 and 0.080 were adopted for a and b and a value of 0.65, typical of cumulus clouds, was assigned to an parameter) and co is the cloud coverage. Daily value of co, that varies in the range 0÷1 (1 is for overcast sky), was obtained from the ratio between the current simulated value of Rg and the maximum possible for the selected day.

The term G was estimated on the base of net radiation Rn by means of the following empirical equation (Burba et al, 1999) (eq. 7):

[J m-2 h-1]

Term E is simulated adopting the following approach, proposed by Penman (1948) (eq. 8):

[J m-2 h-1]

Were es ed ea [hPa] are the vapour pressures respectively referred to water surface and air (vapour pressure of water surface is considered equal to saturated vapour pressure es) is the psicrometric constant (0.66) and is the slope of the saturation vapour pressure curve between the average air temperature and dew point.

ea is obtained by relative humidity RH.

Simulation of temperature at the water surface

The above described energy balance is affected by rice growth: the growing canopy modifies all the fluxes involved in the balance.

The algorithm adopted for canopy simulation is based on the following assumptions: (i) rice canopy is considered as a multilayer pattern with layers of constant depth of 10 cm; (ii) the number of layers increase with the age of the crop; (iii) LAI is homogeneously subdivided among the layers. LAI, canopy height, and crop coefficient at full canopy (kc) are input of the TRIS model and must be obtained externally.

The quote of solar radiation reflected by canopy (albedo) is calculated with the following linear model described in Uchijima (1976) (eq. 9):

[%]

where b is the angle of solar elevation calculated with classical trigonometric functions.

The quote of solar radiation absorbed by canopy is obtained with the following equation defined by Ross (1981) (eq. 10):

[%]

where the extinction coefficient ke is obtained with the formula (eq. 11):

where a spherical leaf angle distribution is considered and therefore Gomega was initialised to 0.5.

The outgoing long wave radiation RL is obtained with the above described Brunt equation (eq. 6) and the quote intercepted by different layers is estimated with Lambert Beer law modified by Monsi e Saeki (1953), with an extinction coefficient ke = 0.65.

Wind velocity for different canopy layers is calculated with the following exponential equation (Uchijima, 1976) (eq. 12):

[m s-1]

where h is the top of the canopy and a value of 2.2 was adopted for the extinction coefficient h.

ET0 (simulated using the Priestley and Taylor approach) is subdivided in the two terms: the radiation driven (ETm_RadT) and the aerodynamic driven (ETm_aeroT) and ETc is obtained multiplying ET0 for Kc.

The radiation driven ETm_RadT id subdivided among the different layers in proportion with the quote of Rg absorbed; the aerodynamic-driven quote ETm_aeroT is subdivided among layers in proportion with the contribution of each layer to the total wind velocity.

Leaf temperature is estimated with the following equation (eq. 13):

where the physical storage term is neglected (Oke, 1978).

In this equation the H term is expressed in the following way (Bonan, 2002) (eq. 14):

[J m-2 h-1]

where  is the air density, Cp is the thermal capacity of air (1005 J kg-1 °C-1), Tl is the leaf temperature [°C] and rb is the leaf boundary layer resistance, expressed in function of wind velocity u by means of the following equation (eq. 15):

[s m-1]

where a value of 200 was adopted for the coefficient aa and a value of 0.04 m was adopted for the mean leaf dimension.

The balance equation become (eq. 16):

[°C]

where E (mm = kg * m-2) is the transpired water.

Considerations about the mechanistic approach

For the mechanistic model, calibration was carried out by acting only on the empirical parameter cf1 that modulates evaporation from water surface. This solution was adopted on the basis of a sensitivity analysis (results not discussed here).

The parameter cf1 was introduced in equation (4) that assumed the following structure:

[°C]

After calibration the final values adopted for cf1 were 0.6 for LAI <= 3, 0.8 for LAI between 3 and 6 and 1.2 for the following period.

Description of the empirical algorithm

The empirical approach simulates minimum daily water temperature by solving the equation below (eq. 18):

where: TnW (°C) is the minimum water temperature of the day D; TnD-1 (°C) is the minimum air temperature of the day D-1; TnD (°C) is the minimum air temperature of the day D and TnD+1 (°C) is the minimum air temperature of the day D+1. This algorithm reproduces the flooding water smoothing effect on temperatures by means of a Gaussian filter applied to the air temperatures gauged in a standard weather station. Moreover the energy storage effect of water was simulated by adding a constant to the values calculated with the Gaussian filter.

The simulation of daily maximum water temperature is based on the following equations (eq. 19):

where: TxW (°C) is the maximum water temperature of the day D; TxD-1 (°C) is the maximum air temperature of the day D-1; TxD (°C) is the maximum air temperature of the day D; TxD+1 (°C) is the maximum air temperature of the day D+1 and DOY is the day of the year. Also in this case the water smoothing effect on temperatures is simulated by using a Gaussian filter.


Getting started

The project must contain a reference to the DLL. An example for Visual Basic 6 projects is shown below.

The public functions made available in TRIS_COMdll can be explored using the object browser of the programming environment. An example for Visual Basic 6 projects is shown below.

TRIS_COMdll consists in a collection of functions and procedures which accept input data directly as arguments of the function or procedure called and return output trough method calls. For each method implemented, the following steps have to be carried out:

1. Object instancing and procedure calling

Once a particular object and a particular function have been chosen, using them involves two steps:

(i) Creation of a new instance of the object;

(ii) Call of the desired routine, and specification of the required inputs and/or parameters.

Retrieving output variables

The object instanced (see point 1.i) contains also the methods for retrieving the output variables (named GetMyOutputVariableName) of the routine called (see point 1.ii).


Unit Test

The methods contained in the clsUnitTest are shown in the Class Diagram section of this Help.

The main method, UnitTest_TRIScomponent(), call all the other methods involved in unit tests. All the other methods (named with the prefix "UnitTest_" followed by the name of the tested method) for the application of unit tests can be called also separately.

The methods for retrieving unit test results (boolean) are functions named with the prefix "Get" followed by the name of the tested method and by the suffix "OK". If these functions return "true", the Unit Test has been carried out successfully.

The following is an example of Visual Basic 6 code for applying the Unit Tests (to the whole TRIS component and to the methods TRIS(), CalculateDayLenght(), CalculateDayLightTimeFactor()).


Class Diagram

The Class Diagram for the TRIS_COMdll component is shown below. The class clsTRIS contains the main methods for the empirical and mechanistic micrometeorological models, respectively TRISempiric and TRIS. The class clsTRIScanopy contains the main method involved with canopy-related algorithms.

Classes clsMeteo, clsHourlyMeteoGenerator, PMETClass, clsRH, and clsConvert contains methods related to standard meteorological, micrometeorological, and conversion functions.

The class clsUnitTest contains methods for verifying that all the implemented methods are working properly.

Input variable types references for each class are explained in the section Variable Types Reference of this Help.


Input Variables Types References

The variables described in the following table are those needed by the mechanistic model (clsTRIS.TRIS()). The first seven variables in the same table are needed also by the empirical model (clsTRIS.TRISempiric()).


Output Variables Type References

Output variables are returned by methods named with the prefix "Get" followed by the name of the variable. In case the empirical model is used, the variable name is followed by the suffix "E".

The names of the output variables are:

- TmaxWater

- TminWater

- TmaxAPEX

- TminAPEX

and are all Single.


Visual Basic 6 code for using the DLL

The following is an example of Visual Basic 6 code for calling the method implementing the mechanistic model.


About TRIS_COMdll, References, Installation

About TRIS_COMdll

TRIS_COMdll was developed by Roberto Confalonieri, Luigi Mariani, Marcello Donatelli, Marco Acutis, Gabriele Cola.

The programming was made by Roberto Confalonieri.

The DLL is available free of charge for use in non-commercial software and for research purposes.

DISCLAIMER: neither the European Commission, University of Milan, ISCI nor any person acting on behalf of these Institutions are responsible for the use which might be made of this DLL.

We look forward to receiving users' comments.

(version 1.0.1, June 2007)

Developed within the activities of the WARM project:

References

Allen, R.G., Pereira, L.S., Raes, D., Smith, M., 1998. Crop evapotranspiration - Guidelines for computing crop water requirements - FAO Irrigation and drainage paper 56. FAO - Food and Agriculture Organization of the United Nations, Rome (http://www.fao.org/docrep).

Bonan, G., 2002. Ecological climatology, concepts and applications. Cambridge Univ. Press, 678 pp.

Burba, G.G., Verma, S.B., Kim, J., 1999. Surface energy fluxes of Phragmites australis in a prairie wetland. Agricultural and forest meteorology, 94, 31-51.

Confalonieri, R., Mariani, L., Bocchi, S., 2005. Analysis and modelling of water and near water temperatures in flooded rice (Oryza sativa L.). Ecological Modelling, 183, 269-280.

Confalonieri, R., Gusberti, D., Acutis, M., 2006. Comparison of WOFOST, CropSyst and WARM for simulating rice growth (Japonica type – short cycle varieties). Italian Journal of Agrometeorology, 3, 7-16.

Denison, R.F., Loomis, R.S., 1989. An integrative Physiological Model of Alfalfa Growth and Development. Univ. Calif. Div. Agric. Natural Resources Publ. 1926, 73 pp.

Donatelli, M., Campbell, G.S., 1998. A simple model to estimate global solar radiation. Proc. 5th Congress of the European Society for Agronomy, Nitra, Slovakia, II, pp. 133-134.

Geiger, R., 1961. The climate near the ground. Harvard University Press, Cambridge, Mass., 611 pp.

Makin, V.K., 1999. A note on wind speed and sea state dependence of the heat exchange coefficient. Boundary Layer Meteorology, Kluver Group, Vol. 91 no. 1,127-134.

Mc Vicar, T., Jupp, D.L.B., 1999. Estimating one-time-of-day meteorological data from standard daily data as inputs to thermal remote sensing based energy balance models. Agricultural and forest meteorology, 96, 219-238.

Monsi, M., Saeki, T., 1953. Über den Lichtfaktor in den Pflanzegesellschaften und seine Bedeutung für die Stoffproduktion. Jpn J. Bot., 1a, 22-52.

Oke, T.R., 1978. Boundary layer climates. Methuen & Co., London, 370 pp.

Penman, H.L., 1948. Natural evaporation from open water, bare soil and grass. Proceedings of the Royal Society, A193, 120-145.

Ross, J., 1981. The radiation regime and architecture of plant stands. W Junk Publ., The Hague, Netherlands, 391p.

Uchijima, Z., 1976. Microclimate of the rice crop. In: Proceedings of the Symposium on Climate and Rice, IRRI.

Sutton, O.G., 1953. Micrometeorology, McGraw-Hill.

Installation

To run the installation of TRIS_COMdll, launch the file "TRIS_COMdll setup.exe" and follow the instructions suggested by the setup program. The installation allows installing and registering the DLL. All the files will be saved in the default directory ..\WARM\TRIS_COMdll\.