Introducing OMS using the Thornthwaite Model

OMS presents the model developer / model user with a graphical user interface that enables user to build model components, create a model, add components to a model and connect and control their execution order, run the model, and finally view the output of model runs. The remainder of the Quick Start Guide is written in walk-through fashion using an existing model therefore it will be necessary for you to follow the instructions in order to see the various features.

Figure: Thornthwaite Conceptual Model Structure

OMS is bundled with an modeling project example. The Thornthwaite water balance model uses an procedure to analyze the allocation of water among various components of the hydrologic system. The Thornthwaite example project contains the assembled water balance model thornthwaite.jma, its source components in the src folder, an climate data input set, and a parameter file. Figure 2.2, “Thornthwaite Conceptual Model Structure” shows all the components and their relationship regarding internal end external data flow.

Open the Thornthwaite Example Project

Click on the link that says Open the Thornthwaite example project shown in the OMS Welcome Tab and you will notice that an item appears in the Modeling Projects panel. This item is the project folder for the Thornthwaite example. Expand the Thornthwaite project folder by clicking on the "+" sign next to the folder and you will see the standard project folder structure that gets created when a project is created. These folders are required by OMS and are created automatically by the OMS Project Creation Wizard.

Figure: Thornthwaite Project Folder

Thornthwaite Data Folder Contents

Expand the Thornthwaite data folder by clicking on the "+" sign next to the data folder and you will see a file named thorn.dat and a file named thornthwaite.pps.

These files are:

thorn.dat

The time series temperature and precipitation input data for the thornthwaite model.

thornthwaite.pps

The parameter input file for the thornthwaite model.

If you double click on the file named thorn.dat the contents of the file will be displayed as its own tab next to the Welcome to OMS tab.

Figure: Thornthwaite Data Folder

Close the thorn.dat tab by clicking the small x located at far right of the thorn.dat tab.

Thornthwaite Source Code Folder Contents

Expand the Thornthwaite src folder by clicking on the "+" sign next to the src folder and you will see several source code files. These files are Java source code files for the components of the Thornthwaite model. These files were initially created with a wizard in OMS so that they follow the interface conventions for a component in OMS.

Double click on the Climate.java file and view the contents of the file in the source code browser/editor tab. The Climate.java file is the source code used to build a component that will read the input data file named thorn.dat in the project data folder. Most of this file is created automatically via a wizard when it was first created. The sections of the file in blue cannot be edited directly by the user but can be changed via an interface to the file. Creating and changing the contents of a component is explained in other documentation.

Figure: Climate.java File

When finished browsing the Climate.java source file, close the Climate.java tab by clicking on the small x on the far right of the Climate.java tab.

Building the Thornthwaite Components

When Thornthwaite project is installed, the components themselves have not been built. All source code to build the components is available; however, the components have not been built and made available for use in a model. In order to build and make the components available for use, first click on the src folder then click on the button in on the Modeling Projects tool bar. Once you click on the button, you will see the another panel open up at the bottom of the OMS screen (outlined in red below). This panel displays the component build progress.

Figure: Output Panel Showing Component Build Progress

Displaying Project Components

In the previous section we built components from existing source code. In order to view these components, the Component panel needs to be displayed. In order to display the available components, click on the Component Library tab shown below.

Note: If the Component Library Tab is not shown, select the menu item Window | Component Library. This will make it visible.

The Component Library tab is organized by .jar files. The gov-usgs-thorhthwaite.jar contains the components that were created in the previous section

Expand the gov-usgs-thorhthwaite.jar file by clicking on the + plus sign to the left of the folder. Once you have expanded the gov-usgs-thorhthwaite.jar folder, the individual components are displayed. Expand the Snow component by clicking the + sign next to Snow. Once the component is expanded, the attributes for the component are displayed. These attributes are the input and/or output attributes for the component.

Figure: Snow Component Attributes

Displaying The Thornthwaite Model

Now that the components of the Thornthwaite project have been built, the Thornthwaite model itself can be displayed. The model resides in the root directory of the Thornthwaite project. Click on the Modeling Project's tab and then expand the thornthwaite project folder if it is not already expanded. The last item listed under the Thornthwaite project is the thornthwaite.jma model specification file.

In order to display the contents of the model, double click on the thornthwaite.jma file and the Thornthwaite model will be displayed to the right and a couple of other panels are displayed as well. The first element in the model named TimeLoop controls looping over the model components based on time. The elements after the TimeLoop model components themselves. Since the components are under the hierarchy of the TimeLoop, their execution is controlled by the TimeLoop.

The extra panels to the right of the model the Declared Attributes panel (outlined in red below) and the Properties panel (outlined in green below). Each panel is context sensitive depending on where you click in the model. Since Thornthwaite is highlighted in blue at the very top of the model, the Declared Attributes panel display attributes that are declared at the very top (or root) level of the model. The Properties panel shows the properties for the Thornthwaite model itself.

Figure: Declared Attributes and Properties Panels

Each component has input and output attributes that are "hooked up" to declared attributes in the model. This hookup occurs when a component is brought into a model. To display the attribute hook ups for the Climate component, click on Climate component in the Thornthwaite model and you will see the hookups in the Hookups for Climate panel (outlined in red below). In the our example, the component attribute temp is hooked up to the model attribute by the same name that is declared at the TimeLoop control block.

Figure: Climate Component Connectivity

Running The Thornthwaite Model

OMS can manage the running of OMS models in several different modes. We will only touch on one mode of running an OMS model in this document. To select the desired mode of running the model, first click on the thornthwaite.jma file in the Modeling Projects panel and then select OMS Internal Execution from the drop down list for the Executor element in the Properties of thornthwaite.jma panel.

Figure: Select Internal Model Execution

There are several different ways to initiate the running of an OMS model. You can select the thornthwaite.jma file in the Modeling Projects tab and then press the function key F6. You can also right click on thornthwaite.jma and select Execute and finally you could select the green triangle at the middle top of the OMS screen to initiate a model run.

Figure: Executing the Model

When you execute a model in the OMS Internal Execution mode another tab appears in the center section of OMS called the model execution tab. The model execution tab controls the viewing and editing of model attributes, filtering which parameters are shown in the view, selecting the correct input files, running the model, debugging the model, and viewing the output.

The Data tab contains all the attribute that the model uses. The model attributes have their default values the first time the model is initiated. What attributes are viewable depends on the filter that is selected in the drop down filter selection box.

Note: The properties and Output panels have been closed below to get more room on the screen

The next step in running the model is selecting the desired input file. Click the folder Icon at the top left of the Repository tab and select thornthwaite.pps from the file browser dialog.

You might have noticed that some of the model attributes changed when you selected the input file. The change occurred because values for these attributes were read in from the data file.

In order to run the model, click the green triangle at the top left of the model execution tab to run the model.

Figure: Running the Model

You will notice that once you run the model that more of the model attributes have changed. This is because the these attributes were calculated during model execution. You will also notice that progress bar displays model execution and the Output panel reappears.

Click on the Output tab to view output of the model. The left window in the Output tab shows the most recent run and the right window shows a history of all the runs.

Model output can also be quickly graphed if the output is in OMS tabular form. Expand the out.tsd item by clicking on the + sign next to it and right click on the runoff output and select Data Plot.

Figure: Selecting Output to View

Once you selected data plot, another tab appears with graph icon on it showing the plot of runoff over time that the model calculated. Basic statistics for the runoff output are shown to far right (outlined in blue below).

Figure: Viewing Output Plots