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


