STEM Design Document

STEM Design Documentation

Overview

Overview of the design of STEM.

Standards

ISO-3166

The ISO 3166-1 Standard defines names and short alphabetic codes for "countries" and "territories" that corresponds the geopolitical divisions of the Earth. There are currently 244 such countries which is a larger number than the membership of the United Nations (191) and reflects the inclusion of territories in the mix. For instance, the standard includes the United States and Puerto Rico as separate entities. This level of representation is sometimes referred to as "United Nations Administration Level 0".

The standard defines two and three letter codes for each entry. A two letter code is referred to as an "alpha-2" code while a three letter code is an "alpha-3" code. Thus, the "ISO 3166-1 alpha-3" code for the United States is "USA" while the "ISO 3166-1 alpha-2" code is "US".

The ISO 3166-2 Standard defines names and alphabetic codes for subdivisions of countries and territories as defined in ISO 3166-1 . This level of representation is sometimes referred to as "United Nations Administration Level 1". Typically, these would be the states or provinces of a particular country. There are approximately 3700 different codes.

The ISO 3166-2 code is a compound code consisting of the ISO 3166-1 alpha-2 code of the parent country and a second country specific string separated by a hyphen. For instance, the code for the State of California in the United States of America is "US-CA". Similarly, the code for Kabul province in Afghanistan is "AF-KAB".

There is a standard called ISO 3166-3 which one might expect would provide codes for subdivisions of Level 1, but it doesn't. Instead, it defines how codes have replaced each other as political boundaries have evolved.

There is still a need in STEM to create codes that reflect Level 2 divisions (e.g., counties in the United States), STEM adopts the convention embodied in the ISO 3166-2 standard by extending the Level 1 code (e.g., "US-CA") with additional country specific identifiers separated by hyphens. In the United States, the Federal Information Processing Standard (FIPS) is the appropriate choice. It defines unique identifiers for each of the counties in the country. For instance, the FIPS code for Santa Clara County in California is "06085" (the leading "0" is significant). Thus, the "ISO" identifier used in STEM for Santa Clara County is "US-CA-06085".

In cases where the Level 2 codes for a particular country are where are known (an opportunity for an open source contribution) a special "generated" code was created with the intention that it would be replaced later by the correct code. This is the case for Afghanistan where the code for the city of Kabul was generated as "G140001" (the leading "G" identifies the code as having been generated and should be replaced when the correct code is obtained). For instance, the "ISO" code used in STEM for Kabul (the city) is "AF-KAB-G140001".

The ISO code used in STEM for a higher resolution area, such as a Census tract, would follow the same convention by appending a code to the code of the containing area separated by a hyphen. There are no such codes defined in STEM at this time.

Dublin Core Metadata

The Dublin Core Meta data standard was developed by the library science community to define a consistent set of attributes that could be attributed to a "Resource". The definition of a Resource is deliberately unspecified by the standard, but would typically be something like a book, a movie, a video, or a musical score. Most of the attributes are simple and easy to understand and basically specify familiar details of something like a book such as its "Title", its "Creator", and the "Date" it was created. The usefulness of the standard is extended by the rest of the attributes that define such things as "Spatial" characteristics, a "License" and a date range for which a Resource is valid; there are several others.

STEM makes use of the standard by incorporating it as a required feature of each composable component of the graph it uses as its representational framework for each Simulation. Thus, when a simulation is created, every component (i.e., all data and all computation) is specifically labeled and identified as to its origin and applicability.

Plug-in Descriptions

This section contains descriptions of the different plug-ins that comprise STEM.

org.eclipse.ohf.stem.core

The org.eclipse.ohf.stem.core plug-in contains the definitions and implementations of the Unified Modeling Language (UML) models that are used to represent the composable components that define a simulation in STEM. These models are Common, Graph, Model, Sequencer and Scenario. These models are implemented using the Eclipse Modeling Framework (EMF).

Common Model

Common Model UML Diagram goes here.

Describe the Dublin Core standard.

Describe how Sanity Checking works.

Graph Model

Graph Model UML Diagram goes here

Model Model

Model Model UML Diagram goes here

Sequencer Model

Sequencer Model UML Diagram goes here

Scenario Model

Scenario Model UML Diagram goes here