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).

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 in the linked OpenMI configuration have generated correct results.

Main success scenario:

  1. The model user loads the OpenMI Configuration editor on the PC.
  2. The model user uses the configuration editor to browse for available LinkableComponents.
  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 configuration editor.
  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 (runs the OpenMI configuration).

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 (runs the OpenMI configuration).

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).


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 editor 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 Configuration editor on the PC.
  2. The model user uses the configuration editor 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 configuration editor.
  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.


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 or implementation.

  • No labels

Disclaimer