**Site Specific Hydrologic Predictor (SSHP)**

**Reference Guide**

**Release: OB6**

Last Updated 2/1/06

NWS

Office of Hydrologic Development

Hydrology Laboratory

[1. Introduction 5](#introduction)

[1.1 Purpose 5](#purpose)

[1.2 Changes From Previous Version (OB5 version)
5](#changes-from-previous-version-ob5-version)

[1.2.2 User Interface Changes 5](#user-interface-changes)

[1.2.3 Database Changes 5](#database-changes)

[2. Overview 5](#overview)

[Figure 2.1 SSHP Overview 6](#figure-2.1-sshp-overview)

[3. Interactive Application 7](#interactive-application)

[Figure 3.1 SSHP Application 8](#figure-3.1-sshp-application)

[4. Precipitation Data 9](#precipitation-data)

[4.1 SSHP MAP Preprocessor 9](#sshp-map-preprocessor)

[Figure 4.1 MAP Preprocessor 10](#figure-4.1-map-preprocessor)

[4.2 Precipitation Input Options 11](#precipitation-input-options)

[5. SSHP Data Transfer 12](#sshp-data-transfer)

[5.1 Transferred Data Description 12](#transferred-data-description)

[Figure 5.1 Data Transfer Process 13](#figure-5.1-data-transfer-process)

[5.2 Invocation Description 14](#invocation-description)

[5.2.1 Sending Side (RFC) 14](#sending-side-rfc)

[5.2.2 Receiving Side (at each targeted WFO)
15](#receiving-side-at-each-targeted-wfo)

[5.3 Cleanup 16](#cleanup)

[5.4 Example XML Data Transfer Control File:
16](#example-xml-data-transfer-control-file)

[6. Local SAC-SMA State Updater 19](#local-sac-sma-state-updater)

[Figure 6.1 SAC-SMA State Updater 19](#figure-6.1-sac-sma-state-updater)

[7. System Setup 21](#system-setup)

[7.1 RFC Setup 21](#rfc-setup)

[7.1.1 OFS Setup 21](#ofs-setup)

[7.1.2 Data Transfer 21](#data-transfer)

[7.2 WFO Setup 21](#wfo-setup)

[7.2.1 Static Data Setup (for API-MKC and SAC-SMA)
21](#static-data-setup-for-api-mkc-and-sac-sma)

[7.2.2 Data Generally Transferred from RFC
22](#data-generally-transferred-from-rfc)

[7.2.3 Token Settings 22](#token-settings)

[7.2.4 Cron Job 22](#cron-job)

[7.2.5 Adding an SSHPConfig record 22](#adding-an-sshpconfig-record)

[8. Forecast Adjustment 24](#forecast-adjustment)

[8.1 Description 24](#description)

[8.2 Details 24](#details)

[8.2.1 Pairing 24](#pairing)

[8.2.2 Interpolation 24](#interpolation)

[8.2.3 Blending 24](#blending)

[Appendix A: Directories and Files
26](#appendix-a-directories-and-files)

[1. Directories and File Locations 26](#directories-and-file-locations)

[1.1 Application Scripts and Executable Files
26](#application-scripts-and-executable-files)

[1.2 Log Files 26](#log-files)

[1.3 Application Setup Files 26](#application-setup-files)

[1.4 Data Transfer Directories 27](#data-transfer-directories)

[2. Script and Executable Descriptions
27](#script-and-executable-descriptions)

[Appendix B -- SSHP AppsDefaults Tokens
29](#appendix-b-sshp-appsdefaults-tokens)

[Appendix C -- RFC Segment Definition Example
31](#appendix-c-rfc-segment-definition-example)

[Appendix D -- Science Background 34](#appendix-d-science-background)

[Appendix E -- Calibration and State Maintenance
36](#appendix-e-calibration-and-state-maintenance)

[1. Model Parameter Calibration Options
36](#model-parameter-calibration-options)

[2. Model State Maintenance Options
37](#model-state-maintenance-options)

[Appendix F -- SSHP Database Tables
39](#appendix-f-sshp-database-tables)

[Appendix G - Unit Hydrograph Editor Guide
44](#appendix-g---unit-hydrograph-editor-guide)

[1. Introduction 44](#introduction-1)

[2. Table Modification 44](#table-modification)

[3. Data Contents and Usage 44](#data-contents-and-usage)

[3.1 UnitGraph Table in IHFS 44](#unitgraph-table-in-ihfs)

[4. Editing 45](#editing)

[4.1 Adding A Record In Memory 45](#adding-a-record-in-memory)

[4.2 Removing A Record In Memory 45](#removing-a-record-in-memory)

[4.3 Modifying A Record In Memory 45](#modifying-a-record-in-memory)

[4.4 Saving Changes To Database 45](#saving-changes-to-database)

[4.5 Deleting Unitgraphs From Database
45](#deleting-unitgraphs-from-database)

[4.6 Importing and Exporting Hydrographs
46](#importing-and-exporting-hydrographs)

[4.7 Sorting 46](#sorting)

[4.8 Viewing 46](#viewing)

[4.9 Screen Shot 47](#screen-shot)

***Document Notes***

This document is the reference guide for the SSHP application and its
associated utility programs. It is intended to provide sufficient
technical information to allow the SSHP application to be configured for
operation at a field site, whether it is a WFO or an RFC. While the
application's primary purpose is to provide WFOs with a forecasting tool
for fast-responding streams, RFCs may also wish to run the application,
in order to help configure and monitor the system as used by the WFOs,
and to have easy access to models run at a 1-hour time step. This
document will refer to the office that uses the application, as the
"WFO". Substitute "RFC" if appropriate.

## 1. Introduction

### 1.1 Purpose

The Site Specific Hydrologic Predictor (SSHP) is an application that is
designed to run at a WFO in order to provide streamflow forecasts for
headwater points of streams which respond quickly to precipation. Since
the 6-hour time step used by most RFC models is too long to be effective
for these fast-responding streams, SSHP uses a 1-hour time step for its
model computations.

### 1.2 Changes From Previous Version (OB5 version)

There are no feature changes for the OB6 version (compared with OB5).

### 1.2.2 User Interface Changes

There are no user interface changes to the OB6 version

### 1.2.3 Database Changes

The database accessed has been changed from INFORMIX to PostgreSQL.

## 2. Overview

The SSHP subsystem consists of the SSHP interactive application, the
SSHP MAP preprocessor, the data transfer components, and the SAC-SMA
state updater. The application is the most visible part of the SSHP
subsystem. The application produces streamflow forecasts for headwater
forecast points and can use either the API-MKC or the SAC-SMA
rainfall-runoff models, configurable by forecast point. It requires a
unit hydrograph and rating curve for each forecast point.

The application relies on the other parts of the subsystem for putting
essential data into the IHFS database. The MAP preprocessor puts
basin-average observed QPE time series into the database. The data
transfer components transfer SAC-SMA states and parameters from the RFC
to the WFO and store them in the database. Finally, the optional SAC-SMA
state updater can be used to keep SAC-SMA states current in cases where
no state update has been sent from the RFC to the WFO. Each of the
components discussed above is discussed below in greater detail.

### Figure 2.1 SSHP Overview

![](media/image1.jpeg){width="6.497222222222222in" height="8.75in"}

## 3. Interactive Application

The SSHP interactive application provides the following functionality
using its various GUIs.

1\. Configuration of model preferences and settings, including a choice
of rainfall-runoff models.

2\. Creation of forecast hydrograph using either the SAC-SMA or API-MKC
rainfall-runoff models.

3\. Graphical and tabular editing of the precipitation time series. As
soon as the data is edited, the

forecast model is rerun and the new hydrograph is displayed.

4\. Graphical and tabular editing and viewing of the forecast
hydrograph. Note: if the forecast model is rerun, this data is
overwritten.

5\. Tabular viewing of the potential evapotranspiration time series (if
used).

6\. Tabular editing of monthly ET-demand curve and PE-adjustment
factors.

7\. Saving of forecast height and discharge time series. The time series
are saved in the IHFS database and are accessible to the other WHFS
applications.

8\. Tabular and graphical viewing of prior computed runoff time series
and the current computed runoff time series.

9\. Modification of model states and parameters through the Analysis
Window's user interface.

### Figure 3.1 SSHP Application

![](media/image2.jpeg){width="6.49375in" height="8.78888888888889in"}

## 4. Precipitation Data

### 4.1 SSHP MAP Preprocessor

In the standard configuration, the SSHP MAP Preprocessor is executed
with MPE/Fieldgen scripts (*run_mpe_fieldgen*, *rerun_mpe_fieldgen, and
run_mpe_whfs*). The MAP Preprocessor reads the best estimate xmrg files
and computes MAP for configured basins. The MAP values for the basins
are placed into the ArealObs table with pe = 'PP', dur = 1 hour, and ts
= "PM". The application, though, only reads observed QPE from the
ArealObs table. So, if some other process were to take the place of the
current preprocessor, the precipitation data source could be different.
This might be necessary in offices in which the MPE application is not
used. Also, the OB4 version of the application will read QPF from the
ArealFcst table, looking for pe = "PP", dur = 1 hour, and a ts starting
with "F". The application determines the type/source to use based on the
ts_rank as stored in the IngestFilter table (editable in HydroBase). The
SSHP does NOT place any mean areal QPF data in this table, it simply
reads it.

### Figure 4.1 MAP Preprocessor

![](media/image3.jpeg){width="6.499305555555556in"
height="8.535416666666666in"}

### 4.2 Precipitation Input Options

If the SSHP MAP Preprocessor is not appropriate for use at a particular
WFO, then some other means of populating the database with mean areal
QPE should be devised. Note: if a different MAP preprocessor is being
used, the "Run MAP Preprocessor" button in the Control Window should not
be clicked by a user, since it will invoke the standard MAP
Preprocessor.

## 5. SSHP Data Transfer

In order to keep the SAC-SMA model states up-to-date and to provide
other necessary input data, the data transfer process moves data from
the OFS database at an RFC to the

IHFS database at a WFO. The transfer process is executed once per day,
after the forecast model run at the RFC has completed.

### 5.1 Transferred Data Description

+------------------------------+-----------------+--------------------+
| **Description**              | **Data Source   | **Destination      |
|                              | at RFC**        | table at WFO**     |
|                              |                 |                    |
|                              |                 | **in IHFS DB**     |
+------------------------------+-----------------+--------------------+
| SAC-SMA state variables      | OFS DB          | SacSmaState        |
+------------------------------+-----------------+--------------------+
| SAC-SMA parameters           | OFS DB          | SacSmaParams       |
+------------------------------+-----------------+--------------------+
| MAPE adjustment values       | OFS DB          | MonthlyValues      |
|                              |                 |                    |
| (12 monthly values)          |                 |                    |
|                              |                 |                    |
| OR                           |                 |                    |
|                              |                 |                    |
| ET-demand curve              |                 |                    |
|                              |                 |                    |
| (12 monthly values)          |                 |                    |
+------------------------------+-----------------+--------------------+
| Prior Computed Runoff        | OFS DB          | FcstDischarge      |
+------------------------------+-----------------+--------------------+
| MAPE Time Series             | OFS DB          | FcstOther          |
|                              |                 |                    |
| (optional)                   |                 |                    |
+------------------------------+-----------------+--------------------+

###  

### Figure 5.1 Data Transfer Process 

![](media/image4.jpeg){width="6.499305555555556in"
height="8.615277777777777in"}

![](media/image5.jpeg){width="2.127083333333333in"
height="3.686111111111111in"}

### 5.2 Invocation Description

### 5.2.1 Sending Side (RFC)

1\) Once per day, cron at an RFC invokes *run_SSHP_data_transfer***,**
which extracts data from OFS flat files and sends an XML data file (via
the AWIPS Message Handling System) to each WFO. The WFOs, OFS segment
ids, and WFO forecast points involved are configured in the control
file:

*/awips/hydroapps/whfs/local/data/app/sshp/SSHPTransfer.xml file*. See
control file format below.

On the sending side, some intermediate files will have been created in:

*/awips/hydroapps/whfs/local/data/sshp_transfer/ofs_extract_text*

*/awips/hydroapps/whfs/local/data/sshp_transfer/ofs_extract_xml*

2\) *run_SSHP_data_transfer* starts

*java ohd.hseb.sshp.messaging.SshpDataTransferMgr*

which then calls:

> 2.1) *run_SSHP_ofs_extract* (script to call *sshp_ofs_extract.LX*) on
> segment ids as defined in the SSHPTransfer.xml file. This creates
> files in
> */awips/hydroapps/whfs/local/data/sshp_transfer/ofs_extract_text*
>
> 2.1) *ohd.hseb.sshp.messaging.XmlSacEncoder* (within same Java
> process) which creates one xml data file per targeted WFO in
> */awips/hydroapps/whfs/local/data/sshp_transfer/ofs_extract_xml*
>
> 2.3) *run_SSHP_data_send*
>
> copies the extracted files to
> ***/**awips/hydroapps/whfs/local/data/sshp_transfer/outgoing*
>
> invokes *distributeProduct* and sends the data files over the AWIPS
> WAN
>
> via the Message Handling System (MHS)

### 5.2.2 Receiving Side (at each targeted WFO)

Upon receipt of a HYDRO_MODEL_DATA message, MHS invokes
*/awips/hydroapps/whfs/bin/process_hydro_model_data***,** which copies
the received data files to
*/awips/hydroapps/whfs/local/data/sshp_transfer/incoming*

and uses *ssh* to invoke *run_SSHP_data_decoder* on a PX machine**.**
The script

*run_SSHP_data_decoder* invokes *java
ohd.hseb.sshp.messaging.XmlSacDecoder* which then posts the data to the
IHFS database. After the data file has been processed, it is moved to
*/awips/hydroapps/whfs/local/data/sshp_transfer/ingest_xml.*.

### 5.3 Cleanup

The standard WHFS mechanisms for file and database cleanup are used with
SSHP.

*purge_files* will delete old files from:

*/awips/hydroapps/whfs/local/data/sshp_transfer/ingest_xml*

*/awips/hydroapps/whfs/local/data/sshp_transfer/ofs_extract_text*

*/awips/hydroapps/whfs/local/data/sshp_transfer/ofs_extract_xml*

*db_purge* will delete old records from the following tables:

FcstDischarge

FcstOther

ArealObs

### 5.4 Example XML Data Transfer Control File:

standard location:

*/awips/hydroapps/wfo/local/data/app/sshp/SSHPTransfer.xml*

\<?xml version=\"1.0\" encoding=\"ISO-8859-1\"?\>

\<SSHPTransfer\>

\<wfo\>

\<name\>SJU\</name\>

\<mhsId\>SJU\</mhsId\>

\<productId\>KSJURRMALR\</productId\>

\<fcstPoint\>

\<ofsSegmentId\>RPOP4\</ofsSegmentId\>

\<ihfsLocId\>RPOP4\</ihfsLocId\>

\<ihfsBasinId\>RPOP4\</ihfsBasinId\>

\<sendMapeTimeseries\>NO\</sendMapeTimeseries\>

\</fcstPoint\>

\<fcstPoint\>

\<ofsSegmentId\>CAGP4\</ofsSegmentId\>

\<ihfsLocId\>CAGP4\</ihfsLocId\>

\<ihfsBasinId\>CAGP4\</ihfsBasinId\>

\<sendMapeTimeseries\>NO\</sendMapeTimeseries\>

\</fcstPoint\>

\</wfo\>

\<wfo\>

\<name\>ABC\</name\>

\<mhsId\>ABC\</mhsId\>

\<productId\>KABCRRMALR\</productId\>

\<fcstPoint\>

\<ofsSegmentId\>DEFV1\</ofsSegmentId\>

\<ihfsLocId\>DEFV1\</ihfsLocId\>

\<ihfsBasinId\>DEFV1\</ihfsBasinId\>

\<sendMapeTimeseries\>NO\</sendMapeTimeseries\>

\</fcstPoint\>

\<fcstPoint\>

\<ofsSegmentId\>GHIV1\</ofsSegmentId\>

\<ihfsLocId\>GHIV1\</ihfsLocId\>

\<ihfsBasinId\>GHIV1\</ihfsBasinId\>

\<sendMapeTimeseries\>NO\</sendMapeTimeseries\>

\</fcstPoint\>

\</wfo\>

\</SSHPTransfer\>

**Element descriptions:**

\<SSHPTransfer\> - mandatory root node

\<wfo\> - For each WFO to which the RFC wants to send data, there will
be 1 WFO element. It will contain the following sub-elements: \<name\>,
\<mhsId\>, \<productId\>, and \<fcstPoint\>. There may be multiple
\<fcstPoint\> elements.

\<name\> - The abbreviated name of the WFO.

\<mhsId\> - The AWIPS Message Handling System Id for the WFO.

\<productId\> - The Product Id to use with distributeProduct.

\<fcstPoint\> - The element that represents the information used to

pull data out of OFS and send it with the correct information to the
WFO.

It contains the sub-elements: \<ofsSegmentId\>, \<ihfsLocId\>,
\<ihfsBasinId\>, \<sendMapeTimeseries\>.

\<ofsSegmentId\> - Contains the name of the OFS segment from which data
will be

> extracted for this particular forecast point.

\<ihfsLocId\> - Contains the location id of the forecast point as stored
in the WFO's

IHFS database.

\<ihfsBasinId\> - Contains the basin id associated with the forecast
point as stored in the

> WFO's IHFS database. The MAPE data will be associated with this
> basinId. This should be the same basinId used for the MAP basin at the
>
> WFO.

\<sendMapeTimeseries\> - contains values (YES or NO). Determines if the
data

> extraction program will attempt to extract MAPE time series data. If
> so, then there will be an MAPE time series sent along with Monthly
> Adjustment factors. If not, then an MAPE demand curve will be sent.

Configuration Instructions:

Edit the file, putting in only the forecast points for which the RFC
wants to extract data from OFS and send to the WFO (or back to the RFC,
if the RFC is going to run SSHP). Make sure that all of the XML elements
are properly fill out, keeping in mind that each WFO has its own \<wfo\>
element with potentially multiple \<fcstPoint\> subelements.

## 6. Local SAC-SMA State Updater

### Figure 6.1 SAC-SMA State Updater

![](media/image6.jpeg){width="6.499305555555556in"
height="8.765277777777778in"}

Although it is not recommended to use it, the SSHP subsystem includes a
utility, *run_SSHP_SAC_state_update***,** that may be run in the
background. It is useful only in cases in which the WFO is using the
SAC-SMA model and either the RFC does not intend to send state updates
to the WFO, or there is a temporary problem which is interrupting the
provision of the daily update. If the policy of the office is to execute
this utility, it should be run daily. In order for a forecast point's
SAC-SMA states to be updated locally, the checkbox labelled "Update
Model States" in the SSHP Configuration Dialog must be checked and the
preferred rainfall-runoff model must be "SAC-SMA". The local state
updater will check the database for a state for each locally updateable
(see above requirements) forecast point with a valid time that is not
older than the number of hours (the default exporation hours value is 25
hours) encoded into the script. If a site that is configured to be
updated does not have a new enough state in the database, then the local
state updater will run the SAC-SMA model in the background for the
number of hours (the default hours forward value is -2) relative to the
latest hour and save the state in the database. No forecast will be
saved.

There are currently no tokens for the expiration hours or the hours
forward, so any customization must be done in the
*run_SSHP_SAC_state_update* script itself.

## 7. System Setup

### 7.1 RFC Setup

For WFOs that are NOT going to use the SAC-SMA rainfall-runoff model,
SSHP does not require any special data transfer. The use of the API-MKC
requires FFH data, generally delivered through SHEF. The following
describes what is necessary to set up the SAC-SMA data transfer. More
data transfer details are available in Section 5.

### 7.1.1 OFS Setup 

In a standard configuration, the RFC will need to define, run, and
maintain segments for the forecast points that are to be modelled at the
WFO using the SAC-SMA rainfall-runoff model. Data from these segments
are to be transferred to the WFO. Please see *Appendix C -- RFC Segment
Definition Example*, *Appendix D -- Science Background*, and *Appendix E
-- Calibration and State Maintenance* for more details.

### 7.1.2 Data Transfer

The RFC will need to edit the data transfer control file:
*/awips/hydroapps/whfs/local/data/app/sshp/ SSHPTransfer.xml*

For details on editing/creating this file, see Section 5.4.

The RFC will need to add an entry in their crontab file to execute
*/awips/hydroapps/whfs /bin/run_SSHP_data_transfer* once per day after
the OFS model run.

### 7.2 WFO Setup

### 7.2.1 Static Data Setup (for API-MKC and SAC-SMA)

The following tables must have entries properly defined in the IHFS
database at the WFO.

*Location* -- the basic table defining a location

*Riverstat* -- preferably including the threshold runoff value

*Unitgraph* - 1 -- hour unit hydrograph

*Rating* -- includes an entry for each rating curve point

*RatingShift* - should have 0 or 1 active shifts at a time

*SSHPConfig* - see **Adding an SSHPConfig record** below

### 7.2.2 Data Generally Transferred from RFC

The following tables must have entries defined in the IHFS database at
the WFO. Typically, this data will be sent from the RFC and posted to
the database.

*SacSmaState* -- state of SAC-SMA model

*SacSmaParams* --SAC-SMA parameters

*FcstOther* -- (optional) - MAPE time series, uses physical element =
'EA'

*MonthlyValues* - MAPE Monthly Values or adjustment factors, uses
physical element = 'EA'

*FcstDischarge* - Prior Computed Runoff time series - stored in uses
physical element = "QB", dur = 1001 (1-hour), and ts = "FZ"

### 7.2.3 Token Settings

In order to run the MAP Preprocessor automatically with the MPE/Fieldgen
scripts, the *sshp_invoke_map_preprocess* token needs to be set to *ON*.
The default is *ON.*.

### 

### 7.2.4 Cron Job

If the WFO chooses to have SAC-SMA states updated locally, in the event
that RFC state transfers fail or are not desired, the
*run_SSHP_SAC_state_update* script should be initiated by cron once per
day. If the WFO receives RFC state transfers and is using this for
backup purposes, then the time of the execution should be 1 hour or more
after the expected data transfer. This script may be started on the HP
machines, but will then use ssh to execute on a px machine. If it is
started on a Linux machine, it will execute on that machine.

**Note:** Starting *run_SSHP_SAC_state_update* will only have an effect
on the SAC-SMA states stored in the database if:

1\. The location is configured in SSHPConfig to auto update AND

2\. The database does not contain a recent (\< 25 hours old) record for
the associated basin id in the SacSmaState table.

### 7.2.5 Adding an SSHPConfig record

Each modeled site should be configured in the IHFS database.

To configure a location, from the SSHP Control Window, press the
"Configure\..." button. The SSHPConfig Dialog will appear. The
SSHPConfig Dialog contains the settings as described below:

[Location Id]{.underline} - The key field.

[Basin id]{.underline} - The basin for which the areal data is to be
used.

[Model Preference -- (Preferred Rainfall-Runoff Model)]{.underline} -

Allowed values: **API-MKC or SAC-SMA**

Determines what is the default rainfall-runoff model to start with for a
particular location when starting the application. This setting, along
with the auto state update toggle, is also used when running the
SacStateUpdater, to determine the stations for which to check for
recently updated model states. The SacStateUpdater does not update
states of locations which have a preferred rainfall-runoff model other
that the SAC-SMA.

[Use Adjustment?]{.underline}

Allowed values: (**true** or **false**)

Sets whether the model will have the adjustment feature toggled on when
the AnalysisWindow is launched for this particular location id.

[Adjustment Method]{.underline}

Allowed values: **DIFF** or **RATIO.**

Sets the interpolation method to use for the Forecast Adjustment
feature.

[Blending Hours]{.underline} - Sets the number of hours for the default
length of the blending portion of the Adjustment feature. The length of
blending hours can be changed in the AnalysisWindow.

[SAC-SMA Settings]{.underline}

[Update states Locally]{.underline}

Allowed values: (**true** or **false**)

If the preferred rainfall-runoff model is SAC-SMA, the option tells the
SacStateUpdater to update the SAC-SMA model states in the event that the
preferred source of state data has not successfully sent within 25 hours
(a 1 hour grace time over 24 hours is allowed). This option has no
effect if the preferred rainfall-runoff model is other than SAC-SMA.

[Data Source Preference]{.underline}

Allowed values: **LOCAL or RFC**

Indicates the preferred source of SAC-SMA state and parameter values.
This option has no effect if the preferred rainfall-runoff model is
other than SAC-SMA.

[Use ET-Demand Curve]{.underline}

Allowed values: (**true** or **false**)

A SAC-SMA setting which indicates to the model if it should use the
monthly ET demand curve or (alternatively) use an MAPE time series for
input.

## 8. Forecast Adjustment

### 8.1 Description

SSHP contains an automated forecast adjustment feature similar to the
NWSRFS Adjust-Q operation. The purpose of this feature is to bring
forecasts in line with observed data. The feature can be configured via
the SSHP Config Dialog to be initially on or off (on a site-by-site
basis) in the AnalysisWindow. Within the AnalysisWindow, the feature be
toggled on or off manually. In the Config Dialog, the interpolation
method (DIFFERENCES or RATIOS) and the number of blending hours can be
set. The time windows for pairing (70 min) and interpolation (3 hours)
are fixed. In the AnalysisWindow, there is the ability to choose the
last time to consider observations in the adjustment computation.

### 8.2 Details

The forecast adjustment feature has 3 types of adjustments that can be
applied, **pairing**, **interpolation**, and **blending**. Forecast
values are first paired with observed points, leftover forecast values
are interpolated between the 2 sets of paired values if within the time
window for interpolation, and then any other values within the blending
time window are blended forward and backward if possible.

### 8.2.1 Pairing

Forecast values and observed values are paired up if they are within the
time window for pairing (see above **Description**) and are the best
match. The forecast values are corrected to equal the paired observed
value.

### 8.2.2 Interpolation

Any non-paired forecast value adjustments may be interpolated if the
previous and next paired values are within the interpolation time
window. The values are interpolated using either RATIOs or DIFFERENCES.
The ratio discussed is the ratio of the observed value and forecast
value from a pair of observed and forecast values (see above). If the
RATIO technique is configured to be used for the site and the both
ratios (of the observed and forecast values in each pair) are less than
or equal to 5.0 and the difference between the two ratios is less than
or equal to 2.0, an interpolated ratio will be used to adjust the
original forecast value. Otherwise, an interpolated difference will be
used to adjust the original forecast value.

### 8.2.3 Blending

When a forecast value cannot be paired with an observed value and it
cannot be interpolated (either because of a lack of a previous or later
pair of values, or the two pairs of values are too far apart in time),
then blending is attempted. If available, the adjustment value for the
previous pair of observed and forecast values is applied in the forward
direction with a linear fade-out time that is set in the user interface
and is called *blending hours*. The adjustment amount reduces to zero in
*blending hours*. The same adjustment is applied in the reverse
direction if a value has not been paired or interpolated and it has a
pair of observed and forecast values that occurs **later** in time than
the forecast value. This is known as a backward blend. Generally,
though, at the end of a forecast, there are no observed values and so
those forecast values are blended forward only.

# Appendix A: Directories and Files

### 1. Directories and File Locations

### 1.1 Application Scripts and Executable Files

directory: */awips/hydroapps/whfs/bin*

> *run_SiteSpecific*
>
> *run_SSHP_data_transfer*
>
> *run_SSHP_data_decode*
>
> *run_SSHP_data_send*
>
> *run_SSHP_MAP_preprocess*
>
> *run_SSHP_ofs_extract*
>
> *run_SSHP_SAC_state_update*
>
> *process_hydro_model_data*
>
> *SiteSpecific.jar*
>
> *sshp_ofs_extract.LX*

### 1.2 Log Files

directory: */awips/hydroapps/whfs/local/data/log/sshp*

> *MAPPreprocessor.log*

*MAPPreprocessor.stdout.log*

*MAPPreprocessor.stdout2.log*

> *SSHP.log*
>
> *SacStateUpdate.log*
>
> *SacStateUpdate.stdout.log*
>
> *SshpDataTransferMgr.log*
>
> *SshpDataTransferMgr.stdout.log*
>
> *SshpDataSender.log*
>
> *SacXMLDecoder.log*

### 1.3 Application Setup Files

directory: /*awips/hydroapps/whfs/local/data/app/sshp*

> *SSHPTransfer.xml*

### 1.4 Data Transfer Directories

The following directories exist at the RFC and the WFO. An RFC may wish
to send the extracted OFS to itself, in which case, the directories
labelled "applies to WFO" will also apply to the RFC.

*/awips/hydroapps/whfs/local/data/sshp_transfer*

Applies to RFC:

*/awips/hydroapps/whfs/local/data/sshp_transfer/ofs_extract_text*

*/awips/hydroapps/whfs/local/data/sshp_transfer/ofs_extract_xml*

*awips/hydroapps/whfs/local/data/sshp_transfer/outgoing*

Applies to WFO:

*/awips/hydroapps/whfs/local/data/sshp_transfer/ingest \_xml*
*/awips/hydroapps/whfs/local/data/sshp_transfer/incoming*

### 2. Script and Executable Descriptions

### 

*SiteSpecific.jar* - contains all of the Java classes for the
application and the other processes.

*run_SiteSpecific* - starts current version of the application

*run_SiteSpecific_API* - starts old version of the application

*run_SSHP_data_decode* - normally called from process_hydro_model_data

*run_SSHP_data_transfer* - main script for starting the data transfer
process from RFC to WFO

*run_SSHP_MAP_preprocess* - invoked by MPE/Fieldgen scripts

*run_SSHP_ofs_extract* - invokes *sshp_ofs_extract.LX*

*run_SSHP_SAC_state_update* - Calculates local updates of SAC-SMA states
for sites that are configured to be updated locally. Useful when RFC
state updates not available

*run_SSHP_data_send* - sends processed XML file to WFO via MHS.Uses
distributeProduct.

*sshp_ofs_extract.LX* - uses OFS routines to extract data from OFS flat
file database

*process_hydro_model_data* - invoked by AWIPS Message Handling System
(MHS) upon message receipt

# Appendix B -- SSHP AppsDefaults Tokens

*sshp_java_process_host* = px1f

This token contains the host name of the machine on which the
MAPPreprocessor,

the SacXmlDecoder, and the SacStateUpdater will run.

*sshp_invoke_map_preprocess* = ON

This token is a switch to determine whether or not to run the SSHP
MAPPreprocessor when the MPE/Fieldgen scripts (run_mpe_fieldgen and
rerun_mpe_fieldgen) are invoked. If this is set to ON (default is ON),
the SSHP MAPPreprocessor will be initiated in the background. If
run_SSHP_MAP_preprocess is executed on the HP machines, it will use ssh
(secure shell) to invoke run_SSHP_MAP_preprocess on a Linux machine.

*rfcwide_xmrg_dir* = */awips/hydroapps/precip_proc/local/data/mpe/qpe*

This token identifies the directory location for the gridded best
estimate QPE files to be used by the MAPPreprocessor.

*sshp_fcst_ts token* = FZ

This controls the default value of the forecast's type/source value in
the Save Forecast Height/Discharge Dialogs.

*sshp_initial_forecast_length* = 24

This token sets the default length in hours of a forecast for all
forecast points. The "live" value can be changed in the Analysis Window.

*sshp_max_forecast_length* = 120

This token sets the maximum length of a forecast for all forecast
points. This sets the maximum value of the forecast length in hours
available to the user of the user interface.

*sshp_sac_update_expiration_hours* = 25

After the SAC-SMA model state is older than this number of hours, the
SAC State Updater will

run the model and save the state.

sshp_sac_update_hours_forward = -2

When the SAC State Updater runs, it will run from the time of the last
valid state to the current time plus the value of this token. In this
example, since the value is negative, the time will actually be 2 hours
*before* the current time rounded back to the top of the hour.

The following are tokens defined in national .Apps_defaults (all are
directories). DO NOT CHANGE.

*local_data_sshp_dir : \$(whfs_local_data_dir)/sshp_transfer*

*sshp_control_dir : \$(whfs_local_data_dir)/app/sshp*

*sshp_ofs_extract_text_dir : \$(local_data_sshp_dir)/ofs_extract_text*

*sshp_ofs_extract_xml_dir : \$(local_data_sshp_dir)/ofs_extract_xml*

*sshp_ingest_xml_dir : \$(local_data_sshp_dir)/ingest_xml*

*sshp_incoming_dir : \$(local_data_sshp_dir)/incoming*

*sshp_outgoing_dir : \$(local_data_sshp_dir)/outgoing*

*sshp_log_dir : \$(whfs_log_dir)/sshp*

# Appendix C -- RFC Segment Definition Example

Provided By SERFC, MAY 2004

\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

For the SAC-SMA Site Specific Model:

The INFL., SSTG, QINE, SMZC and ROCL time series were all set to be
OUTPUT.

Filesize and Filecrat will have to be reviewed to assure that these time
series can be output.

1-hr Unit hydrographs will have to be defined and sent to the WFO.

Rating Curves will also have to be supplied to the WFO.

\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

Here is an example of a segment that was defined on a 1-hr interval:

RESEGDEF

IDENTIFIER CAGP4 18.24 66.01

TITLE RIO GRANDE DE LOIZA

UPSTREAM

DOWNSTREAM

DEF-TS

CAGP4 MAPX 1 INPUT FPDB

CAGP4 MAPX

CAGP4 INFW 1 OUTPUT FPDB

CAGP4 INFW 18.24 66.01 GRANDE DE LOIZA-CAGU

CAGP4 SQIN 1 INTERNAL

CAGP4 STG 1 INPUT FPDB

CAGP4 STG

CAGP4 QIN 1 INTERNAL

CAGP4 SSTG 1 OUTPUT FPDB

CAGP4 SSTG 18.24 66.01 GRANDE DE LOIZA-CAGU

CAGP4 QINE 1 OUTPUT FPDB

CAGP4 QINE 18.24 66.01 GRANDE DE LOIZA-CAGU

CAGP4 SMZC 1 OUTPUT FPDB

CAGP4 SMZC 18.24 66.01 GRANDE DE LOIZA-CAGU

CAGP4 ROCL 1 OUTPUT FPDB

CAGP4 ROCL 18.24 66.01 GRANDE DE LOIZA-CAGU

END

SAC-SMA CAGP4

GRANDE DE LOIZA-CAGU 1 CAGP4 MAPX CAGP4 INFW

0 CAGP4 CAGP4 1 1

1.0001.000 15.0 15.00.3000.0400.3000.000 00.000

95.0 3.00 90. 80.0 170.0.225.01200.1000.300 0.00

3.003.003.003.403.403.804.204.204.003.603.303.00

3.1 0.0 73. 0.1 53. 60. 0

FFG CAGP4

CAGP4 AREA CAGP4 0 0.00 0.00

CAGP4 SAC-SMA CAGP4

CLEAR-TS

CAGP4 SQIN 1

UNIT-HG CAGP4

GRANDE DE LOIZA-CAGU 89.8 16 CARRY ENGL 0.000

CAGP4 INFW 1 CAGP4 SQIN 1

6900.0 10000.0 11000.0 10000.0 8000.0 4000.0 2200.0

1500.0 1220.0 900.0 750.0 500.0 400.0 300.0

200.0 100.0

0.0007 0.0007 0.0007 0.0007 0.0007 0.0008 0.0008

0.0007 0.0007 0.0008 0.0008 0.0008 0.0007 0.0014

0.0009

STAGE-Q CAGP4B

GRANDE DE LOIZA-CAGU CAGP4 1 RDCO

CAGP4 STG 1 CAGP4 QIN 1

1.37 2. -0.04 0

ADJUST-Q CAGP4

GRANDE DE LOIZA-CAGU 1 0 0

CAGP4 QIN 1

CAGP4 SQIN 1

CAGP4 QINE

500

1

STAGE-Q CAGP4C

GRANDE DE LOIZA-CAGU CAGP4 2 RDCO

CAGP4 SSTG 1 CAGP4 QINE 1

1.37 2. 0.00 0

PLOT-TUL CAGP4

1 1 101 0 100 1 1 5 3 I - 0 0 0

0 25 F U M CAGP4 0 0 0

XMP SSTG QIN

CAGP4 MAPX LIST F5.2, 1

CAGP4 SSTG LIST F7.1, 1

CAGP4 QIN PLOT O 1

CAGP4 QINE BOTH A F9.0, 1

CAGP4 SQIN PLOT S 1

END

STOP

# Appendix D -- Science Background

> Sacramento Model and the Site Specific Hydrologic Prediction Tool
>
> Mike Smith
>
> February 6, 2004

1.  Overview

The Sacramento Soil Moisture Accounting Model (SAC-SMA) is being added
to the Site Specific Hydrologic Prediction tool to complement the
existing Antecedent Precipitation Index (API) rainfall/runoff model. In
SSHP, the SAC-SMA will be run at a 1-hour time step. The parameters used
by the basins need to be created for that time step and the actual
forecast basin size. The goal of this approach is to apply the SAC-SMA
at the spatial and temporal scale for which the forecasts are to be
issued. This is to avoid the documented scale sensitivities of the both
the SAC-SMA model parameters and states and the resulting problems of
modeling a 'parent' basin in OFS at a 6-hour time step and using those
parameters and states to run the SSHP at an interior sub-basin at an
hourly time step. The model will be executed continuously so as to have
the best estimate of the initial states at run time.

2.  Scope

This document covers aspects of the SAC-SMA application only and is not
intended to describe all functional components of the SSHP tool.

3\. Model Set-up, Parameterization, and Calibration

We identify two cases for the use of the SAC-SMA version: gaged and
ungaged basins. However, it is anticipated that the predominant usage of
this application will be in gaged basins and run at a one-hour time
step.

3.1 Gaged basins.

In this use case, the model is applied to a watershed that is gaged and
may or may not coincide to a basin being forecasted by the RFC using the
Operational Forecast System (OFS), usually at a 6-hour time step. Here,
there is the possibility that the SAC-SMA and unit hydrographs (UHG) can
be calibrated against observed streamflow data. Typical calibration
procedures can be applied to derive the optimum values of the SAC-SMA
parameters.

3.1.1 SAC-SMA Parameterization

Initial values of the SAC-SMA for the SSHP application can be obtained
from several sources. First, the RFC can apply calibrated SAC-SMA
parameters from the corresponding OFS basin if the two coincide or if
the basin to be modeled is a sub-basin of the OFS basin. Or, initial
parameters may be defined using the hydrograph analysis techniques
described in the calibration manual developed by Eric Anderson
(Anderson, 2002). Finally, the user can select the initial SAC-SMA
parameter estimates developed by Koren et al. (2000) and available via
the Calibration Assistance Program (CAP).

3.1.2 Unit Hydrograph

In the application to gaged basins, a UHG can also be derived and
calibrated. (The user is referred to Chapter 7-6 in Anderson, 2002 for a
discussion of UHG derivation). An initial UHG can be developed through
traditional analysis of observed hydrographs. Or, the user can adopt the
UHG from the OFS basin and make the required adjustments for any changes
in drainage area or time step (e.g., S-Curve analysis). The UHG
derivation options within IHABBS may also be used. An emerging and
promising approach is to use a UHG derivation tool developed as part of
the variational assimilation research being performed in the Hydrology
Lab. At the time of this writing, this tool is being tested at several
RFC's.

3.1.3 Calibration

Given that the SSHP is applied to a gaged basin, parameter calibration
can take place. The Manual-Expert calibration steps described in detail
in Anderson (2002) should be followed to calibrate the SAC-SMA
parameters and the UHG. A calibration time series of precipitation can
be derived from radar data using the MAPX calibration preprocessor and
basin boundary information. The calibration MAP preprocessor may be used
to derive a one-hour MAP time series if the reporting rain gage density
is sufficient for such an area.

3.2 Ungaged Basins

In this use case, the SAC-SMA SSHP model is applied to an ungaged
location and cannot be calibrated. However, the model is set up and run
continuously at the spatial and temporal scale for which forecasts are
to be issued.

3.2.1 SAC-SMA Parameterization

Here, it is recommended that the initial soils-based parameters derived
by Koren et al. (2000) and available via CAP be used. Given the basin
boundary coordinates, CAP may be used to derive spatially-lumped SAC-SMA
parameters.

3.2.2 Unit Hydrograph

For an ungaged application, the UHG for the SAC-SMA model can be derived
using synthetic methods in IHABBS or by appropriately scaling a UHG from
a downstream point.

4\. Model States and Execution

In either the gaged or ungaged application, the SAC-SMA is run
continuously. Precipitation estimates that are quality controlled are
used to execute the model in order to maintain the best possible states.
At the time of forecasting, the user obtains the most recent saved state
variables and observed rainfall to run the model up to the current time.
The SSHP tool is then used with user-defined forecast precipitation to
generate forecasts into the future. Depending on the time of day, it may
not be possible to quality control the observed precipitation data
before running the model from the last carryover date to the current
time. In such cases, the SAC-SMA can be re-run from the same carryover
date once quality controlled precipitation estimates are available so as
to maintain the best possible state variables.

A future enhancement to the SAC-SMA SSHP tool would be to incorporate
the variational assimilation method to develop the most appropriate
state variables. Current research in HL shows that variational
assimilation is very promising.

5\. References

Anderson, E.A., 2002. Calibration of Conceptual Models for Use in River
Forecasting. Hydrology Lab, available at:
<http://www.nws.noaa.gov/oh/hrl/calb/calibration1102/main.htm>

Koren, V., I., Smith, M., Wang, D., and Zhang, Z., 2000. Use of soil
property data in the derivation of conceptual rainfall-runoff model
parameters. Preprints: 15^th^ Conference on Hydrology, Long Beach, CA,
American Meteorological Society, 10-14 January, 103-106.

# Appendix E -- Calibration and State Maintenance

# 

WFO use of the Sacramento model introduces issues that do not apply to
use of the API models. The major issues are those of parameter
calibration and model state maintenance. Parameter calibration is an
issue because SSHP will be running the Sacramento model at a 1-hour time
step. Studies of the Sacramento model using different spatial and
temporal scales indicate that the 6-hour parameters for a large parent
basin modeled at an RFC are not necessarily transferable to a smaller,
interior basin targeted for hourly simulations at a WFO using SSHP. To
avoid uncertainties and problems caused by crossing time/space scales,
the SAC-SMA runs in continuous mode (as is done in OFS) at the space
scale of the target basin with a 1-hour time step. The following table
displays some options for addressing this issue.

### 1. Model Parameter Calibration Options

+---------------------+------------------------------------------------+
| **Option Name**     | **Steps To Obtain Model Parameters for SSHP    |
|                     | Basin**                                        |
+---------------------+------------------------------------------------+
| Pure Calibration    | 1\. Calibrate the SSHP basin for 1 hour time   |
|                     | step.                                          |
|                     |                                                |
|                     | 2\. Develop 1-hour Unit Hydrograph for the     |
|                     | SSHP basin.                                    |
+---------------------+------------------------------------------------+
| Partial Calibration | 1\. Calibrate the parent basin for 1-hour time |
|                     | step operation.                                |
|                     |                                                |
|                     | 2\. Generate a priori parameters with CAP for  |
|                     | both the parent and child basins.              |
|                     |                                                |
|                     | 3\. Apply a ratio of the parameters obtained   |
|                     | from CAP to the calibrated parent basin's      |
|                     | parameters to obtain parameters for the SSHP   |
|                     | (child) basin.                                 |
|                     |                                                |
|                     | 4\. Develop a 1-hour Unit Hydrograph for the   |
|                     | SSHP (child) basin.                            |
+---------------------+------------------------------------------------+
| No calibration      | 1\. Generate a priori parameters with CAP for  |
|                     | the SSHP basin.                                |
|                     |                                                |
|                     | 2\. Develop a 1-hour Unit Hydrograph for the   |
|                     | SSHP basin.                                    |
+---------------------+------------------------------------------------+

Issues regarding model state maintenance also appear with the usage of
the Sacramento model at a WFO. The various options differ in the degree
of participation and interaction between RFC and WFO. In the RFC-
managed options, the model states can be updated using RFC information,
and this requires more RFC involvement. The WFO-managed options put the
responsibility for state management at the WFO. This option requires
that the model at the WFO be run for each hour, so that the state
variables remain current. A possible near-future upgrade to the SSHP in
the state maintenance area is the addition of VAR functionality which
would continuously adjust state variables to optimize the model output.
This would create another type of WFO-managed state maintenance.
Presumably, this version could recover faster from out-of-date model
state information.

### 2. Model State Maintenance Options

+-----------------------+-----------------------------------------------+
| **Option Name**       | **Option Description**                        |
+-----------------------+-----------------------------------------------+
| RFC -- managed with   | RFC models the same basin at 1-hour time step |
| OFS                   | in OFS and regularly updates WFO's model      |
|                       | state stored at the WFO. The SSHP would       |
|                       | update states locally at the WFO in between   |
|                       | RFC updates. Those local state updates could  |
|                       | be overridden by an RFC state update.         |
+-----------------------+-----------------------------------------------+
| RFC --managed without | RFC models the same basin at 1-hour time step |
| OFS                   | using Site Specific at the RFC and regularly  |
|                       | updates WFO model state. The SSHP updates     |
|                       | state locally at the WFO in between RFC       |
|                       | updates. Those local state updates could be   |
|                       | overridden by an RFC state update.            |
+-----------------------+-----------------------------------------------+
| RFC -managed with VAR | RFC models the same basin at 1-hour time step |
|                       | using Site Specific at the RFC and regularly  |
| (future?)             | updates WFO model state. The RFC uses VAR and |
|                       | sends hourly state updates to the WFO.        |
+-----------------------+-----------------------------------------------+
| WFO -managed          | The WFO runs the model for each hour and      |
|                       | maintains its own state.                      |
+-----------------------+-----------------------------------------------+
| WFO-managed with VAR  | The WFO runs the model for each hour and      |
| (future?)             | maintains its own state.                      |
|                       |                                               |
|                       | VAR adjusts the state parameters regularly to |
|                       | optimize forecast.                            |
+-----------------------+-----------------------------------------------+

As shown above, the SSHP application is capable of maintaining its own
state in the IHFS database using newly incorporated tables, but this is
not expected to be the standard mode of operation. SSHP has the ability
to have its model state and even model parameters be updated with data
provided by the RFC. The use of this RFC-to-WFO update capability is
expected to be the most common mode of operation. Updates from RFC to
WFO are handled by an automated process (running at the RFC) to extract
data from OFS and send the data (via the AWIPS WAN) to the WFO. At the
WFO, the updated model state and model parameters (if changed) are
stored in the IHFS database. The prior computed runoff is stored. Also
stored are the MAPE monthly adjustment values or ET-demand curve, and
the MAPE time series (if applicable).

# Appendix F -- SSHP Database Tables

1\. SSHPConfig

Holds configuration data for model configuration by forecast point.

TABLE DEFINITION:

> lid char(8) not null,
>
> basin_id char(8) not null,
>
> postingtime datetime year to second not null,
>
> model_pref char(20) not null,
>
> auto_process char(1) not null,
>
> source_pref char(20) not null,
>
> use_static_evap char(1) not null,
>
> use_blend char(1) not null,
>
> blend_method char(20) not null,
>
> blend_hours integer not null
>
> lid
>
> Location Id of the forecast point.
>
> basin_id
>
> Id of the basin.
>
> postingtime
>
> Time of posting of this record
>
> model_pref
>
> The rainfall runoff model that is preferred for SSHP startup
>
> auto_process
>
> Y or N to update states locally if RFC update not available or
> desired.
>
> source_pref -- ("RFC" or "LOCAL")
>
> If auto_process is "Y", the local SAC-SMA state updater checks for
> recent state updates from the preferred source.
>
> use_static_evap
>
> If "Y" then the ET-DEMAND curve is used, otherwise the MAPE time
> series will be used.
>
> use_blend
>
> The Forecast Adjustment feature default value for the AnalysisWindow.
>
> The name should be changed to use_adjustment.
>
> blend_method
>
> The interpolation method of the Forecast Adjustment feature.
>
> blend_hours
>
> The number of hours for the blend portion of the Forecast Adjustment
> feature.

2\. MonthlyValues

> Used in SSHP to hold the daily mean (by month) ET-Demand curve values
> or adjustment factors to the MAPE time series.

TABLE DEFINITION:

> lid char(8) not null,
>
> pe char(2) not null,
>
> dur smallint not null,
>
> ts char(2) not null,
>
> extremum char(1) not null,
>
> adjustment char(1) not null,
>
> postingtime datetime year to second not null,
>
> jan_value float not null,
>
> feb_value float not null,
>
> mar_value float not null,
>
> apr_value float not null,
>
> may_value float not null,
>
> jun_value float not null,
>
> jul_value float not null,
>
> aug_value float not null,
>
> sep_value float not null,
>
> oct_value float not null,
>
> nov_value float not null,
>
> dec_value float not null

3\. SacSmaState

> Used in SSHP to hold the updates of the SAC-SMA model states.

TABLE DEFINITION:

> basin_id char(8) not null,
>
> source char(20) not null,
>
> validtime datetime year to second not null,
>
> basistime datetime year to second not null,
>
> postingtime datetime year to second not null,
>
> uztwc float not null,
>
> uzfwc float not null,
>
> lztwc float not null,
>
> lzfsc float not null,
>
> lzfpc float not null,
>
> adimc float not null

4\. SacSmaParams

> Used in SSHP to hold the updates of the SAC-SMA parameters.

TABLE DEFINITION:

> basin_id char(8) not null,
>
> source char(20) not null,
>
> validtime datetime year to second not null,
>
> postingtime datetime year to second not null,
>
> uztwm float not null,
>
> uzfwm float not null,
>
> uzk float not null,
>
> pctim float not null,
>
> adimp float not null,
>
> riva float not null,
>
> zperc float not null,
>
> rexp float not null,
>
> lztwm float not null,
>
> lzfsm float not null,
>
> lzfpm float not null,
>
> lzsk float not null,
>
> lzpk float not null,
>
> pfree float not null,
>
> rserv float not null,
>
> side float not null,
>
> peadj float not null,
>
> pxadj float not null,
>
> efc float not null

5\. Other Tables

The following are well-established IHFS tables used by SSHP. Please
refer to IHFS database documentation for more details.

ContingencyValue

Input : Used by API-MKC for FFH values.

FcstDischarge

Input: Prior Computed Runoff time series. Basin ID is stored as the lid.

Output: Forecast discharge time series for forecast point.

FcstHeight

Output: Forecast height time series for forecast point.

Height

Input: Used for observed height time series and to calculate baseflow
for API-MKC.

FcstOther

Input: MAPE time series. The basin id is stored as the lid.

ArealFcst

Input: Basin QPF time series. The basin id is stored as the lid.

ArealObs

Input: Processed 1-hour basin MAP QPE time series. The basin id is
stored in the lid.

Unitgraph

Input: Contains Unit hydrograph.

Rating

Input: Contains raw (unshifed) rating curve data points.

RatingShift:

Input: Contains records for rating shifts.

LineSegs:

Input: Used by MAP Preprocess to compute basin-average QPF.

IngestFilter:

Input and Output: SacXmlDecoder adds a record to allow for data ingest
if a record does not exist for a particular forecast point.

# Appendix G - Unit Hydrograph Editor Guide

## 1. Introduction

In OB5, the Site-Specific Hydrologic Predictor added the Unit-Hydrograph
Editor.

This editor is also available through HydroBase. During the OB5 system
release, the IHFS table UnitGraph was changed to add a column and alter
its primary key. This document describes these changes and some of their
impacts.

## 2. Table Modification

The column \"model\" (char(10)) was added to UnitGraph before the
existing column \"dur\". For previously existing rows, the \"model\"
column is initially set to \"ANY\". The primary key was changed to (lid,
area_id, model, dur, ordinal) and and index was added (lid, area_id,
model, dur). This means that a given location might be associated with
more than one area. Also, the same lid, area_id combination may have
more than one unithydrograph associated with it. There might be a
unithydrograph than is calibrated for the API-MKC and one that is
calibrated for the SAC-SMA rainfall-runoff model.

## 3. Data Contents and Usage

### 3.1 UnitGraph Table in IHFS

+---------------+-----------+------------+--------------+-------------+
| Column Name   | Key       | Type       | Description  | Sample      |
|               | Column?   |            |              | Content     |
+---------------+-----------+------------+--------------+-------------+
| lid           | YES       | Char(8)    | Handbook 5   | BLUO2       |
|               |           |            | Location Id  |             |
+---------------+-----------+------------+--------------+-------------+
| area_id       | YES       | Char(8)    | Area (Basin) | BLUO2H or   |
|               |           |            |              |             |
|               |           |            | Identifier   | BLUO2       |
|               |           |            |              |             |
|               |           |            |              | (may be     |
|               |           |            |              | same as     |
|               |           |            |              | lid)        |
+---------------+-----------+------------+--------------+-------------+
| model         | YES       | Char (20)  | rai          | ANY or      |
|               |           |            | nfall-runoff |             |
|               |           |            | model for    | API-MKC or  |
|               |           |            | which this   |             |
|               |           |            | may be used  | SAC-SMA     |
+---------------+-----------+------------+--------------+-------------+
| dur           | YES       | integer    | duration     |             |
|               |           |            | code         |             |
+---------------+-----------+------------+--------------+-------------+
| ordinal       | YES       | integer    | time period  |             |
|               |           |            | number       |             |
+---------------+-----------+------------+--------------+-------------+
| discharge     | NO        | 8 byte     | discharge    |             |
|               |           | float      | value in     |             |
|               |           |            |              |             |
|               |           |            | CFS          |             |
+---------------+-----------+------------+--------------+-------------+
|               |           |            |              |             |
+---------------+-----------+------------+--------------+-------------+

The SSHP uses the data in the UnitGraph table. In order to be used by
SSHP, each forecast point must be configured in SshpConfig and the lid,
basin_id combination found there must match the lid, area_id found in
UnitGraph. The contents of the new "model" column (as entered from this
editor) may be "ANY", "API-MKC", or "SAC-SMA". The SSHP will find the
closest match available for use with the selected rainfall-runoff model.
"ANY" is a wildcard and will be used if the specific model type is not
available. "ANY" is the value to which the "model" column was
automatically set in the OB4 to OB5 database conversion. This way, the
user could continue to use the SSHP without having to enter new rows in
the UnitGraph table.

## 4. Editing

In either HydroBase or SSHP, call up the Unit Hydrograph Editor for a
particular

location id (lid). Follow the appropriate steps below to alter the unit
hydrograph in **WORKING MEMORY**. After you are satisfied with your
changes, press the **Save** button, or your changes will be **lost**
when you close the editor!

### 4.1 Adding A Record In Memory

To add a record, fill in the area id, model, duration, ordinal, and
discharge text boxes or option menus. Press **Add** button. If the
ordinal already exists for that unit hydrograph, an error message dialog
will appear.

### 4.2 Removing A Record In Memory

To remove a record, click on the single record to remove and then press
the **Remove** button. A confirmation window will appear, press *Yes* to
remove, *No* to keep the record.

### 4.3 Modifying A Record In Memory

To modify a record, change the discharge value and press the **Modify**
button. No confirmation dialog will appear and the discharge value will
have been changed.

### 4.4 Saving Changes To Database

All operations on a record-by-record basis (adding, removing, modifying
records) are performed only **IN MEMORY ONLY**. To save the changes to
the database, press the **Save** button. When any of the records is
modified, the text on the **Save** button changes to remind the user
that changes will need to saved to be made permanent.

### 4.5 Deleting Unitgraphs From Database

To delete an entire unit hydrograph from the database, in the tabular
section, click on a record that belongs to the unit hydrograph, then
click on the **Delete** button. A confirmation dialog will appear. The
confirmation dialog will include the data values that describe the unit
hydrograph to be deleted. Press *YES* to confirm, *NO* to decline.

### 4.6 Importing and Exporting Hydrographs

Importing a hydrograph is useful when the user wants to avoid using the
editor to enter records one at a time. If the the file to import
conflicts with what is already in the database, or is otherwise faulty,
an error dialog will appear. If unsure of the valid format of the UHG
file, enter a small unit hydrograph and export it. The user can export a
hydrograph to a file by pressing the **Export** button. Exported files
may be modified by hand and then imported into the database by pressing
the **Import** button.

### 4.7 Sorting

In order to make editing easier, the rows of the tabular section can be
sorted by clicking on the column header. Clicking again on a column
header reverses its sort order from ascending to descending or vice
versa. For example, to sort by discharge, click on the word "Discharge"
at the top of the column. Click again to reverse the sort order.

The program remembers previous requests to sort by a particular column
and honors those requests when possible. To order by ordinal, model, and
area id at the same time, click on the column headers for ordinal,
model, and area id in that order.

### 4.8 Viewing

To the right of the tabular section, is the graphical section. To select
the unit hydrograph to graph, click on the unit hydrograph descriptor in
the small table below the graph. To select more than one unit
hydrograph, hold down the *shift* key and click on a descriptor.

The graphical section displays what is **IN MEMORY**, not necessarily
what is in the database. Remember to **SAVE** unit hydrographs that you
want to keep.

### 4.9 Screen Shot

![](media/image7.png){width="6.125in" height="4.502083333333333in"}