The C++ Executable
Step-by-step user guide for forest simulation with the C++ executable.
💻 System requirements?
The 3-PG executable can be run on Windows (still need to test Mac and/or Linux). The main limitation of 3-PG is the size of the input files - minimum system requirements can be highlighted here, or we can send readers to Technical Details.
⚙️ Installation process
To use the executable, copy and paste it to your desired location. After that, all you need is the file path to paste into the command line.
✍️ Usage
3-PG is a command line program, and its behaviour is controlled by several command line options, specified in unix style. The C++ implementation of 3-PG is heavily influenced by the original Excel version, enabling users to easily switch between either implementation (more on the Excel version can be found in Other Implementations).
The usage of the program is:
'path to 3-PG.exe' -d 'path to species file' -s 'path to site file'3-PG reads input parameters from two text files. The parameters are named to match the parameter names used in the Excel version. While the two parameter files are referred to as the ‘species’ (or ‘default’) and ‘site’ parameter files, there is virtually no difference in the possible content of the files. Two files are allowed simply as a convenience, and to be similar to the structure of the Excel version. Example parameter files are provided as part of Additional Resources and Examples.
📄 Parameter Files
The format of the parameter file is one parameter per line, with the parameter name being enclosed in double quotes, and white space separating the parameter name and its value.
Comments are allowed in the parameter file. Comments can appear almost anywhere, must begin with two forward slash characters ‘//’, and end at the end of the line.
Site Parameter File
The site parameter file includes two types of parameters. Site characteristics, and climate parameters, which are referred to as ‘series’ parameters. The site parameter file typically contains the following parameters:
// Site and Stand Descriptors
Latitude (Latitude)
Soil fertility (Fertility rating)
Soil texture (Soil class)
Maximum available soil water (Maximum ASW)
Minimum available soil water (Minimum ASW, usually set to 0)
Start age of the trees (Start age)
End year of the simulation (End year)
Start month of the simulation (Start month)
Year the stand was planted (Year Planted)
Initial foliage biomass (WFi)
Initial root biomass (WRi)
Initial stem biomass (WSi)
Initial stem number (StemNoi)
Initial available soil water (ASWi)
// Climate Parameters
Monthly means of maximum daily temperature (Tmax)
Monthly means of minimum daily temperature (Tmax)
Monthly mean rainfall (Rain)
Monthly mean short-wave radiation (Solar radtn)
Frost days per month (Frost)
CO2 concentration for simulation run (ppm)Parameters that describe site conditions can be provided as constants, or rasters.
For example:
"Fertility rating", 0.7or
"Fertility rating", fert.tifIn the first case, fertility would be set to a constant value of 0.7. In the second case, a raster is used to set the fertility value across an area of interest.
Note the comma after the key word!
Climate parameters are formatted slightly differently. While they can still be provided as a constant or as a raster, one value or raster needs to be provided per month. These values can be regarded as being for an average year. In model runs of more than 1 year these values will be used repeatedly. In this format a series parameter takes the form of a climate keyword, followed by white space, followed by 12 values. For example, this line:
"frost days", fr01.tif fr02.tif 1 0 0 0 0 0 0 0 0 0Sets the value of frost days to be zero for all months of the year, except January, February, and March. In January and February, the value of frost days will be obtained from a raster, which allows the values of frost days to vary spatially for those two months.
The second format for series parameters allows for climate values to be associated with particular years, and for more than one year of input. In this format the keyword must be on a line by itself, followed lines containing a year, followed by 12 values. The series must be terminated by a blank line. For example:
"Rain",
1996 0 0 0 0 0 0 ppt9607.tif ppt9608.tif ppt9609.tif ppt9610.tif 50 50
1997 75 ppt9702.tif ppt9703.tif 150 ppt9705.tif ppt9706.tif 0 0 0 0 0 0This gives constant zero values to precipitation for the first 6 months of 1996, raster values for July to October, constant values for November to January, raster values for February and March, a constant value for April, and raster values for May and June.
Make sure to check the formatting of your parameter files! While key words are not case sensitive, any misspellings, incorrect paths, or errant commas can lead to 3-PG failing.
Management Tables
3-PG can make use of “management tables”. These tables allow arbitrary changes to be made to some of the model variables at particular points in time, simulating the effect of management actions. Three management tables are recognised, allowing control of model variables representing fertility (FR), irrigation (Irrig) and minimum available soil water (MinASW).
Management tables in the C++ version of 3-PG are completely analagous to those in the Excel version, with the one difference that the C++ version requires management tables to be listed in calendar years (the Excel version requires tables listed by stand age).
Management tables are indicated in the parameter file by one of the three keyword phrases: “Management: fertility”, “Management: Irrigation”, or “Management: MinASW”. The keyphrase must appear on a line on its own, followed on subsequent lines by the calendar year, and the value of the management variable. Each value can be either a grid file or a constant. For example:
"Management: irrigation",
1994 8
1997 irr1997.tif
2000 0In the example above, if we assume that the “year planted” parameter has the value 1989, then for every year up to, but not including, 1994, 8 ML/year of irrigation is applied, over the whole run area. For the years 1994, 1995 and 1996, each cell will receive the irrigation specified in the grid file irr1997.tif. If a cell contains the NODATA value, the effect of the previous entry in the management table persists. For the years 1998 and on, zero irrigation is applied throughout the whole run area. This carry over of the last entry of the management table duplicates the working of the Excel version.
The irrigation management variable can only be provided with a management table. MinASW and fertility, however, can be provided both as management tables and as ordinary parameters. In this case the ordinary parameter value will take effect only where the management table does not provide a value, such as a cell which has the value NODATA in every entry in the management table.
Other Requirements
The parameters “Model mode” and “Output directory” are required, and usually appear at the top of the site parameter file. “Model mode” should be given as ‘3PG’, while “Output directory” gives the path to a directory in which output rasters will be written. For example:
"Model mode", 3PG
"Output directory", D:\3-PGS_MODELTells the executable to run 3PG and write all output files to a folder called “D:\3-PGS_MODEL”.
Species Parameter File
As mentioned in the previous section, 3-PG requires a specific species parameter file, which is provided separately to the site parameter file.
Example parameter files and how they are used are provided in the Additional Resources and Examples section.