Conference PaperPDF Available

Linking FVS and TELSA via the API

Authors:
  • ESSA Technologies Ltd.

Abstract and Figures

The Forest Vegetation Simulator (FVS) Application Program Interface (API) was created to allow developers to use all variants of FVS in conjunction with other simulation tools. As described in the open-fvs wiki (https://sourceforge.net/p/open-fvs/wiki), the development environment and source code were modified to create a smaller executable program linked to a set of Dynamically Linked Libraries (DLLs). This architectural change allows FVS to be run either as a “classic” command-line simulation or as an embedded simulation component controlled by other supervisory software.
Content may be subject to copyright.
34 Proceedings of the 2017 Forest Vegetation Simulator (FVS) e-Conference
Citation for proceedings: Keyser, Chad E.; Keyser, Tara L., eds. 2017. Proceedings of the 2017 Forest Vegetation Simulator (FVS) e-Conference.
e-Gen. Tech. Rep. SRS-224. Asheville, NC: U.S. Department of Agriculture Forest Service, Southern Research Station. 200 p.
EXTENDED ABSTRACT
Linking FVS and TELSA via the API
Donald C.E. Robinson and Sarah J. Beukema1
The Forest Vegetation Simulator (FVS) Application
Program Interface (API) was created to allow
developers to use all variants of FVS in conjunction
with other simulation tools. As described in the
open-fvs wiki (Robinson 2015a), the development
environment and source code were modied to
create a smaller executable program linked to
a set of Dynamically Linked Libraries (DLLs).
This architectural change allows FVS to be run
either as a “classic” command-line simulation or
as an embedded simulation component controlled
by other supervisory software. At the time the
architecture was changed, the development
environment was enhanced so that 32- and 64-bit
versions of FVS could be compiled for operating
systems running Unix-alike or Windows using
a single open-source software building system
(cmake; https://cmake.org/overview/) that supports
multiple operating systems and compiling tools.
With cmake, a Unix-alike FVS executable and
shared object libraries are built using standard
Unix software (Robinson 2015b), while Windows
executables and DLLs are built with either MinGW
(Robinson 2015c) software or Visual Studio 2010
with Intel Fortran (Robinson 2015d). Outputs from
FVS builds made with cmake are the same across
platforms as well as being identical to outputs from
FVS executables (which do not make use of DLLs)
released by the U.S. Department of Agriculture
Forest Service Forest Management Service Center.
To date the API has been incorporated into
applications written in VB.Net, R, and Python.
Critically, the API adds the ability to repeatedly
stop and start FVS (Crookston 2016), allowing
other software to take overall supervisory control,
possibly modifying FVS internal variables in the
process. In this way, dynamic changes can be
made on-the-y, including modications to the
calculation of growth, regeneration and mortality, as
well as harvest and silvicultural scheduling. When
used in a landscape context, it is also possible to
apply spatially based management to collections
of stands or to develop spatially based disturbance
models such as multi-stand re or epidemic insect
outbreaks. Previously, spatially explicit insect
outbreak models such as the Westwide Pine Beetle
Model (Beukema and others 1997) could only be
developed through complex custom programming
using the Parallel Processing Extension (Crookston
and Stage 1993), which is no longer maintained.
Using the API, we linked FVS to TELSA, a state-
transition landscape simulation model written in
C++ (Kurz and others 2000). In the linked system,
TELSA is the supervisory model that provides a
treelist and site information to FVS, which then
grows the stand in each landscape polygon each
year. FVS passes back to TELSA information such
as stand volume that can be used by TELSA to
schedule harvesting. TELSA also simulates natural
disturbances and initiates regeneration and may pass
changed treelists back to the FVS program.
The linked TELSA-FVS system places the FVS
API behind a Microsoft VB.NET software layer
(g. 1). Although we could have communicated
directly with FVS, we chose to develop this
intermediate .NET layer, allowing developers to
use any .NET language (C++ in the case of TELSA)
to communicate with FVS using a common set of
Visual Basic methods, including the capability of
mixing metric and imperial units (Robinson 2015e).
There is no need to master mixed language calling
conventions.
As we developed and tested the TELSA-FVS
system it was important to carefully consider and
dene the roles played by the supervisory program
1Donald C.E. Robinson, Sr. Systems Ecologist, ESSA Technologies Ltd., 600 – 2695 Granville St., Vancouver, B.C., Canada. V6H 3H4; Sarah J.
Beukema, Sr. Systems Ecologist, ESSA Technologies Ltd., 600 – 2695 Granville St., Vancouver, B.C. Canada V6H 3H4.
Development of Extensions, Post Processors, and Links to Other Models 35
and FVS. This included the following decision
points:
Is TELSA or FVS used to model mortality?
Which model is used to model regeneration
establishment?
What tree and site information does the
supervisory program need to provide to FVS?
What FVS output does the supervisory program
need to capture?
What are the timesteps of the supervisory model
and FVS model?
What is the frequency for calling FVS?
Once these roles were claried we were able to
customize TELSA and link it with FVS, testing
landscapes of up to 180,000 stands. We were
interested in knowing how runtimes for TELSA-
FVS compared with TELSA alone, varying the size
of the landscape and the simulation complexity. We
found that runtimes are controlled by factors that
include the size of the landscape, the complexity
of the spatial management and disturbance being
simulated and le I/O. Linking TELSA with FVS
increases runtime signicantly for small landscapes
due to the very fast performance of TELSA on
these landscapes; is about the same for mid-size
landscapes and is about twice as costly for very
large landscapes due to le I/O (table 1).
When spatial interactions are simulated, FVS is
run with the stop and restart capability of the API.
In this instance FVS automatically creates two
temporary les to hold all model-state information,
storing information on the user’s computer when
a stand simulation is paused, reloading it when
the simulation is restarted. In the process of
creating the TELSA-FVS simulation landscapes
we discovered that it was necessary to restrict the
number of FVS stands stored in these temporary
les, using a batch processing approach to group
the FVS simulations managed by TELSA. In
particular, we found that when many stands are
stored, the internal index position of FVS variables
(an integer) stored within the temporary les can
exceed the computer’s ability to store large integers,
producing unpredictable outputs and crashes. With
further study it may be possible to work around
this limit. But as an interim solution we found that
creating batches of 5,000 FVS stands, which we
implemented in the API, was sufcient to overcome
the problem. The upper limit on the number of
stands will likely vary with the complexity of the
FVS model run (more complex runs store more
model-state information), and we recommend that
Figure 1—TELSA and FVS communicate through an intermediate .NET
layer which simplies the need to master mixed language programming.
Table 1—TELSA-FVS runtimes
Scenario Stands TELSA TELSA-FVS Runtime Ratio
Management only 900 17 31 1.8
9,000 916 984 1.1
90,000 738 — —
Disturbance + Management 900 5 19 3.7
9,000 401 469 1.2
90,000 445 930 2.1
Runtime (minutes) for two example landscapes. Blank cells (—) were not simulated.
36 Proceedings of the 2017 Forest Vegetation Simulator (FVS) e-Conference
various batch sizes be tested during application
development. Although we did not test different
storage media, we expect that intermediate results
stored on solid-state storage will execute much
faster compared to classic spinning hard drive
media.
As a nal consideration we note that FVS is limited
to 40 simulation timesteps, and this limit may
introduce tradeoffs in the temporal extent of the
TELSA simulations. For example, if the combined
models both use an annual timestep, the overall
extent of the simulation will be 40 years. If the
supervisory model can be congured to call FVS
every 5 years, the overall extent of the simulation
may be up to 200 years.
LITERATURE CITED
Beukema, S.J.; Greenough, J.A.; Robinson, D.C.E. 1997.
The Westwide pine beetle model: a spatially-explicit
contagion model. In: Teck, R.; Moeur, M.; Adams,
J, comps. Proceedings: Forest Vegetation Simulator
conference. Gen Tech. Rep. INT-GTR-373. Ogden,
UT: U.S. Department of Agriculture Forest Service,
Intermountain Research Station: 126-130.
Crookston, N.L. 2016. FVS API. https://sourceforge.net/p/
open-fvs/wiki/FVS_API/. [Date accessed: 16-May-2017].
Crookston, N.L.; Stage, A.R. 1991. User’s guide to the
Parallel Processing Extension of the Prognosis model.
Gen. Tech. Rep. INT-GTR-281. Ogden, UT: U.S.
Department of Agriculture Forest Service, Intermountain
Research Station. 88 p.
Kurz, W.A.; Beukema, S.J.; Klenner, W. 2000. TELSA:
the Tool for Exploratory Landscape Scenario Analyses.
Computers and Electronics in Agriculture. 27: 227-242.
Robinson, D.C.E. 2015a. Performance Improvement
Project. https://sourceforge.net/p/open-fvs/wiki/
PerformanceImprovement/. [Date accessed:
16-May-2017].
Robinson, D.C.E. 2015b. The Build Process in Unix.
https://sourceforge.net/p/open-fvs/wiki/BuildProcess_
UnixAlike/. [Date accessed: 16-May-2017].
Robinson, D.C.E. 2015c. The Build Process in Windows
using MinGW. https://sourceforge.net/p/open-fvs/wiki/
BuildProcess_MinGW/. [Date accessed: 16-May-2017].
Robinson, D.C.E. 2015d. The Build Process in Windows
using Visual Studio. https://sourceforge.net/p/open-
fvs/wiki/BuildProcess_VisualStudio/. [Date accessed:
16-May-2017].
Robinson, D.C.E. 2015e. Running FVS from VB.Net using
the API. https://sourceforge.net/p/open-fvs/wiki/VB_
DotNet_FVS/. [Date accessed: 16-May-2017].
ResearchGate has not been able to resolve any citations for this publication.
Article
Full-text available
The Tool for Exploratory Landscape Scenario Analyses (TELSA) is a spatially explicit model of vegetation succession, natural disturbances, and forest management activities. TELSA is a strategic planning tool designed to support adaptive management by projecting the consequences of alternative scenarios at the scale of landscape units (i.e. 10 000–200 000 ha) over time frames of decades to centuries. Scenario combine user-specified assumptions about natural disturbances and management activities, and can include ‘no action’ or historic disturbance scenarios. The simulation model is at the core of a set of tools that also includes a geographic information system, databases, and several user interfaces for scenario definition, data analysis, spatial analysis and the display of results. Spatial characteristics of landscapes, such as fragmentation, patch-size distribution and connectivity are largely determined by management actions and their interaction with natural disturbances. The TELSA toolbox includes a tool for the automated design of management units (i.e. harvest cutblocks), based on user-defined criteria and scenario objectives. TELSA easily evaluates strategic alternatives regarding the size range of management units, their spatial aggregation, the use of adjacency constraints, and the application of different silvicultural systems. TELSA represents vegetation succession as changes in species composition and structural stages of stands, thus projecting landscape conditions in a format that is relevant for the analysis of wildlife habitat and many other resource indicators. Succession pathway diagrams define the transition times between successional classes and, for each class, the probabilities and impacts of disturbance by insects, fire or other agents. These diagrams also define the impacts of management actions on stand structure and vegetation composition. Diagrams can be defined for forests and other vegetation types such as shrub and rangelands. Wildfires and other natural disturbance events that affect vegetation dynamics are inherently unpredictable. The model can use multiple stochastic simulations of each scenario to provide estimates of the mean, range and variability of selected performance indicators.
The Westwide pine beetle model: a spatially-explicit contagion model
  • S J Beukema
  • J A Greenough
  • D C E Robinson
  • R Teck
  • M Moeur
  • J Adams
Beukema, S.J.; Greenough, J.A.; Robinson, D.C.E. 1997. The Westwide pine beetle model: a spatially-explicit contagion model. In: Teck, R.; Moeur, M.; Adams, J, comps. Proceedings: Forest Vegetation Simulator conference. Gen Tech. Rep. INT-GTR-373. Ogden, UT: U.S. Department of Agriculture Forest Service, Intermountain Research Station: 126-130.
  • N L Crookston
Crookston, N.L. 2016. FVS API. https://sourceforge.net/p/ open-fvs/wiki/FVS_API/. [Date accessed: 16-May-2017].
Running FVS from VB.Net using the API
  • D C E Robinson
Robinson, D.C.E. 2015e. Running FVS from VB.Net using the API. https://sourceforge.net/p/open-fvs/wiki/VB_ DotNet_FVS/. [Date accessed: 16-May-2017].
The Build Process in Windows using Visual Studio
  • D C E Robinson
Robinson, D.C.E. 2015d. The Build Process in Windows using Visual Studio. https://sourceforge.net/p/openfvs/wiki/BuildProcess_VisualStudio/. [Date accessed: 16-May-2017].