The DEBUG Keyword

Introduction

When programming the FVS model, write statements are incorporated into subroutines to verify calculations. The DEBUG keyword may be used to print these intermediate calculations as they occur during program processing. The information is useful for analyzing problems (bugs) in model simulations and leaning about the program logic calculations. The FVS growth engine is written in the Fortran computer language. Although some programming experience is useful, most output from the DEBUG keyword is descriptive and understandable when viewed in conjunction with the source code which contains extensive documentation of the program logic. The use of the DEBUG keyword, as described in the FVS Keyword Guide (Van Dyck and Smith-Mateja, 2000), is shown below.

DEBUG (print DEBUG output) Variants: All Related keywords: OPEN, NODEBUG

Used to request printing of program calculations as they occur. DO NOT use this keyword unless you have a good reason because a tremendous amount of > > output results.

field 1: Cycle for which full program debug output is requested. If blank or 0, debug output will be printed for all cycles. Default = 0

field 2: If debugs are desired for specific subroutines, a non-zero number is entered and the specific subroutines are listed on the supplemental record. A blank or no entry will result in debugs for all subroutines. Default = blank

field 3: File reference number for DEBUG output file. File reference numbers are a mechanism that FVS uses to keep track of external files. Numbers less than 30 are reserved for files that are currently used by FVS. The default is to send the output to unit 16, which is the main FVS output file. Default = 16. Hint: Sometimes it can be helpful to write the DEBUG output to unit 6 (the screen), especially when FVS is crashing for mysterious reasons. When unit 6 is chosen there is minimal buffering, so the final statement written to the screen before the crash will likely be very close to the failing line/s of code. Thanks to Nick Crookston for this pointer.

Supplemental record:

Specify the name of the subroutine to debug. If you list more than one subroutine, they need to be space delimited.

Reference: Essential FVS: A User’s Guide to the Forest Vegetation Simulator, s. 9.3

See Appendix A in this page for subroutines that may be important in debugging problems in FVS runs. The DEBUG keyword may be configured to generate debug output for all cycles or a single cycle using the options in Field 1. A non-zero positive integer in field 2 is used to request debug output from specific subroutines that are listed in the supplemental record. A zero or blank in field 2 requests debug output from all subroutines. Sometimes debug output is written for a subroutine when debug is turned on for the calling subroutine. When the DEBUG keyword is used to request debug output for all stands in a serial run the NODEBUG keyword may be used to turn debug output off for selected individual stands. It is often useful to view debug information in the main output file (the default file reference number 16 on field 3), because it appears in sequence with the regular model output tables.

Like most computer programs, the FVS source code is organized into subroutines, each responsible for a specific function in the model. As explained in Appendix A, there is a set of base subroutines that are used in all variants and these files are stored in the /base directory. Each FVS variant has a set of variant-specific subroutines, and these are stored in variant-specific directories. The subroutines are given descriptive names such as the name MORTS for the subroutine that manages mortality calculations, and the name VARMRT for the subroutine that calculates the variant-specific mortality. FVS coding practice makes it convenient to study model function because, typically, most subroutines are entirely contained in a file having the same name as the subroutine name. E.g. the MORTS subroutine can be found in the morts.f file and the morts.f and varmrt.f files may be found in the variant-specific directory. There are exceptions to this coding practice, and if a helper subroutine is only called by one subroutine it is usually contained in the same file as the main subroutine.

To interpret debug output one should compare the debug write statements in the FVS source code with the debug output.

The FVS source code is organized in the directory structure shown in Appendix B. A brief description of FVS subroutines may be found in Appendix A.

Example Use of the DEBUG Keyword

As mentioned above, subroutine names are generally descriptive of the calculations that take place in the subroutine. The FVS subroutine that manages thinning is the CUTS subroutine, and it is contained in the base/src/cuts.f file. In the example shown below, the DEBUG keyword is set up for the CUTS subroutine, to write to the main output file for all cycles

DEBUG               0          1         16
CUTS

After running the simulation open the base/src/cuts.f file and the main output file in a text editor, and synchronize the debug write statements in the source code with the output. The following example shows 2 debug write statement in the CUTS routine and the corresponding debug output in the main output file.

Source code from the CUTS routine (the base/src/cuts.f file)

       IF (DEBUG) WRITE (JOSTND,9000)
 9000  FORMAT (/' IN CUTS: VALUES OF PROB (12/LINE):'/)
       IF (DEBUG) WRITE (JOSTND,9010) (PROB(I),I=1,ITRN)
 9010  FORMAT (1X,12F10.4)

Debug output in the main output file.

IN CUTS: VALUES OF PROB (12/LINE):
90.0000    5.5455   17.3582   11.7511   11.4592   19.0787   10.3938    8.1262   30.0000   10.9070   30.0000   30.0000
90.0000   26.1084    7.3339   19.7094    4.5470    7.9577    6.7806   10.1507    6.1728    8.3000   30.0000   30.0000
21.8010   29.3354   16.8362

The first write statement describes the debug output and the second write statement shows the current contents of the PROB array from element 1 to element ITRN. By FVS convention the local variables are defined at the beginning of the subroutine, and global variables are defined in include files that can be found in the fvs/common directory or in the common directories of the individual variants (e.g. fvs/ie/common). Include files have upper case file names and have the .F77 extension. Look at the file fvs/common/ARRAYS.F77 to find the definition of the PROB array, and at the fvs/common/CONTRL.F77 file to find the definition of the ITRN variable. The PROB array contains the current trees-per-acre value of each tree record. One can infer that there are 27 live tree records in the simulation at this point in model processing because ITRN is defined as the current number of tree records in ARRAYS.F77, and 27 elements of the PROB array are shown in the output from the debug write statement.

Debug output is useful for troubleshooting problems in FVS processing and may also be useful for exploring the details of FVS calculations. One of the challenges in interpreting FVS debug output is in understanding the software system well enough to find the routines where the processes of interest are occurring. The organization of the FVS source code can be found in Appendix B, and an overview of FVS subroutines can be found in Appendix A of this document. If one is debugging model problems or exploring the details of model processing these Appendices may be used to find a subroutine for study using the DEBUG keyword.

Troubleshoot Runtime Errors

The FVS growth engine is contained in the FVS??.exe executable file, where the ?? refers to the 2-character variant name (e.g. FVSie.exe). The FVS executable runs in a command prompt window. If traceback information (e.g. subroutine name and line number) is printed to the screen after a model error, then open the source code file identified in the traceback and find the line number for information on why the model run stopped. If there is no useful traceback information, one may try requesting DEBUG output from all subroutines and then examine the DEBUG output near the end of the main output file for variables having unreasonable values or the presence of asterisks. Asterisks in model output text files mean that the output value exceeds the limits of the output edit descriptor, and therefore may not be a reasonable value. Sometimes one may obtain a more complete set of output leading to an error if output is directed to the screen by giving field 3 a value of 6.

Explore Details of Model Processing

To explore the details of FVS processing one may examine the debug output from routines of interest. To study mortality calculations (see number 11 in Appendix A) set up the DEBUG keyword to write output for the MORTS routine. The MORTS routine passes the DEBUG variable to VARMRT, so debug output will be written for both the MORTS and VARMRT routines by requesting debug for just the MORTS routine. The MORTS and VARMRT routines are variant-specific routines (not bolded in Appendix A). Variant specific routines are stored in the variant-specific source code directory (e.g. fvs/cr/src for the Central Rockies (CR) variant). Open the main output file for the run and the MORTS and VARMRT source code files, then synchronize the debug output in the main output file with the write statements in the source code routines.

References

Van Dyck, M.G. and E.E. Smith-Mateja, 2000. Keyword Reference Guide for the Forest Vegetation Simulator, Forest Management Service Center, Forest Service, U.S. Department of Agriculture, Fort Collins, Colorado. https://www.fs.usda.gov/fmsc/ftp/fvs/docs/gtr/keyword.pdf