ROUTINE
-------

INT_ ug_io_read_grid_file (char Grid_File_Name[],
                           INT_ Message_Flag,
                           INT_ M_BL_Thickness,
                           INT_ M_Initial_Normal_Spacing,
                           INT_ M_Surf_Grid_BC_Flag,
                           INT_ M_Surf_ID_Flag,
                           INT_ M_Surf_Reconnection_Flag,
                           INT_ M_Vol_ID_Flag,
                           INT_ Bnd_Only_Flag,
                           INT_ No_Quad_Flag,
                           INT_ Renumber_ID_Flag,
                           INT_ Separate_by_ID_Flag,
                           INT_ *Number_of_BL_Vol_Tets,
                           INT_ *Number_of_Nodes,
                           INT_ *Number_of_Surf_Quads,
                           INT_ *Number_of_Surf_Trias,
                           INT_ *Number_of_Vol_Hexs,
                           INT_ *Number_of_Vol_Pents_5,
                           INT_ *Number_of_Vol_Pents_6,
                           INT_ *Number_of_Vol_Tets,
                           INT_1D * Surf_Grid_BC_Flag,
                           INT_1D * Surf_ID_Flag,
                           INT_1D * Surf_Reconnection_Flag,
                           INT_4D * Surf_Quad_Connectivity,
                           INT_3D * Surf_Tria_Connectivity,
                           INT_8D * Vol_Hex_Connectivity,
                           INT_1D * Vol_ID_Flag,
                           INT_5D * Vol_Pent_5_Connectivity,
                           INT_6D * Vol_Pent_6_Connectivity,
                           INT_4D * Vol_Tet_Connectivity,
                           DOUBLE_3D * Coordinates,
                           DOUBLE_1D * Initial_Normal_Spacing,
                           DOUBLE_1D * BL_Thickness)

DESCRIPTION
-----------

Read grid data from a standard UG surface or volume grid file.

This routine will allocate the grid data arrays with  as much space as required by the grid file dimensions.

Note that this routine will reorder nodes so that boundary nodes are first
followed by interior nodes.

INPUT ARGUMENTS
---------------

Grid_File_Name           : Grid file name.
                           If the grid file name is blank or NULL then nothing
                           is done.

UG_IO_Param_Struct_Ptr   : UG_IO parameter structure.

Message_Flag             : Output message flag.
                           If Message_Flag =  0 then no information messages
                           are written.
                           If Message_Flag >= 1 then information messages are
                           written to standard output.

M_BL_Thickness           : BL_Thickness allocation flag.
                           If M_BL_Thickness = 1 then allocate.
                           If M_BL_Thickness = 0 then do not allocate.

M_Initial_Normal_Spacing : Initial_Normal_Spacing allocation flag.
                           If M_Initial_Normal_Spacing = 1 then allocate.
                           If M_Initial_Normal_Spacing = 0 then do not allocate.

M_Surf_Grid_BC_Flag      : Surf_Grid_BC_Flag allocation flag.
                           If M_Surf_Grid_BC_Flag = 1 then allocate.
                           If M_Surf_Grid_BC_Flag = 0 then do not allocate.

M_Surf_ID_Flag           : Surf_ID_Flag allocation flag.
                           If M_Surf_ID_Flag = 1 then allocate.
                           If M_Surf_ID_Flag = 0 then do not allocate.

M_Surf_Reconnection_Flag : Surf_Reconnection_Flag allocation flag.
                           If M_Surf_Reconnection_Flag = 1 then allocate.
                           If M_Surf_Reconnection_Flag = 0 then do not allocate.

M_Vol_ID_Flag           :  Vol_ID_Flag allocation flag.
                           If M_Vol_ID_Flag = 1 then allocate and determine.
                           If M_Vol_ID_Flag = 0 then do not allocate.

Bnd_Only_Flag            : Read boundary data only flag.
                           If Bnd_Only_Flag = 1 then only read boundary data.
                           If Bnd_Only_Flag = 0 then read all data.

No_Quad_Flag             : Convert all quads to trias flag.
                           Nothing is done if the grid data is for a volume
                           grid.
                           If No_Quad_Flag = 1 then convert quads.
                           If No_Quad_Flag = 0 then do not convert quads.

Renumber_ID_Flag         : Renumber Surf_ID consecutively flag.
                           If Renumber_ID_Flag = 1 then renumber Surf_ID.
                           If Renumber_ID_Flag = 0 then do not renumber Surf_ID.

Separate_by_ID_Flag      : Flag to reorder surface faces so that they are
                           grouped by separate surface ID and duplicate nodes on
                           their boundaries so that each surface ID patch has
                           unique node indexes. Nothing is done if the grid data
                           is for a volume grid.
                           If Separate_by_ID_Flag = 1 then separate.
                           If Separate_by_ID_Flag = 0 then do not separate.

RETURN VALUE
------------

0                        : No errors occurred reading grid file.
<0                       : The grid file name is blank or NULL or the grid file
                           name is not a standard UG surface or volume grid
                           file. Nothing is done in this case.
                           The return value will be -1.
>0                       : Errors occurred reading grid file.
                           The return value will be between 600 and 699.

OUTPUT ARGUMENTS
----------------

Number_of_BL_Vol_Tets    : Number of boundary-layer/structured-layer
                           tetrahedral elements.

Number_of_Nodes          : Number of nodes.
                           If the boundary-surface grid only option is specified
                           on the first call then the number of nodes is the
                           maximum node index specified in the boundary surface
                           tria or quad face connectivity.

Number_of_Surf_Quads     : Number of boundary surface quad faces.

Number_of_Surf_Trias     : Number of boundary surface tria faces.

Number_of_Vol_Hexs       : Number of volume grid hex elements.

Number_of_Vol_Pents_5    : Number of volume grid pent elements with five nodes
                           (pyramid).

Number_of_Vol_Pents_6    : Number of volume grid pent elements with six nodes
                           (prismatic).

Number_of_Vol_Tets       : Number of volume grid tet elements.

Surf_Grid_BC_Flag        : Surface face grid boundary condition flag.
                           If Surf_Grid_BC_Flag = NULL then this array is not
                           used. This array uses "FORTRAN" style indexing with
                           an index which ranges from one to
                           Number_of_Surf_Quads+Number_of_Surf_Trias. The first
                           one to Number_of_Surf_Trias entries correspond to
                           boundary surface tria faces. The next
                           Number_of_Surf_Trias+1 to
                           Number_of_Surf_Trias+Number_of_Surf_Quads entries
                           correspond to boundary surface quad faces. Array
                           location zero is not used. This array is used
                           primarily for grid generation.

Surf_ID_Flag             : Surface face ID flag.
                           This array uses "FORTRAN" style indexing with an
                           index which ranges from one to Number_of_Surf_Trias+
                           Number_of_Surf_Quads. The first one to
                           Number_of_Surf_Trias entries correspond to boundary
                           surface tria faces. The next Number_of_Surf_Trias+1
                           to Number_of_Surf_Trias+Number_of_Surf_Quads entries
                           correspond to boundary surface quad faces. Array
                           location zero is not used. This array allows surface
                           faces to be grouped. Typically surface faces with
                           the same ID flag represent a complete surface or
                           enclosed surface.

Surf_Reconnection_Flag   : Surface face reconnection flag.
                           If Surf_Reconnection_Flag = NULL then this array is
                           not used. This array uses "FORTRAN" style indexing
                           with a primary index which ranges from one to
                           Number_of_Surf_Trias+Number_of_Surf_Quads. The
                           first one to Number_of_Surf_Trias entries correspond
                           to boundary surface tria faces. The next
                           Number_of_Surf_Trias+1 to Number_of_Surf_Trias+
                           Number_of_Surf_Quads entries correspond to boundary
                           surface quad faces. Array location zero is not used.
                           This array is used primarily for grid generation.

Surf_Quad_Connectivity   : Surface grid quad face connectivity.
                           This array uses "FORTRAN" style indexing with an
                           index which ranges from one to Number_of_Surf_Quads.
                           Array location zero is not used. The secondary index
                           uses "C" style indexing with an index which ranges
                           from zero to three corresponding to the four nodes
                           of a particular quad face. The node index value
                           stored in this array can vary from one to
                           Number_of_Nodes.

Surf_Tria_Connectivity   : Surface grid tria face connectivity.
                           This array uses "FORTRAN" style indexing with an
                           index which ranges from one to Number_of_Surf_Trias.
                           Array location zero is not used. The secondary index
                           uses "C" style indexing with an index which ranges
                           from zero to two corresponding to the three nodes of
                           a particular tria face. The node index value stored
                           in this array can vary from one to Number_of_Nodes.

Vol_Hex_Connectivity     : Volume grid hexahedral element connectivity.
                           This array uses "FORTRAN" style indexing with a
                           primary index which ranges from one to
                           Number_of_Vol_Hexs. Array location zero is not used.
                           The secondary index uses "C" style indexing with an
                           index which ranges from zero to seven corresponding
                           to the eight nodes of a particular hex element. The
                           node index value stored in this array can vary from
                           one to Number_of_Nodes.

Vol_ID_Flag              : Volume element ID flag.
                           This array uses "FORTRAN" style indexing with an
                           index which ranges from one to Number_of_Vol_Tets+
                           Number_of_Vol_Pents_5+Number_of_Vol_Pents_6+
                           Number_of_Vol_Hexs. The first one to
                           Number_of_Vol_Tets entries correspond to volume grid
                           tetrahedral elements. The next Number_of_Vol_Pents_5
                           entries correspond to volume grid 5-node pentahedral
                           elements, etc. Array location zero is not used. If
                           Vol_ID_Flag = NULL then this array is not used. This
                           array allows volume elements to be grouped. Typically
                           volume elements with the same ID flag represent an
                           individual solid or material. If the grid file does
                           not contain Vol_ID_Flag data or has dummy values (all
			   values are the same and that value is <= 0) then the
                           values of Vol_ID_Flag are determined and set from the
                           input surface and volume grid connectivity.

Vol_Pent_5_Connectivity  : Volume grid 5-node pentahedral element connectivity.
                           This array uses "FORTRAN" style indexing with a
                           primary index which ranges from one to
                           Number_of_Vol_Pents_5. Array location zero is not
                           used. The secondary index uses "C" style indexing
                           with an index which ranges from 0 to 5 corresponding
                           to the 5 nodes of a particular 5 node pent element.
                           The node index value stored in this array can vary
                           from one to Number_of_Nodes.

Vol_Pent_6_Connectivity  : Volume grid 6-node pentahedral element connectivity.
                           This array uses "FORTRAN" style indexing with a
                           primary index which ranges from one to
                           Number_of_Vol_Pents_6. Array location zero is not
                           used. The secondary index uses "C" style indexing
                           with an index which ranges from 0 to 5 corresponding
                           to the 6 nodes of a particular 6 node pent element.
                           The node index value stored in this array can vary
                           from one to Number_of_Nodes.

Vol_Tet_Connectivity     : Volume grid tetrahedral element connectivity.
                           This array uses "FORTRAN" style indexing with a
                           primary index which ranges from one to
                           Number_of_Vol_Tets. Array location zero is not used.
                           The secondary index uses "C" style indexing with an
                           index which ranges from zero to three corresponding
                           to the four nodes of a particular tet element. The
                           node index value stored in this array can vary from
                           one to Number_of_Nodes.

Coordinates              : Grid node coordinates.
                           This array uses "FORTRAN" style indexing with a
                           primary index which ranges from one to
                           Number_of_Nodes. Array location zero is not used.
                           The secondary index uses "C" style indexing with an
                           index which ranges from zero to two corresponding to
                           the three coordinates (X,Y,Z) for a particular node.

Initial_Normal_Spacing   : Grid node initial normal spacing for boundary-layer
                           type grids.
                           If Initial_Normal_Spacing = NULL then this array is
                           not used. This array uses "FORTRAN" style indexing
                           with an index which ranges from one to
                           Number_of_Nodes. Array location zero is not used.
                           This array is used primarily for grid generation.

BL_Thickness             : Thickness of boundary-layer region for boundary-layer
                           type grids.
                           If BL_Thickness = NULL then this array is
                           not used. This array uses "FORTRAN" style indexing
                           with an index which ranges from one to
                           Number_of_Nodes. Array location zero is not used.
                           This array is used primarily for grid generation.
