Use of Functions I – Basic Principles

Stefan Kuntsche, Sanam Sabeti Adibpour

This tutorial explains how to use functions in MOSAICmodeling. Functions should be used whenever it is possible to calculate the value of a variable directly by an algebraic expression based on the values of other variables. The explanatory example will solve the following equation system:

Equation system ‘eq sys func simple’

Equations

$x+b\cdot y = A$ (1)
$B\cdot (y)^{2} = - a + x$ (2)

Function
$A=f(a,B)=0.5\cdot(a+B)$ (3)

Notation ‘nota x’

Base Names:

[table sort=”desc,asc”]
Name, Description
$a$ ,parameter a
$A$ ,parameter A
$b$ ,parameter b
$B$ ,parameter B
$x$ ,value x
$y$ ,value y
[/table]

Problem description

Design variables and the corresponding values
$a = 2.0$
$b = 1.0$
$B = -4.0$

Iteration variables initialization and expected results

[table]
,Case one, Case two
Initialization, $x=0.0$ , $x=-0.5$
, $y=0.0$ , $y=0.5$
Solution, $x=-0.25$ , $x=-2$
, $y=-0.75$ , $y=1$
[/table]

In the example given above there are two equations together with a function. Instead of introducing another equation to reflect (Eq. 1), we will create a general MOSAICmodeling function and apply it once to the equation system:

Function ‘mean value’

$m(o,p) = 0.5 \cdot (o+p)$

Notation ‘nota mean value’

Base Names:

[table sort=”desc,asc”]
Name, Description
$m$ ,mean value
$o$ ,value one
$p$ ,value two
[/table]

Creating the equations The equations are created as usual (see section Basics). The basic work flow for this is:

Create and store the notation as it is given above for the equations.

Enter the symbols specified below ‘nota x’ into this notation.

Create and store the equations (1) and (2) using the new notation.

Creating the function First the general function (3) will be created. The following steps have to be done:

Create and store the notation for the function. This notation must contain all symbols specified above ‘nota mean value’.
Select the tab Function in the Model bar.
Load the notation ‘nota mean value’ into the field named Notation.
Write some explanatory text into the Description field.
In the tab Interface & Body Settings check that Free Interface and Specify formula are selected in the comboboxes for the interface respectively body setting.
Activate the tab Interface Specification.
Click [Edit Output] or double click into the white area next to the button. A dialog window pops up where you can enter a variable naming for the output variable.
Type m into the field Tex Expression, press the render button (Shortcut: Shift+Enter), and then [OK] (Shortcut: Ctrl+Enter).
Press [Add Input] and specify the name o the same way as in the previous step.
Repeat the last step to add the output name p.
Activate the tab Body Specification.
Enter the right hand side of (3) into the Mosaic Tex field and press the render button. The string to be entered should be similar to this:

0.5 \cdot (o+p)

Save the function as ‘fun_meanValue’ to make it available in equation systems.

Creating the equation system For detailed help see section Basics. The basic work flow is:

Add the notation, here you should use the same notation as you did for the equations (‘nota x’).
Add the equations created in the previous steps.
Enter a description and save the Equation System (‘eqs_funcSimple’).

Adding and applying the function To use the general function created above, it must be added to the equation system and applied to the variables concerned. In this context, applying means specifying which variable names in the equation system are supposed to be the corresponding input and output variables.

Select the Equation System Editor in the Model Bar and open the Equation System ‘eqs_funcSimple’.
Activate the tab Functions and press [Add Function].
Take a look at the new dialog window named Add Function Usage.
In this dialog press [Select] on the upper right hand side and choose the function ‘fun_meanValue’ you created and stored previously. The field Preview should now display the function (3).
On the left hand side of the dialog you see the Output Naming and the Input Namings as they are defined in the function. The latter will be linked to the desired variable names as they appear in the equation system, the so called applied namings.
On the right hand side of the dialog there is a section called Applications (Function Calls) that contains the tables Output Variable, Input Variables, and Parameters.
Press [Add Application] within the Applications section to create a new function appliance.
Take a look at the new dialog window called Edit Function Application
In this dialog double click into the field Applied Naming or click [Edit Output] below that field. This opens another dialog where you can enter the naming of the output variable in the equation system.
Enter A into the Tex Expression area, press the render buttton (Shorcut: Shift+Enter) and then [OK] (Shortcut: Ctrl+Enter).
Double click into the table row of the variable naming o or select this row and click [Edit Input]. Again a dialog is shown where a variable naming can be entered.
Enter a similar to the previous step
In the same way specify B as the applied naming for p.
Press [OK] in the Edit Function Appliance dialog.
In the Edit Function Usage dialog the new applied Naming ‘A’ should be visible
Click on ‘A’ to show the input applications (o->a, p->B) in the tables in the Applications section.
Press [OK] in the Edit Function Usage dialog.
Save the equation system.

Evaluating the equation system

Activate the Simulation tab.
Select the tab Equation System and load the equation system ‘eqs_funcSimple’ created in the previous steps.
Select the tab Specifications. You will find that the variable named A has been automatically classified as calculated variable.
Manually classify the variables a, b, and B as design variables by moving them into the corresponding table and give them the values specified in the problem description indicated in the beginning of this section.
Enter a description and save the simulation ‘eva_funcSimple’.
Open the tab Evaluation, click [Generate Code] and then [Evaluate].
Have a look at the output of the solver given in the tab Results.