Number range CHAPTERI.2-UNIX-DHM   PROGRAM EXECUTION INFORMATION FOR
DISTRIBUTED HYDROLOGIC MODELING (DHM) ON UNIX SYSTEMS

[Bookmarks]{.underline}

Background \[

Apps Defaults Tokens \[\]

DHM Architecture \[\]

DHM Data \[\]

[Contents]{.underline}

[Page]{.underline}

Background

Apps_Defaults Tokens

DHM Architecture 2

DHM Data 3

[Background]{.underline}

DHM is the set of features integrated into NWSRFS for distributed
hydrlogic modeling. The primary component is DHM-OP, an NWSRFS operation
(#64), which executes in batch mode through OFS-FCST and in GUI mode
through IFP. The existing dependencies for executing operations in
OFS-FCST and IFP (e.g. tokens, scripts and executables) still apply. New
dependencies for the DHM-OP include Java archives and shared libraries
described in more detail below.

DHM-OP uses the FS5files database to read and write timeseries data and
XMRG files for gridded input and output. OFS-FCST can also write netCdf
grids for display in D2D

[Apps Defaults Tokens]{.underline}

**dhm_data_dir: \$(ofs_files)/\$(ofs_level)/dhmdata**

root directory location for DHM input/output xmrg files

> Before running DHM for the first time, this directory and its
> subdirectories need to be created using the script create_files_group.
>
> *create_files_group* **group_name**
>
> (group name should be equal to \$ofs_level)

**ifp_griddb_dir: /data/dhm/\$(LOGNAME)/precip**

root directory for IFP's local copy of the precip xmrgs.

\*\* Performance tests have shown this should be a directory local to
the workstation running IFP

**dhm_d2d_notify_bin_dir: /awips/fxa/bin**

directory location for D2D executable

**dhm_d2d_data_dir: /data/fxa/Grid/LOCAL/netCDF/DHM**

directory location for D2D template and for DHM to write grid output
file that will be displayed by D2D program.

[DHM Architecture]{.underline}

DHM-OP uses FORTRAN, C, C++ and Java. Unlike traditional NWSRFS
operations, the modeling logic is not built into OFS-FCST. The NWSRFS
code specific to DHM-OP (operation #64) is used as an adapter to various
libraries containing the modeling logic. The following schematic is an
overview of the architecture.

![](media/image1.wmf){width="7.15in" height="4.20625in"}

DHM Libraries:

DHM shared and java archive libraries are stored in thedirectory pointed
to by the Apps_defaults token **util_rls**. DHM also uses JAVA system
libraries in subdirectories to the token pointed to by the Apps_defaults
token **sys_java_dir**. The shared libraries are accessed at run-time by
adding these directories to the LD_LIBRARY_PATH environment variable.
The JAVA archives (jars) are accessed by adding the directory pointed to
by the Apps_defaults token **util_rls** to the CLASSPATH environment
variable.

DHM Scripts:

The ofs script was updated to add the shared libraries to the
LD_LIBRARY_PATH and java archive libraries to the CLASSPATH for running
DHM through OFS-FCST (batch mode). A new ifp script, with the same
purpose, was added for running DHM through IFP (GUI mode).

[DHM Data]{.underline}

XMRG Input Grids:

The coupled Sacramento SMA and Kinematic Routing models use the grids in
the following tables. The precipitation grids are standard XMRG files,
located in the directory referenced by the **ofs_griddb_dir and
ifp_griddb_dir** Apps_defaults tokens. The potential evapotranspiration,
model parameter and state grids are gnu zipped in an XMRG-like format.
These files are located in subdirectories (pet, parameters, and states
respectively) of the directory referenced by the **dhm_data_dir**
Apps_defaults token. Each user (\$ofs_level) has their own set of files.
The parent DHM directory and it's subdirectories are automatically
created by running the create_files_group script.

The first record of the XMRG-like files is the same as standard XMRGs
and consists of four integers:

-   X- and Y-origins in HRAP coordinates, and

-   numbers of columns and rows in the file.

    The second record differs from standard XMRG files. It consists of 4
    variables:

-   an integer scale factor to convert integer\*2 values into real
    values (to get the true values, divide the value stored in the file
    by this factor),

-   and number of bytes per value (2 for integer\*2 format and 4 for
    real\*4 format).

-   cell size in HRAP coordinates (1)

-   the grids NODATA value (-999.)

    As with standard XMRGs, data values are written with the
    southernmost row written to the file first and the northernmost row
    written last.

    I. Sacramento SMA Parameter Grids

  ------------------------------------ ----------------------------------
  sac_LZFPM.gz \[mm\]                  sac_UZK.gz \[per day\]

  sac_LZFSM.gz \[mm\]                  sac_UZTWM.gz \[mm\]

  sac_LZPK.gz \[per day\]              sac_ZPERC.gz

  sac_LZSK.gz \[per day\]              sac_PCTIM.gz \[%\]

  sac_LZTWM.gz \[mm\]                  sac_ADIMP.gz \[%\]

  sac_PFREE.gz                         sac_RIVA.gz

  sac_REXP.gz                          sac_SIDE.gz

  sac_UZFWM.gz \[mm\]                  sac_RSERV.gz
  ------------------------------------ ----------------------------------

II\. Sacramento SMA State Grids **^a^**

  -----------------------------------------------------------------------
  sac_uztwc.mmddyyyyhhz.gz \[mm\]

  sac_uzfwc.mmddyyyhhz.gz \[mm\]

  sac_lztwc.mmddyyyyhhz.gz \[mm\]

  sac_lzfpc.mmddyyyyhhz.gz \[mm\]

  sac_lzfsc.mmddyyyyhhz.gz \[mm\]

  sac_adimpc.mmddyyyyhhz.gz \[mm\]
  -----------------------------------------------------------------------

III\. Kinematic Routing Parameter Grids

  ---------------------------------- ------------------------------------
  rutpix_DS.gz                       Drainage Density

  rutpix_ROUGH.gz                    Hillslope Roughness

  rutpix_SLOPH.gz                    Hillslope Slope

  rutpix_Q0CHN.gz                    Coefficient in channel's Kinematic
                                     Routing Equation

  rutpix_QMCHN.gz                    Exponent in channel's Kinematic
                                     Routing Equation
  ---------------------------------- ------------------------------------

IV\. Kinematic Routing State Grids **^a^**

  ------------------------------------------- ---------------------------
  rutpix_depth.mmddyyyyhhz.gz                 Depth of water in hillslope
                                              \[mm\]

  areacN.mmddyyyyhhz.gz ^b^                   Cross-sectional area of
                                              water in channel
  ------------------------------------------- ---------------------------

a = mmddyyyyhh represents the date and time for the saved state

b = N represents the channel reach number, there are usually 3 per 4km
HRAP grid

V. Potential Evapotranspiration Rate on 16^th^ day of month**^c^**
\[mm/day\]

  --------------------------------- -------------------------------------
  pe_JAN.gz                         pe_JUL.gz

  pe_FEB.gz                         pe_AUG.gz

  pe_MAR.gz                         pe_SEP.gz

  pe_APR.gz                         pe_OCT.gz

  pe_MAY.gz                         pe_NOV.gz

  pe_JUN.gz                         pe_DEC.gz
  --------------------------------- -------------------------------------

^c^ The DHM monthly pe grids include all adjustments (i.e. monthly
adjustment grids pe_adj)

XMRG Output Grids:

The results of the SAC-SMA and Kinematic Routing calculations (channel
flow at each pixel in the modeled basin) is stored in a gnu-zipped
XMRG-like file in a directory named channelflow (a subdirectory to the
directory referenced by the **dhm_data_dir** Apps_defaults token).

VI\. Channel Flow Grids **^c^**

  -----------------------------------------------------------------------
  channelflow.xmrg.mmddyyyyhh.gz \[m^3^/s\]

  -----------------------------------------------------------------------

c = mmddyyyyhh represent the date the saved state date and time

netCDF Grids:

netCDF grids are created during batch carryover save runs (OFS-FCST).
The grids will contain the results for all basins modeled with a DHM-OP
in the current carryover group and any previously modeled carryover
groups.

The netCDF grid is stored as a time-stamped file (yyyymmdd_hhmm), where
the date and time represent the model run-time (e.g. TODAY at 12Z). The
file can have data for as far back as 5 days ago and 5 days forward. The
days with data is controlled using the carryover save dates.

For example if the following carryover save FCST deck is run on
1/6/2006. DHM will create a file named 20060101_1200 for all grid
variables. Each file will contain data for days 0102 12Z to 0106 12Z.

\@SETOPT

STARTRUN \*-05

ENDRUN \*

NUMCOSAV \*-04 \*-03 \*-02 \*-01 \*

FUTPRECP(0)

\@COMP FCEXEC

DHM netCDF Grid File: contains all grid variables:

SAC SMA Additional Impervious Area Contents \[ADIMC , % full\],

Lower Zone Free Secondary Contents \[LZFPC, % full\],

Lower Zone Tension Water Contents \[LZFSC, % full\],

Lower Zone Tension Water Contents \[LZTWC, % full\],

Upper Zone Free Water Contents \[UZFWC, % full\],

Upper Zone Tension Water Contents \[UZTWC, % full\],

Hillslope Water Depth \[WATER_DEPTH, inches\],

Channel flow (LOW Range) \[ROUTED_FLOW, cfs\],

Channel flow (MID Range) \[ROUTED_FLOW_M, cfs\],

Channel flow (HIGH Range) \[ROUTED_FLOW_H, cfs\],

Channel flow (ALL Ranges) \[ROUTED_FLOW_C, cfs\].

Connectivity file:

The connectivity file, with filename Connectivity, is a text file
located in the directory referenced by **dhm_data_dir** Apps_defaults
token. It stores an ordered list of all the cells in the model domain.
The cells are ordered so that each time the next cell in the list is
reached, computations for all upstream cells have already been
completed. In the header of the connectivity file, the user specifies
basin outlet cells and IDs of interest for a region. The same outlet IDs
used in the connectivity file are also used in the fcinit input deck to
choose where hydrographs will be generated. Figure 2 shows a screenshot
of the top of a connectivity file.

![](media/image2.wmf){width="3.7083333333333335in" height="4.625in"}

Figure 2 Example Connectivity File

Adding outlets to the connectivity file:

The connectivity file contains 9 lines of general header information,
followed by a list of basin outlets defined for the model, followed by
an ordered list of pixels covering the entire modeling domain. The top
portion of a connectivity file is shown here.

*TEXT_SEQ*

*NUM_HEADER_REC 2 24467*

*COL 1060*

*ROW 821*

*LLX 1*

*LLY 1*

*URX 1060*

*URY 821*

*DATA_HRAP*

*TEST1 1 5 5.0000 375 419*

*TEST2 1 9 5.0000 375 418*

*0 1 Rv 1 376 402 6.4589 377 419*

*1 5 Rv 1 375 401 6.4589 376 420*

*2 5 Rv 1 375 402 6.4589 376 419*

*3 5 Rv 1 374 401 6.4589 375 420*

*4 9 Rv 1 375 403 6.4589 376 418*

*5 9 Rv 1 374 402 6.4589 375 419*

*6 12 Rv 1 369 408 6.4589 370 413*

*7 12 Rv 1 369 406 6.4589 370 415*

*8 13 Rv 1 375 404 6.4589 376 417*

*. . .*

*. . .*

*. . .*

Line 2: Lists the number of outlets identified in this file (2) and the
total number of cells listed in the file (24467)

Lines 3, 4: Number of columns and rows. \*\*

Lines 5, 6: Lower-left X and Y coordinates. \*\*

Lines 7, 8: Upper-right X and Y coordinates. \*\*

Lines 10-11: Basin outlet specifications. Information included in each
line:

Col. 1: ASCII identifier. Must be the same as identifier used in FCINIT
Input Deck.

Col. 2: ignore

Col. 3: Cell line number of this outlet

Col. 4: Representative area (mi^2^) of cells in this basin. Computed as
the USGS area divided by the number of HRAP cells in the basin. (program
does not currently use this value)

Col. 5: hrapx coordinate of outlet cell (program does not currently use
this value)

Col. 6: hrapy coordinate of outlet cell (program does not currently use
this value)

Lines 12-24479: Cell List

Col. 1: Cell line number

Col. 2: Cell line number of the next downstream cell

Col. 3: ignore

Col. 4: ignore

Cols. 5-6: Local reference coordinates

Col. 7: Area represented by the cell in mi^2^

Cols. 8-9: Globally referenced Hrapx and Hrapy (the true hrapx, hrapy
coordinates)

To add a new outlet point, a new basin outlet specification line must be
added (e.g. lines 10 -- 11 in the example). As defined above, the
information required for the added line includes 6 values: a basin
identifier of eight characters or less, a dummy value of 1, the cell
line number in the connectivity file corresponding to the basin outlet,
a representative cell area, and the HRAP x and y coordinates of the
outlet cell for this point. These values should all be entered on one
line in free format, separated by at least one space.

To determine the cell line number corresponding to a new outlet point,
do a text string search on the connectivity file for the true hrapx and
hrapy coordinates of the point you are adding (separated by a single
space). For example, search for "375 419" to identify the outlet line
number for TEST1 in the above example. The search should find "375 419"
in Columns 8-9 somewhere in the Cell List (lines 23-24489). The value in
Column 1 of the cell line number is the third number in your basin
specification line (e.g. 5 for TEST1 in the example). The fourth number,
a representative cell area, can be taken from column 7 of the cell line
number found in your search.

**\*\*** - these values from the connectivity file are not used to
determine the RFC's boundary. Instead the boundary is defined by the
coordinates in the file located using the Appsdefaults tokens
geo_data_dir and ifp_rfc.

\$geo_data_dir/\$ifp_rfc/ascii/coord\_\$ifp_rfc.dat