What is new in version 1.4.0.0 for end users

In previous versions of the OpenMI, end users would normally install the OpenMI Environment before starting to create or run OpenMI linked systems. This has been changed with the OpenMI 1.4.0.0 version, where all required files are provided by the model/component provider.

However, end users may choose to use the OpenMI Configuration Editor (called OmiED in previous versions). Installation files for this editor can be downloaded from http://sourceforge.net/projects/openmi/.

Apart from the changes above, everything works in the same way as for previous releases. (The major changes for the OpenMI 1.4.0.0 relate to developers and not to end users.)

What should be installed on users computers

From now on, all files for using the OpenMI will be provided by the model/component providers.

However, you may choose to use the OpenMI Configuration editor provided by the OpenMI Association Technical Committee. Installation files for the editor can be downloaded from http://sourceforge.net/projects/openmi/.

Linking models

There are many ways in which the OpenMI can be used. However, in order to keep this guide short and simple an example of the typical usage of the OpenMI is given below.

In order to demonstrate the capabilities of the OpenMI, a complex system of integrated catchment modelling is shown in Figure 1. Meteorological data from a number of measurement stations are handled by a database system. This system will provide precipitation and evaporation data to rainfall-runoff models. The rivers are modelled by a simple conceptual river model that will obtain inflow data from the rainfall-runoff models. For a particular river reach, a more detailed representation of the river flow is required. This river reach is modelled by a physically-based hydrodynamic river model. The river model will obtain inflow data for its upper boundary from the conceptual river model and will provide inflow data for the conceptual river models that connect to the downstream boundary of the hydrodynamic river model. Interaction between groundwater and surface water is considered important at the location of the hydrodynamic model. The underlying aquifer is modelled by a 2D distributed groundwater model. The groundwater model will receive leakage from the river model. The river model will calculate this leakage based on information about the groundwater level, which is obtained from the groundwater model.


Figure 1. Example of integrated catchment modelling that can be realized by combining OpenMI-compliant models

This system can be built using appropriate OpenMI-compliant models.
The procedure for building such a system is as follows:

• Populate each of the models with the required data through the preparatory user interfaces of each individual model. The prepared input data for these models is saved to disk. Most OpenMI models will, when input files are saved, also create a small OpenMI standardized XML file (the OMI file), which contains information about the filename for the OpenMI-compliant model component (the LinkableComponent) and the filenames for input files.
• Use an OpenMI editor to add the models to a configuration. Figure 2 illustrates the open source OpenMI Configuration Editor. With this editor, the user selects [Add model] in the Configuration Editor and browses the file system to find the OMI files. Each time an OMI file has been selected, the OpenMI-compliant model component is loaded and the component reads its input files.
• Connections between the models are created simply by dragging arrows from one model to another. Clicking a connection brings up a link editor dialog (see Figure 3). This dialog has information, obtained from the model components, about which quantities can be provided and which quantities can be accepted. The required combination can then be selected.
• When all the links have been established, the linked system can be run.
• When the model run has completed, the results from the calculations can be investigated through the proprietory user interfaces of each individual model.

Figure 2. Open source OpenMI configuration editor used to configure links between the models shown in Figure 1



Figure 3. Open source OpenMI Configuration Editor's link property dialog for the link from the hydrodynamic river model to the groundwater model

The steps described above are valid for the open source user interface. The OpenMI standard does not prescribe that this particular user interface should be used, and we foresee that in the future there will be many different user interfaces available.

Using the configuration editor

Introduction

The OpenMI standard provides the capability for linking different computational models, mostly used for water and environment modeling. After this standard was introduced, the need arose for a user-friendly application to link OpenMI-compliant models. The Configuration Editor performs this task.

Note that the Configuration Editor in previous releases was called OmiED. You may still find this name in figures and documentation files.

Working with the Configuration Editor

Adding models to a composition

The first step in linking models together is to add the models to a composition. From the menu bar, select Composition > Add Model. In the Open dialog, choose the OMI file corresponding to the first model and click on OK. A rectangle representing the model appears in the composition area. (Note that the same operation can be performed using a pop-up menu, which is opened by right-clicking.)



Repeat this procedure for each model that you want to include in the composition. The only limitation is that two models cannot have the same ModelID.

You should also add a Trigger if you want to run a simulation of the composition. Select Composition > Add Trigger. The Trigger is a special model used to start the simulation; see Running a simulation for more detail.

To show the properties of the model, select Composition > Model properties and choose the required model. Alternatively, right-click on the model rectangle and select Model properties.



See Linking models for more detail about the Exchange Items tree.

Linking models

To link two models, you must first create a connection between them. A connection collects the links between two models; all its links have the same direction as the connection itself. From the menu select Composition > Add Connection or on the pop-up menu click Add Connection. Click on the source model's rectangle and then on the target model's rectangle. The source model is the model providing data, the target model is the model accepting data. A line now connects the two models, with a small triangle indicating the direction of the link.



If you select the Use Dimension filter, only input exchange items are shown that have the same dimension as the quantity checked in the output exchange items. The Use ElementType filter is similar but only input exchange items are shown that have either an ID-based element set or an element set of the same type (e.g. line, polygon, poly-line) and with the same number of elements as the checked output element set.

The ElementSet Viewer is a simple tool used to show spatial properties of one or two ElementSets. Check the Output and/or Input ElementSet and click on the corresponding button.

Running a simulation

Before running a simulation, make sure that the Trigger is part of your composition and is linked to one model. The Trigger is a special model used to fire the simulation; its only action is to invoke GetValues() on the linked model at the specified time.

From the menu, select Composition > Run to show the Run Properties dialog.



Here you can set the types of event you want to list during the computation. These events can be stored in a log file (check Log to file and type a filename or click on the right-hand button to browse for a file) and/or shown in a list-box (check Show events in listbox). Remember that the handling of events can cause large performance overheads for models performing fast timesteps; showing events in a list-box will make the simulation particularly slow.

The Invoke trigger at entry defines the time when the Trigger invokes GetValues() on the linked model. It can be set to the latest overlapping time of all the models in the simulation by clicking the Lastest overlapping button. See the Remarks section for the format of the date and time.

The Don't use separate thread check-box determines whether the simulation is run in the same thread as the user interface (UI). If the simulation runs in a separate thread, the UI responds immediately and the user can even stop it. However, some components wrapping - for example a model using COM single-thread apartments - can cause problems, because the model (in this case the COM object) is intialized in the UI thread and not in the simulation thread. If the simulation runs in the same thread as the user interface, and the timestep of a model takes a long time to execute, the UI can stop responding and the user isn't able to stop the simulation. See Command-line options to see how you can change the default thread apartment state.

To start the simulation, click RUN.



After the simulation has finished, a message box appears asking you whether you want to reload the project. The OpenMI standard doesn't include functionallity to reinitialize models after a simulation has finished, and the model may not be able to run the simulation again and may have malformed properties (exchange items, model ID etc.) Reloading just works around this behaviour, and has the same effect as saving the project, restarting OmiEd and opening the project again. However, some models may delete the result files from their simulation if you reload them.



If you decide not to reload the composition, you can do it later using File > Reload.

End-users support

In most cases end-users should ask the model/component providers for support.

Alternatively, questions can be asked on the OpenMI help forum on source forge.