File: ReadMe.2nd 1/24/2000; revised 1/27/2000 -- Charles R. Meyer This file contains some explanations of how CLIGEN works, and the results of some tests on the mathematical and computational stability of the code. OVERVIEW: Cligen generates its outputs from monthly averages, monthly standard deviations, and in the case of precipitation, monthly skewness of the historic period of record for the given site. (Most of the equations that perform this work are in subroutine CLGEN (starting in line 454 in CLIGEN.FOR).) The pseudo random number generator function (RANDN) apparently exists to remedy documented deficiencies in the FORTRAN-77 random number. Function DSTN1 uses two numbers from RANDN to generate a single random representative number from the Standard Normal Distribution (which has mean=0 and std.dev.=1). (This number can be either positive or negative.) The product of this number and the monthly standard deviations is added to the monthly mean to produce a daily value for a non-skewed normal distribution. Other distributions are a bit more complicated. Daily maximum temperature, minimum temperature, precipitation, and radiation are generated as separate independent distributions. Maximum temperature is assumed to follow a Normal distribution. Minimum temperature is generated the same way as maximum temperature, except that it is range-checked to ensure that it is less than maximum temperature for the day. Precipitation is generated using the monthly skewness and a Pearson type-3 equation to generate the skewness term, which is multiplied by the monthly standard deviation, and added to the monthly mean. To generate solar radiation, a random standard normal deviate is produced and multiplied by the monthly std. dev. (as with max. temp.). This value is then multiplied by 1/4 the difference between the monthly mean and the theoretical maximum, and added to the monthly mean. TESTS AND GENERAL OBSERVATIONS: CLIGEN was run for four climatically diverse sites in the U. S., for periods of 1 to 1000 years. (The sites were Moscow, ID, College Station, TX, Indianapolis, IN, and Tucson, AZ.) The monthly means of min. temp., max. temp., precip., and radiation outputs were subjected to confidence interval tests. (See FN 1.) - At all sites for all parameters, the mean for one or more months was out of range at the 90 percent level of probability or higher. The generated random standard normal deviates produced by DSTN1 followed the same pattern for the same months, for a given parameter. It seems likely that the fault lies with the F77 random number generator which feeds DSTN1. - CLIGEN was tested both with, and without linear interpolation of means, std. dev. and skewness. In all cases it converged on its final mean monthly value for all parameters within 28 years. KNOWN CAVEATS, BUGS, AND PROBLEMS: - In subroutine DSTG, there is a precision problem which caused numeric underflows in variables XX and FU during runs of 20 years and longer. This loss of information can lead to unpredictable results. The problem can be corrected by altering the source code so those variables are declared to be "double precision", rather than "real". - There is a range check to ensure that Daily Minimum Temperature is less than Daily Maximum Temperature. The crude way this is implemented alters the distribution of Min Temp, ensuring that the mean of the output values will be lower than the mean values they were generated from. - There is a range check for Solar Radiation which can alter its distribution. With radiation there is a "theoretical maximum" (RMX) for the site. If RMX is less than the monthly average, RMX is set to the monthly average. If the generated value is more than the theoretical maximum, it is set to 90 percent of the theoretical maximum. If it less than zero, it is set to 5 percent of the theoretical maximum. (Note that these checks alter the resulting distribution so that the output can not be guaranteed to match the input numbers it was generated from.) - The daily value for the first day of the month is generated from the same values as those for the last day of that same month. However, the value for one day earlier (last day of the previous month) is generated from different values - those for the previous month. This troubles some people. However, the standard deviation for a month is generally several times the difference between the means of adjacent months. So, in practice, it may not make as much difference as one would guess. Testing several forms of interpolation is in the plans. If used, they will probably be incorporated as user- selectable runtime options. - Except as noted for Min Temp, the values for Max Temp, Min Temp, Solar Radiation, and Precipitation are all generated as independent distributions in CLIGEN. Some people note that these parameters are not independent in the physical world. For example, the temperature and radiation go down on a rainy day. We do not currently know how much practical difference this makes. ---------------------< Footnotes: >-------------------- FN 1 -- The Central Limit Theorem ensures that the _means_ of samples taken from *ANY* type of distribution follow a normal distribution. Ie, the original distribution does NOT have to be a normal distribution. This makes confidence intervals on the mean appropriate without requiring knowledge about the type of underlying distribution.