1. Introduction

Although it may appear a huge challenge to turn a model engine code (the computational heart of a model) into an OpenMI-compliant linkable component, it may not be as difficult as it seems. The OpenMI Software Development Kit (SDK) provides a large number of software utilities that make migration easier. These utilities can be used by anyone migrating a model but are not required in order to comply with the OpenMI standard. The utilities can be used as a whole or you can select only a few of them; alternatively, you can use the utilities as the basis for your own implementations. This article assumes that you will use the OpenMI SDK to the full extent. Step-by-step instructions are given for the whole migration process, from defining the requirements for an OpenMI component, through design and implementation to testing. This section describes the requirements for OpenMI-compliance and introduces the Simple River model, which is used to illustrate the migration process.

1.1. OpenMI compliance

The official requirements for OpenMI compliance are:

There are two variants of OpenMI compliance. Component can be either OpenMI 1.4 .Net compliant or OpenMI 1.4 Java Compliant.

OpenMI .Net compliant components must follow the compliance definition given in the comments in the file ILinkableComponent.cs

OpenMI Java compliant components must follow the compliance definition given in the comments in the file ILinkableComponent.java

However, when you use the software development kit provided by the OpenMI Association Technical Committee (OpenMI.OATC.Sdk) most of the requirements for compliance will automatically be taken care of.

1.2. The simple river example

A Simple River model engine was developed as an example of model migration. The model engine is programmed in Fortran and is a very simple conceptual river model. The Simple River consists of nodes and branches, as shown in Figure 1. For each timestep, the inflow to each node is obtained from a boundary-input file. These flow rates are multiplied by the timestep length and added to the storage in each node. Then, starting from the upstream end, the water is moved to downstream nodes and the flow rate in each branch is calculated.

Source code for the Simple River model (FORTRAN engine and C# wrapper) is included in the OpenMI 1.4.0.0 SDK release, which can be downloaded from:  http://sourceforge.net/projects/openmi/ 

Image Removed

Fig 1. Simple River network

The Simple River engine reads data from three input files, which contain information about the inflow to the river nodes (boundary file), the simulation period and timestep length (simulation file) and the river network (network file) - see Figure 2.

Image Removed
Fig 2. Simple River input and output files

2. Planning the migration

Before you start migrating a model it is important that you have a precise idea about how your model is intended to be used when it is running as an OpenMI component. Think about any situation where it will be useful to run your model linked to other OpenMI components. Such components could be other models, data providers, optimization tools or calibration tools. You may even find it useful to run two instances of your model component in the same configuration.

This chapter suggests ways in which you can plan the migration of a model, including the development of use cases and the definition of exchange items.

2.1 Use cases

Use cases (examples of how software is used) have become very popular in software development. There are no formal requirements for defining a use case. However, what makes a use case different from an example is that a use case is more detailed and well defined. Most importantly, a use case must be formulated in such a way that, after completion of software development, you can unambiguously determine whether the use case is covered or not. The big advantage of use cases is that they are easily understood both by the software developer and the software user. At the beginning of the development process, a number of use cases should be defined. It is important that the repository of use cases at any time, in all areas of the software development, reflects the current target. If a particular use case cannot be fulfilled it should be modified or removed. Two use cases for the migrated Simple River model are given below. The use cases give a step-by-step description of how a user will use the models.

2.1.1 Use case 1: Connecting to other rivers

In the first use case, the Simple River model is connected to another OpenMI-compatible river
model (Figure 3).

Image Removed

Fig 3. Use case 1: Connecting to other rivers

Preconditions:

• The model user has the OpenMI-compliant Simple River model installed on his PC.
• The model user has input files for the Simple River model available on his PC.
• The model user has an OpenMI configuration user interface installed on his PC.
• The model user has another OpenMI-compliant river model (including required datafiles) available on his PC.

Success guarantee (postconditions):

• All models have generated correct results.

Main success scenario:

1. The model user loads the OpenMI GUI on the PC.
2. The model user uses the GUI to browse for available LinkableCompnents.
3. The model user finds the Simple River OMI file and the OMI file for the other river model.
4. The model user loads the two files (components) into the GUI.
5. The model user creates a unidirectional and ID-based link from the downstream node in the other river model to the upstream node in the Simple River.
6. The model user selects input and output exchange items for the link (input quantity for the Simple River is 'Inflow').
7. The model user defines the simulation period.
8. The model user runs the simulation.

Extensions to the use case provide alternative flows. Here, the flow splits from step 5 into two
alternatives.

First alternative:

• 5. The model user creates a unidirectional and ID-based link from the downstream branch in the Simple River model to the upstream node in the other river model.
• 6. The model user selects input and output exchange items for the link (output quantity for the Simple River is 'flow').
• 7. The model user defines the simulation period.
• 8. The model user runs the simulation.

Second alternative:

• 5. The model user creates a unidirectional and ID-based link from the downstream branch in the other river model to an internal node in the Simple River model.
• 6. The model user selects input and output exchange items for the link (input quantity for the Simple River is 'Inflow').
• 7. The model user defines the simulation period.
• 8. The model user runs the simulation.

2.1.2 Use case 2: Inflow from geo-referenced catchment database

In the second use case, the inflow for the Simple River model comes from an OpenMIcompliant
runoff database (Figure 4).

Image Removed
Fig. 4 Inflow from catchments

Preconditions:

• The model user has the OpenMI-compliant Simple River model installed on his PC.
• The model user has input files for the Simple River model available on his PC.
• The model user has an OpenMI configuration user interface installed on his PC.
• The model user has an OpenMI-compliant runoff database (including required data files) available on his PC.

Success guarantee (postconditions):

• All models have generated correct results.

Main success scenario:

1. The model user loads the OpenMI GUI on the PC.
2. The model user uses the GUI to browse for available LinkableComponents.
3. The model user finds the Simple River OMI file.
4. The model user finds the OMI file for the runoff database.
5. The model user loads the two files (components) into the GUI.
6. The model user creates a unidirectional and geo-referenced link from the runoff database to 'All Branches' input exchange item in the Simple River model.
7. The model user selects input and output exchange items for the link (input quantity for the Simple River is 'Inflow').
8. The model user defines the simulation period.
9. The model user runs the simulation.

Note that the runoff for a particular polygon is distributed on the river branches depending on how large a portion of a branch is included in each polygon. This type of boundary condition, where water is added to branches, was not possible in the original Simple River engine. The Simple River engine is (as a result of the migration) extended with this feature, simply because such a boundary condition becomes a possibility when running in combination the OpenMI.

2.2 Defining exchange items

Exchange items are combined information about what can be exchanged and where the exchanged item applies. An input exchange item could define that inflow can be accepted on nodes or river branches. An output exchange item could specify that flow can be provided on branches. The Quantity ID identifies what can be exchanged (e.g. 'Flow') and the ElementSet ID identifies where this quantity applies (e.g. 'Node:1').
The next step is to define input and output exchange items. The exchange items that are required in order to run the use cases are listed in Table 1.

Image Removed
Table 1. Required exchange items for use cases 1 and 2

Naturally, the exchange items should not be limited to a particular network, but for the purpose of planning the migration it is easier to start out with a specific case and then generalize this case when it comes to the more detailed design.

3. Wrapping

The OpenMI standard was designed to allow easy migration of existing model engines. The
standard is implemented in C# running under the .NET framework. Almost all existing model
engines are implemented in other programming languages, such as Fortran, Pascal, C and
C++. In order to bridge the gap between the different technologies and to minimize the
amount of changes needed to be made to the engine core a wrapping pattern will be the most
attractive choice in most cases.
This chapter describes the process of wrapping and the generic wrapper that is provided by
the OpenMI Software Development Kit.

3.1. A general wrapping pattern

Wrapping basically means that you create a C# class that implements the
ILinkableComponent interface. This wrapper will communicate internally with your engine
core. The wrapper will appear to the users as a 'black box', which means that all
communication will take place through the ILinkebleComponent interface (Figure 5).
Image Removed
Fig. 5 OpenMI wrapping pattern
 
One further advantage of using the wrapping pattern is that you can keep the OpenMI specific implementations separated from your engine core. Typically, the engines will also be used as standalone applications where OpenMI is not used and it is naturally an advantage to be able to use the same engine in different contexts. This means that even in situations where new engines are built the wrapping pattern may still be the best choice.
 

3.2 The LinkableEngine

 Model engines that are doing timestep-based computations have many things in common. It is therefore possible to develop a generic wrapper that can be used for these engines. This wrapper is called LinkableEngine and is located in the org.OpenMI.Utilities.Wrapper package. Basically, the LinkableEngine provides a default implementation of the ILinkableComponent interface. Naturally, the LinkableEngine cannot know the specific behaviour of your model engine; this information is obtained though the IEngine interface.
The recommended design pattern for model engine migration when using the LinkableEngine is shown in Figure 6. The design includes the following classes:
 

• The MyEngineDLL class is the compiled core engine code (e.g. Fortran).
• The MyEngineDLLAccess class is responsible for translating the Win32Api from MyEngineDLL to .NET (C#).
• Calling conventions and exception handling are different for .NET and Fortran. The MyEngineDotNetAccess class ensures that these operations follow the .NET conventions.
• The MyEngineWrapper class implements the IEngine interface, which means that it can be accessed by the LinkableEngine class.
• The MyLinkableEngine class is responsible for the creation of the MyEngineWrapper class and for assigning a reference to this class to a protected field variable in the LinkableEngine class, thus enabling this class to access the MyEngineWrapper class.
   
  More details of these classes are provided in the following sections.
  The OpenMI standard puts a lot of responsibilities on the LinkableComponents. The main idea is that when the GetValues method is invoked the providing component must be able to deliver the requested values so that these apply to the requested time and the requested location. To be able to do this the LinkableComponent may have to interpolate, extrapolate or aggregate both in time and space. These and other things are handled by the LinkableEngine.
   
  The LinkableEngine class includes the following features:
   
• Buffering: When a model is running as an OpenMI component it may be queried for values that correspond to a time that is before the current time of the model. Most models will only keep values for the current timestep and the previous timestep in memory. It is therefore necessary to store data associated with the OpenMI links in a buffer. The LinkableEngine handles the buffering for you.
• Temporal interpolation and extrapolation: Most models are only capable of delivering results at times that correspond to their internal timesteps. The LinkableEngine class handles all the temporal operations that are required for LinkableComponents.
• Spatial operations: The LinkableEngine provides a range of spatial data operations.
• Link book-keeping: The LinkableEngine handles book-keeping for links added to your component.
• Event handling: The LinkableEngine sends events that enable an event-listener to monitor the progress of the linked system when running.
   
  More details about how the LinkableEngine works is given in OATC.OpenMI.SDK technical documentation.

Table of contents

4. Migration - step by step

...

...

...

1. Change the engine core so that it can be compiled into a DLL.
2. Add a function to the engine core that will run a full simulation: logical function RunSimulation()
3. Create an engine application (EXE) that from its main program calls the RunSimulation function in your engine core DLL.
4. Run your engine by deploying the engine application and check that the engine is still producing correct results.

...

...

The next step is to create the wrapper classes (Figure 8). For this stage, make sure that the OpenMI Software Development Kit is installed on your PC.
Image Removed
Fig 8. C# wrapping classes
 

Load the .NET development environment. You should create one assembly for your wrapper classes and it is strongly recommended that you also create one assembly for the corresponding test classes.

You should use the following naming conventions for your wrapper assembly:

Assembly name: MyOrganisation.OpenMI.MyModel
Assembly DLL name: MyOrganisation.OpenMI.MyModel.DLL
Namespace: MyOrganisation.OpenMI.MyModel
Class names: MyModelEngineWrapper, MyModelEngineDotNetAccess, MyModelEngineDLLAccess, MyModelLinkableComponent

Naming conventions for the test assembly:

Assembly name: MyOrganisation.OpenMITest.MyModel
Assembly DLL name: MyOrganisation.OpenMITest.MyModel.DLL
Namespace: MyOrganisation.OpenMI.MyModel

Class names: MyModelEngineWrapperTest, MyModelEngineDotNetAccessTest, MyModelEngineDLLAccessTest, MyModelLinkableComponentTest

Now install the NUnit test software (see Chapter 6)

To the wrapper assembly, add the following references:

Org.OpenMI.Standard
Org.OpenMI.Backbone
Org.OpenMI.Utilities.Wrapper

To the test assembly, add the following references:
Org.OpenMI.Standard
Org.OpenMI.Backbone
Org.OpenMI.Utilities.Wrapper
NUnit.framework
MyOrganisation.OpenMI.MyModel

After creating the assemblies and the classes, you can start working on the first class,
MyEngineDLLAccess. Details are given in the next section.

...

...

...

...

using System; using System.Run-time.InteropServices;
using System.Text;
namespace MyOrganisation.OpenMI.MyModel
{
    public class MyEngineDLLAccess
    {
         [DllImport(@"Oatc.OpenMI.Examples.ModelComponents.SimpleRiver.Engine.dll",
	       EntryPoint = "INITIALIZE",
	       SetLastError=true,
	       ExactSpelling = true,
	       CallingConvention=CallingConvention.Cdecl)]
	       public static extern bool Initialize(string filePath, uint length);

          [DllImport(@"Oatc.OpenMI.Examples.ModelComponents.SimpleRiver.Engine.dll",
		EntryPoint = "PERFORMTIMESTEP",
		SetLastError=true,
		ExactSpelling = true,
		CallingConvention=CallingConvention.Cdecl)]
		public static extern bool PerformTimeStep();

          [DllImport(@"Oatc.OpenMI.Examples.ModelComponents.SimpleRiver.Engine.dll",
	       EntryPoint = "FINISH",
	       SetLastError=true,
	       ExactSpelling = true,
	       CallingConvention=CallingConvention.Cdecl)]
	       public static extern bool Finish();
    }
}

...

The fourth step is to implement the MyEngineDotNetAccess class (Figure 10).

Image Removed
Fig 10. MyEngineDotNetAccess class
 
The MyEngineDotNetAccess has two purposes: to change the calling conventions to C# conventions and to change error messages into .NET exceptions.
The listed code below shows the Simple River example code for a MyEngineDotNetAccess class that implements the Initialize method, the performTimeStep method and the Finish method. In each of these methods the corresponding method in the MyEngineDLLAccess class is called and, if this method returns false, the error message from the engine is queried through the GetMessage method (following which an exception is created and thrown).

...

...

The fifth step is to implement the MyEngineWrapper class (Figure 11).

Image Removed

The MyEngineWrapper class must implement the IEngine interface (Oatc.OpenMI.Sdk.Wrapper.IEngine). The easiest way to get started is to make your development environment auto-generate the stub code for this interface.

...

...

using System; using System.Collections namespace MyOrganisation.OpenMI.MyModel {     public class MyEngineWrapper : Oatc.OpenMI.Sdk.Wrapper.IEngine     {        private MyEngineDotNetAccess \_myEngine;        public void Initialize(Hashtable properties)        {           \_myEngine = new MyEngineDotNetAccess();           \_myEngine.Initialize((string)properties\['FilePath'\]);        }         public void Finish()        {           \_simpleRiverEngine.Finish();        }     } }

...

The sixth step is to implement the MyModeLinkableComponent class (Figure 12).

Image Removed

The MyModelLinkableComponent is the OpenMI-compliant linkable component that is going to be accessed by other models. Implementation of this class is very simple. The example code shown below is the complete implementation for the Simple River model.

using System; namespace MyOrganisation.OpenMI.MyModel {    public class MyModelOpenMIComponent :    org.OpenMI.Utilities.Wrapper.LinkableEngine    {       protected override void SetEngineApiAccess()       {          \_engineApiAccess = new MyEngineWrapper();       }    } }

This class inherits from the LinkableEngine class. The class creates the EngineWrapper and assigns it to the protected field variable _engineApiAccess.

...

The basic structure of your engine and wrapper code is now in place. The task is now to go through the MyEngineWrapper class and complete the implementation of the methods that are currently auto-generated stub code. Some of these methods can be completed only by changing the code in the MyEngineWrapper; for others, changes also need to be made to the other classes and the engine core (MyEngineDLL). After completion of each method you should update the test classes and run the unit test.

...

5. Migration of the Simple River

...

5.1 The Simple River Wrapper

The Simple River model uses the migration pattern shown in Figure 4-912. Figure 4-21 13 gives a detailed explanation of how the Simple River wrapper works in terms of the wrapper classes.

...

Fig. 13 Simple River wrapper classes

...

The SimpleRiverEngineWrapper has two private field variables:

...

The _inputExchangeItems is a list of org.OpenMI.Backbone.InputExchangeItem objects and the _outputExchangeItems is a list of org.OpenMI.Backbone.OutputExchangeItem objects. These arraylists are populated in the Initialize method.

...

public void Initialize(System.Collections.Hashtable properties) {    \_inputExchangeItems = new ArrayList(); //ArrayList of    Oatc.OpenMI.Sdk.Backbone.InputExchangeItem objects    \_outputExchangeItems = new ArrayList(); //ArrayList of    Oatc.OpenMI.Sdk.Backbone.OutputExchangeItem objects    // \-\- Create and initialize the engine \-\-    \_simpleRiverEngine = new SimpleRiverEngineDotNetAccess();    \_simpleRiverEngine.Initialize((string)properties\['FilePath'\]);    // \-\- Simulation start time -    // The start time is obtained from the engine core as a string. This string is    // passed and converted to a System.DateTime. Then the    // Oatc.OpenMI.Sdk.DevelopmentSupport.CalendarConverter class is used to convert    // this time into the ModifiedJulianDay (this is the OpenMI standard time)    char \[\] delimiter = new char\[\]{'-',' ',':'};    string\[\] strings = \_simpleRiverEngine.GetSimulationStartDate().Split(delimiter);    int StartYear = Convert.ToInt32(strings\[0\]);    int StartMonth = Convert.ToInt32(strings\[1\]);    int StartDay = Convert.ToInt32(strings\[2\]);    int StartHour = Convert.ToInt32(strings\[3\]);    int StartMinute = Convert.ToInt32(strings\[4\]);    int StartSecond = Convert.ToInt32(strings\[5\]);    DateTime startDate = new DateTime(StartYear,StartMonth,StartDay,StartHour,StartMinute,StartSecond);    \_simulationStartTime = Oatc.OpenMI.Sdk.DevelopmentSupport.CalendarConverter.Gregorian2ModifiedJulian(startDate);    // \-\- Build exchange items \--\-    Dimension flowDimension = new Dimension();    Unit flowUnit = new Unit('m3/sec',1,0,'m3/sec'); //The Simple River only uses    // quantities with the unit m3/sec.    Quantity flowQuantity = new Quantity(flowUnit,'description','Flow',    OpenMI.Standard.ValueType.Scalar,flowDimension);    Quantity inFlowQuantity = new Quantity(flowUnit,'description','InFlow',    OpenMI.Standard.ValueType.Scalar,flowDimension);    int numberOfNodes = \_simpleRiverEngine.GetNumberOfNodes();    for (int i = 0; i < numberOfNodes \-1; i++) //For each branch    {       OutputExchangeItem flowFromBranch = new OutputExchangeItem();       InputExchangeItem inFlowToBranch = new InputExchangeItem();       // One ElementSet is created for each branch. The ElementID's are       // Branch:<Branch number>. E.g. 'Branch:3'       ElementSet branch = new ElementSet('description','Branch:' + i.ToString(),ElementType.XYPolyLine,new SpatialReference('ref'));       branch.AddElement(new Element('Branch:' + i.ToString()));       branch.Elements\[0\].AddVertex(new Vertex(_simpleRiverEngine.       GetXCo-ordinate(i),_simpleRiverEngine.GetYCo-ordinate(i),0));       branch.Elements\[0\].AddVertex(new Vertex(_simpleRiverEngine.       GetXCo-ordinate(i+1),_simpleRiverEngine.GetYCo-ordinate(i+1),0));       flowFromBranch.ElementSet = branch;       flowFromBranch.Quantity = flowQuantity;       inFlowToBranch.ElementSet = branch;       inFlowToBranch.Quantity = inFlowQuantity;       \_outputExchangeItems.Add(flowFromBranch);       \_inputExchangeItems.Add(inFlowToBranch);    }    for (int i = 0; i < numberOfNodes; i++) //For all nodes    {       InputExchangeItem inflowToNode = new InputExchangeItem();       // Each node is a ID-based ElementSet. The ElementSet ID are       // Node:<node number>. E.g. 'Node:3'       ElementSet node = new ElementSet('description','Node:' +       i.ToString(),ElementType.IDBased,new SpatialReference('ref'));       node.AddElement(new Element('Node:' + i.ToString()));       inflowToNode.Quantity = inFlowQuantity;       inflowToNode.ElementSet = node;      \_inputExchangeItems.Add(inflowToNode);    }    ElementSet Branches = new ElementSet('description','AllBranches',    ElementType.XYPolyLine,new SpatialReference('ref'));    for (int i = 0; i < numberOfNodes - 1;i++) //Create an InputExchangeItem that    // has all branches in one ElementSet    {       Element branch = new Element('Branch: ' + i.ToString());       branch.AddVertex(new Vertex(_simpleRiverEngine.       GetXCo-ordinate(i),_simpleRiverEngine.GetYCo-ordinate(i),0));       branch.AddVertex(new Vertex(_simpleRiverEngine.       GetXCo-ordinate(i+1),_simpleRiverEngine.GetYCo-ordinate(i+1),0));       Branches.AddElement(branch);    }    InputExchangeItem inFlowToBranches = new InputExchangeItem();    inFlowToBranches.ElementSet = Branches;    inFlowToBranches.Quantity = inFlowQuantity;    \_inputExchangeItems.Add(inFlowToBranches); }

As you can see from the implementation of the Initialize method, some methods need to be implemented in the MyEngineDotNetAccess class, the MyEngineDLLAccess class and the engine core.

...

Image Removed
Fig. 14 Calling sequence for the initialize method

Note that no DataOperations are added to the OutputExchangeItems. The LinkableEngine class will complete the OutputExchangeItems for you by adding
spatial and temporal data operations to your OutputExchangeItems. You can still add your own data operations as well.

4.5 3 Implementing the SetValues method

The calling sequence for the SetValues method is shown on figure 15 below.

Image Removed
Fig. 15. Calling sequence for the SetValues method

The EngineWrapper class decides what has to be done, based on the QuantityID and the ElementSetID. In the Simple River engine core there is only one possible variable that can act as input, which is the storage of water in the nodes. For the Simple River model, inflow is interpreted as additional inflow, which means that the inflow already received from other sources (the boundary inflow) is not overwritten. The inflow is added to the current storage in the nodes. The ElementSetID is parsed and the node number to which the water is going is determined.

...

4.5.4 Implementing the GetValues method

The source code for the IEngine GetValues implementation is shown below.

public org.OpenMI.Standard.IValueSet GetValues(string QuantityID, string ElementSetID) {    double\[\] returnValues;    Char\[\] separator = new char\[\]{':'};    if (QuantityID == 'Flow')    {       int index = Convert.ToInt32((ElementSetID.Split(separator))\[1\]);       returnValues = new double\[1\];       returnValues\[0\] = \_simpleRiverEngine.GetFlow(index);    }    else    {       throw new Exception('Illegal QuantityID in GetValues method in SimpleRiverEngine');    } }

The branch number is extracted from the ElementSetID and used as an index in the GetValues call to the SimpleRiverDotNetAccess class.

...

Image Removed
Fig. 16. Calling sequence for the GetValues method

...

...

...

The calling sequence for methods not shown in Figure 17 is given in Figure 14, Figure 15 and Figure 15. Note that for some of the methods the full implementation is done in the SimpleRiverEngineWrapper class. The methods GetCurrentTime, GetInputTime and GetEarliestNeededTime are all invoking the GetCurrentTime method in the SimpleRiverDotNetAccess class. The returned time is the engine local time. This time is converted to the ModifiedJulianTime in the SimpleRiverEngineWrapper (see code below).

public OpenMI.Standard.ITime GetCurrentTime() {    double time = \_simulationStartTime + \_simpleRiverEngine.GetCurrentTime() / ((double)(24*3600));    return new Oatc.OpenMI.Sdk.Backbone.TimeStamp(time); }

6. Testing the component

The testing procedure described here assumes you are using the NUnit test tool. You can download the NUnit user interface and libraries fromhttp://www.NUnit.org. This web page also gives more information about NUnit. Basically, you create a test class for each of the wrapper classes; in the test classes you implement a test method for each public method in the class.

...

Image Removed
Fig. 18 Wrapper and test classes for the Simple river model

...

using System; using Oatc.OpenMI.Examples.ModelComponents.SimpleRiver.Wrapper; using NUnit.Framework; namespace org.OpenMITest.Examples.ModelComponents.SimpleRiver.Wrapper {    \[TestFixture\]    public class SimpleRiverEngineDotNetAccessTest    {       \[Test\]       public void GetModelID()       {          SimpleRiverEngineDotNetAccess \_simpleRiverEngineDotNetAccess;          String \_filePath;         \_simpleRiverEngineDotNetAccess = new SimpleRiverEngineDotNetAccess();         \_filePath = 'C:\\SimpleRiver\\UnitTest\\Data\\Rhine';         \_simpleRiverEngineDotNetAccess.Initialize(_filePath);         Assert.AreEqual('The river Rhine',         \_simpleRiverEngineDotNetAccess.GetModelID());         \_simpleRiverEngineDotNetAccess.Finish();       }    } }

Image Removed
Fig. 19. NUnit Userinterface with Simple River wrapper classes loaded

7. Implementing IManageState

Implementation of the IManageState interface is not required in order to claim OpenMI compliance. However, if you want to use your model in configurations where iterations are needed or you want to use calibration or optimization controllers, the implementation of the IManageState interface is required. Normally, you should put the bulk of the implementation into the engine core and save the data required in order to restore a state in memory.

7.1 The IManageState interface

Implementation of the IManageState interface is shown in Figure 20.

...

1. In MyLinkableEngine, specify that it implements the IManageState interface.
2. In MyEngineWrapper, specify that it implements the IManageState interface.
3. Implement the IManageState methods in all wrapper classes. The implementation will typically be very simple code that redirects the call to the next wrapper class and finally to the engine core, where the bulk of the implementation is located.

Image Removed
Fig. 20. IManageState implementation

8. The OMI file

The OMI file defines the entry point to a LinkableComponent. It contains information on the software unit to instantiate and the arguments to provide at initialization. This file makes it possible for a user interface to deploy your model.

...

8.1 Structure of the OMI file

The structure of the OMI file is defined in OpenMI.Standared.LinkableComponent.XSD. (http://www.openmi.org/schemas/LinkableComponent.xsd) Figure 21 provides a visual representation of the schema definition; The XML listing below provides an example of an OMI file.

Image Removed
Fig. 21. Visual representation of the LinkableComponent XML schema definition.

OMI file Example:

<?XML version='1.0'?> <LinkableComponent Type='org.OpenMI.Examples.MC.SimpleRain' Assembly='org.OpenMI.Examples.MC, Version=1.4.0.0, Culture=neutral, PublicKeyToken= 8384b9b46466c568' XMLns='http://www.openmi.org/LinkableComponent.xsd'> <Arguments>    <Argument Key='Data' ReadOnly='true' Value='c:\OpenMI\Examples\Data\SimpleRain.txt' /> </Arguments> </LinkableComponent>

9. The OpenMICompliancyInfo file

OpenMI compliant components must be associated with an OpenMI compliance info file. This file useful information for people that are planning to use the component in an OpenMI configuration. The OpenMI compliance info file must comply to the schema OpenMICompliancyInfo.xsd ((http://www.openmi.org/schemas/OpenMICompliancyInfo.xsd)).

...