Basic modelling functions enable you to create and configure models. System dynamics modeling is basically pretty simple, so with these instructions you can build small and also very large models. The tricky part is writing all the expressions and adjusting the model so that it actually tells you something.

Creating a new model

Start a new model by right-clicking the model browser and selecting New → Model or from the main menu File → New → SD Model.

Creating a new module type

Create a new module type by right-clicking on the Modules-folder and selecting New → Module type. This creates a new module type that you can populate to your other modules and the model configuration.

Configuring a model

Model configuration can be opened by double clicking Configuration in the model browser.

Configuring modules

Configuration of a module type can be opened by double clicking the module type you want to configure. You can also open the configuration of a module from a diagram, when a module has been populated to that diagram, by right-clicking the module and selecting Show Module. When opening modules from diagram, the opened diagram knows to which diagram the module has been populated and can show the connections between the modules. Keep in mind that when making changes to a module, the changes apply to all instances of the respective module type!

Populate variables

You can drag variables to a diagram from symbol view. You can also populate variables using shortcut keys. Variables can be divided into multiple lines by resizing the variable on diagram.

Populate modules

Modules are populated from the model browser. Just drag the module you want to populate from the Modules folder to a diagram.

Create connections

There are two types of connections: dependencies and flows. Both are created basically the same way. Hold Alt down and click on a variable. Left click starts a dependency, right click starts a flow. Both are ended to another variable with a left click. Dependencies and flows can also be created without Alt key by selecting dependency or flow mode on the toolbar.

Flows can also be started and ended to an empty spot in the diagram. If there is no start or end variable, a cloud will be created. Also if start or end is not a valve, a new valve is created in the middle of the flow.

There are some restrictions on what connections can be made, but don't worry, the user interface won't let you do connections that are not allowed.

Connections between modules

Outside the module

You can connect variables to modules like this:

MODULE -----> INPUT
or
ANY VARIABLE -----> MODULE

This is just the visual configuration, but you need those connections to really connect variables in the module's properties.

In the Inputs tab stacked under Module Properties you can select which variables you connect to inputs inside the module. In the Outputs tab you can select which variables you lift from the module to inputs outside it.

Inside the module

Input variables get values from outside the module.

Output variables send their values outside the module. To make a variable output its values, from the properties view make sure the Is Output checkbox is ticked.

Configure variables

Select a single variable from diagram or model browser. The properties of the variables are shown in the properties view where you can also modify them.

Export model

To export your model to a file, select your model from the model browser, right-click and from the context menu choose Export→Model. Select the folder where to export your model, give the file a name and press Save. You do not need to export a model to Save it, the model is automatically saved in your database. Export can be used, for example, to create different versions of a model, create backups or to transport a model to another database.

Import model

Select File→Import Model, browse to your .sysdyn file and select open. The model is added to your model browser.

Export module

To export a module to a file, select the module from the model browser, right-click and from the context menu choose Export→Module. Select the folder where to export your model, give the file a name and press Save. Module export can be used, for example, to transport a module to another model or another database.

Import module

Right-click the Modules folder of a model and select Import→Module. Browse to your .sysdynModule file and select open. The module is added to your model.

Model properties can be viewed by selecting either the model or its configuration on the model browser.

Auxiliary and valve variables have two special types: WithLookup and Delay. These types are selected from Type drop down menu in the variable's properties. The variable types offer more specific functionalities than normal variables, but the same functionality could be achieved using normal variables.

Shortcut keys for configuring a model on diagram.

Other shortcut keys can be found selecting Window → Preferences from the main menu. Keys are located in General → Keys.

Unit validation is useful for finding errors in the model. Unit validation checks the consistency of units. To use this feature you need to define units for every variable used in the model. If a variable is dimensionless, use 1 as the unit. In certain constructs, a dimensionless variable can be used as "a wild card", e.g., adding a dimensionless variable with a dimensioned one is OK.

Common error sources of unit validation include the following. The respective issues are shown in the picture below.

• The equation of a variable yields a different unit than that defined for the variable.

• Two variables which have different units are added (+), subtracted (-), or compared (>, <, =, ...).

• The output unit of a function is used in an inconsistent manner. (The unit validation for the output unit of a function behaves equivalently to the unit of a variable.)

• A function is called with an argument of a prohibited unit.

• A variable has an empty unit.

• A variable has a misspelled unit.

Unit validation is enabled for a model by selecting the model or its configuration on the model browser and enabling "Validate units" on the properties tab. The unit warnings are shown on Issues view and, supposing the respective profile has been enabled, on the diagram as well. Warnings from unit validation do not prevent simulation.

For models that have stocks (i.e., integration), the simulation time unit must be selected from the pull-down menu next to the "Validate units" checkbox in Model Properties tab.

Unit validation can also cope with certain different forms of units, e.g., you can write dollars, dollar, or $ and the validator considers these equal. This functionality can be disabled from Model Properties tab checkbox "Unit equivalents".

As there may be cases for which the unit validation is for some reason not working as desired, the unitCast() function can be used in the equation of a variable to cast the unit of any expression within the equation to a wildcard. E.g., if expression

    Aux1 + time

yields a warning, it can be fixed be changing the expression to

    unitCast(Aux1) + time

in which case the unit of the expression is that of time, or to

    Aux1 + unitCast(time)

in which case the unit of the expression is that of Aux1.

Diagram profiles allow selecting which visual effects are enabled. Currently the following profiles can be used:

Default

Issue warnings

When enabled, an error or a warning symbol is attached to diagram elements in which there are errors or warnings (usually in the equations).

Shadow variable visualizations

When enabled, the original and all the shadow variables are highlighted when one is selected.

Simulation Playback

Playback Colors

When enabled, colors of the elements on diagram change during a playback experiment.

If you find yourself with a model that doesn't simulate or has bizarre behavior, there are several places to look for clues for what went wrong. Firstly, if you got an error message and can't infer the problem straight from the message, look at the issues view if it can tell you what is wrong in different words. If you know how to read Modelica code, right click Configuration under the broken model and choose Open With → Modelica Code Viewer. The tool works by generating Modelica code from the graphical model and then solving it. Therefore, if something is broken it means that there is a problem with the generated Modelica code (or, very rarely, a bug in the solver you are using). You can also refer to the list below, if you still find yourself stuck.

Some of the most common errors include:

• In a model that uses modules, you forget to connect inputs and/or outputs in the module properties

• You forgot to add an enumeration to a variable, i.e. trying to put a vector to a scalar variable (or vice versa)

• You increased the enumeration indices you are using, but forget to update a variable that depend on it

• You wrote a custom Modelica function, but it is broken

• You are comparing two numbers for equality while using OpenModelica solver (forbidden, allowed by the internal solver)

• You have a variable that refers to itself in the equation, making the solver unable find an initial value

If you are using OpenModelica solver it can be very useful to google error messages printed in the console of the tool.

Fonts and colors of diagram elements can be changed by right-clicking the element and selecting Font... The default fonts and colors for each diagram element type can be changed in Window → Preferences → Sysdyn Diagrams.

Dependency arrow properties can be changed on the property view:

Polarity

Polarity sign can be used to indicate whether the dependency increases or decreases the variable it is pointing to. The polarities serve no function for simulation, however, they are used in loop type automatic determination.

Location

Location of the polarity mark

Arrowhead

Toggle for showing arrowhead

Delay mark

Delay mark is a visual cue for helping understandability of the dynamics of the model when there are (information) delays. A delay mark is usually added to the dependency arrow when the effect the tail of the dependency has on the head of the dependency is delayed.

Line thickness

Thickness of the arrow

A loop element is a graphical component for highlighting feedback loops in a model. Usually the most interesting feedback loops that affect the behaviour of the model most are marked with a loop symbol.

Loop Items

The loop of variables which the loop symbol refers can be selected for visualization purposes.

Comment

Comment inside the loop. Usually characters 'B' and 'R' are used to denote balancing and reinforcing loops, respectfully. A feedback loop is reinforcing if and only if it has an even number of negative dependencies. Selecting 'Auto' determines automatically the type of the loop.

Direction of Rotation

Direction to which the loop rotates on diagram.

Comments are just strings of text.

There are three different ways for simulating a model. Different simulations are represented as different types of experiments in Simantics System Dynamics. Currently some of the experiment and solver combinations are still in development.

Experiments are created from the context menu of experiments folder in a model.

Double-click on an experiment activates it and displays experiment type specific controls in the main tool bar.

Normal simulation

Experiment is the basic simulation type. It simulates a model from start time to end time and results can be viewed after the simulation has been run. Works on both the internal and OpenModelica solvers.

Game simulation

Game simulations allow simulating an arbitrary number of steps, changing parameter values and continuing simulation with the new values from where it previously ended. Works on the internal solver, OpenModelica version still in development.

Simulation playback

Simulation playback works essentially as the basic experiment, but it offers some additional visualization options. Works on both solvers.

Sensitivity analysis simulation

Sensitivity analysis allows running multivariate Monte Carlo simulations with different parameter value sets and to visualize how much the simulation result depends on changes in the selected parameters. Works on OpenModelica solver, internal solver implementation still in development.

Simantics System Dynamics allows using the multiple solvers provided by OpenModelica, like Euler, Runge-Kutta, DASSL, etc. OpenModelica is currently the main simulation environment behind the tool and all functionalities are supported with OpenModelica.

Alternatively to OpenModelica, an internal custom Modelica solver is included in Simantics System Dynamics. The custom solver is currently at an experimental state, and thus all functionalities of the tool are not yet supported, e.g., only the basic experiment can be run with it. The advantage of the custom solver is, however, that simulation is usually a lot faster than with OpenModelica. Try out yourself which solver suits best for your needs.

The solver can be changed in Windows → Preferences → Solver.

Line chart shows the time series of a variable. It is capable of displaying multiple multi-dimensional variables at the same time. Simulation playback mode adds a marker to the chart to display the current time in playback simulation. Below is an example chart and its settings.

There are also configuration options for y-axis. They are displayed when an axis is selected in the Axis and variables tab.

Sensitivity chart shows the time series of a variable with confidence bounds. Below is an example chart and its settings. The general settings are defined similarly to those of a line chart explained above.

There are also configuration options for y-axis. They are displayed when an axis is selected in the Axis and variables tab.

Bar charts display variables in a certain point in time. The point can be defined for the complete chart in chart's general settings and individually for each variable in variable's settings. If no time is defined, the last simulation step is shown in game or normal simulation mode. Playback mode displays the current playback time.

Charts can be added to model diagrams simply by dragging the chart from model browser to diagram.

Pie charts display proportions of variables at a certain time. The time, similar to bar charts, can be configured for the whole chart and individually for each variable. If no time is configured, the value at the latest time step (or the time of simulation playback) is displayed.

Chart panel is able to house multiple charts at the same time. Chart panel is a normal view in the workbench, which means it can be resized and located anywhere in the workbench. Eclipse also allows detaching the tab completely from the workbench, which means that the chart panel can be dragged to another screen.

Chart panel can be either horizontally or vertically oriented. Different orientations help in configuring the workbench perspective.

Charts are added to the panel by dragging from model browser. The order of the charts is easily changed by dragging charts from their header. Charts can be minimized or completely removed from the buttons in their headers.

By default, chart panel is hidden in the upper-right corner of the system dynamics perspective.

Models with multidimensional variables look just like any other models. The structure of the models is replicated giving multiple indices to variables. For users with programming background, notation Variable may be familiar. In system dynamic modeling we need to give names to the indices. Instead of using numbers to define the indices, like in normal programming, we use enumerations. The steps to create a model with multidimensional variables are as follows (with examples):

1 Create the model structure

Model with multidimensional variables looks just like any other model.

2 Create Enumerations and define the indices

Enumerations are created by right-clicking configuration and selecting New→Enumeration.

Define enumeration indices by adding as many indices as you want. Rename the indices by selecting them and then clicking on them again.

3 Add Enumerations for variables

Select the variable that you want to be multidimensional. From the indices -tab in the property view, move the wanted enumerations to the right. The order of the enumerations does matter.

4 Define equations for all possible indices

Multidimensional variable can be thought as a multidimensional table. Each cell of the table needs to have an expression or a value. A cell cannot have multiple definitions. All cells can be defined in one expression like in the following example. E1 and E2 have both three indices, so the resulting definition can be {{1,2,3},{4,5,6},{7,8,9}}.

Values for all cells in the variable matrix can be defined in a single expression.

In many situations, it is however more clear to define separate expressions for each cell or blocks.

1 Define range for the expression

2 Define the expression (dimensions of the defined range and the result of the expression must match!)

3 Create a new expression

4 Select the new expression

Repeat until there is value for each cell. There must be exactly one value for each cell.

Many times it is useful to access a slice of a multidimensional variable. In this chapter, we will use the following example variable:

 enumeration E1 = one, two, three
 enumeration E2 = eins, zwei, drei
 Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}

The whole variable can be accessed in three different ways:

1. Auxiliary

2. Auxiliary[E1, E2]

3. Auxiliary[:, :]

The following explains different methods for accessing parts of the variable

 // Single cell
 Auxiliary[one, eins] = 1

 // Slices
 Auxiliary[one, E2] = {1,2,3}
 Auxiliary[E1, zwei] = {{2},{5},{8}}

 // In addition to single cells and the whole enumeration range, a subrange of the enumeration can be used
 Auxiliary[two : three, E2] = {{4,5,6},{7,8,9}}
 Auxiliary[one : two, zwei : drei]  = {{2,3},{5,6}}

The syntax for accessing parts of variables can be used in both expression range definitions and in expressions.

Arithmetic operations are defined in Modelica. Below are examples of different operations.

Addition and substraction

Addition and substraction are calculated elementwise

 {1,2,3} - {0,2,3} = {1,0,0}
 {{2,2},{4,4}} + {{8,8},{1,1}} = {{10,10},{5,5}}
 {1,2,3} - {1,2} = ERROR! Different array sizes

Division

Division with a scalar

 {5,10,15} / 5 = {1,2,3}
 5 / {5,10,15} = ERROR! not allowed

Division with an array

 {1,2,3} / {1,2,3} = ERROR! not allowed

 // Elementwise
 {1,2,3} ./ {1,2,3} = {1,1,1}

Multiplication

Multiplication with a scalar

 {1,2,3} * 2 = {2,4,6}
 5 * {1,2,3} = {5,10,15}

Matrix multiplication with an array

 {{3,4},{5,6}} * {1,2} = {11,17}
 {{3,4},{5,6}}  * {1,2,3} = ERROR! incompatible array sizes

 //Elementwise
 {1,2} .* {1,2} = {1,4}

 Real[3,2] c = {{1,2},{3,4},{5,6}};
 Real[2,2] d = {{3,4},{5,6}};
 Real[2,2] cd;
 cd = c[2:3, :] .* d; // Result: {{9,16},{25,36}}

Power

Elementwise power of array variable

 {1,2} .^ 2 = {1,4}

Modelica has some built-in functions that help using multidimensional variables. You can find the functions under any model inside the folder Functions→Built-in Functions. This chapter introduces some of the built-in functions.

Dimension and size functions

We will use the same example variable as previously.

 enumeration E1 = one, two, three
 enumeration E2 = eins, zwei, drei

 Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}

ndims(A)

The number of dimensions in array A

 ndims(Auxiliary) = 2

size(A, i)

The size of dimension i in array A

 size(Auxiliary, 2) = 3

size(A)

A vector of length ndims(A) containing the dimension sizes of A

 size(Auxiliary) = {3,3}

Construction functions

In addition to normal array constructing, a special construction functions can be used.

zeros(n1,n2,n3,...)

An array full of zeros with dimensions n1 x n2 x n2 x ...

 zeros(2, 2) = {{0,0}, {0,0}}

ones(n1,n2,n3,...)

An array full of ones with dimensions n1 x n2 x n2 x ...

 ones(2, 2) = {{1,1}, {1,1}}

fill(s,n1,n2,n3)

Like zeros() and ones(), but with user defined value (s) for array elements.

 fill(3,2,2) = {{3,3}, {3,3}}

identity(n)

Creates an n x n integer identity matrix with ones on the diagonal and all other elements zero.

 identity(3) =
   1 0 0
   0 1 0
   0 0 1

diagonal(v)

Constructs a square matrix with elements of vector v on the diagonal and all other elements zero.

 diagonal({1,2,3}) =
   1 0 0
   0 2 0
   0 0 3

linspace(x1,x2,n)

Constructs a Real vector from x1 to x2 with n equally spaced elements.

 linspace(2,5,4) = {2,3,4,5}

Reduction functions

Reduction functions reduce arrays to scalars.

min(A)

Returns the minimum value in array A.

 Real A = {{1,2},{3,4}}
 min(A) = 1

max(A)

Returns the maximum value in array A.

 Real A = {{1,2},{3,4}}
 max(A) = 4

sum(A)

Returns the sum of values in array A.

 Real A = {{1,2},{3,4}}
 sum(A) = 10    // 1 + 2 + 3 + 4

product(A)

Returns the product of values in array A.

 Real A = {{1,2},{3,4}}
 product(A) = 24   // 1 * 2 * 3 * 4

Using functions with iterators

Functions min(A), max(A), sum(A) and product(A) reduce arrays to scalars. When you use multidimensional variables, you will most probably like to reduce less dimensions. This can be achieved using iterators with reduction functions. The result is constructed as an array, if curly brackets {} are used to enclose the expression.

 enumeration E1 = one, two, three
 enumeration E2 = eins, zwei, drei
 Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}

 AuxiliarySum[E1] = {sum( Auxiliary[ i , E2 ] ) for i in E1} // Result: {6, 15, 24}

 /* Same as:
 {sum(Auxiliary[one, E2]), sum(Auxiliary[two, E2]), sum(Auxiliary[three, E2])}
 {sum({1,2,3}), sum({4,5,6}), sum({7,8,9})}
 */

One expression can have multiple iterators. The Modelica specification defines the following format, but it is NOT yet supported in OpenModelica:

 {sum(Array[ i, j, E3]) for i in E1, j in E2}  // Dimensions reduced from 3 to 2

To use multiple iterators, use the following format (NOTE the reversed order of iterators!):

 {{sum(Array[ i, j, E3]) for j in E2} for i in E1}  // Dimensions reduced from 3 to 2

The range doesn't have to be the whole enumeration. Subranges can also be used.

 {sum( Auxiliary[ i , eins : zwei ] ) for i in E1.one : E1.two} // Result: {3, 9}

 /* Same as
 {sum(Auxiliary[one, eins : zwei]), sum(Auxiliary[two, eins : zwei])}
 {sum({1,2}), sum({4,5})}
 */

Multidimensional variables provide multiple results for the same variable. One result for each index. The trend view clutters very quickly when you add dimensions to the variables.

The clutter can be reduced by selecting which enumeration indices are shown in charts. Select an enumeration and tick the indices that you want to show. The same settings apply to each variable that uses the enumeration. This way you can follow an interesting index throughout the model.

Replaceable enumeration inside a module

You can also use array variables inside modules. Enumeration need to be defined separately for each module type and added to all necessary variables, also inputs and outputs (see Modeling).

When defining a module, modeler may not want to restrict the size of the array variable. In many cases the same module structure could be used for both large and small arrays. For example if the module is a project, a project may have three or even twenty phases. In this case the enumerations inside modules need to be set as replaceable.

In this example, the original enumeration that the modeler used had two indices. We are using an instance of this module, but we need to use array variables that have three indices instead of two. We are using two variables and an instance of the module.

Module configuration for replacing enumerations inside the module

In the parent configuration, we have used an enumeration with three indices in the two variables.

Enumeration in the parent configuration that will replace the enumeration in the module

The replacement can be defined in the properties of the module instance. When the module instance is selected, a table with all the replaceable enumerations is shown. By clicking on the cell next to the enumeration, a drop-down box is shown with all the enumerations in the parent module. If an enumeration is selected, it will replace the enumeration inside the module during simulation. The replacement will not, however, show elsewhere in the model.

Enumeration in the parent configuration that will replace the enumeration in the module

When creating replaceable enumerations in modules, modelers need to be very careful. Direct references to single enumeration elements are not allowed, since the enumeration elements will change, if the enumeration is replaced for simulation!

You can create new functions to the Functions -folder in your model or to function library folders. Right-click on the folder and select New→Function.

Functions that can be found from Functions -folder can be used in your variable definitions.

Functions are defined using Modelica language. The variables used in the function are defined in the declaration section. Function needs an output and an arbitrary number of inputs. Modelica specification enables use of multiple outputs, but this feature is not supported. The inputs are given in the same order as they are used in calling the function.

Algorithm section defines the actual functionality of the function. In algorithm sections you must use assignments ":=" instead of just plain "=". All the assignments are calculated in the order they are written.

Also, take note that creating new lines in the Modelica code text box is done via shift+enter.

Below is an example of a simple function. For more examples, see the built-in functions provided with the tool and Modelica specifications.

Functions can be collected into libraries. This is a good way of organizing your functions. If function is located in a library, you need to append the library name to the function call (e.g. ExampleFunctionLibrary.ExampleFunction(arg1, arg2)). With libraries, you can also have functions with same names (e.g. library1.func(arg) and library2.func(arg)).

There are three types of function libraries: normal function library, built-in function library and shared function library. Normal function libraries can be created to a model and are available only in that model. Built-in libraries are available in all models and calls to built-in functions should not include the library name. Shared functions are available to all models in your workspace, but you need to enable them to each model individually.

Create a new function library by right-clicking on Functions folder, Shared functions folder or other module library.

A function library can be exported by right clicking the function library and selecting Export → Function library. A function library can be imported by right clicking the Functions folder and selecting Import → Function library. Functions themselves cannot be exported or imported. To export a function, add it into a function library and export that function library.

If you create a shared function library, the library can be added to other models or removed from current model by selecting the Shared Functions -folder and using the properties view.

Modelica allows you to use external functions that are programmed using C language. To use this feature, you need to have the Sysdyn version with OpenModelica included and OpenModelica set as the solver in the Preferences (Window → Preferences → Solver). The installation package with OpenModelica has also MinGW C compiler included that allows to build object files from C source code.

Below is a simple example of using a function that returns the sum of two arguments.

 double exampleCFunction(double x, double y)
 {
   double res;
   res = x + y;
   return res;
 }

You need to create an Object file (.o) of your code, import it to a function and define the function to use the library and function that you created. If you don’t have a C-compiler, you can use the one provided by the Simantics installation (e.g. simantics_home/plugins/org.simantics.openmodelica.win32_x/MinGW/bin/mingw32_gcc.exe -g -O -c ExampleCFunctionCode.c).

You can use the external function like any other function in your variables. Using equation ExampleExternalFunction(Stock1, 10) in an auxiliary variable (Auxiliary2) gives the following result.

In addition to .o -files, you can import .c and .h files. By including these to the function, the source code can be reviewed and later by you or others that use the function.

Small external C function can also be written directly to the function code in Simantics Sysdyn:

 function ExampleExternalFunction
 input Real x;
 input Real y;
 output Real z;
 external "C" z=exampleCFunction(x,y) annotation(Include="
 double exampleCFunction(double x, double y)
 {
   double res;
   res = x + y;
   return res;
 }");
 end ExampleExternalFunction;

Modelica has built-in functions that can be used anywhere and are not visible in function libraries. This section covers a large number of those functions. For functions related to array variables, see see Built-in functions for arrays.

Spreadsheets are an easy way to import and manage parameter values. Sheet shells can be referenced to in models with the syntax SheetName(CellReference). Below is an example of getting a value for Auxiliary. The text "Auxiliary" is not necessary in the spreadsheet, but it helps maintaining the sheet.

You can also refer to sheets with array variables. Reference is simple with one and two dimensional array variables. Below is an example of a sheet with values for two different variables. The names of the indices are not mandatory, but help reading and maintaining the sheet.

Reference to a sheet range creates an array variable.

ArrayTest2 has two dimensions. Reference to a larger range creates a two-dimensional variable. By default, the indices are ordered as in this example. However, if you wish to present the indices in a different order in the spreadsheet, you can transpose the sheet reference (e.g. transpose(ArrayTestSheet(E2:G3)))

Spreadsheets can be used to store and display external history data e.g. from some statistics. The history data should be arranged as columns or rows and include a time variable. Reference variables need to be given the exactly same name as their counterparts in model.

History data is used by creating a History dataset to an experiment. The dataset is activated and deactivated in charts by double-clicking the dataset. History data reference is set in the properties of the history dataset.

If the history dataset is activated, history data is displayed whenever it is available for a variable that is displayed in a chart.