Error handling

Exercise objective:

       ·  Simple (format) error handling and trouble shooting. 

       ·  Effects of improbable or erroneous values in data files.

Suggested reading:

Chapter 7, first page (page 149) of the book, ORYZA2000: modelling lowland rice.

In the following exercises, we will learn to recognize and correct some frequently encountered errors in the data files. The ORYZA2000 model is programmed in the FORTRAN language, which has some particular demands on the format of model input data. Users that are not familiar with FORTRAN may easily make mistakes that may seem small, but may have large consequences for model performance. Though care has been taken in ORYZA2000 to produce intelligible error messages, they often seem cryptic to the beginning student in modelling. The following exercises are designed to study some frequently encountered mistakes in data files.

Some exercises also focus on mistakes in the format of parameter values in input data files that resulted in error messages by ORYZA2000. Another category of mistakes consists of inaccuracies or mistakes in the actual values of the parameters. Quite often, ORYZA2000 cannot recognize such mistakes and produces results that at first sight seem entirely plausible. Such mistakes may go unnoticed and are among the most frequent undetected errors that both novices and veterans in modelling can make! Under certain conditions, however, the mistake may lead to completely erroneous calculations and the model ‘crashes’ during simulation. Although frustrating at first, the crash of a model is in fact a blessing, since it indicates that something is definitely wrong. Sometimes, the ‘crashing’ of a model is the result of (scientific) mistakes in the equations or programming mistakes in the software, that require the attention of an expert to rectify. Mostly, however, the crashing of a model is caused by erroneous data values in the input data files. Finding these mistakes can be cumbersome and very time-consuming to the novice in modelling. But with increasing experience, such mistakes are more readily recognized. The more familiar one becomes with the actual contents on the model, the easier it becomes to find and correct mistakes.

Exercise:

The FORTRAN language distinguishes three ‘types’ of data: two numerical types, and one character type. The numerical types are ‘real’ and ‘integer’. An integer data type is a number defined without a dot, e.g., ‘1’ or ‘100’. A real data type always has a dot with or without following numbers, e.g., 1. or 100.0. Each numerical variable or parameter in a FORTRAN program is defined as belonging to the real or the integer type. If a parameter is defined as a real, then the numerical value in the input file should appear as real.

Ex-I.29. Check that in the CONTROL.DAT file the experimental data file is still EXPLORE.DAT. Open EXPLORE.DAT and locate the parameter IYEAR. Note that this parameter is a numerical of the integer type. Insert a dot (.) behind the value (i.e., 1992.), run the model and study the results. The error message informs us that the model wants to read the value of the integer variable IYEAR from the file EXPLORE.DAT, but that this value is given as real in the data file. Reset the value of IYEAR to integer and run the model. Then locate the variable STTIME and note that it is defined as real. Remove the dot (i.e., 4), run the model and study the error message. Reset STTIME to a real number and run the model.

A variable defined as character has a ‘value’ that consists of a string of letters. In the data files, such a string should be written between inverted commas. For example, the variable RUNMODE, that defines whether ORYZA2000 is run to simulate a particular experiment or to perform an open exploration, is defined as a character. In ORYZA2000, there are well-defined values (‘words’) that a character variable can assume. These are given as options in the input data files.

Ex-I.30. Open EXPLORE.DAT and locate the parameter RUNMODE. This parameter can assume only two values, either 'EXPERIMENT' or 'EXPLORATION'. Note that in the file, RUNMODE = 'EXPERIMENT'. Remove one of the inverted commas (e.g., write RUNMODE = EXPERIMENT', run the model and recognize the error message. Return to the EXPLORE.DAT file, restore the inverted comma, but make a spelling mistake in the word experiment, e.g. RUNMODE = 'EXPERIMENT'. Run the model and recognize the error message, which is less explicit in nature than the previous one. Correct the spelling mistake and run the model.

Each parameter in a data file can only appear once. If the parameter is defined a second time, an error message follows. Also, an error message is produced when a parameter value is not found at all.

Ex-I.31. In EXPLORE.DAT, remove the * in front of *RUNMODE = 'EXPLORATION', so that RUNMODE is now defined twice. Run the model and recognize the error message. Now reset the * and also insert an * in front of the line RUNMODE = 'EXPERIMENT'. Run the model and recognize the error message. Restore the file, so that the mode of running is back to experiment.

Two special characters are used in the data files to identify informative text, the asterisk (*) and the exclamation mark (!). The ‘*’ can be used only at the beginning of a line, whereas the ‘!’ can be used at any position in a line. All text that appears in a line following an ‘*’ or an ‘!’ is ignored by the model. If there is text that is not preceded by an ‘*’ or a ‘!’, then ORYZA2000 reads this text as part of the parameter value and generates an error message.

Ex-I.32. In EXPLORE.DAT, recognize the informative text explaining the value of the parameter RUNMODE:  RUNMODE = 'EXPERIMENT'       ! ORYZA simulates an experiment.

Remove the ‘!’ in this line, run the model and recognize the error message. Note that the error message is not as clear as the previous ones, and that it covers two variables: RUNMODE and the subsequent variable in the data file, WATBAL. The removal of the ‘!’ basically mixes the value of the parameter RUNMODE with the informative text and the parameter WATBAL. Restore the ‘!’ and run the model.

Some parameters are defined as an array and their values consist of a line of values, or of tables with one, two or more columns with values. Each value is usually separated by a comma, except for the last value that represents the end of the ‘array’.

Ex-I.33. In CONTROL.DAT, change the experimental data file to EXPERIMENT.DAT. Run the model and make a graph of simulated (LAI) and observed leaf area index (LAI_OBS) versus time to verify that the model has indeed used the correct experiment data file. Go to Section 8 of the file EXPERIMENT.DAT and study the structure of the data of the variable LAI_OBS (observed leaf area index). All values are numericals of the real type and successive values are separated by commas. Insert a comma at the end of the last line, run the model and examine the results. Note that the error message in this case indicates a mistake in the parameter LAI_FRC; ORYZA2000 tries to read the word LAI_FRC as another value of the variable LAI_OBS, since the last line ends with a comma, indicating that another value is still to come. Remove the comma again on the last line, change one of the real values ‘1992.’ to an integer ‘1992’ by removing the dot, run the model and recognize the error message. Correct the mistake and run the model. Locate next the parameter EMD, insert a comma behind the value 4 (e.g., 4,) and run the model. Again, we notice that the error points to the variable following EMD, which is EMYR, since ORYZA2000 expects another value for EMD following the ‘4,’.

A special error warning is produced when mistakes are made in the names of input data files in the control file.

Ex-I.34. Open CONTROL.DAT, and make an error in the spelling of the name of the experimental data file, e.g., EXPERIMENT.DT. Run the model and recognize the error message. Correct the error, but now make a mistake in the spelling of the directory path indicating where the experimental data file should be located, e.g. 'C:\COUSE\NAVIGATE\EXPERIMENT.DAT' instead of 'C:\COURSE\NAVIGATE\EXPERIMENT.DAT'. Run the model and recognize the error message. Note the similarity in the error message to the previous one: ORYZA2000 does not recognize whether the mistake is made in the name of the file or in the directory path to the file!

Different errors may occur in the same data file or in a number of data files at the same time. The following exercise asks you to identify a number of different errors in the same data file.

Ex-I.35. Open CONTROL.DAT, and change the name of the experimental data file into ERROR.DAT. Find and correct the five errors in this file. When all errors have been corrected, the file OP.DAT should produce the same results as in column Sim1 of Table I.2. For comparison, the data file EXPLORE.DAT that is without errors is given in Appendix 3, and the data file ERROR.DAT in Appendix 4.

View ANSWERS from the Tutorial_answer_sheet.pdf file. 

The next exercise focuses on the relationship between start of simulation and start of the growing season as defined by emergence of the crop.

Ex-I.37. Verify that in CONTROL.DAT the experimental data file is EXPERIMENT.DAT. Verify that the start time of simulation is day 4 (STTIME) of the year 1992 (IYEAR), and that the emergence of the crop in the seedbed is day 4 (EMD) of year 1992 (EMYR). Run the model and fill out the column Sim1 of Table I.3; check that the simulated output is the same as in the column ‘original’ of Table I.3. Make a graph of the simulated and observed leaf area index versus time. Change the value for emergence day into 2, run the model and recognize the error message. Oryza2000 automatically recognized that the start time of the model STTIME was 2 days after the supplied emergence date EMD so that the simulation could not be carried out. Now, restore the emergence date back to 4, change the year of emergence to 1991, and run the model. 

Q: What happens? 

A: This time, there was no “automatic check” by ORYZA2000 that the supplied emergence year was 1 year earlier than the start year IYEAR of the model. Therefore, ORYZA2000 kept running through consecutive weather files after IYEAR (1992) to find the file for EMYR (that was set to 1991). After 1993, it stopped running because there was no consecutive weather data file anymore.

The following exercises illustrate mistakes in a data value that go ‘unrecognized’ by ORYZA2000.

Ex-I.38. Put EMYR back from 1991 to 1992 in EXPERIMENT.DAT and change the value for the seedbed duration (SBDUR) from 12 to –12 days (which is an ‘impossible’ value). Run the model and fill out column Sim2 of Table I.3. Note that the simulated values of weight of grains and of total biomass are plausible. Make a graph of simulated and observed leaf area index versus time, and compare that to the one made in the previous exercise: now we can see the difference! In ORYZA2000, the simulated crop is being transplanted when the number of days since emergence of the crop in the seedbed exactly equals the duration in the seedbed (SBDUR) defined by the user. When SBDUR is negative, this criterion is never satisfied and the crop is never transplanted. Check the values of CROPSTA in the output data file RES.DAT or Run_0! For a description of the calculation of CROPSTA in ORYZA2000, see pages 15-16 of the book “ORYZA2000: modelling lowland rice”.

Ex-I.39. You are welcome to take a break...

Ex-I.40. In EXPERIMENT.DAT, reset the value for the seedbed duration (SBDUR) from -12 to 12 days. Change the value of number of plants per hill (NPLH ) from 5 to –5 (again, an ‘impossible’ value). Run the model and examine the output. In this case, the model ‘crashes’. At transplanting, the crop is being diluted to a negative biomass, which leads to an error in the Carbon Balance check and subsequent discontinuation of the simulation. The error message generated is only helpful in the sense that it indicates that ‘something goes wrong’ in the simulation shortly after transplanting.

Ex-I.41. In EXPERIMENT.DAT, reset the value for the number of plants per hill (NPLH ) from –5 to 5. Change the value of the initial leaf area per plant (LAPE) from 0.0001 to 0.0000 (this means that at emergence, leaf area per plant is set to zero). Run the model and examine the output. In this case, the model ‘crashes’ again, this time on a cryptic ‘error: floating invalid’. This error message is hardly helpful in identifying the cause of the crash! What to do? One possible course of action is to interrupt the simulation, e.g. by setting FINTIM=80., and check the output! The explanation in this example is that with an initial leaf area at emergence of exactly zero, there is no light interception and hence no photosynthesis as a basis for growth.

Table I.3

View ANSWERS from the Tutorial_answer_sheet.pdf file.