README.TXT file for POPSIM 1996.09.12 POPSIM uses "stochastic" simulation techniques to describe changes in genetic structure and diversity resulting from multi- generation breeding plans in closed populations of forest trees. The theoretical basis for the simulation is described in a journal paper by T.J. Mullin and Y.S. Park (Silvae Genetica 44: 132-141, 1995). The users guide for POPSIM is available from: Canadian Forest Service -- Maritimes Region PO Box 4000 Fredericton, New Brunswick CANADA E3B 5P7 please ask for: Information Report M-X-195E (Une version française de ce rapport, M-X-195F, est disponible sur demande.) This file contains information that was not available at the time the users guide was printed, and also contains a "quick start" for those who can't wait for delivery of the manual. CONTENTS: PROGRAM NOTES AND FIXES September 1996 version 2.4.01 April 1996 version 2.3.00 March 1996 version 2.2.00 February 1996 version 2.1.02 February 1996 version 2.1.01 March 1995 version 2.0.16 DOWNLOADING FROM FTP SITE QUICK START PROGRAM DISTRIBUTION AND SUPPORT ================================================================= PROGRAM NOTES AND FIXES: *** September 1996 versione 2.4.01 *** 1. Mean of variance distributions for dominance and epistasis in progeny generations set equivalent to zero, rather than the mean for the selected parents. In effect, the D-bar and I-bar terms in equations 7 and 8 (Users guide, page 9) have been eliminated, as they are not realistic. 2. POPSIM 2.4 will underestimate gains for scenarios when positive assortative mating is requested with RANDOM initial assignment to sublines. This is ISORT options 1 and 3. All other ISORT options are handled correctly. This bug has been addressed in version 3 (under development). If you ARE analysing scenarios which use ISORT = 1 or 3, please contact me and I'll make sure you get the patch you need. *** April 1996 version 2.3.00 *** 1. Within-family variance algorithm modified - In earlier versions, genetic effects were drawn from the within-family portion of variances in the current parental population. However, it became apparent that this method gave inconsistent results between different subline sizes over multiple generations. The correct method has been verified by Lindgren and Mullin (unpublished 1996). In this method, the variances in the REFERENCE population (these are the variances given as scenario input from which trees in the base generation 0 are drawn) are corrected simply for inbreeding, as formulated by Dempfle (1990). The correction is otherwise identical to that used in versions prior to 2.2.0. *** February 1996 version 2.1.02 *** 1. Bug fixed - An error was introduced beginning in version 2.1.01 resulting from compilation of the program under Windows 95. This bug caused incorrect selection of trees for orchard populations, but is otherwised not thought to have had any other impact on POPSIM's output. A patch has been applied to the program code pending upgrading of our compiler. *** February 1996 version 2.1.01 *** 1. Bug fixed - Calculation of status number (Ns) gave erroneous results in some situations with large, sublined populations. 2. New ISORT options 3 and 4 - Users can now perform Positive Assortative Mating based on phenotypic values (or clone means) for selected parents, rather than using a polycross to rank parents based on breeding values. ISORT option 3 will use phenotypic values, with random inital assignment to sublines. ISORT option 4 uses phenotypic values, with uniform assignment to sublines. 3. Updated DOS extender files - Users of the previous release will need to update their copies of the DOS extender files, in order to run this latest version. The files affected are: DOSXMSF.EXE and DOSXNT.386. 4. Run under Window 95 - This and any previous release of POPSIM can be run under Windows 95 as a DOS application. Since Windows 95 looks after virtual memory for DOS programs, the DOS extender files required for DOS and Windows 3.1 are not required and need not be installed. The use of a Shortcut is strongly recommended. After creating your Shortcut, you can changes the Properties so that POPSIM goes to the correct working directory and so that the application window remains open if the program terminates abnormally. Right click on the Shortcut and select Properties, then select the Program tab. Specify the correct working directory where POPSIM is to read and write data. Then make sure that the "Close on exit" box is NOT checked. All other default settings should be OK. *** March 1995 version 2.0.16 *** The users guide is complete for this version. ================================================================= DOWNLOADING FROM FTP SITE: You can get a copy of the demonstration release through the Internet by downloading the self extracting PKZIPed freeware version of POPSIM (file name = popsim21.exe) from the following FTP site: fcmr.forestry.ca In the directory called: popsim i.e., login to the ftp server, "fcmr.forestry.ca", change directory to "popsim", and download file "popsimxx.exe." For example, if you use Mosaic or NETSCAPE software, type; ftp://fcmr.forestry.ca then go to popsim directory All of POPSIM's features are implemented in the freeware version, but reduced array capacity will limit the size and complexity of breeding scenarios ================================================================= QUICK START: 1. INSTALLING THE PROGRAM FILES AND EXAMPLES Begin installation by creating a new directory on your hard drive. For example, if you want to install POPSIM on drive D:, you would enter: C:\> d: D:\> md popsim D:\> cd popsim D:\POPSIM> Put the distribution diskette into drive A: and copy the files to the new directory: D:\POPSIM> copy a:*.* 2. STARTING POPSIM If your POPSIM directory is your current default directory, you can start the program simply by entering: D:\POPSIM> popsim If you want to have your data stored in a different directory, you must modify your AUTOEXEC.BAT file so that the directory containing POPSIM.EXE and DOSXMSF.EXE is listed in your PATH statement (see your DOS documentation for details on the PATH statement). Change to your data directory (for example, \SIMDATA) and start the program by entering the program name: D:\POPSIM> cd \simdata D:\SIMDATA> popsim 3. MAKING EXTENDED RAM AVAILABLE TO POPSIM POPSIM will not run in the 640K of conventional memory that is normally available to DOS programs, and requires access to a "DOS memory extender" (distributed with the program) to make "virtual memory" available in the extended memory region above 1 Mb and, if necessary, on the computer's hard-drive. If POPSIM will not load, verify that you have completed these two important steps: a) The CONFIG.SYS file must load memory drivers, in order to make extended memory (above 1Mb) and upper memory (between 640K and 1 Mb) available. Most DOS installations at version 5.0 or higher will normally include such a drivers as HIMEM.SYS and EMM386.EXE, or the user can install a third-party driver such as QEMM386, 386Max, etc. Once the memory manager is loaded, you can make portions of extended memory available for program execution, while other portions are reserved to setup a software disk cache or a RAM disk drive. b) You must also install DOSXMSF.EXE, which is the actual DOS extender that allows a 32-bit program to run under MS-DOS. The easiest way is simply to copy the DOSXMSF.EXE file into the same directory as POPSIM.EXE, or you can copy the file to any directory that is in your DOS PATH environment variable. 4. RUNNING POPSIM UNDER WINDOWS 3.1 Since Windows 3.1 is a 16-bit operating system, POPSIM must run within a DOS window to execute as a 32-bit DOS-extended program. DOSXNT.386 is a Windows DPMI device driver that is necessary if you want to run a 32-bit FORTRAN application in an MS-DOS session under Windows. To install DOSXNT.386, first copy the file from the distribution diskette to your Windows directory, using a command such as: C:\> copy a:\dosxnt.386 c:\windows\*.* Now use a text editor to add a "device" statement to the [386Enh] section of your SYSTEM.INI file. If Windows is in C:\WINDOWS, this line should be added to the end of the [386Enh] section: [386Enh] . . . device=c:\windows\dosxnt.386 You can run POPSIM from a DOS session started under Windows, or as a program item icon in Program Manager. When setting up a program item, we strongly recommend that you specify a command line to run POPSIM from a "PIF" file; this will help ensure that Windows allocates memory properly to the DOS memory extender. A sample PIF file (POPSIM.PIF) has been provided on the distribution diskette and can be edited as necessary to specify the appropriate program and startup directories on your system. Further, we recommend that you ensure that the "Close Window on Exit" box is NOT checked; this will leave the window open with any error messages visible should your session encounter a fatal error. See your Windows user's guide for instructions on how to set up a new Program Item and modify a PIF file to start POPSIM from an icon. ================================================================= PROGRAM DISTRIBUTION AND SUPPORT Customized versions of POPSIM with expanded capacity can be obtained under license through the software developer: Genesis Forest Science Canada Inc. CP 64, Succ. Haute-Ville Québec, QC G1R 4M8 E-mail: genesis@fox.nstn.ca If you have questions or run into difficulty: Genesis does not, at this time, offer full-time technical support of this software, but we do want to help you when you run into difficulty and certainly want to know if you discover a bug in the program. A copy of your "response file" is the best way to help us reproduce the problem. Please contact us at the address given above, but be aware that work and travel schedules may cause a delay in responding to your question.