Copyright 2014 OpenMI Association

The companies comprising the above have granted the Open Geospatial Consortium (OGC) a nonexclusive, royalty-free, paid up, worldwide license to distribute the OpenMI Version 2.0 standard

License Agreement

Permission is hereby granted by the Open Geospatial Consortium, (“Licensor”), free of charge and subject to the terms set forth below, to any person obtaining a copy of this Intellectual Property and any associated documentation, to deal in the Intellectual Property without restriction (except as set forth below), including without limitation the rights to implement, use, copy, modify, merge, publish, distribute, and/or sublicense copies of the Intellectual Property, and to permit persons to whom the Intellectual Property is furnished to do so, provided that all copyright notices on the intellectual property are retained intact and that each person to whom the Intellectual Property is furnished agrees to the terms of this Agreement.

If you modify the Intellectual Property, all copies of the modified Intellectual Property must include, in addition to the above copyright notice, a notice that the Intellectual Property includes modifications that have not been approved or adopted by LICENSOR.

THIS LICENSE IS A COPYRIGHT LICENSE ONLY, AND DOES NOT CONVEY ANY RIGHTS UNDER ANY PATENTS THAT MAY BE IN FORCE ANYWHERE IN THE WORLD.

THE INTELLECTUAL PROPERTY IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE DO NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE INTELLECTUAL PROPERTY WILL MEET YOUR REQUIREMENTS OR THAT THE OPERATION OF THE INTELLECTUAL PROPERTY WILL BE UNINTERRUPTED OR ERROR FREE. ANY USE OF THE INTELLECTUAL PROPERTY SHALL BE MADE ENTIRELY AT THE USER’S OWN RISK. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR ANY CONTRIBUTOR OF INTELLECTUAL PROPERTY RIGHTS TO THE INTELLECTUAL PROPERTY BE LIABLE FOR ANY CLAIM, OR ANY DIRECT, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM ANY ALLEGED INFRINGEMENT OR ANY LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR UNDER ANY OTHER LEGAL THEORY, ARISING OUT OF OR IN CONNECTION WITH THE IMPLEMENTATION, USE, COMMERCIALIZATION OR PERFORMANCE OF THIS INTELLECTUAL PROPERTY.

This license is effective until terminated. You may terminate it at any time by destroying the Intellectual Property together with all copies in any form. The license will also terminate if you fail to comply with any term or condition of this Agreement. Except as provided in the following sentence, no such termination of this license shall require the termination of any third party end-user sublicense to the Intellectual Property which is in force as of the date of notice of such termination. In addition, should the Intellectual Property, or the operation of the Intellectual Property, infringe, or in LICENSOR’s sole opinion be likely to infringe, any patent, copyright, trademark or other right of a third party, you agree that LICENSOR, in its sole discretion, may terminate this license without any compensation or liability to you, your licensees or any other party. You agree upon termination of any kind to destroy or cause to be destroyed the Intellectual Property together with all copies in any form, whether held by you or by any third party.

Except as contained in this notice, the name of LICENSOR or of any other holder of a copyright in all or part of the Intellectual Property shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Intellectual Property without prior written authorization of LICENSOR or such copyright holder. LICENSOR is and shall at all times be the sole entity that may authorize you or any third party to use certification marks, trademarks or other special designations to indicate compliance with any LICENSOR standards or specifications. This Agreement is governed by the laws of the Commonwealth of Massachusetts. The application to this Agreement of the United Nations Convention on Contracts for the International Sale of Goods is hereby expressly excluded. In the event any provision of this Agreement shall be deemed unenforceable, void or invalid, such provision shall be modified so as to make it valid and enforceable, and as so modified the entire Agreement shall remain in full force and effect. No decision, action or inaction by LICENSOR shall be construed to be a waiver of any rights or remedies available to it.


 

i. Abstract

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.

ii. Keywords

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

iii. Preface

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.

iv. Submitting organizations

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

Commonwealth Scientific and Industrial Research Organization (CSIRO), Australia
OpenMI Association (OA), International

v. Submitters

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

Name Representing OGC member

Standa Vanecek

OA and DHI

No

Stef Hummel

OA and Deltares

Yes

Adrian Harper

OA and Innovyze

No

Gennadii Donchyts

OA and Deltares

Yes

Peter Gijsbers

OA and Deltares

Yes

Jesper Grooss

OA and DHI

No

Johan Hartnack

OA and DHI

No

Rob Knapen

OA and Alterra, Wageningen UR

No

Onno Roosenschoon

OA and Alterra, Wageningen UR

No

Peter Schade

OA and BAW

No

Jon Goodall

OA and University of South Carolina

No

Andrea Antonello

OA and Università di Trento/ HydroloGIS

No

Jan Gregersen

OA and HydroInform

No

Simon Cox

OA and CSIRO

Yes

Paul Cleverley

OA and HR Wallingford

Yes

Robert Szczepanek

OA and Cracow University of Technology / NT

No

Roger Moore

OA

No

David Fortune

OA and XPSolutions

No

Quillon Harpham

OA and HR Wallingford

Yes

Robert Millington

OA and Innovyze

No

David Lemon

OA and CSIRO

Yes

Andrew Hughes

OA and NERC/BGS

Yes

Bert Jagers

OA and Deltares

Yes

Michiel Blind

OA and Deltares

Yes

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.

Linkages between components and the use of adaptors
Figure : Linkages between components and the use of adaptors

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.

The OpenMI and OGC agree to pursue the following items within available resources:
  1. OpenMI and OGC will develop procedures to co=operatively share relevant standards documentation necessary for the accomplishment of objectives under this agreement. Document sharing will be limited to designated representatives of OGC and OpenMI, and will be consistent with the policies and procedures of each organization.
  2. OpenMI and OGC will work to jointly advance international consensus standards of mutual interest. A first priority will be the facilitation of OpenMI 2.0 as an open international consensus standard under the OGC process framework.
  3. OpenMI and OGC will pursue the development of use cases of critical scientific and technical interest to their respective memberships.
  4. OpenMI and OGC shall work jointly to develop architectural frameworks, extensions, ontologies, and service and model standards relevant to simulations and computational models, and their interoperability with each other and with OGC services and data models.
  5. OpenMI and OGC shall collaborate on the development and conduct of outreach activities to raise awareness within and beyond their respective communities.
  6. OpenMI and OGC shall investigate requirements and opportunities, including joint applications for funding, for advancement of model interoperability through joint testbeds, experiments, and pilot activities.
  7. The OGC will provide the OpenMI with an Associate Membership in the OGC. In return, the OpenMI will provide OGC with a complimentary membership in OpenMI. OGC membership access will be limited to no more than two members of OpenMI staff and/or Board, and two OpenMI member delegates. OGC’s membership in OpenMI will be limited to no more than two OGC staff, and two OGC member delegates.

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:

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:

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:

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:

Name Core / Extension Mandatory / Optional Clause
Requirements Class 1: Component Instantiation     #Clause 6.1
Requirement 1.1: Component Instantiation/Valid XML Core Mandatory #Clause 6.1
   
Requirements Class 2: Describable Identifiable     #Clause 6.2
Requirement 2.1: Describable Identifiable/Describable Core Mandatory #Clause 6.2
Requirement 2.2: Describable Identifiable/Identifiable Core Mandatory #Clause 6.2
   
Requirements Class 3: Value Definition     #Clause 6.3
Requirement 3.1: Value Definition/Value Definition Core Mandatory #Clause 6.3
Requirement 3.2: Value Definition/Unit Core Mandatory #Clause 6.3
Requirement 3.3: Value Definition/Quantity Core Mandatory #Clause 6.3
Requirement 3.4: Value Definition/Quality Core Mandatory #Clause 6.3
Requirement 3.5: Value Definition/Category Core Mandatory #Clause 6.3
Requirement 3.6: Value Definition/Dimension Core Mandatory #Clause 6.3
Requirement 3.7: Value Definition/Dimension Base Core Mandatory #Clause 6.3
   
Requirements Class 4: Spatial Definition     #Clause 6.4
Requirement 4.1: Spatial Definition/Spatial Definition TimeSpace Mandatory #Clause 6.4
Requirement 4.2: Spatial Definition/Element Set TimeSpace Mandatory #Clause 6.4
Requirement 4.3: Spatial Definition/Element Type TimeSpace Mandatory #Clause 6.4
   
Requirements Class 5: Temporal Definition     #Clause 6.5
Requirement 5.1: Temporal Definition/Time TimeSpace Mandatory #Clause 6.5
Requirement 5.2: Temporal Definition/Time Set TimeSpace Mandatory #Clause 6.5
   
Requirements Class 6: Value Set     #Clause 6.6
Requirement 6.1: Value Set/Base Value Set Core Mandatory #Clause 6.6
Requirement 6.2: Value Set/Time Space Value Set TimeSpace Mandatory #Clause 6.6
   
Requirements Class 7: Argument     #Clause 6.7
Requirement 7.1: Argument/Argument Core Mandatory #Clause 6.7
   
Requirements Class 8: Linkable Component Status     #Clause 6.8
Requirement 8.1: Linkable Component Status/Linkable Component Status Core Mandatory #Clause 6.8
Requirement 8.2: Linkable Component Status/Linkable Component Behaviour Core Mandatory #Clause 6.8
Requirement 8.3: Linkable Component Status/Event Status Changed Core Mandatory #Clause 6.8
   
Requirements Class 9: Exchange Item     #Clause 6.9
Requirement 9.1: Exchange Item/Base Exchange Item Core Mandatory #Clause 6.9
Requirement 9.2: Exchange Item/Base Input Core Mandatory #Clause 6.9
Requirement 9.3: Exchange Item/Base Output Core Mandatory #Clause 6.9
Requirement 9.4: Exchange Item/Time Space Exchange Item TimeSpace Mandatory #Clause 6.9
Requirement 9.5: Exchange Item/Time Space Output TimeSpace Mandatory #Clause 6.9
Requirement 9.6: Exchange Item/Time Space Input TimeSpace Mandatory #Clause 6.9
Requirement 9.7: Exchange Item/Event Exchange Item Changed Core Mandatory #Clause 6.9
   
Requirements Class 10: Adapted Output     #Clause 6.10
Requirement 10.1: Adapted Output/Base Adapted Output Core Mandatory #Clause 6.10
Requirement 10.2: Adapted Output/Times Space Adapted Output TimeSpace Mandatory #Clause 6.10
Requirement 10.3: Adapted Output/Adapted Output Factory Core Mandatory #Clause 6.10
   
Requirements Class 11: Manage State     #Clause 6.11
Requirement 11.1: Manage State/Manage State Core Optional #Clause 6.11
Requirement 11.2: Manage State/Byte State Converter Core Optional but requires the implementation of the Manage State Interface #Clause 6.11
   
Requirements Class 12: Linkable Component     #Clause 6.12
Requirement 12.1: Linkable Component/Base Linkable Component Core Mandatory #Clause 6.12
Requirement 12.2: Linkable Component/Time Space Component TimeSpace Mandatory #Clause 6.12
Requirement 12.3: Linkable Component/Time Extension TimeSpace Mandatory #Clause 6.12

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.

A graphical view of the OMI file structure
Figure : A graphical view of the OMI file structure

Requirements Class 1: Component Instantiation

/req/component-instantiation

Target type

OpenMI Component

Dependency

 

Requirement 1.1

/req/component-instantiation/ValidXML

 

Requirements for ComponentInstantiation

 

Requirement 1.1: Component Instantiation/Valid XML
/req/component-instantiation/ValidXML

An OpenMI component shall be described by a valid XML document that describes the arguments to be provided when the component is instantiated and initialized.

'Valid' means that the XML document should adhere to the XML schema definition as defined in http://www.openmi.org/schemas/v2_0/LinkableComponent.xsd , a copy of which can be found in Annex B.

 

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.

Requirements Class 2: Describable Identifiable

/req/describable-identifiable

Target type

OpenMI component

Dependency

 

Requirement 2.1

/req/describable-identifiable/IDescribable

Requirement 2.2

/req/describable-identifiable/IIdentifiable

 

UMLDiagram for IDescribable and IIdentifiable
Figure : UMLDiagram for IDescribable and IIdentifiable

Attributes and methods for Describable and Identifiable interfaces

Table : Members of the IDescribable interface
Member Notes Parameters

Caption

string

Public

Sets and returns the value of the "Caption" attribute as a string (not to be used as an identifier).

 

Description

string

Public

Sets and returns additional descriptive information about the entity.

 

 

Table : Members of the IIdentifiableinterface
Member Notes Parameters

Id

string

Public

Returns the value of the "Id" attribute as a string.  The Id must be unique within its context but does not need to be globally unique:  e.g. the Id of an input exchange item must be unique in the list of inputs of an "IBaseLinkableComponent", but an identical Id might be used by an exchange item of another "IBaseLinkableComponent".

 

 

Requirements for Describableand Identifiable interfaces

Requirement 2.1: Describable Identifiable/Describable
/req/describable-identifiable/IDescribable

An OpenMI class that represents a described entity shall implement the IDescribable interface based on the definition in Figure 3 and Table 1.

 

Requirement 2.2: Describable Identifiable/Identifiable
/req/describable-identifiable/IIdentifiable

An OpenMI class that represents an identifiable entity shall implement the IIdentifiable interface based on the definition in Figure 3 and Table 2.

 

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.

Requirements Class 3: Value Definition

/req/ value-definition

Target type

OpenMI component

Dependency

/req/describable-identifiable/IDescribable

Requirement 3.1

/req/value-definition/ IValueDefinition

Requirement 3.2

/req/value-definition/IUnit

Requirement 3.3

/req/value-definition/ IQuantity

Requirement 3.4

/req/value-definition/ IQuality

Requirement 3.5

/req/value-definition/ ICategory

Requirement 3.6

/req/value-definition/IDimension

Requirement 3.7

/req/value-definition/IDimension Base

UML Diagram for Value Definition
Figure : UML Diagram for Value Definition

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 m3/s has dimension Length3Time-1 for which the method would return 3 and ‑1.

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

Table : Base units in the OpenMI (derived from SI with an extension for currency)
Base quantity or dimension SI base unit Symbol

Length

metre (or meter (US English))

m

Mass

kilogram

kg

Time

second

s

Electric current

ampere

A

Temperature

kelvin

K

Amount of substance

mole

mol

Luminous intensity

candela

cd

Currency [6]

Euro

E

 

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

Table : Members of the IValueDefinition interface
Member Notes Parameters

MissingDataValue

Object

Public

Returns the value of the "MissingDataValue" attribute representing data that are missing.

 

ValueType

Type

Public

Returns the object types of values that will be available in the "IBaseValueSet" that is returned by the "Values" attribute and the "GetValues()" method of the "IBaseExchangeItem".

 

 

Table : Members of the IUnit interface
Member Notes Parameters

ConversionFactorToSI

double

Public

Returns the conversion factor to SI units 'A' in the expression:

SI-value = A * quantity-value + B

 

Dimension

IDimension

Public

Returns the unit's dimensions.

 

OffSetToSI

double

Public

Returns the offset to SI units 'B' in the expression:

SI-value = A * quantity-value + B

 

 

Table : Members of the IQuantityinterface
Member Notes Parameters

Unit

IUnit

Public

Returns the unit of measurement in which the quantity's values are expressed.

 

 

Table : Members of the IQuality interface
Member Notes Parameters

Categories

IList<ICategory>

Public

Returns a list of the possible category values allowed for this quality.  If the categories are not ordered, the list contains the category values in an unspecified order.  When it is ordered the list contains the category values in sequence.

 

IsOrdered

bool

Public

Returns a boolean indicating whether or not the quality is defined by an ordered set of category values.

 

 

Table : Members of the ICategory interface
Member Notes Parameters

Value

Object

Public

Returns the value for this category.

For example "blue" from the allowed set of values "red", "green" and "blue".

 

 

Table : Members of the IDimension interface
Member Notes Parameters

GetPower()

double

Public

Returns the power for the requested dimension.   For example, for a quantity such as flow, which may have the units m3/s, the "GetPower()" method must work as follows:

myDimension.GetPower(DimensionBase.AmountOfSubstance) —› returns 0

myDimension.GetPower(DimensionBase.Currency) —› returns 0

myDimension.GetPower(DimensionBase.ElectricCurrent) —› returns 0

myDimension.GetPower(DimensionBase.Length) —› returns 3

myDimension.GetPower(DimensionBase.LuminousIntensity) —› returns 0

myDimension.GetPower(DimensionBase.Mass) —› returns 0

myDimension.GetPower(DimensionBase.Temperature) —› returns 0

myDimension.GetPower(DimensionBase.Time) —› returns -1

DimensionBase[in] dimensionBase

 

 

 


 

Table : TheDimensionBase enumeration
DimensionBase Notes

Length

Public

Base dimension length.

Mass

Public

Base dimension mass.

Time

Public

Base dimension time.

ElectricCurrent

Public

Base dimension electric current.

Temperature

Public

Base dimension temperature.

AmountOfSubstance

Public

Base dimension amount of substance.

LuminousIntensity

Public

Base dimension luminous intensity.

Currency

Public

Base dimension currency.

 

Requirements for ValueDefinition interfaces

Requirement 3.1: Value Definition/Value Definition
/req/value-definition/IValueDefinition

An OpenMI class that represents a definition of values that can be exchanged between OpenMI linkable components shall be derived from the IValueDefinition interface based on the definition in Figure 4 and Table 4 and shall implement it.

 

Requirement 3.2: Value Definition/Unit
/req/value-definition/IUnit

An OpenMI class that represents a unit of a quantity shall implement the IUnit interface based on the definition in Figure 4 and Table 5.

 

Requirement 3.3: Value Definition/Quantity
/req/value-definition/IQuantity

An OpenMI class that represents a unit of a quantity shall implement the "IQuantity" interface based on the definition in Figure 4 and Table 6.

 

Requirement 3.4: Value Definition/Quality
/req/value-definition/IQuality

An OpenMI class that represents a quality shall implement the IQuality interface based on the definition in Figure 4 and Table 7.

 

Requirement 3.5: Value Definition/Category
/req/value-definition/ICategory

An OpenMI class that represents a category item of a quality shall implement the ICategory interface based on the definition in Figure 4 and Table 8.

 

Requirement 3.6: Value Definition/Dimension
/req/value-definition/IDimension

An OpenMI class that represents the dimension of a unit shall implement the IDimension interface based on the definition in Figure 4 and Table 9, and shall express the dimension as a combination of basic dimensions derived from the SI system and defined in the DimensionBase enumeration.

 

Requirement 3.7: Value Definition/Dimension Base
/req/value-definition/DimensionBase

An OpenMI class that represents the dimension of a unit shall implement the DimensionBase enumeration as specified in Table 10 and described in Table 3.

 

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.

 

Requirements Class 4: Spatial Definition

/req/ spatial-definition

Target type

OpenMI component

Dependency

 

Requirement 4.1

/req/spatial-definition/ISpatialDefinition

Requirement 4.2

/req/spatial-definition/ IElementSet

Requirement 4.3

/req/spatial-definition/ IElemetType

 

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.

UML Diagram for SpatialDefinition
Figure : UML Diagram for SpatialDefinition

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

Table : Dependencies for ISpatialDefinition
Connector Source Target Notes

Generalization

Source -> Destination

Public

IElementSet

Public

ISpatialDefinition

 

 

Generalization

Source -> Destination

Public

ISpatialDefinition

Public

IDescribable

 

 

 

Table : Members of the ISpatialDefinition interface
Member Notes Parameters

ElementCount

int

Public

Returns the number of data elements on the spatial axis, e.g. the number of points or the number of polygons.

 

SpatialReferenceSystemWkt

string

Public

Returns the "SpatialReferenceSystemWkt" which specifies the OGC ® Well Known Text representation of the spatial reference system to be used in association with the co-ordinates in the "ISpatialDefinition" interface.

For the list of WKT strings see: " http://spatialreference.org/ ".

 

Version

int

Public

Returns the version number identifying the set of spatial data that describes the current position, shape and extent of the elements in the element set.

The version must be incremented if any of the spatial data are changed.

 

 

Table : Members of the IElementSetinterface
Member Notes Parameters

ElementType

ElementType

Public

Returns the "ElementType" attribute of the element set.  All elements in the set are of this type.

 

GetElementId()

IIdentifiable

Public

Returns the Id of the "index" th element in the element set.  Indexes start from zero.  If the element type of the element set is not "IdBased", a null or an empty string may be returned.

int [in] index

The element index for which the element caption is requested.  If the element index is outside the range [0, number of elements minus 1], an exception must be thrown.

GetElementIndex()

int

Public

Returns the index of the element with the identifier "elementId" in the element set, or -1 if the Id was not found. Indexes start from zero.  There are no restrictions on how elements are ordered.

IIdentifiable [in] elementId

Identification string for the element for which the element index is requested.  If no element in the element set has the specified elementId, ‑1 must be returned.

GetFaceCount() int

Public

Returns the number of faces in a 3D element.  For 2D elements this returns 0.

 

int [in] elementIndex

Index for the element

If the element index is outside the range [0, number of elements minus 1], an exception must be thrown.

GetFaceVertexIndices()

int

Public

Returns the array of the vertex indices for a face.

Remark: The vertex indices for a face must be locally numbered for the element (containing numbers in the range [0;"GetVertexCount" (elementIndex)-1]).

int [in] elementIndex

Element index.

int [in] faceIndex

Face index.

GetVertexCount()

int

Public

Returns the number of vertices for the element specified by the "elementIndex".

If the "GetVertexCount()" method is invoked for element sets of type "IdBased", an exception must be thrown.

 

int [in] elementIndex

The element index for the element for which the number of vertices is requested.

If the element index is outside the range [0, number of elements minus 1], an exception must be thrown.

GetVertexMCoordinate()

double

Public

Returns the M co-ordinate for the vertex with VertexIndex of the element with "elementIndex".

 

int [in] elementIndex

Element index.

int [in] vertexIndex

Vertex index in the element with index "elementIndex".

GetVertexXCoordinate()

double

Public

Returns the X co-ordinate for the vertex with vertexIndex of the element with "elementIndex".

int [in] elementIndex

Element index.

int [in] vertexIndex

Vertex index in the element with index "elementIndex".

GetVertexYCoordinate()

double

Public

Returns the Y co-ordinate for the vertex with vertexIndex of the element with "elementIndex".

int [in] elementIndex

Element index.

int [in] vertexIndex

Vertex index in the element with index "elementIndex".

GetVertexZCoordinate()

double

Public

Returns the Z co-ordinate for the vertex with vertexIndex of the element with "elementIndex".

int [in] elementIndex

Element index.

int [in] vertexIndex

Vertex index in the element with index "elementIndex".

HasM

bool

Public

Returns a boolean which is true if the element set contains M co-ordinates.

 

HasZ

bool

Public

Returns a boolean which is true if the element set contains Z co-ordinates.

 


 

Table : The ElementType enumeration
ElementType Convention

IDBased

Id-based (string comparison).

Point

Geo-referenced point in the horizontal plane or in the 3-dimensional space.

PolyLine

Geo-referenced polyline connecting at least two vertices in the horizontal plane or in the 3-dimensional space.  The begin- and end-vertex indicate the direction of any fluxes.  Open entity with begin- and end-vertex not being identical.

Polygon

Geo-referenced polygons in the horizontal plane or in the 3-dimensional space.  Vertices defined anti-clockwise.  Closed entity with one face, begin- and end-vertices being identical.

Polyhedron

Geo-referenced polyhedra in 3-dimensional space.  Vertices defined anti-clockwise for each face.  Closed entity with many faces, begin- and end-vertices being identical

 

Requirements for SpatialDefinition interfaces

Requirement 4.1: Spatial Definition/Spatial Definition
/req/spatial-definition/ISpatialDefinition

An OpenMI component shall implement the ISpatialDefinition interface based on the definition in Figure 5 and Table 12.

 

Requirement 4.2: Spatial Definition/Element Set
/req/spatial-definition/IElementSet

An OpenMI component shall implement the IElementSet interface derived from ISpatialDefinition based on the definition in Figure 5 and Table 13.

 

Requirement 4.3: Spatial Definition/Element Type
/req/spatial-definition/IElementType

An OpenMI component shall implement the ElementType enumeration for the known element types as specified in Table 14.

 

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.

 

Requirements Class 5: Temporal Definition

/req/ temporal-definition

Target type

OpenMI component

Dependency

 

Requirement 5.1

/req/temporal-definition/ ITime

Requirement 5.2

/req/temporal-definition/ ITimeSet

 

UML Diagram for Temporal Definition
Figure : UML Diagram for Temporal Definition

Attributes and methods forTemporal Definition interfaces

Table : Members of the ITimeSet interface
Member Notes Parameters

HasDurations

bool

Public

Returns a boolean which is true if the "Times" have durations, i.e. are time spans.  In this case, a duration value greater than zero is expected for every "ITime" in the "Times" list.

 

OffsetFromUtcInHours

double

Public

Returns the time zone offset from UTC, expressed as the number of hours.  Because some of the world's time zones differ by half an hour from their neighbours, the value is specified as a double.

 

TimeHorizon

ITime

Public

Returns the time horizon for an input item i.e. the period of time over which it may request values.  This means that the providers of this input can assume that the input item will never request data for times earlier than the time horizon's begin time, "TimeHorizon.StampAsModifiedJulianDay".  Also, it will never request data for times after the time horizon's end time.

"TimeHorizon.StampAsModifiedJulianDay+TimeHorizon.DurationInDays".  For an output item, and thus for an adapted output item, the time horizon indicates in what time span the item can provide values.

 

Specific values:

 TimeHorizon.StampAsModifiedJulianDay  == Double.NegativeInfinity : far back in time

 TimeHorizon.Duration == Double.PositiveInfinity : far in the future.

 

Times

IList<ITime>

Public

Returns the time stamps or time spans as available in the values of an output item, or as required by an input item.

Specific values:

If for an output item  TimeSet.Times.Count == 0 , the output item is time-dependent, but there are no values available yet.

If for an input item TimeSet.Times.Count == 0, the input item is time-dependent item, but currently there are no values required yet.

 

 

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.

Table : Members of the ITime interface
Member Notes Parameters

DurationInDays

double

Public

Returns the duration in days. Zero if time is a time stamp.

 

StampAsModifiedJulianDay

double

Public

Returns a time stamp as a modified julian day value.

 

 

Requirements for TemporalDefinition interfaces

Requirement 5.1: Temporal Definition/Time
/req/temporal-definition/ITime

An OpenMI component supporting time handling shall implement the ITime interface based on the definition in Figure 6 and Table 16.

 

Requirement 5.2: Temporal Definition/Time Set
/req/temporal-definition/ITimeSet

An OpenMI component supporting time handling shall implement the ITimeSet interface based on the definition in  Figure 6 and Table 15.

 

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.

ITimeSpaceValueSet

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 ith value in that dimension of the value set corresponds to the ith 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
The number of elements for which values are returned for the first time (including missingvalue' represented by the 'missing value' value, e.g. -999):
     numElementsForFirstTime = valueSet.Values2D[0].Count
The value returned for the second time and fifth element (note the indices start at zero):
     valueForSecondTimeAndFifthElement = valueSet.Values2D[1][4]
The values for all elements for the sixth time:
     valuesForAllElementsOnSixthTime =  valueSet.Values2D[5]
The values for the fourth element for all times:
     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:

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;
The number of slices in the array:
int nSlices = GetIndexCount(new int{});
The number of rowsin slice 3 of the array:
int nRowsInSlice3 = GetIndexCount(new int{2});
The number of cellsin row2 of slice 3 of the array:
int nCellsInSecondRowOfSlice3 = GetIndexCount(new int{2,1});
The value in the 5th cell in row2 of slice 3 of the array:
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:

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

 

Requirements Class 6: Value Set

/req>value-set

Target type

OpenMI component

Dependency

 

Requirement 6.1

/req/value-set/ IBaseValueSet

Requirement 6.2

/req/value-set/ ITimeSpaceValueSet

UML Diagram for Value Set
Figure : UML Diagram for Value Set


 

Illustration of directions to interpret positive values of fluxes, levels and depths
Figure : Illustration of directions to interpret positive values of fluxes, levels and depths

Attributes and methods forValue Set interfaces

Table : Members of the IBaseValueSet interface
Member Notes Parameters

GetIndexCount()

int

Public

Returns the length (max index count) of the dimension specified by the given indices.  To obtain the size of the first dimension, use a zero-length integer array as input argument.  Length of indices must be a least one smaller than the "NumberOfIndices".

int[] [in] indices

Indices specifying the dimension whose length is to be obtained

 

GetValue()

Object

Public

Returns the value object specified by the given array of indices.  The length of the array of indices must be the equal to the number of dimensions, so that the index for each dimension is specified.  Otherwise an IllegalArgumentException must be thrown.

int[] [in] indices

Index value for each dimension

 

NumberOfIndices

int

Public

Returns the number of possible indices (dimensions) for the value set.

 

SetValue()

void

Public

Sets the value object specified by the given array of indices.  The length of the array of indices must be the equal to the number of dimensions, so that the index for each dimension is specified.  Otherwise an IllegalArgumentException must be thrown.

int[] [in] indices

Value for each dimension

Object [in] value

The value object for the given indices

ValueType

Type

Public

Returns the object type of the values that will be available in the value set that is returned by the Values attribute and the "GetValues()" method.

 

 

Table : Members of the ITimeSpaceValueSet interface
Member Notes Parameters

GetElementValuesForTime()

IList

Public

Returns values from the "Values2D" attribute, for all elements, for the specified "timeIndex".  If the data are time independent, "timeIndex" must be specified as 0.

int [in] timeIndex

GetTimeSeriesValuesForElement()

IList

Public

Returns values from the "Values2D" attribute, for all times, for the specified "elementIndex".  If the data are not related to a location, "elementIndex" must be specified as 0.

int [in] elementIndex

GetValue()

Object

Public

Returns the value for the specified "timeIndex" and "elementIndex" from "Values2D".  If the data are time independent, "timeIndex" must be specified as 0.  If the data are not related to a location, "elementIndex" must be specified as 0.

int [in] timeIndex

 

int [in] elementIndex

SetElementValuesForTime()

void

Public

Sets values for the "Values2D" attribute, for all elements, for the specified "timeIndex".  If the data are time independent, "timeIndex" must be specified as 0.

int [in] timeIndex

 

IList [in] values

SetTimeSeriesValuesForElement()

void

Public

Sets values in the "Values2D" attribute, for all times, for the specified "elementIndex".  If the data are not related to a location, "elementIndex" must be specified as 0.

int [in] elementIndex

 

IList [in] values

SetValue()

void

Public

Sets the value in the "Values2D" attribute, for the specified "timeIndex" and "elementIndex".  If the data are time independent, "timeIndex" must be specified as 0.  If the data are not related to a location, "elementIndex" must be specified as 0.

int [in] timeIndex

 

int [in] elementIndex

 

Object [in] value

Values2D

IList<IList>

Public

Returns and sets a two-dimensional list of values.  The first IList represents time, and the contained IList represents the elements in the "IElementSet".

 

 

Requirements for Value Setinterfaces

Requirement 6.1: Base Value Set
/req/value-set/IBaseValueSet

An OpenMI component shall implement the IBaseValueSet interface based on the definition in Figure 7 and Table 17.

 

Requirement 6.2: Time Space Value Set
/req/value-set/ITimeSpaceValueSet

An OpenMI component exchanging time-based data shall implement the ITimeSpaceValueSet interface based on the definition in Figure 7 and Table 18.

 

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.

Requirements Class 7: Argument

/req/ argument

Target type

OpenMI component

Dependency

/req/describable-identifiable/IIdentifiable

Requirement 7.1

/req/argument/IArgument

 


 

UML Diagram for Argument
Figure : UML Diagram for Argument

Attributes and methods for the Argument interface

Table : Members of the IArgument interface
Member Notes

DefaultValue

Object

Public

Returns the default value of the argument.

IsOptional

bool

Public

Returns whether or not the argument is optional.  If the "Values" attribute returns null and IsOptional == false, a value has to be set before the argument can be used.

IsReadOnly

bool

Public

Returns whether or not the "Values" attribute may be edited.  This is used to let an "IBaseLinkableComponent" or an "IBaseAdaptedOutput" present the actual value of an argument that cannot be changed by the user, but is needed to determine the values of other arguments or is informative in any other way.

PossibleValues

IList<Object>

Public

Returns a list of possible allowed values for this argument.  If for integral types or component specific types all possible values are allowed, null is returned.  A list with length 0 indicates that there is indeed a limitation on the possible values, but that currently no values are possible.  Effectively this means that the values will not and cannot be set.

Value

Object

Public

Returns or sets the current value of the argument.  If no value has been set yet, a default value is returned.

If null is returned, this means that the default value is null.

ValueAsString

string

Public

Returns or sets the argument's value, represented as a string.  If "ValueType" indicates that the argument's value is not of the type string, the "ValueAsString" attribute offers the possibility to treat it as a string, e.g. to let the GUI persist the value in the composition file.

ValueType

Type

Public

Returns the type of the value of the argument, e.g. an integral type such as a string, integer or double, or a non-integral type, such as a time series object.

 

Requirements for the Argumentinterface

Requirement 7.1: Argument/Argument
/req/argument/ IArgument

An OpenMI component exchanging time-based data shall implement the IArgument interface based on the definition in Figure 9 and Table 19.

 

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.

 

Requirements Class 8: Linkable Component Status

/req/ linkable-component-status

Target type

OpenMI component

Dependency

 

Requirement 8.1

/req/ linkable-component-status/LinkableComponentStatus

Requirement 8.2

/req/ linkable-component-status/LinkableComponentBehaviour

Requirement 8.3

/req/ linkable-component-status/EventStatusChanged

 

Component Status Change Diagram
Figure : Component Status Change Diagram

 

UML Diagram forLinkable Component Status
Figure : UML Diagram forLinkable Component Status

 

Table : The LinkableComponentStatus enumeration
Attribute Notes

Created

Public

The linkable component instance has just been created.  This status must and will be followed by "Initializing".

Initializing

Public

The linkable component is initializing itself.  This status will end in a status change to "Initialized" or "Failed".

Initialized

Public

The linkable component has successfully initialized itself.  The connections between its inputs/outputs and those of other components can now be established.

Validating

Public

After links between the component's inputs/outputs and those of other components have been established, the component is validating whether its required input will be available when it updates itself, and whether indeed it will be able to provide the required output during this update.  This Validating status will end in a status change to "Valid" or "Invalid".

Valid

Public

The component is in a valid state.  When updating itself the component's required input will be available, and the component will now be able to provide the required output.

WaitingForData

Public

The component wants to update itself, but is not yet able to perform the actual computation, because it is still waiting for input data from other components.

Invalid

Public

The component is in an invalid state.  When updating itself not all required input will be available, and/or it will not be able to provide the required output.  After the user has modified the connections between the component's inputs/outputs and those of other components, the "Validating" state can be entered again.

Preparing

Public

The component is preparing itself for the first "GetValues()" call.  This Preparing state will end in a status change to "Updated" or "Failed".

Updating

Public

The component is updating itself.  It has received all required input data from other components, and is now performing the actual computation.  This Updating state will end in a status change to "Updated", "Done" or "Failed".

Updated

Public

The component has successfully updated itself.

Done

Public

The last update process that the component performed was the final one.  A next call to the Update method will leave the component's internal state unchanged.

Finishing

Public

The "IBaseLinkableComponent" was requested to perform the actions to be performed before it will either be disposed or re-initialized again.  Typical actions would be writing the final result files, close all open files, free memory, etc.  When all required actions have been performed, the status switches to "Created" when re-initialization is possible.  The status switches to "Finished" when the component is to be disposed.

Finished

Public

The "IBaseLinkableComponent" has successfully performed its finalization actions.  Re-initialization of the component instance is not possible and should not be attempted.  Instead the instance should be disposed, e.g.  through the garbage collection mechanism.

Failed

Public

The linkable component has failed to initialize itself, to prepare itself for computation or to complete its update process.

 

Attributes and methods for the Linkable Component Status ChangeEvent Args class

Table : Members of the LinkableComponentStatusChangeEventArgsclass
Member Notes Parameters

LinkableComponent

IBaseLinkableComponent

Public

Returns and sets the "LinkableComponent" that raised the status change event.

 

LinkableComponentStatusChangeEventArgs()

Public

Constructor.

 

Message

string

Public

Returns and sets the "Message" attribute providing additional information on the status change.  If there is no message, an empty string is returned.

 

NewStatus

LinkableComponentStatus

Public

Returns and sets the linkable component's "NewStatus" attribute after the status changes.

 

OldStatus

LinkableComponentStatus

Public

Returns and sets the linkable component's "OldStatus" attribute thus recording its status before the status change.

 

 

Requirements for LinkableComponent Status

Requirement 8.1: Linkable Component Status/Linkable Component Status
/req/ linkable-component-status/LinkableComponentStatus

An OpenMI component shall provide its status using one of the status conditions from the LinkableComponentStatus enumeration and defined in Figure 11 and Table 20.

 

Requirement 8.2: Linkable Component Behaviour
/req/linkable-component-status/LinkableComponentBehaviour

An OpenMI component shall change its status according to the rules given in Figure 10 and Table 19.

 

Requirement 8.3: Linkable Component Status/Event Status Changed
/req/linkable-component-status/EventStatusChanged

If the implementation programming language provides an event-handling mechanism, then, when a component moves from one state to another, the component shall raise a LinkableComponentStatusChange event through the "IBaseLinkableComponent" interface.  This event shall pass the information contained in the "LinkableComponentStatusChangeEventArgs" class, as described in Figure 11 and Table 21. Error! Reference source not found.

 

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.