An introduction to PC-TRIM

Historic, archived document

Do not assume content reflects current
scientific knowledge, policies, or practices.

a

“\ Department of
4a) Agriculture

<==” Forest Service

<a, United States
ER.

Pacific Northwest
Research Station

Research Note
PNW-RN-491
October 1989

Abstract

Introduction

System
Requirements

An Introduction to
PC-TRIM

John R. Mills

The timber resource inventory model (TRIM) has been adapted to run on person: - a
al computers. The personal computer version of TRIM (PC-TRIM) is more widely ~2
used than its mainframe parent. Errors that existed in previous: versions of TRIM
have been corrected. Information is presented to help users witli program input

and output management in the DOS environment, to understand the differences
between PC-TRIM and mainframe TRIM, and to avoid common mistakes that can
lead to program-generated errors.

Keywords: Timber resource inventory model (TRIM), inventory models, computer
software.

The personal computer timber resource inventory model (PC-TRIM) is an up-
dated version of the original mainframe TRIM program. The PC-TRIM model

is four separate programs that have been compiled to run on IBM-compatible
personal computers. | Because of the growth in use of personal computers by
forest analysts, PC-TRIM has more users than does the mainframe version. The
publication written to support TRIM (Tedder and others 1987) was written for the
mainframe version; but, the format of the input and output is the same for both
models, so Tedder and others is also a reference for PC-TRIM users. This intro-
duction to PC-TRIM is intended to supplement Tedder and others (1987) with the
information necessary to use the model on a personal computer. It contains the
system requirements and hard disk installation information; it is assumed the
reader is already familiar with the DOS operating system. Differences between
the PC and mainframe versions are discussed in the appendix.

The PC-TRIM system consists of four programs written in the FORTRAN 77
standard. The PC-TRIM programs have been compiled by using RM/FORTRAN™
version 2.4, (Ryan-McFarland Corp.). Running PC-TRIM on a microcomputer requires
the following hardware and software:

At least 400K bytes of memory for program execution.

Hard disk, bernoulli drive, or memory disk of at least 1M byte.
DOS 2.1 or later.

Math-coprocessor chip (8087, 80287, or 80387).

The use of trade, firm, or corporation names in this publica-
tion is for the information and convenience of the reader.
Such use does not constitute an official indorsement or ap-
proval by the U.S. Department of Agriculture of any product
or service to the exclusion of others that may be suitable.

JOHN R. MILLS is a research forester, Forestry Sciences
Laboratory, P.O. Box 3890, Portland, Oregon 97208-3890

The PC-TRIM
System

This section contains a summary of the four PC-TRIM programs and their inputs and
outputs. For more details see Tedder and others (1987). The following four programs
make up PC-TRIM:

Program Function

BRUSCN.EXE Inventory data processor

GRUSCN.EXE Growth, yield, and timber management data
processor

ACUSCN.EXE Harvest and simulation contro! data

processor, matches inventory with manage-
ment parameters
TRIM.EXE Timber projection program

The first three programs Process input files and each produces two output files;

one for the user, and one for input to another program (see fig. 1). The process-
ing includes a check for errors in identity codes, formatting errors, and value checks
against preset limits. The program BRUSCN processes the input file containing the
beginning timber inventory. The GRUSCN program processes the input file contain-
ing the growth, yield, and timber Management parameters. The ACUSCN program
has two functions: First it processes the timber harvest parameters. Second, it links
the timber inventory data processed by BRUSCN and the appropriate growth and
yield parameters processed by GRUSCN. The ACUSCN program produces the in-
put file for the TRIM program.

Figure 1 shows how a PC-TRIM simulation can be organized into two levels of ac-
tivity. At the first level are the programs BRUSCN and GRUSCN: at the second are
the ACUSCN and TRIM Programs. Both programs in level 1 must finish without er-
rors before the programs in level 2 can be run. Programs in level 1 do not need to
be run in a particular order. In level 2, however, ACUSCN must always be run be-
fore TRIM, and both programs must be run for each new simulation. The programs
in level 1 may not need to be rerun for every simulation; for example, if changes are
made to just the ACUSCN input (harvests, report request, etc.), then only level 2
needs to be rerun.

Level 1

BRURAF

Level 2

BIGRAF

Figure 1—The organizational flowchart of a PC-TRIM
simulation divided into two levels of activity.

The PC-TRIM system is organized by input files, programs, and outputs, as shown
in the following tabulation:< -

Level Input Program Output

1 INVEN —> BRUSCN —> BRURAF, LIST.BRU
CONTROL —> GRUSCN —> GRURAF, LIST.GRU

2 BRURAF —
GRURAF —
HEADER > ACUSCN —> BIGRAF, LIST.ACU
BIGRAF —> TRIM —> DETAIL, CALLS, OUTPUT,

DUMP, CURRAF

Output Files The BRURAF and GRURAF output files are direct-access binary files used in
level 2 by the ACUSCN program. Because they are binary files, they cannot
be altered in a regular text editor. The ACUSCN program will not run unless
both the BRURAF and GRURAF files are Present (in the same subdirectory as
HEADER).

The LIST files contain an organized report of all input values. If a program en-
counters input records out of order, values out of range, mismatched or missing
inputs, or other errors, error messages or warning messages are written in the
appropriate LIST file.

The most important listing is the output LIST.ACU. It contains a report of the be-
ginning inventory by GRU including stocking (inventory volume divided by yield
table volume) calculated for each age class in each management intensity (that is,
for each yield table). The user should become familiar with this report because it
illustrates the relation between the yield table volume and the beginning inven-
tory volume. At the bottom of the output file is the “tree report,” which accounts
for each BRU, GRU, and ACU found in INVEN, CONTROL, and HEADER. In this
report, the BRU’s making up each GRU are listed, and any BRU’s or GRU’s pres-
ent but not matched are flagged. This is a good place to check to be sure that the
identity codes are matching up and the inventories are being accounted for.

The BIGRAF output file is a direct access binary file containing the compilation of
all PC-TRIM inputs. This is the only input file for the TRIM program, and it must be
present for TRIM to execute.

The CURRAF output file is a direct-access binary file created by the TRIM program
during the simulation. It is used by the TRIM program to store and update the
projected inventory as the simulation progresses. This file contains the database from
which TRIM reports are generated. It cannot be edited with a text editor, and it has
no value after a simulation (unless the user develops a special program to read it).

? Also see figure 2 in Tedder and others (1987).

Setting Up Your
System

The DETAIL output file is the simulation report requested by the user (on HEADER
card types 03 and 05). If a high level of detail was requested, this file may be very
large (that is, a report of each GRU in each period). Printing this file for each run of
TRIM can be time consuming. | recommend that after each simulation the user first
print (or check in an editor) the last section in this file titled “SUMMARY REPORTS.”
This section contains a condensed record of the simulation results; that should pro-
vide enough information for the user to determine whether the simulation ran suc-
cessfully. Then, if the file is needed, it can be printed.

- The CALLS output file contains a listing of the subroutines called by the TRIM

program as the simulation progressed. This file can usually be ignored; however,
if the TRIM program aborts, this file contains error messages (at the bottom) that
may indicate the source of the problem.

The OUTPUT output file is a simple record of the simulation progress by projec-
tion year. It can usually be ignored, but if an error occurs during the simulation, check
it for an informative error message.

The DUMP output file is normally empty. This file is for the convenience of the user
attempting to modify and test new program code. There are three different dump
subroutines in the TRIM program, but with the exception of RETURN statements,
they are empty. A user attempting to modify and test the TRIM program code can
use the DUMP output file as a place to write diagnostic output (that is, values of
particular variables at the completion of each subroutine). If GRU card type 03 has
been set, the DUMP subroutines are called at the end of each program subroutine
or if an error is detected, or both. This is a practical feature, but it is up to the user
to customize the DUMP subroutines with write statements to get diagnostic output.

Note: The ASCII (American National Standard Code for Information Interchange)
input files are 80 columns wide, and the ASCII output files are 122 columns wide.
“Condensed” print mode is required to print the output files on an 80-column printer.

The following section is provided to help users efficiently run the PC-TRIM programs
on a microcomputer. The programs themselves are large, and they create numerous
large output files. To avoid system errors, the computer's CONFIG.SYS file should
contain the following minimum parameters:

Buffers = 20

Files = 20

Fcbs = 20,20 (if using DOS 3.x)

Break = on (not required but recommended)

If the CONFIG.SYS file does not contain these settings, add them and reboot
the system before attempting to run PC-TRIM programs. These settings should
not interfere with the operation of any other software, so they can remain in the
CONEFIG.SYS file when PC-TRIM is not being used. If these parameters are un-
familiar, reference “configuring your system” in your DOS manual. (If “buffers”
and “files” are currently larger than 20, they do not need to be changed.)

Batch Files

Using RAM Memory

To run any of the PC-TRIM programs, a special parameter is required to allow Ryan-
McFarland FORTRAN to read and write long direct-access input and output records.
The following parameter needs to be entered on the command line just after the
program name: /R 35000. To run the BRUSCN program enter: BRUSCN/R35000°
(either upper or lower case). Because this is an awkward command, it makes sense
to use batch files to save keystrokes (and errors); for example, the batch file called
GOBRU needs to contain a one line entry: BRUSCN/R35000. To easily run level 2, a
batch file called LEV2 could contain the following:

ACUSCN/R35000 and TRIM/R35000.

When ACUSCN finishes execution, TRIM starts. (If ACUSCN finishes execution after
detecting errors, the TRIM program, by default, will abruptly stop.)

Batch files can be developed to erase unneeded files after a run. Each new simula-
tion creates a new LIST.ACU, BIGRAF, CURRAF, OUTPUT, CALLS, DUMP, and
DETAIL file. Maintaining files can be made easier by using one batch file to delete
these files after a simulation (be sure to first rename any files that should be saved;
that is, LIST.ACU and DETAIL). If you are unfamiliar with batch files, see your DOS
manual. Batch files save keystrokes for many repetitive tasks.

The PC-TRIM programs are “disk intensive,” meaning that a program will spend a
large fraction of the total processing time reading and writing files on the disk. An
increase in the disk access speed can significantly reduce the time required for PC-
TRIM to complete a simulation. This can be accomplished by using PC-TRIM on
computers with fast disk access times. The programs will run fastest when random
access memory (RAM) configured as a disk drive is used. This is where a PATH
statement (described below) will really be useful, because a RAM drive is usually
limited in size (the PC-TRIM programs take up about 500K bytes). A RAM drive may
require an addition of an expanded (or extended) memory board to the computer. For
the execution of PC-TRIM, a RAM drive of 3 to 4 megabytes should be sufficient;
however, a simulation using 50 or more GRU’s will require prudent file management.

One final reminder concerning RAM drives; they lose all memory when the power is
off. The inputs INVEN, CONTROL, and HEADER will need to be copied to the RAM
drive before the run. When the run is finished, copy the inputs back to the hard disk
only if they need to be saved (that is, if they were edited after being copied to the
RAM drive). If DETAIL is worth keeping, it can be renamed and copied to a subdirec-
tory on the hard disk. All files left on the RAM disk will be erased when the computer
is turned off.

3 The minimum record-length parameter required for each
program is different; that is, BRUSCN will run with a record-
length parameter of 8000. The value 35000 is slightly more
than the minimum required for TRIM to run, and larger
values cause no problems; so for simplicity, the same num-
ber was used for all programs.

File Handling

The PC-TRIM programs require and create 14 input and output files. Some users
may want to simplify file management by using DOS subdirectories to separate
the PC-TRIM programs and batch files from the input and output files. Subdirec-
tories should be used to keep related sets of inputs and outputs in one place.

The program files can be stored apart from the inputs and outputs by invoking the
DOS PATH statement. The PATH statement will act to bridge subdirectories so
that the program and batch commands will operate as if they reside locally. It is
possible to run PC-TRIM from any subdirectory (or disk drive) as long as the input
files (INVEN, CONTROL, and HEADER) reside in the “current” directory. A PATH
statement can be issued from the keyboard or added to the AUTOEXEC.BAT file.
The following example illustrates how to create subdirectories for the program and
input files, and how to add the PATH statement to the AUTOEXEC.BAT file:

First create the subdirectories PCTRIM and DATA with the commands
MD\PCTRIM and MD\DATA .

Modify the path command in the AUTOEXEC.BAT file to contain the string:
C:\PCTRIM .

A change to the path statement might look like this:

Before: path c:\dos;c:\fortran

After: path c:\dos;c:Mortran;c:\petrim

if there is no PATH command in the AUTOEXEC.BAT file, see the DOS manual and
create one. A PATH statement will allow the DOS command (COM) files to be stored
together in a subdirectory rather than in the root directory. Be sure to include that
subdirectory in the PATH statement. The modification to AUTOEXEC.BAT will remain
transparent; PATH can be invoked at all times without affecting the performance of
other applications.

Copy the PC-TRIM EXE and any BAT files into the C:\PCTRIM subdirectory, and
copy the input files (INVEN, CONTROL, HEADER) into the subdirectory C:\DATA .
The PC-TRIM programs can now be run from the \DATA subdirectory by using the
appropriate commands (BRUSCN/R35000, or GOBRU, etc.). All PC-TRIM output
files will be written to the \DATA subdirectory. With the use of the PATH command
shown above there is no restriction as to the subdirectory, or drive, which must be
current to run PC-TRIM; for example, a user can insert a floppy disk in drive A:,
which contains the INVEN file, and issue the GOBRU command from drive A:. The
BRUSCN program located in C:\PCTRIM reads INVEN from A: and writes the out-
puts to drive A:. Again, this procedure works well with a RAM drive for fastest per-
formance. The PC-TRIM programs will load into memory (used by the operating
system) from the hard disk, and all file reading and writing takes place on the RAM
memory disk rather than on a physical disk.

Literature Cited

Appendix
History

A word of caution. Create a logical system to rename the input and output files.
With a single simulation involving 14 files that always have the same names, it

iS easy to become confused over the differences between sets of inputs and out-
puts. | recommend using one subdirectory or drive to make most simulations. This
is much the same procedure followed when using a RAM drive in which to run the
programs. Create inputs in a separate subdirectory and copy them to a scratch sub-
directory dedicated to input and output files. After the simulation, edited inputs and
Savable outputs can be renamed and copied into other subdirectories for Saving.
When a session is finished, CURRAF and BIGRAF should be deleted because they
will have no further use and they occupy disk space.

Beuter, John H.; Johnson, K. Norman; Scheurman, H. Lynn. 1976. Timber for
Oregon's tomorrow. Res. Bull. 19. Corvallis, OR: Oregon State University, Forest
Research Laboratory. 111 p.

Tedder, P.L.; La Mont, Richard N.; Kincaid, Jonna C. 1987. The timber resource
inventory model (TRIM): a Projection model for timber supply and policy analysis.
Gen. Tech. Rep. PNW-GTR-202. Portland, OR: U.S. Department of Agriculture,
Forest Service, Pacific Northwest Research Station. 82 p.

Tedder, Philip L.; Schmidt, James S.; Gourley, Jonna. 1980. TREES: timber
resource economic estimation system, volume |: a user's manual for forest
Management and harvest scheduling. Bull. 31a. Corvallis, OR: Oregon State
University, Forest Research Laboratory. 81 p.

U.S. Department of Agriculture. 1988. The South’s fourth forest: alternatives for
the future. For. Resour. Rep. 24. Washington, DC: U.S. Department of Agriculture,
Forest Service. 512 p.

The origin of PC-TRIM can be traced back to the model developed for use in a study
of the timber resource in Oregon (Beuter and others 1976). That model became
known as TREES and was well documented by Tedder and others (1980). Tedder
began the development of a new model based on the TREES system in 1981, this
model became known as TRIM. The onginal TRIM model was compiled on a CYBER
170/720 at Oregon State University. The conversion to a PC version began in 1986
by K. Norman Johnson of the College of Forestry, Oregon State University.

Since the development of initial microcomputer version, both the mainframe and PC
versions of TRIM have been modified. The mainframe version was modified for use
in the fourth forest study (U.S. Department of Agriculture 1988) to accommodate
input from a complex area-change model. The sequencing of growth and harvest
was changed so growth would be reported with the beginning of the period inventory.
Figure 6 in Tedder and others (1987) represents the fourth forest version.

|

]
i]
I
|
|

Changes to PC-TRIM

Rounding Problems

The differences between the PC version and the southern study version include the
sequencing of growth and harvest and the reporting of growth-on-harvest. The result
of these differences is that, given the same inputs, the two models will produce differ-
ent projections of inventories.

The PC version uses the same sequencing of harvest and growth as the original
mainframe version. The biggest difference between PC-TRIM and the southern
study version is the sequencing of activity in the “zero-period” or starting period.
Compare figure 2 in this paper and figure 6 in Tedder and others (1987). In PC-
TRIM, when period equals zero, there is a shortcut across the loop and the first
action is the summing of current (or beginning) inventory. In figure 6 (Tedder and
others 1987) the shortcut does not exist; instead it appears that when period equals
zero, harvest allocated first. But figure 6 does not clearly represent the activities in
period zero. In the starting period, the first time through the loop, harvest is set to
zero so that harvest and regeneration of harvested acres is skipped. The projec-
ted period starts with area change, thinning, and growth, with the effect that har-
vest and regeneration occur at the end of the period.

In PC-TRIM the beginning inventory is summed, harvest occurs, and at the end
of the period, growth takes place. Because harvest occurs at the start of the per-
iod, growth-on-harvest must be used if it is assumed that harvest will occur over
the entire period (or at the middle of the period). Growth-on-harvest is an option
with southern study TRIM, but because a full period of growth is applied to the
inventory before harvest, it is not logical to use it.

The PC-TRIM program was modified to allow for donor-acre shifts to occur before
harvest in the first period (allowing for the option of volume to be captured and
partially fulfill the first harvest request). The subroutine DONORS is executed

at the start of a period (after the beginning inventory is summed) rather than

after harvest (see fig. 2 in this paper and fig. 6 in Tedder and others [1987]).

A PC does not necessarily carry the same precision or use the same rounding
scheme as a mainframe computer. A mainframe such as the CYBER has a 60-bit
word length that allows more places of precision than does a microcomputer with
a 32-bit (single precision) unit length. The TRIM program contains many error-
checking algorithms that often depend on a high level of precision (double preci-
sion). The single precision and rounding that takes place on the microcomputer
will sometimes cause problems for GRU card types 28 and 38 in the program TRIM.
Card type 28 is an Ml-shifting card that might have portions summing to 1.00. The
GRU card 38 allocates a proportion of the harvest to an age class, and the total
proportions should sum to 1.00. (See Tedder and others [1987] for more details
about these GRU card types.) While TRIM is running, it checks the total propor-
tion of acres shifted or harvested; if they sum to more than 1.0000, an error mes-
sage is written to the CALLS file and the program aborts.

TRIM

Run level
initialization

Time = 0

Fine! ceteil
yes and summary
repons STOP

Time level
initialization

FINAL

TimexTime + 1

yes

ACU level

Compute GRU
Inivalization Proponion of
seats harvest

PROPRT

Bring In
GRU Gata

Aggregate
Svalladie harvest

GRUINT

AGGREG

Donor shifts

N:
and exogenous oc lth
harvest: CNVERS
conversion, THIN
thinning,
mortality wilds:
salvage
Comput

Allocate gromn
harvest
ALOCAT
GROW

GRU report

Regeneration Compute next
for es (regular and period's
P unstocked) inventory

REPORT

Sd

SHIFT

Figure 2—Flowchart of the PC version of the TRIM program.
The names of subroutines are in capital letters.

a

|

Growth Carryover

These errors can be avoided by adjusting proportions (within a GRU) so that the
total is slightly less than 1.0000. In the case of GRU card 28, the error may occur
when 100 percent of the acres are shifted out of any one management intensity (MI)
category. The problem can be eliminated by reducing the acreage shift by less than 1
percent; for example, if the total shift out of Ml 1 equals 1.00, then lower one card 28
so the that new total is equal to 0.9999 . The same strategy applies to GRU card
type 38; the sum of the harvest proportions should be slightly less than 1.00 (0.9999
works fine), however, if the difference between 1.00 and the lower sum is too great,
the GRUSCN program will indicate an error. This solution to the error-checking prob-
lem should not significantly alter projection results.

For versions of PC-TRIM older than January 1989, growth-on-harvest can be incor-
rectly summed into the wrong ACU’s. This will happen only when multiple ACU’s are
used and the number of harvest values in the HEADER file exceeds the number of
periods in the simulation. The model will always attempt to make one extra harvest,
so if there are eight harvest values in HEADER but the simulation is for five periods,
the model will make a total of six harvests. The sixth harvest represents an action

in the period beyond the last reported inventory. (In the final period of the simulation,
the subroutines ALOCAT and REPORT are called from the subroutine PROPRT.
This is not shown in fig. 2.) A problem occurs because growth-on-harvest is calcu-
lated for the extra harvest. The regular growth routine does not get called, and this
growth gets carried into the next ACU where it is incorrectly summed into the growth
reported for the final period. To avoid this problem do not enter more harvests than
there are periods. In the case above, three zeros can be entered to fill out the eight
harvest entries.

11

The Forest Service of the U.S. Department of
Agriculture is dedicated to the principle of multiple
use Management of the Nation's forest resources
for sustained yields of wood, water, forage, wildlife,
and recreation. Through forestry research,
cooperation with the States and private forest
owners, and management of the National Forests
and National Grasslands, it strives—as directed by
Congress—to provide increasingly greater service
to a growing Nation.

The U.S. Department of Agriculture is an Equal
Opportunity Employer. Applicants for all Department
programs will be given equal consideration without
regard to age, race, color, sex, religion, or national
Origin.

Pacific Northwest Research Station
319 S.W. Pine St.

P.O. Box 3890

Portland, Oregon 97208-3890

GPO 791-171/20000