open-fvs Wiki

The Forest Vegetation Simulator (FVS) forest growth model

Brought to you by: donrobinson, lancedavid, mshettles521, mvandyck

DEBUG Keyword

Authors:

FVS Home Repository Has Moved

Please note, the official FVS repository has recently migrated from Source Forge to GitHub. Please visit us at https://github.com/USDAForestService/ForestVegetationSimulator for the latest in code and wiki updates. This Source Forge repository will no longer be maintained, and is kept here as archival reference only.

THE DEBUG KEYWORD
When programing 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 document 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 in Suppose 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 may be found on code tab of the Source Forge open-fvs web site.

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. When running FVS through Suppose this window may close if the run encounters a numerical error. If this happens any traceback information is lost. To prevent the command prompt window from closing, open a command prompt window and navigate to the working directory. Run the batch file built by Suppose by typing the batch file name (e.g. keyWordFileName.bat) in the command prompt window followed by the enter key. If traceback information (e.g. subroutine name and line number) is printed to the screen after the 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

APPENDIX A: Subroutine Overview
The typical FVS convention requires that file names be the same as subroutine names, and that only one subroutine is contained in a file. See Appendix B for a description of the organization of the FVS directory structure. The purpose of some of the primary FVS growth and mortality subroutines is described below. The bolded subroutines can be found in the base/src source directory. All other subroutines are used in specific variants or in an FVS extension.

Run Initialization, and File Management
Primary: MAIN, FILOPN, MYOPEN, GROHED, BLKDAT, GRINIT, SITSET
Process Keywords
Primary: INITRE
Secondary: KEYRDR, KEYWDS, ERRGRO, HABTYP, HBDECD, FORKOD, SPDECD
Read Input Stand and Tree Data
Primary: INTREE
Secondary: DAMCDS SPCTRN
Compute Initial Stand Statistics
Primary: NOTRE, DENSE, STATS, VOLS
Secondary: SETUP
Backdate densities / Dub missing data / Compute calibration statistics
Primary: CRATET
Secondary: DGDRIV, REGENT, CROWN, DUBSCR
Control Looping Over Cycles
Primary: TREGRO, GRINCR, GRADD
Control of event monitor
Primary: EVMON
Thinnings
Primary: CUTS
Secondary: CUTSTK
Grow Large Trees
Primary: DGDRIV, DGF, HTGF, CROWN
Secondary: HTCALC CWCALC
Grow Small trees
Primary: REGENT
Secondary: SMHTGF (Some variants)
Mortality
Primary: MORTS
Secondary: SDICAL, VARMRT
Regeneration
Primary: ESTAB
Secondary: REGENT
Volume Computation
Primary: VOLS
Secondary: CFVOL, BFVOL, BEHPRM, CFTOPK, BFTOPK, VARVOL, FORMCL
Model Output
Primary: ** SUMOUT, DISPLY, PRTRLS, EXTREE**

Appendix B: Organization of the FVS Source Code
COMMON indicates a directory of include files that contain labeled COMMON blocks. This file directory immediately under the FVS file directory contains base model COMMON blocks used in all variants and COMMON blocks for some of the extensions. The COMMON directory under a variant specific directory (e.g. FVS/AK/COMMON) contains COMMON blocks which are specific to that variant.

SRC indicates a file directory containing FORTRAN source code. This file directory immediately under the base file directory (i.e. BASE/SRC) contains base model code used in all variants. This file directory under a variant specific directory (e.g. FVS/AK/SRC) contains source code that is variant specific to the extent that it is not used in all variants but may be used in more than one variant.

All files used in an FVS executable are listed in the fvs\bin\FVS??_sourceList.txt files, where ?? refers to the 2-character abbreviation for the FVS variant. E.g. the source list file for the Inland Empire variant (IE) is named fvs\bin\FVSie_sourceList.txt. Refer to these file lists to make sure that a subroutine is used in the variant of interest.

Directory Description

fvs\
├───acd Acadian variant
│ ├───common
│ └───src
├───ak Southeast Alaska / Coastal British Columbia variant
│ ├───common
│ └───src
├───base Base model, routines used in all variants
│ ├───baseDocument
│ └───src
├───bc British Columbia variant
├───bgc BioGeoChemical extension
│ └───src
├───bin
├───bm Blue Mountains variant
│ ├───common
│ └───src
├───ca Inland California / Southern Cascades variant
│ ├───common
│ └───src
├───changeNotes
├───ci Central Idaho variant
│ ├───common
│ └───src
├───clim Climate Effects extension
│ ├───base
│ └───bc
├───common
├───covr Cover (Canopy and Shrubs) extension
│ └───src
├───cr Central Rockies extension
│ ├───common
│ └───src
├───cs Central States variant
│ ├───common
│ └───src
├───dbs Database extension
│ └───src
├───dfb Douglas-fir Beetle Impact extension
│ ├───common
│ └───src
├───dftm Douglas-fir Tussock Moth Outbreak extension
│ └───src
├───ec East Cascades variant
│ ├───common
│ └───src
├───econ Economics extension
│ └───src
├───em Eastern Montana extension
│ ├───common
│ └───src
├───estb Full Regeneration Establishment Model extension
│ └───src
├───fire Fire and Fuels extension
│ ├───ak Fire-related AK variant specific
│ │ └───src
│ ├───base Fire Base
│ │ ├───common
│ │ └───src
│ ├───bc Fire-related BC variant specific
│ │ └───src
│ ├───bm Fire-related BM variant specific
│ │ └───src
│ ├───ca Fire-related CA variant specific
│ │ └───src
│ ├───clim
│ │ └───base Fire-related Climate extension specific
│ │ └───bc Fire-related Climate / BC variant specific
│ ├───ci Fire-related CI variant specific
│ │ └───src
│ ├───cr Fire-related CR variant specific
│ │ └───src
│ ├───cs Fire-related CS variant specific
│ │ └───src
│ ├───ec Fire-related EC variant specific
│ │ └───src
│ ├───em Fire-related EM variant specific
│ │ └───src
│ ├───fireDocument
│ ├───fofem First-Order Fire Effects Model
│ │ └───src
│ ├───ie Fire-related IE variant specific
│ │ └───src
│ ├───ls Fire-related LS variant specific
│ │ └───src
│ ├───nc Fire-related NC variant specific
│ │ └───src
│ ├───ne Fire-related NE variant specific
│ │ └───src
│ ├───ni Fire-related NI variant specific
│ │ └───src
│ ├───pn Fire-related PN variant specific
│ │ └───src
│ ├───sn Fire-related SN variant specific
│ │ └───src
│ ├───so Fire-related SO variant specific
│ │ └───src
│ ├───tt Fire-related TT variant specific
│ │ └───src
│ ├───ut Fire-related UT variant specific
│ │ └───src
│ ├───wc Fire-related WC variant specific
│ │ └───src
│ └───ws Fire-related WS variant specific
│ └───src
├───ie Inland Empire variant
│ ├───common
│ └───src
├───kt Kootenai/Kaniksu/Tally Lake variant
│ ├───common
│ └───src
├───lpmpb Lodgepole Pine Mountain Pine Beetle Impact Ext.
│ └───src
├───ls Lake States variant
│ ├───common
│ └───src
├───metric Metric Input/Output
│ ├───ak Metric-related AK variant specific
│ │ └───src
│ ├───base Metric-related Base
│ │ └───src
│ ├───clim Metric-related Climate extension specific
│ │ └───src
│ ├───cr Metric-related CR variant specific
│ │ └───src
│ ├───dbs Metric-related Database extension specific
│ │ └───src
│ ├───dfb Metric-related Douglas-fir Beetle Imp. Ext.specific
│ │ └───src
│ ├───estb Metric-related Full Regen. Estab Model specific
│ │ └───src
│ ├───fire Metric-related Fire and Fuels extension specific
│ │ ├───base
│ │ │ └───src
│ │ └───cr
│ ├───ls Metric-related LS variant specific
│ │ └───src
│ ├───mistoe Metric-related Dwarf Mistletoe Impact Ext. specific
│ │ └───src
│ ├───ne Metric-related NE variant specific
│ │ └───src
│ ├───newmist Metric-related New Dwarf Mistletoe Ext.specific
│ │ └───src
│ ├───ni Metric-related NI variant specific
│ │ └───src
│ ├───ppbase Metric-related Parallel Processing Ext. Specific
│ │ └───src
│ ├───rd Metric-related Wstern Root Disease Ext. specific
│ │ └───src
│ ├───so Metric-related SO variant specific
│ │ └───src
│ ├───strp Metric-related Partial Regen. Estb. Ext. specific
│ │ └───src
│ ├───ut Metric-related UT variant specific
│ │ └───src
│ ├───wc Metric-related WC variant specific
│ │ └───src
│ └───wwpb Metric-related West-wide Pine Beetle Ext. specific
│ └───src
├───mistoe Dwarf Mistletoe Impact extension
│ └───src
├───nc Northern California (Klamath Mountains) variant
│ ├───common
│ └───src
├───ne Northeast variant
│ ├───common
│ └───src
├───newmist New (3D) Dwarf Mistletoe Impact extension
│ └───src
├───ni Northern Idaho variant
│ └───src
├───on Ontario variant
│ └───src
├───oz Ozark variant
│ └───src
├───pg Mass storage routines
│ └───src
├───pn Pacific Northwest Coast variant
│ ├───common
│ └───src
├───rd Western Root Disease Impact extension
│ └───src
├───sn Southern variant
│ ├───common
│ └───src
├───so South Central Oregon / Northeast California variant
│ ├───common
│ └───src
├───strp Partial Regeneration Establishment Model extension
│ └───src
├───tests Model verification testing
│ ├───APIviaR
│ ├───FVSak
│ ├───FVSbcc
│ ├───FVSbmc
│ ├───FVScac
│ ├───FVScic
│ ├───FVScrc
│ ├───FVScs
│ ├───FVSecc
│ ├───FVSemc
│ ├───FVSiec
│ │ └───econ
│ ├───FVSktc
│ ├───FVSls
│ ├───FVSncc
│ ├───FVSne
│ ├───FVSpnc
│ ├───FVSsn
│ ├───FVSsoc
│ ├───FVSttc
│ ├───FVSutc
│ ├───FVSwcc
│ ├───FVSwsc
│ ├───ODBC
│ │ ├───access
│ │ ├───conn_strings
│ │ └───sqlite
│ └───testSetFromFMSC
│ │ └───sqlite
│ └───VolTest
├───tt Tetons variant
│ ├───common
│ └───src
├───ut Utah variant
│ ├───common
│ └───src
├───volume National Cruise System
│ └───src
├───wc West Cascades variant
│ ├───common
│ └───src
├───wpbr White Pine Blister Rust extension
│ └───src
├───ws Westside Sierra Nevada variant
│ ├───common
│ └───src
├───wsbwe Western Spruce Budworm extension
│ └───src
└───wwpb West-wide Pine Beetle extension
└───src