Technical Report No. 29, Edition 2

3PGpjs vsn 2 – a User-Friendly Interface to 3-PG, the Landsberg and Waring Model of Forest Productivity

Peter Sands

COOPERATIVE RESEARCH CENTRE FOR SUSTAINABLE PRODUCTION FORESTRY AND CSIRO FORESTRY AND FOREST PRODUCTS

Technical Report No. 29, Edition 2

3PGpjs – a User-Friendly Interface

to 3-PG, the Landsberg and Waring Model of Forest Productivity

Peter Sands

CRC for Sustainable Production Forestry and

CSIRO Forestry and Forest Products,

GPO Box 252-12, Hobart, Tasmania 7001,

Australia

email: Peter.Sands@ffp.csiro.au

Software versions : 3PGpjs vsn 2 / 3‑PG vsn Jan2001

Date: January 2001

Disclaimer

3PGpjs is available as ‘freeware’. Neither CSIRO nor the CRC for Sustainable Production Forestry represent or warrant that the information in this report is accurate or complete or accept any responsibility for the use of 3PGpjs or of the model 3-PG in the form supplied with this document or subsequently modified by third parties. This document and 3PGpjs do not constitute an endorsement of 3-PG. CSIRO and the CRC for Sustainable Production Forestry disclaim liability for all loss, damages and costs incurred by any person as a result of relying on the information in this document and/or the associated software.

3-PG was developed by Joe Landsberg and Dick Waring. Enquiries concerning 3-PG should be directed to Joe Landsberg (email: joe.landsberg@landsberg.com.au).

Enquiries or suggestions concerning 3PGpjs are welcome and should be directed to the author.

Summary

3PGpjs is a user-friendly interface to 3-PG, a model of forest productivity (Landsberg and Waring, 1997). The interface is via MicroSoft Excel worksheets and is coded in Visual Basic. Normal spreadsheet operations can be combined with 3PGpjs.

3PGpjs presumes some structure to input worksheets, yet is flexible enough to facilitate easy modification of site factors and default parameter values. The interface allows runs of several types:

· a single-site run, in which all data for a single site are specified on a worksheet and a detailed summary of stand development is written to that worksheet;

· a sensitivity analysis, in which stand development is simulated for a series of site factors or 3-PG parameters and selected output from all runs is written to a single worksheet;

· a multi-site run, in which stand development of a series of sites is simulated from planting and selected output from all runs is written to a single worksheet.

3PGpjs permits selected site factors to be age-dependent. This simulates silvicultural intervention and aids the study of consequences to changes in site conditions, e.g. due to fertilisation or irrigation, or a natural run-down of site conditions.

Changes to 3-PG in 3PGpjs vsn 1:

· The model is consistently state-determined

· Canopy quantum efficiency is affected by temperature and site nutrient status

· The manner in which the various modifiers are applied has been improved

· Specific leaf area is age-dependent

· Loss of production by non-closed canopies is considered

· Stand volume takes into account basic density and an age-dependent branch and bark fraction

· Changes in how relationships are parameterised give parameters intuitive meaning

Changes to 3-PG in 3PGpjs vsn 2

· Mortality is applied monthly; the self-thinning law is satisfied after mortality has been applied

· Rainfall interception depends on canopy LAI

· The radiation conversion for the Penman-Monteith equation can be modified by the user

Changes to 3PGpjs in vsn 2

· Output can be monthly; the stand can be planted or the simulation initialised in any month

· Spreadsheet-based database of climatic data can be established and used

· Output variables in a summary of stand development can be specified by the user

· Thinning and defoliation are available as silvicultural options

· Multi-site runs allow many sites to be run simultaneously

· Changes to the interface include menu bars and buttons

· 3PGpjs can be loaded as an Excel add-in

1. Introductory remarks

3-PG is a dynamic, process-based model of forest growth (Landsberg and Waring, 1997) that runs on a monthly time step using monthly climatic data. 3PGpjs is a simple MS Excel spreadsheet-based interface to 3‑PG. It provides the user considerable flexibility with no need to modify computer code. It was designed primarily to facilitate the use of 3-PG in a research setting, e.g. the adaptation of 3‑PG to novel species or situations (Sands and Landsberg, 2000), although it is ideally suited to perform production runs at a single site or across a moderate number of sites.

Normal spreadsheet operations are available with 3PGpjs. The user can use these to transform or display 3‑PG output: e.g., to compute variables not provided by 3-PG, graph stand development with observed data superimposed, or show how stand characteristics depend on 3-PG parameters. Some 3PGpjs worksheets are executable (see Sec. 3.1). Non-executable worksheets provide default 3-PG parameter values, summarise 3PGpjs output variables and keywords, provide parameter conversions, or graph functional relationships.

3‑PG is properly state-determined in 3PGpjs: intermediate variables are determined from the state of the system at the beginning of a time step, age-dependent variables are determined from stand age at the beginning of a time step, output variables are determined from the state at the end of a time step. The structure of 3PGpjs is guided by the experience of myself and others using 3‑PG as a research tool. I have greatly appreciated this assistance. Comments, ideas and requests are welcome.

2. Installation of 3PGpjs

3PGpjs can be installed in two ways. These are:

· as an Excel add-in, so that the 3PGpjs code is available from any work book without being explicitly attached to that work book; or

· as a fully integrated workbook, combining the 3PGpjs code and data sheets.

Full details of the installation process are in the file ReadmeFirst.Doc. The advantage of the first method is that only a single copy of code is stored, working files are smaller and code is common to all spreadsheets. The program package includes two Excel workbooks:

· 3PGpjs.xls the 3PGpjs code, which can be used to create the add-in, and

· 3PGpjs.samples.xls sample spreadsheets with macros to load/unload the 3PGpjs add-in.

3. Running 3‑PG

3.1 The 3PGpjs run-types

The interface allows various modes of operation:

· A single-site run simulates stand development for a single site. Climate data, site factors, initial conditions, optional changes to 3-PG parameters, and data defining silvicultural events can be read from a single sheet: the single-site sheet. Climate data can be obtained from a database on a separate sheet. A monthly or annual summary of stand development is written to the single-site sheet. A listing of most 3-PG variables can be written to the 3‑PG_results worksheet.

· A site-series run simulates stand development at a series of sites. The site-series sheet lists the names of single-site sheets to be run, and all input/output for each site is from/to its single-site sheet. Each site runs independently of the others.

· A sensitivity analysis is a repeated run of one or more sites to perform a sensitivity analysis of stand growth to initial conditions, climatic or site factors, or 3‑PG parameters. The sensitivity analysis sheet lists the names of the single-site sheet or sheets and specifies modifications to 3‑PG parameters or site factors for each site. It also lists the required output variables. Primary output is to the sensitivity analysis sheet and the single-site sheets are unchanged. Standard single-site output from the individual runs can be written to a named output sheet.

· A multi-site run simulates stand development at a large number of sites over a specified rotation using standardised initial conditions. The multi-site sheet lists the names of the sites and their basic site factors, and specifies the required output. Climatic data are contained on a climate data sheet. Primary output is to the multi-site sheet, but standard single-site output for all sites can be written to a named output sheet.

A cell near the top left-hand corner of 3PGpjs worksheets contains the keyword Run type. The cell to the right of this contains the run-type keyword and determines how data on this sheet will be treated by 3PGpjs. The run-type keywords for the above four run-types are SingleSite, SiteSeries, Sensitivity and MultiSite, respectively, and sample spreadsheets for each are in 3PGpjs.samples.xls. Pressing the 3PGpjs run button causes the run-type keyword to be examined and the appropriate run initiated.

Error checking is performed during data input and model execution. The interface exits gracefully with a meaningful error message under those circumstances I managed to contrive! Press Ctrl-Pause to interrupt execution.

3.2 General comments on 3PGpjs runs

When 3PGpjs is loaded, a disclaimer and conditions of use are displayed. If you agree, press Y or click the Yes button, otherwise you cannot run 3-PG. If you press Yes, the 3PGpjs “About” form is displayed. Pressing any key removes this and 3PGpjs can then be used.

Loading 3PGpjs creates a menu item on the menu bar, and three buttons on a toolbar in the bottom left of the screen. This toolbar can be dragged to any other location. The menu includes items for running 3PGpjs, for accessing on-line help (not available yet), for displaying the “About” form, and for unloading 3PGpjs. The toolbar buttons are a calculator to run 3PGpjs, a telephone to access on-line help, and a yellow smile to display the “About” form.

3.3 Use of keywords

All input data is provided in data blocks, and 3PGpjs uses keywords to locate a data block and to determine the nature of the data therein. The leading characters of a keyword must be as given in Table 1. In this report, keywords are shown in bold italic Arial type, e.g. Output data. Keywords often have data associated with them, usually in the cell or cells to the right of the keyword. In response to questions, y or yes signify “Yes” and any other input is “No”. The format (case, font, size, colour) of keywords and all other input is ignored.

4. Specification of 3‑PG parameters and options

The 3-PG parameters that characterise a species are given on a worksheet named 3PG_Parameters. This must have the form shown in 3PGpjs.samples.xls. Columns to the right of the Units column contain the parameter values for the species named at the head of the column. Do not edit parameter names, but you may edit parameter values or add columns of values for new species. The species selected by a Species keyword on the running sheet is compared with the species names on 3PG_Parameters to select the parameters to be used in a run. If parameters for this species are not on 3PG_Parameters, or this sheet is not in the active workbook, internal values are used.

Parameter values can also be specified on single-site and sensitivity analysis sheets. 3PGpjs assigns parameters in the following steps so the values used are those found on the active worksheet:

1. The internal, coded values are assigned.

2. Default parameters for the species selected by the run are then read from 3PG_Parameters.

3. Values given on single-site sheets replace these default values.

4. For a sensitivity analysis, parameters are then read from the sensitivity analysis sheet.

3PGpjs also has run-time options whose default values are specified on 3PG_Parameters:

· Output frequency determines the frequency of output for stand development summaries.

· Clear output region determines if potential output cells are cleared prior to fresh output.

· Output variables for any single-site run are defined.

5. The SingleSite run-type

A single-site sheet has the run-type keyword SingleSite.

The keyword Site on a single-site sheet identifies a name for the site. The keyword Species identifies the name of the species to be used to select parameter sets from 3PG_Parameters. If the species does not match a species on 3PG_Parameters, or that sheet is not present in the workbook, the parameter values coded into 3PGpjs are used.

The minimum data required to run 3-PG are the following:

· Climate data: Monthly mean temperature, solar radiation, rainfall, vapour pressure deficit, and frost days.

· Site factors: Site-latitude, maximum available water stored in the soil, soil fertility rating.

· Initial conditions: Stem, root and foliage biomass, stocking and soil water at some time.

· 3-PG parameters: Parameters characterising the species modelled.

The following data are optional:

· Changes to default parameters.

· Silvicultural events: e.g., changes in fertility rating or irrigation rates can be specified.

Data is provided on a single-site sheet through three mandatory data blocks, Climate data, Site factors, and Initialisation, and optional blocks for parameter changes and silvicultural events. Optional inputs control the resolution (monthly or annual), and a list of output variables.

5.1 Mandatory single-site data

Climate data

The source of climate data for a single-site run is identified by the keyword Climate data. Climate data for a weather station can be read from a climate database on a separate sheet, or from a table on the single-site sheet. Full details of climate databases are given in Sec.6. The options are:

· If the cell to the right of Climate data contains a valid climate variable name (Sec. 6), the climate data is presented at this location in the form of a table, with variables in columns and months in rows.

· If the cell to the right of Climate data does not contain a valid climate variable name, the cell below Climate data is examined to see if the table matches one of the formats employed in 3PGpjs version 1.

· If it does not, then the cell to the right of Climate data names a sheet containing a climate database, and the single-site sheet must also contain the keyword Met station naming the weather station whose climate data is to be used.

Site factor data

The site factor data are identified by the following site-factor keywords:

Latitude : Site latitude (-ve for the S hemisphere).

Fertility rating : Site fertility rating, on a range of 0 for concrete to 1 for a highly fertile site.

Soil class : Soil class in accordance with Table 2, used to specify the parameters c_q and n_q.

Maximum ASW : Maximum available water stored in the soil (mm).

Minimum ASW : The minimum allowed available soil water (mm). If actual available soil water falls below a non-zero minimum, it is assumed the shortfall is made up by an external source. 3PGpjs totals this added water, and can report it.

The location of site-factor keywords is arbitrary, but on the sample data sheets they are grouped below Site factor block.

Initialisation data

Initialisation data are identified by the following initialisation keywords:

Year planted : Calendar year in which the stand was planted.

Month planted : Calendar month in which the stand was planted.

Initial year : Calendar year (or stand age) at which initialisation data is given.

Initial month : Calendar month at which initialisation data is given .

End age : Stand age at which the run terminates.

W foliage : Initial biomass (t/ha) in the foliage biomass pool.

W root : Initial biomass (t/ha) in the root biomass pool.

W stem : Initial biomass (t/ha) in the stem biomass pool.

Stocking : Initial stocking (trees/ha) of the stand.

Soil water : Initial available soil water (mm) constrained to be between the minimum allowed and maximum available soil water and set to the maximum by default.

The location of initialisation keywords is arbitrary, but on the sample data sheets they are grouped below Initialisation block.

The times of planting and stand initialisation are assumed to be at the end of the calendar month. The initial stand age is the time from the month and year planted to the initial month and year. For example, if the month and year planted are April 1990 and the initial month and year are June 1995, initial stand age is 5 years, 2 months, and the first month of the run will use climate data for July.

5.2 Optional single-site data

The format of the optional Parameters and Silvicultural event data blocks on a single-site sheet must be as shown in the sample data sheets, but their location, size and content is flexible.

Parameters data block

The parameters data block is identified by the keyword Parameters. Parameter names (see Table 3, or the Names column on 3PG_Parameters) are listed in cells immediately below the Parameters keyword, with their value in the cell to the right. The number of parameters that can be specified this way is arbitrary. A blank cell in the column of parameter names terminates parsing of parameters. If either of the parameters Swconst or Swpower are included in the parameters data block, the values implied by the soil class given in the site factors data block will be overwritten.

Silvicultural events

Silvicultural events are defined by tables specifying how site fertility, minimum available soil water or annual total irrigation vary with stand-age, or the time and effects of thinning or defoliation events. Keywords that identify these tables are Fertility, MinASW, Irrigation, Thinning and Defoliation, respectively. The location of these silvicultural event tables is arbitrary.

Each table is of arbitrary depth. The left-hand column contains its keyword (e.g. Fertility), below which is “Age” and a series of stand ages. Columns to the right contain relevant variables that pertain up to and including the age given in that row. A blank cell in the “Age” column terminates parsing of the table. The required inputs for each age are

Fertility Site fertility rating in the range 0-1.

MinASW Available soil water (mm) below which ASW is supplemented by external water.

Irrigation Irrigation rate (ML ha^-1 yr^-1), but applied in equal monthly instalments.

Thinning Residual stocking (trees ha^-1) after thinning at the nominated age, and biomass pools of each tree removed by the thinning, expressed as a % of foliage, root and stem biomass of an average single tree in the stand at thinning.

Defoliation % foliage remaining after defoliation at the nominated age.

Important note: 3-PG does not appear to respond correctly to thinning or defoliation, particularly in relation to biomass partitioning after the event, so use these events with extreme care! For example, after thinning or defoliation, stands usually grow towards a closed canopy through changes in biomass partitioning. However, partitioning in 3-PG is currently based only on average stem diameter, and hence cannot respond to thinning or defoliation.

5.3 Single-site output

3‑PG uses a monthly time step. The time of planting, initial stand conditions and all output are at the end of a calendar month. Thus, if the stand is initialised in June, the first monthly output will be for the end of July, and the output at the end of the each annual cycle will be at the end of June.

Stand development summary

A single-site run writes a summary of stand development to the single-site sheet. The location of this output, and the default output variables and frequency (specified on the 3PG_Parameters sheet), can be changed by keywords on the single-site sheet.

The location of single-site output is identified by the keyword #Output, and output commences in column 1 of the row containing this keyword. If Clear output region has been selected on 3PG_Parameters, 3PGpjs clears a rectangular region of the sheet prior to writing any output. This region has as its top-left corner the cell in column 1 of the first output row. The bottom-right corner is found by scanning down to the last non-blank cell, and then right to the last non-blank cell. This region depends on existing data, and hence may not correspond to the actual output region used. To preserve existing output, remove the “#” from the keyword #Output.

The default output frequency is set by Output frequency on 3PG_Parameters. To change this, include on the single-site sheet the keyword Output frequency, and enter to its right: 1, r or rotation for output at the end of the run; 2, a or annual for annual output; or 3, m or monthly for monthly output. Note that if output is annual, the canopy LAI is the annual average monthly LAI.

Default single-site output variables are the Output variables specified on the 3PG_Parameters sheet. Additional variables can be requested by listing their names (as in Table 4) in cells to the right of the keyword Output data. Parsing for output variables terminates when a blank cell is encountered in the row containing the Output data keyword.

The keyword Title can be used to provide a title that is printed with the single-site output. This is useful to identify distinct blocks of output on the same single-site sheet: simply change the text of the title before making a distinct run.

Detailed 3‑PG output

Detailed output of most 3‑PG variables is written to the sheet 3PG_Results if the cell to the right of the keyword Detailed output on the single-site sheet contains yes. If 3PG_Results does not exist it is created, and it is cleared if Clear output region is on. If annual stand output is selected, detailed output is generated only for each month of the last year of the run, or if monthly stand output is selected, for each month of each year. A detailed annual summary of stand-level data is provided for all years, irrespective of the output frequency.

6. Climate databases

Climatic data can be provided on a single-site data sheet, or on a sheet forming a climatic database containing data from one or more weather stations. There are two database formats:

· table format, where climatic data for each site is a table with climatic variables in columns and months as rows, or

· row format, where climatic data for each year of each site is provided as a single row.

The format is indicated by the key-word Database format, with values Table format or Row format, respectively. Examples are the sheets MetData1 and MetData2, respectively.

6.1 Climatic variables

3‑PG requires the following climatic variables: monthly mean daily temperature, solar radiation and vapour pressure deficit (VPD), total monthly rainfall, and total frost days per month. 3PGpjs recognises climatic variables by the names given in Table 5, and which variables are in a climatic database are determined by keywords on the sheet.

Note that when supplying VPD values it is preferable to use values based on the daylight hours only, rather than values inferred from daily maxima and minimum temperatures. If mean temperature or VPD are not available, they can be computed from monthly mean daily maximum and minimum temperatures. Mean temperature is then the average of maximum and minimum temperatures. VPD is calculated as half the difference between saturated vapour pressure at the maximum and minimum temperatures (see also the worksheet Tools). Frost days are optional, and are zero by default. Pan evaporation and rain days are ignored by 3PGpjs. Their inclusion is so data can be shared with productivity models that require them (e.g. ProMod, Battaglia and Sands, 1997). Daylength is computed from site latitude as the daylength on the 15^th day of each month.

6.2 Table format

In table format, climatic data are in a table with rows for months and columns for each variable. Each table of climate data has one row for each month, starting with January of the first year of data and proceeding to December of the last year. The first row contains column headings: the year, the month, and the variable names as in Table 5. A blank cell terminates parsing of names. The name of the weather station from which a block of data is from must be in the cell above the Month heading of its table and is used by 3PGpjs to locate climate data for that station.

To use realistic sequences of climate data, extend the climate data block downward by giving monthly data in multiples of 12 months – so one year follows another. If the year column contains values in the January row, these are assumed to be the year of the corresponding climate data, and a single-site run will read climate data starting with the first year of the simulation based on the year of planting and initial stand age. If insufficient data is available for the run, 3-PG will then cycle through this data, starting again at the initial year. If only a single year’s data is given, it is used for all years of a run. This would be the case when using long-term mean data.

6.3 Row format

In row format, climatic data are provided as consecutive rows of data, one for each year for each station. If a run spans more years than the number of years for which data is provided, the data is recycled. If there is only a single row of data for a station, it is used for all years of the run. The names of the climatic variables (as in table 5) provided on the sheet are in the cells to the right of the keyword Climate data, and a blank cell terminates scanning for names. The order of these names determines the order of the climate data in the database.

Column A contains the station name. 3PGpjs locates data for a station by searching column A for the station name, and if a station cannot be located, execution terminates. Subsequent groups of 12 columns contain climatic data for January to December. For example, in the case of MetData2, the first group of 12 columns (B-M) contain mean maximum temperatures for January to December. Then come mean minimum temperatures, followed by total monthly rainfall, etc. Annual data for a station must be in consecutive rows, but there can be blank rows between distinct stations.

7. The SiteSeries run-type

A site-series data sheet has the run-type keyword SiteSeries. It contains a single column of data with the keyword Sites as its heading and the names of single-site sheets below this. These sheets will be run as a series of independent runs. Parsing for sheet names commences with the cell below Sites and proceeds downwards until a blank cell is obtained. All other input is from the selected single-site sheet, and all output is directed to the that sheet. The net effect is the same as if the selected sites were run as individual single-site runs.

8. The Sensitivity analysis run-type

A worksheet is a sensitivity analysis sheet if its run-type keyword is Sensitivity. A series of single-site runs are performed in which data on named single-site sheets are updated by optional data on the sensitivity analysis sheet. These runs are used to conduct sensitivity analyses of stand growth to site factors or 3‑PG parameters.

8.1 The sensitivity analysis data block

The sensitivity analysis sheet contains one or more rectangular blocks of data with the keyword Sites in the top-left corner. All sensitivity analysis data blocks on a sheet are run, and to stop a block from running, remove its Sites keyword.

Each sensitivity analysis data block comprises adjacent columns of data. The left-most column has the keyword Sites as its heading, and lists the names of the single-site sheets to run. Names are parsed by scanning down until a blank cell is encountered. The top row contains the names of 3-PG parameters, site factors, or initial conditions as headings to columns of data to the right of the Sites column, and the columns contain the values of the corresponding data for each site. Valid names of parameters, or site factors and initial conditions are given in Tables 3 and 6, respectively. Headings are parsed by scanning to the right. A blank cell, or a cell that does not contain a known parameter, site factor or initial condition terminates parsing. Further columns are assumed to be output data. Note that fertility rating can be assigned as part of a sensitivity analysis data block only if it is not specified as a silvicultural event on the single-site data sheet.

8.2 Sensitivity analysis output

Sensitivity analysis output is directed to the sensitivity analysis sheet; none is written to individual single-site sheets, or to 3PG_Results. Output variables are selected using the keyword Output data on the sensitivity analysis sheet. The corresponding outputs are in columns to the right of the sensitivity analysis data block, which are first cleared if Clear output region is set.

Detailed single-site output for each run in an analysis can be written to a selected sheet by using the keyword Output sheet to specify the name of this sheet. If it does not exist it is created, and if it does exist it is cleared of all existing data. The output frequency is set by the keyword Output frequency on the sensitivity analysis sheet, and the output variables are the current default output variables together with those selected by the Output data keyword.

9. The MultiSite run-type

A multi-site sheet has the run-type keyword MultiSite. A multi-site run is a simple way to simulate stand development from planting at a large number of sites. Each run is initialised at stand age 0 with biomass pools appropriate to the seedlings.

9.1 Multi-site input data

The keyword Sites identifies the multi-site data block. This contains a single row of data for each site. The names in the Sites column are used to select climate data stations from a climate database. Other essential items of data are in columns to the right of the sites column, and in the following order: latitude, soil type (Table 2), maximum available soil water (mm), minimum available soil water (mm), and initial stand stocking (trees ha^-1).

Data common for all sites in a multi-site run are given by keywords anywhere on the multi-site sheet. The species name is to the right of the keyword Species. The name of the climate database is to the right of the keyword Climate sheet. Stand development is simulated up to the age given by the keyword Stand age. Initial stand biomass pools are based on mean seedling biomass, assigned by the keyword Seedling mass, multiplied by initial stocking. 50% of seedling biomass is leaves, 25% is roots and 25% is stem. Experience shows that, except for initial canopy development, results are largely independent of seedling biomass and partitioning (Sands and Landsberg, 2000).

9.2 Multi-site output

Standard output from a multi-site run is directed to the multi-site sheet, and the keyword Output data on the multi-site sheet is used to select output variables from those listed in Table 4. Output is displayed in columns to the right of the stocking column in the multi-site data block.

Detailed single-site output for each site in the multi-site run can be written to a selected sheet named by the keyword Output sheet. If it does not exist it is created, and if it does exist it is cleared of all existing data. The output frequency is set by the keyword Output frequency, and the output variables are the current default output variables together with those selected by Output data.

10. Worksheets in 3PGpjs.samples.xls

10.1 The 3PG_Parameters worksheet

The 3PG_Parameters worksheet has the standard name and format for a worksheet giving default, species-specific, 3‑PG parameters. Further details are in Sec. 4. The values shown for the species Default are the values hard-coded into 3PGpjs.

10.2 The SingleSite examples

In the following examples, climate, site factors and observed data are realistic for a particular site. However, analyses are purely illustrative, and the resulting parameter values should not be assumed to be realistic.

The Sample1 worksheet is a basic application of 3PGpjs. Climate data is in the preferred format described in Sec 5.1, i.e. monthly data are in rows. Default values for some parameters have been overwritten with values which better reproduce early stand growth. Age-dependent silvicultural events have been specified. The stand was irrigated with about 10 Ml ha^-1 of water applied in each of the first 6 years, but then subject to mild drought, simulated by a negative irrigation of 1 Ml ha^-1 from age 7. The site was fertilised for the first three years, and site fertility subsequently ran down. Accordingly, the 3‑PG fertility rating was reduced as the stand ages. The default output was supplemented with annual and accumulated litterfall.

Sample2 now uses actual rainfall data, including applied irrigation, for the period of the trial. Climate data is therefore presented for each year of growth. This is for the weather station Yearly data, and is read from the climate database MetData1. As before, site fertility runs down over the life of the stand, but irrigation is no longer specified as a silvicultural event. This example also requests monthly output and the production of detailed 3‑PG output, shown on the sheet 3PG_results.

10.3 The SiteSeries example

This example runs single-site sheets SingleSite1, SingleSite2 and Example_3, taking all input from the single-site sheet, and writing all output to that sheet. The single-site sheet Example_3 does not exist so the result of its run is listed as “aborted”.

10.4 The Sensitivity example

This sheet examines the sensitivity of canopy development to litterfall patterns by running the same site with a range of parameter values. Results from two runs are shown, each with its own sensitivity analysis data block, and in each of which a different parameter controlling litterfall was varied over a range of values. Graphs were constructed using normal spreadsheet techniques.

10.5 The MultiSite example

The MultiSite sheet simulates production for a series of E. globulus sites in SE Tasmania and SW Western Australia (Battaglia and Sands, 1997; Sands and Landsberg, 2000). All climate data is read from the climate database Metdata2, and detailed results for each site are written to Multisite results.

10.6 The climate databases

The sheets MetData1 and MetData2 illustrate climate databases in table and row formats, respectively.

10.6 The non-executable worksheets

Instructions contains very basic comments on the 3PGpjs menu items, toolbar and hot keys.

3PGpjs_Keywords and 3PGpjs_Outputs summarise keywords and output variables.

3PG_Parameters is the standard 3PGpjs sheet providing 3‑PG parameters, and 3PG_results is an example of the detailed output from a single-site run (SingleSite2).

MetData1 and MetData2 are examples of climate databases in table and row formats, respectively.

Conversions allows conversion between new and old parameter sets. Edit the parameter values shown in red and the corresponding old (or new) values are updated to reflect the changes.

Tools graphs many of the relationships in 3‑PG. It is used to explore consequences on the form of a relationship of changes in the parameters that characterise it. Change the value of a parameter and the graph of the associated relationship is updated to reflect the change in the parameter.

References

Battaglia, M. and Sands, P.J. (1997). Modelling site productivity of Eucalyptus globulus in response to climatic and site factors. Australian Journal of Plant Physiology 24: 831-850.

Landsberg, J.J. and Waring, R.H. (1997). A generalised model of forest productivity using simplified concepts of radiation-use efficiency, carbon balance and partitioning. Forest Ecology and Management 95: 209-228.

Sands, P.J. and Landsberg, J.J. (2000). Parameterisation of 3-PG for plantation-grown Eucalyptus globulus. (In preparation)

Table 1. Summary of 3PGpjs keywords and their action

Keyword	Comments on context and meaning	Mandatory or optional
Identification of run type
Run type	Assigns nature of run to be performed based on following run-type keywords:	M
SingleSite	Identifies a single-site run
SiteSeries	Identifies a series of single-site runs
Sensitivity	Identifies a sensitivity analysis run
MultiSite	Identifies a multi-site run
Single-site data
Site	Assigns name of site for a single-site run	O
Species	Assigns name of species	O
Latitude	Site latitude (-ve for S hemisphere)	M
Fertility rating	Fertility rating, 0-1	M
Soil class	Soil classification (1-4, or S, SL, CL, C; 0 for no soil water limits; ? for default)	M
Maximum ASW	Maximum available soil water (mm)	M
Minimum ASW	Minimum available soil water (mm)	M
Year planted	Calendar year in which stand was planted	O
Month planted	Calendar month in which stand was planted	O
Initial year	Calendar year or age at which initialisation data is given	M
Initial month	Calendar month of initialisation data, i.e. first month of each run	O
End age	Stand age at which run ends (years)	M
Initial WF	Initial foliage biomass, i.e. at initial year, initial month (t ha^-1)	M
Initial WR	Initial root biomass (t ha^-1)	M
Initial WS	Initial stem biomass (t ha^-1)	M
Initial stocking	Initial stocking (trees ha^-1)	M
Initial ASW	Initial available soil water (mm)	O
Parameters	Locates parameter block on single-site sheet	O
Fertility	Identifies table of fertility ratings (0-1)	O
MinASW	Identifies table of values of imposed MinASW (mm)	O
Irrigation	Identifies table of applied irrigation rates (Ml ha^-1 yr^-1)	O
Thinning	Identifies table of thinning events	O
Defoliation	Identifies table of defoliation events	O
Sensitivity analysis and Site-series runs
Sites	Names of single-site sheets to be run must be below Sites	M
Multi-site run
Climate data	Assigns name of climate input data sheet	M
Species	Assigns name of species	O
Stand age	Assigns maximum stand age for multi-site runs	O
Seedling mass	Assigns seedling biomass for initialising multi-site runs	O
Month planted	Sets month in which stand was planted	O
Sites	Names of climate data sets sites to be used must be below Sites	M

Table 1. Summary of 3PGpjs keywords and their action (continued)

Keyword	Comments on context and meaning	Mandatory or optional
Climate input data
Climate data	On climate data sheet: Keywords to right of Climate data identify input variables on this sheet or table. Variables recognised are: Tmax, Tmin, Tav, VPD, Rain, Solar Rad or Radtn, Pan evap or Evap, rain days, and Frost days	M
	On multi-site sheet: names climate data input sheet	M
	On single-site sheet: If cell to right of Climate data is a climate variable (as above), get climate data from this sheet; otherwise names climate data sheet (Met station then required)	M
Met station	Names climate data set when climate data for a single-site read from climate data input sheet	O
Database format	Required on climate data sheet to identify database format:	M
Table format	Table format: variables in columns, months in rows	O
Row format	Single row format: one row per year	O
Output control
#Output	Identifies 1^st row for single-site run output block	M
Title	Assigns text to identify single-site run output block	O
Output data	Assigns list of output variables for run	O
Output frequency	n = none, r = end of rotation, a = annual, m = monthly	O
Detailed output	yes = write detailed single-site output to 3PG_Results sheet, no = no detailed output	O
Output sheet	Name of output sheet for stand development details (multi-site & sensitivity runs)	O

Table 2. Soil classes and corresponding parameter assignments

Soil class	Soil class	Predominant	Soil parameters
index	code	character of soil	cq	nq
1	S	Sandy	0.7	9
2	SL	Sandy loam	0.6	7
3	CL	Clay loam	0.5	5
4	L	Clay	0.4	3
	?	Non-standard soil class: use values for cq and nq from the parameter set
	0	No effect of available soil water on production or conductance, i.e. fSW = 1

Table 3. Description of 3‑PG parameters, their 3PGpjs names,

and values for E. globulus

Meaning/comments	3‑PG symbol	3PGpjs Name	Value	Units
Allometric relationships & partitioning
Ratio of foliage:stem partitioning at D = 2 cm	p2	pFS2	1	-
Ratio of foliage:stem partitioning at D = 20 cm	p20	pFS20	0.15	-
Constant in stem mass v diam. relationship	aS	stemConst	0.095	-
Power in stem mass v diam. relationship	nS	stemPower	2.4	-
Maximum fraction of NPP to roots	hRx	pRx	0.8	-
Minimum fraction of NPP to roots	hRn	pRn	0.23	-
Temperature modifier
Minimum temperature for growth	Tmin	Tmin	8	deg. C
Optimum temperature for growth	Topt	Topt	16	deg. C
Maximum temperature for growth	Tmax	Tmax	40	deg. C
Frost modifier
Number of days production lost for each frost day	kF	kF	1	-
Soil water modifier
Moisture ratio deficit which gives fq = 0.5	cq	SWconst	0.7	-
Power of moisture ratio deficit in fq	nq	SWpower	9	-
Age modifier
Maximum stand age used to computer relative age	-	MaxAge	50	years
Power of relative age in fage	nage	nAge	4	-
Relative age to give fage = 0.5	rage	rAge	0.95	-
Litterfall & root turnover
Maximum litterfall rate	gFx	gammaFx	0.027	month^-1
Litterfall rate at t = 0	gF0	gammaF0	0.002	month^-1
Age at which litterfall rate has median value	tgF	tgammaF	24	month
Average monthly root turnover rate	gR	Rttover	0.015	month^-1
Conductance
Maximum canopy conductance	gCx	MaxCond	0.02	m s^-1
Canopy LAI for maximum canopy conductance	LCx	LAIgcx	3.33	-
Defines stomatal response to VPD	kg	CoeffCond	0.05	mBar^-1
Canopy boundary layer conductance	gB	BLcond	0.2	m s^-1
Fertility effects
Value of m when FR = 0	m0	m0	0	-
Value of fN when FR = 0	fN0	fN0	1	-
Stem mortality
Maximum stem mass per tree at 1000 trees/ha	wSx1000	wSx1000	300	kg tree^-1
Power in self thinning law	nN	thinPower	3/2	-
Fraction of mean foliage biomass per tree on dying trees	mF	mF	0	-
Fraction of mean root biomass per tree on dying trees	mR	mR	0.2	-
Fraction of mean stem biomass per tree on dying trees	mS	ms	0.2	-

Table 3. Description of 3‑PG parameters, their 3PGpjs names,

and values for E. globulus (continued)

Meaning/comments	3‑PG symbol	3PGpjs Name	Value	Units
Canopy structure and processes
Specific leaf area at stand age 0	s0	SLA0	11	m^2 kg^-1
Specific leaf area for mature aged stands	s1	SLA1	4	m^2 kg^-1
Age at which specific leaf area = ½(s0+s1)	ts	tSLA	2.5	years
Extinction coefficient for absorption of PAR by canopy	k	k	0.5	-
Age at full canopy cover	tcc	fullCanAge	0	years
Maximum proportion of rainfall intercepted by canopy	Ix	MaxIntcptn	0.15	-
LAI for maximum rainfall interception	LIx	LAImaxIntcptn	0	-
Canopy quantum efficiency	a	alpha	0.07	molC mol^-1PAR
Branch & bark fraction
Branch and bark fraction at stand age 0	pBB0	fracBB0	0.75	-
Branch and bark fraction for mature aged stands	pBB1	fracBB1	0.15	-
Age at which branch and bark fraction = ½(pBB0+ pBB1)	tBB	tBB	1.5	years
Various
Ratio NPP/GPP	Y	Y	0.47	-
Basic density	r	Density	0.5	t m^-3
Conversion factors
Intercept of net radiation v solar radiation relationship	Qa	Qa	-90	W m^-2
Slope of net radiation v solar radiation relationship	Qb	Qb	0.8
Molecular weight of dry matter		gDM_mol	24	gm mol^-1
Conversion of solar radiation to PAR		molPAR_MJ	2.3	mol MJ^-1

Table 4. Names and description of output variables

Description	Output name	3-PG name	Units
Site and management attributes
Name of site given on site data sheet	Site name	siteName
Fertility rating	Fert. rating	FR
Minimum available soil water (for supplemental irrigation)	Min ASW	minASW	mm
Applied irrigation	Annual irrigation	Irrig	mm ha^-1 yr^-1
Stand attributes
Current stand age	Stand age	StandAge	years
Stand stocking	Stocking	StemNo	trees ha^-1
Stand basal area	Basal area	BasArea	m^2 ha^-1
Stand volume, main stem excluding bark	Stand volume	StandVol	m^3 ha^-1
Stand-based mean DBH	Mean DBH	avDBH	cm
Current mean annual stem volume increment	MAI	MAI	m^3 ha^-1 yr^-1
Peak MAI of stand to the current stand age	Peak MAI	MAIx	m^3 ha^-1 yr^-1
Stand age at which MAI peaked	Age at peak MAI	ageMAIx	yr
Current canopy LAI (mean annual value if output is annual)	LAI	LAI
Peak canopy LAI up to the current stand age	Max LAI	LAIx
Stand age at which LAI peaked	Age at max LAI	ageLAIx	yr
Fraction of ground area covered by canopy	Fract. canopy cover	CanCover
Biomass pools and canopy attributes
Foliage biomass	Foliage DM	WF	tDM ha^-1
Root biomass	Root DM	WR	tDM ha^-1
Stem biomass, including branches and bark	Stem DM	WS	tDM ha^-1
Total biomass	Total DM	TotalW	tDM ha^-1
Total litter fall over run	Total litter fall	TotalLitter	tDM ha^-1yr^-1
Mean stem biomass per tree	Mean stem mass	AvStemMass	kgDM tree^-1
Fraction of above ground woody biomass as branch and bark	Fract. as bark & branch	fracBB
Specific leaf area	SLA	SLA	m^2 kg^-1
Annual outputs
Light utilisation efficiency based on above ground biomass	Above ground epsilon	AbvgrndEpsilon	gDM MJ^-1
Light utilisation efficiency based on total biomass	Total epsilon	TotalEpsilon	gDM MJ^-1
Annual total evapoptranspiration	Annual ET	CumEvapTransp	mm yr^-1
Annual total transpiration	Annual transp.	cumTransp	mm yr^-1
Annual total supplemental irrigation	Annual suppl. irrigation	cumIrrig	mm yr^-1
Annual total net primary production	Annual NPP	cumNPP	tDM ha^-1 yr^-1
Growth modifiers
Age dependent modifier	fAge	fAge
VPD dependent modifier	fVPD	fVPD
Temperature dependent modifier	fTemp	fT
Frost dependent modifier	fFrost	fFrost
Soil water dependent modifier	fSW	fSW
Nutrition dependent modifier	fNutr	fNutr
Physiological modifier of canopy conductance	Phys. modifier	PhysMod
Fertility dependent modifier of root biomass partitioning	m	m

Table 4. Names and description of output variables (continued)

Description	Output name	3-PG name	Units
Biomass production and partitioning
Net primary production	Monthly NPP	NPP	tDM ha^-1 month^-1
Canopy quantum efficiency after application of modifiers	Canopy alpha	alphaC	mol mol^-1
Fraction of NPP partitioned to roots	pR	pR
Fraction of NPP partitioned to stems	pS	pS
Fraction of NPP partitioned to foliage	pF	pF
Ratio of foliage to stem biomass partitioning	pFS	pFS
Leaf litterfall rate	Litter fall rate	Littfall	month^-1
Litter fall in current period	Litter fall	delLitter	tDM ha^-1 month^-1
Stem mortality
Maximum tree stem mass at current stocking	wSmax	wSmax	kg tree^-1
Number of stems dying	Dying stems	delStemNo	trees ha^-1
Water use
Available soil water	ASW	ASW	mm
Monthly supplemental irrigation (to maintain minASW)	Monthly supp. irrig.	monthlyIrrig	mm month^-1
Monthly evapoptranspiration rate	Monthly ET	EvapTransp	mm month^-1
Monthly transpiration rate	Monthly transp.	Transp	mm month^-1
Canopy conductance	Canopy conductance	CanCond
Climatic factors
Day length (sunrise to sunset)	Daylength	DayLength	s day^-1
Mean number of frost days per month	Frost days	FrostDays	days month
Mean daily incident solar radiation	Solar rad.	SolarRad	MJ m^-2 day^-1
Mean daily temperature	Mean temp.	Tav	C
Mean daily VPD	VPD	VPD	mBar
Mean monthly rainfall	Rainfall	Rain	mm month^-1

Table 5. Climate data variables recognised by 3PGpjs

Variable name	Units	Meaning and comments
Tmax	°C	Monthly mean daily maximum temperature
Tmin	°C	Monthly mean daily minimum temperature
Tav	°C	Monthly mean temperature
Rain	mm month^-1	Monthly rainfall
Pan evap	mm d^-1	Monthly mean daily pan evaporation
Solar rad	MJ m^-2 d^-1	Monthly mean daily solar radiation
Rain days	d month^-1	Rainy days per month
Frost days	d month^-1	Frost days per month
VPD	mBar	Monthly mean vapour pressure deficit

Table 6. Names and description of site factors that can be controlled

during a sensitivity analysis

Description of site factor	Variable name
Fertility rating	FR
Maximum available soil water capacity	MaxASW
Minimum available soil water capacity	MinASW
Soil class (S, SL, CL, C) as per Table 2	SoilClass
Initial foliage biomass	WFi
Initial root biomass	WRi
Initial stem biomass	WSi
Initial stand stocking	StemNoi
Initial available soil water	ASWi

Appendix 1: Changes incorporated into 3-PG

The 3-PG code embodied in 3PGpjs differs in several ways from the 3-PG described in Landsberg and Waring (1997). The differences are the result of experience applying 3-PG to numerous data sets, and in response to my attempts to parameterise the model for E. globulus and E. grandis. I also changed how relationships are parameterised to make parameters more intuitively meaningful. The relationships themselves have not been changed, and there is a unique relationship between old and new parameter values. Table 3 lists all parameters, the names by which they are known to 3PGpjs, and a set of default values. Note that 3‑PG uses the conversion factors:

1 MJ solar radiation º 2.3 mol PAR,

1 mol C º 1 mol DM º 24 g DM .

The worksheet Tools in 3PGpjs.samples facilitate conversion between old and new parameter sets.

The following notes on changes in 3‑PG presume familiarity with Landsberg and Waring (1997).

A.1 New or changed environmental modifiers

Temperature modifier

A new modifier f_T(T_a) that depends on the monthly average daily temperature T_a has been introduced. The definition of f_T is

, (1)

where f_T = 0 if T_a £ T_min or T_max £ T_a, and T_min, T_opt and T_max are the minimum, optimum and maximum temperatures for net photosynthetic production.

Frost modifier

The functional form of frost modifier f_F(d_f) has been generalised from its original form (Sec. 2.3, Landsberg & Waring, 1997) and is now given by

, (2)

where d_f is the number of frost days in a month and k_F is the number of day’s production lost for each frost day, and may be greater or less than 1. Setting k_F = 0 switches the frost modifier “off”.

Nutrient modifier

A modifier f_N(FR) which depends linearly on the site fertility rating FR has been introduced:

, (3)

where f_N0 is the value of f_N when FR = 0.

A.2 How environmental modifiers are taken into account

The modifiers f_VPD and f_SW reduce both canopy conductance (g_c) and canopy quantum efficiency (a_C) through a multiplier j (called PhysMod in the 3‑PG code) defined by

. (4)

Here, f_age is the age-dependent modifier simulating possible decline in hydraulic properties with age (Landsberg and Waring 1977, Eqn (3)).

The temperature, frost and nutrition modifiers affect the canopy quantum efficiency (a_C) multiplicatively because these are assumed to have independent effects on photosynthesis. Thus

, (5)

where a is the theoretical maximum canopy quantum efficiency. Gross primary production P_G is then given by

(6)

where f_pa is PAR absorbed by the canopy.

Canopy conductance has been re-parameterised as follows

(7)

where g_Cx (m s^-1) is maximum canopy conductance, j is the physiological modifier, and L_Cx is the canopy LAI at which canopy conductance attains its maximum value.

A.3 Specific leaf area depends on stand age

Observations from a range of eucalypt stands show specific leaf area s (m² kg^-1) declines with stand age for very young stands. Experience with 3‑PG has shown it is unable to reproduce both observed stem biomass and canopy leaf area index of young stands unless s is age dependent. Accordingly, specific leaf area as a function of stand age t (years) is given by the empirical relationship

, (7)

where s₀ and s₁ (m² kg^-1) are specific leaf areas at age 0 and for mature stands, respectively, and t_s (years) is the stand age at which s = ½(s₀+s₁).

A.4 Loss of intercepted radiation due to non-canopy closure

It is assumed that canopy closure occurs at a stand age of t_cc years. Prior to this, intercepted PAR is reduced by the factor t/t_cc where t is stand age (in years). This does not work adequately and the default value of t_cc has been set to 0, i.e. by default the canopy is assumed to be closed at all ages.

A.5 Calculation of stand volume

Stand volume V (m³ ha^-1) is determined from above ground woody biomass W_S (t ha^-1) and basic density r (t m^-3), and is discounted for the fraction p_BB of W_S as branch and bark:

. (8)

Observations from a range of eucalypt stands show p_BB declines with stand age:

, (9)

where p_{BB 0} and p_BB1 are branch and bark fractions at age 0 and for mature stands, respectively, and t_BB (years) is the stand age at which p_BB = ½( p_BB0+ p_BB1).

A.6 Litterfall

Litterfall is applied monthly, and the monthly litterfall rate g_F is now parameterised by the rate of litterfall (g_F0, month^-1) at age 0, the maximum rate of litter fall (g_Fx, month^-1), and the age (t_gF, months) at which the litterfall rate is ½(g_F0+g_Fx). Then

(10)

, (11)

where t is stand age in months. The relationships between the new and old parameters are:

(12)

With parameters from Eqn (7) of Landsberg and Waring (1997), g_Fx=0.02 month^-1, g_F0=0.00125 month^-1 and t_g=23.6 months.

A.7 Root biomass partitioning

The relationship for the root biomass partitioning ratio h_R is now parameterised by the maximum and minimum partitioning ratios h_Rx and h_Rn so

, (13)

where j is given by Eqn (4), and m is given by Eqn (14) below. With parameters from Eqn (15) of Landsberg and Waring (1997), h_Rx=0.8 and h_Rn=0.23. The parameter m in Eqn (13), controlling how root biomass allocation depends on site fertility, is assumed to depend linearly on site fertility rating:

, (14)

where m₀ is the value of m for sites of poor fertility, i.e. FR = 0.

A.8 Foilage-to-stem biomass partitioning ratio

Landsberg and Waring (1977) expressed the ratio p_FS = h_F/h_S of foliage biomass partitioning to stem biomass partitioning as an allometric function of stem diameter B (cm) through observed allometric relationships between foliage and stem biomass and B. (Allometric relationships now assume that B is given in cm rather than mm.) As this is the only place where the foliage allometric parameters appear in 3‑PG, p_FS has been written explicitly as an allometric function of B

. (15)

In terms of the original allometric parameters a_F and n_F, and a_S and n_S, the new parameters are

. (16)

However, when calibrating 3‑PG it is more convenient to parameterise p_FS in terms of its values p₂ and p₂₀ at 2 cm and 20 cm, respectively. In terms of these,

. (17)

For example, if p₂=1 and p₂₀=0.15, then n_p=-0.824 and a_p=1.77.

A.9 Stem mortality

Stem mortality is determined by the self-thinning rule. Eqn (8) in Landsberg and Waring (1977) for the maximum permissible mean single-tree above-ground woody biomass w_Sx (kg tree^-1) as a function of the current stand stocking N (trees ha^-1) has been rewritten as

, (18)

where n_m is the exponent in the self-thinning law (nominally 3/2), and w_Sx1000 (kg tree^-1) is the value of w_Sx when the stocking N = 1000 trees ha^-1. (If stocking is 1000 trees ha^-1, this equation implies that the total above ground woody biomass on the stand at which self-thinning commences is about w_Sx1000 t ha^-1.)

If the mean single-tree above-ground biomass w_S exceeds w_Sx, mortality is applied. When a tree dies, it is assumed that its biomass is some fraction of the mean biomass of all trees in the stand. Let these fractions be m_F, m_R and m_S for the foliage, root and stem pools respectively. Let W_i⁺ and N⁺ be the stand biomass pools and stocking after mortality. Then

(19)

where the subscript i is F, R or S. Mortality induced by self-thinning requires that the stand satisfy the self-thinning law after mortality, i.e.

(20)

where the 10^-3 converts kg to t. Eqs (19, 20) give an implicit equation for N⁺, which is solved by the Newton-Raphson method. Eq (19) then gives the stand biomass pools after self-thinning.

Default parameter values are n_m = 3/2, w_Sx = 300 kg tree^-1, m_F = 0, m_R = m_S =0.2.

A.10 Interception of rainfall by canopy

The proportion I of rainfall intercepted by the canopy depends on the leaf area index L of the canopy

(19)

where I_x is the maximum canopy interception, and L_Ix is the canopy leaf area index at which interception is maximised.

Appendix 2: Notes on the 3PGpjs code

No code is protected so you are free to modify it at will – and at your responsibility!

3PGpjs.xls

This workbook contains code for the model 3‑PG itself, code for the 3PGpjs interface, including all input and output routines, and code to create and remove the 3PGpjs menu, toolbar, hotkeys, and Disclaimer and About forms. A detailed discussion of this code is inappropriate here, so I confine my comments to the following:

· 3PGpjs is coded in Visual Basic, coupled to MicroSoft Excel.

· I have used Option Explicit so all variables are, and must be, explicitly defined.

· I have attempted to isolate code for distinct aspects of the user interface into the distinct modules.

· It is my intent that the interface be easily modified. Code in the Generic_IO module avoids need to count and explicitly state which row or column a particular item of data is read from, or written to. The code knows where on the spreadsheet it is, and updates this location after each i/o operation. Insertion of new input or output between existing items is thus very easy.

The 3PGpjs code includes the following modules:

Main_Program comprises procedures that run 3PGpjs and are linked to the hot keys, toolbar buttons and menu items. The run-type (e.g. single-site) is detected and the appropriate procedure invoked, which in turn runs the code for 3‑PG.

The_3PG_Model declares all 3-PG variables and parameters, and contains code for the 3-PG model. It should be possible to export just this module in order to use 3-PG in other applications.

Climate includes code to read and pre-process climatic data in various formats.

Data_Input includes the 3PGpjs procedures for parsing all executable worksheets, and for reading site factors, initial conditions, silvicultural events, etc.

Data_Output includes procedures for displaying detailed intermediate results, annual or monthly summaries of stand development, and output from sensitivity analyses or multi-site runs.

Interface contains code defining the hotkeys, toolbar and menu, and the Disclaimer and About forms. It uses the form frmAbout3PGpjs.

Generic_IO is a module of generic procedures and functions that assist the implementation of input from, and output to, worksheets.

Parameters comprises code for reading and assigning 3‑PG parameters.

When 3PGpjs.xls is opened, code in its copy of ThisWorkbook displays the Disclaimer and About forms, creates the hotkeys, and displays the toolbar and menu item. Additional code in ThisWorkbook removes the hotkeys, toolbar and menu items when 3PGpjs.xls is closed.

3PGpjs.samples.xls

The workbook 3PGpjs.samples.xls, and workbooks copied from it, contain code in the ThisWorkbook module. This code only acts when the workbook is being opened or closed: opening the workbook in turn loads the corresponding Excel add-in (3PGpjs.xla), and closing the workbook unloads the add-in. This code is required to properly associate 3PGpjs with a workbook. Accordingly, when creating a new workbook for using 3PGpjs, it is strongly recommended that it be based on a copy of 3PGpjs.samples.xls.