ParameterCatalogs3Usage.adoc

[#using-parameter-catalogs]
== TBD: Accessing and Using Parameter Catalogs

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

.Parameterization of blocks


.Creation of submodels, e.g. for computing parameterized functions