Getting Started - Netbeans and the OMS Console

The general approach to OMS modeling involves using the IDE to develop, compile, and debug source code written in supported languages (currently Java, FORTRAN, C, C++, and NetLogo), and to build a .jar file for OMS simulations. Then the modeler uses the OMS Console and domain specific lanaguage (DSL) elements to create and run simulations (test, simulate, calibrate, analyze).

System Requirements and Installing OMS on Your Computer

OMS Installation

• JDK 1.6 installed. The JRE is not sufficient to run OMS!
• ANT 1.8+ if you need to build a model from within the Console; this is provided if Netbeans is used as the IDE (see next section)
• GCC 4.+ if you need to integrate native code in FORTRAN or C; this is provided if you install MinGW (see next section)

1. Unzip the OMS download into any folder.
2. Execute console.sh or console.bat in order to start the OMS Console.

On its first execution the console will install required jar files and configuration files into HOME/.oms. Those files are being used to run models, and an IDE can use the jar files during model development.

Installing Netbeans and Creating a Project Workspace (EXERCISE 1)

Setting Up a Project Workspace

Although modelers do not have to use one of the oms3.prj.<prjname> templates or examples, they can avoid several configuration and set-up steps by using one. A template project provides both Netbeans and OMS configuration properties necessary for a successful OMS modeling experience.

A project template should be extracted (if zipped) and/or copied to a directory of the modeler's choice. The basic oms3.prj.template provides the folder stucture displayed in the graphic below. Starting out, the folder name oms3.prj.template should be changed by replacing "template" with a suitable name, for example, the workshop training project is oms3.prj.csm ("csm" an acronym for crop simulation model).

Using Netbeans, the modeler should open the template project via File>Open Project. A snapshot of the Netbeans user interface follows, displaying the folders and files for a mock-up oms3.prj.csm.

As the modeler develops and compiles source code, Netbeans will add the build and dist folders to the project to contain the build products. Source code is saved in the src folder.

Simulations developed with the OMS Console are saved in the simulation folder. Data files for simulation are placed in the data folder. Simulation output files in the output folder. Auto-documentation also is saved to the output folder. Other relevant documentation is kept in the docs folder.

Using the OMS Console (EXERCISE 2)

OMS Console - Simulation

The main purpose of the OMS Console is to allow a modeler a straightforward and simple tool to develop a model, create a simulation, run the simulation, provide for parameter editing and offer ad-hoc post run analysis and visualization. The figures below provide an overview of the OMS Console.

The Console's principal UI is shown in the figure above. Several buttons and layout features are familiar standard elements. The UI is organized as follows:

Working Directory

Simulation Tabs

Toolbars

Editor

Console Output

Status Line

1. Create a new, empty simulation.
2. Open an existing simulation from <working directory>/simulations.
3. Save all open simulations.
4. Select options and settings (show hidden files, folders; clear output before next run)
5. Create a new project (currently inactive)
6. Close current project
7. Open project
8. Save simulation script to a file. If the file is new, it will prompt for a name.
9. Run the simulation script.
10. Interrupt and stop a running simulation. If no simulation is running this button is disabled.
11. Open the Parameter Editor loading referenced parameter files from the current simulation. The Parameter Editor is explained in a section below.
12. Open the Analysis Output window. The window will open if a simulation specifying analysis has run. The analysis window is explained in more detail below.
13. Generate Docbook5 documentation of the simulation and store it into the project output folder.
14. Clean and build the model. This is an alternative to doing this in Netbeans or the IDE being used.
15. Open the last output folder using the computer operating system file explorer.
16. Clear the console output for this simulation.
17. Set logging level for the simulation. This will result in more or less verbose output during simulation execution.
    
18. (Not shown) Create a SHA digital signature of the simulation and print the simulation fingerprint to the Analysis Output Window.
    

OMS Console - Parameter Editor

The editor works on parameter files that adhere to the OMS CSV parameter file format. Such files can be easily edited with other external tools such as Excel, however the parameter editor provides an easy to use interface to manipulate parameter values numerically.

Note that only parameter files referenced as properties in the model parameter sub-element in a simulation using the .. parameter(file:'<name>') ... construct can be loaded into the Parameter Editor. Parameters and parameter files referenced as sub-elements of the parameter sub-element, that is, contained within curly brackets "{...}" cannot be loaded into the Parameter Editor.

The figure above shows the Parameter Editor with loaded parameters. The layout of the window is organized as follows.

Parameter File

Filter

Command Console

Parameter Editor Panel

The figure above shows the parameter editor with an applied dimension filter. The table presents all parameters bound to a specific dimension. Selecting cells in the table will print basic statistics about those on the bottom of the window. Any area can be selected, a column selection will print statistics about the whole column at the bottom of the editor.

OMS Console - Analysis Output

The tile bar shows the output folder containing the analysis data. Depending on the setting in <outputstrategy>, such output can be versioned or unversioned. With either setting, the last output folder of a simulation run is presented.

The analysis tabs contain the plots, graphs, and charts, such as timeseries, error, scatter, flowduration, and other analyses. The tab name reflects the analysis performed.

A part of the analysis section used to create the plots above is shown below.

...
analysis(title:"Simulation Output") {
    timeseries(title:"East Fork Carson", view: COMBINED) {
        x(file:"%last/out1.csv", column:"date")
        y(file:"%last/out1.csv", column:"basin_cfs")
        calc(eq:"simulated - observed") {
             simulated(file:"%last/out1.csv", column:"basin_cfs")
             observed(file:"%last/out1.csv", column:"runoff[0]")
        }
        y(file:"%last/out1.csv", column:"runoff[0]")
    }
     timeseries(title:"Error", view: MULTI ) {
...

Note the timeseries sub-element of analysis maps to the view of the plot graph above. Note the variable %last references the last output folder of a simulation run. The plot contains three y axes, one of which involves the calculation of simulated minus observed values.

To reiterate, the Analysis Output window displays graphics only if the analysis DSL element is specified in the simulation file.