PrmsOms Model Components

A detailed description of the computational methods and equations used in PRMS were provided in Leavesley et al. (1983), Leavesley and Stannard (1995), Leavesley et. al. (2006), and Markstrom et. al. (2008). Material from these publications has been combined and rewritten to create detailed documentation for each PrmsOms model configuration. Individual component documentation includes the listing and definition of all parameters and variables used in the component, the equations used in the computational algorithms, and a text description of the component process and function.

The porting of all PRMS MMS components to PrmsOms is a work in progress. The components that have been ported to date are listed below. The source code for each component can be view by clicking on the component name. This list and the associated documentation will be updated as additional PRMS MMS components are added.

Model Process Components

Basin Definition

• Basin.java

• Obs.java

• Temp1sta.java
• XyzDist.java

Precipitation Distribution

• Precip.java
• XyzDist.java

• Soltab.java

• Ccsolrad.java
• Ddsolrad.java

• PotetHamon.java
• PotetHamonHru.java
• PotetJh.java
• TranspTindex.java

• Intcp.java

• Snowcomp.java

• SrunoffSmidx.java

• Smbal.java
• Soilzone.java

• Ssflow.java

• Gwflow.java

• Strmflow.java

• BasinSum.java

The availability of alternative process conceptualizations for selected process components results in the ability to create several variations of a model that one could call PRMS. The selection of specific components for a given model can be made at the time the model is built. Model building is an option for users who want to create a model of their own choosing. Model building is covered in detail in another section of this tutorial.

A second option is to use previously developed versions of PRMS and thus avoid the model building process. Precompiled versions of PrmsOms are contained in the PrmsOms.jar file that can be downloaded in Download section of PrmsOms wiki page. A description and information unique to each model are provided in the Detailed Description and Execution of PrmsOms Model Configurations section.

Model .sim Files

Exectution of a PrmsOms model in the OMS3 Console requires the use of a .sim file. A .sim file is a script that identifies the specific model to be executed, the data and parameter file locations, user selected output variables, selected statistical measures of model performance to be computed, and selected output analyses to be displayed graphically. Detailed information about creating a .sim file can be found in the OMS3 User Documentation LINK HERE.

The efc.sim file provided in the PrmsOms download will be used to highlight the key elements of the .sim file for PrmsOms model execution.

The first element of the .sim file is the sim name, sim(name:"Efcarson"). The name will typically relate to the basin being modeled.

The next element in the file defines the location of the workspace directory. This directory gets set to the Working Directory that has been defined in the OMS3 Console.

  // workspace directory
    def work = System.getProperty("oms3.work");

The next element defines the output strategy and the directory where model output will be written. In this example the $work is the path to the work directory defined in the workspace element above and the output directory is one of the four subdirectories in the PrmsOmsWork directory. Output from each model run will be written to a subdirectory in the output directory that is created and named using the .sim name, in this case Efcarson. The scheme NUMBERED will result in the generation of an output directory under the Efcarson directory with the name 0000 for the first model execution. Each new model execution will create another directory under the Efcarson directory with a numeric name that is the previous run name incremented by 1.

    // define output strategy: output base dir and
    // the scheme NUMBERED|SIMPLE|DATE
    outputstrategy(dir:"$work/output", scheme:NUMBERED)

The next element is the define models element of the .sim. This is the element where the specific PrmsOms model and associated input and output files are defined. The model name for this application is PrmsDdJh. More detail on this specific model configuration can be found in the PrmsDdJh section of the tutorial. After the model name, the parameter file name and path, and a lists four individual model parameters and their values are provided. The parameter file path is defined using the work directory as the starting point. The parameters provided from the are inputFile which is the path and name of the input data file, sumFile which is the name of the file where model summary output will be written, and the startTime and the endTime of the model run.

    // define models
    model(classname:"model.PrmsDdJh") {
        // parameter
        parameter (file:"$work/data/efcarson/efc_params.csv") {
            inputFile  "$work/data/efcarson/efc_data.csv"
            sumFile    "basinsum.csv"

            startTime "1980-10-01"
            endTime   "1986-09-30"
        }

The next element is the model efficiency element which enables the user to select a variety of efficiency measures for evaluating model performance. A detailed description of available efficiency measures can be found at LINK HERE. In this example, the efficiency measures selected are the Nash-Sutcliffe Coefficient of Efficiency (NS), the sum of the absolute difference between simulated and observed values (ABSDIF), and the Transformed Root Mean Square Error (TRMSE). The observed variable (obs) is the measured daily streamflow at gauging station [0] (runoff[0]) and the simulated variable (sim) is the simulated daily streamflow (basin_cfs) at the same gauging point. The efficiencies will be written to an output file named sum.txt.

//model efficiency (optional)
        efficiency(obs:"runoff[0]", sim:"basin_cfs", methods:NS+ABSDIF+TRMSE, file:"sum.txt")

The next element provides the user with the ability to create summaries of selected model variables at a range of time scales.

// compute some summary for runoff 'on-the-fly' (optional)
       summary(time:"date", var:"basin_cfs", moments:MEAN+MIN, period:MONTHLY, file:"sum.txt")
       summary(time:"date", var:"basin_gwflow_cfs", moments:MEAN+MIN+MAX+LAG1, period:YEARLY, file:"sum.txt")

       output(time:"date", vars:"runoff[0],basin_cfs,basin_sroff_cfs,basin_ssflow_cfs,basin_gwflow_cfs,
                  basin_potet,basin_actet,", fformat:"9.6f", file:"out1.csv")

The first summary will generate a table of monthly values for the mean and minimum value of the variable basin_cfs and write this summary in the output file sum.txt. A sample of the resulting table is shown below.

Summary for 'basin_cfs' (monthly)
               date            mean           min
1980-10-01 12:00:00       116.45305     116.45305
1980-11-01 12:00:00        95.72138      78.35633
1980-12-01 12:00:00        64.82390      53.58372
1981-01-01 12:00:00        66.23311      47.77496
1981-02-01 12:00:00        53.30244      45.36838
1981-03-01 12:00:00       131.33003      38.77442

The second summary will generate a table of annual values for the mean, minimum, maximum, and lag1 of the variable basin_gwflow_cfs and write this summary to the output file sum.txt. The resulting table is shown below.

Summary for 'basin_gwflow_cfs' (yearly)
               date            mean           min           max          lag1
1981-01-01 12:00:00        71.01550      47.34615     116.45305       0.96918
1982-01-01 12:00:00       117.29010      38.15250     267.93800       0.99460
1983-01-01 12:00:00       295.23018     136.97900     561.82740       0.99756
1984-01-01 12:00:00       332.90327     156.49540     583.68007       0.99632
1985-01-01 12:00:00       236.81722      69.29116     429.59492       0.99625
1986-01-01 12:00:00       131.83366      32.18235     342.19805       0.99764

The third summary output is a table of daily values for user selected model variables. This table could be used in an external analysis program but it is also used for the graphical analysis element of the .sim file. The user can specify the output format (fformat) and an output file name.

The last element of the .sim file is the graphical analysis element. A variety of graphical options are available for displaying and analyzing model variables. The example below creates and Graphical window with the title EFCarson Analysis and a set of window tabs that will display the speicified individual timeseries plots. A detail description of available plot types and formats is available at LINK HERE.

analysis(title:"EFCarson Analysis") {


        timeseries(title:"Efc_Q", view: COMBINED ) {
            x(file:"%last/out1.csv", column:"date")
            y(file:"%last/out1.csv", column:"runoff[0]")
            y(file:"%last/out1.csv", column:"basin_cfs")
        } 
        
        timeseries(title:"Sim_Error", view: STACKED) {
            x(file:"%last/out1.csv",  column:"date")
            calc(eq:"sim - obs") {
                sim(file:"%last/out1.csv", column:"basin_cfs")
                obs(file:"%last/out1.csv", column:"runoff[0]")
            }
        calc(eq:"sim - obs", acc:true) {
                sim(file:"%last/out1.csv", column:"basin_cfs")
                obs(file:"%last/out1.csv", column:"runoff[0]")
            }
        } 

The example above is a subset of the full analysis element in the efc.sim. Note that all references to model variables are to the output table out1.csv that was generated in the summary element of efc.sim. The %last part of the path to out1.csv references the output directory from the last execution of the efc.sim. The first timeseries graph will plot the measured (runoff[0]) and simulated (basin_cfs) values of streamflow. The second timeseries graph will be composed of two graphs, one stacked above the other. The top graph will plot the daily difference between simulated and observed streamflow. The lower graph will be a plot of the accumulated daily difference between simulated and observed streamflow.

Parameter Files

The form of the OMS3 model parameter file is shown below:

@S, Parameter
 created at, "Thu Jun 25 13:44:42 MDT 2009"
 created by, george
 adjusted by, olaf

@P, adjmix_rain,   "{0.5, 0.6000000238419, 0.6999999880791, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 0.5}"
 bound,nmonths

@P, carea_max,     "{0.2000000029802, 0.2000000029802, 0.2000000029802, 0.2000000029802, 0.2000000029802, 0.2000000029802, 0.2000000029802, 0.2000000029802, 0.0, 0.0, 0.2000000029802, 0.2000000029802, 0.2000000029802, 0.2000000029802, 0.2000000029802, 0.2000000029802, 0.2000000029802, 0.0, 0.0, 0.0, 0.0, 0.2000000029802, 0.2000000029802}"
bound,nhru

@P, nhru,          "23"
 role, dimension

@P, snarea_curve,  "{{0.05000000074506, 0.2399999946356, 0.4000000059605, 0.5299999713898, 0.6499999761581, 0.75, 0.8199999928474, 0.8799999952316, 0.9300000071526, 0.9900000095367, 1.0 }}"
bound, "ndepl, ndeplval"

The @S section provides information on when the file was created and by whom.

Each individual parameter begins with @P followed by the parameter name and then the parameter values. Parameters that specify model dimensions, such as number of hydrologic response units (nhru) have their value specified inside “ “. The value is then followed by role, dimension which identifies this parameter as a dimension.

Parameters that are arrays of values have their values listed inside “{ }” and these are followed by bound, <dimension> where <dimension> is a dimension provided within the parameter file. Parameter adjmix_rain is bound by the dimension nmonths which is the number of months in a year. Parameter carea_max is bound by the dimension nhru. The parameter snarea_curve is a 2-dimensional parameter and is bound by the dimensions ndepl which is the number of depletion curves, and ndeplval which is the number of values used to define a depletion curve. In this example there is only one depletion curve (ndepl) and it has 11 values defining the curve (ndeplval). If ndepl was greater than one, there would be a set of 11 values inside a set of { } for each additional curve.

The file format above is how the parameter file is stored. However, this format can be cumbersome to use for parameter entry or editing. To more easily work with a parameter file, a parameter editing tool is provided in the OMS3 Console. Clicking on the calculator icon in the Console will start the parameter editor and loads the parameter file specified in the .sim file.

The parameter file loads into the editor with the same format as that shown above. Clicking on the Filter pull down menu in the Editor provides the ability to view and edit parameters in subsets specified by their dimension. SCALAR parameters are those that have only a single value.

Selecting the nhru dimension provides a spreadsheet view of all the parameters that are dimensioned by nhru. The parameter name is given at the top of each column. The array element number is provided on the left side.

Note that the the numbering sequence is 0 to n-1 where n is the dimension size of the array nhru, in this case 23. This may cause some confusion because historically the PRMS parameter files identify array elements using a “1 to n” numbering convention The user should continue to use the “1 to n” numbering convention for all parameters that relate various spatial and temporal variables within the model. For example, the parameter hru_psta identifies the precipitation station to be associated with an hru. The Efcarson example has five precipitation stations. Note that in the hru_psta column of the editor, the values range from 1 to 5. PrmsOms has been coded to handle the array element conversion from “1 to n” to “0 to n-1” within the model.

The window area above the spreadsheet is the area where a wide range of functions can be entered to added parameters and dimensions, convert existing MMS format parameter, data, and statvar files to OMS3 consistent files, and to modify and save parameter values in the currently displayed file. Typing help in this window provides a list of all the available functions.

Basic editing functions typically involve modifying parameter values by directly replacing them with a new value or modifying the current value through the processes of addition, subtraction, multiplication, or division. Parameters to be modified can be the entire array or a subset of parameter values. To select the entire array, click on the column heading name. To select a subset of parameter values, click on the first value in the set with the left mouse button, and holding the button down, drag the cursor over the values to be selected. A detailed description of editor functions and examples are provided at LINK HERE.

Data Files

The input data file is a comma separated value (.csv) file that can be created using your favorite editor, an Xcel spreadsheet, or can be converted from a previous PRMS MMS data file. A few lines of the efc_data.csv file used in this example are

@T,obs
 Created,5/29/2008
 Author,george
 ConvertedFrom,efcarson.data
 dataStart,"1980 10 1 0 0 0"
 dataEnd,"1986 9 30 0 0 0"
 dateFormat,"yyyy M d H m s"

@H,date,runoff[0],precip[0],precip[1],precip[2],precip[3],precip[4],tmin[0],tmin[1],tmax[0],tmax[1]
name,,E FK CARSON,WOODFORDS,BLUE LAKES,EBBETTS PASS,POISON FLAT, ..... ID,,10308200,49775,19I05s,19I19s,19I06s,19I07s,49105,49775,49105,49775
elevation,,5400,5650,8000,8765,7900,8800,8000,5650,8000,5650
x,,-119.7648985,-119.8,-119.924431,-119.804649,-119.626122,-119.599419,-120.04028,-119.8, .......
y,,38.7146274,38.783329,38.6078,38.54955,38.50553,38.3103,38.70861,38.783329,38.70861,38.783329
Type,Date,Real,Real,Real,Real,Real,Real,Real,Real,Real,Real
 Format,yyyy M d H m s,,,,,,,,,,
,1980 10 1 0 0 0,84,0,0,0,0,0,44,51,78,86
,1980 10 2 0 0 0,82,0,0,0,1.5,0,51,48,78,84
,1980 10 3 0 0 0,80,0,0,0,0,0,44,52,77,86

The first seven lines provide general information about the data file. The @T,obs provides the name of the data Table as obs. Use of this name is important because the model is looking for that name to identify the input data table. The start date and end date must be consistent with the first and last data elements in the table. If additional data are appended to the file, the end date must changed.

The second part of the header provides specific information about each column variable. The first element provides the variable name used by the model for each data column and the array identifier if there are more than one station providing a measure of the variable. In this example there are one streamflow station (runoff), five precipitation stations (precip), two minimum temperature stations (tmin), and two maximum temperature stations (tmax).

Note that the array element numbering convention starts with the first element having the id of 0. This is consistent with Java notation. For precip, the five stations are numbered from 0-4. This may cause some confusion because historically the PRMS parameter files identify the precip stations ranging from 1-5. The user should continue to use the “1 to n” numbering convention in a parameter file for all parameters that relate various spatial and temporal variables within the model. For example, the parameter hru_psta identifies the precipitation station id to be associated with an hru. The hru_psta values will range from 1 to 5 in the parameter file. PrmsOms has been coded to handle the array element conversion from “1 to n” to “0 to n-1” within the model.

The next five lines in the header are the name and ID used to identify each station, and the elevation (elev), latitude(y), and longitude(x) of each station. These are followed by a decription of the variable type and the Format of the data. Note that the Date field is a single field that is composed of year, month, day, hour, minute, and second values. Each data line in the file contains the date followed by the values for all variables defined in the header.

Model Output

In the define models element of a PrmsOms .sim file, a sumFile name is provided to name the summary output file that is written by the BasinSum.java component of PrmsOms. The two PrmsOms parameters that control the content of the model summary output are print_type and print_freq. Print_type specifies the type of output written to the sumFile (0=measured and predicted flow only; 1=water balance table; 2=detailed output). Print_freq specifies the frequency of output written to sumFile (0=none; 1=simulation totals; 2=yearly; 4=monthly; 8=daily; or additive combinations—for example, use 3 for output of yearly and simulation totals). In the parameter file used in this example the parameter print_type was set to 1 which selects a simple water balance and the parameter print_freq was set to 3 which selects annual and total run summaries for the water balance. This summary output is written to the file basinsum.csv. The content of basinsum.csv is shown below.