III. How to Use This Manual

This user manual and its supporting documents are written and organized for several types of VELMA user groups:

• Group 1: User describes questions and goals, VELMA team does the rest.

  Example: EPA client offices (Regional offices, Office of Water, etc.) requiring information on potential effects of a change in policy on water quality and other environmental endpoints. VELMA team functions as user types 3 and 4, below, to address client questions and goals.

• Group 2: User assembles GIS data, creates scenarios, runs simulations, analyzes data; VELMA team calibrates hydrology & biogeochemistry submodels and supplies initial input files (parameter values and, if necessary, initial GIS data and climate drivers).

  Example: federal and state land management agencies, watershed councils and other community groups with

expertise.
• Group 3: User works independently to assemble model input files, calibrate parameters, and analyze model output.

  Example: academics and other professionals with expertise in hydrology, biogeochemistry and GIS methods.

• Group 4: User works independently, as for (3), and modifies the program code and ecohydrological equations. Suggested code modifications can be submitted to the VELMA development team, who will review and may incorporate proposed modifications into updated model versions.

  Example: academics and other professionals with expertise in hydrology, biogeochemistry, GIS methods, and computer programming and software design.

This user manual is a reasonably complete how to for operating VELMA v2.0. However, rather than getting immediately bogged down in details, we recommend that all users begin with a quick example and condensed version of the user manual.

Use these steps:

1. Open the VELMA v2.0 subfolder located inside the VELMA Model folder
2. Open the PDF VELMA 2.0 Quick Example. This condensed version (12 pages) of the complete User Manual (176 pages) will guide you through a quick example of how to start VELMA and run it for a pre- configured set of input files and parameters located in the path\folder named VELMA Model\VELMAv2.0\BlueRiver_Example. This application is for a headwater forest catchment at the HJ Andrews Experimental Forest in western Oregon (Abdelnour et al. 2011, 2013). The Quick Example PDF will walk you through the remaining steps, below.
3. Confirm that you have either a Java 7 JRE installed and accessible on your machine.
4. Start the VELMA GUI.
5. Load the example Simulation Configuration File.
6. Set the Location of the Simulation Configuration's Input Data Files.
7. Set the Location Where the VELMA Simulator Will Writer Results Files.
8. Save Your Parameter Changes.
9. Click the Start Button to Start a Simulation Run.
10. Look in the Specified initialOutputDataLocationRoot Results Directory for Results.

These are the most basic steps for using VELMA. All user groups can benefit from the details included in the complete User Manual (this document), although persons in each group likely will have a different approach to using the manual.

For example, if you are a Group 2 VELMA user interested in investigating watershed responses to climate change, you could develop and apply climate scenarios of your own design by following instructions in section IV in this manual. You could then apply your scenarios to an existing VELMA application - for example, the BlueRiver_Example located in the VELMA v20 folder with this User Manual. Our hope is that some Group 2 users will make the jump to Group 3 as they gain experience with VELMA and modeling methods in general.

If you are a Group 3 or Group 4 VELMA user interested in developing new simulator configurations (VELMA applications), you may want to step through all or most of the remainder of this manual. There are a fair number of steps, but we've tried to organize these in a logical way. In particular, “Chapter VI - Steps for Configuring All Parameters TOC Sections 0.0 - 25.0 is our attempt to break up the parameterization process into manageable pieces. Each section and its subsections are focused on parameters associated with a particular ecosystem component or process.

If you are a Group 4 super-user interested in developing new algorithms or other features for VELMA, please contact the authors of this user manual. We will be happy to provide instructions for accessing the VELMA program code through an open source (Subversion / SVN) site where you can download the current release, and later upload your proposed enhancements. Our intent is to make VELMA an open-source community model that is freely accessible and will improve over time.

Before beginning, we recommend that all users become familiar with two “box and arrow” figures describing VELMA's hydrological and biogeochemical pools and fluxes. The first figure is located in Appendix 6.2 section A3 from Abdelnour et al. (2013). It describes the original (VELMA v1.0) model structure and nicely captures the interaction of hydrological and biogeochemical processes in VELMA. The second is Figure 1 on page 43 under Important Information for Sections 5.0 - 25.0 of the All Parameters TOC. It describes VELMA v2.0's Plant Soil Model (PSM) submodel, for which a Leaf-Stem-Root (LSR) submodel has replaced the single (aggregate) plant biomass pool in VELMA v1.0. Together, these figures will give users a good sense of how the model works, and how each section of the User Manual relates to the others.