                                    Hydrologic Engineering Center
                                                     October 1998


                            RAS2UNET
                          User's Guide
                                

Introduction

RAS2UNET is a utility program designed to convert an HEC-RAS geometry file into an
HEC-UNET geometry file.  The geometry file(s) produced by HEC-RAS contain literally
all the data entered into HEC-RAS through it's geometry editor.  However, not all HEC-
RAS data has a direct parallel in HEC-UNET; therefore, not all data available in the
HEC-RAS geometry file will find its way into the HEC-UNET geometry file through this
utility program.


Installation

Install this program to the \hecexe directory on your computer.  This directory should
already exist if you have installed HEC-UNET.  If you installed HEC-UNET to a directory
other than \hecexe, install RAS2UNET.EXE in the same directory as the HEC-UNET
executables.  When finished, be sure that \hecexe (or the directory containing
RAS2UNET) is on your computer's search path.


Usage

The command line syntax to execute RAS2UNET is:

     RAS2UNET I=input_file O=output_file S=sort_flag

                         where: input_file_name is the name of the HEC-RAS geometry file to be
                    converted (No Default).
                        output_file_name is the name of the HEC-UNET (CSECT) geometry
            file to be created (Default is UNET.CS)
                        sort_flag is YES or NO.  (Default is NO.)  See Sorting section for
            details.
            
For example, if the name of the HEC-RAS geometry file that you wish to convert is
MYPROJ.G01, then you might use the command:

     RAS2UNET  I=MYPROJ.G01  O=MYPROJ.CS
What You Need to Know

          The RAS2UNET input file must be a geometry file saved by HEC-RAS version
     2.1 or newer.

          The RAS2UNET output file will be an HEC-UNET geometry file in CSECT
     format. Although almost all relevant data available in an HEC-RAS geometry file
     will be converted, the output file will be incomplete for HEC-UNET because
     certain required records which are the responsibility of the user to add will be
     missing (e.g. the XK record).

          The first title record (T1) for each reach will begin with the string "REACH# nnn"
     where nnn is the reach number used by RAS2UNET to build the UB and DB
     records.  Reach numbers (nnn) will be assigned to each reach in the order the
     reach is encountered in the input file unless sorting is turned on (in which case,
     each reach name must contain a unique whole number to be used to identify and
     order the reaches.  See the section on Sorting for important details.)  Following
     the reach number will be the river and reach names (separated by a comma) as
     specified in the HEC-RAS geometry file.

          Junction information in the input file will be used to build the UB and DB records
     in the output file that indicate reach connections to HEC-UNET.  Junction names
     from the HEC-RAS data will be used internally in RAS2UNET but will not find
     their way into the output file.  If for any reason RAS2UNET has problems building
     the UB or DB records, a 0 (zero) will be placed on the record to indicate that
     RAS2UNET expected to identify a reach connection but encountered an error.  A
     UB or DB record with a 0 on it is not valid to HEC-UNET and must be corrected
     by the user.  On the other hand, a blank UB or DB record indicates an external
     boundary condition and is valid input to HEC-UNET.

          HEC-RAS stores cross sections in decreasing RiverStation order.  Typically, this
     means upstream to downstream and implies a positive flow direction from first to
     last cross section.  HEC-UNET assumes that the order of the cross sections in
     the geometry file implies a positive flow direction; therefore, the order of the
     cross sections in the output file produced by RAS2UNET will be the same as that
     in the input file.

          Wherever possible, data stored in the input file will be exactly duplicated in the
     output file.  However, cross section identifiers or RiverStations should be limited
     to six numeric characters (including the decimal) by the HEC-RAS user or the ID
     will get truncated by RAS2UNET when the X1 record is created for the cross
     section.  This limitation is a result of the six character field available on the X1
     record for cross section identification in the CSECT input format.  This six
     character limitation also affects the elevation data for each cross section.  The
     first field of each GR record is only six characters in size, therefore, every fifth
     elevation value of the cross section geometry data starting with the first may also
     get truncated (i.e., EL(1), EL(6), EL(11), etc.)

          Interpolated sections stored in the HEC-RAS geometry file (those whose
     RiverStations include a "*") will be treated in the same manner as any other
     section.  However, the "*" will not be retained in the cross section ID and
     comment records will precede the section in the output file to indicate that the
     section is interpolated.

          The description data (if any) for a cross section in the input file will be included in
     the output as comment records preceding the X1 record for that section.

          NC and NH data records will be developed from HEC-RAS Manning's N data;
     however, equivalent roughness data is not used by HEC-UNET so will not be
     converted.  A blank NC record will be placed in the output file at cross sections
     where equivalent roughness data was encountered.  Also, contraction and
     expansion coefficients will be ignored since HEC-UNET does not use them.

          If encountered in the input file, "normal" ineffective flow and "normal" blocked
     encroachments will be converted to X3 record data (fields 4,5,6 &7).  In UNET if
     the elevations (fields 5 & 7) are positive, the region is outside the stations is
     "ineffective" or storage.  The difference between RAS and UNET is that in RAS,
     once the water surface exceeds the specified elevation - the ineffective region
     becomes effective.  In UNET, regardless of the water surface, the region outside
     the specified stations and below the specified elevations is ineffective - always... 
     area above, however, can convey water.  Similarly, if the elevations are
     "negative" (fields 5 & 7) then the region outside the stations is blocked.  Think of
     it as physically modifying the cross section in UNET.  The cross section
     modification will remain in effect regardless of the water surface. All area above
     the "encroachment" can convey water.

          Bridges and culverts will NOT be converted.  Their location in the reach will be
     marked with comment records in the output file.

          A cross section lid will be converted into BT data.  


Sorting

In HEC-UNET, the order of the reaches in the geometric input file is significant in a
number of ways.  First, there is no mechanism that allows the user to label the reaches
and use that label when defining the connections.  Instead, the reach is identified by its
position in the input file.  The first reach is reach 1, the second is reach 2, and so on. 
The user must then use that number when defining the reach connectivity on the UB
and DB records.  If for any reason a reach needed to be inserted into the middle of an
HEC-UNET geometry file, all the reaches from the new one down will effectively be
renumbered and almost all the UB and DB records will need to be corrected.  

The reach order and resulting connectivity can also affect the efficiency of the HEC-
UNET solution matrix and therefore execution time.  Most HEC-UNET users are aware
of this issue and design their input files to increase efficiency.  To enable the HEC-RAS
modeler to produce a geometry file that will assemble into a preconceived order during
conversion, a mechanism was added to RAS2UNET to sort the reaches.  The rules are
simple: 

              Include in each reach name (in the HEC-RAS model) a whole number (made
       up only of digits) indicating the reach's number or sequence after conversion.
              The number must be the only number in the reach name.
              No special characters or strings are required.
              The number does not need to be in a particular location in the name.
              Start numbering with 1 and do not skip numbers.  (Although this is not
       required for sorting, if you do not start at 1 or if you skip numbers, the reach
       numbers used by RAS2UNET to label each reach will not match your
       numbering scheme.)

The following table illustrates some valid and invalid (for sorting) reach names:


Valid
Reason
Invalid
Reason


1
one number in name
Reach 1
seg#24
more than 1 number in
name


7 Lower Rose
Cr
one number in name
Sacramento
no number in name


reach9
one number in name
Stream 2.37
2.37 is not a whole
number


seg#97 Yuba
one number in name
Upper Eel
1,234
1,234 will be seen as 1 &
234 - - 2 numbers!  


Once the reaches have been defined following the above rules, the sort option of
RAS2UNET must be turned on from the command line.  This is done by adding
SORT=YES after the specification of the input and output file names.  For example, if
the HEC-RAS geometry file named "MYPROJ.G01" has reach names that include a
numbering scheme, then to convert that file for use by HEC-UNET, use the following
command line:

     RAS2UNET  I=MYPROJ.G01  O=MYPROJ.CS  SORT=YES


