Modules of the OEO

The OEO is developed and maintained in a modular structure. The main file of the OEO, oeo.omn, imports the several module files. These imports are specified in the catalog.xml-files. Upon editing the module structure this file has to be edited, too.

The structure diagram depicts the imports (represented by arrows) and file hierarchy: starting from external imports (right hand side) to the domain specific proper oeo modules (centre) to the creation of the complete oeo.omn and full oeo.omn file (left hand side). )

Proper OEO modules

These modules are the primary editable files in which the OEO is developed. The following modules can be found in src\ontology\edits\

On the one hand, there are the content-related, i.e. domain specific, module files, which contain proper OEO classes.

• oeo-model: covers entities for models, assumptions, parameters, data, software and all the processes that transform these, including model execution and data transformation.
• oeo-physical: covers all those aspects of the world that are relevant for the energy systems domain, including physical entities such as generators, power lines, technologies, hardware, portions of matter; attributes of those, such as the energy they carry or release, whether they can be a pollutant, or their origins; representational transformations into maps and measures, such as coordinates, units, quantities; and the processes that modify the physical entities, such as energy production.
• oeo-social: covers entities that relate to people and the social, organisational and economic environment in which energy is produced and consumed, including sector, organisation, and various roles.
• oeo-sectors: contains both sector and sector division classes and individuals.
• oeo-shared: covers entities and relations needed in all of the modules mentioned above, to prevent them getting implemented multiple times. It is impored by oeo-model, oeo-social, oeo-physical and oeo-sector.
• oeo-shared-axioms: contains only axioms that are implemented across modules. It imports the above menttioned modules.

The modules oeo-shared-axioms and oeo-sectors were introduced with release 2.0.0.

In addition to the newly developed modules, there is a dedicated module only for customizations of terms from existing ontologies:

• oeo-import-edits: covers custom axioms and annotations customizing any of the "imports"-modules

Imports Modules

These modules are external ontologies or subsets of external ontologies imported in the OEO to improve compatibility with other ontologies and to not "re-invent the wheel". For more information concerning the details of each source ontology, see this wiki article.

The following modules can be found in src\ontology\imports\

⚠: Modules whichs name contains "extracted" are already based on the new structure, which supports autogeneration of these modules from their respective source ontology.

• iao-extracted.owl: a subset of the information artifact ontology containing classes to describe information artifacts
• ro-extracted.owl: a subset of the relationship ontology containing relations relevant for the OEO
• uo-extracted.owl: the unit ontology containing classes to describe units
• omo-extracted.owl: the open metadata ontology
  • related issues: https://github.com/OpenEnergyPlatform/ontology/issues/409
  • import was deleted with release 2.1.0 to avoid duplicate entities, since omo is imported into IAO

Architecture of "imports" generation and usage

The key-element of the architecture is a divide-and-conquer-approach which separates the axioms related to customization from the source ontologies original content. This concept relies on the fact that only IRIs are referenced between the modules. This means that the labels, definitions, etc. within the module can change while the interconnecting axioms remain intact, even during regeneration e.g. when pulling a new version of the source ontology.

graph LR;

subgraph "created for each <br> module to import"
TL1["📄 <br> ontologyName-extract-w-hierarchy.txt"]
TL2["📄 <br> ontologyName-extract-n-hierarchy.txt"]
end

Robot["🤖 <br> ROBOT-script"]
  
TL1-->Robot;
TL2-->Robot;

Robot -- composes --> RO

subgraph "⚙autogenerated, <br>read-only modules"
RO["🦉<br>ontologyName-extracted.owl"]
end

RO -- is annotated by --> CUS
CUS -- references IRIs of --> RO
OEO -- references IRIs of --> RO

subgraph "👤 user-editable <br> read-write modules"
    OEO["OEO-ontology"] 
    CUS["🦉<br>oeo-import-edits.owl"]
end

Loading

The ROBOT-script for generating the -extracted.owl-file can be found in src\scripts\requiredModuleName\.

All commands of the task can be run at once or either be run manually from the command-line.

Adding terms to "import"-module

In case a new term shall be added, do NOT copy the RDF manually into the module-file. Add the terms IRI simply either to …

• … moduleName-extract-w-hierarchy.txt ➔ for additions including the full hierarchy …
• … moduleName-extract-n-hierarchy.txt ➔ for additions excluding the full hierarchy …

… and run the extraction-script.

Moving terms to the oeo-import-edits.owl

Sometimes axioms or terms are placed wrongly due to user errors, as the read-only nature of the "import"-modules is not enforced, yet.

The cleanest and least error-prone way is moving the axioms in Protegé:

1. Select axiom in Protegé ①
2. Hit RIGHT-CLICK
3. Select "Move axiom(s) to ontology …" ②
4. Select oeo-import-edits from the list of ontologies.

⚠: This still has to be done for some scattered axioms from ro which reside in oeo-shared and for every newly generated or migrated "imports"-module!