ParameterCatalogs.adoc

@@ -10,9 +10,9 @@ image:https://mirrors.creativecommons.org/presskit/icons/by.svg[by,20]
 image:https://mirrors.creativecommons.org/presskit/icons/nc.svg[nc,20]
 image:https://mirrors.creativecommons.org/presskit/icons/nd.svg[nd,20]
 
-Non-final version: January 31, 2022.
+Non-final version: April 8th, 2022.
 
-Go to link:https://www.khbrassel.de/parametercatalogs/ParameterCatalogs.pdf[PDF-Version as of January 31, 2022]
+Go to link:https://www.khbrassel.de/parametercatalogs/ParameterCatalogs.pdf[PDF-Version as of April 8th, 2022]
 
 include::ParameterCatalogs1Overview.adoc[]
 

ParameterCatalogs2Creation.adoc

@@ -22,7 +22,7 @@ First time users of Eclipse better understand the following concepts.
 An Eclipse package is an Eclipse distribution dedicated to a specific type of task.footnote:[The notion of an Eclipse package has nothing to do with Java packages.]
 A list of packages is available at https://www.eclipse.org/downloads/packages/[eclipse.org].
 Beside others it contains _Eclipse IDE for Java Developers_, _Eclipse IDE for Scientific Computing_, and _Eclipse Modeling Tools_.
-Note that third parties offer many other packages, e.g. _GAMA_ for multi-agent-simulation or _Obeo Designer Community_ for creating diagram and form editors. This is the package we will use later.
+Note that third parties offer many other packages, e.g. _GAMA_ for multi-agent-simulation.
 
 [NOTE]
 ====
@@ -92,33 +92,27 @@ That way, we can follow the convention that local Git repositories should all be
 
 === Setup Eclipse Modeling Tools
 
-.Install Java
-
-Eclipse runs on 64-bit versions of Windows, Linux, and macOS and requires an according Java Development Kit (JDK), version 17 or higher, to be installed on your machine.
-Even if such JDK is already installed on your machine, please download the JDK version *17* for your operating system from https://adoptium.net[Adoptium].
-Installation process is straight forward, but you can also find links to exhaustive instructions for your operating system.
-
-New Java versions appear every six months, but we will stick for the coming years with version 17, since it comes with long time support (LTS).
-
-Note that different versions of Java coexist peacefully.
+.[line-through]##Install Java##
 
+Starting with version 2022-03 Eclipse packages come with a bundled Java Development Kit (JDK), version 17.
+Thus, there is no need anymore to install a JDK manually.
 
 .Install Eclipse Modeling Tools
 
 Our graphical and form based modeling tools, e.g. Insel 9.0 and Parameter Catalogs, run on top of Eclipse Sirius, an open source framework that provides a set of features and plugins that can be added to any Eclipse package to transform it into a very flexible modeling workbench.
 
-In the past, we used the pre-configured Eclipse package _Obeo Designer Community_ from https://www.obeodesigner.com[Obeo], but it wasn't updated for a while and, thus, is stucked at Java version 14.
-
-Instead, we install the Eclipse package _Eclipse Modeling Tools_ first and, then, Eclipse Sirius on top. To get current version 4.22 (2021‑12) of _Eclipse Modeling Tools_, go to https://www.eclipse.org/downloads/packages/[www.eclipse.org/downloads/packages/].
+We will install Eclipse package _Eclipse Modeling Tools_ first and, then, Eclipse Sirius on top. To get current version 4.23 (2022‑03) of _Eclipse Modeling Tools_, go to https://www.eclipse.org/downloads/packages/[www.eclipse.org/downloads/packages/].
 On this page you may see _"Try the Eclipse Installer"_ or similar.
-Do *not* follow this advice, since we want more control over what versions of Java and Eclipse shall be installed.
-Instead, look for package _Eclipse Modeling Tools_ and follow the link for your operating system and system architecture displayed on the right:
+Do *not* follow this advice, since we want more control over what will be installed.
+Instead, look for package _Eclipse Modeling Tools_ and click the download link for your operating system and system architecture displayed on the right:
 
 .Download links for Eclipse Modeling Tools package
-image::EclipseDownload.gif[EclipseDownload, 500, role="thumb"]
+image::EclipseModelingDownload.png[Eclipse Modeling Download, 500, role="thumb"]
+
+Finally, click on `Download` and wait for the 550 something MB package to arrive.
+On macOS this is a disk image file (.dmg) that is mounted by a double click. Drag and drop  `Eclipse` to folder _Applications_ and rename the copy to something more specific like `EclipseModeling2203`.
 
-Finally, click on `Download` and wait for the 450 something MB package to arrive.
-Unzip the downloaded file and possibly rename the resulting application `Eclipse` to something more specific like `EclipseModeling2112`. Then, move the application to a suited directory. This would be `Applications` on macOS, similar on Linux, but **not** `Programs` or `Programs (x86)` on Windows!
+On windows and Linux unzip/extract the downloaded file and possibly rename the resulting application to `EclipseModeling2203` or similar. Then, move the application to a suited directory, but **not** `Programs` or `Programs (x86)` on Windows!
 
 [WARNING]
 ====
@@ -154,39 +148,47 @@ Now you should see the initial window layout with _Model Explorer_ and _Outline_
 
 .Install Eclipse Sirius
 
-While package _Eclipse Modeling Tools_ already contains Sirius features that let you create graphical Ecore models, features for specifying your own forms and graphical editors are still missing. You can add these features easily from _Eclipse Marketplace_:
+While package _Eclipse Modeling Tools_ already contains Sirius features that let you create graphical Ecore models, features for specifying your own forms and graphical editors are still missing.
+You can add these features easily with Eclipse's built-in update mechanism:
 
-* Open dialog `Help -> Eclipse Marketplace...` and type _Search_ into the search field
-* Look for Sirius 6.6 or newer in the list of results and click `Install`
-* From the list of features choose `Sirius Specifier Environment` and `Sirius Support for AQL` for installation and unchoose the others (see screen shot)
-* Confirm your choice, acknowlege any licenses, and restart Eclipse when asked for.
+* Open dialog `Help -> Install New Software...` (see screenshot below)
+* For _Work with:_ choose software site `2022-03 - https://download.eclipse.org/releases/2022-03/` 
+* Deselect _Group items by category_
+* Type _Sirius_ into the search field
+* From the list of features select
+** `Sirius Properties Views - Specifier Support`
+** `Sirius Query API for AQL`
+** `Sirius Specifier Environment`
+** `Sirius Support for AQL` and click `Next >`
+* Acknowlege any licenses and restart Eclipse when asked for.
 
-.Download links for Eclipse Modeling Tools package
-image::InstallSirius.png[InstallSirius, 500, role="thumb"]
-
-Above steps added commonly used software components to your Eclipse application, publicly available in the _Eclipse Marketplace_. In the next section, however, you will add features that were created specifically for parameter catalogs and hosted at the transfer portal of _HfT Stuttgart_.
+.Install additional Sirius features
+image::InstallSiriusSpecifier.png[Install Sirius Specifier, 500, role="thumb"]
 
 
 [[quantity-plug-ins]]
 .Add Plug-ins to deal with Quantities and Units
 
+Now we use the same update mechanism to add software components that were created specifically for parameter catalogs and hosted at the transfer portal of _HfT Stuttgart_.
+
 Parameter catalogs should be able to represent quantities, not just bare numbers.
 See https://onlinelibrary.wiley.com/doi/full/10.1002/spe.2926[Unit of measurement libraries, their popularity and suitability] for a systematic account of open source solutions in the this area. 
-
 Java provides an extensive framework to deal with quantities and their units defined in https://docs.google.com/document/d/12KhosAFriGCczBs6gwtJJDfg_QlANT92_lhxUWO2gCY/edit#heading=h.6698n7erex5o[Java Specification Request (JSR) 385].
 The reference implementation for this framework is https://unitsofmeasurement.github.io/indriya/[Indriya]. Demos of its usage can be found at https://unitsofmeasurement.github.io/uom-demos/[].
 
-To make Indriya available for use in Ecore data models, the author has created two plug-ins that can easily be added to Eclipse. To do so, open dialog `Help -> Install New Software...` and enter site `https://transfer.hft-stuttgart.de/pages/neqmodplus/indriya-p2/release_target_211/` like depicted below.
+While Indriya offers all common SI units and more, the author provided additional units specific to urban simulation plus specialized Ecore types for specifying these units for attributes in Ecore data models as an Eclipse feature named _City Units_.
+
+The new types are named _Quantity_ and _TimeOfDay_.
+Some examples of valid unit symbols are listed in this https://transfer.hft-stuttgart.de/gitlab/neqmodplus/de.hft-stuttgart.cityunits[README].
 
-.Install Plug-in from Specific Update Site
-image::AddUpdateSite.png[Install Plug-in, 500, role="thumb"]
+To install _City Units_, open dialog `Help -> Install New Software...` and enter site `https://transfer.hft-stuttgart.de/pages/neqmodplus/de.hft-stuttgart.cityunits/p2repo` like depicted below.
 
-Select Indriya plug-in, press `Next >` and acknowledge all following dialogs, including security warnings.
+.Install Feature CityUnits from Update Site
+image::InstallCityUnits.png[Install Plug-in, 500, role="thumb"]
 
-Do the same for the City Units plug-in available at site `https://transfer.hft-stuttgart.de/pages/neqmodplus/de.hft-stuttgart.cityunits/release_target_110/`
-Finally, restart Eclipse to complete plug-in installation.
+Select _City Units_, press `Next >` and acknowledge all following dialogs, including security warnings.
 
-While the first plug-in installs Indriya, the second plug-in adds some specific units for urban simulation and Ecore types used for modeling quantities as attributes of classes.
+Finally, restart Eclipse to complete installation.
 
 
 === Exercise: Modeling a Parameter Catalog with Ecore
@@ -519,7 +521,7 @@ That's it for the data modeling part. By now, your Ecore model should look like
 image::Homework.png[Homework, role="thumb"]
 
 
-=== Making an Application to Create and Edit Data
+=== Making a Prototype Application to Create and Edit Data
 
 In this section you will get a glimpse on how to create an application to create and edit data conforming to the Ecore data model of our demo parameters catalog.
 
@@ -557,10 +559,10 @@ In general, it is highly recommended to resolve warnings, and errors of course,
 
 .Create a Prototype Application for Data Editing and UI Design
 
-Firstly, launch a new instance of the running _Obeo Designer_ application:
+Firstly, launch a new instance of the running _Eclipse_ application:
 
 . Execute `Run -> Run Configurations...` from the main menu and double click on _Eclipse Application_ to get a _New_configuration_. You may want to rename _New_configuration_ to _DemoCatalog_ or the like.
-. Press `Run` to start the new Eclipse application that is basically a copy of your running _Obeo Designer_ application but with a different workspace.
+. Press `Run` to start the new Eclipse application that is basically a copy of your running _Eclipse_ but with a different workspace.
 . In the new application window close the welcome screen and open the Sirius perspective using the suited button in the top right corner of the main window. This perspective provides specific Sirius menus and new project types.
 
 Secondly, create a project that will contain catalog data (remember Eclipse can only handle files that are part of a project):
@@ -660,7 +662,7 @@ But you can add new Boilers any time via command `New child -> Boiler` in the co
 Note, that you can delete boilers from the table's context menu, but currently there is no button or menu entry to create new boilers.
 Such a command would have to be described in `democatalog.odesign` first.
 
-Be aware that applications with UI design and example data launched from _Obeo Designer_ are meant to be prototypes for the final software only.
+Be aware that applications with UI design and example data launched from development environment are meant to be prototypes for the final software only.
 In fact, any saved changes in the design file are instantly reflected in the UI.
 During refinement of model and UI, data sets can be created, edited, and tested for usability without the need to built deployable software component. (On deployment, see parts _Accessing and Using Parameter Catalogs_ and _Build (Parameter Catalog) Applications with Eclipse Tycho_ below.)
 
@@ -675,7 +677,7 @@ However, since the UI is not implemented by program code, but a description in a
 === Working with Git Hosted Parameter Catalogs
 
 Ecore data models and Sirius based UI design are used to create parameter catalog software hosted in Git repositories.
-To work with these, all you need is Jave 16 and the _Obeo Designer_ with plug-ins for handling of Units installed (see <<Setup Obeo Designer>> for details.)
+To work with these, all you need is Java, _Eclipse_ with required plug-ins for Sirius and Unit handling (see <<Setup Eclipse Modeling Tools>> for details.)
 
 
 .Import Modeling Projects from Git
@@ -684,10 +686,10 @@ To connect to a Git repository open the _Import Projects from Git_ wizard via `F
 
 . Copy the URI of the git repository into the according input field, e.g.:
 https://rs-loy-gitlab.concordia.ca/parameter-catalogs-ecore/greenery-catalog.git and provide your credentials in fields _User_ and _Password_. *Tick check box _Store in Secure Store_ and provide a master password if required!* If you don't, be prepared to be prompted for your credentials over and over again
-. Click `Next >` and select a repository branch to check out, usually _master_
+. Click `Next >` and select a repository branch to check out, usually _main_ or _master_
 . Click `Next >` and choose the directory on your file system where to store the repository, e.g.
 `<user home>/git/greenery-catalog`. Here, we adhere to the convention is to have all git repositories stored in `<user home>/git/`
-. After data transfer has completed, the wizard offers to _Import existing Eclipse projects_. Click `Next >` and select the project with suffix `.model`,  `.edit` and `.editor` for import, e.g. `ca.concordia.usp.greenerycatalog.model` etc.
+. After data transfer has completed, the wizard offers to _Import existing Eclipse projects_. Click `Next >` and select the project with suffix `.design`, `.model`,  `.edit` and `.editor` for import, e.g. `ca.concordia.usp.greenerycatalog.model` etc.
 . Click `Finish`.
 
 Now you can work on the data model like you did with the demo catalog. Find it under `model` in `ca.concordia.usp.greenerycatalog.model` (compare fig. <<fig-ecore-modeling-project>>).
@@ -706,7 +708,7 @@ Simply reuse the _Run Configuration_ specified above, when starting the applicat
 Now, import the projects that contain data and UI design, respectively:
 
 . Execute `File -> Import...` for the import wizard
-. Browse to the directory containing the projects (e.g. `<user home>/git/greenery-catalog`) and check just the projects with suffixes `.data` and `.design` for import, e.g. `ca.concordia.usp.greenerycatalog.data` , `ca.concordia.usp.greenerycatalog.design`
+. Browse to the directory containing the projects (e.g. `<user home>/git/greenery-catalog`) and check just the project with suffix `.data` for import, e.g. `ca.concordia.usp.greenerycatalog.data`
 . Click `Finish`.
 
 When closing the application, it asks to store or dismiss any changes in data or UI design. You can also save these any time with `File -> Save All`.
@@ -797,7 +799,7 @@ can inform a programmer that wants to use the generated API.
 
 Congratulations on making it this far. What have we achieved?
 
-We get to know the _Obeo Designer_ IDE and created a graphical Ecore data model with one catalog class and five classes/types of domain objects therein.
+We get to know _Eclipse Modeling Tools_ and created a graphical Ecore data model with one catalog class and five classes/types of domain objects therein.
 Classes have been defined by name, attributes, and relationships between them, often with cardinalities.
 Whenever classes shared some attributes or relationships we factored these out into super classes.
 An enumeration introduced a new attribute type as a set of named values.

ParameterCatalogs3Usage.adoc

 [#using-parameter-catalogs]
 == TBD: Accessing and Using Parameter Catalogs
 
-=== Accessing XML-Catalogs from Java
+Some terminology first:
+
+- The _Urban Simulation Platform_ at CERC shall support scientists, urban planners and stake holders in performing _Urban Simulation Projects_
+- An _Urban Simulation Project_ aims at evaluating one or several _Urban Scenarios_ with respect to climate, environmental, economic and social performance.
+- An _Urban Scenario_ describes a real or envisioned _Urban Infrastructure_ in combination with a _Scenario Description_, that systematically **assigns** _Archetypes_ to the elements of an _Urban Infrastructure_ so that different policy measures, technological, environmental, social, or economic conditions can be modeled and simulated.
+- _Urban Infrastructure_ is a model of the build environment at a specific year and geographic location, embedded in a given landscape, natural and urban environment.
+- _Urban Development Scenario_ would be a series of _Urban Scenarios_ over several years that could be created manually or rule-based.
+- Abstractly, an _Archetype_ is an identifiable set of parameters for some component or system of components that should be easily/automatically be assignable to elements of an _Urban Infrastructure_. See the examples in the table below.
+
+
+.Archetypes
+[width="100%",options="header"]
+|====================
+| Archetypes for | Defined by | Identifiable and Assignable by 
+| buildings | archetypes for windows, walls, roofs, energy systems  | function, renovation state, age, geometry/size, world region/climate
+| walls, roofs | materials and sequence of material layers of certain thickness | 
+| windows | glazing number, U-value, ... |  
+|  |  |  
+|  |  |  
+| occupation | common patterns or schedules of usage of _Urban Infrastructure_ elements, e.g. buildings or roads |
+|  |  |  
+|  |  |  
+|====================
+
+- Building archetype, assignable via building function, renovation state, age, geometry/size, world region/climate: a collection of archetypes for windows, walls, roofs, energy systems 
+- Wall/Roof archetype, assignable via building archetype:  
+- Vegetation archetype, assignable via world region/climate, underground, roof/wall geometry, landscape: specific sequence of soil layers with a certain mixture of plants
+- Meteorology: Climate parameters and weather data (assignable via geographic location)
+- Energy System archetype: ?
+- Occupation archetype: Common patterns or schedules of occupation and usage of elements of the _Urban_Infrastructure, e.g. buildings or roads
+- Water tube archetype: ?
+
+Parameter catalogs provide manual and programmatic access to parameters describing general or often used components or systems of components that describe parts of an urban model (aka infrastructure data). These components or systems of components are called _archetypes_.
+
+
+=== Using Ecore Catalog Data with Java
+
+
+=== Using Ecore Catalog Data with Python
+
+To access catalog data via Python, we use PyEcore, a Python re-implementation of Ecore (see https://pyecore.readthedocs.io/en/latest/[PyEcore Documentation])
+
+While it is possible to work with an Ecore data model and according data in a purely dynamical fashion by accessing data just by name using reflection, here we prefer a "statical" approach, that generates explicit Python classes from the Ecore data model in a first step according to https://pyecore.readthedocs.io/en/latest/user/quickstart.html#static-metamodels[this part of the above documentation].
+
+After installation of the required Python libraries `pyecore` and `pyecoregen` (see documentation above), this command generates Python classes from an Ecore data model:
+
+	pyecoregen -e EnergyComponentsForPython.ecore -o .
+
+Here we assume an Ecore data model `EnergyComponentsForPython.ecore` to be located in the current directory and the output be generated in a new directory located besides the model file.
+See contents of `python` in project `/de.hftstuttgart.energycomponents.model` as an example.
+
+Note that `EnergyComponentsForPython.ecore` is different from the original `EnergyComponents.ecore` in that attribute type `Quantity` was replaced by `String` for now, since a suited Python library to represent Units and Quantites has not been choosen yet.
+
+With Python Ecore libraries and generated classes in place, according catalog data can be imported and queried like so:
+
+	from pyecore.resources import ResourceSet, URI
+	from energycomponents import EnergyComponentsCatalog
+	
+	rset = ResourceSet()
+	resource = rset.get_resource(URI('EnergyComponentsForPython.ecore'))
+	datamodel_root = resource.contents[0]
+	rset.metamodel_registry[datamodel_root.nsURI] = datamodel_root
+	
+	# At this point, the .ecore data model is loaded in 'rset'
+	
+	resource = rset.get_resource(URI('HfTStuttgart.energycomponents'))
+	catalog: EnergyComponentsCatalog = resource.contents[0]
+	
+	# Navigate data with lambdas, attributes and references
+	for res in filter(lambda chp: float(chp.electricalEfficiency) < 0.32, catalog.combinedHeatPowerUtilities):
+	    print("Efficiency of CHP", sel.modelName, "by",
+	          res.manufacturer.name, ":", res.electricalEfficiency)
+
+With `HfTStuttgart.energycomponents` as input, we get:
+
+	Efficiency of CHP GB4-8 by GIESE Energie- und Regeltechnik GmbH : 0.26
+	Efficiency of CHP Mephisto G16+ by kraftwerk Kraft-Wärme-Kopplung GmbH : 0.315
+	Efficiency of CHP M-AT 12 by Motoren AT GmbH : 0.279
+
 
 
 === Create Insel Models with Handlebars Templates
@@ -12,5 +90,4 @@
 .Creation of submodels, e.g. for computing parameterized functions
 
 
-=== Accessing XML-Catalogs from Python