Functional Requirements for a Shared Library Version of FVS, or Calling FVS from R!

1. Functional Requirements for a Shared Library Version of FVS, or Calling FVS from R! Nicholas L. Crookston Rocky Mountain Research Station December 9, 2011 Growth Model Users Group World Forestry Center Portland, Oregon

2. Goals: my vision for opening FVS to more model builders and more uses. Strategy: my current direction and progress. Your feedback: what do you think? Contents:

3. Provide a for interaction between FVS and other models at each time step of a simulation. Make it easy for other models to: modify growth and mortality rates, define harvests, predict establishment (add trees), and create custom reports. Goals:

4. Provide for interaction at each time step for collections of stands. Run FVS for a time step for thousands of stands, stop the program, and restart from the stopping point perhaps at a later date. Support parallel computing for this class of problem. Goals:

5. Replace the obsolete commercial library that supports the FVS database connectivity with code that runs on 64 bit Windows, Linux, and Mac OSX. Achieve these new capabilities without making major changes to the current code. Keep the current capabilities, that is, don’t break what we have (including Suppose). Goals:

6. Provide a way forward where we can incrementally “build and replace” existing tools. A motive is to eventually replace the keyword commands and the Event Monitor with R scripts. Goals:

7. Build FVS as a shared library (.dll in Windows, .so otherwise). Create an Application Program Interface (API) that provides for interaction between FVS and other programs. Demonstrate the use of the API in R Use the same source for the shared library as used in the full program. Strategy:

8. Provide for using these new capabilities from the traditional program when appropriate. Other systems besides R can use the library, but make sure it works with R. For the database problem, replace the library with a custom built C language layer that translates the Fortran callable functions to the ODBC library functions. Strategy:

9. The database problem is solved. It runs on Linux using unixODBCand Windows. FVS is built as a shared library using gfortran and gcc (using the Rtools tools set). Most of the goals have been addressed. Progress:

10. I have demonstrated that this code works as a shared library from R and provides the same output when run as a stand alone program from a command line. This is done on Linux (64 bit) and Windows. Progress:

11. The API is taking shape. Functions to get and set tree attributes have been tested in R. A function to “add trees” has been written but not tested. A function to set the “proportion to Cut” for each tree is being built. A function to add “FVS activities” on the fly is planned. Progress:

12. The ability to store the FVS memory, stop the program, restart the program and continue from where computation left off has been built and tested from both R and the command line. A strategy for using all this with Suppose as the GUI has been thought through. Progress:

13. I’m concentrating on the highest priorities, mostly centered on interoperation with other models. Absent, for example, is a way to enter inventory data from scratch directly from R and to set the run options (I still rely on the keyword file and FVS’s initialization code). Suppose is still relevant. Closing remarks:

14. Open discussion: • What is important to you? • Questions/comments? • Write to me at: ncrookston@fs.fed.us