plugins/org.eclipse.app4mc.amalthea.model.help/docu/model_basics.textile

h2. Model Basics

The following classes are used all over the Amalthea model to define specific attributes of the model classes.

h3(#basics-custom-props). Custom Properties

The __CustomProperty__ element is used to define own properties that are not (yet) available in AMALTHEA. If there is the need to extend an element or to store tool information related to processing steps, __CustomProperties__ can be used to store this type of information. It also provides the possibility to work with prototypical approaches that later (if established and more stable) can be integrated in the standard model.

!../pictures/model_common_custom_property.png!

The elements are stored in a __HashMap__. The values can be of different types as shown in the structure picture, like String, Integer, Boolean...
In addition a __ReferenceObject__ is available to store own references to other __EObject__ elements.
The __ListObject__ can be used to store multi-valued custom properties and the __MapObject__ allows nested entries.

!(scale)../pictures/model_common_custom_property_value.png!


h3. Time (and Time Unit)

The AMALTHEA data model includes a common element to describe time ranges in an easy way, the __Time__ element. The __Time__ class in general allows to define negative time values. If only positive values are expected the AMALTHEA validation will show a warning.
The __Time__ element can be contained by any other element for specifying attributes to store time information.
Time units are needed to describe different timing behavior and requirements, like deadlines or offsets of components.
To support different time ranges, especially different time units, AMALTHEA predefines these types like seconds, milli-seconds, micro-seconds, nano-seconds or pico-seconds.

!(scale)../pictures/model_common_time.png!


h3. Frequency (and Frequency Unit)

!(scale)../pictures/model_common_frequency.png!


h3. Data Size (and Data Size Unit)

The  __DataSize__ (and  __DataRate__) definition contains units and prefixes
* according to the SI Standard
* for binary multiples
 <table>
 <tr>
 <th style="padding:15px">International System of Units (SI)</th>
 <th style="padding:15px">Prefixes for binary multiples</th>
 </tr>
 <tr>
 <td style="vertical-align:top; padding:15px"> 
table(classic). 
| _*Name*_ | _*Prefix*_ | _*Factor*_ |
| kilo | k | 10<sup>3</sup> |
| mega | M | 10<sup>6</sup> |
| giga | G | 10<sup>9</sup> |
| tera | T | 10<sup>12</sup> |
| _peta_ | _P_ | _10<sup>15</sup>_ |
 </td>
 <td style="vertical-align:top; padding:15px"> 
table(classic). 
| _*Name*_ | _*Prefix*_ | _*Factor*_ |
| kibi | Ki | 2<sup>10</sup> |
| mebi | Mi | 2<sup>20</sup> |
| gibi | Gi | 2<sup>30</sup> |
| tebi | Ti | 2<sup>40</sup> |
| pebi | Pi | 2<sup>50</sup> |
| _exbi_ | _Ei_ | _2<sup>60</sup>_ |
 </td>
 </tr>
 </table>

The __DataSize__ provides convenience methods to get the size also in bit and byte.
It is internally converted and can be retrieved in both ways.

!(scale)../pictures/model_common_data_size.png! 


h3. Data Rate (and Data Rate Unit)

!(scale)../pictures/model_common_data_rate.png! 


h3. Deviation

Deviations used to model constant values, histograms and statistical distributions within AMALTHEA. There is a wide variety of possible use cases, where such a distribution is needed. For example, the variation in runtime of functions can be imitated. Therefore, AMALTHEA currently supports the following statistical distributions:

!(scale)../pictures/model_common_deviations_abstract.png!

The earlier implementation used Generics to support the different use cases. To simplify the usage (via Java API and in the editor) the new implementation provides three different top level interfaces for *Time Deviation*, *Discrete Value Deviation* (integer values) and *Continuous Value Deviation* (float values). They provide specialized methods to handle their values and a common interface to access lower bound, upper bound and average.
The following image shows the detailed hierarchy of time deviations, the other implementations are built accordingly.

!(scale)../pictures/model_common_deviations_time.png!

h4. Boundaries

With the __Boundaries__ class it is possible to specify commonly used deviations (scenarios). On the one hand, the scenario specified by the minimum and maximum value between which the sampled values vary. On the other hand, the __Sampling Type__ denotes the specific scenario that is covered. These scenarios are actually defined by a Beta Distribution with preconfigured Alpha and Beta parameters. The following sampling types are available (visualized in the figures below):

- BestCase := Defines the scenario in which most instances should have runtimes close to the specified minimum runtime, but still should consider some more time-consuming outliers up to the set maximum. Alpha = 0.2; Beta = 1.
- WorstCase := Defines the scenario in which most instances should have runtimes close to the specified maximum runtime, but still should consider some less time-consuming outliers down to the set minimum. Alpha = 1; Beta = 0.2.
- AverageCase := Defines the scenario in which most instances should have runtimes close to the middle between the specified minimum and maximum, but still should consider some more or less time-consuming outliers down to the set minimum or up to the set maximum respectively. Alpha = 2; Beta = 2.
- CornerCase := Defines the scenario in which most instances should have runtimes close to the specified minimum and maximum runtime, but still should consider some other time-consuming outliers between those two. Alpha = 0.2; Beta = 0.2.
- Uniform := Defines the scenario in which all instances should have runtimes that are uniformly distributed between the specified minimum and maximum. Alpha = 1; Beta = 1.

!../pictures/model_common_deviation_boundaries_1.png!

!../pictures/model_common_deviation_boundaries_2.png!

h4. Uniform Distribution

The uniform distribution is a statistical distribution where the values between the stated lower and upper bound are equally likely to be observed.

!../pictures/model_common_deviation_uniform.png!

h4. Gaussian/Normal Distribution

The Gaussian/normal distribution is a statistical distribution where the values decrease symmetrically. The maximum value and thus its location is thereby stated by the mean and the rate of decrease is defined by its standard deviation. Since the curves approach zero on either side, an additional upper and lower bound can be added to constraint the values.

!../pictures/model_common_deviation_normal.png!

h4. Beta Distribution

The Beta distribution is a statistical distribution whose shape is defined by alpha > 0 and beta > 0. That way, the Beta distribution can also be used to model other distributions like for example uniform, normal, or Bernoulli distribution. Since the curves can approach zero or infinity on either side, an additional upper and lower bound can be added to constraint the values.

!../pictures/model_common_deviation_beta.png!

h4. Weibull Distribution

The Weibull distribution is a statistical distribution whose shape is mathematically defined by kappa > 0 and the scale of the distribution by lambda > 0. In the model, it is parameterized using the mean value, the lower and upper bound, and the probability that a real-valued random variable of that distribution will not take a value less than or equal to a specific value. To calculate the scale and shape parameter for the Weibull distribution from the model parameters, the equation of the mean ( see "Weibull distribution - Wikipedia":https://en.wikipedia.org/wiki/Weibull_distribution ) is solved for the scale parameter, first. Then, the resulting equation for lambda is plugged into the equation of the cumulative distribution function (CDF) for the Weibull distribution. Finally, the lower and upper bound allow to shift this function and the remaining unknown shape parameter in the equation is numerically approximated until the value of the parameter that constraints the distribution regarding the per mill of remaining values is reached.

!../pictures/model_common_deviation_weibull.png!

h4. Histogram

A histogram represents a distribution containing a limited number of entries (e.g. extracted from a trace). Each entry thereby is an __Interval__ with the extra attribute __occurrences__ which holds the number instances within the interval. The intervals do not have to cover a continuous range nor do they need to have the same interval size. Histograms are useful if there is a limited number of possibilities of valuations, which covers most practical systems. See the following figure for an example of two runnables having a time histogram deviation of their execution times.

!../pictures/model_common_deviation_time_histogram.png!


h3. Statistic Elements

The contained elements are representing statistical values.
The values can be set either with a min, avg and max representation using the __MinAvgMaxStatistic__ element.
The other possibility is to set a single value using the __SingleValueStatistic__ element.
The minimum and maximum values are set as a normal __int__ value,  the average the single value as __float__.

!../pictures/model_common_statistic.png!


h3(#basics-ticks). Ticks

Ticks are used to express execution times in a basic way. The number of ticks characterizes the amount of computation that is necessary to execute e.g. a __Runnable__. The corresponding execution time can be easily calculated if the frequency of the executing __ProcessingUnit__ (PU) is known.The corresponding execution time can be easily calculated if the frequency of the executing __ProcessingUnit__ (PU) is knownexecution time can be easily calculated if the frequency of the executing __ProcessingUnit__ (PU) is known. Depending on the capabilities of a PU the time to execute such an element will differ. If necessary the fundamentally different numbers for specific types of PUs can be stored as extended values in a map.

In the next picture __Ticks__ are shown in more detail.

!../pictures/model_common_ticks.png!

table(minimal){padding:10px; border:1px solid black; background:#f8f8f8}. 
|_. Name |_. Description |
| __default__| The default number of ticks. This value is used if (1) the executing PU is unknown or (2) no extended entry is available for the PU. |
| __extended__| Possibility to store a PU-specific number of ticks. |


h3. Counters

The __Counter__ element describes an activation of a target element that happens only every n<sup>th</sup> time.

table(minimal){padding:10px; border:1px solid black; background:#f8f8f8}. 
|_. Name |_. Description |
| __prescaler__ | Gives the number n for the activation,<br/>e.g. if set to 2, the target element is executed every second time. |
| __offset__ | Initial shift for the first execution of the target. |

If for example __prescaler__ is 5 and __offset__ is 2 it is executed on the 2<sup>nd</sup>, 7<sup>th</sup>, 12<sup>th</sup>, … time.

Counters are available at the following elements:

* Activity graph items:
** __ClearEvent__
** __EnforcedMigration__
** __InterProcessActivation__
** __SchedulePoint__
** __SetEvent__
** __TerminateProcess__
** __RunnableCall__
** __WaitEvent__
* Stimuli:
** __InterProcess__
** __EventStimulus__


h3. Conditions

Conditions are used to model the conditional execution of high level elements (Runnables, Stimuli) and also the repeated or conditional execution in a detailed activity graph (Switch, WhileLoop). The conditions have a predefined structure of top level disjunction (OR) with conjunctions (AND) or single conditions as contained elements. It is similar to the disjunctive normal form (DNF) of a logical formula.

!(scale)../pictures/model_common_conditions.png!

Use of common conditions:

!(scale)../pictures/model_common_conditions_references.png!