OMS-PRMS

What is OMS-PRMS?

Precipitation Runoff Modeling System (PRMS) is a deterministic, distributed-parameter, physical process based modeling system developed to evaluate the response of various combinations of climate and land use on streamflow and general watershed hydrology. The OMS-PRMS is a customized version of the USGS PRMS and is intended for water forecasting use at USDA-NRCS NWCC. Please use the links below to learn more about USGS PRMS and OMS-PRMS.

• • USGS PRMS: http://wwwbrr.cr.usgs.gov/projects/SW_MoWS/software/oui_and_mms_s/prms.shtml

  • PRMS/OMS - used at NWCC. See http://www.javaforge.com/wiki/77666 for more information.

For general information about the use of PRMS, please see USGS Watershed modeling training site.

How to install OMS-PRMS

OMS-PRMS is an open source hydrological modeling tool that users can download from the OMS page. It runs on Windows-based computers that have java runtime environment (JRE) installed. JRE is available freely from the Oracle web site. Please follow the simple steps below to install the OMS-PRMS program. A set of sample data is also installed with the program.

• 1. Go to the OMS-PRMS download page: http://www.javaforge.com/dir/518130 and click on the zipped package file (e.g., nwcc2013-20130909.zip). The browser automatically saves the zip file to the local computer.

  2. Move the zip file to the intended target folder and unzip the file.

  3. The decompressed files are located in the nwcc2013 subfolder under the target folder. Under the nwcc2013 folder, there are 3 subfolders (dist, docs, and simulation) and some shell scripting files (.bat and .sh). The dist folder contains the OMS-PRMS java code libraries (.jar); the docs folder contains the supplemental documents related to OMS-PRMS; the simulation folder contains the parameter files of several example AOIs that users can use to perform PRMS modeling.

  4. Once the files are decompressed, the installation process is completed.

How to use OMS-PRMS

• Open a Windows command line window and change to the folder containing the wsf.bat file. For example, if the target folder of OMS-PRMS is E:\PRMS, then the following commands set the current directory to the folder that contains the wsf.bat file (see screenshot image).

E:

cd \PRMS\nwcc2013

• Key in the following statement on the command prompt to open the OMS console.

wsf.bat --omsconsole

• • The first time you run OMS-PRMS most of the buttons may be disabled. You need to open a project first. Use the 'Open Project' button to the left of the Project dropdown list. Select the nwcc2013 folder as the project to open. Note that OMS-PRMS caches configuration files in your temporary directory in an .oms folder. To restore to system default, delete this folder.

  • Use the Open Simulation button (circled in red on the image below) to open a simulation file (.sim). Some example simulation files can be found in the example AOI folders. The simulation files, stored as ASCII files, define the simulation settings such as input parameter files, output files, and other parameters. Users can modify a simulation file based on their need. Once a simulation file is loaded, users can use the Run button (circled in blue) to execute a simulation.

OMS-PRMS Parameter File Syntax

BAGIS-P's export function generates OMS parameter files that can be used in PRMS. A shapefile of the HRU geometry is not required for running OMS-PRMS. This page provides information on the OMS parameter files generated by BAGIS-P. For a complete description of the OMS parameter file format, see OMS page.

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

@S,Parameter

Descr,"East Fork Carson River, CA"

modifed_at,Wed Aug 29 17:41:47 MDT 2012

Version,Version: 1.7

CreatedAt,Tue Aug 21 16:02:12 MDT 2012

• • @P - one scalar value. Individual parameter followed by the parameter name and then the parameter value.

@P,albset_rna,0.8000000119209

• • @P with Role and Dimension - Parameters that specify model dimensions using a name and a value, such as number of hydrologic response units (nhru) or number of months a year. The value is then followed by "role", "dimension" which identifies this parameter as a dimension. Note that the role modifier is only for descriptive purposes. A parameter file may have dimensions that aren't indicated as such in the parameter definition and there may be dimensions that aren't used in tables.

@P,nmonths,12

role,dimension

• @P - array. 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.

@P, adjmix_rain, "{0.5, 0.6, 0.67, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 0.5}"

bound,nmonths

• • @P - 2-D array. Parameters that are arranged as 2-D arrays of values have their values listed inside sets of "{ }" and these are followed by "bound", <dimension1>, and <dimension2>. For example, 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.

@P, snarea_curve, "{{0.05, 0.24, 0.4, 0.53, 0.65, 0.75, 0.82, 0.88, 0.93, 0.99, 1.0 }}"

bound, "ndepl, ndeplval"

• • @H - table header. Data file headers that define the column headers of a data file (i.e., table) and appear immediately after @T. The tag is followed by a list of parameter names. The number of names defines the number of columns in the data file.

See the @T tag below or an example.

• • @T - data file. Following the @T is the length, len, of the dimension size. This is followed by a header @H which contains the name of the parameter in each column. These are the most current definitions of Table syntax. The table syntax has been under development so older parameter files may use slightly different syntax. But this is the syntax that will be produced by BAGIS-P.

@T,nmonths

len,12

@H,dday_intcp,dday_slope,adjmix_rain,epan_coef,jh_coef,ppt_rad_adj,tmax_allrain,tmax_index,tmax_lapse,rain_code,tstorm_mo,cecn_coef,tmin_lapse

,-10,0.4,0.5,1,0.014,0.02,60,50,3.2,0,0,5,3.2

,-10,0.4,0.6,1,0.014,0.02,60,50,4.2,0,0,5,4.2

,-10,0.4,0.7,1,0.014,0.02,60,50,4.9,0,0,5,4.9

,-10,0.4,1,1,0.014,0.02,50,50,5.3,0,0,5,5.3

,-10,0.4,1,1,0.014,0.02,50,50,5.7,0,1,5,5.7

,-10,0.4,1,1,0.014,0.02,50,50,5.8,0,1,5,5.8

,-10,0.4,1,1,0.014,0.02,40,50,6.3,0,1,5,6.3

,-10,0.4,1,1,0.014,0.02,40,50,4,0,1,5,4

,-10,0.4,1,1,0.014,0.02,40,50,4.9,0,1,5,4.9

,-10,0.4,1,1,0.014,0.02,50,50,4.2,0,1,5,4.2

,-10,0.4,1,1,0.014,0.02,60,50,3.3,0,0,5,3.3

,-10,0.4,0.5,1,0.014,0.02,60,50,3,0,0,5,3

• • For 2-D parameters, the table identifier @T is followed by the parameter name and the next line shows the bounds of each dimension of the parameter. The order is row, column. The example below represents the snarea_curve parameters that are dimensioned by ndepl and ndeplval. The header @H lists the deplval values.

@T,snarea_curve

bound,"ndepl,ndeplval"

size,"1,11"

@H,0,1,2,3,4,5,6,7,8,9,10

,0.05, 0.24, 0.4, 0.53, 0.65, 0.75, 0.82, 0.88, 0.93, 0.99, 1.0

• • Note: If a parameter file is edited in Excel, extra commas may be appended to the end of the lines. These commas should be ignored by the OMS parser and will not be present in the parameter file export from BAGIS-P.

@P,albset_rna,0.8,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,

BAGIS-P Generated OMS-PRMS Parameter Files

BAGIS-P's export function generates files that support eWSF. To use the parameters generated by BAGIS-P, eWSF uploads a zip file containing 4 data items: 1) a parameter file saved in OMS-PRMS parameter file format, 2) the HRU zones that was used to generate the parameters in ESRI shapefile format, 3) a (resampled) raster HRU zones map stored as an ASCII text file (in ESRI GRID2ASCII output format), and 4) a (resampled) raster DEM stored as an ASCII text file (same format as item 3). The naming convention for these files are:

[filename_prefix].csv - parameter file in OMS parameter file format

[filename_prefix].shp - vector HRU zones in ESRI shapefile format (to include also .shx, .sbn, .sbx, .dbf, .prj)

[filename_prefix]_dem.asc - (resampled) filled DEM in ArcInfo GRID to ASCII output format

[filename_prefix]_hru.asc - (resampled) raster HRU zones in ArcInfo GRID to ASCII output format

All these files are compressed in a zip file (i.e., [filename_prefix].zip).

To create the OMS-PRMS output parameter files, BAGIS-P's export function uses an input parameter file template to produce three output parameter files. They are for storing non-spatial parameters, spatial parameters that have a dimension of "nhru" (i.e., the number of HRUs in an AOI) that were calculated by BAGIS-P, and spatial parameters that have a dimension of nhru but were not calculated by BAGIS-P. The file naming conventions used in this document for referring to these files are: for non-spatial parameters, params_ns; for BAGIS-P calculated spatial parameters, params_bagis; for none-BAGIS-P spatial parameters, params_nhru.

During the export process, BAGIS-P retrieves params_ns from the input template file and saves the data to an output CSV file (e.g., aoi_params_ns.csv). Then, BAGIS-P retrieves the spatial parameters' values stored in the AOI's File Geodatabase and saves them to a second output CSV file (e.g., aoi_params_bagis.csv). Finally, BAGIS-P uses a set of pre-determined values to create the none-BAGIS spatial parameter file (e.g., aoi_param_nhru.csv). Users must review the parameter values in both aoi_params_ns.csv and aoi_params_nhru.csv before using them in OMS-PRMS. The aoi_params_bagis.csv file should not be modified by users. The formats and usage of these files are described below.

BAGIS-P Export Parameter File Format

• aoi_params_ns.csv: the file format is identical to the input parameter template file, which must comply with OMS-PRMS parameter file specifications. The input template file must contain all required none-spatial parameter values for OMS-PRMS execution and may not contain any spatial parameter values. If the input template file contains spatial parameters values, then they will be removed by BAGIS-P from the exported aoi_params_ns.csv file. Users must review and verify the parameters values in this file before using it in OMS-PRMS.

• aoi_params_bagis.csv: the file contains only spatial parameters that have a dimension of nhru and whose values were calculated by BAGIS-P.

  • aoi_params_nhru.csv: the file contains only spatial parameters that have a dimension of nhru and whose values were predetermined and must be verified by the users.

Both aoi_params_bagis.csv and aoi_params_nhru.csv have the same file format representing a tabular, 2D data file. Here is an example of the file format:

@T,nhru

description,Parameter bound by nhru and generated by BAGIS-P

@H,ERAMS_ID,frozen,groundmelt,transp_tmax,wrain_intcp,hru_percent_dprst,hru_solsta,hru_type

,1,0,0,500,0.050000001,0,0,1

,2,0,0,500,0.050000001,0,0,1

,3,0,0,500,0.043463681,0,0,1

,4,0,0,500,0.050000001,0,0,1

...

The table columns included in these two parameters files must meet the following criteria for OMS-PRMS to ingest the simulation data.

• • All OMS-PRMS required parameters must be present in aoi_params_bagis.csv and aoi_params_nhru.csv combined. The order of the parameters is inconsequential.

  • It's fine to have additional parameters that are not used by OSM-PRMS. BAGIS-P stores the unique ID for HRUs in the ERAMS_ID column in both parameter files. The ERAMS_ID values are not used by OMS-PRMS.

Using BAGIS-P Exported Parameter Files in OMS-PRMS

Users must modify OMS-PRMS' .sim simulation definition file so that the BAGIS-P exported parameter files are read correctly. The modifications implement two major steps: 1) combining the spatial parameter files into one spatial parameter file and 2) read the none spatial parameter file and the combined spatial parameter file. An example of the modification is shown below.

OMS3.sim(name:"efcarson_sim",

OMS-PRMS Parameters

What are in the PRMS OMS parameter files?

• • Non-spatial Parameters

    • Initial conditions: values of the contents of model storages (state variables) at the beginning of a simulation

    • Input control parameters: these values specify units for observed data

    • Output control parameters: these values control the types and frequency of model output as well as set some options for objective functions

    • Dimensions: values that set the number of elements in arrays of model parameters or other constants

    • Scalar parameters

    • XYZ parameters

  • Spatial Parameters for AOI (i.e., have a dimension of 1)

    • AOI area and location (latitude)

  • Spatial Parameters for HRU (of nhru dimension)

    • Generated by BAGIS-P

    • Whose values are specified by the users

BAGIS-P creates three separate files to store these parameters that are required for OMS-PRMS simulation. See the "BAGIS-P Export Parameter File Format" section above for more information.

• • aoi_params_ns.csv: stores non-spatial and AOI spatial parameters

  • aoi_params_bagis.csv: stores HRU spatial parameters that are generated by BAGIS-P

  • aoi_params_nhru.csv: stores HRU spatial parameters whose values are specified by the users

The tables below summarize the parameters used in the latest version of OMS-PRMS.

Notes for the tables:

• Parameters highlighted in red are the ones that are not in the params.csv template file (i.e., not used by OMS-PRMS) but are in David's spreadsheet.

• Parameters with ??? are in the params.csv template file but there are no descriptions about them.

• Parameters highlighted in yellow are none-HRU parameters but whose values must be set by BAGIS-P.

Non-Spatial Parameters or AOI Spatial Parameters (that are not of nhru dimension)

Initial Conditions

There are 4 initial condition parameters. Two of them have a nhru dimension (soil_moist_init and soil_rechr_init) and are listed with the HRU none-BAGIS-P spatial parameter table. The gwstor_init parameter has a dimension of ngw and is listed in the ngw table. The ssstor_init is listed with the nssr table.

Input Control Parameters

Output Control Parameters

Dimensions

Scalar parameters

XYZ parameters

groundwater storage (with a dimension of ngw)

nmonths (with a dimension of nmonths)

Radiation Planes Spatial Parameters (with a dimension of nradple) (OMS-PRMS uses HRUs as the zones)

BAGIS uses HRU zones, instead of radiation planes, to calculate their values. The calculation is based on Weasel's algorithm, which involves the combinations of reclassified slope and reclassified aspect. The most commonly occurring combination of reclassified slope and reclassified aspect in each HRU zone is the output for radpl_slope and radpl_aspect. These models will be stored in the Topographic toolbox. Geoffrey to check with George to see if these can be included with the other BAGIS-P spatial parameters.If it has to be separate, check to see if radpl parameters (and other BAGISi-P params) exist in source table. They should be part of the profile. If not, add dimension each parameter nhru or nradpl.

HRU Spatial Parameters Whose Values Are Specified by The Users (with a dimension of nhru)

HRU Spatial Parameters Generated by BAGIS-P (with a dimension of nhru)