FVS API

FVS API

Introduction

This document describes the FVS Application Program Interface (API) that provides for running FVS as a shared library.

Note that the fact that FVS is written as a procedural program rather than an object oriented program means that the methods used in the FVS_API are not consistent with an object-oriented paradigm. Specific goals, for example, processing many stands in parallel through time, are achieved differently in FVS than would be accomplished if FVS were object oriented. The design of the API is keyed to this reality.

The design of this API is driven by known and perceived needs and as those change, the API will change. The design was further dictated by the systems used to call it. Currently, there are three systems which are known to be using the API and others may exist. The first is an interface to the R System for Statistical Computing. The second system is based on VB.Net and developed by ESSA by Don Robinson and Sarah Beukema. The third is a system which supports calling FVS from Python. As these efforts progress, it is highly likely that the API will be augmented.

For more information about the interface to R, please visit the FVS Interface Repository. This is a collection of R functions used to run FVS on a wide variety of simulations. These functions also serve to demonstrate how to use the API that is described below. In the future, these R functions may become an R package; for now they documented in the rFVS Wiki page as well as the Interface Repository. For a working example of the interface to VB.Net using Visual Studio 2010, see the FVS-VB.Net branch within this repository. The VB.Net Wiki page describes the implementation of the interface and an annotated version of the working example in the repository.

Basic Idea

FVS can hold one stand in memory at a time. When a shared library is loaded, the state of its memory is not set to reliable initial values; no stand, no run options, and no trees are defined. Using the current API functions, there is only one way to define the initial conditions and that is to read a keyword file as would be done with FVS if it were run as a program rather than as a shared library. FVS keyword commands that cause FVS to read site and tree information are used to setup the simulation.

Specifying the name of the keyword file is done by setting the --keywordfile argument as done the FVS Command Line (there is an API call to set this value without putting it on the command line). The FVS program is then run by calling a single API function which returns when the simulation is over, unless, of course, the program is requested to stop during the simulation. The request to stop is done by setting a stop point and stop year. The program returns when it reaches the designated stop point and then it picks up the calculations where it left off when it is called again. There are several ways to interact with the program between its "return" and when it is called again, each is supported with an API function. Note, this is the basic idea, details are provided below that cover more complicated scenarios.

API Reference

What follows is the definition of subroutines designed to be called by the parent programs. On some operating systems, depending on how the FVS library is built, many routines within FVS, besides those listed below, could be called. It would be easy to destroy the simulation if FVS routines are called out of order. Users are encouraged to take a minimalist approach, yet by all means do take an approach!

Command Line

subroutine fvsSetCmdLine(theCmdLine,lenCL,rtnCode)

Set the command line arguments. When FVS is run as a program, this value is specified on the command line as arguments to the program start (see FVS Command Line for definitions of this string). Values specified using this function take precedence over those set on the actual command line. This function also opens files for input as indicted by the values found and it can result in the FVS return code state to be reset.

Argument	Definition
theCmdLine	input character string defines the command line values.
lenCL	the length of theCmdLine (integer)
rtnCode	current FVS return code (integer)

FVS File Close

subroutine fvsCloseFile(filename,nch)

Close the file if it is opened. This routine will normally not be needed.

Argument	Definition
filename	input character string specifying a file name.
nch	the length of the defined part of filename (integer)

Stop Points

subroutine fvsSetStoppointCodes (spptcd,spptyr)
subroutine fvsGetStoppointCodes (spptcd,spptyr)

Set (or Get) the parameters that control stop/restart while FVS is run as a shared library (also see FVS Command Line for definitions).

Argument	Definition
stptcd	is the stop point code (integer) to be used, see table below for codes
stptyr	is the stop point year (integer) be used: 0 means never stop, -1 means stop at every cycle.

stptcd value	Definition
0	Never stop.
-1	Stop at every stop location.
1	Stop just before the first call to the Event Monitor.
2	Stop just after the first call to the Event Monitor.
3	Stop just before the second call to the Event Monitor.
4	Stop just after the second call to the Event Monitor.
5	Stop after growth and mortality has been computed, but prior to applying them.
6	Stop just before the ESTAB routines are called.
7	Stop just after input is read but before missing values are imputed (tree heights and crown ratios, for example) and model calibration (argument stptyr is ignored).

subroutine fvsGetRestartcode (restartcode)

Returns the current value of the stop/restart code. This is an integer the indicates the point within the FVS sequence of calculations where the program will start when subroutine FVS is called next (also see FVS Command Line). Note that stopping between the simulation of stands in a multi stand simulation is done even when no stop request has been scheduled (that is, subroutine FVS returns between stands even if there are no stop codes specified). Values are as follows:

restartcode value	Definition
1	Stop was done just before the first call to the Event Monitor.
2	Stop was done just after the first call to the Event Monitor.
3	Stop was done just before the second call to the Event Monitor.
4	Stop was done just after the second call to the Event Monitor.
5	Stop was done after growth and mortality has been computed, but prior to applying them.
6	Stop was done just before the ESTAB routines are called.
100	Stop was done after a stand has been simulated but prior to starting a subsequent stand.

Return Code State

subroutine fvsGetRtnCode (rtnCode)
subroutine fvsSetRtnCode (rtnCode)

fvsGetRtnCode simply returns the current value of the return code while fvsSetRtnCode sets it as well. If fvsSetRtnCode is called with a non-zero value, FVS automatically closes all open files and any open databases.

rtnCode is returned with the current return code value in FVS.

rtnCode value	Meaning
-1	indicates that FVS has not been started.
0	indicates that FVS is in good running state.
1	indicates that FVS has detected an error of some kind and should not be used until reset by specifying new input.
2	indicates that FVS has finished processing all the stands; new input can be specified.

FVS

subroutine fvs(rtnCode)

Run FVS up to the next stop point, or to the end of the simulation of a stand. FVS is started by reading the keyword file or by reading a restart file, depending on run options FVSCommandLine FVS Command Line. Note that fvs() always automatically returns at the end of each stand in a multi stand simulation done even when no stop request has been scheduled. For a multi stand simulation, simply call fvs() as often as necessary until the return code is not zero.

The rtnCode is as described for Return Code State.

FVS Dimensions

subroutine fvsDimSizes(ntrees,ncycles,maxtrees,maxspecies,
                       maxplots,maxcycles)

Get dimension information for the version of FVS being run.

Argument	Definition
ntrees	returned number of trees defined in FVS.
ncycles	returned number of cycle defined in FVS.
nplots	returned number of plots inventoried.
maxtrees	returned maximum number of trees FVS can hold.
maxspecies	returned maximum number of species FVS has defined.
maxplots	returned maximum number of sample plots FVS can hold.
maxcycles	returned maximum number of cycles the can be defined in FVS.

FVS Summary Statistics

subroutine fvsSummary(summary,icycle,ncycle,maxrow,maxcol,rtnCode)

Get a snap shot of the simulation of the current stand. (The return code reported here is independent of the general return code.)

Argument	Definition
summary	returned vector of 20 integer words that hold summary statistic attributes.
icycle	requested cycle number corresponding to the summary statistics desired.
ncycle	returned number of cycles defined for the run.
maxrow	returned maximum value of ncycle (and icycle).
maxcol	returned length of summary (20 words).
rtnCode	returned status code for this call where 0=OK, 1=an error.

The 20 returned summary values are as follows (Differences for eastern variants are described in parentheses. See FVS documentation for more details).

summary index	Name	Definition
1	Year	Current year of simulation
2	Age	Current age of stand
3	Tpa	Trees per acre
4	TCuFt	Total cubic volume (Total merchantable volume in eastern variants)
5	MCuFt	Total merchantable volume (Sawtimber volume in eastern variants)
6	BdFt	Total Board Foot Volume
7	RTpa	Removed trees per acre
8	RTCuFt	Removed total cubic volume
9	RMCuFt	Removed merchantable volume
10	RBdFt	Removed board foot volume
11	ATBA	After thin basal area
12	ATCCF	After thin CCF
13	ATTopHt	After thin top height
14	PrdLen	Length of simulation cycle (years)
15	Acc	Accretion in cubic feet/acre/year
16	Mort	Mortality in cubic feet/acre/year
17	SampWt	Stand sampling weight, often the area
18	ForTyp	Forest type code
19	SizeCls	Size class code
20	StkCls	Stocking class code

FVS Species Attributes

subroutine fvsSpeciesAttr(name,nch,action,attr,rtnCode)

Get or set attributes of the species in the simulation. (The return code reported here is independent of the general return code.) When action is "set", the length of the vector must be maxspecies, see Dimensions.

Argument	Definition
name	character string defining the tree attribute being being acted upon; 10 chars maximum
nch	integer number defining the length of name.
action	action requested where, "get" signals that the current values defined in FVS should be returned as a vector in attr and "set" signals that the current values in FVS should be changed to those specified in attr ; 4 chars maximum
attr	a vector of double precision (8-byte floats) of the attribute being processed.
rtnCode	return codes, as follows: 0=OK, 1=name not found, 2=ntrees is greater than the maximum allowed, 3=there were more or fewer trees than ntrees, 4=length of name string was too large or small.

Species attributes that can be returned or set. The units of measure or the period length to which some values apply can depend on when, during the sequence of calculations in FVS, these data are accessed.

name values	Definition
spccf	CCF for each species, recomputed in FVS so setting will likely have no effect
spsdi	SDI maximums for each species
spsiteindx	Species site indices
bfmind	Min diameter related to BFVOLUME keyword
bftopd	Top diameter related to BFVOLUME keyword
bfstmp	Stump height related to BFVOLUME keyword
frmcls	Form class related to BFVOLUME keyword
bfmeth	Volume calculation code related to BFVOLUME keyword (internal FVS variable methb)
mcmind	Min diameter related to VOLUME keyword (internal FVS variable dbhmin)
mctopd	Top diameter related to VOLUME keyword (internal FVS variable topd)
mcstmp	Stump height related to VOLUME keyword (internal FVS variable stmp)
mcmeth	Volume calculation code related to VOLUME keyword (internal FVS variable methc)
baimult	Basal area increment multiplier for large trees (internal FVS variable xdmult)
htgmult	Height growth multiplier for large trees (internal FVS variable xhmult)
mortmult	Mortality rate multiplier (internal FVS variable xmmult)
mortdia1	Lower diameter limit for mortality multiplier (internal FVS variable xmdia1)
mortdia2	Upper diameter limit for mortality multiplier (internal FVS variable xmdia2)
regdmult	Diameter growth mulitplier for regeneration (internal FVS variable xrdmlt)
reghmult	Height growth multiplier for regeneration (internal FVS variable xrhmlt)

FVS Tree Attributes

subroutine fvsTreeAttr(name,nch,action,ntrees,attr,rtnCode)

Get or set attributes of the trees in the simulation. (The return code reported here is independent of the general return code.)

Argument	Definition
name	character string defining the tree attribute being being acted upon; 10 chars maximum
nch	integer number defining the length of name.
action	action requested where, "get" signals that the current values defined in FVS should be returned as a vector in attr and "set" signals that the current values in FVS should be changed to those specified in attr ; 4 chars maximum
ntrees	the length of the attr
attr	a vector of double precision (8-byte floats) of the attribute being processed.
rtnCode	return codes, as follows: 0=OK, 1=name not found, 2=ntrees is greater than the maximum allowed, 3=there were more or fewer trees than ntrees, 4=length of name string was too large or small.

Tree attributes that can be returned or set. The units of measure or the period length to which some values apply can depend on when, during the sequence of calculations in FVS, these data are accessed. Note that while you can set the value of these variables changing some of them will likely cause FVS to fail (species is an example).

name values	Definition
age	Age in years
bdft	Board feet
cratio	Crown radio (percent)
crownwt0	Weight of foliage (pounds)
crownwt1	Weight of 0-.25 inch crown material (pounds)
crownwt2	Weight of .25-1 inch crown material (pounds)
crownwt3	Weight of 1-3 inch crown material (pounds)
crownwt4	Weight of 3-6 inch crown material (pounds)
crownwt5	Weight of 06-12 inch crown material (pounds)
crwdth	Crown width (feet)
dbh	DBH (inches)
defect	Defect coded as 11223344 as described below
dg	Diameter increment
ht	Height (feet)
htg	Height growth (feet)
id	Internal tree identification number
mcuft	Merchantable cubic feet
mgmtcd	Tree value class or management code (1, 2, or 3)
mort	Trees per acre predicted to die.
plot	FVS internal numeric sub plot code
plotsize	Size of plot tree was sampled from
ptbalt	Point basal area in larger trees (sq ft/acre)
special	The value of FVS variable ISPECL used to hold the severity codes when damage code is 54
species	FVS internal numeric species code
tcuft	Total cubic feet
tpa	Trees per acre represented by the tree record.

Defect code	Definition
11	input merchantable cubic volume defect percent
22	input board foot defect percent
33	applied merchantable cubic volume defect percent
44	applied board foot defect percent

FVS Stand Visualizaton (SVS)

subroutine fvsSVSDimSizes(nsvsobjs, ndeadobjs, ncwdobjs, mxsvsobjs, 
                          mxdeadobjs, mxcwdobjs)

Get dimension information for the version of FVS being run.

Argument	Definition
nsvsobjs	returned number of tota objects defined in SVS storage.
ndeadobjs	returned number of dead tree objects defined in SVS storage.
ncwdobjs	returned number of coarse wood objects defined in SVS storage.
mxsvsobjs	returned maximum number of live tree objects SVS can hold.
mxdeadobjs	returned maximum number of dead tree objects SVS can hold.
mxcwdobjs	returned maximum number of coarse wood objects SVS can hold.

subroutine fvsSVSObjData(name,nch,action,nobjs,attr,rtnCode)

Get or set attributes of the SVS attributes in the simulation. (The return code reported here is independent of the general return code.)

Argument	Definition
name	character string defining the tree attribute being being acted upon.
nch	integer number defining the length of name.
action	action requested where, "get" signals that the current values defined in FVS should be returned as a vector in attr and "set" signals that the current values in FVS should be changed to those specified in attr.
nobjs	the length of the attr
attr	a vector of double precision (8-byte floats) of the attribute being processed.
rtnCode	return codes, as follows: 0=OK, 1=name not found, 2=nobjs is greater than the maximum allowed, and 3=there were more or fewer objects than nobjs.

The attributes have different lengths as defined by fvsSVSDimSizes or fvsDimSizes

name value	nobjs value	Definition
objtype	nsvsobjs	Object type code (see below). Note that when the object type code indicates an FVS tree record, use fvsTreeAttr to get or set corresponding attributes.
objindex	nsvsobjs	Index into corresponding state variables depending on objtype.
xloc	nsvsobjs	x Location (feet) of object on the SVS plot.
yloc	nsvsobjs	y Location (feet) of object on the SVS plot.
snagdbh	ndeadobjs	Current dbh (inches) of the snag.
snaglen	ndeadobjs	Current length of a snag record.
snagyear	ndeadobjs	Year the tree died.
snagspp	ndeadobjs	FVS numeric species code.
snagfdir	ndeadobjs	The direction of fall if down, -1 otherwise.
snagstat	ndeadobjs	Status code (see below)
snagwt0	ndeadobjs	Crown weight (pounds) of the foliage at time of death.
snagwt1	ndeadobjs	Crown weight (pounds) of the 0-.25 inch material.
snagwt2	ndeadobjs	Crown weight (pounds) of the .25-1 inch material.
snagwt3	ndeadobjs	Crown weight (pounds) of the 1-5 inch material.
cwddia	ncwdobjs	Diameter (inches) of a chunk of wood (CWD).
cwdlen	ncwdobjs	Length (feet) of CWD object.
cwdpil	ncwdobjs	Piled code, 0=unpiled, 1=piled.
cwddir	ncwdobjs	Direction chunk lying.
cwdwt	ncwdobjs	Weight (pounds).

Object type codes:

objtype value	Definition
0	The slot is open, no corresponding object exists
1	An FVS tree
2	A snag record
3	An FVS tree that is flagged for removal
4	CWD object (exclusive of fallen snags)
5	A snag record that is flagged for removal

Snag status codes:

snagstat value	Definition
0	open slot (no snag)
1	green, hard snag
2	red, hard snag
3	grey, hard snag
4	grey, soft snag
5	black, recently burned, still has crown
6	black, older burned, no crown
90	WWPB mortality, one or less years old (red)
91	WWPB mortality, two years old (dark)
92	WWPB mortality, 3-4 years old (grey)

Fire and Fuels Extension Attributes

subroutine fvsFFEAttrs(name,nch,action,nSpecies,attr,rtnCode)

Get or set FFE species attributes in the simulation. (The return code reported here is independent of the general return code.)

Argument	Definition
name	character string defining the species attribute being being acted upon.
nch	integer number defining the length of name.
action	action requested where, "get" signals that the current values defined in FVS should be returned as a vector in attr and "set" signals that the current values in FVS should be changed to those specified in attr.
nSpecies	the length of the attr
attr	a vector of double precision (8-byte floats) of the attribute being processed.
rtnCode	return codes, as follows: 0=OK, 1=name not found, 2=nSpecies is greater than the maximum allowed, 3=there were more or fewer trees than nSpecies, and 4=length of name string was too large or small.

The following attributes can be accessed:

name value	nSpecies value	Definition
fallyrs0	maxsp	Number of years before all foliage will fall from a recently killed tree.
fallyrs1	maxsp	Number of years before all 0-.25 inch crown material will fall from a recently killed tree.
fallyrs2	maxsp	Number of years before all .25-1 inch crown material will fall from a recently killed tree.
fallyrs3	maxsp	Number of years before all 1-3 inch crown material will fall from a recently killed tree.
fallyrs4	maxsp	Number of years before all 3-6 inch crown material will fall from a recently killed tree.
fallyrs5	maxsp	Number of years before all 6-12 inch crown material will fall from a recently killed tree.

FVS Event Monitor Variables

subroutine fvsEvmonAttr(name,nch,action,attr,rtnCode)

Get or set FVS Event Monitor variables. There are too many variables to list here, see FVS documentation for more details. (The return code reported here is independent of the general return code.)

Argument	Definition
name	character string defining name of the Event Monitor attribute being being acted upon.
nch	integer number defining the length of name.
action	action requested where, "get" signals that the current values defined in FVS should be returned as a vector in attr and "set" signals that the current values in FVS should be changed to those specified in attr.
attr	a single double precision (8-byte float) word of the attribute being processed.
rtnCode	return codes, as follows: 0=OK, 1=name not found.

Add Trees

subroutine fvsAddTrees(in_dbh,in_species,in_ht,in_cratio,
                       in_plot,in_tpa,ntrees,rtnCode)

Add more trees to a current simulation. All values are double precision vectors of length ntrees except as noted below. (The return code reported here is independent of the general return code.)

Argument	Definition
in_dbh	dbh values for the additional trees.
in_species	internal FVS species codes for the additional trees.
in_ht	tree heights for the additional trees.
in_cratio	crown ratios (%) for the additional trees.
in_plot	internal FVS plot indices for the additional trees.
in_tpa	number of trees per acre for the tree being added.
ntrees	a integer value, length of the vectors.
rtnCode	return code, where 0=OK, 1=there was not enough room to store the new trees.

Species Codes

subroutine fvsSpeciesCode(fvs_code,fia_code,plant_code,
                          indx,nchfvs,nchfia,nchplant,rtnCode)

Get the FVS species codes. (The return code reported here is independent of the general return code.)

Argument	Definition
fvs_code	returned FVS species code; 4 chars maximum.
fia_code	returned FIA code; 4 chars maximum
plant_code	returned FIA code; 6 chars maximum
indx	index (integer) of requested code.
nchfvs	returned actual length of fvs_code (integer).
nchfia	returned actual length of fia_code (integer).
nchplant	returned actual length of plant_code (integer).
rtnCode	return code, where 0=OK, 1=indx is out of range.

Define Harvest

subroutine fvsCutTrees(pToCut,nt,rtnCode)

TODO: Not yet implemented

Specify the proportion of each existing tree record FVS should cut. (The return code reported here is independent of the general return code.)

Argument	Definition
pToCut	double precision vector of proportions, one per tree.
ntrees	length of pToCut (integer)
rtnCode	return code, where 0=OK, 1=ntrees is not equal to the number of trees in the model.

Stand Identification

subroutine fvsStandID(sID,sCN,mID,ncsID,ncCN,ncmID)

Get the stand identification codes.

Argument	Definition
sID	returned character string holding the stand identification code (26 characters maximum).
sCN	returned character string holding the database control identification (40 characters maximum).
mID	returned character string holding the management identification code (4 characters maximum).
ncsID	length of defined part of sID (integer)
ncCN	length of the defined part of sCN (integer)
ncmID	length of defined part of mID (integer)

Current Keyword File Name

subroutine fvsGetKeywordFileName(name,mxch,nch)

Get the string that holds the current file name (not NULL terminated).

Argument	Definition
name	returned character string holding the file name.
mxch	the length of the string the calling routine has reserved (integer)
nch	returned length of defined part of name (integer)

Return Error Code

subroutine fvsGetICCode(rtnCode)

Fetch the integer code returned when FVS exits. A value of 0 means that no serious errors occurred. Non-zero values indicate different error states that sometimes make it impossible to continue (error codes: 10=input data; 20=keyword or expression; 30=extension or group activities; 40=scratch file). The maximum error code value is returned, with more specific clues are written to the main output file beginning with "FVS_nn_ WARNING", where nn =(01,...,36).

Argument	Definition
rtnCode	value of FVS return code (integer)

Return Unit Conversion

subroutine fvsUnitConversion(name,nch,rtnCode)

Fetch a unit conversion multiplier.

Argument	Definition
name	character string defining conversion factor desired.
nch	integer number defining the length of name.
rtnCode	return codes, as follows: 0=OK, 1=name not found.

The value of name is case sensitive (must be coded exactly as show here) and can be one of the following:

name value	Definition
CMtoIN	cm to inches
CMtoFT	cm to feet
MtoIN	m to inches
MtoFT	m to feet
KMtoMI	km to miles
M2toFT2	square m to square feet
HAtoACR	hectares to acres
M3toFT3	cubic meters to cubic feet
KGtoLB	kg to pounds (lbs)
TMtoTI	Tonnes metric (1,000 kg) to Tons Imperial (2,000 lbs)
CtoF1	Slope in the Celsius to Fahrenheit conversion
CtoF2	Intercept in the Celsius to Fahrenheit conversion
INtoCM	inches to cm
FTtoCM	feet to cm
INtoM	inches to m
FTtoM	feet to m
MItoKM	miles to km
FT2toM2	square feet to square m
ACRtoHA	acres to hectares
FT3toM3	cubic feet to cubic m
LBtoKG	pounds (lbs) to kg
TItoTM	Tons Imperial (2,000 lbs) to Tonnes metric (1,000 kg)
FtoC1	Slope in the Fahrenheit to Celsius conversion
FtoC2	Intercept in the Fahrenheit to Celsius conversion
BTUtoKJ	BTU to kilojoules
M2pHAtoFT2pACR	square m per hectare to square feet per acre
M3pHAtoFT3pACR	cubic m per hectare
FT2pACRtoM2pHA	square feet per acre to square m per hectare
FT3pACRtoM3pHA	cubic feet per acre to cubic m per hectare

Summary of TODO

Here is a list of TODO items:

1. Finish the fvsCutTrees function (the implementation in subroutine cuts needs to be done).
2. Set up the FVS function so that one can restart from the previous stand (assuming that the stand is stored in a stoppoint file). This would allow for making several projections from a stoppoint year into the future (upto a stoppoint year) for the same stand. This feature would be useful for treatment optimizations. There are two functions in the API that are designed to support the functionality, but they have not yet been tested.
3. Add a --treeDataFile option to the command line.