Historic, archived document Do not assume content reflects current scientific knowledge, policies, or practices. a “\ Department of 4a) Agriculture <==” Forest Service 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