Use of Functions I – Basic Principles

On this page

This tutorial explains the basic principles of 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.

Model description

This example will solve the following equation system:

$\begin{align*}&x+b \cdot y = A \\&B \cdot y^2 = - a + x\end{align*}$

In this example, $A$ shall be calculated via a function:

$\begin{equation*}A = f(a, B) = 0.5 \cdot (a+B)\end{equation*}$

This function shall be implemented in MOSAICmodeling with the inputs

$\begin{equation*}m = f(o,p) = 0.5 \cdot (o+p)\end{equation*}$

Workflow

Notation of equation system

For the notation of the equation, we need to set up all base names of symbols that appear in the equations, i.e.

$a$ , parameter
$b$ , parameter
$B$ , parameter
$A$ , explicity calculable value
$x$ , iteration variable
$y$ , iteration variable

The resulting notation has ID 182652.

Equations

Next, we can define the equations of the model. Therefore, we open the equation editor, load the notation we just created, and enter the equations as stated above in the model description. The formulated equations are available with the IDs 182653 and 182654.

Notation of function

Now, we want to set up the explicit function for A. For this purpose, we set up a new notation only for this function. This is not necessary, but it illustrates how MOSAICmodeling works with different notations. In this new notation, we only define the symbols relevant for the function, i.e.

$m$ , output value
$o$ , input value 1
$p$ , input value 2

This notation has ID 182652.

Function

Now, we define the generic function, i.e., the function consisting of the variables $m$ , $o$ , and $p$ . Hence, we go to the function tab in the “Model” section and take the following steps:

Load the notation for the function
Add a description of the function
Make sure that “Free interface” and “Specify formula” are selected in the Interface & Body Settings
Go to the tab Interface Specification and click on “Output”. Enter $m$ into the popup window, click on the render button, and confirm
Click on “Input” and add the symbol o the same way as in the previous step
Repeat the last step to add the input p
Go to the tab Body Specification and enter the function body $0.5 \cdot (o + p)$ , render the formula and save the function

The function is available with ID 182656.

Equation system

Now we are able to construct our equation system:

Go to “Equation System” and load the notation for the equations
Add the two equations to your system in the Connected Elements tab
Go to the Functions tab. To use the general function created above, it must be added to the equation system and applied on the variables within this problem. In this context, applying means specifying which variable names in the equation system are supposed to be the corresponding input and output variables of the function.
Click on “Add Function” at the bottom of the screen and open your function in the opening popup window. After loading the function, you should see the expression for $m$ as a function of the inputs $o$ and $p$ . On the left hand side of the dialog, you see the Output Naming and the Input Naming as defined in the function.
On the right hand side of the dialog there is a section called Applications (Function Calls), which contains the tables Output Variable, Input Variables, and Parameters. Click on “Add Application”, which opens another popup window.
In this dialog, double click into the field Applied Naming or click on “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, render, and confirm
Double click into the table row of the variable naming o or select this row and click “Edit Input”. Again a dialog is shown in which a variable naming can be entered. Enter $a$ , render, and confirm; then repeat this step for $p$ with $B$ being the applied input
Confirm these matches at the bottom of the window. When clicking on ‘A’ in the Applications, you should now find the match of the inputs ( $o \rightarrow a$ , $p \rightarrow B$ )
Confirm in this window at the bottom and save your equation system

This equation system is available with ID 182657.

Evaluation / Simulation

Your model is now complete and you can move on to the “Simulation” section of MOSAICmodeling.

Enter a suitable description
Select the tab Equation System and load the system created in the previous steps. As there are no indices in the model, you can skip the Indexing step
Select the tab Specifications. In the list ALL VARIABLES, you will find the variables as defined in your model notation. Therein, $A$ will be of type “CALCULATED_VALUE” because it is determined by a function
Classify the variables $a$ , $b$ , and $B$ as design variables by selecting this category from the dropdown menu in the Type column. You can also assign the variables $x$ and $y$ as “ITERATION_VALUE”

Initialization and results

This simple example shall be solved with two different initial guesses for the variables x and y, which are given in Table 1. After having assigned the initial guesses and the parameter values, you can save the variable specification and then the simulation. You can find both initializations in the example folder in MOSAICmodeling:

Case 1: simulation ID 182658 with variable specification 182659
Case 2: simulation ID 182661 with variable specification 182660

The solution for both iteration variables and both cases is also given in Table 1.

Name	Description	Value / Initial guess	Solution
$a$	Parameter a	2.0
$b$	Parameter b	1.0
$B$	Parameter B	-4.0
$A$	Explicitly calculable value		Case 1: 1.5; Case 2: 1.5
$x$	Value x	Case 1: 0.0; Case 2: -0.5	Case 1: -0.25; Case 2: -2.0
$y$	Value y	Case 1: 0.0; Case 2: 0.5	Case 1: -0.75; Case 2: 1.0

Table 1: Overview of parameter values, initial guesses, and the solution for both cases.