**CRiSP Passage README** Last updated 4/29/98 ********************************************************************** CRiSP Passage v 1.5.5 is a reimplementation of the CRiSP Passage model (v 1.5) from the Sun Unix environment to a cross-platform development environment which supports Win95 and WinNT on the PC as well as SOLARIS 2 on Unix. 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. Windows 95/NT minimum system requirements: This version of CRiSP.1 requires an IBM compatible computer running under Windows 95 or Windows NT, 486/66 Mhz, 8 MB of RAM, and 10 MB available hard disk space. Unix system requirements: This version of CRiSP.1 requires the Solaris 2.5.x operating system or higher. The directories /usr/openwin/lib and /usr/dt/lib must exist and contain the standard system libraries. ********************************************************************** Files and directories in a CRiSP.1 release: 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. crisp1.exe CRiSP.1 executable -- Win 95/NT only. crisp1b.exe CRiSP.1 executable for Batch Mode -- Win 95/NT only. crisp1 CRiSP.1 shell script -- Unix only. crisp1.executable CRiSP.1 executable -- Unix only. columbia.desc Default river description file. 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 on startup. base.sample.rls A set of sample releases, loaded automatically on startup by the "base.dat" file. flow.archive Sample flow archive file for use in Monte Carlo Mode. zapp.ad Xresource file for proper colors -- Unix only. crisp1.zhp Help file containing basic text for CRiSP on-line help. zhelp Help viewer executable -- Unix only. zhelp.exe Help viewer executable -- Win 95/NT only. README This file. Also provided in this distribution: flow.data Directory containing a number of other sample flow archive files for use in Monte Carlo Mode. yearly.data A directory containing other user data files corresponding to yearly historical conditions. ********************************************************************** Starting CRiSP.1: To start CRiSP.1 from a file manager, double-click on the CRiSP.1 icon. To start CRiSP.1 from a command tool or DOS window, the model must be in the current directory (or, on Unix only, in the path). Type the command line with the following syntax: crisp1 [-l{wmrd}] [-bsmi] [-r river_desc] [-f data_file] 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 a default value is used. [-l{wmrd}] controls the logging level. Five seperate 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, and "-ld" causes only Debug output to be logged. [-bsmi] signifies a 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). See section at end of file for special instructions on running CRiSP.1 in Batch Mode for Windows 95/NT users. [-r river_desc] gives the name of the river description file. The default name is "columbia.desc". [-f data_file] gives the name of the data file. The default name is "base.dat". ********************************************************************** CRiSP.1 Features: Following is a list of features, organized around the main application window's menu bar. The File menu. Database files can be read with File/Open. File/Save As... will save the entire database, or portions thereof, depending on the file extension selected (for example, saving data to "glop.spill" saves only spill-related parts of the database). File/Mouse Tool... opens a dialog to specify what actions are caused by clicking on various map features with the mouse. File/Message Log... opens the message logging window. File/Unzoom is used to undo the new map zooming feature. If you use the left mouse button to drag-select an area of the map (which will be shown black while you are dragging it) the map zooms in until the area you selected fills the entire map window. Drag-selecting another area causes the map to zoom in further. Select File/Unzoom, or click "Unzoom" on the toolbar, to go back to previous map settings. The Release menu. Selecting "Release Tool..." opens the Release Tool dialog, displaying an arbitrary release. Selecting from the Release / New menu opens the dialog and selects the given release site (and an existing release at that site, if any). Existing releases can be selected from the Existing Releases combobox in the Release Tool window (which shows existing releases at all release sites, not just the current one). The Release Tool implements a concept that will be seen throughout CRiSP Passage - two level editing. The Release Tool edits a temporary copy of the release list. To make edits take effect, the Apply or ApplyAll buttons must be pushed (Apply affects only the release currently being displayed; ApplyAll makes all changes to the release list take effect). Edit changes can be discarded with the Reset or ResetAll buttons. The red dots which you may see in the corners of the Release Tool or it's subsidiary windows indicate that the data being displayed has been changed, but the changes have not yet been applied to the underlying database (in other words, the dialog is "dirty" with respect to the underlying database). The Release Tool also has "Create This Release" and "Delete This Release" buttons - this allows releases to be added to or removed from the temporary copy of the release list. If a release is deleted from the temporary list, the ApplyAll button must be used to apply that deletion to the underlying database. As an general rule, "OK" is taken to mean "Apply All and close Dialog", whereas "Cancel" is taken to mean "Reset All and close Dialog". The Reservoir menu no longer includes a Water Travel Time dialog - this feature has been dropped. Dialogs such as Reservoir / Reach Predator Density have a new feature called "group updating". In this dialog, setting the checkboxes labeled "G" to the checked state, indicates that the checked values will always be forced to be equal to each other. The "G" checkbox which is not connected to a particular reach controls this feature globally - when it is checked, all reaches are forced to the same value. Some dialogs have two or more grouped update boxes - these have different labels depending on what is being forced to equality. "S" usually means that the data will be forced equal for all species, for example. These dialogs may also have tabs - "A", "B", "C", and "D" in the Reach Predator Density Dialog, for example. Clicking on these tabs shows other values which can be edited. Conceptually, a single list of values is being edited - the tabs simply allow the list to be "folded" into a restricted screen area. These dialogs also have the two-level editing concept - changes are not applied to the underlying database unless "Apply" or "OK" is pressed. The Reservoir menu also contains examples of display-only (output) graph windows and editable (input) graph windows. Editable graph windows can be recognized by the row of buttons on the bottom. Editable graphs display data which can be edited, either by dragging the mouse across the window with the left button held down, or by left-clicking in two separate places to define a rectangle, or by clicking the "Schedule" button and typing values into the Schedule Tool. These windows also implement the two-level editing concept. In general, any number of windows of the same type can be active at the same time - just select the same menu item several times to create several copies of the same type of window. For input windows (dialogs and editable graphs) it is possible to have multiple windows displaying the same data at the same time. If the data is changed in one window, the others update automatically to reflect the changes. Both types of graph windows implement the "live selection" feature. For example, click on the Reservoir / NSat / Dam / Bonneville Dam menu item, and then click the rightmost button in the top row of buttons in the graph window - this turns on live selection. Click that button again to turn the feature off. When live selection is on, whenever you point to a dam on the map, the graph automatically displays the NSat data for that dam. Any number of graphs can be active at one time, showing all sorts of different data, and some or all of them can perform live selection at the same time. The Behavior menu. Please note that the Behavior / Gas Mortality Eqn... menu item creates two equation editing dialogs, which are initially on top of each other - one will have to be moved to another part of the screen. The Flow menu. The Flow / Reservoirs submenu gives the names of dams which are directly downstream from headwaters and, therefore, are modeled as having storage basins. Selecting a dam from the Flow / Reservoirs submenu opens two editing graph dialogs - one for basin volume at the dam and one for outflow from the dam. The outflow dialog is ficticious, in the sense that these values are recalculated during simulation. Editing the outflow at a dam with a storage reservoir actually edits the storage reservoir volume. The "dirty" status of an outflow graph actually reflects the dirtyness of the storage basin volume and the associated headwater flow (these two quantities together determine the outflow). Unfortunately, you just have to know which headwaters are associated with which dams - in the columbia.desc river description file which is shipped with CRiSP Passage, the Columbia Headwater is associated with Chief Joseph Dam, the Snake Headwater is associated with the Hells Canyon Dam, and the North Fork Clearwater Headwater is associated with the Dworshak Dam. The Dam menu. The Dam / Survival simulation window has been dropped. The Predator Density and Predation Probability dialogs have been moved from the Reservoir menu to the Dam menu, because it seemed like a more logical place for them. The Passage menu. Please note that Bypass, Turbine, Spillway, and Transport passage data are not available unless the corresponding boxes were checked in the Output Settings for Dams dialog (see below). The Run menu. Scenario and Monte Carlo modes are fully implemented. Run / Output Settings... implements a new method for controlling simulation outputs. In the previous versions, it was necessary to open histogram windows for the particular outputs to be generated during a run. In the new version, this same function is achieved by selecting Run / Output Settings and checking or unchecking various boxes. For example, checking "Flow" for Bonneville Dam will cause the daily flow values at that point to be sent to the log message window and to the summary.dat file. The rows and columns labeled "all" control all of the checkboxes in their respective rows and columns. The "all" checkbox in the upper-right corner controls every box in the dialog. These output settings boxes implement two-level editing, so "Apply" or "OK" must be clicked before the output settings can take effect. The message log window will show daily information if Logging / Message is selected, and time-slice level information if Logging / Raw is selected. It is particularly important to use Run / Output Settings... to control the information which is collected during Monte Carlo runs, because no detailed information is collected by default (to conserve memory). The Analysis menu is fully functional. The Input Data Report and Monte Data Report tools work as they did in previous versions - multiple selections of data are printed into a window on the screen, from which they can be stored or printed to hardcopy. The Monte Alternative Comparison and Monte Analysis tools also work as they did previously, with the exception that the "Critical Value" feature is not implemented for Monte Analysis and that the information is presented in different windows (all of the same information is presented, and all calculated values are expected to be the same). The Help system is partially implemented. All windows and dialogs have either a red "?" button or a "Help" button, or a Help menu item - selecting those brings up the corresponding page in the online help file. The current release contains an online help file which is not complete. We hope to ship an updated, complete online help file shortly. In general, the underlying modeling system is expected to work the same as in CRiSP v 1.5.4 on Unix; the graphical user interface has been extended in ways we hope are intuitive. The CRiSP Passage manuals -- Theory, Validation, and Calibration and User -- for the old Unix version are available online at: http://www.cqs.washington.edu/crisp/models/crisp1manual/. ********************************************************************** Additional Information about the Unix crisp1 Shell Script: The shell script takes the following actions. If you have any trouble with the script, you could perform these 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". Note that this script also translates the outdated "-d inputdatafile" flag to the new "-f inputdatafile" flag. ********************************************************************** Special Instructions for Running CRiSP.1 in Batch Mode for Windows 95/NT: There are a few special considerations for running CRiSP Passage in batch mode. These derive from the architechure of Windows 95 and Windows NT, which make sharp distinctions between batch mode ("console") applications and graphical, window mode applications. If you are running CRiSP.1 from the command line prompt in a DOS box, you have two choices: redirect the program's standard and error output streams to text files, or have them print out in the DOS box. To redirect the output streams to text files use a command line like this: crisp1 -bis -f base.dat >output.txt 2>error.txt To redirect both of the output streams to the same file, use a command line like this: crisp1 -bis -f base.dat 1>output.txt 2>&1 To let the batch mode program's output streams print out in the DOS box, you must use a second program called "crisp1b", which launches crisp1 is batch mode and is equivalent to "crisp1 -b". Use a command line like this: crisp1b -is -f base.dat For this to work properly, the files crisp1.exe and crisp1b.exe must be in the same directory. It would be unnecessary, and a mistake, to launch the crisp1b application and then redirect it's standard output streams. ********************************************************************** Please direct questions or comments to: crisp-passage@pogo.cqs.washington.edu Columbia Basin Research, UW