United States Office of Water EPA-823-R-99-005
Environmental Protection 4305 June 1999
r/EPA BASINS Technical Note 4
Incorporating Upstream Flow and
Water Quality Time Series in the
Nonpoint Source Model (NPSM)
-------
BASINS Technical Note 4
Incorporating Upstream Flow and Water Quality Time Series in the NPSM
June 2, 1999
INTRODUCTION:
To model water quality in reaches located in downstream portions of large watersheds, it can be
advantageous to use monitored flow and water quality data in lieu of modeling the entire
upstream portion of the watershed. Stream flow rate and water quality data is readily available
for thousands of gage stations throughout the U.S. While the NPSM does not explicitly allow
time series import for upstream flow and constituent loadings, the following procedures
demonstrate how to modify the input file, incorporate the desired upstream flow and/or water
quality loading rate time series, and run the program in dos mode.
INCORPORATING UPSTREAM FLOW:
Run the NPSM to produce user control input (uci) file:
Setup the NPSM for all other parameters and run the model. NPSM creates an HSPF user
control input (uci) file and executes the hspf model in dos mode. The uci file is placed in the
modelout/ directory and can be read and edited with a text editor.
Download daily flow data from USGS web page:
Obtain the gage station id number from BASINS (8 digit number in "Agcy" field in the
"Attributes of USGS gage stations" data table). Go to the USGS NWIS web page at:
http://h2o-nwisw.er.usgs.gov/nwis-w/US/. Select the state of interest and enter the usgs gage
station id number or search the list of United States gaging stations using the station id and/or
other identifying information about the station. Download historical streamflow daily values for
the simulation period of your model. For the output format, select tab-delimited text data file in
MM/DD/YYYY format. Be sure to save as a text file.
Add USGS gage station data to the Water shed Data Management (WDM) file:
Obtain the WDMUtil (beta version) from the BASINS web page. Start WDMUtil and
open the WDM file for the project. Open the gage station data (.cgi) file (see the Tutorial:
Lesson 2 and Data Access sections in WDMUtil documentation) and fill out the Data
Initialization form. Determine the number of lines of text to skip when importing the file
(USGS .cgi files typically contain 38 lines of text before the time series starts). If you selected
the MM/DD/YYYY format when downloading the gage station data, the format for reading the
data is M2,X,D2,X,Y4,V. The Scenario is OBSERVED, the Constituent is FLOW, and the
Location is the id number of the gage station. Enter a Description of the data set such as "USGS
gage daily flow (cfs)." The Time Units are Days and Time Step is 1. Select the Start and End
Page 1 of 10
-------
dates by placing the cursor on a year, month or day block and pressing the up or down arrow.
Click "OK" to import the time series to the WDMUtil. Finally, add the data to WDM file by
highlighting the flow rate time series and clicking the "Write Time Series to WDM" button. Fill
in the Output DSN and click the Write button. Exit the WDMUtil program. WDMUtil will
interpret the new data as a potential new meteorological data location for use in BASINS. On
the BASINS Information Update form, click on the location name of the new data and then click
the Delete Row button so that this will not be added to the list of available meteorological data
locations. Click the OK button.
Modify the .ucifile to accept the time series as an input to the model:
Use a text editor to open the User Control Input (uci) file (in the Modelout/
directory). Find the EXT SOURCES section (toward the end of the file). Add another line
under the last RCHRES line as follows:
WDM# ### FLOW ENGL 1.98347 DIV RCHRES 1 EXTNL IVOL
where:
• WDM# - refers to WDM volume to which gage flow time series was written (e.g. WDM1);
• ### refers to the DSN number (e.g. 779);
• FLOW is the name given to the time series ("Constituent" in Data Initialization screen);
• ENGL refers to English units (only English units available in BASINS 2.0);
• 1.98347 - conversion factor (cfs to ac-ft/day)
• DIV - indicates to convert source time series (FLOW) to target time series (IVOL) (i.e.
divide by conversion factor);
• RCHRES # - refers to the RCHRES block to which the flow will be added (i.e. most
upstream reach);
• EXTNL refers to an external data source (in this case a time series in a WDM file);
• IVOL - refers to the model parameter for input flow.
Refer to the HSPF user manual (p. 649) for formatting for this line of input, as well as using the
previous lines of input as a guide. Save the uci file and exit the text editor.
Run NPSM in dos mode using the modified uci and WDM files:
The run command should look like this:
C:\Basins\models\Npsm\XNPSMllx.exe c:\Basins\modelout\\.uci
where and are the directory and project file names for your project. Use
the Post-processor in the NPSM to view the output. You can modify the output file names in the
FILES section of the .uci file (at the top) to write the output to different files or directories.
Note: Each time you modify the project file (.prj) in the NPSM, you'll need to re-run the model
from the NPSM window in order to create a uci file that reflects the changes to the .prj file. You
then need to modify the uci file, as before, to reference the flow rate time series in the EXT
SOURCES block.
Page 2 of 10
-------
INCORPORATING WATER QUALITY LOADINGS:
If any water quality constituents are being simulated, then a mass-loading time series for each
constituent must also be created. Each such time series can be either stored in the WDM file or
in a PLTGEN/MUTSIN-formatted text file (up to 10 constituents per file). The principal
advantages of the WDM file are greater speed and less required disk storage space. The
advantage of the PLTGEN/MUTSIN format is that the data can be created, examined, and
manipulated without the need of WDM utility programs such as WDMUtil.
Make sure that the units of the time series matches that specified in the Time Series Catalog (p.
668, HSPF User Manual; NPSM uses English units). The time series may be at any time step
from the run interval up to 1 month (NPSM runs on an hourly time step). Consult the Time
Series Catalog in the HSPF user manual for the proper time series name for the inflow of each
constituent (e.g. ISED, IHEAT). This name will appear as the target name in the EXT
SOURCES or NETWORK block, as appropriate (see below).
The procedure to store the data in the WDM file is similar to that described above for flow,
except that the original text file must be constructed by hand rather than being provided from the
USGS web site. The formatting of the data can be accomplished easily in a spreadsheet, based
on data exported from BASINS Water Quality Observation data, or provided directly by the
user, with the results exported as a text file. This file is then read by WDMUtil.
Once the DSN has been created, a corresponding line must be added to the EXT SOURCES
block:
WDM# ### SEDM ENGL 0.05 DIV RCHRES 1 INFLOW ISED 1
WDM# ### SEDM ENGL 0.70 DIV RCHRES 1 INFLOW ISED 2
WDM# ### SEDM ENGL 0.25 DIV RCHRES 1 INFLOW ISED 3
WDM# ### HEAT ENGL DIV RCHRES 1 INFLOW IHEAT
where:
• SEDM is the name given to the sediment loading time series in the WDM file
• INFLOW is the time series group for all inflows of constituents
• ISED(l-3) refers to the model parameters for inflow of sand, silt, and clay respectively.
The multipliers .05, .70, and .25 are used to divide the sediment inflow into these size
fractions, assuming that only the total load is available for input. If separate input time series
are available for each fraction, then they are used directly, without multipliers.
• HEAT is the name given to the heat loading time series in the WDM file
• IHEAT refers to the model parameter for inflow of heat
Page 3 of 10
-------
The PLTGEN/MUTSIN method is essentially the same method that NPSM uses to represent a
point source. If point sources are also present in your model, then you can use both the data file
and the changes to the UCI as guides. First, the data file with the proper format must be
constructed. Again, this can easily be accomplished in a spreadsheet program. Then, a
MUTSIN operation is added in the OPN SEQUENCE block of the uci file, just above the
RCHRES which receives the loads. If more than 10 constituents are being modeled, then an
additional MUTSIN operation will be necessary.
The MUTSIN operation required that a table of input parameters be added to the uci file:
MUTSIN
MUTSINFO
# - # MFL NPT
1 91 0
END MUTSINFO
END MUTSIN
NMN NLI MISS ***
913
where:
• MFL is the file unit number for the PLTGEN/MUTSIN file, which is given in the FILES
block.
• NPT is the number of point-valued time series (zero in this cases)
• NMN is the number of mean-valued time series (in this case, the number of constituents
including flow, up to ten).
• NLI is the number of header lines in the PLTGEN/MUTSIN file (at least one)
• MISS is a flag which tells what to do for values missing from the file. (See HSPF manual, p.
641, for meaning of possible values.)
The data read in by the MUTSIN operation is passed to the RCHRES by new lines in the
NETWORK block:
MUTSIN 1 OUTPUT MEAN 1
MUTSIN 1 OUTPUT MEAN 1
MUTSIN 1 OUTPUT MEAN 1
MUTSIN 1 OUTPUT MEAN 2
0.05
0.70
0.25
RCHRES 1 INFLOW ISED 1
RCHRES 1 INFLOW ISED 2
RCHRES 1 INFLOW ISED 3
RCHRES 1 INFLOW IHEAT
where:
• OUTPUT MEAN 1 and 2 are the first two columns of time series data stored in the
PLTGEN/MUTSIN file
Page 4 of 10
-------
An alternative approach may be to assume a constant concentration for a constituent. In this
case, a multiplier for the flow time series can be used, with the result passed to the appropriate
target. For instance, if a constant dissolved oxygen concentration of 10 mg/1 is desired, then the
input line would read:
WDM# ### FLOW ENGL 27.182 DIV RCHRES 1 INFLOW OXIF 1
where:
• where WDM dataset for flow is in acre-feet
$ 27.182 is the multiplier for 10 mg/1 times conversion factor of 2.7182 (mg/1 to tons/ac-ft)
$ OXIF(l) refers to the model parameter for inflow of dissolved oxygen
Page 5 of 10
-------
CONNECTING AN UPSTREAM REACH
While NPSM automatically performs all inter-watershed data transfers when two or more
adjacent watersheds are selected, a user may wish to shorten overall model run time by
simulating each watershed separately. This is especially useful in extremely large watersheds, or
watersheds with a large number of subwatersheds. This section describes the mechanics of
completing an inter-watershed data transfer (i.e. how to output flow and/or constituent mass
loading time series from an upper watershed, and how to import it to a downstream watershed)
outside of NPSM.
If the upstream source is another basin which is being modeled by NSPM, then the additions to
the downstream uci file are almost exactly the same as if the upstream reach was being treated as
a point source, as described above. That is, the loadings from upstream are stored in either a
WDM file or in a PLTGEN/MUTSIN file, and added to the downstream RCHRES in the EXT
SOURCES or NETWORK block, respectively. The only difference is that this transfer data
must be stored at the same time interval as the HSPF run (usually hourly for water quality runs,
always for NPSM). The advantages for each method are similar, except that the WDM file now
also preserves greater accuracy, since the numbers are stored in binary format.
In the upstream uci, the transfer data must be stored in the place where the downstream one can
read it. If the WDM file is to be used, then all of the DSNs must be created using WDMUtil.
The procedure is the same as before, except that the step of importing the actual numbers can be
skipped, since they will be provided by the run. If the PLTGEN/MUTSIN file is to be used,
then an extra PLTGEN operation is added at the end of the OPN SEQUENCE block to write the
transfer data. If more than ten constituents are being transferred, then an additional PLTGEN
operation is required.
The input parameters in the PLTGEN block can be modeled after the PLTGENs placed in the
uci by the Output Manager in NPSM. The major difference is that the output is not accumulated
to longer time steps.
Page 6 of 10
-------
Transfer Example
The following example demonstrates how the PLTGEN and MUTSIN operations are used to
link an upstream basin to another one downstream. The study area in Mississippi combines the
draininge areas of two creeks. The upstream Sowashee Creek flows downstream into Okatibbee
Creek. Each creek has a separate uci file, originally generated by the NPSM interface. The only
instream water quality constituent being modeled is fecal coliform, using the GQUAL portion of
RCHRES.
The Sowashee uci file instructs HSPF to write a PLTGEN file. The necessary steps are:
• Open the transfer file for output.
• Pass the timeseries for each constituent from the lowest RCHRES to the PLTGEN operation.
• Define and write the transfer file.
First, the transfer file SOWASHPT.002 is opened by declaring it in the FILES block:
FILES
***
[ . . . ]
32 C:\BASINS\MODELS\NPSM\sowashpt.002
END FILES
Next, the flow and coliform outflow timeseries are passed to the PLTGEN operation via the
NETWORK block:
NETWORK
<-Volume-> <-Grp> <-Member-><--Mult-->Tran <-Target vols> <-Grp> <-Member-> ***
RCHRES
COPY
RCHRES
COPY
#
5
1
5
1
ROFLOW
OUTPUT
GQUAL
OUTPUT
ROVOL
MEAN
RODQAL
MEAN
#
1
1
2
#<-
1.
1.
f actor->strg
OOOE+000
1.0
OOOE+000
1.0
COPY
PLTGEN
COPY
PLTGEN
#
1
1
1
1
#
INPUT
INPUT
INPUT
INPUT
MEAN
MEAN
MEAN
MEAN
# #
1
1
2
2
***
END NETWORK
The COPY operation, automatically generated by BASINS, is not strictly necessary, since it
simply passes along the data unchanged to the PLTGEN. The pairs of NETWORK lines shown
above could be consolidated into single lines:
RCHRES 5 ROFLOW ROVOL 1.OOOE+000 PLTGEN 1 INPUT MEAN 1
RCHRES 5 GQUAL RODQAL 1 1.OOOE+000 PLTGEN 1 INPUT MEAN 2
Page 7 of 10
-------
Then the PLTGEN block describes how the data are written to the transfer file:
PLTGEN
PLOTINFO
# - # FILE NPT NMN LABL PYR PIVL ***
1 30 0 2 1
END PLOTINFO
GEN-LABELS
# - #< Title > *** < Y axis
1 SOWASHEE CREEK ft3/s concu/1
END GEN-LABELS
SCALING
# - # YMIN YMAX IVLIN ***
11 0. 1000. 20.
END SCALING
CURV-DATA (First curve)
<-Curve label--> Line Intg Col Tran ***
# - # type eqv code code ***
1 ROVOL (FLOW) 5 1 SAME
END CURV-DATA
CURV-DATA (Second curve)
<-Curve label--> Line Intg Col Tran ***
# - # type eqv code code ***
1 RODQAL (FECAL CO 51 SAME
END CURV-DATA
END PLTGEN
For transfers, the print interval PIVL is set to 1, meaning that the results are written every
interval of the hourly run, rather than the daily average generated by BASINS for calibration and
analysis. The parameter NMN=2 means that two constituents (including flow) are to be
transferred. (Mass-transfer timeseries are always mean-valued rather than point-valued.) The
CURV-DATA table is repeated once for each, giving a label and a transformation code (ignored
in this case) describing how the timeseries would be aggregated if necessary.
Page 8 of 10
-------
The beginning of the resulting PLTGEN file SOWASHPT.002 is shown below. For each
interval, PLTGEN writes a line containing the date and time, followed by the value of each time
series on that interval. The label for each column from the CURV-DATA table appear in the 25-
line header.
0317 HSPF FILE FOR DRIVING SEPARATE PLOT PROGRAM
0317 Time interval: 60 mins Last month in printout year: 9
0317 No. of curves plotted: Point-valued: 0 Mean-valued: 2 Total 2
0317 Label flag: 0 Pivl: 1 Idelt: 60
0317 Plot title: 03170001002: SOWASHEE CR
0317 Y-axis label: ft3/s qty/ivld
0317 Scale info: Ymin: 0.00000 Threshold:-0.10000E+31
0317 Ymax: 1000.0
0317 Time: 20.000 intervals/inch
0317 Data for each curve (Point-valued first, then mean-valued):
0317 Label LINTYP INTEQ COLCOD TRAN TRANCOD
0317 ROVOL (FLOW) 051 AVER 2
0317 RODQAL (FECAL CO 051 AVER 2
0317
0317
0317
0317
0317
0317
0317
0317
0317 Time series (pt-valued, then mean-valued):
0317
0317 Date/time Values
0317
0317 1984 12 31 24 0 -0.10000E+31 -0.10000E+31
0317 1985 1110 0.22265 7973.7
0317 1985 1120 1.1811 0.45442E+08
Page 9 of 10
-------
The second half of the transfer is to declare the incoming time series as inputs to the receiving
reach in the downstream Okatibbee uci. Here, the steps are:
• Open the transfer file SOWASHPT.002 created above.
• Declare and read the data in the MUTSIN operation.
• Pass the data to the correct RCHRES.
First, the FILES block entry is exactly the same as before:
FILES
***
[ . . . ]
32 C:\BASINS\MODELS\NPSM\sowashpt.002
END FILES
Next, the MUTSIN block describes the incoming data:
MUTSIN
MUTSINFO
<-range> ***
# - # MFL NPT NMN NLI MSFG ***
2 32 0 2 25 3
END MUTSINFO
END MUTSIN
Again, NMN is set to two to tell MUTSIN how many constituents to receive. NLI says how
many header lines to skip before the first line of data.
Finally, the NETWORK block passes these time series to the receiving RCHRES:
NETWORK
<-Volume-> <-Grp> <-Member-><--Mult->Tran <-Target vols> <-Grp> <-Member-> ***
# # #<-factor->strg # # # # **'
MUTSIN 2 OUTPUT MEAN 1 1.0000 RCHRES 1 INFLOW IVOL 1
MUTSIN 2 OUTPUT MEAN 2 1.0000 RCHRES 1 INFLOW IDQAL 1
[ . . . ]
END NETWORK
This combination of changes to the upstream and downstream uci files will link the masses of
flow and water quality constituents as if the contributing and receiving reaches were in the same
uci.
Page 10 of 10
------- |