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.
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.
- 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.
- 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.
- OpenMI and OGC will pursue the development of use cases of critical scientific and technical interest to their respective memberships.
- 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.
- OpenMI and OGC shall collaborate on the development and conduct of outreach activities to raise awareness within and beyond their respective communities.
- 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.
- 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:
- 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:
- An OpenMI-compliant component shall implement the mandatory 'Core' requirements according to specifications provided in this document – see Clause 6.
- 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.
- 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.
- 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.
- 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
- Documents associated with Unified Modeling Language™ (UML®), August 2011. http://www.omg.org/spec/UML/2.4.1/
- 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:
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.
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 |
Attributes and methods for Describable and Identifiable interfaces
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. |
|
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 |
|
Requirement 3.1 |
/req/value-definition/ IValueDefinition |
Requirement 3.2 |
|
Requirement 3.3 |
/req/value-definition/ IQuantity |
Requirement 3.4 |
/req/value-definition/ IQuality |
Requirement 3.5 |
/req/value-definition/ ICategory |
Requirement 3.6 |
|
Requirement 3.7 |
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.
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
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". |
|
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 |
|
Member | Notes | Parameters |
---|---|---|
Unit IUnit Public |
Returns the unit of measurement in which the quantity's values are expressed. |
|
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. |
|
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". |
|
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
|
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.
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
Connector | Source | Target | Notes |
---|---|---|---|
Generalization Source -> Destination |
Public IElementSet |
Public ISpatialDefinition |
|
Generalization Source -> Destination |
Public ISpatialDefinition |
Public IDescribable |
|
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. |
|
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. |
|
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 |
Attributes and methods forTemporal Definition interfaces
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.
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.
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.CountThe 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].CountThe 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:
- 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;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:
- 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..
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 |
Attributes and methods forValue Set interfaces
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. |
|
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 |
Attributes and methods for the Argument 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 |
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
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.