CRiSP1 Passage README File last updated: Tuesday, 21-Dec-1999 13:42:31 PST ------------------------------------------------------------------------ CRiSP.1.6 is a cross-platform program which models passage and survival of multiple salmon substocks through the Snake and Columbia rivers and their tributaries and the Columbia River Estuary. The model is being applied to the Columbia River. As a result, the files describing the river and release points of fish into the river are an essential part of the model. A list of references pertaining to model theory and calibration can be found in the Theory, Calibration and Validation Manual. We expect to release the completely updated version in 2000. (The older Unix version is available online at: http://www.cbr.washington.edu/crisp/models/crisp1manual/.) The model is designed to run on Windows 95/NT operating systems or Sun SPARC workstations running Solaris2.5.X operating system. CRiSP.1 has been tested in both environments. Our expectation is that the application will look and feel the same on both types of computers and will produce the same numerical results to within 6 significant figures (small differences in numerical results may be observed because of the different ways that PCs and SPARCStations deal with roundoff errors). This is a complete implementation of the CRiSP Passage model, with all major functions available. CRiSP.1 was developed at Columbia Basin Research, School of Fisheries, University of Washington, under a contract from Environment, Fish and Wildlife, Bonneville Power Administration (BPA). Windows 95/NT minimum system requirements: Windows 95 or Windows NT or later, 486/66 Mhz, 16 MB of RAM, and 40 MB available hard disk space to install. Unix system requirements: Solaris 2.5.x operating system or later and 45 MB available hard disk space to install. The directories /usr/openwin/lib and /usr/dt/lib must exist and contain the standard system libraries. ------------------------------------------------------------------------ Files and directories in the CRiSP.1 distribution: Following is a list of all files and directories associated with a full CRiSP.1 release. All of the files should reside in the same directory. Win95/NT Unix crisp1.exe crisp1.executable CRiSP.1 executable crisp1b.exe crisp1bat.exe CRiSP.1 executable for Batch Mode (no GUI) - crisp1 CRiSP.1 shell script columbia.desc columbia.desc Default river description file which contains an abbreviated description of the Columbia Basin river system with about thirty fish release points and major dams. Some rivers in the basin are not represented in this map (for example, Imnaha River or Grande Ronde River). base.dat base.dat Sample user data file for use in scenario mode, or as a yearly input file in monte carlo mode. Contains calibrated parameters with stochastic variability. This file is read automatically by CRiSP.1 on startup. base.sample.rls base.sample.rls A set of sample releases, loaded automatically on startup by the base.dat file. flow.archive flow.archive Sample flow archive file for use in Monte Carlo Mode. - zapp.ad Xresource file for proper colors crisp1.zhp crisp1.zhp Help file containing basic text for CRiSP online help. zhelp.exe zhelp Help viewer executable README README This file. columbia_snakedraw.desc columbia_snakedraw.desc Alternative river description file that does not include any of the Snake River dams in it. This simulates a Snake River drawdown in order to make the Snake River free-flowing. It has four dams removed that are in the default columbia.desc file: Lower Granite, Little Goose, Lower Monumental, and Ice Harbor dams. columbia_drawdown.desc columbia_drawdown.desc Alternative river description file in which the four Snake River dams are removed as well as the John Day dam. This represents the most drawdown being considered. flow.data flow.data Directory containing a number of other sample flow archive files for use in Monte Carlo Mode. yearly.data yearly.data A directory containing other user data files corresponding to yearly historical conditions. ------------------------------------------------------------------------ CRiSP.1.6 Highlights: Updates, Changes and New Features Version 1.6 of the CRiSP Model includes many updates, changes and new features. Yearly Input Data Files from previous versions of the model can be converted into the new version data files by reading the files into CRiSP.1.6 and writing the data out to your local system. We recommend using the CRiSP.1.6 calibrated values. Changes to the model in version 1.6 include improvements to the internal operation of the model and the graphical user interface (GUI). The following list highlights many of the improvements to the model. * Total Dissolved Gas. Dissolved gas production algorithms have been completely replaced. New model features include Reach Gas Theta, Dam Gas Theta, K Entrain, and three new TDG Saturation equations (Day, Night, and Backup). The new equations have new parameters and new functional forms. * Predation. The predation submodel has been improved. The predator density / volume interaction algorithm has been changed completely. A new parameter, the Predator Distribution Coefficient, controls the new interaction. The Predation Temperature Response Equation was updated. * Delay Equation. The Dam Delay Equation algorithm has been completely replaced. * FLUSH Model. We have added the capability to calculate mortality based on the FLUSH Model (based only on running time since release). New model features include the Simple Mortality Equation and the FLUSH Transport Merit Equation. FLUSH Model equations and parameter values were based on work completed for the PATH process. Marmorek, D.R., et al. 1996. Plan for Analyzing and Testing Hypotheses (PATH): Final report on the retrospective analysis for fiscal year 1996. Compiled and edited by ESSA Technologies Ltd., Vancouver, B.C. * Gas Distribution. The Gas Distribution window displays dissolved gas distribution along a given reach. This is the only graph window in CRiSP Passage whose X-axis represents space (river miles) rather than time (days). * Reach Regulation Points. CRiSP.1 can now process reach flow data in flow archive files. Reaches can be potential regulation points, and if a reach flow is given in the flow archive, it is propagated upstream to headwaters, and downstream as losses, in just the same way that flow archive data for dams is handled. * Basin Volumes. It is now possible to graphically edit basin volumes for headwaters with storage basins (Hells Canyon, Dworshak, and Chief Joseph dams, currently). Headwater flow, basin volume, and dam outflow are all editable and all interact with each other automatically and appropriately. * Upstream Propagation. Upstream propagation of elevation changes now runs through forks more realistically. The Fork Threshold parameter defines how big a fork must be before elevation changes propagate up it. * Graph Window Features. Graph windows have become more capable: a second toolbar allows the user to select drawing method, switch between automatic and fixed scaling, and to group several graph windows together so that they use the same vertical scale. * Keyboard Control. Keyboard control of dialog windows has been implemented. Calibration of the CRiSP model to PIT tag data has been upgraded. CRiSP.1.6 has been calibrated, via a minimization of sum of squares, to PIT tag travel time data (courtesy of Pacific States Marine Fisheries Commission) and to National Marine Fisheries Service (NMFS) survival estimates. This is performed iteratively; alternating between calibration of travel time and of survival. All other model data and parameters are chosen or calibrated first so that the model best fits the travel time and survival data sets. The calibration has been done for Snake River releases of spring chinook and fall chinook for the years 1993 to 1998 and steelhead for the years 1994 to 1998. The calibrated model predictions were compared to the average 1999 survival estimates. Model predicted survivals were compared to 1999 estimates. For example, estimated spring chinook survival between the tailraces of Lower Granite and Bonneville dams was 52% for the model and 56% for the PIT tag estimate. ------------------------------------------------------------------------ Win95/NT Download and Install 1. Download the current version of CRiSP.1 (Win32) from the Columbia Basin Research web site (http://www.cbr.washington.edu/crisp/crisp.html) or ftp the self extracting archive from the Columbia Basin Research's FTP site (ftp://www.cbr.washington.edu/crisp1/pc/crisp1.exe). With a 28.8 modem, downloading the model takes approximately 30 minutes. 2. Save to the directory of your choice when downloading. If you have problems downloading the model, try connecting directly to our ftp site (1. login: anonymous; 2. password: your email address; 3. cd crisp1/pc/; 4. get crisp1.exe). 3. Double click on the self-extracting file crisp1.exe icon or launch crisp1.exe from a Run dialog box. 4. A "WinZip Self-Extractor" dialog box will open. Select a destination directory for the install directory (Install) and subdirectories (Disk1 - Disk5). 5. Click Unzip to start the extracting process. Note. You can leave the check mark on "Overwrite Files Without Prompting" to shorten the upgrade process. 6. When the extracting process finishes, click OK. 7. Click Close to quit the "WinZip Self-Extractor" dialog box. 8. Change to the specified unzip destination directory. 9. Open the Install\Disk1 directory and double-click on the setup.exe icon. 10. Follow the on-screen instructions. 11. When you have finished installing CRiSP Passage, you can delete the Install directory and the self-extracting file crisp1.exe. Unix Download and Install 1. Download the current version of CRiSP.1 (Unix) from the Columbia Basin Research web site (http://www.cbr.washington.edu/crisp/crisp.html). The tar file includes all help files, sample data files, and executable files. 2. Save to the directory of your choice when downloading. If you have problems downloading the model, try connecting directly to our ftp site. cd crisp1/unix get r1.6.0.tar.gz quit 3. To extract the files, copy the tar file into your desired installation directory and type the following commands: gunzip r1.6.0.tar.gz tar -xf r1.6.0.tar 4. This will create the directory "r1.6.0" containing all the data files and executable files. 5. When you have finished installing CRiSP Passage, you can delete the r1.6.0.tar file. Starting from the Desktop (Windows 95/NT) There are several ways to start CRiSP.1 using the graphical interface from your Desktop. * Double-click the CRiSP.1 icon. OR * Click the Start button, point to Programs, and click CRiSP Passage. OR * Click the Start button, point to Run, and click Browse to find and open CRiSP.1 on your computer. Wait for the CRiSP.1 Graphical User Interface and River Map to appear. Basic information about CRiSP.1, model parameters, and running CRiSP.1 are covered in the model Help system. Starting from the Command Prompt To start CRiSP.1 from a command prompt, the model must be in the current directory (or, on Unix only, in the path). At a command prompt, type a command with the following syntax: crisp1 [-l{wmrd}] [-bsmi] [-r river_desc] [-f data_file] [-o output_file] [-c output_control_file] [-u] On the Unix system, this invokes a shell script which runs the model (see end of file for further details about the shell script). You can pass any standard crisp arguments to this shell script. The arguments delimited by "[ ]" are all optional and can be given in any order. If an argument is not present, the default value is used. -l{wmrd} controls the logging level. Five separate classes of logging messages are defined: Errors which are always logged, Warnings, Messages, Raw output, and Debug output. By default, Warnings are logged and the others are not. If -l is given, then the default is ignored and the characters which follow define what is logged. For example -lwm causes Warnings and Messages to be logged, -l causes nothing (except Errors) to be logged, -ld causes only Debug output to be logged, and -lr causes Raw output to be logged. -bsmi controls the running mode. b selects Batch Mode (the default is Graphical User Interface mode). s selects Scenario Mode. m selects Monte Carlo Mode (which is the default in Batch Mode). i selects Realtime Mode. The letters can be combined in various ways and not all need to be included. -bsi would select Batch Realtime Scenario Mode. -b selects Batch Monte Carlo Mode (since Monte Carlo Mode is the default for Batch Mode). Batch Monte Carlo Mode runs depend on the existence of a .crisp-alts file which specifies which alternatives to run. Note. Realtime Mode is only active in batch mode, not through the GUI. In either Scenario or Monte Carlo mode, the model default is to run with a yearly data file realtime.dat unless an alternate yearly data file is indicated with the -f flag. Running in Realtime Mode will create a realtime subdirectory with several default files, of particular interest is realtime.real file which is the output file. For Realtime Monte Carlo mode runs, a flow file named flow.archive must reside in the run directory. In Realtime Monte Carlo Mode, the model does not depend on the .crisp-alts file to determine which alternative and which files to use. -r river_desc specifies the name of the river description file. The default file is columbia.desc. -f data_file specifies the name of the yearly data file. The default file is base.dat. -o output_file specifies the name of the parameter data file to output at the end of a batch run. This option can only be used in conjunction with the -b argument. Only one -o option is allowed for any given batch run. The extension of the output filename determines what parameter data used during the model run will be written to the file. -c output_control_file gives the name of the parameter data configuration file to be used for the entire batch run. This option can only be used in conjunction with the -b argument. Either a file of type .dat or .cnf may be specified. If this option is given, the program as it starts up first reads columbia.desc, then it reads the "output_control_file" and turns on the Lock Output Settings feature, then it reads the yearly input data file (ignoring any output settings contained therein), and then it runs the model in batch mode, as specified by the other command line arguments. This option is intended to facilitate control of data output in batch mode processing. -u indicates that a summary.alt# file should be written for each alternative run, exactly as if the "Write Supplemental Data" check box had been checked in the GUI Monte Carlo window. Data written to the file is based on the output settings in the yearly input data file(s) specified in each alternative. This option can only be used in conjunction with the -b{mi} argument. Example commands that open the CRiSP.1 Graphical User Interface crisp1 crisp1 -lmw -r columbia_drawdown.desc -f new.dat crisp1 -f test.dat Example commands that run CRiSP.1 in batch mode crisp1 -b -o batch.ctrl crisp1 -b -c batch.dat crisp1 -bsi -f realtime.alt.dat crisp1 -b -u ------------------------------------------------------------------------ Running in Batch Mode The CRiSP Passage model can be executed in batch mode for either Monte Carlo or Scenario runs. See the above section for command options. The following are special instructions on running in batch mode for both Unix and Windows 95/NT operating systems. Unix: On the Unix system, batch mode runs can be executed from the command prompt using any of the options detailed in the above section. There are a few special considerations for running CRiSP.1 in batch mode on Unix systems. The CRiSP.1 Unix distribution includes the program crisp1bat, which is the simulation engine of CRiSP.1 without the graphical user interface. Using this program, you can run CRiSP.1 in batch mode without having to set the DISPLAY environment variable. This makes it possible to run the CRiSP.1 model in batch mode from a dial-up connection or from a detached process, i.e. left running after logging off the workstation. The crisp1bat program uses the same command prompt arguments as crisp1, except that the -b is assumed. Example commands crisp1bat -o batch.ctrl crisp1bat -c batch.dat crisp1bat -u Windows 95/NT: There are a few special considerations for running CRiSP.1 in batch (non-graphics) mode on Windows 95/NT systems. These derive from the architecture of Windows 95 and Windows NT, which make sharp distinctions between MS-DOS-based programs and Windows-based programs. If you are running CRiSP.1 from the MS-DOS prompt, you have two choices: 1) redirect the program's standard and error output streams to text files or 2) have standard and error output streams write to the MS-DOS shell. Example command to redirect the output streams to text files crisp1 -bs -f base.dat >output.txt 2>error.txt Example command to redirect both of the output streams to the same file crisp1 -bs -f base.dat 1>output.txt 2>&1 To let the batch mode program's output streams write to the MS-DOS shell, you must use a second program called crisp1b that runs crisp1 in batch mode and is equivalent to crisp1 -b. crisp1b -s -f base.dat For this to work properly, the files crisp1.exe and crisp1b.exe must reside in the same directory. Warning. It would be a mistake to run the crisp1b program and then redirect its standard output streams. ------------------------------------------------------------------------ Additional Information about the Unix crisp1 Shell Script: The shell script takes the following actions: sets the colors correctly; sets your environment variable LD_LIBRARY_PATH to contain /usr/openwin/lib and /usr/dt/lib; and starts the executable. If you have any trouble with the script, you could perform these actions yourself, then invoke the executable directly. If desired, you could make changes to your environment to incorporate the following actions, then always invoke the executable directly. Neither of these should be necessary; the standard method of simply invoking "crisp1" as described above is perfectly acceptable. To get the colors correct, invoke the command: xrdb zapp.ad Make sure your LD_LIBRARY_PATH contains /usr/openwin/lib and /usr/dt/lib. One way to do this is to execute the following command: setenv LD_LIBRARY_PATH /usr/openwin/lib:usr/dt/lib:$LD_LIBRARY_PATH in the shell in which you will be running crisp1. You can also modify your startup file (.login or .cshrc) with a similar command. After the above steps are completed, run the crisp1 executable "crisp1.executable". ------------------------------------------------------------------------ Please direct questions or comments to: crisp-passage@cbr.washington.edu