United States Office of Water EPA-823-R-99-005

Environmental Protection 4305 June 1999

Agency

BASINS Technical Note 4

Incorporating Upstream Flow and

Water Quality Time Series in the

Nonpoint Source Model (NPSM)
Page 1 of 10

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/<project> 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 Watershed 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 2 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 .uci file 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/<project>

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\XNPSM11x.exe c:\Basins\modelout\<your_dir>\<your_prj>.uci

where <your_dir> and <your_prj> 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 3 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(1-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 4 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 NMN NLI MISS ***

 1 91 0 9 1 3

 END MUTSINFO

END MUTSIN

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 0.05 RCHRES 1 INFLOW ISED 1

MUTSIN 1 OUTPUT MEAN 1 0.70 RCHRES 1 INFLOW ISED 2

MUTSIN 1 OUTPUT MEAN 1 0.25 RCHRES 1 INFLOW ISED 3

MUTSIN 1 OUTPUT MEAN 2 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 5 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/l 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/l times conversion factor of 2.7182 (mg/l to tons/ac-ft)

$ OXIF(1) refers to the model parameter for inflow of dissolved oxygen
Page 6 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 7 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

<type> <un#> <file name>***

 [ . . . ]

 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-> ***

<Name> # <Name> # #<-factor->strg <Name> # # <Name> # # ***

RCHRES 5 ROFLOW ROVOL 1.000E+000 COPY 1 INPUT MEAN 1

COPY 1 OUTPUT MEAN 1 1.0 PLTGEN 1 INPUT MEAN 1

RCHRES 5 GQUAL RODQAL 1 1.000E+000 COPY 1 INPUT MEAN 2

COPY 1 OUTPUT MEAN 2 1.0 PLTGEN 1 INPUT MEAN 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.000E+000 PLTGEN 1 INPUT MEAN 1

RCHRES 5 GQUAL RODQAL 1 1.000E+000 PLTGEN 1 INPUT MEAN 2
Page 8 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/l 

 END GEN-LABELS

 SCALING

 # - # YMIN YMAX IVLIN ***

 1 1 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 5 1 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 9 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) 0 5 1 AVER 2

0317 RODQAL (FECAL CO 0 5 1 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 1 1 1 0 0.22265 7973.7 

0317 1985 1 1 2 0 1.1811 0.45442E+08

 [ . . . ]
Page 10 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

<type> <un#> <file name>***

 [ . . . ]

 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-> ***

<Name> # <Name> # #<-factor->strg <Name> # # <Name> # # ***

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.