In NeqModPlus, Simulation models will be developed using INSEL. These models shall be integrated in the Simulation Workflow SimStadt as a Workflow step. A Workflow step can be deployed as part of the SimStadt desktop workflow as well as a (Micro) Web Service. To ensure that the Workflow step is doing exactly the same in both cases, a single code base is required.
This document proposes a general conceptual approach to integrate INSEL models developed in NeqModPlus as a workflow step in SimStadt and gives some guidelines to implement this integration. In addition, some extension will be proposed to simplify the integration in future.
SimStadt is workflow management system that allows the user to define workflows with the aim of using 3D city models for urban simulations on district level and beyond. Of course, it can be used for single buildings as well, but this is not the focus of SimStadt. SimStadt itself has no simulation engine, but prepares 3D city models to be executed in an external simulation engine such as INSEL. As usual, no rule without an exception. If the simulation is rather a calculation, this calculation can be directly integrated in the workflow. An example is the DIN 18599 monthly energy balance workflow step. A Workflow in SimStadt consists of workflow steps (WFS). A particular workflow such as DIN 18599 workflow is executed in a workflow environment.
[NOTE]
The DIN 18599 workflow is the entire workflow from the CityGML model to the execution of the last workflow step, the DIN 18599 workflow step.
Currently, two workflow engine are available in SimStadt:
* SimStadt Desktop: hierarchically connection of WFS using Java streaming technology
* SimStadt Web Services: orchestration of WFS deployed as Web Services
The definition of the scope of a WFS is up to the user. Some predefined WFSs as well as some predefined workflows are available in SimStadt both in the SimStadt Desktop workflow engine and as orchestration of Web Services.
### SimStadt Workflow Step
In general, a workflow step in SimStadt consists of a functional part F, connector to workflow communication part C and a human computer interaction part HCI.
The functional part of the Workflow step encapsulates the purpose of a particular workflow step. For example, the calculation of the volume of a building happens here. The functional part has to be independend of the communication between workflow steps as well as the HCI part. Why? Because a workflow step has to have the same functionality in the SimStadt desktop application and as Web Services. In addition, the workflow can be executed as a batch process and as an interactive system.
The C part is necessary to connect the workflow step to an existing workflow in a given workflow environment. It retrieves input data that is needed to execute the functionality of the WFS, execute the functionial part of the WFS and passes the results to the next WFS. The implementation of the C part depends on the used workflow environment itself. A workflow step usually has a connector to the SimStadt desktop (SD_Connector) workflow environment as well as to the Micro Web Service (WS_Connector) workflow environment. If another workflow system such as FME shall be used, a specific connector has to be implemented.
In order to control the workflow in more detail, the C part can be configured e.q. to select the used level of detail in a multi-resolution building modeln or to exclude buildings with a small volume or unknown building function from the workflow (filter). This configuration has to be implemented in each workflow environment seperatly.
Dependencies:
* The C part executes the functional part. The C part depends on the F part, but the F part has to be independend of the C part
* The C part shall have no functionality that is relevant for the purpose of the WFS. Its purpose is to connect the functional part to a workflow in a given workflow environment.
An example of a SD_connector is given in the SimStadt documentation. The example shows an empty workflow step without any functionality. Examples of a WS_connectors are provided in the SimStadt documentation on redmine.
The HCI part is used to interactively change the configurion of the Workflow environment and a WFS if required. At the same time it displays the results of the WFS during runtime.
### SimStadt Data Model
Math: The SimStadt data model is a heterogeneous algebra.
Birkhoff and Lipson (1968) have defined a heterogeneous algebra as a system A=[Σ,F] in which
1. Σ={S~i~} is a family of non-void sets S~i~ of different types of elements, each called a _phylum_ of the algebra A. The _phyla_ S~i~ are indexed by some set I; i.e. S~i~∈Σ for i∈I (or are called by appropriate names).
2. F={f~α~} is a set of finitary operations, where each f~α~ is a mapping f~α~:S~i(1,α)~×S~i(2,α)~×⋯ ×S~i(n(α),α)~→S~r(α)~
for some non-negative integer n(α), function i~α~:k→i(k,α) from {1,2,⋯,n(α)} to I, and r(α)∈I. The operations f~α~ are indexed by some set Ω; i.e. f~α~∈F for α∈Ω (or are called by appropriate names).
Thus each operation f~α~ assigns to each n(α)-tuple (x~1~,⋯,x~n~(α) ), where x~j~∈S~i(j,α)~, some value f~α~ (x~1~,⋯,x~n(α)~ ) in S~r(α)~. The operation f~α~ is said to be n(α)-ary: unary when n(α)=1, binary when n(α)=2, ternary when n(α)=3, etc. When n(α)=0, it selects a fixed element (distinguished constant) of S~r(α)~.
An algebra which has only one phylum will be called a _homogeneous_ algebra; an algebra having more than one phylum, a _heterogeous_ algebra.
Example:
In this example, simple algebra A=[Σ,F] will be defined as a starting point of the SimStadt data model. Let S~0~ be a set of buildings, and S~1~=ℝ. For reasons of simplicity, an intuitiv understanding of _building_ is sufficient for now. It will be defined later in more detail. The phylum Σ={S~0~,S~1~} of A consists of a set of buildings and a set of real numbers.
F={f~0~,f~1~,f~2~} consists of the three operations f~0~ named buildingFactory, f~1~ named volume, and f~2~ named heatedVolume.
f~0~: → S~0~ selects a building of the set of buildings.
f~1~: S~0~ → S~1~ assigns a volume to a building in S~0~. Usually, the volume is calculated based on the solid geormetry of the building. But so far, solid geometry has not been introduced. The nice thing about math is, that the operation can still be definied, without the need to specify an algorithm to calculate the volume.
f~2~: S~0~ → S~1~ assigns a heating volume to a building in S~0~. Let’s assume that for a building b∈S~0~ the heated volume is given by the volume multiplied by a constant factor c∈S~1~,c<1: f~2~ (b)=c f~1~ (b). In SimStadt, c=0.8 is used.
As a result, we already have a first simple version of an algebra as a specification of a simple SimStadt data model.
This algebra can be implemented as a data model using UML.
A building will be implemented as a data type _Building_. The set of buildings S~0~ will be implemented by a class _BuildingCollection_ using the well know abstract data type Set. The set S~1~ will be implemented as _float_. The class _Building_ has three methods to implement the operations of F: _Building()_ to create an instance of a Building, _volume()_ to get the volume of a Building, and _heatedVolume()_ to get the heated volume of a Building. Please note that in contrast to the operations f~1~ and f~2~ the methods _volume()_ and _heatedVolume()_ do not have a building as a parameter as they operate on the specific instance of the class _Building_.
In Java, the data types Building and BuildingCollection can be implemented as classes:
[source,java]
----
class Building {
public Building() {};
public float volume() {
return …;
}
public float heatedVolume() {
return volume()*0.8;
}
}
class BuildingCollection extends Set {
}
----
Please notice that it is a simple example, and not implemented as such in the SimStadt data model. It is just an example to illustrate the relations / roles of an algebra as a mathematical concept, data types as an implementation of the algebra, and Java classes as an implementation of the data types. Algebra, data types, and Java class are similar concepts on a different level of abstraction.
The level of abstraction is similar to a mathematical function, an algorithm (implementation of a function) and Java Method (implementation of an algorithm). There are many different algorithms to implement the same mathematical function. And of course, an algorithm can be implemented by an infinite number of different implementations in Java and in other programming languages. But it is still the same algorithm. The same idea applies to data types and algebra. A data type can be implemented an infinite number of different Java classes and in other programming languages such as Fortran and C, as well as in INSEL, but it is still the same data type.
# Concept of the Integration of INSEL models into SimStadt
The main concept to integrate INSEL models into SimStadt is to introduce a SimStadt Workflow step *INSEL templater* that is able to
1. read an INSEL template
2. writes an INSEL model per feature of interest based on the INSEL template
3. executes the INSEL model
4. reads the results written by the INSEL process and maps the resulting values to the SimStadt data model
In a first prototype, the INSEL template is restricted to variables only. The feature of interest are buildings. For the implementation, the Java-Library handlebars (https://github.com/jknack/handlebars.java) has been choosen. That iomplies that a variable in the INSEL template has been encapsulated by two brackets: {{name of variable}}. To avoid an additional mapping between variables in teh INSEL template and attributes in the SimStadt data model, the names of the variables in the INSEL template have to be the same as in the SimStadt data model.
Example:
This statement in an INSEL template
[source,java]
----
{{building.yearOfConstruction}}
----
will be replaced by the value of the attribute _yearOfConstruction_ of the class _Building_ in the INSEL model by the INSEL templater Workflow step per building.
If an attribute is not set in an instance of an object in SimStadt, a default value can be defined in the template:
[source,java]
----
{{getOrDefault building.yearOfConstruction 9999}}
----
In this example, yearOf Construction is set to 9999 if not available for a specific building.
The following example shows an INSEL template that write the yearOfConstruction per building. The INSEL templater read the template and generate an INSEL model per building by replacing the variables {{building.yearOfConstruction}} and {{building.gmlId}} with the attributes of each instance of the class _Building_. The variable {{step.location}} is always replaced by the same attribute of the workflow step.
[source]
----
b 1 DO
p 1
1
{{getOrDefault building.yearOfConstruction 9999}}
1
b 2 WRITE 1.1
p 2
1
0
'{{step.location}}/OneToN-{{building.gmlId}}.txt'
'*'
----
The resulting INSEL model generated for a specific _Building_ be the workflow step may look like this:
[source]
----
b 1 DO
p 1
1
1980
1
b 2 WRITE 1.1
p 2
1
0
'./OneToN-gmlid01.txt'
'*'
----
Running this INSEL model writes a file that contains all number from 1 to the year of construction of the building. If the workflow is applied to a CityGML model with 150 _Buildings_, 150 INSEL models will be stored and executed, and the same amount of resulting files will be written.
The INSEL templater has been implemented in SimStadt as _Dynamic Template WFS_ and is available as an experimental Workflow in the current SimStadt SNAPSHOT.
