FVS Repository Structure

First-Level Subdirectories

Within the directory organization are a number of subdirectories, which, in turn, contain files and/or additional subdirectories. The subdirectories at the highest level within the codebase will be referred to as first-level subdirectories. The subdirectories within the first-level subdirectories will be referred to as second-level, and so on.

There are many first-level subdirectories. Most were set up to contain source code for a particular part of the FVS model. In this way, related code files are located in the same subdirectory. The subdirectory name is an abbreviated indicator of the part of the model to which its code pertains. For example, the subdirectory named dbs contains source code for the database model. It’s not always practical to keep related source code files in the same subdirectory, but you should make every attempt to maintain this type of logical order when modifying code in your branch.

Several of the first-level subdirectories are discussed below. Some have been grouped for discussion purposes.

common - The first-level subdirectory common contains declarations of variables and arrays used throughout the FVS code as globals. All files in common have filenames in all caps, and filename extensions of .F77. This is in contrast to the Fortran source code files in other subdirectories, which have filenames in all lowercase and extensions of .f. The files in the first-level common subdirectory are universal in that they can be included in the build for any geographic variant executable. There are other common subdirectories within some of the other first-level subdirectories. Those contain declarations of global variables and arrays used in particular variants or model components. Source code files in common subdirectories should be reserved only for global declarations.

base - The base subdirectory contains source code used to build the base model of FVS. The files in base are universal in that there is nothing in their source code that limits their use to a subset of geographic variants. The files could potentially be used to build any variant. If you modify source code in base you should make every attempt to keep it applicable to all variants. If you have to modify a source code file so that it is specific only to a subset of variants, you should move that source code file out of base and into the appropriate variant-specific directory. You should also move the original, unedited file to an appropriate variant-specific directory. Contact an Administrator if you are unsure of the appropriate locations for files. You will need to edit the affected source list files to reflect the new file locations.

Variant-specific subdirectories - Many of the subdirectories have names with the two-letter designation for a geographic variant of FVS. For example, the subdirectory named ie refers to the Inland Empire variant of FVS. Source code contained in the variant-specific subdirectories is used only to build that specific variant or a group of related variants. For information on the FVS variants and their two-letter designations, refer to the FVS website (https://www.fs.usda.gov/fvs/whatis).

Extension subdirectories - A number of the subdirectories contain source code for an FVS extension. Extensions are model segments that are typically optional to include in an executable. For example, many of the variants can be built with extensions that simulate the effects of insects or disease. The Essential FVS document, available from the FVS website (https://www.fs.usda.gov/fvs/documents/guides.shtml), describes the various extensions. For information about the various insect and disease extensions and the variants to which they apply, refer to the Forest Health Protection website (https://www.fs.usda.gov/foresthealth/applied-sciences/fvs-models).

There are a few special subdirectories that do not contain source code, and they are described below.

bin - The bin subdirectory does not contain source code. It contains files used to build executables. The procedure used to build executables is described in the Build Process wiki documents. Developers may need to modify the FVSxx_sourceList.txt files in their branch (where xx is the variant designation), but the files in main should not be updated. When builds are completed, your local bin directory may contain additional subdirectories and files related to the builds, including the executable files. These subdirectories and the files they contain should not be uploaded to the open-fvs repository.

changeNotes - The changeNotes subdirectory does not contain source code. It contains text files describing changes made to the source code. These files may be valuable to developers when trying to determine when particular features were changed in the code. You should not modify the changeNotes subdirectory in main unless an Administrator has given you explicit permission to do so.

tests - The tests subdirectory does not contain source code. It contains subdirectories and files needed to run tests on executables built with modified code. The required testing process is described in the Testing wiki document.

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.

1. Run Initialization, and File Management

   • Primary: MAIN, FILOPN, MYOPEN, GROHED, BLKDAT, GRINIT, SITSET

2. Process Keywords

   • Primary: INITRE
   • Secondary: KEYRDR, KEYWDS, ERRGRO, HABTYP, HBDECD, FORKOD, SPDECD

3. Read Input Stand and Tree Data

   • Primary: INTREE
   • Secondary: DAMCDS SPCTRN

4. Compute Initial Stand Statistics

   • Primary: NOTRE, DENSE, STATS, VOLS
   • Secondary: SETUP

5. Backdate densities / Dub missing data / Compute calibration statistics

   • Primary: CRATET
   • Secondary: DGDRIV, REGENT, CROWN, DUBSCR

6. Control Looping Over Cycles

   • Primary: TREGRO, GRINCR, GRADD

7. Control of event monitor

   • Primary: EVMON

8. Thinnings

   • Primary: CUTS
   • Secondary: CUTSTK

9. Grow Large Trees

   • Primary: DGDRIV, DGF, HTGF, CROWN
   • Secondary: HTCALC CWCALC

10. Grow Small trees

    • Primary: REGENT
    • Secondary: SMHTGF (Some variants)

11. Mortality

    • Primary: MORTS
    • Secondary: SDICAL, VARMRT

12. Regeneration

    • Primary: ESTAB
    • Secondary: REGENT

13. Volume Computation

    • Primary: VOLS
    • Secondary: CFVOL, BFVOL, BEHPRM, CFTOPK, BFTOPK, VARVOL, FORMCL

14. 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