Table of contents
| Include Page |
|---|
| 1 Introduction |
|---|
| 1 Introduction |
|---|
|
...
Although it may appear a huge challenge to turn a model engine into an OpenMI-compliant linkable component, it may not be as difficult as it seems. The OpenMI Software Development Kit provides a large number of software utilities that make migration easier. These tools and 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 book assumes that you will use the OpenMI utilities to the full extent. Step-by-step instructions are given for the whole migration process, from defining the requirements for an OpenMI omponent, through design and implementation to testing. This chapter describes the requirements for OpenMI-compliance and introduces the Simple
River model, which is used to illustrate the migration process.
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.
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.
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
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.
| Include Page |
|---|
| 2 Planning the migration |
|---|
| 2 Planning the migration |
|---|
|
4. Migration - step by step
The best strategy when migrating a model is to split the process into a number of steps; at the end of each step you can compile your code and run a small test.
The steps needed for migration are described in this chapter. |
|---|
| Include Page |
|---|
| 4.1 Step 1 - Changing your engine core |
|---|
| 4.1 Step 1 - Changing your engine core |
|---|
|
| Include Page |
|---|
| 4.2 Step 2 - Creating the .Net assemblies |
|---|
| 4.2 Step 2 - Creating the .Net assemblies |
|---|
|
| Include Page |
|---|
| 4.3 Step 3 - Accessing the functions in the engine core |
|---|
| 4.3 Step 3 - Accessing the functions in the engine core |
|---|
|
| Include Page |
|---|
| 4.4 Step 4 - Implementing the MyEngineDotNetAccess |
|---|
| 4.4 Step 4 - Implementing the MyEngineDotNetAccess |
|---|
|
| Include Page |
|---|
| 4.5 Step 5 - Implementing the MyEngineWrapper class |
|---|
| 4.5 Step 5 - Implementing the MyEngineWrapper class |
|---|
|
| Include Page |
|---|
| 4.6 Step 6 - Implementing the MyModelLinkablComponent |
|---|
| 4.6 Step 6 - Implementing the MyModelLinkablComponent |
|---|
|
| Include Page |
|---|
| 4.7 Step 7 - Implementation of the remaining IEngine methods |
|---|
| 4.7 Step 7 - Implementation of the remaining IEngine methods |
|---|
|
5. Migration of the Simple River
The previous chapter described the steps involved in migrating a model to the OpenMI.
This chapter shows how the migrated code is developed for the Simple River example. |
|---|
5.1 The Simple River Wrapper
The Simple River model uses the migration pattern shown in Figure 12. Figure 13 gives a detailed explanation of how the Simple River wrapper works in terms of the wrapper classes.
Image Added
Fig. 13 Simple River wrapper classes
| Include Page |
|---|
| 5.2 Implementation of the Initialize method |
|---|
| 5.2 Implementation of the Initialize method |
|---|
|
| Include Page |
|---|
| 5.3 Implementing the SetValues method |
|---|
| 5.3 Implementing the SetValues method |
|---|
|
| Include Page |
|---|
| 5.4 Implementing the GetValues method |
|---|
| 5.4 Implementing the GetValues method |
|---|
|
| Include Page |
|---|
| 5.5 Implementation of the remaining methods |
|---|
| 5.5 Implementation of the remaining methods |
|---|
|
6. Testing the component
It is important to test the component to check that it is working correctly. Traditionally, the procedure has been to complete implementation and then run the engine to see if it produces the correct results. However, in recent years new methodologies have been developed for testing. The dominant testing method for object oriented programs is unit testing. Unit testing is done in parallel with the implementation. This means that you will be able to find errors earlier and thus save time on debugging your code later.
This chapter discusses the testing of migrated components. |
|---|
| Include Page |
|---|
| 6.1 Unit testing |
|---|
| 6.1 Unit testing |
|---|
|
| Include Page |
|---|
| 7. Implementing IManageState |
|---|
| 7. Implementing IManageState |
|---|
|
| Include Page |
|---|
| 8. The OMI file |
|---|
| 8. The OMI file |
|---|
|
| Include Page |
|---|
| 9. The OpenMICompliancyInfo file |
|---|
| 9. The OpenMICompliancyInfo file |
|---|
|
...