The purpose of the Open Modelling Interface (OpenMI) is to enable the runtime exchange of data between process simulation models and also between models and other modelling tools such as databases and analytical and visualization applications. Its creation has been driven by the need to understand how processes interact and to predict the likely outcomes of those interactions under given conditions. A key design aim has been to bring about interoperability between independently developed modelling components, where those components may originate from any discipline or supplier. The ultimate aim is to transform integrated modelling into an operational tool accessible to all and so open up the potential opportunities created by integrated modelling for innovation and wealth creation.

This document defines the requirements that a component must meet to achieve OpenMI compliance. These comprise: 1) a very thin core set of requirements covering the information and functions needed to establish a link and make an exchange between two components and 2) a set of optional extensions for handling more complex situations.

The document does not describe how to implement the standard. This information together with a range of software tools for creating and running OpenMI-compliant components are provided by the OpenMI Association and third-party software vendors – visit www.openmi.org for further documentation.

The following are keywords to be used by search engines and document catalogues.

ogcdoc, OGC document, OpenMI, Open Modelling Interface, standard, integrated modelling, model integration, model component, interface, model linking, model coupling, data exchange, API

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

The following organizations submitted this Document to the Open Geospatial Consortium (OGC):

Commonwealth Scientific and Industrial Research Organization (CSIRO), Australia

OpenMI Association (OA), International

All questions regarding this submission should be directed to the editor or the submitters:

Scope

Background

The Open Modelling Interface standard (more usually referred to as the OpenMI) makes possible runtime data exchange between independently developed modelling components. It is an enabling technology that facilitates the simulation of process interactions, where the interactions may either lie within or across the traditional boundaries of scientific disciplines. When the components are models, they may be simple or complex, be based on the same or different concepts and come from the same or different suppliers, whether commercial or open source.

The OpenMI's development has been co-funded by the European Union through two projects (HarmonIT (EC contract: EVK1-CT-2001-00090) and Open-Life (Grant agreement number LIFE06 ENV/UK/000409)) and by the commercial and academic partners of those projects. They were managed by the Natural Environment Research Council (UK) with technical leadership coming from DHI (DK), Deltares (NL) and HR Wallingford (UK), the last with the assistance of its former subsidiary Wallingford Software (now Innovyze (USA)). Future development and the OpenMI's publication as an Open Geospatial Consortium international standard are now the responsibility of the OpenMI Association, which is a legal entity established under Dutch law to take ownership of the Intellectual Property Rights (IPR) relating to the OpenMI – see Annex D for details of the OpenMI Association's IPR policy in relation to the OpenMI standard.

What is it for?

The standard exists to enable the exchange of data between modelling components at runtime; components being anything from a single constant, e.g. Pi, via measurement devices, functions, models, databases, visualization tools and analytical tools, to complex 3D time-variant modelling applications. In more practical terms, components can be anything necessary to build simulation models or decision support systems (DSS). These enable scientists to improve our understanding of the Earth as a system, help policy-makers to find effective and sustainable responses to societal challenges, help entrepreneurs, consultants and developers to explore, develop and deliver new ideas, products and services and provide facilities for teaching and demonstrating our growing knowledge of a joined-up world.

What is it?

The OpenMI is an interface standard and consists of a core group of requirements and optional extensions. The core is very thin and defines the requirements for describing components and the data they can exchange, linking and exchanging data; extensions deal with the more sophisticated data exchange requirements, such as those involving interactions over time and space. At the time of writing, there is one extension, the TimeSpace Extension, that forms part of the OpenMI 2.0 Standard. Clause 6 will explain which requirements are core and which are extensions.

The purpose of the core and extension concept is to allow for the future incremental development of the OpenMI. It is also intended to provide a path for its harmonization and integration with other known standards for example, those of the OGC®.

Users can develop their own extensions and are welcome to put these forward to the OpenMI Association for adoption as part of the formal standard. Such proposals should be made to the OpenMI Association Technical Committee (oatc@openmi.org) or be submitted via the OGC®.

What does it do?

The key feature of the standard is to enable the creation of links between components, where a link matches a variable in one component with its equivalent in another. These variables are referred to as either input or output exchange items. Related to the links are the GetValues and SetValues calls. These calls enable components to obtain ('get')^[1] the values of a variable from one component or change ('set') them in another (at particular locations and/or times should the component compute values over time and/or space). Bi-directional links are also possible (i.e. exchanges between two components can be made in both directions).

Adaptors are used to handle unit transformations and to handle differences in model temporal and spatial resolutions and representations (e.g. vector/raster/non-spatial) – see Figure 1. Adaptors can also be designed to exchange data with model components using alternative interfaces.

Further details are available in What's New in OpenMI 2.0.

How is the OpenMI implemented?

The process begins by analysing the component's description and code and identifying the variables^[2] whose values are to be 'accepted' from or 'provided' to other modelling components via the OpenMI interface. Some modelling components can accept or provide data for a variable at multiple locations, e.g. points in a grid or nodes in a network. In these cases, decisions are needed as to which of the locations are to be able exchange data with other components. It might be decided to expose only one or two points, e.g. the inlet and/or outlet of a process, or any number of points.

Next, if the model component already exists as a callable entity, then the structure of its code needs to be examined. If the code is not in the form 'initialize, run, finalize', then the code must be rearranged into this pattern. This structure facilitates the handing over of partial control to the outside world. For example, it makes possible the design of interfaces that allow another component to request data and, if necessary, cause the component to run until it is able to provide the requested data. If the component does not exist, then it should be designed to have 'initialize, run, finalize' structure.

Finally, the code is 'wrapped', i.e. given an OpenMI interface. There are two main options for doing this. One is to download the OpenMI software development kit (SDK) from the OpenMI Association website and/or use the available third-party tools which simplify this task. These are available from the web at no charge under an open source licence. The other is to write your own code following the specification and the guidance in the user documentation available on the OpenMI Association website at www.openmi.org. The use of the tools is entirely optional and they do not form part of the standard.

Third-party open source tools are also available for building and running compositions, i.e. a set of linked modelling components. The OA intends, subject to resources, to make a set of aids available should there be no third-party software. The use of the tools is entirely optional and they do not form part of the standard.

Future development

Background

In 2008, the OpenMI Association (OA) was approached by the OGC® and asked if it would be prepared to publish the OpenMI Standard as one of the OGC® family of standards. Two reasons were given for the inquiry. The first was the increasing importance of the time dimension in the OGC's work and the consequent need to grow the OGC's knowledge and experience in this area; while the second was to address the growing need, common to all disciplines, to link sensors, datasets, models and related modelling components in order to understand and explore process interactions better. Such understanding could then be applied in improved simulation and decision support systems. It was the early perception of this latter need that led David Schell to found the OGC®.

The OpenMI Association welcomed the invitation because accreditation by an internationally-recognized standards organization would remove an important barrier to use of the OpenMI by public bodies and industry. It would also facilitate the uptake and development of integrated modelling, which is the OA's ultimate goal.

As the Association had just agreed a major upgrade of the OpenMI and was well on with the process of implementing that upgrade, the OGC® and the OA agreed that the starting point for their joint work would be the OpenMI Version 2.0. This was formally released at the International Summit on Integrated Environmental Modelling in Washington in December 2010. The period leading up to and just after the release was used to grow the relationship between the OA and the OGC® and, in particular, to work out how they would collaborate.

The OpenMI-OGC Memorandum of Understanding

The outcome of this period was a memorandum of understanding (MoU) on the way forward, the key points of which are outlined below.

Outline plan

The combined aim of the OpenMI Association and the OGC® is to transform integrated modelling from being a research tool largely confined to academia to an operational tool readily useable by the public and private sectors and ultimately the public. To do this a number of challenges must be overcome; these are:

• Raising and maintaining awareness and building confidence in integrated modelling
• Establishing a minimum set of standards and ensuring their interoperability
• Achieving a critical mass of linkable modelling components
• Ensuring availability, accessibility and usability of integrated modelling techniques, tools and standards
• Building the skills base
• Establishing an underpinning R & D programme
• Growing take-up by government, industry and the public
• Securing resources

It has been appreciated for many years that a key first step in transforming integrated modelling is to establish a recognized standard interface for data exchange. This first standard will not be all-encompassing, will be imperfect and may well not be compatible with other standards. However, it will enable independent model developers to create linkable components. This is the purpose in making the OpenMI V2.0 an OGC® standard. It is expected that the initial rate of development will be slow but accelerating as competency and confidence grow. Once a critical mass of linkable components is in place rapid development can be expected.

While that is happening it is proposed to start addressing the challenges through the OGC® Domain Working Groups (DWG), particularly the Workflow DWG. The Workflow DWG is seen as particularly appropriate in that it is trans-disciplinary and therefore provides a neutral forum where people from any discipline can meet to discuss their shared need. A strong reason for partnering with the OGC® is that it already has a wide membership spanning many disciplines drawn from the public, private and academic sectors. Many either have or will have an interest in integrated modelling.

Exploratory work has suggested that it is feasible to design adaptors that will allow the linking of OpenMI-compliant components with components using other interface standards. An immediate task will be to bring together the authors of other relevant interface standards, including those for modelling and sensors, in order to establish if operational versions of such adaptors can be designed and developed. This will further increase the pool of sensors and modelling components that can be linked. A number of the key players are already OGC® members.

Attention can then be turned to developing a detailed plan for addressing the longer-term challenges. Quite detailed outline plans are known to exist among environmental and health modellers and almost certainly exist in other disciplines. These and the MoU above will form the starting point for the OA-OGC plan.

While it would be wrong to anticipate the detail of that plan, it is almost certain that it will contain a review of all the current interface standards and take a forward look at where additional standards would help advance integrated modelling. If, as is almost certain to be the case, modifications or new standards are required, then these will be progressed through the OGC® Standards Working Group system. Where existing standards are used, the model established for incorporating and publishing NetCDF and the OpenMI as OGC® standards will be followed.

Further reading

The following OpenMI Association documents from The OpenMI Document Series provide further background reading and detailed information on its implementation:

• What's New in OpenMI 2.0 (OpenMI Association, 2010)
• The OpenMI 'in a Nutshell' for the OpenMI (Version 2.0) (OpenMI Association, 2010)
• Scope for the OpenMI (Version 2.0) (Moore, et al., 2010)
• Migrating Models for the OpenMI (Version 2.0) (OpenMI Association, 2010)
• OpenMI Standard 2 Specification for the OpenMI (Version 2.0) (OpenMI Association, 2010)
• OpenMI Standard 2 Reference for the OpenMI (Version 2.0) (OpenMI Association, 2010)

For further details, please see the Bibliography at the end of this document. The cited documents are available through the OpenMI Association website at www.openmi.org.

Document structure

The document that follows defines the Open Modelling Interface. Clause 2 sets out the rules for conformance. Clauses 3, 4 and 5 cover normative references^[3] , terms and definitions, and conventions. Clause 6 specifies in detail the classes for creating an Open Modelling Interface. Testing is described in the Annexes.

Conformance

To conform to this specification and hence be termed 'OpenMI-compliant', a model component shall implement a set of interfaces that can connect to and interact with the OpenMI component interface "IBaseLinkableComponent" (or its specializations, e.g. the "ITimeSpaceComponent" for time and space dependent components). These interfaces are described in Clause 6 'OpenMI Requirements classes'.

The requirements for compliance are as follows:

1. An OpenMI-compliant component shall implement the mandatory 'Core' requirements according to specifications provided in this document – see Clause 6.
2. The OpenMI Association provides two additional core interfaces that OpenMI-compliant components may or may not implement: the "IManageState" interface and the "IByteStateConverter" interface. However, if these interfaces are implemented, each method and attribute shall be implemented according to the instructions given in this document.
3. An OpenMI-compliant component may also implement one or more of the optional OpenMI extensions. If implemented, the implementation shall conform to the specifications provided in this document.
4. An OpenMI-compliant component including its extensions shall, when compiled, reference the OpenMI.Standard2*.DLLs (.Net Framework 2.0 or higher) or OpenMI-standard2*.jars (java 1.5 or higher). These DLLs/jars contain only interfaces. They are compiled and released by the OpenMI Association. The OpenMI Association's downloadable standard zip file provides the only recognized version of OpenMI Version 2 Standard interfaces.

If an OpenMI-compliant component is to run in one or more of the existing GUIs for linking OpenMI-components, it shall be associated with an XML file, referred to as the 'OMI file', which conforms to and can be validated with the LinkableComponent.xsd schema – see Annex B.The interfaces are specified in language independent UML and are available in C# and Java. Both C# and Java compilers will ensure that the client code correctly calls the methods and will ensure type safety for the objects obtained from the method call.

Conformance with the specification shall be checked by applying the abstract tests specified in Annex A of this specification.

Normative References

The following normative documents contain provisions that, through reference in this text, constitute provisions of this document. For dated references, subsequent amendments to or revisions of any of these publications do not apply. For undated references, the latest edition of the normative document referred to applies.

1. OGC 08-015r2, The OpenGIS Abstract Specification, Topic 2: Spatial Referencing by Co-ordinates, 2010-04-27. http://portal.opengeospatial.org/files/?artifact_id=39049
2. Documents associated with Unified Modeling Language™ (UML®), August 2011. http://www.omg.org/spec/UML/2.4.1/
3. Extensible Markup Language (XML) 1.0 (Fifth Edition), 26 November 2008. http://www.w3.org/TR/xml/

Terms and Definitions

In the context of the OpenMI and for the purposes of this document, the following terms and definitions apply:

Adaptee

An output exchange item whose values are to be adapted. In an OpenMI context 'adapt' means:

• to convert units of measurement
• to aggregate or disaggregate output values over time or space
• to interpolate between output values over time or space
• any other operation to convert the output of a providing model component to match the input requirements of the accepting model component.

Adaptor

In the OpenMI context, adaptors are used to convert the output values of the providing component to the form required by the requesting component. Adaptors can be used to handle any or all of unit conversions, spatial transformations and temporal transformations. Users can either use adaptors provided by third parties or write their own.

Compliancy information file

An XML file containing information about a component whose compliance you would like to be registered with and published by the OpenMI Association – see Annex C.

Component

See Model component.

Composition

A set of linked components set up to simulate a particular scenario.

Element

Data exchange between components in the OpenMI is nearly always related to one or more of a set of elements in a space that may or may not be geo-referenced. For example, these elements might represent towns, pathways in the human body, segments of transmission lines or a cellular representation of the atmosphere or a water body for which values are requested or set – see also element set and version.

Element set

An element set can comprise any number of elements and the geometry of each element can be represented in any way from a one-dimensional array of points, line segments, poly lines or polygons, through to an array of three-dimensional volumes. As a special case, a cloud of Id-based elements (i.e. they do not have co-ordinates or their co-ordinates are not being used) is also supported. This allows data exchange in contexts where spatial position is unimportant or irrelevant as might arise in an economic model – see also element and version.

Engine

A synonym for model component often used in OpenMI documentation.

Exchange item

A variable exposed by a model component through the OpenMI interface, whose values can be provided to or accepted from other model components. A specific exchange item will be referred to as being either an input exchange item or an output exchange item. The terms quantity and quality are often used in place of the word variable; quantity if the values are numeric and quality where values are qualitative: for example, 'hot' and 'cold' for temperature or 'sand', 'clay' and 'peat' for soil type.

Link

When used as a verb, it means to connect an output exchange item of one model component to an input exchange item of another.

Linkable component

A model component which implements the OpenMI "IBaseLinkableComponent" interface according to specifications provided in this document.

Model

A model component that has read in the data that describes the situation to be simulated, analysed, visualized or otherwise processed: e.g. a generic model component for simulating the flow of water down an open channel that has been set up to model the specific behaviour of all or part of the River Rhine under given conditions.

Model application

An entire modelling software system that can be installed on a computer.

Model component

A distinct part of a model application where computation takes place – in this context the 'computation' might be simulating a process, analysing or visualizing results or some other process. The computation may be very simple (for example, a linear equation) or extremely complex (for example, a dynamic model of airflow through the nose and mouth to the lungs).

Model linking

The process by which one or more data transfer links are established between the output exchange items of one model component and the input exchange items of another model component.

Modified Julian day

Modified Julian day is the Julian Day minus 2400000.5. A Modified Julian Day represents the number of days since midnight 17 November 1858 Universal Time on the Julian calendar. The Modified Julian Day has been selected as a reference, since few models operate in a time horizon before 1858. Any date before 17 November 1858 will be represented as a negative value.

(See RECOMMENDATION ITU-R TF.457-2. USE OF THE MODIFIED JULIAN DATE BY THE STANDARD-FREQUENCY AND TIME-SIGNAL SERVICES – which may be found at: http://www.itu.int/dms_pubrec/itu-r/rec/tf/R-REC-TF.457-2-199710-I!!PDF-E.pdf)

OMI file

The OMI file is an XML file containing metadata about a component – see Annex B. Third-party GUIs can use the information the file contains to simplify the linking of components.

Quality

In the context of the OpenMI, a quality usually refers to an exchange item whose values are qualitative (for example, 'hot' and 'cold' for temperature) or categorical (for example, 'sand', 'clay' and 'peat' for soil type).

UTC

Co-ordinated Universal Time, the primary time standard by which the world regulates clocks and time - see the definition of Co-ordinated Universal Time (UTC) in Clause 2.1.12 of ISO-8601, http://dotat.at/tmp/ISO_8601-2004_E.pdf.

Version

Although most models assume a static spatial world, some advanced models make provision for a dynamic world, i.e. one in which objects move and/or change shape (e.g. waves). To enable the tracking of spatial changes over time, the Version number has been introduced. If the version changes then the spatial definition may need to be re-queried – see also element and element set.

Conventions

Identification

This document and the standard it defines follow the guidelines of the OGC® Naming Authority for all identifiers. The key identifiers are given below.

The external identifier of this OGC® document

This may be found at the top right hand corner of the front page of this document.

The identifier of this OGC® standard

This standard is identified as:

http://www.opengis.net/spec/openmi/2.0

The base URI for requirement and conformance classes

The base URI for all relative URIs that denote requirements and conformance classes is:

http://www.opengis.net/spec/openmi/2.0

The OpenMI XML namespaces

The namespace for OpenMI 2.0 is:

http://www.openmi.org/v2_0

The XML schema definitions (XSD) are located in:

http://www.openmi.org/schemas/v2_0

Symbols (and abbreviated terms)

1D

One dimensional

2D

Two dimensional

3D

Three dimensional

API

Application programming interface

DSS

Decision support system

DWG

Domain Working Group of the OGC®

Id

Identifier

GUI

Graphical user interface

MOU

Memorandum of understanding

OA

OpenMI Association

OATC

OpenMI Association's Technical Committee

OCT

OATC Conformance Tool

OGC

Open Geospatial Consortium

OMG

Object Modelling Group

OMI

Open Modelling Interface

OpenMI

Open Modelling Interface

SDK

Software development kit

SI

Systeme Internationale (FR) or International System of Units

SWG

Standards Working Group of the OGC®

UML

Unified Modelling Language

URI

Uniform Resource Identifier

URL

Uniform Resource Locator

UTC

Co-ordinated Universal Time (for most purposes this is the same as Greenwich Mean Time (GMT))

XML

Extensible Markup Language

XSD

XML Schema Definition

Unified modelling language (UML)

This document follows the Object Modelling Group's (OMG) recommendations and specifications for UML which may be found at http://www.omg.org/spec/UML/2.4.1/.

Specific UML terms used in this document or used to define other UML terms are:

Attribute

A named property of a type. The UML diagrams explicitly identify those attributes that are 'read-only'.

Class

A description of a set of objects.

Enumeration

A list of named values used as the range of a particular attribute type. For example, Colour = {Red, Green, Blue}.

Event

A significant occurrence. An event has a location in time and space and may have parameters. In the context of state diagrams, an event is an occurrence that can trigger a state transition.

Instance

An individual member described by a type or a class. Usage note: According to a strict interpretation of the metamodel, an individual member of a type is an instance and a member of a class is an object. In less formal usage it is acceptable to refer to a member of a class as an object or an instance.

Interface

The use of a type to describe the externally visible behaviour of a class, object, or other entity. In the case of a class or object, the interface includes the signatures of the methods.

Member

A part of a type or class denoting either an attribute or a method.

Method

The implementation of an operation or service that can be requested from an object to effect behaviour. A method has a signature, which may restrict the actual parameters that are possible

Namespace

A part of the model in which the names may be defined and used. Within a namespace, each name has a unique meaning.

Object

An entity with a well-defined boundary and identity that encapsulates state and behaviour. State is represented by attributes and relationships, behaviour is represented by methods. An object is an instance of a class.

Parameter

The specification of a variable that can be changed, passed or returned. A parameter may include a name, type and direction. Parameters are used for methods, messages and events.

Signature

The name and parameters of a method, message or event. Parameters may include an optional returned parameter.

State

A condition or situation during the life of an object during which it satisfies some condition, performs some activity or waits for some event.

Type

A description of a set of instances that share the same methods, abstract attributes and relationships and semantics. A type may define a method specification (such as a signature) but not a method implementation. Usage note: Type is sometimes used synonymously with interface, but it is not an equivalent term.

http://www.iai.uni-bonn.de/III/lehre/vorlesungen/SWT/SS96/Material/UML1.0/glossary.html#

Extensible Markup Language (XML)

This document follows the W3C recommendation of 26 November 2008 Extensible Markup Language (XML) 1.0 (Fifth Edition) which may be found at http://www.w3.org/TR/xml/.

OpenMI Requirements Classes

The OpenMI Standard comprises:

• a set of 'Core' requirements classes
• an extension set of requirements classes referred to as the 'TimeSpace' extension.

Listed below are the required classes and their component requirements for the Core and the TimeSpace extension. All the Core requirements must be implemented except those marked as optional. Implementation of the TimeSpace extension is optional but, if implemented, all its requirements must be met.

The requirements for each are as follows:

In the following clauses the requirement class descriptions are grouped according to the aspect of the OpenMI to which they relate. Each description begins with a general introduction, which includes a table of the URIs for the requirement class and the specific requirements relating to it. This is followed by a UML diagram presenting the dependencies between the classes. Where appropriate, the UML diagram is supported by one or more tables describing the members (methods, attributes and events) of any interfaces. The description concludes with a table listing the specific requirements that must be met for compliance to be achieved.

Note: In so far as it is possible, the interface descriptions that follow are language independent. However, the UML diagrams and the tables describing the interface members are derived from diagrams and tables generated by program from the C# implementation. A consequence of this is that the description uses the concept of an 'attribute'. Some languages use the term 'property' and as the terms attribute and property are equivalent in this context, there is no problem. Other languages have no attribute concept. However, in these cases, the same functionality can be achieved through the use of methods or functions. Thus, an attribute "Caption" can be represented by two methods, "GetCaption()", which returns the caption value as a string and "SetCaption (string)" which assigns the value in the string to the caption. If the attribute is 'read-only' then no 'Set' method is required.

Developers may find it helpful to view the supported implementations of the standard available in C# and Java and accessible via the OpenMI Association's website at www.openmi.org.

Component instantiation

An OpenMI Linkable Component is instantiated, for example, by loading a .NET assembly and creating an instance of a class that is incorporated into that assembly. The information on the assembly to be loaded and the class to be instantiated is specified in a registration file called the OMI file, which can be located anywhere on disk.

This file also holds the arguments that should be provided to the component when it is initialized.

In addition to its interfaces, the OpenMI Standard therefore also defines an XML Schema Definition (xsd) for the OMI file. Figure 2 provides a graphical view of the file structure according to the XML Schema Definition. The full Schema Definition for the OMI file can be found in Annex B.

Requirements for ComponentInstantiation

The Describable and Identifiable interfaces

Many of the OpenMI interfaces describe entities to which users will need to refer through the user interface.  Therefore, these entities need a caption anda more detailed description where a caption cannot provide all the informationneeded.

In addition, some interfaces describe anentity whose specific instances need to be referenced and these therefore also require descriptors and identifiers.  An exampleof their use might be in establishing and storing a link between two components by pairing the identifier of a specific output exchange item of the providing component with a specific input exchange item of the accepting component.

To ensure consistency in the identification and description of all kinds of entity instances, two interfaces are provided: "IDescribable"and, derived from that, "IIdentifiable" – see Figure 3.  The majority of the OpenMI Standard Version2.0 interfaces are derived from one of these interfaces.

Attributes and methods for Describable and Identifiable interfaces

Requirements for Describableand Identifiable interfaces

The Value Definition interfaces

The OpenMI leaves the modeller free to decide the names used to label exchange items. It does, however, require some minimal information to be provided about each exchange item, partly to reduce the chance of erroneous links being made and partly to check that unit conversions are provided where the output units of the providing component are different to those of the accepting component.

Figure 4 illustrates the information required and the structure in which the information is held.

The "IValueDefinition"interface establishes the data type of a specific exchange item's values and how those values will be represented when missing, e.g. by '-9999'.  A value definition is an IDescribable and therefore has a caption, for example 'Flow', and a description (more extensive information for correct interpretation of the caption and other information such as units, etc.)

The "ValueType" attribute indicates the type of object returned when retrieving one of the values of the set, i.e. the value for a certain element and time.  Typical values of the "ValueType"attribute will be "double", "bool", "string" or a dedicated class type.  Further details will follow below in the descriptions of the "IQuantity" and "IQuality"interfaces.

One of the inheritors of the"IValueDefinition"interface is the "IQuantity" interface.  This interface applies to exchange items whose values are numerical and have a "ValueType" of, for example, "double","int", "boolean" or a class type.  It also establishes the units of measurement in which values of the exchange item will be accepted or returned.

The "IUnit"interface provides additional information for checking that linked quantities have the same dimensions and unit conversion. For a given value v of a specific exchange item variable, the conversion to the SI value s can be made using the following equation:

s =Unit.ConversionFactorToSI() * v + Unit.GetOffsetToSI()

The "IDimension"interface has been defined to enable physical dimension ^[4] checks between quantities.  A dimension is expressed as a combination of the basic dimensions, derived from the SI system ^[5] .  A minor extension has been made for currencies.  Table 3 illustrates the base quantities/dimensions and the associated SI units.  The "IUnit" interface provides a method to obtain the power for each base dimension of a specific exchange item. For example, a discharge expressed in units of m³/s has dimension Length³Time-¹ for which the method would return 3 and ‑1.

A further method checks if the dimensions of two exchange items are equal.

Note that some units are dimensionless, represent logarithmic scales or present other problems when expressed in SI.  In such cases, extra attention should be paid to the descriptive part of the unit, to ensure that a user defining a link has a proper understanding of the meaning of the values for the given exchange item.

The other inheritor of the "IValueDefinition"interface is the "IQuality" interface and it applies to exchange items whose values are qualitative.  The "IQuality"interface specifies the list of categories used to record the state of the variable: for example, 'hot' and 'cold' for temperature or 'sand', 'clay' and 'peat'for soil type.  The "ValueType"for these values will be "string".

The "IsOrdered" attribute indicates whether or not an ordering can be recognized in the categories.  If "IsOrdered" is True, onecategory represents a 'higher' value than another category.  The sequence 'very light', 'light', 'heavy', 'veryheavy' is an example of an ordered categorization.

Attributes and methods for Value Definition interfaces

Requirements for ValueDefinition interfaces

The Spatial Definition interfaces

Many modelling components record, simulateanalyse or visualize the behaviour not just of a single variable at a singlelocation but the behaviour of many variables for many elements of the system.  Data exchange requests in the OpenMI arenearly always directed at one or more of such elements in the providingcomponent.

Elements will usually be spread over 1, 2or 3 dimensional space.  Often but notalways the space will be geographic and the location, shape and extent of eachelement will be defined by geographic co-ordinates.  M co-ordinates are also supported which allowfor linear referencing along a line, for example, distance along a segment ofriver or road.  On other occasions theremay be no spatial aspect to the model and values are computed for a set of Id-basedelements.  Examples of elements might bea town, a section of an artery or nerve, a reach of river or a segment of road,a cell or grid intersection in a climate model or a particular animal orperson.  The collective term used torefer to all the elements represented in a modelling component is "elementset".

An element set can comprise any number ofelements and the geometry of the elements can be represented in any way from aone-dimensional array of points, line segments, poly lines or polygons, throughto an array of three-dimensional volumes. As a special case, a cloud of Id-based elements (i.e. they do not haveco-ordinates or their co-ordinates are not being used) is also supported.  This allows data exchange in contexts wherespatial position is unimportant or irrelevant as might arise in an economicmodel.

As will be explained further below,although the geometry of most current models remains the same during a modelrun, the OpenMI makes provision for the possibility that the location, shapeand extent of each element may change over time.

The "ISpatialDefinition"interface is the general spatial construct of which all other spatialconstructions are extensions – see Figure 5. It makes available the number of elements in the element set, thespatial reference system used for defining locations and the version of eachelement when these are dynamic.  Althoughmost models assume a static spatial world, some advanced models may makeprovision for a dynamic world, i.e. one in which objects move and/or changeshape (for example, waves).  To enablethe tracking of spatial changes over time, the "Version" number hasbeen introduced into the "ISpatialDefinition".  If the version changes then the spatialdefinition may need to be re-queried.

Of the extensions, the one most likely tobe used is the "IElementSet" [7] .  The "IElementSet" interface hasbeen defined to describe, in a finite element sense, the location where eachexchange item value applies.  Tointerpret the co-ordinates correctly, it is necessary to obtain the spatialreference system to which they relate from the "ISpatialDefinition"interface.  Unless the spatial referencesystem specifies differently, the X and Y axes are assumed to lie in thehorizontal plane and the Z axis is vertical.

Note that the "IElementSet"interface can be used to query the geometric description of a modelschematization, for example the locations of sampling points or a rivernetwork, but this description may not necessarily provide all the topologicalknowledge on inter-element connections.

The elements in an element set are identifiedby a string Id, and are therefore IIdentifiables.  Where practicable, the element Id's should bedesigned to be meaningful to end users. The element set does not need to be identifiable, because it is alwaysattached to an input or output exchange item that will have an identity.  However, the element set is an IDescribableand therefore can have a caption and a description; these can be helpful to theend user in composing configurations, i.e. building a linked model.

The properties of an element (its vertices and/or faces) areobtained using an integer index for example, " elementIndex", "faceIndex" or "v ertexIndex" .  This functionality has been introducedbecause an element set is basically an ordered list of elements, an element mayhave faces and an element (or a face) is an ordered list of vertices.  The integer index indicates the location ofthe element/vertex in the array list.

Dependencies, attributes andmethods for Spatial Definition interfaces

Requirements for SpatialDefinition interfaces

The Temporal Definition interfaces

Time in the OpenMI is defined by the "ITimeSet"interface - see Figure 6.  A time setcontains a list of times, where time is specified by the "ITime"interface, containing a Modified Julian Day value and duration.  If the duration is zero, the time is a timestamp.  If it is greater than zero it isa time span.

Attributes and methods forTemporal Definition interfaces

The "ITimeSet" interface containsadditional information about the time stamps or spans that it contains or willcontain.  The "OffsetFromUtcInHours"attribute indicates the time zone in terms of an offset from UTC time.

The value of the "HasDurations"attribute specifies whether the time set's times are time stamps (False) ortime spans (True).

The "TimeHorizon" attributeprovides information on the timeframe during which an exchange item willinteract with other exchange items.  Foran input item, the attribute specifies for what time span the input item can beexpected to request values during the computation.  This means that the providers of this inputcan assume that the input item never goes back further in time than the timehorizon's begin time, "StampAsModifiedJulianDay".  Also, it will never go further ahead than thetime horizon's end time, "StampAsModifiedJulianDay + DurationInDays".

For an output item, and also for an adaptedoutput item, the time horizon indicates the time span in which the output willbe able to provide values.

To indicate that an input item may ask forvalues far back in time, or that an output item can provide values as far backin time as requested, the begin time of the time horizon should be set toinfinitely back in time, i.e. the "StampAsModifiedJulianDay" shouldbe set to the 'negative infinity value' of a double precision number.  Comparably, if an input item may requestvalues far in future, or if an output item can provide values far in thefuture, the end time of the time horizon should be set to infinitely far aheadin time, i.e. the "DurationInDays" should be set to the 'positiveinfinity value' of a double precision number.

Requirements for TemporalDefinition interfaces

The Value Set interfaces

The volume and structure of the data valuesexchanged between components can vary from a single value to largen-dimensional arrays.  Therefore ageneric solution, the "IBaseValueSet" interface, has been developedwhich component developers can configure to meet their specific requirements.  However, in most instances, the full power ofthe generic solution will not be required.  Therefore the time and space extensionOpenMI.Standard2.TimeSpace contains a preconfigured version of the "IBaseValueSet"interface, the "ITimeSpaceValueSet" interface.  This will be described first as it provides auseful introduction to the more abstract generic solution.

The "ITimeSpaceValueSet" interface sets and returns valuesin the form of an ordered 'list of lists', called "Values2D".  This can be visualised as shown in theadjoining diagram.  The first dimension(the rows) represents the times for which values are to be set or were requested.  There is one row for eachtime.  The cells along each row (whichcan be thought of as the second dimension) each contain the value relating top recisely one element in the element set (which was specified when setting or requesting for the values).  In otherwords, the i^th value in that dimension of the value set corresponds to the i^th element in the specified element set.

Note: the list of lists structure allows the rows to be of different lengths,though in many cases they will all be the same length.  The 'missing value' value, e.g. -999, must beused to ensure that values are located the correct column for the element towhich they relate.

The following pseudo code illustrates howvalues can be located in the "Values2D" list of lists.  Note that all indices are zero-based.

The number of distinct times for which values are returned (= the number of rows):

     numTimes = valueSet.Values2D.Count

     numElementsForFirstTime = valueSet.Values2D[0].Count

     valueForSecondTimeAndFifthElement = valueSet.Values2D[1][4]

     valuesForAllElementsOnSixthTime =  valueSet.Values2D[5]

     ValuesForFourthElementForAllTimes = GetTimeSeriesValuesForElement(3);

Methods and attributes to simplify accessto "Values2D" will be found in Table 18.  For example, Three pairs of Set/Get-Value methods areprovided for requesting or setting exchange item values.  These allow the user to set or get the valuesfor:

• A specific time and/or element (Set/Get-Value)
• ·All times for a given element (Set/Get-TimeSeriesValuesForElement)
• All elements for a given time (Set/Get-TimeSeriesValuesForTime)

Not all models or components require therepresentation of time and/or space. Even if they do, they may still need to exchange data that do not have spatial or temporal dimensions. An example might be the need to set or request the values of model parameters during calibration. There may also be data that do have spatialand temporal dimensions but which do not fit the model above, for example, atime-series of 3-dimensional gridded values or other data types altogether suchas complex numbers.

The "IBaseValueSet" interface provides the developer with a blob through which values can be set or returned by the"GetValue()" and "SetValue()" methods – see Table 17.  

The developers can configure this blob as alist or list of lists, nested as many times as are necessary to handle thestructure of the values to be exchanged.  If more convenient, the blob may be viewed as amulti-dimensional array, whose dimensionality can be discovered through the"NumberOfIndices" attribute.  The blob is "Idescribable" and so the developer can usethe caption and description attributes to document the structure of the blob.  In particular, the description should explainthe meaning of each level in the lists or each dimension of the array.  For example, they could be used to representx, y, z and t. However, it is important to stress that the axes are not confined to representing time or space. They may represent any quantity.  The following pseudo code shows how a 3 level list of lists of lists, i.e. a3-dimensional array can be accessed using the methods and attributes in Table 17.

The number of dimensionsto the array:

int nDimensions = NumberOfIndices;

int nSlices = GetIndexCount(new int{});

int nRowsInSlice3 = GetIndexCount(new int{2});

int nCellsInSecondRowOfSlice3 = GetIndexCount(new int{2,1});

valueInFifthCellOfSecondRowOfSlice3 = valueSet.GetValue(new int{ 2, 1,4})

Movingon from the structure in which exchanged values, the specification will now explain the interpretation of those values, where the exchange item value indicates the movement of something, for example the flow of water, from the "source/providing"component to the "target/requesting/accepting" component.  To prevent the misunderstanding of positive and negative values, the following conventions, which are illustrated in Figure8, have been adopted:

• Values are positive if the matter leaves thesource component and enters the target component.
• The 'right-hand rule' applies for fluxes througha plane or polygon [8] .
• The direction of fluxes along a polyline isdefined as positive from the begin node to the end node.
• The 'right-hand rule' applies for fluxesperpendicular to a polyline [9].

Software developers who do not comply with these conventions should make software users aware that have adopted a differentrule..

Attributes and methods forValue Set interfaces

Requirements for Value Setinterfaces

The Argument interface

Both the adapted output and the linkablecomponent contain arguments that are used to provide information to let theadapted output do its work.  This isachieved by means of the "IArgument" interface – see Figure 9.

Attributes and methods for the Argument interface

Requirements for the Argumentinterface

Linkable Component Status

This clause should be read in conjunctionwith the information in Clause 6.9 on the Exchange Item as some componentstates, e.g. 'updating' may lead to Exchange Item Change events.

The linkable component status has twopurposes: an informative purpose (what is the component currently doing, i.e. whatstate is it in) and a control flow decision purpose.  The OpenMI explicitly specifies the possiblestates in which a linkable component can be found.  When a component moves from one status toanother, the component must raise an event through the "IBaseLinkableComponent"interface.  The "LinkableComponentStatusChangeEventArgs"class contains the information that will be passed.

Example states for a component are: created,initializing, updating, finishing and finished. The complete list of these terms forms the "LinkableComponentStatus"enumeration; explanations of the terms are given in Table 2.  Figure 10 shows the sequence in which theycan occur.  Readers will probably find ithelpful to view the diagram first.

Attributes and methods for the Linkable Component Status ChangeEvent Args class

Requirements for LinkableComponent Status

Input and output interfaces

Correctly interpreting an exchange itemvalue requires supporting information in order to understand what itrepresents, where it applies, when it applies and how it may be processed.  This information is obtained through the "IBaseExchangeItem"interface and the various interfaces that are derived from it.  Figure 12 shows schematically how theseinterfaces relate to the passage of data between two linkable components and Figure13 presents a UML diagram of the interfaces.