01 Background_and_Definitions.adoc

# Background and Definitions

## SimStadt

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. 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.

[#img_WFS,reftext='{figure-caption} {counter:figure-num}']
.The three components of a SimStadt Workflow Step
image::img/WFS.png[align="left"]

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_. 

[#img_UML_Ex1,reftext='{figure-caption} {counter:figure-num}']
.Example SimStadt Data Model
image::img/UML_Ex1.png[align="left"]

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 invinite 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.  

## INSEL Model