			  **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
