Introducing OpenMI

Jon Goodall, Duke University and Tim Whiteaker, CRWR

Table of Contents

Introduction. 1

Computer and Data Requirements. 2

About the Components. 2

DailyStreamflow Data: A WaterOneFlow component 3

Water Balance: A simple water balance model component 3

Procedure. 4

Prepare the exercise data. 4

Open the OmiEd application and add the WaterOneFlow linkable component 5

Add the Simple Water Balance Model to OmiEd. 7

Add a connection between the WaterOneFlow component and the Water Balance component 9

Add a trigger to the model 12

Run the model 14

Verify results. 16

 

Introduction

OpenMI (Open Modelling Interface and Environment) is a data and model integration framework.  The primary objective is to take otherwise independent data and computing systems, for example a database storing rainfall time series, a rainfall-runoff model, and a river hydraulics model, and provide a standard means for describing how time series are communicated between the systems.  OpenMI was developed by HarmonIT, which consists of a number European environmental software companies and university researchers.  Software companies like DHI are working to make their models “OpenMI-compliant”, thereby allowing environmental modelers the ability to couple different DHI models into modeling frameworks that may include models or data sources independent of DHI. The following links provide additional background information on OpenMI.

 

·        OpenMI official website: http://www.openmi.org/

·        OpenMI download and source code: http://sourceforge.net/projects/openmi

·        HarmonIT: http://www.harmonit.org

·        HarmonIT parteners: http://www.harmonit.org/partners/all.htm  

 

In order to be OpenMI-compliant, a model or data source must implement a set of OpenMI interfaces, which define how time series are communciated between OpenMI components.  The interfaces use a “What-Where-When” framework, which means that in order for OpenMI components to communicate data, they must specify:

 

  • What – The quantity or variable that is being exchanged, e.g. “Streamflow”
  • Where – The location where the quantity is being exchanged, e.g. “At stream junction number 23”
  • When – The time when the quantity is being exchanged, e.g. “2007-06-04T16:43:00”

 

The actual mechanics of how this takes place is beyond the scope of this document.  For the details about how to implement OpenMI interfaces, please refer to the OpenMI documentation available in the external links above.

 

The remainder of this document demonstrates how to use free OpenMI software called OmiEd, which let’s you assemble OpenMI-compliant components into a simulation package, and run the overall model.  In the exercise, you will use OmiEd to perform a water balance using WaterOneFlow web services, coupled with a simple water balance model.

Computer and Data Requirements

For this exercise you will need:

  • The .Net framework 2.0, installed.
  • OpenMI (available for download at http://sourceforge.net/projects/openmi), installed
  • Exercise data (available here)
    • OpenMI compliant water balance model
    • Database of metadata for the WaterOneFlow component
    • OpenMI omi files (a file that describes an OpenMI component) for the NWISDV component and Water Balance model component
    • Other supporting OpenMI files

About the Components

In this exercise, you will use the OmiEd application to link a water balance model with a component that obtains streamflow data from WaterOneFlow web services.  You will then execute the composition to perform the simple water balance.  In this example, the WaterOneFlow component is not actually a model, but rather a connection to a remote data source.  But the water balance model doesn’t care, as long as the WaterOneFlow component is OpenMI compliant.

DailyStreamflow Data: A WaterOneFlow component

This component returns a time series of daily streamflow, retrieved from the USGS National Water Information System (NWIS) via CUAHSI’s WaterOneFlow web service.  The time series are retrieved for USGS stream gage locations, as defined in a local database file that sits alongside this component.  The following files are associated with this component:

  • WaterOneFlow.dll – Object library that contains the OpenMI compliant DailyStreamflow Data component.  This DLL is designed to retrieve daily stream data from the WaterOneFlow web service at http://water.sdsc.edu/waterOneFlow/NWIS/DailyValues.asmx.
  • Catalog.mdb – Database defining the gages that this component can access, and the available period of record for retrieval.  The period of record defined in the database is for the year 1999.
  • NWISDV.omi – OMI file that defines the necessary parameters to add this component as a Linkable Component in OmiEd, or any other OpenMI System application.

 

The time horizon for this component is for the year 1999, as defined in Catalog.mdb.

Water Balance: A simple water balance model component

This component is a simple water balance model created by Jon Goodall at Duke University, to serve as a demonstration component for OpenMI.  The model computes a water balance for a set of watersheds.  The output of the model is a time series of storage values for watersheds.  The inputs to the model are the inflow into a watershed, and outflow from the watershed.  The storage is computed with a daily time step, with the following equation:

 

St = (It-∆t  + Ot-∆t) * ∆t + St-∆t

 

Where:

            St = storage for a given watershed at time t (m3)

            St-∆t = storage for a given watershed at time t-∆t (m3)

            It-∆t = inflow to a given watershed at time t-∆t (m3/s)

            Ot-∆t = outflow from a given watershed at time t-∆t (m3/s)

            ∆t = 86400 (the number of seconds in a day) (s)

 

Note that by convention, flows into a watershed are positive, and flows out of a watershed are negative.

 

Of course, this model performs a very simplified water balance.  A more proper water balance model would also take into account evaporation, precipitation, and groundwater fluxes.

 

The following files are associated with this component:

 

  • WaterBalanceModel.dll – Object library that contains the OpenMI compliant Water Balance component.
  • watershed.txt – Text file listing the nodes which define the shapes of watersheds in the water balance model.
  • WaterBalanceModel.omi – OMI file that defines the necessary parameters to add this component as a Linkable Component in OmiEd, or any other OpenMI System application.
  • model_parameters.txt – Text file listing the start time, time step, and number of time steps for the model.

 

 The time horizon for this model is for the year 1999, as defined in model_parameters.txt.

Procedure

For this composition, you will use the DailyStreamflow Data component to provide the inflows and outflows to a watershed in the Water Balance component.  The inflow occurs at a stream gage at the upstream end of a watershed, while the outflow occurs at the outlet of a watershed.  With inflow and outflow determined, the Water Balance component can then compute storage for a watershed.

Prepare the exercise data

Download data for the exercise here.  Unzip the OpenMI_ExFiles folder and save the folder to your computer in a location such as c:\temp\.  The location does not matter, as long as you have write access to the folder. 

 

Note that it’s best to save the files to your computer locally.  If you try to run the models from a remote location such as a server, you may encounter errors when trying to access the component which uses web services.

Open the OmiEd application and add the WaterOneFlow linkable component

OmiEd is an application used to build and run OpenMI compositions by linking together OpenMI compliant models or components. 

 

Open the OmiEd application by clicking Start | All Programs | OpenMI 1.2.0 | OmiEd.

 

 

Next you will add the WaterOneFlow model to OmiEd.

 

Click Composition | Add Model.

 

 

Browse to the NWISDV.omi file and open it (this file is in the OpenMI_ExFiles folder.)  An omi file is a text file that contains the information needed to locate a given OpenMI compliant model on disk, as well as other parameters or data files required by the model.

 

The tool appears with the name “DailyStreamflow Data”.  This OpenMI linkable component is designed to retrieve daily streamflow values from NWIS and then provide the data for a given time step when a GetValues request is made to the component.  Because this component is OpenMI compliant, OmiEd can add it to the composition.  Otherwise, OmiEd would have alerted you that this is not an OpenMI compliant component.

 

 

View the properties of the component by right clicking on the yellow rectangle and choosing Model properties….  This opens the Model properties window.  In the Output Exchange Items list, click the plus sign to expand the output exchange items, and then browse through the various items.

 

 

From this dialog we see the list of time series that can be obtained from WaterOneFlow.  These are defined as output exchange items, and include the elements at which the time series apply, which are stream gages in this case.  Also included is information about the quantity measured (daily streamflow in this case), such as units of measure for the quantity.  These time series are documented in the local database file Catalog.mdb, included in the OpenMI_ExFiles folder.  If a study required different time series from WaterOneFlow, changing this local database file to store the metadata for the additional stations will allow those additional stations to appear as Output Exchange Items within OpenMI.  

 

Close the Model properties window.

Add the Simple Water Balance Model to OmiEd

Click Composition | Add Model.

 

Browse to the WaterBalanceModel.omi file and open it (this file is in the OpenMI_ExFiles folder.)  The water balance model appears with the name “Water Balance”.

 

 

View the properties of the Water Balance model component (Right-click on component and then click Model properties…).

 

From this dialog we see that the water balance component can accept input exchange items of InFlow and OutFlow, and provides Storage as an output exchange item.  

Add a connection between the WaterOneFlow component and the Water Balance component

We will use the DailyStreamflow Data component to provide the input data to the Water Balance component.

 

Click Composition | Add Connection.

 

Left-click on the DailyStreamflow Data component and then left-click on the Water Balance component.  You should then see a blue line linking the two components with the arrow pointing from DailyStreamflow Data (the data source) to the Water Balance component.

 

 

Here we are telling OmiEd that the Water Balance component is dependent on input values from DailyStreamflow Data. 

 

Now you need to edit the properties of the connection that you just created.

 

Right-click on the connection (it’s best to click on the triangle in the middle of the connection) and then click Connection properties….  This opens the Connection properties window.

 

From the output exchange item list, choose the Trent River near Trenton, NC as the inflow for watershed 2, and click Apply.  This adds a link between an output exchange item from the DailyStreamflow Data component and an input exchange item from the Water Balance component.  Repeat the procedure to create another link for the Trent River at Pollocksville, NC as outflow for watershed 2.  We have now defined the surface water that goes in and comes out of a given watershed.  From this, the water balance model can compute the storage in the watershed.

 

 

It is also possible to see the geometries for the watershed and a gage location by highlighting one of the link items and clicking ElementSet viewer.  The vertices for the watershed are stored in a text file named watershed.txt located in the OpenMI_ExFiles folder.

 

 

In the viewer, you see the boundary of the watershed, and a red dot indicating the location of the streamflow gage at the outlet of the watershed.

 

Close the ElementSetViewer and the Connection properties dialog.

Add a trigger to the model

A trigger is used to initiate calculations and tell the model which quantities should be calculated.

 

Click Composition | Add Trigger.

 

Click Composition | Add Connection.

 

Left-click on the Water Balance component and then left-click on the Trigger component.  

 

 

Right-click on the connection from the Water Balance model to the Trigger and click Connection properties….

 

Under Output Exchange Items, click watershed 2 and under Input Exchange Items choose TriggerElementID.  Click Apply and then Close.

 

 

You’ve just told OpenMI what it should calculate.  The model will run until the trigger value (storage for watershed 2) is known.  Because the trigger is requesting to know the storage, the Water Balance component will be called.  Because the Water Balance component needs inflows and outflows, the DailyStreamflow Data component will be called.  Thus, by triggering computation of the most downstream model component, all components in the chain will be called.

Run the model

Ok, it’s almost time to run the model.  But first…SAVE THE MODEL (click File | Save.)  Give the model the name of your choosing.

 

Click Composition | Run.  This opens the Run properties dialog.

 

Choose the message you’d like to view as the model runs.  For this exercise, click Set all.  Next click the Latest overlapping button to make the model run for the latest time that overlaps both components in the model, and then click Run.  The water balance model runs at a daily time step, which is the same time step as the daily streamflow values.

 

 

When the model runs, the trigger tells the model that it needs to know the storage for Watershed 2 at 12/31/1999 12:00:00 AM.  Each component then communicates which data items are needed in order to compute the storage at that time.  In this simple example, the components basically say, “To calculate the storage you requested, I need to begin by computing storage from 1/1/1999 12:00:00 AM.”  This is how the composition knows over what time period to run, which is basically for the year 1999 in this case.

 

As the model runs, you will see the simulation progress and a record of the events that occurred, based on the events that you checked earlier.  First, the model will download the daily streamflow values from NWIS that are required for the model run.  Then the model will perform each time step to compute storage in the watershed.  Note that the download of streamflow occurs before the main model loop, and so the simulation progress may appear to be frozen until the data download is complete.

 

 

Close the messages dialog and you’ll get a warning like what’s shown below.  Choosing Yes will allow you to run the model again, choosing no will let you view the results.  Choose no this time so we can see the results file. 

 

 

Open and view the results files in the OpenMI_ExFiles folder.

 

  • results_inflow.txt – the inflow values from NWIS (cubic meters per second)
  • results_outflow.txt – the outflow values from NWIS (cubic meters per second)
  • results_storage.txt – the calculated storage values (cubic meters)

 

Note: If you decide to run the model again, make sure you delete these text files before running the model.

 

You have just created a simple simulation model that gains access to the federal archival of streamflow through the WaterOneFlow system.  Because we used OpenMI as the mediator between the data source and the model, it is easier to separate these two components and use them as part of other models.  This modularity is the advantage of OpenMI.

Verify results

There are a number of ways that you can see if the model is computing its results correctly.  One way is to set up a spreadsheet that includes the inflow, outflow, and storage results from the text files mentioned above, as well as streamflow data obtained independently from the model.  You can then compare the model’s inflows and outflows to the streamflow data to see if the numbers match up.  You can also compute storage from the independently obtained streamflow data, and see if it matches storage as computed by the model.

Note: If you wish to look up data for the stream gages used in this exercise, the NWIS unique codes for the gages are:

  • Trent River near Trenton, NC: 02092500
  • Trent River at Pollocksville, NC: 02092554

 

This concludes the exercise. 

Primary Contact:

Jon Goodall
Duke University

e-mail: jon.goodall@duke.edu
Phone: (919) 613-8716
webpage: http://www.nicholas.duke.edu/faculty/goodall.html

These materials may be used for study, research, and education, but please credit the authors and the Center for Research in Water Resources, The University of Texas at Austin. All commercial rights reserved. Copyright 2007 Center for Research in Water Resources.