https://wiki.simantics.org/api.php?action=feedcontributions&user=Teemu+Lempinen&feedformat=atomEnd-User Wiki - User contributions [en]2024-03-28T22:03:04ZUser contributionsMediaWiki 1.30.0https://wiki.simantics.org/index.php?title=Tutorial:_Advanced_System_Dynamics_Modelling&diff=593Tutorial: Advanced System Dynamics Modelling2013-12-03T09:05:26Z<p>Teemu Lempinen: Is output location changed from additional information to equation tab</p>
<hr />
<div>In this tutorial, we are going to bild a work model with two projects and shared workforce. Both the workforce and a separate project (work) are going to be created as modules, so they can be reused several times. Actually the model doesn't limit the number of projects at all.<br />
<br />
===Creating model and modules===<br />
<br />
Let's start by creating the work model and the needed modules. First create a new model by right-clicking on the model browser and selecting New->Model. Alternatively you can select File->New Model from the main menu.<br />
<br />
Then create two new modules to your model. Right-click on the Modules folder and select New->Module. <br />
<br />
Name your model WorkModel and modules WorkforceModule and WorkModule. You can rename them by right-clicking on the item on the model browser and selecting Rename. <br />
<br />
{|<br />
|[[File:NewModel.png|none|frame|Creating a new model]]<br />
|[[File:NewModule.png|none|frame|Creating a new module]]<br />
|[[File:ModelStructure2.png|none|frame|Model after renaming]]<br />
|}<br />
<br />
===Initial configuration===<br />
<br />
[[File:TwoModules.png|right|frame|Workforce and Work modules]]<br />
We will use a top-down approach in our model, so first we will make a simple model configuration with our modules. Open our model configuration by double-clicking Configuration in your model browser. <br />
<br />
Drag one WorkforceModule and one WorkModule from your model browser to the WorkModel diagram. The modules are automatically named with a suffix number. Rename the modules to Workforce and Work1. You can rename objects on the diagram by double-clicking them or selecting them with one click and renaming them on the properties view below the diagram.<br />
<br style="clear: both" /><br />
<br />
[[File:ConfigurationStart.png|right|frame|Workforce and Work modules, first inputs and connections]]<br />
When the modules are on the diagram, we should think what values we would like to get from the modules and what values we would like to use in the modules. <br />
<br />
Workforce needs to know, how much work is required and it should provide information on how much work can be done. To provide the information on how much work can be done, we need an Input variable. Variables can be dragged to the diagram from Symbols view or by using [[System Dynamics Modelling#Shortcut and control keys|shortcut keys]] (Shift+I for Input variable). Drag an input variable to the diagram and name it TotalPossibleWorkingSpeed.<br />
<br />
Work module on the other hand provides information on how much work is required in it and it needs to know when the work has to be ready. Create an input variable RequiredWorkingSpeed1 and an Auxiliary variable Work1CompletionTime and place all variables like in the picture on the right. <br />
<br />
Connect the variables to modules using dependency connections (arrows). Connections are created by holding down Alt key and first clicking on the variable where to start the connection and then clicking on the variable where to end.<br />
<br />
Now we have the initial idea of the model, so let's configure the modules.<br />
<br style="clear: both" /><br />
<br />
===Workforce module===<br />
<br />
[[File:NetResourcing1.png|right|frame|Cloud, Valve, Flow and Stock]]<br />
Open Workforce module by selecting it from the diagram, right-clicking it and selecting Show Module.<br />
<br />
Create a Stock variable and name it WorkforceStock. Stock variables are created the same way as Input and Auxiliary variables. The level of the stock is controlled with a valve and a flow. To create the flow, hold down Alt and right-click on an empty space left of the stock. Then left-click on the stock. A cloud, valve and a flow is created. Rename the valve to NetResourcing.<br />
<br style="clear: both" /><br />
[[File:NetResourcing2.png|right|frame|Cloud, Valve, Flow and Stock. Flow works both on directions.]]<br />
NetResourcing works both ways. To display this also visually, delete the cloud by selecting it and pressing delete on your keyboard. Then create a flow starting from NetResourcing valve and ending on an empty space next to it.<br />
<br style="clear: both" /><br />
<br />
[[File:WorkforceAuxiliaries.png|right|frame|Auxiliaries in Workforce module]]<br />
Now you have used all the basic components and connections. From now on the instructions will be a more simplified.<br />
<br />
Next we will create four Auxiliary variables: TimeToAllocateResources, WorkforceRequired, Productivity and PossibleWorkingSpeed. Place and connect them according to the picture on the right.<br />
<br />
To be able to simulate the model, all variables must have valid equations. To configure an equation, select a variable. Variable's properties are shown in the Property view and you can input the required equations in the text fields. You can copy the equations directly from here or type them manually. Variables connected to the selected variable are shown in the Variables list. To speed up typing, you can double click on a variable name and it will be inserted to the equation.<br />
<br />
WorkforceStock <br /><br />
Initial value: 0<br />
<br />
NetResourcing <br /><br />
= (WorkforceRequired - WorkforceStock)/TimeToAllocateResources<br />
<br />
TimeToAllocateResources <br /><br />
= 2<br />
<br />
Productivity <br /><br />
= 1<br />
<br />
PossibleWorkingSpeed <br /><br />
= WorkforceStock * Productivity<br /><br />
Is Output<br />
<br />
Variables can be set as output by selecting Is Output option from the Equation tab. <br />
<br />
<br style="clear: both" /><br />
[[File:RequiredWorkingSpeedInput.png|right|frame|RequiredWorkingSpeedInput]]<br />
On a previous phase, we wanted to give the value of RequiredWorkingSpeed1 to this workforce module. To get that value, we need to create an input. Create input RequiredWorkingSpeedInput, connect it to WorkforceRequired and write the following equation to WorkforceRequired.<br />
<br />
WorkForceRequired <br /><br />
= RequiredWorkingSpeedInput/Productivity<br />
<br />
Now this module is ready to be used as a part of the model.<br />
<br />
<br style="clear: both" /><br />
<br />
===Work module===<br />
<br />
[[File:WorkStocks.png|right|frame|Basic work with errors]]<br />
Open Work1 module by selecting it from the WorkModel diagram, right-clicking it and selecting Show Module. Alternatively you can double click Work1 on the model browser.<br />
<br />
Create the basic flow of work with stocks and flows like in the picture on the right. <br />
<br />
The idea of the model is that first there is work. Work is done at a certain speed. When working, errors are also made. When errors are found, the amount of Errors is reduced, errors are removed from WorkDone and moved back to WorkToDo.<br />
<br />
<br style="clear: both" /><br />
<br />
<br />
[[File:ProjectIsReady.png|right|frame|Smoothener for work is done]]<br />
Work needs to be stopped when the project is ready. Since the simulator might face some difficulties to determine the projects readyness when project is almost ready, we need to implement some smoothing to the limit. OpenModelica doesn't yet have a builtin function for smoothing, so we need to implement our own. Create variables and connections according to the picture on the right.<br />
<br />
Use the following equations for variables:<br />
<br />
ProjectIsReady <br /><br />
Initial value: 0<br />
<br />
ProjectReadyness <br /><br />
= (xidz(WorkDone, ProjectWorkAmount, 0.0) - ProjectIsReady) / 0.08<br />
<br />
xidz is short for function X if devided by zero. This means that the simulation calculates ''WorkDone / ProjectWorkAmount''. If ProjectWorkAmount is zero, the result is the third argument ''0.0''.<br />
<br />
[[File:ProjectWorkAmount.png|right|frame|ProjectWorkAmount input variable]]<br />
As you can see, ProjectWorkAmount is highlighted. Your model doesn't contain such variable and it is not connected to ProjectReadyness. Create an Input variable ProjectWorkAmount with default value 1000 and connect it to ProjectReadyness. The reason we are using input variable is that you can determine the default size of a project, but if you want to change it, you can change it from outside the module. <br />
<br />
<br style="clear: both" /><br />
<br />
[[File:ErrorsVariables.png|right|frame|Variables needed for error handling]]<br />
Next we need to define how errors are found. For that we need new variables: WorkQuality and ErrorsFoundTime. Create the variables and connections according to the picture and give variables their equations.<br />
<br />
ErrorsGenerated<br /><br />
= (1-WorkQuality) * WorkingSpeed<br />
<br />
ErrorsFoundRate<br /><br />
= Errors/ErrorsFoundTime<br />
<br />
WorkQuality<br /><br />
= 0.9<br />
<br />
ErrorsFoundTime<br /><br />
Type: WithLookup<br /><br />
With Lookup: xidz(WorkDone, ProjectWorkAmount, 0.0) <br /><br />
Lookup table: {{0,5},{0.5,3},{1,0.5},{2,0.5}}<br />
<br />
WithLookup is a variable type where the value is interpolated from a 2-dimensional table (Lookup table) using the value determined in the "With Lookup" field. Type can be changed from the drop-down menu Type.<br />
<br />
<br style="clear: both" /><br />
<br />
[[File:WorkAllocation.png|right|frame|WorkAllocation and RequiredWorkingSpeed]]<br />
To calculate our own need for workforce we need to create and connect WorkCompletionTime input variable and the following auxliary variables:<br />
<br />
RequiredWorkingSpeed <br /><br />
= if ProjectIsReady < 1 then xidz(WorkToDo, TimeToDeadline, MaximumWorkingSpeed) else 0<br /><br />
Is Output<br />
<br />
MaximumWorkingSpeed <br /><br />
= 500<br />
<br />
TimeToDeadline <br /><br />
= max(0, WorkCompletionTime-time)<br />
<br />
time is a universal variable that gives the current simulation time.<br />
<br />
<br />
We need to decide how the workforce is allocated between all the work modules that are using the same workforce. For that we need to know how much work can be done and how much workforce other works require. <br />
<br />
Create two Inputs, RequiredWorkingSpeedTotalInput and PossibleWorkingSpeedInput, and an auxiliary variable WorkAllocation. Connect the variables like int the picture.<br />
<br />
WorkAllocation<br /><br />
= xidz(RequiredWorkingSpeed, RequiredWorkingSpeedTotalInput, 0.0) * PossibleWorkingSpeedInput<br />
<br style="clear: both" /><br />
<br />
Finally let's give initial values for all the remaining variables:<br />
<br />
WorkingSpeed <br /><br />
= if ProjectIsReady < 1 then WorkAllocation else 0<br />
<br />
WorkToDo <br /><br />
Initial value: ProjectWorkAmount<br />
<br />
WorkDone <br /><br />
Initial value: 0<br />
<br />
Errors <br /><br />
Initial value: 0<br />
<br />
===Connecting modules===<br />
<br />
Our modules are complete. Let's get back to the WorkModel Configuration. <br />
<br />
Set Work1CompletionTime to 10.<br />
<br />
[[File:ModuleConnections1.png|right|frame|Module input connections]]<br />
Connections between modules are made in the properties of the module. Select Work1 and open tab Inputs from the properties. The table lists all input variables in the module that are available. Clicking on the Refers to output column will open a drop-down menu that shows all available variables that are connected to the module. By selecting a variable, you connect that variable to the input.<br />
<br style="clear: both" /><br />
<br />
[[File:RequiredWorkingSpeed1Connection.png|right|thumb|Connection from RequiredWorkingSpeed to Work1]]<br />
[[File:ModuleConnections2.png|right|frame|Module input connections]]<br />
Work1 need also information on how much working speed is required by all works. Since Work1 is the only work, create a dependency connection from RequiredWorkingSpeed1 to Work1 and in Work1's properties connect it to RequiredWorkingSpeedTotalInput. <br />
<br style="clear: both" /><br />
<br />
In Outputs tab, make the only possible connection: from RequiredWorkingSpeed to RequiredWorkingSpeed1.<br />
<br />
Workforce module has only one input and one output. Create the only possible connections:<br /><br />
(Inputs) RequiredWorkingSpeedInput -> RequiredWorkingSpeed1<br /><br />
(Outputs) PossibleWorkingSpeed -> TotalPossibleWorkingSpeed<br />
<br />
Now your model is ready for simulation!<br />
<br />
===Simulating the model===<br />
<br />
To make the simulation time longer, select Configuration on the model browser. Give the model Stop time 24.0<br />
<br />
[[File:ActivateExperiment.png|right|frame|Experiment activation]]<br />
To run simulations, you must activate an experiment. Expand the experiments folder on your model browser. There is one ready-made experiment. Double click on the experiment and the experiment control buttons appear on the toolbar. Press the play button [[File:ExperimentPlay.png]].<br />
<br />
System shows the simulation progress in the progress bar on the lower right corner of the screen. <br />
<br />
[[File:SimulationProgress.png]]<br />
<br />
When the progress indicator disappears, the simulation is complete.<br />
<br />
If the Console view pops up and shows an error "Error: Too few equations, underdetermined system. The model has X equation(s) and Y variable(s)", the simulation has failed. The reason might be that you forgot to assign an equation to some variable or some connection in modules. See through all the variables, write the missing equation and simulate again.<br />
<br />
After the simulation is succesfully run, you can select a variable and see its simulation results in the trend view. For example WorkDone variable in Work1 module will give the following graph.<br />
<br />
[[File:FirstSimulation.png]]<br />
<br />
<br style="clear: both" /><br />
<br />
===Adding modules===<br />
<br />
[[File:ModulesFinal.png|right|frame|Final configuration with two modules]]<br />
We created the WorkModule to be reusable. To use two WorkModules in the model, you must do the following.<br />
<br />
Populate a second WorkModule to WorkModel configuration and name it Work2. <br />
<br />
Create RequiredWorkingSpeed2 input variable and Work2CompletionTime auxiliary variable.<br />
<br />
We need a sum of all working speed requirements to give to the work modules. For this purpose, create an auxiliary variable RequiredWorkingSpeedTotal which sums the requirements.<br />
<br />
You can also have a different size work. To make Work2 smaller, create an auxiliary variable Work2Amount.<br />
<br />
Use the following equations:<br />
<br />
Work2CompletionTime<br /><br />
= 13<br />
<br />
Work2Amount<br /><br />
= 800<br />
<br />
RequiredWorkingSpeedTotal<br /><br />
= RequiredWorkingSpeed1 + RequiredWorkingSpeed2<br />
<br />
Update connections to match connections shown in the picture and connect the inputs and outputs to the modules.<br />
<br />
Workforce<br /><br />
RequiredWorkingSpeedInput -> RequiredWorkingSpeedTotal<br />
<br />
Work1 Inputs<br /><br />
RequiredWorkingSpeedTotalInput -> RequiredWorkingSpeedTotal<br />
<br />
Work2 Outputs<br /><br />
RequiredWorkingSpeed -> RequiredWorkingSpeed2<br />
<br />
Work2 Inputs<br /><br />
[[File:Module2Inputs.png]]<br />
<br />
<br />
When all the connections are made, you can simulate the model again. Now you have model with two work modules. Select variables from both modules in model browser to display them in trend view.<br />
<br />
[[File:SecondSimulation.png]]<br />
<br />
<br style="clear: both" /><br />
<br />
<!---<br />
Operating interfaces not supported right now<br />
===Creating an Operating Interface===<br />
<br />
[[File:NewOperatingUI.png|right|frame|New Operating UI]]<br />
To use the model and adjust its parameters without seeing the actual model, we can use Operating interfaces. Create a new operating interface by right-clicking Operating interfaces on the model browser and selecting New -> Operating UI. Double click the created operating ui to open it.<br />
<br />
Switch to Symbols view. WidgetLibrary shows all the widgets that can be used when creating an operating interface. We will create a simple interface with a trend and two sliders. <br />
<br style="clear: both" /><br />
<br />
[[File:FirstOUI.png|right|frame|Operating UI with a trend and two sliders]]<br />
Drag a trend to the diagram. Adjust the size of the trend so that it is larger. The size of the elements can be adjusted by first selecting the element and then draggign from the lower right corner of the element.<br />
<br />
Then drag two sliders to the right side of the trend.<br />
<br />
Now you should have an operating user interface that looks something like the picture on the right.<br />
<br />
To be able to use the interface, we need to configure the elements and connect them to the actual variables on the model. First let's configure the sliders.<br />
<br />
We are going to adjust the time when Work1 and Work2 are ready. Our simulation time ranges from 0 to 24, so that is the range that we are going to use in our sliders. Select one of the sliders. The Property view shows all the different properties that can be configured in the element. Do the following settings for both sliders:<br />
<br />
[[File:SliderProperties.png|none|frame|Slider properties]]<br />
<br />
Then select the trend element. Set its Title to "Work1 and Work2" and Y-Axis Label to "Work Done"<br />
<br />
Now we need to connect the actual variables to the elements. From Model Browser, drag Work1CompletionTime to the first slider and Work2CompletionTime to the second slider.<br />
<br />
Then from each of the Work module, drag WorkDone to the trend element.<br />
<br />
Activate an experiment by double clicking it, activate the Operating UI by clicking it and switch it to operating mode with the switch button [[File:OperatingModeSwitch.png]] on the main toolbar.<br />
<br />
Run a simulation. The trend element should show the results of the simulation. Adjust the completion times from the sliders and simulate again.<br />
<br />
[[File:OperatingUI.png|none|frame|Ready Operating interface]]<br />
<br />
<br style="clear: both" /><br />
<br />
--><br />
<br />
<br />
[[Category:Tutorials]]</div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=Simantics_End_User_Documentation&diff=592Simantics End User Documentation2013-06-12T12:48:43Z<p>Teemu Lempinen: </p>
<hr />
<div>__NOTOC__ [[image:Simantics_puzzle_piece.png|right|360px]]<br />
<br />
'''Simantics''' is a software platform for modelling and simulation. The system has client-server architecture with a semantic ontology-based modelling database and Eclipse framework -based client software with plug-in interface. The Simantics platform and many of its components are open source under [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License (EPL)].<br />
<br />
Simantics platform is used in open source and commercial modelling and simulation products. Simantics comes with [[Simantics System Dynamics | System dynamics modelling and simulation tool]], which is an open source tool for modelling business processes. The next versions of [http://www.apros.fi/ Apros] and [http://balas.vtt.fi/ Balas] will be based on the Simantics platform. For more information on Simantics and related projects, visit [http://www.simantics.org/ Simantics website].<br />
<br />
The philosophy of the Simantics platform is to offer an open, high level application platform on which different computational tools can be easily integrated to form a common environment for modelling and simulation. One of the biggest innovations in the Simantics platform is the semantic modelling approach. The data triple engine on the server side enables high performance data management and arbitrary mapping of data. This enables e.g. efficient mapping of simulation and measurement data to the model configuration and its visualisation.<br />
<br />
This ''Simantics End User Documentation'' provides information on the open source products that have been developed using Simantics platform. The basic principles of Simantics platform and some components common to all Simantics-based products are also explained. If you wish to dig deeper to the foundations of the Simantics platform or create your own modelling and simulation tool based on Simantics, see [http://dev.simantics.org/ Simantics Developer Documentation] or contact us through [http://www.simantics.org Simantics website].<br />
<br />
{| border="0" cellpadding="10"<br />
! !! Simantics Platform Products !!<br />
|-<br />
| style="width="270" align="center" valign="bottom"| [[File:AprosShot.png|300x160px|link=https://www.simantics.org/simantics/about-simantics/related-projects#section-0]]<hr>Apros<br />
| style="width="270" align="center" valign="bottom"| [[File:BalasShot.png|300x160px|link=https://www.simantics.org/simantics/about-simantics/related-projects#section-1]]<hr>Balas<br />
| style="width="270" align="center" valign="bottom"| [[File:SysdynOverviewPicture.png|link=Simantics System Dynamics]]<hr>System Dynamics<br />
|}<br />
<br />
=== [[Introduction to Simantics]] ===<br />
* [[Simantics#About Simantics Platform|About Simantics Platform]]<br />
* [[Simantics#Simantics Development and Open Source|Simantics Development and Open Source]]<br />
* [[Simantics#Simantics Concepts and Conventions|Simantics Concepts and Conventions]]<br />
<br />
=== [[Simantics System Dynamics]] ===<br />
<br />
* [[Simantics System Dynamics#Introduction to System Dynamics Simulation|Introduction to System Dynamics Simulation]]<br />
* [[Simantics System Dynamics#Installation Instructions|Installation Instructions]]<br />
* [[Simantics System Dynamics#Workbench|Workbench]]<br />
* [[Simantics System Dynamics#Modelling|Modelling]]<br />
* [[Simantics System Dynamics#Simulation|Simulation]]<br />
* [[Simantics System Dynamics#Multidimensional variables|Multidimensional variables]]<br />
* [[Simantics System Dynamics#Functions|Functions]]<br />
<br />
[[Tutorial: Basic System Dynamics Modelling]]<br />
<br />
[[Tutorial: Advanced System Dynamics Modelling]]<br />
<br />
-----</div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=Simantics_System_Dynamics&diff=591Simantics System Dynamics2013-02-14T08:06:13Z<p>Teemu Lempinen: /* Modelica functions */</p>
<hr />
<div>== Simantics System Dynamics ==<br />
<br />
Simantics System Dynamics is currently the only open source modelling and simulating tool for Simantics. Simantics System Dynamics is under development and will go through some changes in the future. New features will be added and old ones improved according to the needs of the modellers. New features include module libraries and different analysis tools.<br />
<br />
This documentation introduces you to the current version of Simantics System Dynamics. Documentation includes the basic modelling principles and a guide on how to model system dynamics models with Simantics System Dynamics. If you like to get to know the tool better and try modelling and simulating yourself, [[#Installation Instructions|install]] the software and try our [[Tutorial: Basic System Dynamics Modelling|basic]] and [[Tutorial: Advanced System Dynamics Modelling|advanced]] tutorials!<br />
<br />
== Introduction to System Dynamics Simulation ==<br />
<br />
===System Dynamics===<br />
System dynamics is an approach to understanding different organizations, markets and other complex systems and their dynamic behavior. System dynamics modelling in Simantics is a free modelling tool. See [[#Installation Instructions|installation instructions]].<br />
<br />
===Model===<br />
[[File:ModelStructure.png|right|thumb|Model structure]]<br />
System dynamics model is generally understood as the model configuration. In this tool, the model contains also other components. Model can have Operating interfaces that enable the use of the model with simple controls. Operating interfaces are configured separately and when using them, the complex model is hidden from the user. Experiments are the way to simulate the model. In the future, you can have experiments with different configurations, for example different initial values for some parameters. In that way, you don't have to always configure the model for different scenarios. Modules folder contains all the different module types in your model and you can create new module types there. <br />
<br />
<br style="clear: both" /><br />
<br />
===Components===<br />
Most of the components you can use in your models are basic system dynamics components. The modularity of the models introduces two additional components, Modules and Inputs. All the components are explained below.<br />
[[File:ComponentTypes.png|right|frame|Component types]]<br />
;Auxiliary<br />
:Auxiliary is the most basic variable you can use. It represents a single value or a mathematical expression. There are different types of auxiliary variables currently in the system: Auxiliary, Parameter, Constant, Delay and WithLookup. Auxiliary is the default type. Parameters are single values that the user can change. When only parameters are changed, the model simulates faster, because the system does not have to recompile the model. WithLookup and Delay are special variables. WithLookup has an expression and a lookup table. The expresssion defines what value is taken from the defined table. Delay variable delays an equation a given time with a given delay order.<br />
;Dependency<br />
:Dependency is an arrow that connects two components. It means that the value of the variable from which the arrow starts is used to calculate the value of the variable where the arrow ends.<br />
;Flow<br />
:Flow connects clouds, valves and stocks. Flow represents an actual flow of something from stocks or clouds to stocks or clouds. There has to be at least one valve in a flow and the system creates it automatically, if none of the ends of the flow is a valve.<br />
;Valve<br />
:Valve regulates the rate of a flow. The value of a valve is automatically used in calculating the level of an adjacent stock. Valves behave just like Auxiliary variables but look different and you can connect also flows to them.<br />
;Stock<br />
:The value of a stock variable is an integral of flows leaving and flows arriving to the variable. The integral is calculated automatically from the valves that are connected to the variable with flow connections. You must give an initial value to the stock. Initial value can be a single value or an equation. You can use values of other variables to calculate the initial value.<br />
;Cloud<br />
:Cloud is not a variable. It represents a starting or ending point of a flow, if it is not in the scope of the model.<br />
;Module<br />
:Modules enable structural modeling. Modules are defined just like the basic model configuration, but the module component hides the actual configuration. You can only connect dependency connections into the module and dependency connections from the module must end to Input variables. The interface of the module is defined using input and output variables in the configuration of the module. All variable types can be set as output variables. If a variable is an output variable, its font is bold.<br />
;Input<br />
:Input variables are the way of getting values from other modules. Inputs look like auxiliary variables except their font is italics. You can set a default value to the input variable in case it is not connected to any variable. Connections are made from the modules properties, when the module is populated. Input doesn't have to be connected with an arrow to a module. If the variable has no connections, it can get values from a higher level in the hierarchy. If an input is connected to an output, the output and its module are shown below the variable using dot notation.<br />
<br style="clear: both" /><br />
<br />
===Modeling principles===<br />
<br />
System dynamics modelling is much more than just mathematical formulas and nice graphs. Models are ways of communicating. There are some basic principles in system dynamics modelling that make the models easier to read and understand. You do not have to apply these principles to simulate models, but using them makes it easier for you to communicate your model to others.<br />
<br />
;Variable names<br />
:Variables names should be nouns, not verbs. The names should be positive: for example it is easier to understand that satisfaction decreases than dissatisfaction rises. <br />
<br />
:Variable names can and should have multiple words, if they are needed. Unfortunately current version of the tool does not support spaces in variable names. A good practice is to use CamelCase if name contains multiple words. This means that you start every word woth a capital letter (example: ExampleVariable).<br />
<br />
;Connections<br />
:You should try to avoid overlapping dependency arrows. In some situations, however, it is not possible. Dependencies should also form distinctive loops, if there is a loop. It makes it easier to read and understand the model and its behavior.<br />
<br />
;Graphical annotations<br />
:System dynamics contains usually annotations for loops, polarities, delays and so on. Currently those annotations are not supported, but the support will be added later. Annotations are important, again, for communicating the behavior of the model.<br />
<br />
==Installation Instructions==<br />
<br />
System dynamics tool is a provided with the Simantics platform.<br />
<br />
# [https://www.simantics.org/simantics/download Download installer from Simantics download page]<br />
# Install the program to a directory without spaces (limitation inherited from OpenModelica).<br />
# Run the application through the launcher generated by the installer<br/><br />
: (default: Simantics\Simantics-1.6.0-Sysdyn-32\Simantics-1.6.0-Sysdyn-32)<br />
<br />
[http://www.openmodelica.org/ OpenModelica] is used to build and simulate the models. Simantics platform has integrated OpenModelica 1.8.1 for Windows environments. For other versions and other environments you need to install [http://www.openmodelica.org/index.php/download OpenModelica].<br />
<br />
== Workbench ==<br />
<br />
[[File:BasicWorkbench.png|center|729px]]<br />
<br />
<br />
# '''Diagram''' <br /> Diagram is the area where you will graphically modify your model. Diagrams are built from elements that can be dragged from Symbols view or populated using shortcut keys. <br />
# '''Model Browser''' <br /> Model browser shows the structure of your model and all items related to it. <br /> Symbols view is stacked with the model browser and used for dragging elements to diagrams.<br />
# '''Properties''' <br /> Property view shows the selected variable's properties. Property view has a different layout depending on the type of the selected component. The view can also have different tabs depending on the component type. Basic tabs are with variables are Equation and Additional information.<br />
# '''Trend''' <br /> Trend view shows the graphical representation of the values of the selected value over time. For the trend to be shown, a simulation has to be run. The view shows always the results of the latest run, but you can save results of a simulation and show them in the same trend with results from another simulation. Values view and Dependencies are stacked with Trend view and can also be used for analyzing the model.<br />
# '''Experiment controls''' <br /> Experiment controls are shown when an experiment is active. Experiment is activated by double clicking an experiment in the model browser. With the experiment control, you can start simulation runs and save simulation results.<br />
<br />
<br /><br />
If you accidentally close a view, you can reopen them from Window->Show View->Other...<br />
<br />
== Modelling ==<br />
<br />
===Basic modelling===<br />
<br />
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.<br />
<br />
[[File:Basic_1.png|right]]<br />
;Creating a new model<br />
:Start a new model by right-clicking the model browser and selecting New->Model or from the main menu File->New Model.<br />
<br style="clear: both" /><br />
<br />
[[File:Basic_2.png|right]]<br />
;Creating a new module type<br />
:Create a new module type by right-clicking on the Modules-folder and selecting New->Module. This creates a new module type that you can populate to your other modules and the model configuration. <br />
<br style="clear: both" /><br />
<br />
;Configuring a model<br />
:Model configuration can be opened by double clicking Configuration in the model browser. <br />
<br />
;Configuring modules<br />
: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 module!<br />
<br />
;Populate variables<br />
:You can drag variables to a diagram from symbol view. You can also populate variables using [[#Shortcut and control keys|shortcut keys]]<br />
<br />
;Populate modules<br />
:Modules are populated from the model browser. Just drag the module you want to populate from the Modules folder to a diagram.<br />
<br />
;Create connections<br />
: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.<br />
: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.<br />
: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.<br />
<br />
;Connections between modules<br />
:'''Outside the module''' <br /><br />
:You can connect variables to variables in modules like this:<br />
MODULE -----> INPUT<br />
or<br />
ANY VARIABLE -----> MODULE <br />
:This is just the visual configuration, but you need those connections to really connect variables in the module's properties.<br />
:In Inputs -tab you select which variables you connect to inputs inside the module. In Outputs -tab you select which variables you lift from the module to inputs outside it.<br />
<br />
:'''Inside the module''' <br /><br />
:Input variables get values from outside the module<br />
<br />
:Output variables can send their values outside the module. From the variable properties, select Additional Information and press Is Output<br />
<br />
;Configure variables<br />
:Select a single variable from diagram or model browser. The properties of the variables are shown in the equation view and you can modify them.<br />
<br />
;Export model<br />
: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 to for example create different versions of the model, create backups or to transport it to another database.<br />
<br />
;Import model<br />
:Right-click on the model browser and select Import->Model. Browse to your .tg file and select open. The model is added to your model browser.<br />
<br />
=== Special variables ===<br />
<br />
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.<br />
<br />
;WithLookup<br />
WithLookup variable has two equation fields, WithLookup and Lookup table. Lookup table has a table from which the value of the variable is interpolated using the value of WithLookup field.<br />
<br />
[[File:WithLookup1.png]]<br />
<br />
You do not need to manually input the Lookup table. WithLookup variable type offers an additional Lookup table tab in the property view. In this view you can add and modify points in the lookup table. Points can be added either by clickin on the chart or by using the input fields and Add button. Points can be modified by dragging them on the chart or modifying values in the table. Points are removed by clicking them with right mouse click. <br />
<br />
[[File:WithLookup2.png]]<br />
<br />
;Delay<br />
Delay variables build equations for Nth order delays. Users can set the equation for the value that is to be delayed, the time and order of the delay and a possible start value. If start value is empty, the start value is set automatically. <br />
<br />
[[File:Delay1.png]]<br />
<br />
Different order delays have slightly different curves when a step change is triggered. The example picture below shows a step change from 0 to 1 at time 1 with four different delays: 1st, 2nd, 3rd and 10th order delays. <br />
<br />
[[File:Delay2.png]]<br />
<br />
For further information on how the delays work, you can look at the equations that are created by the delay variable. Below is a third order delay. Delay3 is the actual variable that is seen by users. DelayClass has as many level (LV) variables as the order of the delay is. <br />
<br />
Definitions:<br />
Real Delay3;<br />
Delay3_delayClass Delay3_delayClass_instance(initialValue = 0, delayTime = 1);<br />
class Delay3_delayClass<br />
parameter Real DL = delayTime/3;<br />
parameter Real delayTime;<br />
parameter Real initialValue;<br />
Real delay0;<br />
Real LV1(fixed=true, start=initialValue * DL);<br />
Real delay1;<br />
Real LV2(fixed=true, start=initialValue * DL);<br />
Real delay2;<br />
Real LV3(fixed=true, start=initialValue * DL);<br />
Real delay3;<br />
equation<br />
der(LV1) = - delay1 + delay0;<br />
delay1 = LV1 /DL;<br />
der(LV2) = - delay2 + delay1;<br />
delay2 = LV2 /DL;<br />
der(LV3) = - delay3 + delay2;<br />
delay3 = LV3 /DL;<br />
end Delay3_delayClass;<br />
<br />
The above definitions can be seen as a line of stocks and valves. The first valve, delay0, is given the value of the delayed expression. Delay3 is given the value of the valve that is coming from the last stock. <br />
<br />
Equations:<br />
Delay3_delayClass_instance.delay0 = Step1;<br />
Delay3 = Delay3_delayClass_instance.delay3;<br />
<br />
===Shortcut and control keys===<br />
<br />
Shortcut keys for configuring a model on diagram.<br />
<br />
{|<br />
|Esc <br />
|Cancel operations (e.g. connection and rename).<br />
|-<br />
|Shift + A <br />
|Hover Auxiliary at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + S<br />
|Hover Stock at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + C<br />
|Hover Cloud at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + V<br />
|Hover Valve at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + I<br />
|Hover Input at the cursor position, populate with left mouse button.<br />
|-<br />
|Alt + left mouse button<br />
|Start an arrow from a variable. End to another variable by clicking left mouse button.<br />
|-<br />
|Alt + right mouse button<br />
|Start flow from a variable. End by clicking left mouse button.<br />
<br />
If a flow is not started or ended on to a variable, a cloud will be created to that end. <br /><br />
If a new flow does not have a valve at either end, a valve will be created in the middle of the flow.<br />
|-<br />
|Delete<br />
|Remove selected variables<br />
|-<br />
|Ctrl + left mouse button<br />
|Select multiple variables<br />
|-<br />
|Mouse wheel or<br/>+ and -<br />
|Diagram zoom<br />
|-<br />
|drag(mouse3) or<br/>drag(shift + any mouse button)<br />
|Diagram pan<br />
|-<br />
|Ctrl + C<br />
|Copy selected elements<br />
|-<br />
|Ctrl + X<br />
|Cut selected elements<br />
|-<br />
|Ctrl + V<br />
|Paste copied or cut elements<br />
|-<br />
|G<br />
|Show / hide grid<br />
|-<br />
|R<br />
|Show / hide ruler<br />
|-<br />
|1<br />
|Fit diagram contents to screen<br />
|}<br />
<br />
Other shortcut keys can be found selecting Window -> Preferences from the main menu. Keys are located in General -> Keys.<br />
<br />
== Simulation ==<br />
There are three different ways for simulating a model. Different simulations are represented as different types of experiments in Simantics System Dynamics. <br />
<br />
Experiments are created from the context menu of experiments folder in a model. <br />
<br />
[[File:NewExperiment.png]]<br />
<br />
Double-click on an experiment activates it and displays experiment type specific controls in the main tool bar.<br />
<br />
;Normal simulation<br />
: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.<br />
<br />
;Game simulation<br />
:Game simulations allow simulating an arbitrary number of steps, changing parameter values and continuing simulation with the new values from where it previously ended.<br />
<br />
;Simulation playback<br />
:Simulation playback works essentially as the basic experiment, but it offers some additional visualization options.<br />
<br />
== Simulation result and model structure analysis ==<br />
Simulation results can be viewed as trends in trend view or as plain numbers in values view. The views display results of variables that are selected in the workbench. Users can also create [[#Custom charts |custom charts]].<br />
<br />
Model structure can be examined in the Structure view. There are two options: Dependency structures of individual variables or the complete hierarchy structure of the model.<br />
<br />
;Trend<br />
:Shows you the values of the selected variable(s) graphically over the simulation time. You can modify the trend and zoom it using the context menu (right-click) of the trend. <br /> [[File:Trend.png]]<br />
<br />
;Values<br />
:Shows you the values of the selected variable(s) in a table form. If the value has a star (*) at the end, it means that the value is an approximate. There is no value for that variable for the given time step. Selected values can be copied to other software in csv format.<br /> [[File:Values.png]]<br />
<br />
;Compare results<br />
:You can compare different results of the same model by saving simulation results and displaying the saved results side by side with other results. You can save your results after simulating by clicking the save button [[File:Saveresults.png]] on your experiment controls. The saved results appear to model browser under the active experiment. To show the results on trends and tables, right-click on the result and select Show on charts. <br /> [[File:CompareTrend.png]]<br />
<br />
;Dependencies<br />
:Dependencies display which variables affect and which are affected by the selected variable. The direction and number of steps that are traveled from the selected variable can be configured at the bottom of the view. <br /> [[File:Dependencies.png]]<br />
<br />
;Model Hierarchy<br />
:Model Hierarchy displays the hierarchical structure of the model. The module type where a selected variable is located is highlighted.<br /> [[File:ModelHierarchy.png]]<br />
<br />
== Custom charts ==<br />
Custom charts are user-defined displays of simulation result data. They can be used and re-used in various places. The three types of custom charts (line, bar and pie charts) provide model developers means for examining and developing their models and communicating the simulation results to others. <br />
<br />
Custom charts are created to the Charts folder in model browser.<br />
<br />
[[File:NewChart.png | Creating a new chart]]<br />
<br />
Charts are configured the same way as variables: first select the chart from model browser and then configure it in the property view. Charts can be viewed in the same active trend view as any variable by selecting the chart from model browser. In addition to trend view, charts can be populated directly to the model diagram or to a separate chart panel that can contain multiple charts. <br />
<br />
=== Line chart ===<br />
<br />
Line char 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.<br />
<br />
[[File:LineChart.png|Line chart with an array variable]]<br />
<br />
[[File:LineChartGeneral.png|General settings of line chart]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|The title of the chart. Displayed in the chart<br />
|-<br />
|Type<br />
|Line chart (default) or area chart<br />
|-<br />
|Hide<br />
|Options to hide chart grid, title or legend<br />
|-<br />
|'''X-axis'''<br />
|<br />
|-<br />
|Variable<br />
|A variable that is used as the x-axis variable. The default variable is time and it needs not to be typed in the field.<br />
|-<br />
|Label<br />
|Optional other label for the variable than its name<br />
|-<br />
|Min<br />
|Minimum value of the x-axis<br />
|-<br />
|Max<br />
|Maximum value of the x-axis<br />
|-<br />
|Hide<br />
|Options to hide x-axis lable, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
[[File:LineChartAxisAndVariables.png|Axis and variables settings of line chart]]<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed.<br />
|-<br />
|Color<br />
|Color for the lines of this variable<br />
|-<br />
|Line width<br />
|The width of the lines drawn for this variable<br />
|}<br />
There are also configuration options for y-axis. They are displayed when an axis is selected in the Axis and variables tab.<br />
{|<br />
|'''Y-axis'''<br />
|<br />
|-<br />
|Label<br />
|Label of the axis<br />
|-<br />
|Min<br />
|Minimum value in the axis<br />
|-<br />
|Max<br />
|Maximum value in the axis<br />
|-<br />
|Color<br />
|The color of the axis lines, ticks and labels<br />
|-<br />
|Hide<br />
|Options to hide parts of the axis: label, axis line, tick marks, tick labels<br />
|-<br />
|}<br />
<br />
=== Bar chart ===<br />
Bar charts display variables in a certain point in time. The point can be defined for the complete chart in cart'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. <br />
<br />
[[File:BarChartGeneral.png|General bar chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Name is displayed in model browser.<br />
|-<br />
|Title<br />
|The title of the chart. Title is displayed in the chart, if not hidden<br />
|-<br />
|Type<br />
|Normal or stacked. Normal type displays all variables in separate bars. Stacked mode is able to display one-dimensional array variables in stacks.<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Option for hiding grid, title and Legend. Legend is hidden by default since it only contains the information that the current simulation is displayed.<br />
|-<br />
|}<br />
<br />
[[File:BarChartInDiagram.png|Bar chart in a model diagram]]<br />
<br />
Charts can be added to model diagrams simply by dragging the chart from model browser to diagram.<br />
<br />
[[File:BarChartVariable.png|Settings for a variable in bar chart]]<br />
<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|}<br />
[[File:BarChartAxis.png|Settings for axis in bar chart]]<br />
{|<br />
|'''Domain axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for x axis<br />
|-<br />
|Label angle<br />
|Axis labels can be displayed in an angle. This value determines the angle in degrees.<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|'''Range axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for y axis<br />
|-<br />
|Min<br />
|Minimum value of y axis<br />
|-<br />
|Max<br />
|Maximum value of y axis<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
=== Pie chart ===<br />
<br />
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.<br />
<br />
[[File:PieChartGeneral.png|General pie chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|Title The title of the chart. Displayed in the chart<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Options for hiding title, section labels and legend<br />
|-<br />
|}<br />
<br />
[[File:PieChartVariable.png|Variable settings in pie chart]]<br />
{|<br />
|'''Variables'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Color<br />
|Color for the sector of this variable<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|Exploded<br />
|If set, the sector(s) of the variable(s) are "exploded" away from the center of the pie chart<br />
|-<br />
|}<br />
<br />
[[File:PieChartChartPanel.png|Pie chart in chart panel]]<br />
<br />
=== Chart panel ===<br />
[[File:ChartPanel.png|right]]<br />
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.<br />
<br />
Chart panel can be either horizontally or vertically oriented. Different orientations help in configuring the workbench perspective. <br />
<br />
[[File:ChartPanelOrientation.png|Chart panel orientation]]<br />
<br />
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.<br />
<br />
By default, chart panel is hidden in the upper-left corner of the system dynamics perspective.<br />
<br style="clear: both" /><br />
<br />
== Multidimensional variables ==<br />
<br />
<br />
=== Modeling ===<br />
<br />
Models with multidimensional variables look just like any other models. The structure of the models is replicated givin multiple indexes to variables. For users with programming background, notation Variable[] may be familiar. In system dynamic modeling we need to give names to the indexes. Instead of using numbers to define the indexes, like in normal programming, we use enumerations. The steps to create a model with multidimensional variables are as follows (with examples):<br />
<br />
# '''Create the model structure''' <BR />Model with multidimensional variables looks just like any other model.<BR /> [[File:ModelWithMultidimensionalVariables.png|300px|Model with multidimensional variables]]<br />
# '''Create Enumerations and define the indexes''' <BR />Enumerations are created by right-clicking configuration and selecting New->Enumeration.<BR /> [[File:NewEnumeration.png|250px|New enumeration]]<BR />Define enumeration indexes by adding as many indexes as you want. Rename the indexes by selecting them and then clicking on them again.<BR />[[File:DefineIndexes.png|200px|Index definitions]]<br />
# '''Add Enumerations for variables''' <BR />Select the variable that you want to be multidimensional. From the Indexes -tab in the property view, move the wanted enumerations to the right. The order of the enumerations does matter.[[File:SelectEnumerations.png|500px|Select enumerations for variables]]<br />
# '''Define equations for all possible indexes''' <BR />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 indexes, so the resulting definition can be {{1,2,3},{4,5,6},{7,8,9}}.<BR />[[File:DefineEquations.png|500px|Define equations for all indexes]]<br />
<br />
<br />
<br />
=== Expressions ===<br />
<br />
Values for all cells in the variable matrix can be defined in a single expression. <br />
<br />
[[File: DefineEquations.png|600px]]<br />
<br />
[[File:DefineEquations2.png|600px]]<br />
<br />
In many situations, it is however more clear to define separate expressions for each cell or blocks. <br />
<br />
# '''Define range for the expression'''<BR /> [[File:DefineRange.png]]<br />
# '''Define the expression''' (dimensions of the defined range and the result of the expression must match!) <BR /> [[File:DefineEquations3.png]]<br />
# '''Create a new expression''' <BR /> [[File:CreateNewExpression.png]]<br />
#''' Select the new expression''' <BR /> [[File:SelectNewExpression.png]]<br />
<br />
Repeat until there is value for each cell. There must be exactly one value for each cell.<br />
<br />
=== Array slices ===<br />
<br />
Many times it is useful to access a slice of a multidimensional variable. In this chapter, we will use the following example variable:<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
The whole variable can be accessed in three different ways:<br />
# Auxiliary<br />
# Auxiliary[E1, E2]<br />
# Auxiliary[:, :]<br />
<br />
The following explains different methods for accessing parts of the variable<br />
<br />
// Single cell<br />
Auxiliary[one, eins] = 1<br />
<br />
// Slices<br />
Auxiliary[one, E2] = {1,2,3}<br />
Auxiliary[E1, zwei] = {{2},{5},{8}}<br />
<br />
// In addition to single cells and the whole enumeration range, a subrange of the enumeration can be used<br />
Auxiliary[two : three, E2] = {{4,5,6},{7,8,9}}<br />
Auxiliary[one : two, zwei : drei] = {{2,3},{5,6}}<br />
<br />
The syntax for accessing parts of variables can be used in both expression range definitions and in expressions.<br />
<br />
=== Arithmetic Operators ===<br />
<br />
Arithmetic operations are defined in Modelica. Below are examples of different operations.<br />
<br />
;Addition and substraction<br />
Addition and substraction are calculated elementwise<br />
<br />
{1,2,3} - {0,2,3} = {1,0,0}<br />
{{2,2},{4,4}} + {{8,8},{1,1}} = {{10,10},{5,5}}<br />
{1,2,3} - {1,2} = ERROR! Different array sizes<br />
<br />
;Division<br />
Division with a scalar<br />
{5,10,15} / 5 = {1,2,3}<br />
5 / {5,10,15} = ERROR! not allowed<br />
<br />
Division with an array<br />
{1,2,3} / {1,2,3} = ERROR! not allowed<br />
<br />
// Elementwise<br />
{1,2,3} ./ {1,2,3} = {1,1,1}<br />
<br />
;Multiplication<br />
<br />
Multiplication with a scalar<br />
{1,2,3} * 2 = {2,4,6}<br />
5 * {1,2,3} = {5,10,15}<br />
<br />
Matrix multiplication with an array<br />
{{3,4},{5,6}} * {1,2} = {11,17}<br />
{{3,4},{5,6}} * {1,2,3} = ERROR! incompatible array sizes<br />
<br />
//Elementwise<br />
{1,2} .* {1,2} = {1,4}<br />
<br />
Real[3,2] c = {{1,2},{3,4},{5,6}}; <br />
Real[2,2] d = {{3,4},{5,6}};<br />
Real[2,2] cd;<br />
cd = c[2:3, :] .* d; // Result: {{9,16},{25,36}}<br />
<br />
;Power<br />
Elementwise power of array variable<br />
{1,2} .^ 2 = {1,4}<br />
<br />
=== Builtin Modelica functions ===<br />
<br />
Modelica has some builtin functions that help using multidimensional variables. This chapter introduces some of the builtin functions. <br />
<br />
;Dimension and size functions<br />
<br />
We will use the same example variable as previously.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
;ndims(A)<br />
The number of dimensions in array A<br />
ndims(Auxiliary) = 2<br />
<br />
;size(A, i)<br />
The size of dimension i in array A<br />
size(Auxiliary, 2) = 3<br />
<br />
;size(A)<br />
A vector of length ndims(A) containing the dimension sizes of A<br />
size(Auxiliary) = {3,3}<br />
<br />
<br />
;Construction functions<br />
In addition to normal array constructing, a special construction functions can be used.<br />
<br />
;zeros(n1,n2,n3,...)<br />
An array full of zeros with dimensions n1 x n2 x n2 x ... <br />
zeros(2, 2) = {{0,0}, {0,0}}<br />
<br />
;ones(n1,n2,n3,...)<br />
An array full of ones with dimensions n1 x n2 x n2 x ... <br />
ones(2, 2) = {{1,1}, {1,1}}<br />
<br />
;fill(s,n1,n2,n3)<br />
Like zeros() and ones(), but with user defined value (s) for array elements.<br />
fill(3,2,2) = {{3,3}, {3,3}}<br />
<br />
;identity(n)<br />
Creates an n x n integer identity matrix with ones on the diagonal and all other elements zero.<br />
identity(3) =<br />
1 0 0<br />
0 1 0<br />
0 0 1<br />
<br />
;diagonal(v)<br />
Constructs a square matrix with elements of vector v on the diagonal and all other elements zero.<br />
diagonal({1,2,3}) =<br />
1 0 0<br />
0 2 0<br />
0 0 3<br />
<br />
;linspace(x1,x2,n)<br />
Constracts a Real vector from x1 to x2 with n equally spaced elements.<br />
linspace(2,5,4) = {2,3,4,5}<br />
<br />
;Reduction functions<br />
<br />
Reduction functions reduce arrays to scalars.<br />
<br />
;min(A)<br />
Returns the minimum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
min(A) = 1<br />
<br />
;max(A)<br />
Returns the maximum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
max(A) = 4<br />
<br />
;sum(A)<br />
Returns the sum of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
sum(A) = 10 // 1 + 2 + 3 + 4<br />
<br />
;product(A)<br />
Returns the product of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
product(A) = 24 // 1 * 2 * 3 * 4<br />
<br />
<br />
;Using functions with iterators<br />
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.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
AuxiliarySum[E1] = {sum( Auxiliary[ i , E2 ] ) for i in E1} // Result: {6, 15, 24}<br />
<br />
/* Same as:<br />
{sum(Auxiliary[one, E2]), sum(Auxiliary[two, E2]), sum(Auxiliary[three, E2])}<br />
{sum({1,2,3}), sum({4,5,6}), sum({7,8,9})}<br />
*/<br />
<br />
One expression can have multiple iterators. The Modelica specification defines the following format, but it is NOT yet supported in OpenModelica:<br />
{sum(Array[ i, j, E3]) for i in E1, j in E2} // Dimensions reduced from 3 to 2<br />
<br />
To use multiple iterators, use the following format (NOTE the reversed order of iterators!):<br />
{{sum(Array[ i, j, E3]) for j in E2} for i in E1} // Dimensions reduced from 3 to 2<br />
<br />
The range doesn't have to be the whole enumeration. Subranges can also be used.<br />
{sum( Auxiliary[ i , eins : zwei ] ) for i in E1.one : E1.two} // Result: {3, 9}<br />
<br />
/* Same as<br />
{sum(Auxiliary[one, eins : zwei]), sum(Auxiliary[two, eins : zwei])}<br />
{sum({1,2}), sum({4,5})}<br />
*/<br />
<br />
=== Simulation results ===<br />
<br />
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. <br />
<br />
[[File:3x3trend.png|300px|Trend view for a 3x3 variable]]<br />
<br />
The clutter can be reduced by selecting which enumeration indexes are shown in charts. Select an enumeration and tick the indexes 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.<br />
<br />
[[File:ShowInCharts.png|500px|Select indexes to show in charts]]<br />
<br />
<br />
=== Array Variables in Modules ===<br />
<br />
[[File:Replaceable.png|frame|Replaceable enumeration inside a module]]<br />
<br />
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 [[Simantics_System_Dynamics#Modeling|Modeling]]). <br />
<br />
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.<br />
<br />
<br />
<br style="clear: both" /><br />
<br />
In this example, the original enumeration that the modeler used had two indexes. We are using an instance of this module, but we need to use array variables that have three indexes instead of two. We are using two variables and an instance of the module.<br />
<br />
[[File:ReplacingEnumerationConfiguration.png|frame|left|500px|Module configuration for replacing enumerations inside the module]]<br />
<br style="clear: both" /><br />
<br />
In the parent configuration, we have used an enumeration with three indexes in the two variables.<br />
<br />
[[File:Replacing.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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 clickin 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.<br />
<br />
<br />
[[File:ReplacingEnumeration.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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!<br />
<br />
== Functions ==<br />
<br />
Modelica provides a convenient way to use functions in your models. You can create your own functions, import complete function libraries and share function libraries to be used in all of your models. <br />
<br />
=== Creating functions ===<br />
<br />
[[File:NewFunction.png|right]]<br />
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.<br />
<br />
Functions that can be found from Functions -folder can be used in your variable definitions.<br />
<br />
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. <br />
<br />
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.<br />
<br />
Below is an example of a simple function. For more examples, see the built-in functions provided with the tool and [https://www.modelica.org/documents/ Modelica specifications].<br />
<br />
<br style="clear: both" /><br />
<br />
[[File:ExampleFunction.png]]<br />
<br />
=== Function libraries ===<br />
<br />
<br />
[[File:NewFunctionLibrary.png|right]]<br />
<br />
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)).<br />
<br />
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. <br />
<br />
Create a new function library by right-clicking on Functions folder, Shared functions folder or other module library.<br />
<br />
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.<br />
<br />
[[File:SharedFunctions.png]]<br />
<br style="clear: both" /><br />
<br />
=== External functions ===<br />
<br />
Modelica allows you to use external functions that are programmed using C language. Below is a simple example of using a function that returns the sum of two arguments. <br />
<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}<br />
<br />
<br />
[[File:ImportCFunctionLibrary.png|right]]<br />
<br />
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 <br />
(e.g. simantics_home/plugins/org.simantics.openmodelica.win32_x/MinGW/bin/mingw32_gcc.exe -g -O -c ExampleCFunctionCode.c). <br />
<br style="clear: both" /><br />
<br />
[[File:ExampleExternalFunction.png]]<br />
<br />
<br />
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.<br />
<br />
[[File:ExternalFunctionResult.png]]<br />
<br />
<br />
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.<br />
<br />
<br />
Small external C function can also be written directly to the function code in Simantics Sysdyn:<br />
function ExampleExternalFunction<br />
input Real x;<br />
input Real y;<br />
output Real z;<br />
external "C" z=exampleCFunction(x,y) annotation(Include="<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}");<br />
end ExampleExternalFunction;<br />
<br />
=== Modelica functions ===<br />
<br />
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 [[Simantics_System_Dynamics#Builtin_Modelica_functions|builtin functions for arrays]].<br />
<br />
{|<br />
|abs(x)<br />
|Returns the absolute value of x. Expanded into "(if x >= 0 then x else -x)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|acos(x)<br />
|Inverse cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|asin(x)<br />
|Inverse sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan(x)<br />
|Inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan2(x1,x2)<br />
|four quadrant inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cat(n,A,B,...)<br />
|General concatenation function that concatenates arrays A,B,... along the nth dimension.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|ceil(x)<br />
|Returns the smallest integer not less than x, the closest integer above x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cos(x)<br />
|Cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cosh(x)<br />
|Hyperbolic cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cross(x,y)<br />
|Returns the 3-vector cross product of the 3-vectors x and y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|delay(expr, delayTime)<br />
|Returns the value of expr at the time time-delayTime. The value of expr is returned when time <= time.start + delayTime.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|der(x)<br />
|Time derivative of x. X must be have continuous-time variability.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|div(x, y)<br />
|Returns the algebraic quotient x/y with any fractional part discarted. E.g. div(10,3) = 3.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|edge(b)<br />
|Returns true when the value of the boolean expression b changes. Expanded into (b and not pre(b)).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|exp(x)<br />
|Exponential, base e.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|floor(x)<br />
|Returns the largest integer not greater than x, the closest integer below x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|initial()<br />
|Returns true at the beginning of the simulation. <br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|integer(x)<br />
|Returns the largest integer not greater than x as an integer.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log(x)<br />
|Natural logarithm. (base e, x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log10(x)<br />
|Base 10 logarithm. (x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|mod(x, y)<br />
|Returns the integer modulus of x/y: mod(x,y) = x - floor(x/y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|noEvent(expr)<br />
|noEvent around an expression causes the expression to NOT generate event.<br />
'''Important:''' <br />
:If you want a condition to be checked only on time steps, use noEvent.<br />
:(e.g. if noEvent(value >= 1) then ... else ...)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|pre(x)<br />
|Returns the preceding value of y from time event that has occured before current time.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|rem(x, y)<br />
|Returns the integer remainder of x/y: rem(x,y) = x - div(x,y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sample(start, interval)<br />
|Returns true and triggers time events at times start + i * interval (i=0,1,...).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sign(x)<br />
|Returns -1 if x is negative, 1 if x is positive. Expanded into "(if x > 0 then 1 else if x < 0 then -1 else 0)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sin(x)<br />
|Sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sinh(x)<br />
|Hyperbolic sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sqrt(x)<br />
|Square root of x. The value of x must be greater or equal to 0 or an assertion error occurs.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tan(x)<br />
|Tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tanh(x)<br />
|Hyperbolic tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|terminal()<br />
|Returns true at the end of a successful simulation.<br />
|}<br />
<br />
== Spreadsheets ==<br />
<br />
Spreadsheets allow storing and maintaining values in a familiar format. The current spreadsheet implementation is experimental and does not provide much functionality. Some basic tasks can, however, be performed. You cannot type directly to a cell, you need to first copy some value or text into it. Then it can be modified.<br />
<br />
=== Variable values ===<br />
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.<br />
<br />
[[File:AuxiliarySheetReference.png|Sheet reference in an expression]][[File:AuxiliarySheet.png|Value of a variable in sheet]]<br />
<br />
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 indexes are not mandatory, but help reading and maintaining the sheet.<br />
<br />
[[File:SheetForMultidim.png|Spreadsheet for multidimensional variables]]<br />
<br />
Reference to a sheet range creates an array variable.<br />
<br />
[[File:SheetMultidim1.png|Array variable ArrayTest1[2] with sheet reference]]<br />
<br />
ArrayTest2 has two dimensions. Reference to a larger range creates a two-dimensional variable. By default, the indexes are ordered as in this example. However, if you wish to present the indexes in a different order in the spreadsheet, you can transpose the sheet reference (e.g. transpose(ArrayTestSheet(E2:G3)))<br />
<br />
[[File:SheetMultidim2.png|Array variable ArrayTest2[2,3] with sheet reference]]<br />
<br />
=== History data ===<br />
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.<br />
<br />
[[File:Sheet.png|Spreadsheet with history data]]<br />
<br />
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. <br />
<br />
[[File:HistoryDataSettings.png|History data settings]]<br />
<br />
{|<br />
|'''History data properties'''<br />
|<br />
|-<br />
|Name<br />
|Name of the history dataset<br />
|-<br />
|Sheet<br />
|Combo box for selecting a sheet where the history data is located<br />
|-<br />
|Orientation<br />
|Columns or rows. How the data is arranged in the sheet.<br />
|-<br />
|Range start<br />
|The upper-left corner cell of the history data range<br />
|-<br />
|Range end<br />
|The lower-right corner cell of the history data range<br />
|-<br />
|Time variable<br />
|The name of the time variable in the history data, if it is different than "time"<br />
|-<br />
|Variables in range<br />
|This text field displays the found variables in the given sheet and range<br />
|-<br />
|}<br />
<br />
If the history dataset is activated, history data is displayed whenever it is available for a variable that is displayed in a chart.<br />
<br />
[[File:HistoryData.png|History data in two charts]]<br />
<br />
<br />
<center><br />
[[Simantics]] | ''System Dynamics Modelling''<br />
</center><br />
<br />
----<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Basic System Dynamics Modelling]]'''<br><br />
System dynamics modelling in Simantics is a free modelling tool that is included into the basic installation. This tutorial introduces the basic features of the system dynamics modelling tool.<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Advanced System Dynamics Modelling]]'''<br><br />
This tutorial introduces the more advanced features of the system dynamics modelling tool: Modules and Operating interfaces<br />
<br />
[[Category: Simantics System Dynamics]]</div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=Simantics_System_Dynamics&diff=590Simantics System Dynamics2013-02-03T11:06:01Z<p>Teemu Lempinen: /* Shortcut and control keys */</p>
<hr />
<div>== Simantics System Dynamics ==<br />
<br />
Simantics System Dynamics is currently the only open source modelling and simulating tool for Simantics. Simantics System Dynamics is under development and will go through some changes in the future. New features will be added and old ones improved according to the needs of the modellers. New features include module libraries and different analysis tools.<br />
<br />
This documentation introduces you to the current version of Simantics System Dynamics. Documentation includes the basic modelling principles and a guide on how to model system dynamics models with Simantics System Dynamics. If you like to get to know the tool better and try modelling and simulating yourself, [[#Installation Instructions|install]] the software and try our [[Tutorial: Basic System Dynamics Modelling|basic]] and [[Tutorial: Advanced System Dynamics Modelling|advanced]] tutorials!<br />
<br />
== Introduction to System Dynamics Simulation ==<br />
<br />
===System Dynamics===<br />
System dynamics is an approach to understanding different organizations, markets and other complex systems and their dynamic behavior. System dynamics modelling in Simantics is a free modelling tool. See [[#Installation Instructions|installation instructions]].<br />
<br />
===Model===<br />
[[File:ModelStructure.png|right|thumb|Model structure]]<br />
System dynamics model is generally understood as the model configuration. In this tool, the model contains also other components. Model can have Operating interfaces that enable the use of the model with simple controls. Operating interfaces are configured separately and when using them, the complex model is hidden from the user. Experiments are the way to simulate the model. In the future, you can have experiments with different configurations, for example different initial values for some parameters. In that way, you don't have to always configure the model for different scenarios. Modules folder contains all the different module types in your model and you can create new module types there. <br />
<br />
<br style="clear: both" /><br />
<br />
===Components===<br />
Most of the components you can use in your models are basic system dynamics components. The modularity of the models introduces two additional components, Modules and Inputs. All the components are explained below.<br />
[[File:ComponentTypes.png|right|frame|Component types]]<br />
;Auxiliary<br />
:Auxiliary is the most basic variable you can use. It represents a single value or a mathematical expression. There are different types of auxiliary variables currently in the system: Auxiliary, Parameter, Constant, Delay and WithLookup. Auxiliary is the default type. Parameters are single values that the user can change. When only parameters are changed, the model simulates faster, because the system does not have to recompile the model. WithLookup and Delay are special variables. WithLookup has an expression and a lookup table. The expresssion defines what value is taken from the defined table. Delay variable delays an equation a given time with a given delay order.<br />
;Dependency<br />
:Dependency is an arrow that connects two components. It means that the value of the variable from which the arrow starts is used to calculate the value of the variable where the arrow ends.<br />
;Flow<br />
:Flow connects clouds, valves and stocks. Flow represents an actual flow of something from stocks or clouds to stocks or clouds. There has to be at least one valve in a flow and the system creates it automatically, if none of the ends of the flow is a valve.<br />
;Valve<br />
:Valve regulates the rate of a flow. The value of a valve is automatically used in calculating the level of an adjacent stock. Valves behave just like Auxiliary variables but look different and you can connect also flows to them.<br />
;Stock<br />
:The value of a stock variable is an integral of flows leaving and flows arriving to the variable. The integral is calculated automatically from the valves that are connected to the variable with flow connections. You must give an initial value to the stock. Initial value can be a single value or an equation. You can use values of other variables to calculate the initial value.<br />
;Cloud<br />
:Cloud is not a variable. It represents a starting or ending point of a flow, if it is not in the scope of the model.<br />
;Module<br />
:Modules enable structural modeling. Modules are defined just like the basic model configuration, but the module component hides the actual configuration. You can only connect dependency connections into the module and dependency connections from the module must end to Input variables. The interface of the module is defined using input and output variables in the configuration of the module. All variable types can be set as output variables. If a variable is an output variable, its font is bold.<br />
;Input<br />
:Input variables are the way of getting values from other modules. Inputs look like auxiliary variables except their font is italics. You can set a default value to the input variable in case it is not connected to any variable. Connections are made from the modules properties, when the module is populated. Input doesn't have to be connected with an arrow to a module. If the variable has no connections, it can get values from a higher level in the hierarchy. If an input is connected to an output, the output and its module are shown below the variable using dot notation.<br />
<br style="clear: both" /><br />
<br />
===Modeling principles===<br />
<br />
System dynamics modelling is much more than just mathematical formulas and nice graphs. Models are ways of communicating. There are some basic principles in system dynamics modelling that make the models easier to read and understand. You do not have to apply these principles to simulate models, but using them makes it easier for you to communicate your model to others.<br />
<br />
;Variable names<br />
:Variables names should be nouns, not verbs. The names should be positive: for example it is easier to understand that satisfaction decreases than dissatisfaction rises. <br />
<br />
:Variable names can and should have multiple words, if they are needed. Unfortunately current version of the tool does not support spaces in variable names. A good practice is to use CamelCase if name contains multiple words. This means that you start every word woth a capital letter (example: ExampleVariable).<br />
<br />
;Connections<br />
:You should try to avoid overlapping dependency arrows. In some situations, however, it is not possible. Dependencies should also form distinctive loops, if there is a loop. It makes it easier to read and understand the model and its behavior.<br />
<br />
;Graphical annotations<br />
:System dynamics contains usually annotations for loops, polarities, delays and so on. Currently those annotations are not supported, but the support will be added later. Annotations are important, again, for communicating the behavior of the model.<br />
<br />
==Installation Instructions==<br />
<br />
System dynamics tool is a provided with the Simantics platform.<br />
<br />
# [https://www.simantics.org/simantics/download Download installer from Simantics download page]<br />
# Install the program to a directory without spaces (limitation inherited from OpenModelica).<br />
# Run the application through the launcher generated by the installer<br/><br />
: (default: Simantics\Simantics-1.6.0-Sysdyn-32\Simantics-1.6.0-Sysdyn-32)<br />
<br />
[http://www.openmodelica.org/ OpenModelica] is used to build and simulate the models. Simantics platform has integrated OpenModelica 1.8.1 for Windows environments. For other versions and other environments you need to install [http://www.openmodelica.org/index.php/download OpenModelica].<br />
<br />
== Workbench ==<br />
<br />
[[File:BasicWorkbench.png|center|729px]]<br />
<br />
<br />
# '''Diagram''' <br /> Diagram is the area where you will graphically modify your model. Diagrams are built from elements that can be dragged from Symbols view or populated using shortcut keys. <br />
# '''Model Browser''' <br /> Model browser shows the structure of your model and all items related to it. <br /> Symbols view is stacked with the model browser and used for dragging elements to diagrams.<br />
# '''Properties''' <br /> Property view shows the selected variable's properties. Property view has a different layout depending on the type of the selected component. The view can also have different tabs depending on the component type. Basic tabs are with variables are Equation and Additional information.<br />
# '''Trend''' <br /> Trend view shows the graphical representation of the values of the selected value over time. For the trend to be shown, a simulation has to be run. The view shows always the results of the latest run, but you can save results of a simulation and show them in the same trend with results from another simulation. Values view and Dependencies are stacked with Trend view and can also be used for analyzing the model.<br />
# '''Experiment controls''' <br /> Experiment controls are shown when an experiment is active. Experiment is activated by double clicking an experiment in the model browser. With the experiment control, you can start simulation runs and save simulation results.<br />
<br />
<br /><br />
If you accidentally close a view, you can reopen them from Window->Show View->Other...<br />
<br />
== Modelling ==<br />
<br />
===Basic modelling===<br />
<br />
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.<br />
<br />
[[File:Basic_1.png|right]]<br />
;Creating a new model<br />
:Start a new model by right-clicking the model browser and selecting New->Model or from the main menu File->New Model.<br />
<br style="clear: both" /><br />
<br />
[[File:Basic_2.png|right]]<br />
;Creating a new module type<br />
:Create a new module type by right-clicking on the Modules-folder and selecting New->Module. This creates a new module type that you can populate to your other modules and the model configuration. <br />
<br style="clear: both" /><br />
<br />
;Configuring a model<br />
:Model configuration can be opened by double clicking Configuration in the model browser. <br />
<br />
;Configuring modules<br />
: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 module!<br />
<br />
;Populate variables<br />
:You can drag variables to a diagram from symbol view. You can also populate variables using [[#Shortcut and control keys|shortcut keys]]<br />
<br />
;Populate modules<br />
:Modules are populated from the model browser. Just drag the module you want to populate from the Modules folder to a diagram.<br />
<br />
;Create connections<br />
: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.<br />
: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.<br />
: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.<br />
<br />
;Connections between modules<br />
:'''Outside the module''' <br /><br />
:You can connect variables to variables in modules like this:<br />
MODULE -----> INPUT<br />
or<br />
ANY VARIABLE -----> MODULE <br />
:This is just the visual configuration, but you need those connections to really connect variables in the module's properties.<br />
:In Inputs -tab you select which variables you connect to inputs inside the module. In Outputs -tab you select which variables you lift from the module to inputs outside it.<br />
<br />
:'''Inside the module''' <br /><br />
:Input variables get values from outside the module<br />
<br />
:Output variables can send their values outside the module. From the variable properties, select Additional Information and press Is Output<br />
<br />
;Configure variables<br />
:Select a single variable from diagram or model browser. The properties of the variables are shown in the equation view and you can modify them.<br />
<br />
;Export model<br />
: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 to for example create different versions of the model, create backups or to transport it to another database.<br />
<br />
;Import model<br />
:Right-click on the model browser and select Import->Model. Browse to your .tg file and select open. The model is added to your model browser.<br />
<br />
=== Special variables ===<br />
<br />
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.<br />
<br />
;WithLookup<br />
WithLookup variable has two equation fields, WithLookup and Lookup table. Lookup table has a table from which the value of the variable is interpolated using the value of WithLookup field.<br />
<br />
[[File:WithLookup1.png]]<br />
<br />
You do not need to manually input the Lookup table. WithLookup variable type offers an additional Lookup table tab in the property view. In this view you can add and modify points in the lookup table. Points can be added either by clickin on the chart or by using the input fields and Add button. Points can be modified by dragging them on the chart or modifying values in the table. Points are removed by clicking them with right mouse click. <br />
<br />
[[File:WithLookup2.png]]<br />
<br />
;Delay<br />
Delay variables build equations for Nth order delays. Users can set the equation for the value that is to be delayed, the time and order of the delay and a possible start value. If start value is empty, the start value is set automatically. <br />
<br />
[[File:Delay1.png]]<br />
<br />
Different order delays have slightly different curves when a step change is triggered. The example picture below shows a step change from 0 to 1 at time 1 with four different delays: 1st, 2nd, 3rd and 10th order delays. <br />
<br />
[[File:Delay2.png]]<br />
<br />
For further information on how the delays work, you can look at the equations that are created by the delay variable. Below is a third order delay. Delay3 is the actual variable that is seen by users. DelayClass has as many level (LV) variables as the order of the delay is. <br />
<br />
Definitions:<br />
Real Delay3;<br />
Delay3_delayClass Delay3_delayClass_instance(initialValue = 0, delayTime = 1);<br />
class Delay3_delayClass<br />
parameter Real DL = delayTime/3;<br />
parameter Real delayTime;<br />
parameter Real initialValue;<br />
Real delay0;<br />
Real LV1(fixed=true, start=initialValue * DL);<br />
Real delay1;<br />
Real LV2(fixed=true, start=initialValue * DL);<br />
Real delay2;<br />
Real LV3(fixed=true, start=initialValue * DL);<br />
Real delay3;<br />
equation<br />
der(LV1) = - delay1 + delay0;<br />
delay1 = LV1 /DL;<br />
der(LV2) = - delay2 + delay1;<br />
delay2 = LV2 /DL;<br />
der(LV3) = - delay3 + delay2;<br />
delay3 = LV3 /DL;<br />
end Delay3_delayClass;<br />
<br />
The above definitions can be seen as a line of stocks and valves. The first valve, delay0, is given the value of the delayed expression. Delay3 is given the value of the valve that is coming from the last stock. <br />
<br />
Equations:<br />
Delay3_delayClass_instance.delay0 = Step1;<br />
Delay3 = Delay3_delayClass_instance.delay3;<br />
<br />
===Shortcut and control keys===<br />
<br />
Shortcut keys for configuring a model on diagram.<br />
<br />
{|<br />
|Esc <br />
|Cancel operations (e.g. connection and rename).<br />
|-<br />
|Shift + A <br />
|Hover Auxiliary at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + S<br />
|Hover Stock at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + C<br />
|Hover Cloud at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + V<br />
|Hover Valve at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + I<br />
|Hover Input at the cursor position, populate with left mouse button.<br />
|-<br />
|Alt + left mouse button<br />
|Start an arrow from a variable. End to another variable by clicking left mouse button.<br />
|-<br />
|Alt + right mouse button<br />
|Start flow from a variable. End by clicking left mouse button.<br />
<br />
If a flow is not started or ended on to a variable, a cloud will be created to that end. <br /><br />
If a new flow does not have a valve at either end, a valve will be created in the middle of the flow.<br />
|-<br />
|Delete<br />
|Remove selected variables<br />
|-<br />
|Ctrl + left mouse button<br />
|Select multiple variables<br />
|-<br />
|Mouse wheel or<br/>+ and -<br />
|Diagram zoom<br />
|-<br />
|drag(mouse3) or<br/>drag(shift + any mouse button)<br />
|Diagram pan<br />
|-<br />
|Ctrl + C<br />
|Copy selected elements<br />
|-<br />
|Ctrl + X<br />
|Cut selected elements<br />
|-<br />
|Ctrl + V<br />
|Paste copied or cut elements<br />
|-<br />
|G<br />
|Show / hide grid<br />
|-<br />
|R<br />
|Show / hide ruler<br />
|-<br />
|1<br />
|Fit diagram contents to screen<br />
|}<br />
<br />
Other shortcut keys can be found selecting Window -> Preferences from the main menu. Keys are located in General -> Keys.<br />
<br />
== Simulation ==<br />
There are three different ways for simulating a model. Different simulations are represented as different types of experiments in Simantics System Dynamics. <br />
<br />
Experiments are created from the context menu of experiments folder in a model. <br />
<br />
[[File:NewExperiment.png]]<br />
<br />
Double-click on an experiment activates it and displays experiment type specific controls in the main tool bar.<br />
<br />
;Normal simulation<br />
: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.<br />
<br />
;Game simulation<br />
:Game simulations allow simulating an arbitrary number of steps, changing parameter values and continuing simulation with the new values from where it previously ended.<br />
<br />
;Simulation playback<br />
:Simulation playback works essentially as the basic experiment, but it offers some additional visualization options.<br />
<br />
== Simulation result and model structure analysis ==<br />
Simulation results can be viewed as trends in trend view or as plain numbers in values view. The views display results of variables that are selected in the workbench. Users can also create [[#Custom charts |custom charts]].<br />
<br />
Model structure can be examined in the Structure view. There are two options: Dependency structures of individual variables or the complete hierarchy structure of the model.<br />
<br />
;Trend<br />
:Shows you the values of the selected variable(s) graphically over the simulation time. You can modify the trend and zoom it using the context menu (right-click) of the trend. <br /> [[File:Trend.png]]<br />
<br />
;Values<br />
:Shows you the values of the selected variable(s) in a table form. If the value has a star (*) at the end, it means that the value is an approximate. There is no value for that variable for the given time step. Selected values can be copied to other software in csv format.<br /> [[File:Values.png]]<br />
<br />
;Compare results<br />
:You can compare different results of the same model by saving simulation results and displaying the saved results side by side with other results. You can save your results after simulating by clicking the save button [[File:Saveresults.png]] on your experiment controls. The saved results appear to model browser under the active experiment. To show the results on trends and tables, right-click on the result and select Show on charts. <br /> [[File:CompareTrend.png]]<br />
<br />
;Dependencies<br />
:Dependencies display which variables affect and which are affected by the selected variable. The direction and number of steps that are traveled from the selected variable can be configured at the bottom of the view. <br /> [[File:Dependencies.png]]<br />
<br />
;Model Hierarchy<br />
:Model Hierarchy displays the hierarchical structure of the model. The module type where a selected variable is located is highlighted.<br /> [[File:ModelHierarchy.png]]<br />
<br />
== Custom charts ==<br />
Custom charts are user-defined displays of simulation result data. They can be used and re-used in various places. The three types of custom charts (line, bar and pie charts) provide model developers means for examining and developing their models and communicating the simulation results to others. <br />
<br />
Custom charts are created to the Charts folder in model browser.<br />
<br />
[[File:NewChart.png | Creating a new chart]]<br />
<br />
Charts are configured the same way as variables: first select the chart from model browser and then configure it in the property view. Charts can be viewed in the same active trend view as any variable by selecting the chart from model browser. In addition to trend view, charts can be populated directly to the model diagram or to a separate chart panel that can contain multiple charts. <br />
<br />
=== Line chart ===<br />
<br />
Line char 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.<br />
<br />
[[File:LineChart.png|Line chart with an array variable]]<br />
<br />
[[File:LineChartGeneral.png|General settings of line chart]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|The title of the chart. Displayed in the chart<br />
|-<br />
|Type<br />
|Line chart (default) or area chart<br />
|-<br />
|Hide<br />
|Options to hide chart grid, title or legend<br />
|-<br />
|'''X-axis'''<br />
|<br />
|-<br />
|Variable<br />
|A variable that is used as the x-axis variable. The default variable is time and it needs not to be typed in the field.<br />
|-<br />
|Label<br />
|Optional other label for the variable than its name<br />
|-<br />
|Min<br />
|Minimum value of the x-axis<br />
|-<br />
|Max<br />
|Maximum value of the x-axis<br />
|-<br />
|Hide<br />
|Options to hide x-axis lable, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
[[File:LineChartAxisAndVariables.png|Axis and variables settings of line chart]]<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed.<br />
|-<br />
|Color<br />
|Color for the lines of this variable<br />
|-<br />
|Line width<br />
|The width of the lines drawn for this variable<br />
|}<br />
There are also configuration options for y-axis. They are displayed when an axis is selected in the Axis and variables tab.<br />
{|<br />
|'''Y-axis'''<br />
|<br />
|-<br />
|Label<br />
|Label of the axis<br />
|-<br />
|Min<br />
|Minimum value in the axis<br />
|-<br />
|Max<br />
|Maximum value in the axis<br />
|-<br />
|Color<br />
|The color of the axis lines, ticks and labels<br />
|-<br />
|Hide<br />
|Options to hide parts of the axis: label, axis line, tick marks, tick labels<br />
|-<br />
|}<br />
<br />
=== Bar chart ===<br />
Bar charts display variables in a certain point in time. The point can be defined for the complete chart in cart'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. <br />
<br />
[[File:BarChartGeneral.png|General bar chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Name is displayed in model browser.<br />
|-<br />
|Title<br />
|The title of the chart. Title is displayed in the chart, if not hidden<br />
|-<br />
|Type<br />
|Normal or stacked. Normal type displays all variables in separate bars. Stacked mode is able to display one-dimensional array variables in stacks.<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Option for hiding grid, title and Legend. Legend is hidden by default since it only contains the information that the current simulation is displayed.<br />
|-<br />
|}<br />
<br />
[[File:BarChartInDiagram.png|Bar chart in a model diagram]]<br />
<br />
Charts can be added to model diagrams simply by dragging the chart from model browser to diagram.<br />
<br />
[[File:BarChartVariable.png|Settings for a variable in bar chart]]<br />
<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|}<br />
[[File:BarChartAxis.png|Settings for axis in bar chart]]<br />
{|<br />
|'''Domain axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for x axis<br />
|-<br />
|Label angle<br />
|Axis labels can be displayed in an angle. This value determines the angle in degrees.<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|'''Range axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for y axis<br />
|-<br />
|Min<br />
|Minimum value of y axis<br />
|-<br />
|Max<br />
|Maximum value of y axis<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
=== Pie chart ===<br />
<br />
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.<br />
<br />
[[File:PieChartGeneral.png|General pie chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|Title The title of the chart. Displayed in the chart<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Options for hiding title, section labels and legend<br />
|-<br />
|}<br />
<br />
[[File:PieChartVariable.png|Variable settings in pie chart]]<br />
{|<br />
|'''Variables'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Color<br />
|Color for the sector of this variable<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|Exploded<br />
|If set, the sector(s) of the variable(s) are "exploded" away from the center of the pie chart<br />
|-<br />
|}<br />
<br />
[[File:PieChartChartPanel.png|Pie chart in chart panel]]<br />
<br />
=== Chart panel ===<br />
[[File:ChartPanel.png|right]]<br />
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.<br />
<br />
Chart panel can be either horizontally or vertically oriented. Different orientations help in configuring the workbench perspective. <br />
<br />
[[File:ChartPanelOrientation.png|Chart panel orientation]]<br />
<br />
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.<br />
<br />
By default, chart panel is hidden in the upper-left corner of the system dynamics perspective.<br />
<br style="clear: both" /><br />
<br />
== Multidimensional variables ==<br />
<br />
<br />
=== Modeling ===<br />
<br />
Models with multidimensional variables look just like any other models. The structure of the models is replicated givin multiple indexes to variables. For users with programming background, notation Variable[] may be familiar. In system dynamic modeling we need to give names to the indexes. Instead of using numbers to define the indexes, like in normal programming, we use enumerations. The steps to create a model with multidimensional variables are as follows (with examples):<br />
<br />
# '''Create the model structure''' <BR />Model with multidimensional variables looks just like any other model.<BR /> [[File:ModelWithMultidimensionalVariables.png|300px|Model with multidimensional variables]]<br />
# '''Create Enumerations and define the indexes''' <BR />Enumerations are created by right-clicking configuration and selecting New->Enumeration.<BR /> [[File:NewEnumeration.png|250px|New enumeration]]<BR />Define enumeration indexes by adding as many indexes as you want. Rename the indexes by selecting them and then clicking on them again.<BR />[[File:DefineIndexes.png|200px|Index definitions]]<br />
# '''Add Enumerations for variables''' <BR />Select the variable that you want to be multidimensional. From the Indexes -tab in the property view, move the wanted enumerations to the right. The order of the enumerations does matter.[[File:SelectEnumerations.png|500px|Select enumerations for variables]]<br />
# '''Define equations for all possible indexes''' <BR />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 indexes, so the resulting definition can be {{1,2,3},{4,5,6},{7,8,9}}.<BR />[[File:DefineEquations.png|500px|Define equations for all indexes]]<br />
<br />
<br />
<br />
=== Expressions ===<br />
<br />
Values for all cells in the variable matrix can be defined in a single expression. <br />
<br />
[[File: DefineEquations.png|600px]]<br />
<br />
[[File:DefineEquations2.png|600px]]<br />
<br />
In many situations, it is however more clear to define separate expressions for each cell or blocks. <br />
<br />
# '''Define range for the expression'''<BR /> [[File:DefineRange.png]]<br />
# '''Define the expression''' (dimensions of the defined range and the result of the expression must match!) <BR /> [[File:DefineEquations3.png]]<br />
# '''Create a new expression''' <BR /> [[File:CreateNewExpression.png]]<br />
#''' Select the new expression''' <BR /> [[File:SelectNewExpression.png]]<br />
<br />
Repeat until there is value for each cell. There must be exactly one value for each cell.<br />
<br />
=== Array slices ===<br />
<br />
Many times it is useful to access a slice of a multidimensional variable. In this chapter, we will use the following example variable:<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
The whole variable can be accessed in three different ways:<br />
# Auxiliary<br />
# Auxiliary[E1, E2]<br />
# Auxiliary[:, :]<br />
<br />
The following explains different methods for accessing parts of the variable<br />
<br />
// Single cell<br />
Auxiliary[one, eins] = 1<br />
<br />
// Slices<br />
Auxiliary[one, E2] = {1,2,3}<br />
Auxiliary[E1, zwei] = {{2},{5},{8}}<br />
<br />
// In addition to single cells and the whole enumeration range, a subrange of the enumeration can be used<br />
Auxiliary[two : three, E2] = {{4,5,6},{7,8,9}}<br />
Auxiliary[one : two, zwei : drei] = {{2,3},{5,6}}<br />
<br />
The syntax for accessing parts of variables can be used in both expression range definitions and in expressions.<br />
<br />
=== Arithmetic Operators ===<br />
<br />
Arithmetic operations are defined in Modelica. Below are examples of different operations.<br />
<br />
;Addition and substraction<br />
Addition and substraction are calculated elementwise<br />
<br />
{1,2,3} - {0,2,3} = {1,0,0}<br />
{{2,2},{4,4}} + {{8,8},{1,1}} = {{10,10},{5,5}}<br />
{1,2,3} - {1,2} = ERROR! Different array sizes<br />
<br />
;Division<br />
Division with a scalar<br />
{5,10,15} / 5 = {1,2,3}<br />
5 / {5,10,15} = ERROR! not allowed<br />
<br />
Division with an array<br />
{1,2,3} / {1,2,3} = ERROR! not allowed<br />
<br />
// Elementwise<br />
{1,2,3} ./ {1,2,3} = {1,1,1}<br />
<br />
;Multiplication<br />
<br />
Multiplication with a scalar<br />
{1,2,3} * 2 = {2,4,6}<br />
5 * {1,2,3} = {5,10,15}<br />
<br />
Matrix multiplication with an array<br />
{{3,4},{5,6}} * {1,2} = {11,17}<br />
{{3,4},{5,6}} * {1,2,3} = ERROR! incompatible array sizes<br />
<br />
//Elementwise<br />
{1,2} .* {1,2} = {1,4}<br />
<br />
Real[3,2] c = {{1,2},{3,4},{5,6}}; <br />
Real[2,2] d = {{3,4},{5,6}};<br />
Real[2,2] cd;<br />
cd = c[2:3, :] .* d; // Result: {{9,16},{25,36}}<br />
<br />
;Power<br />
Elementwise power of array variable<br />
{1,2} .^ 2 = {1,4}<br />
<br />
=== Builtin Modelica functions ===<br />
<br />
Modelica has some builtin functions that help using multidimensional variables. This chapter introduces some of the builtin functions. <br />
<br />
;Dimension and size functions<br />
<br />
We will use the same example variable as previously.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
;ndims(A)<br />
The number of dimensions in array A<br />
ndims(Auxiliary) = 2<br />
<br />
;size(A, i)<br />
The size of dimension i in array A<br />
size(Auxiliary, 2) = 3<br />
<br />
;size(A)<br />
A vector of length ndims(A) containing the dimension sizes of A<br />
size(Auxiliary) = {3,3}<br />
<br />
<br />
;Construction functions<br />
In addition to normal array constructing, a special construction functions can be used.<br />
<br />
;zeros(n1,n2,n3,...)<br />
An array full of zeros with dimensions n1 x n2 x n2 x ... <br />
zeros(2, 2) = {{0,0}, {0,0}}<br />
<br />
;ones(n1,n2,n3,...)<br />
An array full of ones with dimensions n1 x n2 x n2 x ... <br />
ones(2, 2) = {{1,1}, {1,1}}<br />
<br />
;fill(s,n1,n2,n3)<br />
Like zeros() and ones(), but with user defined value (s) for array elements.<br />
fill(3,2,2) = {{3,3}, {3,3}}<br />
<br />
;identity(n)<br />
Creates an n x n integer identity matrix with ones on the diagonal and all other elements zero.<br />
identity(3) =<br />
1 0 0<br />
0 1 0<br />
0 0 1<br />
<br />
;diagonal(v)<br />
Constructs a square matrix with elements of vector v on the diagonal and all other elements zero.<br />
diagonal({1,2,3}) =<br />
1 0 0<br />
0 2 0<br />
0 0 3<br />
<br />
;linspace(x1,x2,n)<br />
Constracts a Real vector from x1 to x2 with n equally spaced elements.<br />
linspace(2,5,4) = {2,3,4,5}<br />
<br />
;Reduction functions<br />
<br />
Reduction functions reduce arrays to scalars.<br />
<br />
;min(A)<br />
Returns the minimum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
min(A) = 1<br />
<br />
;max(A)<br />
Returns the maximum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
max(A) = 4<br />
<br />
;sum(A)<br />
Returns the sum of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
sum(A) = 10 // 1 + 2 + 3 + 4<br />
<br />
;product(A)<br />
Returns the product of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
product(A) = 24 // 1 * 2 * 3 * 4<br />
<br />
<br />
;Using functions with iterators<br />
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.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
AuxiliarySum[E1] = {sum( Auxiliary[ i , E2 ] ) for i in E1} // Result: {6, 15, 24}<br />
<br />
/* Same as:<br />
{sum(Auxiliary[one, E2]), sum(Auxiliary[two, E2]), sum(Auxiliary[three, E2])}<br />
{sum({1,2,3}), sum({4,5,6}), sum({7,8,9})}<br />
*/<br />
<br />
One expression can have multiple iterators. The Modelica specification defines the following format, but it is NOT yet supported in OpenModelica:<br />
{sum(Array[ i, j, E3]) for i in E1, j in E2} // Dimensions reduced from 3 to 2<br />
<br />
To use multiple iterators, use the following format (NOTE the reversed order of iterators!):<br />
{{sum(Array[ i, j, E3]) for j in E2} for i in E1} // Dimensions reduced from 3 to 2<br />
<br />
The range doesn't have to be the whole enumeration. Subranges can also be used.<br />
{sum( Auxiliary[ i , eins : zwei ] ) for i in E1.one : E1.two} // Result: {3, 9}<br />
<br />
/* Same as<br />
{sum(Auxiliary[one, eins : zwei]), sum(Auxiliary[two, eins : zwei])}<br />
{sum({1,2}), sum({4,5})}<br />
*/<br />
<br />
=== Simulation results ===<br />
<br />
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. <br />
<br />
[[File:3x3trend.png|300px|Trend view for a 3x3 variable]]<br />
<br />
The clutter can be reduced by selecting which enumeration indexes are shown in charts. Select an enumeration and tick the indexes 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.<br />
<br />
[[File:ShowInCharts.png|500px|Select indexes to show in charts]]<br />
<br />
<br />
=== Array Variables in Modules ===<br />
<br />
[[File:Replaceable.png|frame|Replaceable enumeration inside a module]]<br />
<br />
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 [[Simantics_System_Dynamics#Modeling|Modeling]]). <br />
<br />
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.<br />
<br />
<br />
<br style="clear: both" /><br />
<br />
In this example, the original enumeration that the modeler used had two indexes. We are using an instance of this module, but we need to use array variables that have three indexes instead of two. We are using two variables and an instance of the module.<br />
<br />
[[File:ReplacingEnumerationConfiguration.png|frame|left|500px|Module configuration for replacing enumerations inside the module]]<br />
<br style="clear: both" /><br />
<br />
In the parent configuration, we have used an enumeration with three indexes in the two variables.<br />
<br />
[[File:Replacing.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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 clickin 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.<br />
<br />
<br />
[[File:ReplacingEnumeration.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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!<br />
<br />
== Functions ==<br />
<br />
Modelica provides a convenient way to use functions in your models. You can create your own functions, import complete function libraries and share function libraries to be used in all of your models. <br />
<br />
=== Creating functions ===<br />
<br />
[[File:NewFunction.png|right]]<br />
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.<br />
<br />
Functions that can be found from Functions -folder can be used in your variable definitions.<br />
<br />
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. <br />
<br />
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.<br />
<br />
Below is an example of a simple function. For more examples, see the built-in functions provided with the tool and [https://www.modelica.org/documents/ Modelica specifications].<br />
<br />
<br style="clear: both" /><br />
<br />
[[File:ExampleFunction.png]]<br />
<br />
=== Function libraries ===<br />
<br />
<br />
[[File:NewFunctionLibrary.png|right]]<br />
<br />
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)).<br />
<br />
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. <br />
<br />
Create a new function library by right-clicking on Functions folder, Shared functions folder or other module library.<br />
<br />
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.<br />
<br />
[[File:SharedFunctions.png]]<br />
<br style="clear: both" /><br />
<br />
=== External functions ===<br />
<br />
Modelica allows you to use external functions that are programmed using C language. Below is a simple example of using a function that returns the sum of two arguments. <br />
<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}<br />
<br />
<br />
[[File:ImportCFunctionLibrary.png|right]]<br />
<br />
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 <br />
(e.g. simantics_home/plugins/org.simantics.openmodelica.win32_x/MinGW/bin/mingw32_gcc.exe -g -O -c ExampleCFunctionCode.c). <br />
<br style="clear: both" /><br />
<br />
[[File:ExampleExternalFunction.png]]<br />
<br />
<br />
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.<br />
<br />
[[File:ExternalFunctionResult.png]]<br />
<br />
<br />
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.<br />
<br />
<br />
Small external C function can also be written directly to the function code in Simantics Sysdyn:<br />
function ExampleExternalFunction<br />
input Real x;<br />
input Real y;<br />
output Real z;<br />
external "C" z=exampleCFunction(x,y) annotation(Include="<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}");<br />
end ExampleExternalFunction;<br />
<br />
=== Modelica functions ===<br />
<br />
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 [[Simantics_System_Dynamics#Builtin_functions|builtin functions for arrays]].<br />
<br />
{|<br />
|abs(x)<br />
|Returns the absolute value of x. Expanded into "(if x >= 0 then x else -x)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|acos(x)<br />
|Inverse cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|asin(x)<br />
|Inverse sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan(x)<br />
|Inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan2(x1,x2)<br />
|four quadrant inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cat(n,A,B,...)<br />
|General concatenation function that concatenates arrays A,B,... along the nth dimension.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|ceil(x)<br />
|Returns the smallest integer not less than x, the closest integer above x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cos(x)<br />
|Cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cosh(x)<br />
|Hyperbolic cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cross(x,y)<br />
|Returns the 3-vector cross product of the 3-vectors x and y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|delay(expr, delayTime)<br />
|Returns the value of expr at the time time-delayTime. The value of expr is returned when time <= time.start + delayTime.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|der(x)<br />
|Time derivative of x. X must be have continuous-time variability.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|div(x, y)<br />
|Returns the algebraic quotient x/y with any fractional part discarted. E.g. div(10,3) = 3.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|edge(b)<br />
|Returns true when the value of the boolean expression b changes. Expanded into (b and not pre(b)).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|exp(x)<br />
|Exponential, base e.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|floor(x)<br />
|Returns the largest integer not greater than x, the closest integer below x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|initial()<br />
|Returns true at the beginning of the simulation. <br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|integer(x)<br />
|Returns the largest integer not greater than x as an integer.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log(x)<br />
|Natural logarithm. (base e, x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log10(x)<br />
|Base 10 logarithm. (x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|mod(x, y)<br />
|Returns the integer modulus of x/y: mod(x,y) = x - floor(x/y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|noEvent(expr)<br />
|noEvent around an expression causes the expression to NOT generate event.<br />
'''Important:''' <br />
:If you want a condition to be checked only on time steps, use noEvent.<br />
:(e.g. if noEvent(value >= 1) then ... else ...)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|pre(x)<br />
|Returns the preceding value of y from time event that has occured before current time.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|rem(x, y)<br />
|Returns the integer remainder of x/y: rem(x,y) = x - div(x,y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sample(start, interval)<br />
|Returns true and triggers time events at times start + i * interval (i=0,1,...).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sign(x)<br />
|Returns -1 if x is negative, 1 if x is positive. Expanded into "(if x > 0 then 1 else if x < 0 then -1 else 0)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sin(x)<br />
|Sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sinh(x)<br />
|Hyperbolic sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sqrt(x)<br />
|Square root of x. The value of x must be greater or equal to 0 or an assertion error occurs.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tan(x)<br />
|Tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tanh(x)<br />
|Hyperbolic tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|terminal()<br />
|Returns true at the end of a successful simulation.<br />
|}<br />
<br />
== Spreadsheets ==<br />
<br />
Spreadsheets allow storing and maintaining values in a familiar format. The current spreadsheet implementation is experimental and does not provide much functionality. Some basic tasks can, however, be performed. You cannot type directly to a cell, you need to first copy some value or text into it. Then it can be modified.<br />
<br />
=== Variable values ===<br />
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.<br />
<br />
[[File:AuxiliarySheetReference.png|Sheet reference in an expression]][[File:AuxiliarySheet.png|Value of a variable in sheet]]<br />
<br />
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 indexes are not mandatory, but help reading and maintaining the sheet.<br />
<br />
[[File:SheetForMultidim.png|Spreadsheet for multidimensional variables]]<br />
<br />
Reference to a sheet range creates an array variable.<br />
<br />
[[File:SheetMultidim1.png|Array variable ArrayTest1[2] with sheet reference]]<br />
<br />
ArrayTest2 has two dimensions. Reference to a larger range creates a two-dimensional variable. By default, the indexes are ordered as in this example. However, if you wish to present the indexes in a different order in the spreadsheet, you can transpose the sheet reference (e.g. transpose(ArrayTestSheet(E2:G3)))<br />
<br />
[[File:SheetMultidim2.png|Array variable ArrayTest2[2,3] with sheet reference]]<br />
<br />
=== History data ===<br />
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.<br />
<br />
[[File:Sheet.png|Spreadsheet with history data]]<br />
<br />
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. <br />
<br />
[[File:HistoryDataSettings.png|History data settings]]<br />
<br />
{|<br />
|'''History data properties'''<br />
|<br />
|-<br />
|Name<br />
|Name of the history dataset<br />
|-<br />
|Sheet<br />
|Combo box for selecting a sheet where the history data is located<br />
|-<br />
|Orientation<br />
|Columns or rows. How the data is arranged in the sheet.<br />
|-<br />
|Range start<br />
|The upper-left corner cell of the history data range<br />
|-<br />
|Range end<br />
|The lower-right corner cell of the history data range<br />
|-<br />
|Time variable<br />
|The name of the time variable in the history data, if it is different than "time"<br />
|-<br />
|Variables in range<br />
|This text field displays the found variables in the given sheet and range<br />
|-<br />
|}<br />
<br />
If the history dataset is activated, history data is displayed whenever it is available for a variable that is displayed in a chart.<br />
<br />
[[File:HistoryData.png|History data in two charts]]<br />
<br />
<br />
<center><br />
[[Simantics]] | ''System Dynamics Modelling''<br />
</center><br />
<br />
----<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Basic System Dynamics Modelling]]'''<br><br />
System dynamics modelling in Simantics is a free modelling tool that is included into the basic installation. This tutorial introduces the basic features of the system dynamics modelling tool.<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Advanced System Dynamics Modelling]]'''<br><br />
This tutorial introduces the more advanced features of the system dynamics modelling tool: Modules and Operating interfaces<br />
<br />
[[Category: Simantics System Dynamics]]</div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:Delay2.png&diff=589File:Delay2.png2012-10-26T06:28:12Z<p>Teemu Lempinen: </p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:Delay1.png&diff=588File:Delay1.png2012-10-26T06:28:09Z<p>Teemu Lempinen: </p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:WithLookup2.png&diff=587File:WithLookup2.png2012-10-26T06:28:03Z<p>Teemu Lempinen: </p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:WithLookup1.png&diff=586File:WithLookup1.png2012-10-26T06:27:59Z<p>Teemu Lempinen: </p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=Simantics_System_Dynamics&diff=585Simantics System Dynamics2012-10-26T06:27:41Z<p>Teemu Lempinen: /* Basic modelling */</p>
<hr />
<div>== Simantics System Dynamics ==<br />
<br />
Simantics System Dynamics is currently the only open source modelling and simulating tool for Simantics. Simantics System Dynamics is under development and will go through some changes in the future. New features will be added and old ones improved according to the needs of the modellers. New features include module libraries and different analysis tools.<br />
<br />
This documentation introduces you to the current version of Simantics System Dynamics. Documentation includes the basic modelling principles and a guide on how to model system dynamics models with Simantics System Dynamics. If you like to get to know the tool better and try modelling and simulating yourself, [[#Installation Instructions|install]] the software and try our [[Tutorial: Basic System Dynamics Modelling|basic]] and [[Tutorial: Advanced System Dynamics Modelling|advanced]] tutorials!<br />
<br />
== Introduction to System Dynamics Simulation ==<br />
<br />
===System Dynamics===<br />
System dynamics is an approach to understanding different organizations, markets and other complex systems and their dynamic behavior. System dynamics modelling in Simantics is a free modelling tool. See [[#Installation Instructions|installation instructions]].<br />
<br />
===Model===<br />
[[File:ModelStructure.png|right|thumb|Model structure]]<br />
System dynamics model is generally understood as the model configuration. In this tool, the model contains also other components. Model can have Operating interfaces that enable the use of the model with simple controls. Operating interfaces are configured separately and when using them, the complex model is hidden from the user. Experiments are the way to simulate the model. In the future, you can have experiments with different configurations, for example different initial values for some parameters. In that way, you don't have to always configure the model for different scenarios. Modules folder contains all the different module types in your model and you can create new module types there. <br />
<br />
<br style="clear: both" /><br />
<br />
===Components===<br />
Most of the components you can use in your models are basic system dynamics components. The modularity of the models introduces two additional components, Modules and Inputs. All the components are explained below.<br />
[[File:ComponentTypes.png|right|frame|Component types]]<br />
;Auxiliary<br />
:Auxiliary is the most basic variable you can use. It represents a single value or a mathematical expression. There are different types of auxiliary variables currently in the system: Auxiliary, Parameter, Constant, Delay and WithLookup. Auxiliary is the default type. Parameters are single values that the user can change. When only parameters are changed, the model simulates faster, because the system does not have to recompile the model. WithLookup and Delay are special variables. WithLookup has an expression and a lookup table. The expresssion defines what value is taken from the defined table. Delay variable delays an equation a given time with a given delay order.<br />
;Dependency<br />
:Dependency is an arrow that connects two components. It means that the value of the variable from which the arrow starts is used to calculate the value of the variable where the arrow ends.<br />
;Flow<br />
:Flow connects clouds, valves and stocks. Flow represents an actual flow of something from stocks or clouds to stocks or clouds. There has to be at least one valve in a flow and the system creates it automatically, if none of the ends of the flow is a valve.<br />
;Valve<br />
:Valve regulates the rate of a flow. The value of a valve is automatically used in calculating the level of an adjacent stock. Valves behave just like Auxiliary variables but look different and you can connect also flows to them.<br />
;Stock<br />
:The value of a stock variable is an integral of flows leaving and flows arriving to the variable. The integral is calculated automatically from the valves that are connected to the variable with flow connections. You must give an initial value to the stock. Initial value can be a single value or an equation. You can use values of other variables to calculate the initial value.<br />
;Cloud<br />
:Cloud is not a variable. It represents a starting or ending point of a flow, if it is not in the scope of the model.<br />
;Module<br />
:Modules enable structural modeling. Modules are defined just like the basic model configuration, but the module component hides the actual configuration. You can only connect dependency connections into the module and dependency connections from the module must end to Input variables. The interface of the module is defined using input and output variables in the configuration of the module. All variable types can be set as output variables. If a variable is an output variable, its font is bold.<br />
;Input<br />
:Input variables are the way of getting values from other modules. Inputs look like auxiliary variables except their font is italics. You can set a default value to the input variable in case it is not connected to any variable. Connections are made from the modules properties, when the module is populated. Input doesn't have to be connected with an arrow to a module. If the variable has no connections, it can get values from a higher level in the hierarchy. If an input is connected to an output, the output and its module are shown below the variable using dot notation.<br />
<br style="clear: both" /><br />
<br />
===Modeling principles===<br />
<br />
System dynamics modelling is much more than just mathematical formulas and nice graphs. Models are ways of communicating. There are some basic principles in system dynamics modelling that make the models easier to read and understand. You do not have to apply these principles to simulate models, but using them makes it easier for you to communicate your model to others.<br />
<br />
;Variable names<br />
:Variables names should be nouns, not verbs. The names should be positive: for example it is easier to understand that satisfaction decreases than dissatisfaction rises. <br />
<br />
:Variable names can and should have multiple words, if they are needed. Unfortunately current version of the tool does not support spaces in variable names. A good practice is to use CamelCase if name contains multiple words. This means that you start every word woth a capital letter (example: ExampleVariable).<br />
<br />
;Connections<br />
:You should try to avoid overlapping dependency arrows. In some situations, however, it is not possible. Dependencies should also form distinctive loops, if there is a loop. It makes it easier to read and understand the model and its behavior.<br />
<br />
;Graphical annotations<br />
:System dynamics contains usually annotations for loops, polarities, delays and so on. Currently those annotations are not supported, but the support will be added later. Annotations are important, again, for communicating the behavior of the model.<br />
<br />
==Installation Instructions==<br />
<br />
System dynamics tool is a provided with the Simantics platform.<br />
<br />
# [https://www.simantics.org/simantics/download Download installer from Simantics download page]<br />
# Install the program to a directory without spaces (limitation inherited from OpenModelica).<br />
# Run the application through the launcher generated by the installer<br/><br />
: (default: Simantics\Simantics-1.6.0-Sysdyn-32\Simantics-1.6.0-Sysdyn-32)<br />
<br />
[http://www.openmodelica.org/ OpenModelica] is used to build and simulate the models. Simantics platform has integrated OpenModelica 1.8.1 for Windows environments. For other versions and other environments you need to install [http://www.openmodelica.org/index.php/download OpenModelica].<br />
<br />
== Workbench ==<br />
<br />
[[File:BasicWorkbench.png|center|729px]]<br />
<br />
<br />
# '''Diagram''' <br /> Diagram is the area where you will graphically modify your model. Diagrams are built from elements that can be dragged from Symbols view or populated using shortcut keys. <br />
# '''Model Browser''' <br /> Model browser shows the structure of your model and all items related to it. <br /> Symbols view is stacked with the model browser and used for dragging elements to diagrams.<br />
# '''Properties''' <br /> Property view shows the selected variable's properties. Property view has a different layout depending on the type of the selected component. The view can also have different tabs depending on the component type. Basic tabs are with variables are Equation and Additional information.<br />
# '''Trend''' <br /> Trend view shows the graphical representation of the values of the selected value over time. For the trend to be shown, a simulation has to be run. The view shows always the results of the latest run, but you can save results of a simulation and show them in the same trend with results from another simulation. Values view and Dependencies are stacked with Trend view and can also be used for analyzing the model.<br />
# '''Experiment controls''' <br /> Experiment controls are shown when an experiment is active. Experiment is activated by double clicking an experiment in the model browser. With the experiment control, you can start simulation runs and save simulation results.<br />
<br />
<br /><br />
If you accidentally close a view, you can reopen them from Window->Show View->Other...<br />
<br />
== Modelling ==<br />
<br />
===Basic modelling===<br />
<br />
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.<br />
<br />
[[File:Basic_1.png|right]]<br />
;Creating a new model<br />
:Start a new model by right-clicking the model browser and selecting New->Model or from the main menu File->New Model.<br />
<br style="clear: both" /><br />
<br />
[[File:Basic_2.png|right]]<br />
;Creating a new module type<br />
:Create a new module type by right-clicking on the Modules-folder and selecting New->Module. This creates a new module type that you can populate to your other modules and the model configuration. <br />
<br style="clear: both" /><br />
<br />
;Configuring a model<br />
:Model configuration can be opened by double clicking Configuration in the model browser. <br />
<br />
;Configuring modules<br />
: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 module!<br />
<br />
;Populate variables<br />
:You can drag variables to a diagram from symbol view. You can also populate variables using [[#Shortcut and control keys|shortcut keys]]<br />
<br />
;Populate modules<br />
:Modules are populated from the model browser. Just drag the module you want to populate from the Modules folder to a diagram.<br />
<br />
;Create connections<br />
: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.<br />
: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.<br />
: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.<br />
<br />
;Connections between modules<br />
:'''Outside the module''' <br /><br />
:You can connect variables to variables in modules like this:<br />
MODULE -----> INPUT<br />
or<br />
ANY VARIABLE -----> MODULE <br />
:This is just the visual configuration, but you need those connections to really connect variables in the module's properties.<br />
:In Inputs -tab you select which variables you connect to inputs inside the module. In Outputs -tab you select which variables you lift from the module to inputs outside it.<br />
<br />
:'''Inside the module''' <br /><br />
:Input variables get values from outside the module<br />
<br />
:Output variables can send their values outside the module. From the variable properties, select Additional Information and press Is Output<br />
<br />
;Configure variables<br />
:Select a single variable from diagram or model browser. The properties of the variables are shown in the equation view and you can modify them.<br />
<br />
;Export model<br />
: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 to for example create different versions of the model, create backups or to transport it to another database.<br />
<br />
;Import model<br />
:Right-click on the model browser and select Import->Model. Browse to your .tg file and select open. The model is added to your model browser.<br />
<br />
=== Special variables ===<br />
<br />
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.<br />
<br />
;WithLookup<br />
WithLookup variable has two equation fields, WithLookup and Lookup table. Lookup table has a table from which the value of the variable is interpolated using the value of WithLookup field.<br />
<br />
[[File:WithLookup1.png]]<br />
<br />
You do not need to manually input the Lookup table. WithLookup variable type offers an additional Lookup table tab in the property view. In this view you can add and modify points in the lookup table. Points can be added either by clickin on the chart or by using the input fields and Add button. Points can be modified by dragging them on the chart or modifying values in the table. Points are removed by clicking them with right mouse click. <br />
<br />
[[File:WithLookup2.png]]<br />
<br />
;Delay<br />
Delay variables build equations for Nth order delays. Users can set the equation for the value that is to be delayed, the time and order of the delay and a possible start value. If start value is empty, the start value is set automatically. <br />
<br />
[[File:Delay1.png]]<br />
<br />
Different order delays have slightly different curves when a step change is triggered. The example picture below shows a step change from 0 to 1 at time 1 with four different delays: 1st, 2nd, 3rd and 10th order delays. <br />
<br />
[[File:Delay2.png]]<br />
<br />
For further information on how the delays work, you can look at the equations that are created by the delay variable. Below is a third order delay. Delay3 is the actual variable that is seen by users. DelayClass has as many level (LV) variables as the order of the delay is. <br />
<br />
Definitions:<br />
Real Delay3;<br />
Delay3_delayClass Delay3_delayClass_instance(initialValue = 0, delayTime = 1);<br />
class Delay3_delayClass<br />
parameter Real DL = delayTime/3;<br />
parameter Real delayTime;<br />
parameter Real initialValue;<br />
Real delay0;<br />
Real LV1(fixed=true, start=initialValue * DL);<br />
Real delay1;<br />
Real LV2(fixed=true, start=initialValue * DL);<br />
Real delay2;<br />
Real LV3(fixed=true, start=initialValue * DL);<br />
Real delay3;<br />
equation<br />
der(LV1) = - delay1 + delay0;<br />
delay1 = LV1 /DL;<br />
der(LV2) = - delay2 + delay1;<br />
delay2 = LV2 /DL;<br />
der(LV3) = - delay3 + delay2;<br />
delay3 = LV3 /DL;<br />
end Delay3_delayClass;<br />
<br />
The above definitions can be seen as a line of stocks and valves. The first valve, delay0, is given the value of the delayed expression. Delay3 is given the value of the valve that is coming from the last stock. <br />
<br />
Equations:<br />
Delay3_delayClass_instance.delay0 = Step1;<br />
Delay3 = Delay3_delayClass_instance.delay3;<br />
<br />
===Shortcut and control keys===<br />
<br />
Shortcut keys for configuring a model on diagram.<br />
<br />
{|<br />
|Esc <br />
|Cancel operations (e.g. connection and rename).<br />
|-<br />
|Shift + A <br />
|Hover Auxiliary at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + S<br />
|Hover Stock at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + C<br />
|Hover Cloud at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + V<br />
|Hover Valve at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + I<br />
|Hover Input at the cursor position, populate with left mouse button.<br />
|-<br />
|Alt + left mouse button<br />
|Start an arrow from a variable. End to another variable by clicking left mouse button.<br />
|-<br />
|Alt + right mouse button<br />
|Start flow from a variable. End by clicking left mouse button.<br />
<br />
If a flow is not started or ended on to a variable, a cloud will be created to that end. <br /><br />
If a new flow does not have a valve at either end, a valve will be created in the middle of the flow.<br />
|-<br />
|Delete<br />
|Remove selected variables<br />
|-<br />
|Ctrl + left mouse button<br />
|Select multiple variables<br />
|-<br />
|Mouse wheel or<br/>+ and -<br />
|Diagram zoom<br />
|-<br />
|drag(mouse3) or<br/>drag(shift + any mouse button)<br />
|Diagram pan<br />
|-<br />
|Ctrl + C<br />
|Copy selected elements<br />
|-<br />
|Ctrl + X<br />
|Cut selected elements<br />
|-<br />
|Ctrl + V<br />
|Paste copied or cut elements<br />
|-<br />
|G<br />
|Show / hide grid<br />
|-<br />
|R<br />
|Show / hide ruler<br />
|}<br />
<br />
Other shortcut keys can be found selecting Window -> Preferences from the main menu. Keys are located in General -> Keys.<br />
<br />
== Simulation ==<br />
There are three different ways for simulating a model. Different simulations are represented as different types of experiments in Simantics System Dynamics. <br />
<br />
Experiments are created from the context menu of experiments folder in a model. <br />
<br />
[[File:NewExperiment.png]]<br />
<br />
Double-click on an experiment activates it and displays experiment type specific controls in the main tool bar.<br />
<br />
;Normal simulation<br />
: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.<br />
<br />
;Game simulation<br />
:Game simulations allow simulating an arbitrary number of steps, changing parameter values and continuing simulation with the new values from where it previously ended.<br />
<br />
;Simulation playback<br />
:Simulation playback works essentially as the basic experiment, but it offers some additional visualization options.<br />
<br />
== Simulation result and model structure analysis ==<br />
Simulation results can be viewed as trends in trend view or as plain numbers in values view. The views display results of variables that are selected in the workbench. Users can also create [[#Custom charts |custom charts]].<br />
<br />
Model structure can be examined in the Structure view. There are two options: Dependency structures of individual variables or the complete hierarchy structure of the model.<br />
<br />
;Trend<br />
:Shows you the values of the selected variable(s) graphically over the simulation time. You can modify the trend and zoom it using the context menu (right-click) of the trend. <br /> [[File:Trend.png]]<br />
<br />
;Values<br />
:Shows you the values of the selected variable(s) in a table form. If the value has a star (*) at the end, it means that the value is an approximate. There is no value for that variable for the given time step. Selected values can be copied to other software in csv format.<br /> [[File:Values.png]]<br />
<br />
;Compare results<br />
:You can compare different results of the same model by saving simulation results and displaying the saved results side by side with other results. You can save your results after simulating by clicking the save button [[File:Saveresults.png]] on your experiment controls. The saved results appear to model browser under the active experiment. To show the results on trends and tables, right-click on the result and select Show on charts. <br /> [[File:CompareTrend.png]]<br />
<br />
;Dependencies<br />
:Dependencies display which variables affect and which are affected by the selected variable. The direction and number of steps that are traveled from the selected variable can be configured at the bottom of the view. <br /> [[File:Dependencies.png]]<br />
<br />
;Model Hierarchy<br />
:Model Hierarchy displays the hierarchical structure of the model. The module type where a selected variable is located is highlighted.<br /> [[File:ModelHierarchy.png]]<br />
<br />
== Custom charts ==<br />
Custom charts are user-defined displays of simulation result data. They can be used and re-used in various places. The three types of custom charts (line, bar and pie charts) provide model developers means for examining and developing their models and communicating the simulation results to others. <br />
<br />
Custom charts are created to the Charts folder in model browser.<br />
<br />
[[File:NewChart.png | Creating a new chart]]<br />
<br />
Charts are configured the same way as variables: first select the chart from model browser and then configure it in the property view. Charts can be viewed in the same active trend view as any variable by selecting the chart from model browser. In addition to trend view, charts can be populated directly to the model diagram or to a separate chart panel that can contain multiple charts. <br />
<br />
=== Line chart ===<br />
<br />
Line char 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.<br />
<br />
[[File:LineChart.png|Line chart with an array variable]]<br />
<br />
[[File:LineChartGeneral.png|General settings of line chart]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|The title of the chart. Displayed in the chart<br />
|-<br />
|Type<br />
|Line chart (default) or area chart<br />
|-<br />
|Hide<br />
|Options to hide chart grid, title or legend<br />
|-<br />
|'''X-axis'''<br />
|<br />
|-<br />
|Variable<br />
|A variable that is used as the x-axis variable. The default variable is time and it needs not to be typed in the field.<br />
|-<br />
|Label<br />
|Optional other label for the variable than its name<br />
|-<br />
|Min<br />
|Minimum value of the x-axis<br />
|-<br />
|Max<br />
|Maximum value of the x-axis<br />
|-<br />
|Hide<br />
|Options to hide x-axis lable, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
[[File:LineChartAxisAndVariables.png|Axis and variables settings of line chart]]<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed.<br />
|-<br />
|Color<br />
|Color for the lines of this variable<br />
|-<br />
|Line width<br />
|The width of the lines drawn for this variable<br />
|}<br />
There are also configuration options for y-axis. They are displayed when an axis is selected in the Axis and variables tab.<br />
{|<br />
|'''Y-axis'''<br />
|<br />
|-<br />
|Label<br />
|Label of the axis<br />
|-<br />
|Min<br />
|Minimum value in the axis<br />
|-<br />
|Max<br />
|Maximum value in the axis<br />
|-<br />
|Color<br />
|The color of the axis lines, ticks and labels<br />
|-<br />
|Hide<br />
|Options to hide parts of the axis: label, axis line, tick marks, tick labels<br />
|-<br />
|}<br />
<br />
=== Bar chart ===<br />
Bar charts display variables in a certain point in time. The point can be defined for the complete chart in cart'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. <br />
<br />
[[File:BarChartGeneral.png|General bar chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Name is displayed in model browser.<br />
|-<br />
|Title<br />
|The title of the chart. Title is displayed in the chart, if not hidden<br />
|-<br />
|Type<br />
|Normal or stacked. Normal type displays all variables in separate bars. Stacked mode is able to display one-dimensional array variables in stacks.<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Option for hiding grid, title and Legend. Legend is hidden by default since it only contains the information that the current simulation is displayed.<br />
|-<br />
|}<br />
<br />
[[File:BarChartInDiagram.png|Bar chart in a model diagram]]<br />
<br />
Charts can be added to model diagrams simply by dragging the chart from model browser to diagram.<br />
<br />
[[File:BarChartVariable.png|Settings for a variable in bar chart]]<br />
<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|}<br />
[[File:BarChartAxis.png|Settings for axis in bar chart]]<br />
{|<br />
|'''Domain axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for x axis<br />
|-<br />
|Label angle<br />
|Axis labels can be displayed in an angle. This value determines the angle in degrees.<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|'''Range axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for y axis<br />
|-<br />
|Min<br />
|Minimum value of y axis<br />
|-<br />
|Max<br />
|Maximum value of y axis<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
=== Pie chart ===<br />
<br />
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.<br />
<br />
[[File:PieChartGeneral.png|General pie chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|Title The title of the chart. Displayed in the chart<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Options for hiding title, section labels and legend<br />
|-<br />
|}<br />
<br />
[[File:PieChartVariable.png|Variable settings in pie chart]]<br />
{|<br />
|'''Variables'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Color<br />
|Color for the sector of this variable<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|Exploded<br />
|If set, the sector(s) of the variable(s) are "exploded" away from the center of the pie chart<br />
|-<br />
|}<br />
<br />
[[File:PieChartChartPanel.png|Pie chart in chart panel]]<br />
<br />
=== Chart panel ===<br />
[[File:ChartPanel.png|right]]<br />
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.<br />
<br />
Chart panel can be either horizontally or vertically oriented. Different orientations help in configuring the workbench perspective. <br />
<br />
[[File:ChartPanelOrientation.png|Chart panel orientation]]<br />
<br />
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.<br />
<br />
By default, chart panel is hidden in the upper-left corner of the system dynamics perspective.<br />
<br style="clear: both" /><br />
<br />
== Multidimensional variables ==<br />
<br />
<br />
=== Modeling ===<br />
<br />
Models with multidimensional variables look just like any other models. The structure of the models is replicated givin multiple indexes to variables. For users with programming background, notation Variable[] may be familiar. In system dynamic modeling we need to give names to the indexes. Instead of using numbers to define the indexes, like in normal programming, we use enumerations. The steps to create a model with multidimensional variables are as follows (with examples):<br />
<br />
# '''Create the model structure''' <BR />Model with multidimensional variables looks just like any other model.<BR /> [[File:ModelWithMultidimensionalVariables.png|300px|Model with multidimensional variables]]<br />
# '''Create Enumerations and define the indexes''' <BR />Enumerations are created by right-clicking configuration and selecting New->Enumeration.<BR /> [[File:NewEnumeration.png|250px|New enumeration]]<BR />Define enumeration indexes by adding as many indexes as you want. Rename the indexes by selecting them and then clicking on them again.<BR />[[File:DefineIndexes.png|200px|Index definitions]]<br />
# '''Add Enumerations for variables''' <BR />Select the variable that you want to be multidimensional. From the Indexes -tab in the property view, move the wanted enumerations to the right. The order of the enumerations does matter.[[File:SelectEnumerations.png|500px|Select enumerations for variables]]<br />
# '''Define equations for all possible indexes''' <BR />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 indexes, so the resulting definition can be {{1,2,3},{4,5,6},{7,8,9}}.<BR />[[File:DefineEquations.png|500px|Define equations for all indexes]]<br />
<br />
<br />
<br />
=== Expressions ===<br />
<br />
Values for all cells in the variable matrix can be defined in a single expression. <br />
<br />
[[File: DefineEquations.png|600px]]<br />
<br />
[[File:DefineEquations2.png|600px]]<br />
<br />
In many situations, it is however more clear to define separate expressions for each cell or blocks. <br />
<br />
# '''Define range for the expression'''<BR /> [[File:DefineRange.png]]<br />
# '''Define the expression''' (dimensions of the defined range and the result of the expression must match!) <BR /> [[File:DefineEquations3.png]]<br />
# '''Create a new expression''' <BR /> [[File:CreateNewExpression.png]]<br />
#''' Select the new expression''' <BR /> [[File:SelectNewExpression.png]]<br />
<br />
Repeat until there is value for each cell. There must be exactly one value for each cell.<br />
<br />
=== Array slices ===<br />
<br />
Many times it is useful to access a slice of a multidimensional variable. In this chapter, we will use the following example variable:<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
The whole variable can be accessed in three different ways:<br />
# Auxiliary<br />
# Auxiliary[E1, E2]<br />
# Auxiliary[:, :]<br />
<br />
The following explains different methods for accessing parts of the variable<br />
<br />
// Single cell<br />
Auxiliary[one, eins] = 1<br />
<br />
// Slices<br />
Auxiliary[one, E2] = {1,2,3}<br />
Auxiliary[E1, zwei] = {{2},{5},{8}}<br />
<br />
// In addition to single cells and the whole enumeration range, a subrange of the enumeration can be used<br />
Auxiliary[two : three, E2] = {{4,5,6},{7,8,9}}<br />
Auxiliary[one : two, zwei : drei] = {{2,3},{5,6}}<br />
<br />
The syntax for accessing parts of variables can be used in both expression range definitions and in expressions.<br />
<br />
=== Arithmetic Operators ===<br />
<br />
Arithmetic operations are defined in Modelica. Below are examples of different operations.<br />
<br />
;Addition and substraction<br />
Addition and substraction are calculated elementwise<br />
<br />
{1,2,3} - {0,2,3} = {1,0,0}<br />
{{2,2},{4,4}} + {{8,8},{1,1}} = {{10,10},{5,5}}<br />
{1,2,3} - {1,2} = ERROR! Different array sizes<br />
<br />
;Division<br />
Division with a scalar<br />
{5,10,15} / 5 = {1,2,3}<br />
5 / {5,10,15} = ERROR! not allowed<br />
<br />
Division with an array<br />
{1,2,3} / {1,2,3} = ERROR! not allowed<br />
<br />
// Elementwise<br />
{1,2,3} ./ {1,2,3} = {1,1,1}<br />
<br />
;Multiplication<br />
<br />
Multiplication with a scalar<br />
{1,2,3} * 2 = {2,4,6}<br />
5 * {1,2,3} = {5,10,15}<br />
<br />
Matrix multiplication with an array<br />
{{3,4},{5,6}} * {1,2} = {11,17}<br />
{{3,4},{5,6}} * {1,2,3} = ERROR! incompatible array sizes<br />
<br />
//Elementwise<br />
{1,2} .* {1,2} = {1,4}<br />
<br />
Real[3,2] c = {{1,2},{3,4},{5,6}}; <br />
Real[2,2] d = {{3,4},{5,6}};<br />
Real[2,2] cd;<br />
cd = c[2:3, :] .* d; // Result: {{9,16},{25,36}}<br />
<br />
;Power<br />
Elementwise power of array variable<br />
{1,2} .^ 2 = {1,4}<br />
<br />
=== Builtin Modelica functions ===<br />
<br />
Modelica has some builtin functions that help using multidimensional variables. This chapter introduces some of the builtin functions. <br />
<br />
;Dimension and size functions<br />
<br />
We will use the same example variable as previously.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
;ndims(A)<br />
The number of dimensions in array A<br />
ndims(Auxiliary) = 2<br />
<br />
;size(A, i)<br />
The size of dimension i in array A<br />
size(Auxiliary, 2) = 3<br />
<br />
;size(A)<br />
A vector of length ndims(A) containing the dimension sizes of A<br />
size(Auxiliary) = {3,3}<br />
<br />
<br />
;Construction functions<br />
In addition to normal array constructing, a special construction functions can be used.<br />
<br />
;zeros(n1,n2,n3,...)<br />
An array full of zeros with dimensions n1 x n2 x n2 x ... <br />
zeros(2, 2) = {{0,0}, {0,0}}<br />
<br />
;ones(n1,n2,n3,...)<br />
An array full of ones with dimensions n1 x n2 x n2 x ... <br />
ones(2, 2) = {{1,1}, {1,1}}<br />
<br />
;fill(s,n1,n2,n3)<br />
Like zeros() and ones(), but with user defined value (s) for array elements.<br />
fill(3,2,2) = {{3,3}, {3,3}}<br />
<br />
;identity(n)<br />
Creates an n x n integer identity matrix with ones on the diagonal and all other elements zero.<br />
identity(3) =<br />
1 0 0<br />
0 1 0<br />
0 0 1<br />
<br />
;diagonal(v)<br />
Constructs a square matrix with elements of vector v on the diagonal and all other elements zero.<br />
diagonal({1,2,3}) =<br />
1 0 0<br />
0 2 0<br />
0 0 3<br />
<br />
;linspace(x1,x2,n)<br />
Constracts a Real vector from x1 to x2 with n equally spaced elements.<br />
linspace(2,5,4) = {2,3,4,5}<br />
<br />
;Reduction functions<br />
<br />
Reduction functions reduce arrays to scalars.<br />
<br />
;min(A)<br />
Returns the minimum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
min(A) = 1<br />
<br />
;max(A)<br />
Returns the maximum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
max(A) = 4<br />
<br />
;sum(A)<br />
Returns the sum of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
sum(A) = 10 // 1 + 2 + 3 + 4<br />
<br />
;product(A)<br />
Returns the product of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
product(A) = 24 // 1 * 2 * 3 * 4<br />
<br />
<br />
;Using functions with iterators<br />
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.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
AuxiliarySum[E1] = {sum( Auxiliary[ i , E2 ] ) for i in E1} // Result: {6, 15, 24}<br />
<br />
/* Same as:<br />
{sum(Auxiliary[one, E2]), sum(Auxiliary[two, E2]), sum(Auxiliary[three, E2])}<br />
{sum({1,2,3}), sum({4,5,6}), sum({7,8,9})}<br />
*/<br />
<br />
One expression can have multiple iterators. The Modelica specification defines the following format, but it is NOT yet supported in OpenModelica:<br />
{sum(Array[ i, j, E3]) for i in E1, j in E2} // Dimensions reduced from 3 to 2<br />
<br />
To use multiple iterators, use the following format (NOTE the reversed order of iterators!):<br />
{{sum(Array[ i, j, E3]) for j in E2} for i in E1} // Dimensions reduced from 3 to 2<br />
<br />
The range doesn't have to be the whole enumeration. Subranges can also be used.<br />
{sum( Auxiliary[ i , eins : zwei ] ) for i in E1.one : E1.two} // Result: {3, 9}<br />
<br />
/* Same as<br />
{sum(Auxiliary[one, eins : zwei]), sum(Auxiliary[two, eins : zwei])}<br />
{sum({1,2}), sum({4,5})}<br />
*/<br />
<br />
=== Simulation results ===<br />
<br />
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. <br />
<br />
[[File:3x3trend.png|300px|Trend view for a 3x3 variable]]<br />
<br />
The clutter can be reduced by selecting which enumeration indexes are shown in charts. Select an enumeration and tick the indexes 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.<br />
<br />
[[File:ShowInCharts.png|500px|Select indexes to show in charts]]<br />
<br />
<br />
=== Array Variables in Modules ===<br />
<br />
[[File:Replaceable.png|frame|Replaceable enumeration inside a module]]<br />
<br />
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 [[Simantics_System_Dynamics#Modeling|Modeling]]). <br />
<br />
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.<br />
<br />
<br />
<br style="clear: both" /><br />
<br />
In this example, the original enumeration that the modeler used had two indexes. We are using an instance of this module, but we need to use array variables that have three indexes instead of two. We are using two variables and an instance of the module.<br />
<br />
[[File:ReplacingEnumerationConfiguration.png|frame|left|500px|Module configuration for replacing enumerations inside the module]]<br />
<br style="clear: both" /><br />
<br />
In the parent configuration, we have used an enumeration with three indexes in the two variables.<br />
<br />
[[File:Replacing.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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 clickin 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.<br />
<br />
<br />
[[File:ReplacingEnumeration.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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!<br />
<br />
== Functions ==<br />
<br />
Modelica provides a convenient way to use functions in your models. You can create your own functions, import complete function libraries and share function libraries to be used in all of your models. <br />
<br />
=== Creating functions ===<br />
<br />
[[File:NewFunction.png|right]]<br />
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.<br />
<br />
Functions that can be found from Functions -folder can be used in your variable definitions.<br />
<br />
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. <br />
<br />
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.<br />
<br />
Below is an example of a simple function. For more examples, see the built-in functions provided with the tool and [https://www.modelica.org/documents/ Modelica specifications].<br />
<br />
<br style="clear: both" /><br />
<br />
[[File:ExampleFunction.png]]<br />
<br />
=== Function libraries ===<br />
<br />
<br />
[[File:NewFunctionLibrary.png|right]]<br />
<br />
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)).<br />
<br />
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. <br />
<br />
Create a new function library by right-clicking on Functions folder, Shared functions folder or other module library.<br />
<br />
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.<br />
<br />
[[File:SharedFunctions.png]]<br />
<br style="clear: both" /><br />
<br />
=== External functions ===<br />
<br />
Modelica allows you to use external functions that are programmed using C language. Below is a simple example of using a function that returns the sum of two arguments. <br />
<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}<br />
<br />
<br />
[[File:ImportCFunctionLibrary.png|right]]<br />
<br />
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 <br />
(e.g. simantics_home/plugins/org.simantics.openmodelica.win32_x/MinGW/bin/mingw32_gcc.exe -g -O -c ExampleCFunctionCode.c). <br />
<br style="clear: both" /><br />
<br />
[[File:ExampleExternalFunction.png]]<br />
<br />
<br />
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.<br />
<br />
[[File:ExternalFunctionResult.png]]<br />
<br />
<br />
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.<br />
<br />
<br />
Small external C function can also be written directly to the function code in Simantics Sysdyn:<br />
function ExampleExternalFunction<br />
input Real x;<br />
input Real y;<br />
output Real z;<br />
external "C" z=exampleCFunction(x,y) annotation(Include="<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}");<br />
end ExampleExternalFunction;<br />
<br />
=== Modelica functions ===<br />
<br />
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 [[Simantics_System_Dynamics#Builtin_functions|builtin functions for arrays]].<br />
<br />
{|<br />
|abs(x)<br />
|Returns the absolute value of x. Expanded into "(if x >= 0 then x else -x)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|acos(x)<br />
|Inverse cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|asin(x)<br />
|Inverse sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan(x)<br />
|Inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan2(x1,x2)<br />
|four quadrant inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cat(n,A,B,...)<br />
|General concatenation function that concatenates arrays A,B,... along the nth dimension.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|ceil(x)<br />
|Returns the smallest integer not less than x, the closest integer above x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cos(x)<br />
|Cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cosh(x)<br />
|Hyperbolic cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cross(x,y)<br />
|Returns the 3-vector cross product of the 3-vectors x and y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|delay(expr, delayTime)<br />
|Returns the value of expr at the time time-delayTime. The value of expr is returned when time <= time.start + delayTime.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|der(x)<br />
|Time derivative of x. X must be have continuous-time variability.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|div(x, y)<br />
|Returns the algebraic quotient x/y with any fractional part discarted. E.g. div(10,3) = 3.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|edge(b)<br />
|Returns true when the value of the boolean expression b changes. Expanded into (b and not pre(b)).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|exp(x)<br />
|Exponential, base e.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|floor(x)<br />
|Returns the largest integer not greater than x, the closest integer below x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|initial()<br />
|Returns true at the beginning of the simulation. <br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|integer(x)<br />
|Returns the largest integer not greater than x as an integer.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log(x)<br />
|Natural logarithm. (base e, x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log10(x)<br />
|Base 10 logarithm. (x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|mod(x, y)<br />
|Returns the integer modulus of x/y: mod(x,y) = x - floor(x/y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|noEvent(expr)<br />
|noEvent around an expression causes the expression to NOT generate event.<br />
'''Important:''' <br />
:If you want a condition to be checked only on time steps, use noEvent.<br />
:(e.g. if noEvent(value >= 1) then ... else ...)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|pre(x)<br />
|Returns the preceding value of y from time event that has occured before current time.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|rem(x, y)<br />
|Returns the integer remainder of x/y: rem(x,y) = x - div(x,y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sample(start, interval)<br />
|Returns true and triggers time events at times start + i * interval (i=0,1,...).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sign(x)<br />
|Returns -1 if x is negative, 1 if x is positive. Expanded into "(if x > 0 then 1 else if x < 0 then -1 else 0)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sin(x)<br />
|Sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sinh(x)<br />
|Hyperbolic sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sqrt(x)<br />
|Square root of x. The value of x must be greater or equal to 0 or an assertion error occurs.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tan(x)<br />
|Tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tanh(x)<br />
|Hyperbolic tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|terminal()<br />
|Returns true at the end of a successful simulation.<br />
|}<br />
<br />
== Spreadsheets ==<br />
<br />
Spreadsheets allow storing and maintaining values in a familiar format. The current spreadsheet implementation is experimental and does not provide much functionality. Some basic tasks can, however, be performed. You cannot type directly to a cell, you need to first copy some value or text into it. Then it can be modified.<br />
<br />
=== Variable values ===<br />
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.<br />
<br />
[[File:AuxiliarySheetReference.png|Sheet reference in an expression]][[File:AuxiliarySheet.png|Value of a variable in sheet]]<br />
<br />
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 indexes are not mandatory, but help reading and maintaining the sheet.<br />
<br />
[[File:SheetForMultidim.png|Spreadsheet for multidimensional variables]]<br />
<br />
Reference to a sheet range creates an array variable.<br />
<br />
[[File:SheetMultidim1.png|Array variable ArrayTest1[2] with sheet reference]]<br />
<br />
ArrayTest2 has two dimensions. Reference to a larger range creates a two-dimensional variable. By default, the indexes are ordered as in this example. However, if you wish to present the indexes in a different order in the spreadsheet, you can transpose the sheet reference (e.g. transpose(ArrayTestSheet(E2:G3)))<br />
<br />
[[File:SheetMultidim2.png|Array variable ArrayTest2[2,3] with sheet reference]]<br />
<br />
=== History data ===<br />
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.<br />
<br />
[[File:Sheet.png|Spreadsheet with history data]]<br />
<br />
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. <br />
<br />
[[File:HistoryDataSettings.png|History data settings]]<br />
<br />
{|<br />
|'''History data properties'''<br />
|<br />
|-<br />
|Name<br />
|Name of the history dataset<br />
|-<br />
|Sheet<br />
|Combo box for selecting a sheet where the history data is located<br />
|-<br />
|Orientation<br />
|Columns or rows. How the data is arranged in the sheet.<br />
|-<br />
|Range start<br />
|The upper-left corner cell of the history data range<br />
|-<br />
|Range end<br />
|The lower-right corner cell of the history data range<br />
|-<br />
|Time variable<br />
|The name of the time variable in the history data, if it is different than "time"<br />
|-<br />
|Variables in range<br />
|This text field displays the found variables in the given sheet and range<br />
|-<br />
|}<br />
<br />
If the history dataset is activated, history data is displayed whenever it is available for a variable that is displayed in a chart.<br />
<br />
[[File:HistoryData.png|History data in two charts]]<br />
<br />
<br />
<center><br />
[[Simantics]] | ''System Dynamics Modelling''<br />
</center><br />
<br />
----<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Basic System Dynamics Modelling]]'''<br><br />
System dynamics modelling in Simantics is a free modelling tool that is included into the basic installation. This tutorial introduces the basic features of the system dynamics modelling tool.<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Advanced System Dynamics Modelling]]'''<br><br />
This tutorial introduces the more advanced features of the system dynamics modelling tool: Modules and Operating interfaces<br />
<br />
[[Category: Simantics System Dynamics]]</div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=Simantics_System_Dynamics&diff=584Simantics System Dynamics2012-10-25T10:37:59Z<p>Teemu Lempinen: /* Components */</p>
<hr />
<div>== Simantics System Dynamics ==<br />
<br />
Simantics System Dynamics is currently the only open source modelling and simulating tool for Simantics. Simantics System Dynamics is under development and will go through some changes in the future. New features will be added and old ones improved according to the needs of the modellers. New features include module libraries and different analysis tools.<br />
<br />
This documentation introduces you to the current version of Simantics System Dynamics. Documentation includes the basic modelling principles and a guide on how to model system dynamics models with Simantics System Dynamics. If you like to get to know the tool better and try modelling and simulating yourself, [[#Installation Instructions|install]] the software and try our [[Tutorial: Basic System Dynamics Modelling|basic]] and [[Tutorial: Advanced System Dynamics Modelling|advanced]] tutorials!<br />
<br />
== Introduction to System Dynamics Simulation ==<br />
<br />
===System Dynamics===<br />
System dynamics is an approach to understanding different organizations, markets and other complex systems and their dynamic behavior. System dynamics modelling in Simantics is a free modelling tool. See [[#Installation Instructions|installation instructions]].<br />
<br />
===Model===<br />
[[File:ModelStructure.png|right|thumb|Model structure]]<br />
System dynamics model is generally understood as the model configuration. In this tool, the model contains also other components. Model can have Operating interfaces that enable the use of the model with simple controls. Operating interfaces are configured separately and when using them, the complex model is hidden from the user. Experiments are the way to simulate the model. In the future, you can have experiments with different configurations, for example different initial values for some parameters. In that way, you don't have to always configure the model for different scenarios. Modules folder contains all the different module types in your model and you can create new module types there. <br />
<br />
<br style="clear: both" /><br />
<br />
===Components===<br />
Most of the components you can use in your models are basic system dynamics components. The modularity of the models introduces two additional components, Modules and Inputs. All the components are explained below.<br />
[[File:ComponentTypes.png|right|frame|Component types]]<br />
;Auxiliary<br />
:Auxiliary is the most basic variable you can use. It represents a single value or a mathematical expression. There are different types of auxiliary variables currently in the system: Auxiliary, Parameter, Constant, Delay and WithLookup. Auxiliary is the default type. Parameters are single values that the user can change. When only parameters are changed, the model simulates faster, because the system does not have to recompile the model. WithLookup and Delay are special variables. WithLookup has an expression and a lookup table. The expresssion defines what value is taken from the defined table. Delay variable delays an equation a given time with a given delay order.<br />
;Dependency<br />
:Dependency is an arrow that connects two components. It means that the value of the variable from which the arrow starts is used to calculate the value of the variable where the arrow ends.<br />
;Flow<br />
:Flow connects clouds, valves and stocks. Flow represents an actual flow of something from stocks or clouds to stocks or clouds. There has to be at least one valve in a flow and the system creates it automatically, if none of the ends of the flow is a valve.<br />
;Valve<br />
:Valve regulates the rate of a flow. The value of a valve is automatically used in calculating the level of an adjacent stock. Valves behave just like Auxiliary variables but look different and you can connect also flows to them.<br />
;Stock<br />
:The value of a stock variable is an integral of flows leaving and flows arriving to the variable. The integral is calculated automatically from the valves that are connected to the variable with flow connections. You must give an initial value to the stock. Initial value can be a single value or an equation. You can use values of other variables to calculate the initial value.<br />
;Cloud<br />
:Cloud is not a variable. It represents a starting or ending point of a flow, if it is not in the scope of the model.<br />
;Module<br />
:Modules enable structural modeling. Modules are defined just like the basic model configuration, but the module component hides the actual configuration. You can only connect dependency connections into the module and dependency connections from the module must end to Input variables. The interface of the module is defined using input and output variables in the configuration of the module. All variable types can be set as output variables. If a variable is an output variable, its font is bold.<br />
;Input<br />
:Input variables are the way of getting values from other modules. Inputs look like auxiliary variables except their font is italics. You can set a default value to the input variable in case it is not connected to any variable. Connections are made from the modules properties, when the module is populated. Input doesn't have to be connected with an arrow to a module. If the variable has no connections, it can get values from a higher level in the hierarchy. If an input is connected to an output, the output and its module are shown below the variable using dot notation.<br />
<br style="clear: both" /><br />
<br />
===Modeling principles===<br />
<br />
System dynamics modelling is much more than just mathematical formulas and nice graphs. Models are ways of communicating. There are some basic principles in system dynamics modelling that make the models easier to read and understand. You do not have to apply these principles to simulate models, but using them makes it easier for you to communicate your model to others.<br />
<br />
;Variable names<br />
:Variables names should be nouns, not verbs. The names should be positive: for example it is easier to understand that satisfaction decreases than dissatisfaction rises. <br />
<br />
:Variable names can and should have multiple words, if they are needed. Unfortunately current version of the tool does not support spaces in variable names. A good practice is to use CamelCase if name contains multiple words. This means that you start every word woth a capital letter (example: ExampleVariable).<br />
<br />
;Connections<br />
:You should try to avoid overlapping dependency arrows. In some situations, however, it is not possible. Dependencies should also form distinctive loops, if there is a loop. It makes it easier to read and understand the model and its behavior.<br />
<br />
;Graphical annotations<br />
:System dynamics contains usually annotations for loops, polarities, delays and so on. Currently those annotations are not supported, but the support will be added later. Annotations are important, again, for communicating the behavior of the model.<br />
<br />
==Installation Instructions==<br />
<br />
System dynamics tool is a provided with the Simantics platform.<br />
<br />
# [https://www.simantics.org/simantics/download Download installer from Simantics download page]<br />
# Install the program to a directory without spaces (limitation inherited from OpenModelica).<br />
# Run the application through the launcher generated by the installer<br/><br />
: (default: Simantics\Simantics-1.6.0-Sysdyn-32\Simantics-1.6.0-Sysdyn-32)<br />
<br />
[http://www.openmodelica.org/ OpenModelica] is used to build and simulate the models. Simantics platform has integrated OpenModelica 1.8.1 for Windows environments. For other versions and other environments you need to install [http://www.openmodelica.org/index.php/download OpenModelica].<br />
<br />
== Workbench ==<br />
<br />
[[File:BasicWorkbench.png|center|729px]]<br />
<br />
<br />
# '''Diagram''' <br /> Diagram is the area where you will graphically modify your model. Diagrams are built from elements that can be dragged from Symbols view or populated using shortcut keys. <br />
# '''Model Browser''' <br /> Model browser shows the structure of your model and all items related to it. <br /> Symbols view is stacked with the model browser and used for dragging elements to diagrams.<br />
# '''Properties''' <br /> Property view shows the selected variable's properties. Property view has a different layout depending on the type of the selected component. The view can also have different tabs depending on the component type. Basic tabs are with variables are Equation and Additional information.<br />
# '''Trend''' <br /> Trend view shows the graphical representation of the values of the selected value over time. For the trend to be shown, a simulation has to be run. The view shows always the results of the latest run, but you can save results of a simulation and show them in the same trend with results from another simulation. Values view and Dependencies are stacked with Trend view and can also be used for analyzing the model.<br />
# '''Experiment controls''' <br /> Experiment controls are shown when an experiment is active. Experiment is activated by double clicking an experiment in the model browser. With the experiment control, you can start simulation runs and save simulation results.<br />
<br />
<br /><br />
If you accidentally close a view, you can reopen them from Window->Show View->Other...<br />
<br />
== Modelling ==<br />
<br />
===Basic modelling===<br />
<br />
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.<br />
<br />
[[File:Basic_1.png|right]]<br />
;Creating a new model<br />
:Start a new model by right-clicking the model browser and selecting New->Model or from the main menu File->New Model.<br />
<br style="clear: both" /><br />
<br />
[[File:Basic_2.png|right]]<br />
;Creating a new module type<br />
:Create a new module type by right-clicking on the Modules-folder and selecting New->Module. This creates a new module type that you can populate to your other modules and the model configuration. <br />
<br style="clear: both" /><br />
<br />
;Configuring a model<br />
:Model configuration can be opened by double clicking Configuration in the model browser. <br />
<br />
;Configuring modules<br />
: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 module!<br />
<br />
;Populate variables<br />
:You can drag variables to a diagram from symbol view. You can also populate variables using [[#Shortcut and control keys|shortcut keys]]<br />
<br />
;Populate modules<br />
:Modules are populated from the model browser. Just drag the module you want to populate from the Modules folder to a diagram.<br />
<br />
;Create connections<br />
: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.<br />
: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.<br />
: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.<br />
<br />
;Connections between modules<br />
:'''Outside the module''' <br /><br />
:You can connect variables to variables in modules like this:<br />
MODULE -----> INPUT<br />
or<br />
ANY VARIABLE -----> MODULE <br />
:This is just the visual configuration, but you need those connections to really connect variables in the module's properties.<br />
:In Inputs -tab you select which variables you connect to inputs inside the module. In Outputs -tab you select which variables you lift from the module to inputs outside it.<br />
<br />
:'''Inside the module''' <br /><br />
:Input variables get values from outside the module<br />
<br />
:Output variables can send their values outside the module. From the variable properties, select Additional Information and press Is Output<br />
<br />
;Configure variables<br />
:Select a single variable from diagram or model browser. The properties of the variables are shown in the equation view and you can modify them.<br />
<br />
;Export model<br />
: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 to for example create different versions of the model, create backups or to transport it to another database.<br />
<br />
;Import model<br />
:Right-click on the model browser and select Import->Model. Browse to your .tg file and select open. The model is added to your model browser.<br />
<br />
===Shortcut and control keys===<br />
<br />
Shortcut keys for configuring a model on diagram.<br />
<br />
{|<br />
|Esc <br />
|Cancel operations (e.g. connection and rename).<br />
|-<br />
|Shift + A <br />
|Hover Auxiliary at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + S<br />
|Hover Stock at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + C<br />
|Hover Cloud at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + V<br />
|Hover Valve at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + I<br />
|Hover Input at the cursor position, populate with left mouse button.<br />
|-<br />
|Alt + left mouse button<br />
|Start an arrow from a variable. End to another variable by clicking left mouse button.<br />
|-<br />
|Alt + right mouse button<br />
|Start flow from a variable. End by clicking left mouse button.<br />
<br />
If a flow is not started or ended on to a variable, a cloud will be created to that end. <br /><br />
If a new flow does not have a valve at either end, a valve will be created in the middle of the flow.<br />
|-<br />
|Delete<br />
|Remove selected variables<br />
|-<br />
|Ctrl + left mouse button<br />
|Select multiple variables<br />
|-<br />
|Mouse wheel or<br/>+ and -<br />
|Diagram zoom<br />
|-<br />
|drag(mouse3) or<br/>drag(shift + any mouse button)<br />
|Diagram pan<br />
|-<br />
|Ctrl + C<br />
|Copy selected elements<br />
|-<br />
|Ctrl + X<br />
|Cut selected elements<br />
|-<br />
|Ctrl + V<br />
|Paste copied or cut elements<br />
|-<br />
|G<br />
|Show / hide grid<br />
|-<br />
|R<br />
|Show / hide ruler<br />
|}<br />
<br />
Other shortcut keys can be found selecting Window -> Preferences from the main menu. Keys are located in General -> Keys.<br />
<br />
== Simulation ==<br />
There are three different ways for simulating a model. Different simulations are represented as different types of experiments in Simantics System Dynamics. <br />
<br />
Experiments are created from the context menu of experiments folder in a model. <br />
<br />
[[File:NewExperiment.png]]<br />
<br />
Double-click on an experiment activates it and displays experiment type specific controls in the main tool bar.<br />
<br />
;Normal simulation<br />
: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.<br />
<br />
;Game simulation<br />
:Game simulations allow simulating an arbitrary number of steps, changing parameter values and continuing simulation with the new values from where it previously ended.<br />
<br />
;Simulation playback<br />
:Simulation playback works essentially as the basic experiment, but it offers some additional visualization options.<br />
<br />
== Simulation result and model structure analysis ==<br />
Simulation results can be viewed as trends in trend view or as plain numbers in values view. The views display results of variables that are selected in the workbench. Users can also create [[#Custom charts |custom charts]].<br />
<br />
Model structure can be examined in the Structure view. There are two options: Dependency structures of individual variables or the complete hierarchy structure of the model.<br />
<br />
;Trend<br />
:Shows you the values of the selected variable(s) graphically over the simulation time. You can modify the trend and zoom it using the context menu (right-click) of the trend. <br /> [[File:Trend.png]]<br />
<br />
;Values<br />
:Shows you the values of the selected variable(s) in a table form. If the value has a star (*) at the end, it means that the value is an approximate. There is no value for that variable for the given time step. Selected values can be copied to other software in csv format.<br /> [[File:Values.png]]<br />
<br />
;Compare results<br />
:You can compare different results of the same model by saving simulation results and displaying the saved results side by side with other results. You can save your results after simulating by clicking the save button [[File:Saveresults.png]] on your experiment controls. The saved results appear to model browser under the active experiment. To show the results on trends and tables, right-click on the result and select Show on charts. <br /> [[File:CompareTrend.png]]<br />
<br />
;Dependencies<br />
:Dependencies display which variables affect and which are affected by the selected variable. The direction and number of steps that are traveled from the selected variable can be configured at the bottom of the view. <br /> [[File:Dependencies.png]]<br />
<br />
;Model Hierarchy<br />
:Model Hierarchy displays the hierarchical structure of the model. The module type where a selected variable is located is highlighted.<br /> [[File:ModelHierarchy.png]]<br />
<br />
== Custom charts ==<br />
Custom charts are user-defined displays of simulation result data. They can be used and re-used in various places. The three types of custom charts (line, bar and pie charts) provide model developers means for examining and developing their models and communicating the simulation results to others. <br />
<br />
Custom charts are created to the Charts folder in model browser.<br />
<br />
[[File:NewChart.png | Creating a new chart]]<br />
<br />
Charts are configured the same way as variables: first select the chart from model browser and then configure it in the property view. Charts can be viewed in the same active trend view as any variable by selecting the chart from model browser. In addition to trend view, charts can be populated directly to the model diagram or to a separate chart panel that can contain multiple charts. <br />
<br />
=== Line chart ===<br />
<br />
Line char 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.<br />
<br />
[[File:LineChart.png|Line chart with an array variable]]<br />
<br />
[[File:LineChartGeneral.png|General settings of line chart]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|The title of the chart. Displayed in the chart<br />
|-<br />
|Type<br />
|Line chart (default) or area chart<br />
|-<br />
|Hide<br />
|Options to hide chart grid, title or legend<br />
|-<br />
|'''X-axis'''<br />
|<br />
|-<br />
|Variable<br />
|A variable that is used as the x-axis variable. The default variable is time and it needs not to be typed in the field.<br />
|-<br />
|Label<br />
|Optional other label for the variable than its name<br />
|-<br />
|Min<br />
|Minimum value of the x-axis<br />
|-<br />
|Max<br />
|Maximum value of the x-axis<br />
|-<br />
|Hide<br />
|Options to hide x-axis lable, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
[[File:LineChartAxisAndVariables.png|Axis and variables settings of line chart]]<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed.<br />
|-<br />
|Color<br />
|Color for the lines of this variable<br />
|-<br />
|Line width<br />
|The width of the lines drawn for this variable<br />
|}<br />
There are also configuration options for y-axis. They are displayed when an axis is selected in the Axis and variables tab.<br />
{|<br />
|'''Y-axis'''<br />
|<br />
|-<br />
|Label<br />
|Label of the axis<br />
|-<br />
|Min<br />
|Minimum value in the axis<br />
|-<br />
|Max<br />
|Maximum value in the axis<br />
|-<br />
|Color<br />
|The color of the axis lines, ticks and labels<br />
|-<br />
|Hide<br />
|Options to hide parts of the axis: label, axis line, tick marks, tick labels<br />
|-<br />
|}<br />
<br />
=== Bar chart ===<br />
Bar charts display variables in a certain point in time. The point can be defined for the complete chart in cart'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. <br />
<br />
[[File:BarChartGeneral.png|General bar chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Name is displayed in model browser.<br />
|-<br />
|Title<br />
|The title of the chart. Title is displayed in the chart, if not hidden<br />
|-<br />
|Type<br />
|Normal or stacked. Normal type displays all variables in separate bars. Stacked mode is able to display one-dimensional array variables in stacks.<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Option for hiding grid, title and Legend. Legend is hidden by default since it only contains the information that the current simulation is displayed.<br />
|-<br />
|}<br />
<br />
[[File:BarChartInDiagram.png|Bar chart in a model diagram]]<br />
<br />
Charts can be added to model diagrams simply by dragging the chart from model browser to diagram.<br />
<br />
[[File:BarChartVariable.png|Settings for a variable in bar chart]]<br />
<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|}<br />
[[File:BarChartAxis.png|Settings for axis in bar chart]]<br />
{|<br />
|'''Domain axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for x axis<br />
|-<br />
|Label angle<br />
|Axis labels can be displayed in an angle. This value determines the angle in degrees.<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|'''Range axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for y axis<br />
|-<br />
|Min<br />
|Minimum value of y axis<br />
|-<br />
|Max<br />
|Maximum value of y axis<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
=== Pie chart ===<br />
<br />
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.<br />
<br />
[[File:PieChartGeneral.png|General pie chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|Title The title of the chart. Displayed in the chart<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Options for hiding title, section labels and legend<br />
|-<br />
|}<br />
<br />
[[File:PieChartVariable.png|Variable settings in pie chart]]<br />
{|<br />
|'''Variables'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Color<br />
|Color for the sector of this variable<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|Exploded<br />
|If set, the sector(s) of the variable(s) are "exploded" away from the center of the pie chart<br />
|-<br />
|}<br />
<br />
[[File:PieChartChartPanel.png|Pie chart in chart panel]]<br />
<br />
=== Chart panel ===<br />
[[File:ChartPanel.png|right]]<br />
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.<br />
<br />
Chart panel can be either horizontally or vertically oriented. Different orientations help in configuring the workbench perspective. <br />
<br />
[[File:ChartPanelOrientation.png|Chart panel orientation]]<br />
<br />
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.<br />
<br />
By default, chart panel is hidden in the upper-left corner of the system dynamics perspective.<br />
<br style="clear: both" /><br />
<br />
== Multidimensional variables ==<br />
<br />
<br />
=== Modeling ===<br />
<br />
Models with multidimensional variables look just like any other models. The structure of the models is replicated givin multiple indexes to variables. For users with programming background, notation Variable[] may be familiar. In system dynamic modeling we need to give names to the indexes. Instead of using numbers to define the indexes, like in normal programming, we use enumerations. The steps to create a model with multidimensional variables are as follows (with examples):<br />
<br />
# '''Create the model structure''' <BR />Model with multidimensional variables looks just like any other model.<BR /> [[File:ModelWithMultidimensionalVariables.png|300px|Model with multidimensional variables]]<br />
# '''Create Enumerations and define the indexes''' <BR />Enumerations are created by right-clicking configuration and selecting New->Enumeration.<BR /> [[File:NewEnumeration.png|250px|New enumeration]]<BR />Define enumeration indexes by adding as many indexes as you want. Rename the indexes by selecting them and then clicking on them again.<BR />[[File:DefineIndexes.png|200px|Index definitions]]<br />
# '''Add Enumerations for variables''' <BR />Select the variable that you want to be multidimensional. From the Indexes -tab in the property view, move the wanted enumerations to the right. The order of the enumerations does matter.[[File:SelectEnumerations.png|500px|Select enumerations for variables]]<br />
# '''Define equations for all possible indexes''' <BR />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 indexes, so the resulting definition can be {{1,2,3},{4,5,6},{7,8,9}}.<BR />[[File:DefineEquations.png|500px|Define equations for all indexes]]<br />
<br />
<br />
<br />
=== Expressions ===<br />
<br />
Values for all cells in the variable matrix can be defined in a single expression. <br />
<br />
[[File: DefineEquations.png|600px]]<br />
<br />
[[File:DefineEquations2.png|600px]]<br />
<br />
In many situations, it is however more clear to define separate expressions for each cell or blocks. <br />
<br />
# '''Define range for the expression'''<BR /> [[File:DefineRange.png]]<br />
# '''Define the expression''' (dimensions of the defined range and the result of the expression must match!) <BR /> [[File:DefineEquations3.png]]<br />
# '''Create a new expression''' <BR /> [[File:CreateNewExpression.png]]<br />
#''' Select the new expression''' <BR /> [[File:SelectNewExpression.png]]<br />
<br />
Repeat until there is value for each cell. There must be exactly one value for each cell.<br />
<br />
=== Array slices ===<br />
<br />
Many times it is useful to access a slice of a multidimensional variable. In this chapter, we will use the following example variable:<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
The whole variable can be accessed in three different ways:<br />
# Auxiliary<br />
# Auxiliary[E1, E2]<br />
# Auxiliary[:, :]<br />
<br />
The following explains different methods for accessing parts of the variable<br />
<br />
// Single cell<br />
Auxiliary[one, eins] = 1<br />
<br />
// Slices<br />
Auxiliary[one, E2] = {1,2,3}<br />
Auxiliary[E1, zwei] = {{2},{5},{8}}<br />
<br />
// In addition to single cells and the whole enumeration range, a subrange of the enumeration can be used<br />
Auxiliary[two : three, E2] = {{4,5,6},{7,8,9}}<br />
Auxiliary[one : two, zwei : drei] = {{2,3},{5,6}}<br />
<br />
The syntax for accessing parts of variables can be used in both expression range definitions and in expressions.<br />
<br />
=== Arithmetic Operators ===<br />
<br />
Arithmetic operations are defined in Modelica. Below are examples of different operations.<br />
<br />
;Addition and substraction<br />
Addition and substraction are calculated elementwise<br />
<br />
{1,2,3} - {0,2,3} = {1,0,0}<br />
{{2,2},{4,4}} + {{8,8},{1,1}} = {{10,10},{5,5}}<br />
{1,2,3} - {1,2} = ERROR! Different array sizes<br />
<br />
;Division<br />
Division with a scalar<br />
{5,10,15} / 5 = {1,2,3}<br />
5 / {5,10,15} = ERROR! not allowed<br />
<br />
Division with an array<br />
{1,2,3} / {1,2,3} = ERROR! not allowed<br />
<br />
// Elementwise<br />
{1,2,3} ./ {1,2,3} = {1,1,1}<br />
<br />
;Multiplication<br />
<br />
Multiplication with a scalar<br />
{1,2,3} * 2 = {2,4,6}<br />
5 * {1,2,3} = {5,10,15}<br />
<br />
Matrix multiplication with an array<br />
{{3,4},{5,6}} * {1,2} = {11,17}<br />
{{3,4},{5,6}} * {1,2,3} = ERROR! incompatible array sizes<br />
<br />
//Elementwise<br />
{1,2} .* {1,2} = {1,4}<br />
<br />
Real[3,2] c = {{1,2},{3,4},{5,6}}; <br />
Real[2,2] d = {{3,4},{5,6}};<br />
Real[2,2] cd;<br />
cd = c[2:3, :] .* d; // Result: {{9,16},{25,36}}<br />
<br />
;Power<br />
Elementwise power of array variable<br />
{1,2} .^ 2 = {1,4}<br />
<br />
=== Builtin Modelica functions ===<br />
<br />
Modelica has some builtin functions that help using multidimensional variables. This chapter introduces some of the builtin functions. <br />
<br />
;Dimension and size functions<br />
<br />
We will use the same example variable as previously.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
;ndims(A)<br />
The number of dimensions in array A<br />
ndims(Auxiliary) = 2<br />
<br />
;size(A, i)<br />
The size of dimension i in array A<br />
size(Auxiliary, 2) = 3<br />
<br />
;size(A)<br />
A vector of length ndims(A) containing the dimension sizes of A<br />
size(Auxiliary) = {3,3}<br />
<br />
<br />
;Construction functions<br />
In addition to normal array constructing, a special construction functions can be used.<br />
<br />
;zeros(n1,n2,n3,...)<br />
An array full of zeros with dimensions n1 x n2 x n2 x ... <br />
zeros(2, 2) = {{0,0}, {0,0}}<br />
<br />
;ones(n1,n2,n3,...)<br />
An array full of ones with dimensions n1 x n2 x n2 x ... <br />
ones(2, 2) = {{1,1}, {1,1}}<br />
<br />
;fill(s,n1,n2,n3)<br />
Like zeros() and ones(), but with user defined value (s) for array elements.<br />
fill(3,2,2) = {{3,3}, {3,3}}<br />
<br />
;identity(n)<br />
Creates an n x n integer identity matrix with ones on the diagonal and all other elements zero.<br />
identity(3) =<br />
1 0 0<br />
0 1 0<br />
0 0 1<br />
<br />
;diagonal(v)<br />
Constructs a square matrix with elements of vector v on the diagonal and all other elements zero.<br />
diagonal({1,2,3}) =<br />
1 0 0<br />
0 2 0<br />
0 0 3<br />
<br />
;linspace(x1,x2,n)<br />
Constracts a Real vector from x1 to x2 with n equally spaced elements.<br />
linspace(2,5,4) = {2,3,4,5}<br />
<br />
;Reduction functions<br />
<br />
Reduction functions reduce arrays to scalars.<br />
<br />
;min(A)<br />
Returns the minimum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
min(A) = 1<br />
<br />
;max(A)<br />
Returns the maximum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
max(A) = 4<br />
<br />
;sum(A)<br />
Returns the sum of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
sum(A) = 10 // 1 + 2 + 3 + 4<br />
<br />
;product(A)<br />
Returns the product of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
product(A) = 24 // 1 * 2 * 3 * 4<br />
<br />
<br />
;Using functions with iterators<br />
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.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
AuxiliarySum[E1] = {sum( Auxiliary[ i , E2 ] ) for i in E1} // Result: {6, 15, 24}<br />
<br />
/* Same as:<br />
{sum(Auxiliary[one, E2]), sum(Auxiliary[two, E2]), sum(Auxiliary[three, E2])}<br />
{sum({1,2,3}), sum({4,5,6}), sum({7,8,9})}<br />
*/<br />
<br />
One expression can have multiple iterators. The Modelica specification defines the following format, but it is NOT yet supported in OpenModelica:<br />
{sum(Array[ i, j, E3]) for i in E1, j in E2} // Dimensions reduced from 3 to 2<br />
<br />
To use multiple iterators, use the following format (NOTE the reversed order of iterators!):<br />
{{sum(Array[ i, j, E3]) for j in E2} for i in E1} // Dimensions reduced from 3 to 2<br />
<br />
The range doesn't have to be the whole enumeration. Subranges can also be used.<br />
{sum( Auxiliary[ i , eins : zwei ] ) for i in E1.one : E1.two} // Result: {3, 9}<br />
<br />
/* Same as<br />
{sum(Auxiliary[one, eins : zwei]), sum(Auxiliary[two, eins : zwei])}<br />
{sum({1,2}), sum({4,5})}<br />
*/<br />
<br />
=== Simulation results ===<br />
<br />
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. <br />
<br />
[[File:3x3trend.png|300px|Trend view for a 3x3 variable]]<br />
<br />
The clutter can be reduced by selecting which enumeration indexes are shown in charts. Select an enumeration and tick the indexes 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.<br />
<br />
[[File:ShowInCharts.png|500px|Select indexes to show in charts]]<br />
<br />
<br />
=== Array Variables in Modules ===<br />
<br />
[[File:Replaceable.png|frame|Replaceable enumeration inside a module]]<br />
<br />
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 [[Simantics_System_Dynamics#Modeling|Modeling]]). <br />
<br />
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.<br />
<br />
<br />
<br style="clear: both" /><br />
<br />
In this example, the original enumeration that the modeler used had two indexes. We are using an instance of this module, but we need to use array variables that have three indexes instead of two. We are using two variables and an instance of the module.<br />
<br />
[[File:ReplacingEnumerationConfiguration.png|frame|left|500px|Module configuration for replacing enumerations inside the module]]<br />
<br style="clear: both" /><br />
<br />
In the parent configuration, we have used an enumeration with three indexes in the two variables.<br />
<br />
[[File:Replacing.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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 clickin 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.<br />
<br />
<br />
[[File:ReplacingEnumeration.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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!<br />
<br />
== Functions ==<br />
<br />
Modelica provides a convenient way to use functions in your models. You can create your own functions, import complete function libraries and share function libraries to be used in all of your models. <br />
<br />
=== Creating functions ===<br />
<br />
[[File:NewFunction.png|right]]<br />
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.<br />
<br />
Functions that can be found from Functions -folder can be used in your variable definitions.<br />
<br />
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. <br />
<br />
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.<br />
<br />
Below is an example of a simple function. For more examples, see the built-in functions provided with the tool and [https://www.modelica.org/documents/ Modelica specifications].<br />
<br />
<br style="clear: both" /><br />
<br />
[[File:ExampleFunction.png]]<br />
<br />
=== Function libraries ===<br />
<br />
<br />
[[File:NewFunctionLibrary.png|right]]<br />
<br />
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)).<br />
<br />
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. <br />
<br />
Create a new function library by right-clicking on Functions folder, Shared functions folder or other module library.<br />
<br />
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.<br />
<br />
[[File:SharedFunctions.png]]<br />
<br style="clear: both" /><br />
<br />
=== External functions ===<br />
<br />
Modelica allows you to use external functions that are programmed using C language. Below is a simple example of using a function that returns the sum of two arguments. <br />
<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}<br />
<br />
<br />
[[File:ImportCFunctionLibrary.png|right]]<br />
<br />
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 <br />
(e.g. simantics_home/plugins/org.simantics.openmodelica.win32_x/MinGW/bin/mingw32_gcc.exe -g -O -c ExampleCFunctionCode.c). <br />
<br style="clear: both" /><br />
<br />
[[File:ExampleExternalFunction.png]]<br />
<br />
<br />
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.<br />
<br />
[[File:ExternalFunctionResult.png]]<br />
<br />
<br />
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.<br />
<br />
<br />
Small external C function can also be written directly to the function code in Simantics Sysdyn:<br />
function ExampleExternalFunction<br />
input Real x;<br />
input Real y;<br />
output Real z;<br />
external "C" z=exampleCFunction(x,y) annotation(Include="<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}");<br />
end ExampleExternalFunction;<br />
<br />
=== Modelica functions ===<br />
<br />
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 [[Simantics_System_Dynamics#Builtin_functions|builtin functions for arrays]].<br />
<br />
{|<br />
|abs(x)<br />
|Returns the absolute value of x. Expanded into "(if x >= 0 then x else -x)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|acos(x)<br />
|Inverse cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|asin(x)<br />
|Inverse sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan(x)<br />
|Inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan2(x1,x2)<br />
|four quadrant inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cat(n,A,B,...)<br />
|General concatenation function that concatenates arrays A,B,... along the nth dimension.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|ceil(x)<br />
|Returns the smallest integer not less than x, the closest integer above x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cos(x)<br />
|Cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cosh(x)<br />
|Hyperbolic cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cross(x,y)<br />
|Returns the 3-vector cross product of the 3-vectors x and y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|delay(expr, delayTime)<br />
|Returns the value of expr at the time time-delayTime. The value of expr is returned when time <= time.start + delayTime.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|der(x)<br />
|Time derivative of x. X must be have continuous-time variability.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|div(x, y)<br />
|Returns the algebraic quotient x/y with any fractional part discarted. E.g. div(10,3) = 3.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|edge(b)<br />
|Returns true when the value of the boolean expression b changes. Expanded into (b and not pre(b)).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|exp(x)<br />
|Exponential, base e.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|floor(x)<br />
|Returns the largest integer not greater than x, the closest integer below x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|initial()<br />
|Returns true at the beginning of the simulation. <br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|integer(x)<br />
|Returns the largest integer not greater than x as an integer.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log(x)<br />
|Natural logarithm. (base e, x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log10(x)<br />
|Base 10 logarithm. (x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|mod(x, y)<br />
|Returns the integer modulus of x/y: mod(x,y) = x - floor(x/y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|noEvent(expr)<br />
|noEvent around an expression causes the expression to NOT generate event.<br />
'''Important:''' <br />
:If you want a condition to be checked only on time steps, use noEvent.<br />
:(e.g. if noEvent(value >= 1) then ... else ...)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|pre(x)<br />
|Returns the preceding value of y from time event that has occured before current time.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|rem(x, y)<br />
|Returns the integer remainder of x/y: rem(x,y) = x - div(x,y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sample(start, interval)<br />
|Returns true and triggers time events at times start + i * interval (i=0,1,...).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sign(x)<br />
|Returns -1 if x is negative, 1 if x is positive. Expanded into "(if x > 0 then 1 else if x < 0 then -1 else 0)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sin(x)<br />
|Sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sinh(x)<br />
|Hyperbolic sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sqrt(x)<br />
|Square root of x. The value of x must be greater or equal to 0 or an assertion error occurs.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tan(x)<br />
|Tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tanh(x)<br />
|Hyperbolic tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|terminal()<br />
|Returns true at the end of a successful simulation.<br />
|}<br />
<br />
== Spreadsheets ==<br />
<br />
Spreadsheets allow storing and maintaining values in a familiar format. The current spreadsheet implementation is experimental and does not provide much functionality. Some basic tasks can, however, be performed. You cannot type directly to a cell, you need to first copy some value or text into it. Then it can be modified.<br />
<br />
=== Variable values ===<br />
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.<br />
<br />
[[File:AuxiliarySheetReference.png|Sheet reference in an expression]][[File:AuxiliarySheet.png|Value of a variable in sheet]]<br />
<br />
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 indexes are not mandatory, but help reading and maintaining the sheet.<br />
<br />
[[File:SheetForMultidim.png|Spreadsheet for multidimensional variables]]<br />
<br />
Reference to a sheet range creates an array variable.<br />
<br />
[[File:SheetMultidim1.png|Array variable ArrayTest1[2] with sheet reference]]<br />
<br />
ArrayTest2 has two dimensions. Reference to a larger range creates a two-dimensional variable. By default, the indexes are ordered as in this example. However, if you wish to present the indexes in a different order in the spreadsheet, you can transpose the sheet reference (e.g. transpose(ArrayTestSheet(E2:G3)))<br />
<br />
[[File:SheetMultidim2.png|Array variable ArrayTest2[2,3] with sheet reference]]<br />
<br />
=== History data ===<br />
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.<br />
<br />
[[File:Sheet.png|Spreadsheet with history data]]<br />
<br />
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. <br />
<br />
[[File:HistoryDataSettings.png|History data settings]]<br />
<br />
{|<br />
|'''History data properties'''<br />
|<br />
|-<br />
|Name<br />
|Name of the history dataset<br />
|-<br />
|Sheet<br />
|Combo box for selecting a sheet where the history data is located<br />
|-<br />
|Orientation<br />
|Columns or rows. How the data is arranged in the sheet.<br />
|-<br />
|Range start<br />
|The upper-left corner cell of the history data range<br />
|-<br />
|Range end<br />
|The lower-right corner cell of the history data range<br />
|-<br />
|Time variable<br />
|The name of the time variable in the history data, if it is different than "time"<br />
|-<br />
|Variables in range<br />
|This text field displays the found variables in the given sheet and range<br />
|-<br />
|}<br />
<br />
If the history dataset is activated, history data is displayed whenever it is available for a variable that is displayed in a chart.<br />
<br />
[[File:HistoryData.png|History data in two charts]]<br />
<br />
<br />
<center><br />
[[Simantics]] | ''System Dynamics Modelling''<br />
</center><br />
<br />
----<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Basic System Dynamics Modelling]]'''<br><br />
System dynamics modelling in Simantics is a free modelling tool that is included into the basic installation. This tutorial introduces the basic features of the system dynamics modelling tool.<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Advanced System Dynamics Modelling]]'''<br><br />
This tutorial introduces the more advanced features of the system dynamics modelling tool: Modules and Operating interfaces<br />
<br />
[[Category: Simantics System Dynamics]]</div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=Tutorial:_Advanced_System_Dynamics_Modelling&diff=583Tutorial: Advanced System Dynamics Modelling2012-10-12T11:12:37Z<p>Teemu Lempinen: /* Adding modules */</p>
<hr />
<div>In this tutorial, we are going to bild a work model with two projects and shared workforce. Both the workforce and a separate project (work) are going to be created as modules, so they can be reused several times. Actually the model doesn't limit the number of projects at all.<br />
<br />
===Creating model and modules===<br />
<br />
Let's start by creating the work model and the needed modules. First create a new model by right-clicking on the model browser and selecting New->Model. Alternatively you can select File->New Model from the main menu.<br />
<br />
Then create two new modules to your model. Right-click on the Modules folder and select New->Module. <br />
<br />
Name your model WorkModel and modules WorkforceModule and WorkModule. You can rename them by right-clicking on the item on the model browser and selecting Rename. <br />
<br />
{|<br />
|[[File:NewModel.png|none|frame|Creating a new model]]<br />
|[[File:NewModule.png|none|frame|Creating a new module]]<br />
|[[File:ModelStructure2.png|none|frame|Model after renaming]]<br />
|}<br />
<br />
===Initial configuration===<br />
<br />
[[File:TwoModules.png|right|frame|Workforce and Work modules]]<br />
We will use a top-down approach in our model, so first we will make a simple model configuration with our modules. Open our model configuration by double-clicking Configuration in your model browser. <br />
<br />
Drag one WorkforceModule and one WorkModule from your model browser to the WorkModel diagram. The modules are automatically named with a suffix number. Rename the modules to Workforce and Work1. You can rename objects on the diagram by double-clicking them or selecting them with one click and renaming them on the properties view below the diagram.<br />
<br style="clear: both" /><br />
<br />
[[File:ConfigurationStart.png|right|frame|Workforce and Work modules, first inputs and connections]]<br />
When the modules are on the diagram, we should think what values we would like to get from the modules and what values we would like to use in the modules. <br />
<br />
Workforce needs to know, how much work is required and it should provide information on how much work can be done. To provide the information on how much work can be done, we need an Input variable. Variables can be dragged to the diagram from Symbols view or by using [[System Dynamics Modelling#Shortcut and control keys|shortcut keys]] (Shift+I for Input variable). Drag an input variable to the diagram and name it TotalPossibleWorkingSpeed.<br />
<br />
Work module on the other hand provides information on how much work is required in it and it needs to know when the work has to be ready. Create an input variable RequiredWorkingSpeed1 and an Auxiliary variable Work1CompletionTime and place all variables like in the picture on the right. <br />
<br />
Connect the variables to modules using dependency connections (arrows). Connections are created by holding down Alt key and first clicking on the variable where to start the connection and then clicking on the variable where to end.<br />
<br />
Now we have the initial idea of the model, so let's configure the modules.<br />
<br style="clear: both" /><br />
<br />
===Workforce module===<br />
<br />
[[File:NetResourcing1.png|right|frame|Cloud, Valve, Flow and Stock]]<br />
Open Workforce module by selecting it from the diagram, right-clicking it and selecting Show Module.<br />
<br />
Create a Stock variable and name it WorkforceStock. Stock variables are created the same way as Input and Auxiliary variables. The level of the stock is controlled with a valve and a flow. To create the flow, hold down Alt and right-click on an empty space left of the stock. Then left-click on the stock. A cloud, valve and a flow is created. Rename the valve to NetResourcing.<br />
<br style="clear: both" /><br />
[[File:NetResourcing2.png|right|frame|Cloud, Valve, Flow and Stock. Flow works both on directions.]]<br />
NetResourcing works both ways. To display this also visually, delete the cloud by selecting it and pressing delete on your keyboard. Then create a flow starting from NetResourcing valve and ending on an empty space next to it.<br />
<br style="clear: both" /><br />
<br />
[[File:WorkforceAuxiliaries.png|right|frame|Auxiliaries in Workforce module]]<br />
Now you have used all the basic components and connections. From now on the instructions will be a more simplified.<br />
<br />
Next we will create four Auxiliary variables: TimeToAllocateResources, WorkforceRequired, Productivity and PossibleWorkingSpeed. Place and connect them according to the picture on the right.<br />
<br />
To be able to simulate the model, all variables must have valid equations. To configure an equation, select a variable. Variable's properties are shown in the Property view and you can input the required equations in the text fields. You can copy the equations directly from here or type them manually. Variables connected to the selected variable are shown in the Variables list. To speed up typing, you can double click on a variable name and it will be inserted to the equation.<br />
<br />
WorkforceStock <br /><br />
Initial value: 0<br />
<br />
NetResourcing <br /><br />
= (WorkforceRequired - WorkforceStock)/TimeToAllocateResources<br />
<br />
TimeToAllocateResources <br /><br />
= 2<br />
<br />
Productivity <br /><br />
= 1<br />
<br />
PossibleWorkingSpeed <br /><br />
= WorkforceStock * Productivity<br /><br />
Is Output<br />
<br />
Variables can be set as output by selecting Is Output option from Additional information tab of the variable. <br />
<br />
<br style="clear: both" /><br />
[[File:RequiredWorkingSpeedInput.png|right|frame|RequiredWorkingSpeedInput]]<br />
On a previous phase, we wanted to give the value of RequiredWorkingSpeed1 to this workforce module. To get that value, we need to create an input. Create input RequiredWorkingSpeedInput, connect it to WorkforceRequired and write the following equation to WorkforceRequired.<br />
<br />
WorkForceRequired <br /><br />
= RequiredWorkingSpeedInput/Productivity<br />
<br />
Now this module is ready to be used as a part of the model.<br />
<br />
<br style="clear: both" /><br />
<br />
===Work module===<br />
<br />
[[File:WorkStocks.png|right|frame|Basic work with errors]]<br />
Open Work1 module by selecting it from the WorkModel diagram, right-clicking it and selecting Show Module. Alternatively you can double click Work1 on the model browser.<br />
<br />
Create the basic flow of work with stocks and flows like in the picture on the right. <br />
<br />
The idea of the model is that first there is work. Work is done at a certain speed. When working, errors are also made. When errors are found, the amount of Errors is reduced, errors are removed from WorkDone and moved back to WorkToDo.<br />
<br />
<br style="clear: both" /><br />
<br />
<br />
[[File:ProjectIsReady.png|right|frame|Smoothener for work is done]]<br />
Work needs to be stopped when the project is ready. Since the simulator might face some difficulties to determine the projects readyness when project is almost ready, we need to implement some smoothing to the limit. OpenModelica doesn't yet have a builtin function for smoothing, so we need to implement our own. Create variables and connections according to the picture on the right.<br />
<br />
Use the following equations for variables:<br />
<br />
ProjectIsReady <br /><br />
Initial value: 0<br />
<br />
ProjectReadyness <br /><br />
= (xidz(WorkDone, ProjectWorkAmount, 0.0) - ProjectIsReady) / 0.08<br />
<br />
xidz is short for function X if devided by zero. This means that the simulation calculates ''WorkDone / ProjectWorkAmount''. If ProjectWorkAmount is zero, the result is the third argument ''0.0''.<br />
<br />
[[File:ProjectWorkAmount.png|right|frame|ProjectWorkAmount input variable]]<br />
As you can see, ProjectWorkAmount is highlighted. Your model doesn't contain such variable and it is not connected to ProjectReadyness. Create an Input variable ProjectWorkAmount with default value 1000 and connect it to ProjectReadyness. The reason we are using input variable is that you can determine the default size of a project, but if you want to change it, you can change it from outside the module. <br />
<br />
<br style="clear: both" /><br />
<br />
[[File:ErrorsVariables.png|right|frame|Variables needed for error handling]]<br />
Next we need to define how errors are found. For that we need new variables: WorkQuality and ErrorsFoundTime. Create the variables and connections according to the picture and give variables their equations.<br />
<br />
ErrorsGenerated<br /><br />
= (1-WorkQuality) * WorkingSpeed<br />
<br />
ErrorsFoundRate<br /><br />
= Errors/ErrorsFoundTime<br />
<br />
WorkQuality<br /><br />
= 0.9<br />
<br />
ErrorsFoundTime<br /><br />
Type: WithLookup<br /><br />
With Lookup: xidz(WorkDone, ProjectWorkAmount, 0.0) <br /><br />
Lookup table: {{0,5},{0.5,3},{1,0.5},{2,0.5}}<br />
<br />
WithLookup is a variable type where the value is interpolated from a 2-dimensional table (Lookup table) using the value determined in the "With Lookup" field. Type can be changed from the drop-down menu Type.<br />
<br />
<br style="clear: both" /><br />
<br />
[[File:WorkAllocation.png|right|frame|WorkAllocation and RequiredWorkingSpeed]]<br />
To calculate our own need for workforce we need to create and connect WorkCompletionTime input variable and the following auxliary variables:<br />
<br />
RequiredWorkingSpeed <br /><br />
= if ProjectIsReady < 1 then xidz(WorkToDo, TimeToDeadline, MaximumWorkingSpeed) else 0<br /><br />
Is Output<br />
<br />
MaximumWorkingSpeed <br /><br />
= 500<br />
<br />
TimeToDeadline <br /><br />
= max(0, WorkCompletionTime-time)<br />
<br />
time is a universal variable that gives the current simulation time.<br />
<br />
<br />
We need to decide how the workforce is allocated between all the work modules that are using the same workforce. For that we need to know how much work can be done and how much workforce other works require. <br />
<br />
Create two Inputs, RequiredWorkingSpeedTotalInput and PossibleWorkingSpeedInput, and an auxiliary variable WorkAllocation. Connect the variables like int the picture.<br />
<br />
WorkAllocation<br /><br />
= xidz(RequiredWorkingSpeed, RequiredWorkingSpeedTotalInput, 0.0) * PossibleWorkingSpeedInput<br />
<br style="clear: both" /><br />
<br />
Finally let's give initial values for all the remaining variables:<br />
<br />
WorkingSpeed <br /><br />
= if ProjectIsReady < 1 then WorkAllocation else 0<br />
<br />
WorkToDo <br /><br />
Initial value: ProjectWorkAmount<br />
<br />
WorkDone <br /><br />
Initial value: 0<br />
<br />
Errors <br /><br />
Initial value: 0<br />
<br />
===Connecting modules===<br />
<br />
Our modules are complete. Let's get back to the WorkModel Configuration. <br />
<br />
Set Work1CompletionTime to 10.<br />
<br />
[[File:ModuleConnections1.png|right|frame|Module input connections]]<br />
Connections between modules are made in the properties of the module. Select Work1 and open tab Inputs from the properties. The table lists all input variables in the module that are available. Clicking on the Refers to output column will open a drop-down menu that shows all available variables that are connected to the module. By selecting a variable, you connect that variable to the input.<br />
<br style="clear: both" /><br />
<br />
[[File:RequiredWorkingSpeed1Connection.png|right|thumb|Connection from RequiredWorkingSpeed to Work1]]<br />
[[File:ModuleConnections2.png|right|frame|Module input connections]]<br />
Work1 need also information on how much working speed is required by all works. Since Work1 is the only work, create a dependency connection from RequiredWorkingSpeed1 to Work1 and in Work1's properties connect it to RequiredWorkingSpeedTotalInput. <br />
<br style="clear: both" /><br />
<br />
In Outputs tab, make the only possible connection: from RequiredWorkingSpeed to RequiredWorkingSpeed1.<br />
<br />
Workforce module has only one input and one output. Create the only possible connections:<br /><br />
(Inputs) RequiredWorkingSpeedInput -> RequiredWorkingSpeed1<br /><br />
(Outputs) PossibleWorkingSpeed -> TotalPossibleWorkingSpeed<br />
<br />
Now your model is ready for simulation!<br />
<br />
===Simulating the model===<br />
<br />
To make the simulation time longer, select Configuration on the model browser. Give the model Stop time 24.0<br />
<br />
[[File:ActivateExperiment.png|right|frame|Experiment activation]]<br />
To run simulations, you must activate an experiment. Expand the experiments folder on your model browser. There is one ready-made experiment. Double click on the experiment and the experiment control buttons appear on the toolbar. Press the play button [[File:ExperimentPlay.png]].<br />
<br />
System shows the simulation progress in the progress bar on the lower right corner of the screen. <br />
<br />
[[File:SimulationProgress.png]]<br />
<br />
When the progress indicator disappears, the simulation is complete.<br />
<br />
If the Console view pops up and shows an error "Error: Too few equations, underdetermined system. The model has X equation(s) and Y variable(s)", the simulation has failed. The reason might be that you forgot to assign an equation to some variable or some connection in modules. See through all the variables, write the missing equation and simulate again.<br />
<br />
After the simulation is succesfully run, you can select a variable and see its simulation results in the trend view. For example WorkDone variable in Work1 module will give the following graph.<br />
<br />
[[File:FirstSimulation.png]]<br />
<br />
<br style="clear: both" /><br />
<br />
===Adding modules===<br />
<br />
[[File:ModulesFinal.png|right|frame|Final configuration with two modules]]<br />
We created the WorkModule to be reusable. To use two WorkModules in the model, you must do the following.<br />
<br />
Populate a second WorkModule to WorkModel configuration and name it Work2. <br />
<br />
Create RequiredWorkingSpeed2 input variable and Work2CompletionTime auxiliary variable.<br />
<br />
We need a sum of all working speed requirements to give to the work modules. For this purpose, create an auxiliary variable RequiredWorkingSpeedTotal which sums the requirements.<br />
<br />
You can also have a different size work. To make Work2 smaller, create an auxiliary variable Work2Amount.<br />
<br />
Use the following equations:<br />
<br />
Work2CompletionTime<br /><br />
= 13<br />
<br />
Work2Amount<br /><br />
= 800<br />
<br />
RequiredWorkingSpeedTotal<br /><br />
= RequiredWorkingSpeed1 + RequiredWorkingSpeed2<br />
<br />
Update connections to match connections shown in the picture and connect the inputs and outputs to the modules.<br />
<br />
Workforce<br /><br />
RequiredWorkingSpeedInput -> RequiredWorkingSpeedTotal<br />
<br />
Work1 Inputs<br /><br />
RequiredWorkingSpeedTotalInput -> RequiredWorkingSpeedTotal<br />
<br />
Work2 Outputs<br /><br />
RequiredWorkingSpeed -> RequiredWorkingSpeed2<br />
<br />
Work2 Inputs<br /><br />
[[File:Module2Inputs.png]]<br />
<br />
<br />
When all the connections are made, you can simulate the model again. Now you have model with two work modules. Select variables from both modules in model browser to display them in trend view.<br />
<br />
[[File:SecondSimulation.png]]<br />
<br />
<br style="clear: both" /><br />
<br />
<!---<br />
Operating interfaces not supported right now<br />
===Creating an Operating Interface===<br />
<br />
[[File:NewOperatingUI.png|right|frame|New Operating UI]]<br />
To use the model and adjust its parameters without seeing the actual model, we can use Operating interfaces. Create a new operating interface by right-clicking Operating interfaces on the model browser and selecting New -> Operating UI. Double click the created operating ui to open it.<br />
<br />
Switch to Symbols view. WidgetLibrary shows all the widgets that can be used when creating an operating interface. We will create a simple interface with a trend and two sliders. <br />
<br style="clear: both" /><br />
<br />
[[File:FirstOUI.png|right|frame|Operating UI with a trend and two sliders]]<br />
Drag a trend to the diagram. Adjust the size of the trend so that it is larger. The size of the elements can be adjusted by first selecting the element and then draggign from the lower right corner of the element.<br />
<br />
Then drag two sliders to the right side of the trend.<br />
<br />
Now you should have an operating user interface that looks something like the picture on the right.<br />
<br />
To be able to use the interface, we need to configure the elements and connect them to the actual variables on the model. First let's configure the sliders.<br />
<br />
We are going to adjust the time when Work1 and Work2 are ready. Our simulation time ranges from 0 to 24, so that is the range that we are going to use in our sliders. Select one of the sliders. The Property view shows all the different properties that can be configured in the element. Do the following settings for both sliders:<br />
<br />
[[File:SliderProperties.png|none|frame|Slider properties]]<br />
<br />
Then select the trend element. Set its Title to "Work1 and Work2" and Y-Axis Label to "Work Done"<br />
<br />
Now we need to connect the actual variables to the elements. From Model Browser, drag Work1CompletionTime to the first slider and Work2CompletionTime to the second slider.<br />
<br />
Then from each of the Work module, drag WorkDone to the trend element.<br />
<br />
Activate an experiment by double clicking it, activate the Operating UI by clicking it and switch it to operating mode with the switch button [[File:OperatingModeSwitch.png]] on the main toolbar.<br />
<br />
Run a simulation. The trend element should show the results of the simulation. Adjust the completion times from the sliders and simulate again.<br />
<br />
[[File:OperatingUI.png|none|frame|Ready Operating interface]]<br />
<br />
<br style="clear: both" /><br />
<br />
--><br />
<br />
<br />
[[Category:Tutorials]]</div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:ModuleConnections2.png&diff=582File:ModuleConnections2.png2012-10-08T09:34:19Z<p>Teemu Lempinen: uploaded a new version of "File:ModuleConnections2.png"</p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:ModuleConnections1.png&diff=581File:ModuleConnections1.png2012-10-08T09:34:12Z<p>Teemu Lempinen: uploaded a new version of "File:ModuleConnections1.png"</p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:ModuleConnections1.png&diff=580File:ModuleConnections1.png2012-10-08T09:32:14Z<p>Teemu Lempinen: uploaded a new version of "File:ModuleConnections1.png"</p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:ModuleConnections2.png&diff=579File:ModuleConnections2.png2012-10-08T09:32:02Z<p>Teemu Lempinen: uploaded a new version of "File:ModuleConnections2.png"</p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:Module2Inputs.png&diff=578File:Module2Inputs.png2012-10-08T06:21:22Z<p>Teemu Lempinen: uploaded a new version of "File:Module2Inputs.png"</p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:Module2Inputs.png&diff=577File:Module2Inputs.png2012-10-08T06:20:27Z<p>Teemu Lempinen: uploaded a new version of "File:Module2Inputs.png"</p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=Tutorial:_Hands-on_Exercises_with_a_model_template&diff=576Tutorial: Hands-on Exercises with a model template2012-08-27T07:24:54Z<p>Teemu Lempinen: </p>
<hr />
<div>This is a tutorial built for a system dynamics training session. The software used in this example is from May 2011, so many features have changed since then.<br />
<br />
# Download Simantics System Dynamics software: [https://www.simantics.org/simantics/files/Sysdyn.zip Sysdyn.zip].<br />
# Download [https://www.simantics.org/simantics/files/WorkModelTemplate.tg Model template].<br />
# Proceed with the exercies according to the [https://www.simantics.org/simantics/files/Training25.5.2011.pdf exercise documentation].<br />
<br />
[[Category:Tutorials]]</div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=Tutorial:_Advanced_System_Dynamics_Modelling&diff=575Tutorial: Advanced System Dynamics Modelling2012-08-27T07:23:33Z<p>Teemu Lempinen: </p>
<hr />
<div>In this tutorial, we are going to bild a work model with two projects and shared workforce. Both the workforce and a separate project (work) are going to be created as modules, so they can be reused several times. Actually the model doesn't limit the number of projects at all.<br />
<br />
===Creating model and modules===<br />
<br />
Let's start by creating the work model and the needed modules. First create a new model by right-clicking on the model browser and selecting New->Model. Alternatively you can select File->New Model from the main menu.<br />
<br />
Then create two new modules to your model. Right-click on the Modules folder and select New->Module. <br />
<br />
Name your model WorkModel and modules WorkforceModule and WorkModule. You can rename them by right-clicking on the item on the model browser and selecting Rename. <br />
<br />
{|<br />
|[[File:NewModel.png|none|frame|Creating a new model]]<br />
|[[File:NewModule.png|none|frame|Creating a new module]]<br />
|[[File:ModelStructure2.png|none|frame|Model after renaming]]<br />
|}<br />
<br />
===Initial configuration===<br />
<br />
[[File:TwoModules.png|right|frame|Workforce and Work modules]]<br />
We will use a top-down approach in our model, so first we will make a simple model configuration with our modules. Open our model configuration by double-clicking Configuration in your model browser. <br />
<br />
Drag one WorkforceModule and one WorkModule from your model browser to the WorkModel diagram. The modules are automatically named with a suffix number. Rename the modules to Workforce and Work1. You can rename objects on the diagram by double-clicking them or selecting them with one click and renaming them on the properties view below the diagram.<br />
<br style="clear: both" /><br />
<br />
[[File:ConfigurationStart.png|right|frame|Workforce and Work modules, first inputs and connections]]<br />
When the modules are on the diagram, we should think what values we would like to get from the modules and what values we would like to use in the modules. <br />
<br />
Workforce needs to know, how much work is required and it should provide information on how much work can be done. To provide the information on how much work can be done, we need an Input variable. Variables can be dragged to the diagram from Symbols view or by using [[System Dynamics Modelling#Shortcut and control keys|shortcut keys]] (Shift+I for Input variable). Drag an input variable to the diagram and name it TotalPossibleWorkingSpeed.<br />
<br />
Work module on the other hand provides information on how much work is required in it and it needs to know when the work has to be ready. Create an input variable RequiredWorkingSpeed1 and an Auxiliary variable Work1CompletionTime and place all variables like in the picture on the right. <br />
<br />
Connect the variables to modules using dependency connections (arrows). Connections are created by holding down Alt key and first clicking on the variable where to start the connection and then clicking on the variable where to end.<br />
<br />
Now we have the initial idea of the model, so let's configure the modules.<br />
<br style="clear: both" /><br />
<br />
===Workforce module===<br />
<br />
[[File:NetResourcing1.png|right|frame|Cloud, Valve, Flow and Stock]]<br />
Open Workforce module by selecting it from the diagram, right-clicking it and selecting Show Module.<br />
<br />
Create a Stock variable and name it WorkforceStock. Stock variables are created the same way as Input and Auxiliary variables. The level of the stock is controlled with a valve and a flow. To create the flow, hold down Alt and right-click on an empty space left of the stock. Then left-click on the stock. A cloud, valve and a flow is created. Rename the valve to NetResourcing.<br />
<br style="clear: both" /><br />
[[File:NetResourcing2.png|right|frame|Cloud, Valve, Flow and Stock. Flow works both on directions.]]<br />
NetResourcing works both ways. To display this also visually, delete the cloud by selecting it and pressing delete on your keyboard. Then create a flow starting from NetResourcing valve and ending on an empty space next to it.<br />
<br style="clear: both" /><br />
<br />
[[File:WorkforceAuxiliaries.png|right|frame|Auxiliaries in Workforce module]]<br />
Now you have used all the basic components and connections. From now on the instructions will be a more simplified.<br />
<br />
Next we will create four Auxiliary variables: TimeToAllocateResources, WorkforceRequired, Productivity and PossibleWorkingSpeed. Place and connect them according to the picture on the right.<br />
<br />
To be able to simulate the model, all variables must have valid equations. To configure an equation, select a variable. Variable's properties are shown in the Property view and you can input the required equations in the text fields. You can copy the equations directly from here or type them manually. Variables connected to the selected variable are shown in the Variables list. To speed up typing, you can double click on a variable name and it will be inserted to the equation.<br />
<br />
WorkforceStock <br /><br />
Initial value: 0<br />
<br />
NetResourcing <br /><br />
= (WorkforceRequired - WorkforceStock)/TimeToAllocateResources<br />
<br />
TimeToAllocateResources <br /><br />
= 2<br />
<br />
Productivity <br /><br />
= 1<br />
<br />
PossibleWorkingSpeed <br /><br />
= WorkforceStock * Productivity<br /><br />
Is Output<br />
<br />
Variables can be set as output by selecting Is Output option from Additional information tab of the variable. <br />
<br />
<br style="clear: both" /><br />
[[File:RequiredWorkingSpeedInput.png|right|frame|RequiredWorkingSpeedInput]]<br />
On a previous phase, we wanted to give the value of RequiredWorkingSpeed1 to this workforce module. To get that value, we need to create an input. Create input RequiredWorkingSpeedInput, connect it to WorkforceRequired and write the following equation to WorkforceRequired.<br />
<br />
WorkForceRequired <br /><br />
= RequiredWorkingSpeedInput/Productivity<br />
<br />
Now this module is ready to be used as a part of the model.<br />
<br />
<br style="clear: both" /><br />
<br />
===Work module===<br />
<br />
[[File:WorkStocks.png|right|frame|Basic work with errors]]<br />
Open Work1 module by selecting it from the WorkModel diagram, right-clicking it and selecting Show Module. Alternatively you can double click Work1 on the model browser.<br />
<br />
Create the basic flow of work with stocks and flows like in the picture on the right. <br />
<br />
The idea of the model is that first there is work. Work is done at a certain speed. When working, errors are also made. When errors are found, the amount of Errors is reduced, errors are removed from WorkDone and moved back to WorkToDo.<br />
<br />
<br style="clear: both" /><br />
<br />
<br />
[[File:ProjectIsReady.png|right|frame|Smoothener for work is done]]<br />
Work needs to be stopped when the project is ready. Since the simulator might face some difficulties to determine the projects readyness when project is almost ready, we need to implement some smoothing to the limit. OpenModelica doesn't yet have a builtin function for smoothing, so we need to implement our own. Create variables and connections according to the picture on the right.<br />
<br />
Use the following equations for variables:<br />
<br />
ProjectIsReady <br /><br />
Initial value: 0<br />
<br />
ProjectReadyness <br /><br />
= (xidz(WorkDone, ProjectWorkAmount, 0.0) - ProjectIsReady) / 0.08<br />
<br />
xidz is short for function X if devided by zero. This means that the simulation calculates ''WorkDone / ProjectWorkAmount''. If ProjectWorkAmount is zero, the result is the third argument ''0.0''.<br />
<br />
[[File:ProjectWorkAmount.png|right|frame|ProjectWorkAmount input variable]]<br />
As you can see, ProjectWorkAmount is highlighted. Your model doesn't contain such variable and it is not connected to ProjectReadyness. Create an Input variable ProjectWorkAmount with default value 1000 and connect it to ProjectReadyness. The reason we are using input variable is that you can determine the default size of a project, but if you want to change it, you can change it from outside the module. <br />
<br />
<br style="clear: both" /><br />
<br />
[[File:ErrorsVariables.png|right|frame|Variables needed for error handling]]<br />
Next we need to define how errors are found. For that we need new variables: WorkQuality and ErrorsFoundTime. Create the variables and connections according to the picture and give variables their equations.<br />
<br />
ErrorsGenerated<br /><br />
= (1-WorkQuality) * WorkingSpeed<br />
<br />
ErrorsFoundRate<br /><br />
= Errors/ErrorsFoundTime<br />
<br />
WorkQuality<br /><br />
= 0.9<br />
<br />
ErrorsFoundTime<br /><br />
Type: WithLookup<br /><br />
With Lookup: xidz(WorkDone, ProjectWorkAmount, 0.0) <br /><br />
Lookup table: {{0,5},{0.5,3},{1,0.5},{2,0.5}}<br />
<br />
WithLookup is a variable type where the value is interpolated from a 2-dimensional table (Lookup table) using the value determined in the "With Lookup" field. Type can be changed from the drop-down menu Type.<br />
<br />
<br style="clear: both" /><br />
<br />
[[File:WorkAllocation.png|right|frame|WorkAllocation and RequiredWorkingSpeed]]<br />
To calculate our own need for workforce we need to create and connect WorkCompletionTime input variable and the following auxliary variables:<br />
<br />
RequiredWorkingSpeed <br /><br />
= if ProjectIsReady < 1 then xidz(WorkToDo, TimeToDeadline, MaximumWorkingSpeed) else 0<br /><br />
Is Output<br />
<br />
MaximumWorkingSpeed <br /><br />
= 500<br />
<br />
TimeToDeadline <br /><br />
= max(0, WorkCompletionTime-time)<br />
<br />
time is a universal variable that gives the current simulation time.<br />
<br />
<br />
We need to decide how the workforce is allocated between all the work modules that are using the same workforce. For that we need to know how much work can be done and how much workforce other works require. <br />
<br />
Create two Inputs, RequiredWorkingSpeedTotalInput and PossibleWorkingSpeedInput, and an auxiliary variable WorkAllocation. Connect the variables like int the picture.<br />
<br />
WorkAllocation<br /><br />
= xidz(RequiredWorkingSpeed, RequiredWorkingSpeedTotalInput, 0.0) * PossibleWorkingSpeedInput<br />
<br style="clear: both" /><br />
<br />
Finally let's give initial values for all the remaining variables:<br />
<br />
WorkingSpeed <br /><br />
= if ProjectIsReady < 1 then WorkAllocation else 0<br />
<br />
WorkToDo <br /><br />
Initial value: ProjectWorkAmount<br />
<br />
WorkDone <br /><br />
Initial value: 0<br />
<br />
Errors <br /><br />
Initial value: 0<br />
<br />
===Connecting modules===<br />
<br />
Our modules are complete. Let's get back to the WorkModel Configuration. <br />
<br />
Set Work1CompletionTime to 10.<br />
<br />
[[File:ModuleConnections1.png|right|frame|Module input connections]]<br />
Connections between modules are made in the properties of the module. Select Work1 and open tab Inputs from the properties. The table lists all input variables in the module that are available. Clicking on the Refers to output column will open a drop-down menu that shows all available variables that are connected to the module. By selecting a variable, you connect that variable to the input.<br />
<br style="clear: both" /><br />
<br />
[[File:RequiredWorkingSpeed1Connection.png|right|thumb|Connection from RequiredWorkingSpeed to Work1]]<br />
[[File:ModuleConnections2.png|right|frame|Module input connections]]<br />
Work1 need also information on how much working speed is required by all works. Since Work1 is the only work, create a dependency connection from RequiredWorkingSpeed1 to Work1 and in Work1's properties connect it to RequiredWorkingSpeedTotalInput. <br />
<br style="clear: both" /><br />
<br />
In Outputs tab, make the only possible connection: from RequiredWorkingSpeed to RequiredWorkingSpeed1.<br />
<br />
Workforce module has only one input and one output. Create the only possible connections:<br /><br />
(Inputs) RequiredWorkingSpeedInput -> RequiredWorkingSpeed1<br /><br />
(Outputs) PossibleWorkingSpeed -> TotalPossibleWorkingSpeed<br />
<br />
Now your model is ready for simulation!<br />
<br />
===Simulating the model===<br />
<br />
To make the simulation time longer, select Configuration on the model browser. Give the model Stop time 24.0<br />
<br />
[[File:ActivateExperiment.png|right|frame|Experiment activation]]<br />
To run simulations, you must activate an experiment. Expand the experiments folder on your model browser. There is one ready-made experiment. Double click on the experiment and the experiment control buttons appear on the toolbar. Press the play button [[File:ExperimentPlay.png]].<br />
<br />
System shows the simulation progress in the progress bar on the lower right corner of the screen. <br />
<br />
[[File:SimulationProgress.png]]<br />
<br />
When the progress indicator disappears, the simulation is complete.<br />
<br />
If the Console view pops up and shows an error "Error: Too few equations, underdetermined system. The model has X equation(s) and Y variable(s)", the simulation has failed. The reason might be that you forgot to assign an equation to some variable or some connection in modules. See through all the variables, write the missing equation and simulate again.<br />
<br />
After the simulation is succesfully run, you can select a variable and see its simulation results in the trend view. For example WorkDone variable in Work1 module will give the following graph.<br />
<br />
[[File:FirstSimulation.png]]<br />
<br />
<br style="clear: both" /><br />
<br />
===Adding modules===<br />
<br />
[[File:ModulesFinal.png|right|frame|Final configuration with two modules]]<br />
We created the WorkModule to be reusable. To use two WorkModules in the model, you must do the following.<br />
<br />
Populate a second WorkModule to WorkModel configuration and name it Work2. <br />
<br />
Create RequiredWorkingSpeed2 input variable and Work2CompletionTime auxiliary variable.<br />
<br />
We need a sum of all working speed requirements to give to the work modules. For this purpose, create an auxiliary variable RequiredWorkingSpeedTotal which sums the requirements.<br />
<br />
You can also have a different size work. To make Work2 smaller, create an auxiliary variable Work2Amount.<br />
<br />
Use the following equations:<br />
<br />
Work2CompletionTime<br /><br />
= 13<br />
<br />
Work2Amount<br /><br />
= 800<br />
<br />
RequiredWorkingSpeedTotal<br /><br />
= RequiredWorkingSpeed1 + RequiredWorkingSpeed2<br />
<br />
Update connections to match connections shown in the picture and connect the inputs and outputs to the modules.<br />
<br />
Workforce<br /><br />
RequiredWorkingSpeedInput -> RequiredWorkingSpeedTotal<br />
<br />
Work1 Inputs<br /><br />
RequiredWorkingSpeedTotalInput -> RequiredWorkingSpeedTotal<br />
<br />
Work2 Outputs<br /><br />
RequiredWorkingSpeed -> RequiredWorkingSpeed2<br />
<br />
Work2 Inputs<br /><br />
[[File:Module2Inputs.png]]<br />
<br />
<br />
When all the connections are made, you can simulate the model again. Now you have model with two work modules.<br />
<br />
[[File:SecondSimulation.png]]<br />
<br />
<br style="clear: both" /><br />
<br />
<!---<br />
Operating interfaces not supported right now<br />
===Creating an Operating Interface===<br />
<br />
[[File:NewOperatingUI.png|right|frame|New Operating UI]]<br />
To use the model and adjust its parameters without seeing the actual model, we can use Operating interfaces. Create a new operating interface by right-clicking Operating interfaces on the model browser and selecting New -> Operating UI. Double click the created operating ui to open it.<br />
<br />
Switch to Symbols view. WidgetLibrary shows all the widgets that can be used when creating an operating interface. We will create a simple interface with a trend and two sliders. <br />
<br style="clear: both" /><br />
<br />
[[File:FirstOUI.png|right|frame|Operating UI with a trend and two sliders]]<br />
Drag a trend to the diagram. Adjust the size of the trend so that it is larger. The size of the elements can be adjusted by first selecting the element and then draggign from the lower right corner of the element.<br />
<br />
Then drag two sliders to the right side of the trend.<br />
<br />
Now you should have an operating user interface that looks something like the picture on the right.<br />
<br />
To be able to use the interface, we need to configure the elements and connect them to the actual variables on the model. First let's configure the sliders.<br />
<br />
We are going to adjust the time when Work1 and Work2 are ready. Our simulation time ranges from 0 to 24, so that is the range that we are going to use in our sliders. Select one of the sliders. The Property view shows all the different properties that can be configured in the element. Do the following settings for both sliders:<br />
<br />
[[File:SliderProperties.png|none|frame|Slider properties]]<br />
<br />
Then select the trend element. Set its Title to "Work1 and Work2" and Y-Axis Label to "Work Done"<br />
<br />
Now we need to connect the actual variables to the elements. From Model Browser, drag Work1CompletionTime to the first slider and Work2CompletionTime to the second slider.<br />
<br />
Then from each of the Work module, drag WorkDone to the trend element.<br />
<br />
Activate an experiment by double clicking it, activate the Operating UI by clicking it and switch it to operating mode with the switch button [[File:OperatingModeSwitch.png]] on the main toolbar.<br />
<br />
Run a simulation. The trend element should show the results of the simulation. Adjust the completion times from the sliders and simulate again.<br />
<br />
[[File:OperatingUI.png|none|frame|Ready Operating interface]]<br />
<br />
<br style="clear: both" /><br />
<br />
--><br />
<br />
<br />
[[Category:Tutorials]]</div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=Tutorial:_Advanced_System_Dynamics_Modelling&diff=574Tutorial: Advanced System Dynamics Modelling2012-08-27T07:22:55Z<p>Teemu Lempinen: /* Creating an Operating Interface */</p>
<hr />
<div>In this tutorial, we are going to bild a work model with two projects and shared workforce. Both the workforce and a separate project (work) are going to be created as modules, so they can be reused several times. Actually the model doesn't limit the number of projects at all. We are also going to create an operating interface for the finished model.<br />
<br />
===Creating model and modules===<br />
<br />
Let's start by creating the work model and the needed modules. First create a new model by right-clicking on the model browser and selecting New->Model. Alternatively you can select File->New Model from the main menu.<br />
<br />
Then create two new modules to your model. Right-click on the Modules folder and select New->Module. <br />
<br />
Name your model WorkModel and modules WorkforceModule and WorkModule. You can rename them by right-clicking on the item on the model browser and selecting Rename. <br />
<br />
{|<br />
|[[File:NewModel.png|none|frame|Creating a new model]]<br />
|[[File:NewModule.png|none|frame|Creating a new module]]<br />
|[[File:ModelStructure2.png|none|frame|Model after renaming]]<br />
|}<br />
<br />
===Initial configuration===<br />
<br />
[[File:TwoModules.png|right|frame|Workforce and Work modules]]<br />
We will use a top-down approach in our model, so first we will make a simple model configuration with our modules. Open our model configuration by double-clicking Configuration in your model browser. <br />
<br />
Drag one WorkforceModule and one WorkModule from your model browser to the WorkModel diagram. The modules are automatically named with a suffix number. Rename the modules to Workforce and Work1. You can rename objects on the diagram by double-clicking them or selecting them with one click and renaming them on the properties view below the diagram.<br />
<br style="clear: both" /><br />
<br />
[[File:ConfigurationStart.png|right|frame|Workforce and Work modules, first inputs and connections]]<br />
When the modules are on the diagram, we should think what values we would like to get from the modules and what values we would like to use in the modules. <br />
<br />
Workforce needs to know, how much work is required and it should provide information on how much work can be done. To provide the information on how much work can be done, we need an Input variable. Variables can be dragged to the diagram from Symbols view or by using [[System Dynamics Modelling#Shortcut and control keys|shortcut keys]] (Shift+I for Input variable). Drag an input variable to the diagram and name it TotalPossibleWorkingSpeed.<br />
<br />
Work module on the other hand provides information on how much work is required in it and it needs to know when the work has to be ready. Create an input variable RequiredWorkingSpeed1 and an Auxiliary variable Work1CompletionTime and place all variables like in the picture on the right. <br />
<br />
Connect the variables to modules using dependency connections (arrows). Connections are created by holding down Alt key and first clicking on the variable where to start the connection and then clicking on the variable where to end.<br />
<br />
Now we have the initial idea of the model, so let's configure the modules.<br />
<br style="clear: both" /><br />
<br />
===Workforce module===<br />
<br />
[[File:NetResourcing1.png|right|frame|Cloud, Valve, Flow and Stock]]<br />
Open Workforce module by selecting it from the diagram, right-clicking it and selecting Show Module.<br />
<br />
Create a Stock variable and name it WorkforceStock. Stock variables are created the same way as Input and Auxiliary variables. The level of the stock is controlled with a valve and a flow. To create the flow, hold down Alt and right-click on an empty space left of the stock. Then left-click on the stock. A cloud, valve and a flow is created. Rename the valve to NetResourcing.<br />
<br style="clear: both" /><br />
[[File:NetResourcing2.png|right|frame|Cloud, Valve, Flow and Stock. Flow works both on directions.]]<br />
NetResourcing works both ways. To display this also visually, delete the cloud by selecting it and pressing delete on your keyboard. Then create a flow starting from NetResourcing valve and ending on an empty space next to it.<br />
<br style="clear: both" /><br />
<br />
[[File:WorkforceAuxiliaries.png|right|frame|Auxiliaries in Workforce module]]<br />
Now you have used all the basic components and connections. From now on the instructions will be a more simplified.<br />
<br />
Next we will create four Auxiliary variables: TimeToAllocateResources, WorkforceRequired, Productivity and PossibleWorkingSpeed. Place and connect them according to the picture on the right.<br />
<br />
To be able to simulate the model, all variables must have valid equations. To configure an equation, select a variable. Variable's properties are shown in the Property view and you can input the required equations in the text fields. You can copy the equations directly from here or type them manually. Variables connected to the selected variable are shown in the Variables list. To speed up typing, you can double click on a variable name and it will be inserted to the equation.<br />
<br />
WorkforceStock <br /><br />
Initial value: 0<br />
<br />
NetResourcing <br /><br />
= (WorkforceRequired - WorkforceStock)/TimeToAllocateResources<br />
<br />
TimeToAllocateResources <br /><br />
= 2<br />
<br />
Productivity <br /><br />
= 1<br />
<br />
PossibleWorkingSpeed <br /><br />
= WorkforceStock * Productivity<br /><br />
Is Output<br />
<br />
Variables can be set as output by selecting Is Output option from Additional information tab of the variable. <br />
<br />
<br style="clear: both" /><br />
[[File:RequiredWorkingSpeedInput.png|right|frame|RequiredWorkingSpeedInput]]<br />
On a previous phase, we wanted to give the value of RequiredWorkingSpeed1 to this workforce module. To get that value, we need to create an input. Create input RequiredWorkingSpeedInput, connect it to WorkforceRequired and write the following equation to WorkforceRequired.<br />
<br />
WorkForceRequired <br /><br />
= RequiredWorkingSpeedInput/Productivity<br />
<br />
Now this module is ready to be used as a part of the model.<br />
<br />
<br style="clear: both" /><br />
<br />
===Work module===<br />
<br />
[[File:WorkStocks.png|right|frame|Basic work with errors]]<br />
Open Work1 module by selecting it from the WorkModel diagram, right-clicking it and selecting Show Module. Alternatively you can double click Work1 on the model browser.<br />
<br />
Create the basic flow of work with stocks and flows like in the picture on the right. <br />
<br />
The idea of the model is that first there is work. Work is done at a certain speed. When working, errors are also made. When errors are found, the amount of Errors is reduced, errors are removed from WorkDone and moved back to WorkToDo.<br />
<br />
<br style="clear: both" /><br />
<br />
<br />
[[File:ProjectIsReady.png|right|frame|Smoothener for work is done]]<br />
Work needs to be stopped when the project is ready. Since the simulator might face some difficulties to determine the projects readyness when project is almost ready, we need to implement some smoothing to the limit. OpenModelica doesn't yet have a builtin function for smoothing, so we need to implement our own. Create variables and connections according to the picture on the right.<br />
<br />
Use the following equations for variables:<br />
<br />
ProjectIsReady <br /><br />
Initial value: 0<br />
<br />
ProjectReadyness <br /><br />
= (xidz(WorkDone, ProjectWorkAmount, 0.0) - ProjectIsReady) / 0.08<br />
<br />
xidz is short for function X if devided by zero. This means that the simulation calculates ''WorkDone / ProjectWorkAmount''. If ProjectWorkAmount is zero, the result is the third argument ''0.0''.<br />
<br />
[[File:ProjectWorkAmount.png|right|frame|ProjectWorkAmount input variable]]<br />
As you can see, ProjectWorkAmount is highlighted. Your model doesn't contain such variable and it is not connected to ProjectReadyness. Create an Input variable ProjectWorkAmount with default value 1000 and connect it to ProjectReadyness. The reason we are using input variable is that you can determine the default size of a project, but if you want to change it, you can change it from outside the module. <br />
<br />
<br style="clear: both" /><br />
<br />
[[File:ErrorsVariables.png|right|frame|Variables needed for error handling]]<br />
Next we need to define how errors are found. For that we need new variables: WorkQuality and ErrorsFoundTime. Create the variables and connections according to the picture and give variables their equations.<br />
<br />
ErrorsGenerated<br /><br />
= (1-WorkQuality) * WorkingSpeed<br />
<br />
ErrorsFoundRate<br /><br />
= Errors/ErrorsFoundTime<br />
<br />
WorkQuality<br /><br />
= 0.9<br />
<br />
ErrorsFoundTime<br /><br />
Type: WithLookup<br /><br />
With Lookup: xidz(WorkDone, ProjectWorkAmount, 0.0) <br /><br />
Lookup table: {{0,5},{0.5,3},{1,0.5},{2,0.5}}<br />
<br />
WithLookup is a variable type where the value is interpolated from a 2-dimensional table (Lookup table) using the value determined in the "With Lookup" field. Type can be changed from the drop-down menu Type.<br />
<br />
<br style="clear: both" /><br />
<br />
[[File:WorkAllocation.png|right|frame|WorkAllocation and RequiredWorkingSpeed]]<br />
To calculate our own need for workforce we need to create and connect WorkCompletionTime input variable and the following auxliary variables:<br />
<br />
RequiredWorkingSpeed <br /><br />
= if ProjectIsReady < 1 then xidz(WorkToDo, TimeToDeadline, MaximumWorkingSpeed) else 0<br /><br />
Is Output<br />
<br />
MaximumWorkingSpeed <br /><br />
= 500<br />
<br />
TimeToDeadline <br /><br />
= max(0, WorkCompletionTime-time)<br />
<br />
time is a universal variable that gives the current simulation time.<br />
<br />
<br />
We need to decide how the workforce is allocated between all the work modules that are using the same workforce. For that we need to know how much work can be done and how much workforce other works require. <br />
<br />
Create two Inputs, RequiredWorkingSpeedTotalInput and PossibleWorkingSpeedInput, and an auxiliary variable WorkAllocation. Connect the variables like int the picture.<br />
<br />
WorkAllocation<br /><br />
= xidz(RequiredWorkingSpeed, RequiredWorkingSpeedTotalInput, 0.0) * PossibleWorkingSpeedInput<br />
<br style="clear: both" /><br />
<br />
Finally let's give initial values for all the remaining variables:<br />
<br />
WorkingSpeed <br /><br />
= if ProjectIsReady < 1 then WorkAllocation else 0<br />
<br />
WorkToDo <br /><br />
Initial value: ProjectWorkAmount<br />
<br />
WorkDone <br /><br />
Initial value: 0<br />
<br />
Errors <br /><br />
Initial value: 0<br />
<br />
===Connecting modules===<br />
<br />
Our modules are complete. Let's get back to the WorkModel Configuration. <br />
<br />
Set Work1CompletionTime to 10.<br />
<br />
[[File:ModuleConnections1.png|right|frame|Module input connections]]<br />
Connections between modules are made in the properties of the module. Select Work1 and open tab Inputs from the properties. The table lists all input variables in the module that are available. Clicking on the Refers to output column will open a drop-down menu that shows all available variables that are connected to the module. By selecting a variable, you connect that variable to the input.<br />
<br style="clear: both" /><br />
<br />
[[File:RequiredWorkingSpeed1Connection.png|right|thumb|Connection from RequiredWorkingSpeed to Work1]]<br />
[[File:ModuleConnections2.png|right|frame|Module input connections]]<br />
Work1 need also information on how much working speed is required by all works. Since Work1 is the only work, create a dependency connection from RequiredWorkingSpeed1 to Work1 and in Work1's properties connect it to RequiredWorkingSpeedTotalInput. <br />
<br style="clear: both" /><br />
<br />
In Outputs tab, make the only possible connection: from RequiredWorkingSpeed to RequiredWorkingSpeed1.<br />
<br />
Workforce module has only one input and one output. Create the only possible connections:<br /><br />
(Inputs) RequiredWorkingSpeedInput -> RequiredWorkingSpeed1<br /><br />
(Outputs) PossibleWorkingSpeed -> TotalPossibleWorkingSpeed<br />
<br />
Now your model is ready for simulation!<br />
<br />
===Simulating the model===<br />
<br />
To make the simulation time longer, select Configuration on the model browser. Give the model Stop time 24.0<br />
<br />
[[File:ActivateExperiment.png|right|frame|Experiment activation]]<br />
To run simulations, you must activate an experiment. Expand the experiments folder on your model browser. There is one ready-made experiment. Double click on the experiment and the experiment control buttons appear on the toolbar. Press the play button [[File:ExperimentPlay.png]].<br />
<br />
System shows the simulation progress in the progress bar on the lower right corner of the screen. <br />
<br />
[[File:SimulationProgress.png]]<br />
<br />
When the progress indicator disappears, the simulation is complete.<br />
<br />
If the Console view pops up and shows an error "Error: Too few equations, underdetermined system. The model has X equation(s) and Y variable(s)", the simulation has failed. The reason might be that you forgot to assign an equation to some variable or some connection in modules. See through all the variables, write the missing equation and simulate again.<br />
<br />
After the simulation is succesfully run, you can select a variable and see its simulation results in the trend view. For example WorkDone variable in Work1 module will give the following graph.<br />
<br />
[[File:FirstSimulation.png]]<br />
<br />
<br style="clear: both" /><br />
<br />
===Adding modules===<br />
<br />
[[File:ModulesFinal.png|right|frame|Final configuration with two modules]]<br />
We created the WorkModule to be reusable. To use two WorkModules in the model, you must do the following.<br />
<br />
Populate a second WorkModule to WorkModel configuration and name it Work2. <br />
<br />
Create RequiredWorkingSpeed2 input variable and Work2CompletionTime auxiliary variable.<br />
<br />
We need a sum of all working speed requirements to give to the work modules. For this purpose, create an auxiliary variable RequiredWorkingSpeedTotal which sums the requirements.<br />
<br />
You can also have a different size work. To make Work2 smaller, create an auxiliary variable Work2Amount.<br />
<br />
Use the following equations:<br />
<br />
Work2CompletionTime<br /><br />
= 13<br />
<br />
Work2Amount<br /><br />
= 800<br />
<br />
RequiredWorkingSpeedTotal<br /><br />
= RequiredWorkingSpeed1 + RequiredWorkingSpeed2<br />
<br />
Update connections to match connections shown in the picture and connect the inputs and outputs to the modules.<br />
<br />
Workforce<br /><br />
RequiredWorkingSpeedInput -> RequiredWorkingSpeedTotal<br />
<br />
Work1 Inputs<br /><br />
RequiredWorkingSpeedTotalInput -> RequiredWorkingSpeedTotal<br />
<br />
Work2 Outputs<br /><br />
RequiredWorkingSpeed -> RequiredWorkingSpeed2<br />
<br />
Work2 Inputs<br /><br />
[[File:Module2Inputs.png]]<br />
<br />
<br />
When all the connections are made, you can simulate the model again. Now you have model with two work modules.<br />
<br />
[[File:SecondSimulation.png]]<br />
<br />
<br style="clear: both" /><br />
<br />
<!---<br />
===Creating an Operating Interface===<br />
<br />
[[File:NewOperatingUI.png|right|frame|New Operating UI]]<br />
To use the model and adjust its parameters without seeing the actual model, we can use Operating interfaces. Create a new operating interface by right-clicking Operating interfaces on the model browser and selecting New -> Operating UI. Double click the created operating ui to open it.<br />
<br />
Switch to Symbols view. WidgetLibrary shows all the widgets that can be used when creating an operating interface. We will create a simple interface with a trend and two sliders. <br />
<br style="clear: both" /><br />
<br />
[[File:FirstOUI.png|right|frame|Operating UI with a trend and two sliders]]<br />
Drag a trend to the diagram. Adjust the size of the trend so that it is larger. The size of the elements can be adjusted by first selecting the element and then draggign from the lower right corner of the element.<br />
<br />
Then drag two sliders to the right side of the trend.<br />
<br />
Now you should have an operating user interface that looks something like the picture on the right.<br />
<br />
To be able to use the interface, we need to configure the elements and connect them to the actual variables on the model. First let's configure the sliders.<br />
<br />
We are going to adjust the time when Work1 and Work2 are ready. Our simulation time ranges from 0 to 24, so that is the range that we are going to use in our sliders. Select one of the sliders. The Property view shows all the different properties that can be configured in the element. Do the following settings for both sliders:<br />
<br />
[[File:SliderProperties.png|none|frame|Slider properties]]<br />
<br />
Then select the trend element. Set its Title to "Work1 and Work2" and Y-Axis Label to "Work Done"<br />
<br />
Now we need to connect the actual variables to the elements. From Model Browser, drag Work1CompletionTime to the first slider and Work2CompletionTime to the second slider.<br />
<br />
Then from each of the Work module, drag WorkDone to the trend element.<br />
<br />
Activate an experiment by double clicking it, activate the Operating UI by clicking it and switch it to operating mode with the switch button [[File:OperatingModeSwitch.png]] on the main toolbar.<br />
<br />
Run a simulation. The trend element should show the results of the simulation. Adjust the completion times from the sliders and simulate again.<br />
<br />
[[File:OperatingUI.png|none|frame|Ready Operating interface]]<br />
<br />
<br style="clear: both" /><br />
<br />
--><br />
<br />
<br />
[[Category:Tutorials]]</div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=Simantics_System_Dynamics&diff=573Simantics System Dynamics2012-07-27T12:10:26Z<p>Teemu Lempinen: /* Arithmetic Operators */</p>
<hr />
<div>== Simantics System Dynamics ==<br />
<br />
Simantics System Dynamics is currently the only open source modelling and simulating tool for Simantics. Simantics System Dynamics is under development and will go through some changes in the future. New features will be added and old ones improved according to the needs of the modellers. New features include module libraries and different analysis tools.<br />
<br />
This documentation introduces you to the current version of Simantics System Dynamics. Documentation includes the basic modelling principles and a guide on how to model system dynamics models with Simantics System Dynamics. If you like to get to know the tool better and try modelling and simulating yourself, [[#Installation Instructions|install]] the software and try our [[Tutorial: Basic System Dynamics Modelling|basic]] and [[Tutorial: Advanced System Dynamics Modelling|advanced]] tutorials!<br />
<br />
== Introduction to System Dynamics Simulation ==<br />
<br />
===System Dynamics===<br />
System dynamics is an approach to understanding different organizations, markets and other complex systems and their dynamic behavior. System dynamics modelling in Simantics is a free modelling tool. See [[#Installation Instructions|installation instructions]].<br />
<br />
===Model===<br />
[[File:ModelStructure.png|right|thumb|Model structure]]<br />
System dynamics model is generally understood as the model configuration. In this tool, the model contains also other components. Model can have Operating interfaces that enable the use of the model with simple controls. Operating interfaces are configured separately and when using them, the complex model is hidden from the user. Experiments are the way to simulate the model. In the future, you can have experiments with different configurations, for example different initial values for some parameters. In that way, you don't have to always configure the model for different scenarios. Modules folder contains all the different module types in your model and you can create new module types there. <br />
<br />
<br style="clear: both" /><br />
<br />
===Components===<br />
Most of the components you can use in your models are basic system dynamics components. The modularity of the models introduces two additional components, Modules and Inputs. All the components are explained below.<br />
[[File:ComponentTypes.png|right|frame|Component types]]<br />
;Auxiliary<br />
:Auxiliary is the most basic variable you can use. It represents a single value or a mathematical expression. There are different types of auxiliary variables currently in the system: Auxiliary, Parameter, Constant and WithLookup. Auxiliary is the default type. Parameters are single values that the user can change. When only parameters are changed, the model simulates faster, because the system does not have to recompile the model. WithLookup is a special variable that has an expression and a lookup table. The expresssion defines what value is taken from the defined table.<br />
;Dependency<br />
:Dependency is an arrow that connects two components. It means that the value of the variable from which the arrow starts is used to calculate the value of the variable where the arrow ends.<br />
;Flow<br />
:Flow connects clouds, valves and stocks. Flow represents an actual flow of something from stocks or clouds to stocks or clouds. There has to be at least one valve in a flow and the system creates it automatically, if none of the ends of the flow is a valve.<br />
;Valve<br />
:Valve regulates the rate of a flow. The value of a valve is automatically used in calculating the level of an adjacent stock. Valves behave just like Auxiliary variables but look different and you can connect also flows to them.<br />
;Stock<br />
:The value of a stock variable is an integral of flows leaving and flows arriving to the variable. The integral is calculated automatically from the valves that are connected to the variable with flow connections. You must give an initial value to the stock. Initial value can be a single value or an equation. You can use values of other variables to calculate the initial value.<br />
;Cloud<br />
:Cloud is not a variable. It represents a starting or ending point of a flow, if it is not in the scope of the model.<br />
;Module<br />
:Modules enable structural modeling. Modules are defined just like the basic model configuration, but the module component hides the actual configuration. You can only connect dependency connections into the module and dependency connections from the module must end to Input variables. The interface of the module is defined using input and output variables in the configuration of the module. All variable types can be set as output variables. If a variable is an output variable, its font is bold.<br />
;Input<br />
:Input variables are the way of getting values from other modules. Inputs look like auxiliary variables except their font is italics. You can set a default value to the input variable in case it is not connected to any variable. Connections are made from the modules properties, when the module is populated. Input doesn't have to be connected with an arrow to a module. If the variable has no connections, it can get values from a higher level in the hierarchy. If an input is connected to an output, the output and its module are shown below the variable using dot notation.<br />
<br style="clear: both" /><br />
<br />
===Modeling principles===<br />
<br />
System dynamics modelling is much more than just mathematical formulas and nice graphs. Models are ways of communicating. There are some basic principles in system dynamics modelling that make the models easier to read and understand. You do not have to apply these principles to simulate models, but using them makes it easier for you to communicate your model to others.<br />
<br />
;Variable names<br />
:Variables names should be nouns, not verbs. The names should be positive: for example it is easier to understand that satisfaction decreases than dissatisfaction rises. <br />
<br />
:Variable names can and should have multiple words, if they are needed. Unfortunately current version of the tool does not support spaces in variable names. A good practice is to use CamelCase if name contains multiple words. This means that you start every word woth a capital letter (example: ExampleVariable).<br />
<br />
;Connections<br />
:You should try to avoid overlapping dependency arrows. In some situations, however, it is not possible. Dependencies should also form distinctive loops, if there is a loop. It makes it easier to read and understand the model and its behavior.<br />
<br />
;Graphical annotations<br />
:System dynamics contains usually annotations for loops, polarities, delays and so on. Currently those annotations are not supported, but the support will be added later. Annotations are important, again, for communicating the behavior of the model.<br />
<br />
==Installation Instructions==<br />
<br />
System dynamics tool is a provided with the Simantics platform.<br />
<br />
# [https://www.simantics.org/simantics/download Download installer from Simantics download page]<br />
# Install the program to a directory without spaces (limitation inherited from OpenModelica).<br />
# Run the application through the launcher generated by the installer<br/><br />
: (default: Simantics\Simantics-1.6.0-Sysdyn-32\Simantics-1.6.0-Sysdyn-32)<br />
<br />
[http://www.openmodelica.org/ OpenModelica] is used to build and simulate the models. Simantics platform has integrated OpenModelica 1.8.1 for Windows environments. For other versions and other environments you need to install [http://www.openmodelica.org/index.php/download OpenModelica].<br />
<br />
== Workbench ==<br />
<br />
[[File:BasicWorkbench.png|center|729px]]<br />
<br />
<br />
# '''Diagram''' <br /> Diagram is the area where you will graphically modify your model. Diagrams are built from elements that can be dragged from Symbols view or populated using shortcut keys. <br />
# '''Model Browser''' <br /> Model browser shows the structure of your model and all items related to it. <br /> Symbols view is stacked with the model browser and used for dragging elements to diagrams.<br />
# '''Properties''' <br /> Property view shows the selected variable's properties. Property view has a different layout depending on the type of the selected component. The view can also have different tabs depending on the component type. Basic tabs are with variables are Equation and Additional information.<br />
# '''Trend''' <br /> Trend view shows the graphical representation of the values of the selected value over time. For the trend to be shown, a simulation has to be run. The view shows always the results of the latest run, but you can save results of a simulation and show them in the same trend with results from another simulation. Values view and Dependencies are stacked with Trend view and can also be used for analyzing the model.<br />
# '''Experiment controls''' <br /> Experiment controls are shown when an experiment is active. Experiment is activated by double clicking an experiment in the model browser. With the experiment control, you can start simulation runs and save simulation results.<br />
<br />
<br /><br />
If you accidentally close a view, you can reopen them from Window->Show View->Other...<br />
<br />
== Modelling ==<br />
<br />
===Basic modelling===<br />
<br />
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.<br />
<br />
[[File:Basic_1.png|right]]<br />
;Creating a new model<br />
:Start a new model by right-clicking the model browser and selecting New->Model or from the main menu File->New Model.<br />
<br style="clear: both" /><br />
<br />
[[File:Basic_2.png|right]]<br />
;Creating a new module type<br />
:Create a new module type by right-clicking on the Modules-folder and selecting New->Module. This creates a new module type that you can populate to your other modules and the model configuration. <br />
<br style="clear: both" /><br />
<br />
;Configuring a model<br />
:Model configuration can be opened by double clicking Configuration in the model browser. <br />
<br />
;Configuring modules<br />
: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 module!<br />
<br />
;Populate variables<br />
:You can drag variables to a diagram from symbol view. You can also populate variables using [[#Shortcut and control keys|shortcut keys]]<br />
<br />
;Populate modules<br />
:Modules are populated from the model browser. Just drag the module you want to populate from the Modules folder to a diagram.<br />
<br />
;Create connections<br />
: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.<br />
: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.<br />
: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.<br />
<br />
;Connections between modules<br />
:'''Outside the module''' <br /><br />
:You can connect variables to variables in modules like this:<br />
MODULE -----> INPUT<br />
or<br />
ANY VARIABLE -----> MODULE <br />
:This is just the visual configuration, but you need those connections to really connect variables in the module's properties.<br />
:In Inputs -tab you select which variables you connect to inputs inside the module. In Outputs -tab you select which variables you lift from the module to inputs outside it.<br />
<br />
:'''Inside the module''' <br /><br />
:Input variables get values from outside the module<br />
<br />
:Output variables can send their values outside the module. From the variable properties, select Additional Information and press Is Output<br />
<br />
;Configure variables<br />
:Select a single variable from diagram or model browser. The properties of the variables are shown in the equation view and you can modify them.<br />
<br />
;Export model<br />
: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 to for example create different versions of the model, create backups or to transport it to another database.<br />
<br />
;Import model<br />
:Right-click on the model browser and select Import->Model. Browse to your .tg file and select open. The model is added to your model browser.<br />
<br />
===Shortcut and control keys===<br />
<br />
Shortcut keys for configuring a model on diagram.<br />
<br />
{|<br />
|Esc <br />
|Cancel operations (e.g. connection and rename).<br />
|-<br />
|Shift + A <br />
|Hover Auxiliary at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + S<br />
|Hover Stock at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + C<br />
|Hover Cloud at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + V<br />
|Hover Valve at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + I<br />
|Hover Input at the cursor position, populate with left mouse button.<br />
|-<br />
|Alt + left mouse button<br />
|Start an arrow from a variable. End to another variable by clicking left mouse button.<br />
|-<br />
|Alt + right mouse button<br />
|Start flow from a variable. End by clicking left mouse button.<br />
<br />
If a flow is not started or ended on to a variable, a cloud will be created to that end. <br /><br />
If a new flow does not have a valve at either end, a valve will be created in the middle of the flow.<br />
|-<br />
|Delete<br />
|Remove selected variables<br />
|-<br />
|Ctrl + left mouse button<br />
|Select multiple variables<br />
|-<br />
|Mouse wheel or<br/>+ and -<br />
|Diagram zoom<br />
|-<br />
|drag(mouse3) or<br/>drag(shift + any mouse button)<br />
|Diagram pan<br />
|-<br />
|Ctrl + C<br />
|Copy selected elements<br />
|-<br />
|Ctrl + X<br />
|Cut selected elements<br />
|-<br />
|Ctrl + V<br />
|Paste copied or cut elements<br />
|-<br />
|G<br />
|Show / hide grid<br />
|-<br />
|R<br />
|Show / hide ruler<br />
|}<br />
<br />
Other shortcut keys can be found selecting Window -> Preferences from the main menu. Keys are located in General -> Keys.<br />
<br />
== Simulation ==<br />
There are three different ways for simulating a model. Different simulations are represented as different types of experiments in Simantics System Dynamics. <br />
<br />
Experiments are created from the context menu of experiments folder in a model. <br />
<br />
[[File:NewExperiment.png]]<br />
<br />
Double-click on an experiment activates it and displays experiment type specific controls in the main tool bar.<br />
<br />
;Normal simulation<br />
: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.<br />
<br />
;Game simulation<br />
:Game simulations allow simulating an arbitrary number of steps, changing parameter values and continuing simulation with the new values from where it previously ended.<br />
<br />
;Simulation playback<br />
:Simulation playback works essentially as the basic experiment, but it offers some additional visualization options.<br />
<br />
== Simulation result and model structure analysis ==<br />
Simulation results can be viewed as trends in trend view or as plain numbers in values view. The views display results of variables that are selected in the workbench. Users can also create [[#Custom charts |custom charts]].<br />
<br />
Model structure can be examined in the Structure view. There are two options: Dependency structures of individual variables or the complete hierarchy structure of the model.<br />
<br />
;Trend<br />
:Shows you the values of the selected variable(s) graphically over the simulation time. You can modify the trend and zoom it using the context menu (right-click) of the trend. <br /> [[File:Trend.png]]<br />
<br />
;Values<br />
:Shows you the values of the selected variable(s) in a table form. If the value has a star (*) at the end, it means that the value is an approximate. There is no value for that variable for the given time step. Selected values can be copied to other software in csv format.<br /> [[File:Values.png]]<br />
<br />
;Compare results<br />
:You can compare different results of the same model by saving simulation results and displaying the saved results side by side with other results. You can save your results after simulating by clicking the save button [[File:Saveresults.png]] on your experiment controls. The saved results appear to model browser under the active experiment. To show the results on trends and tables, right-click on the result and select Show on charts. <br /> [[File:CompareTrend.png]]<br />
<br />
;Dependencies<br />
:Dependencies display which variables affect and which are affected by the selected variable. The direction and number of steps that are traveled from the selected variable can be configured at the bottom of the view. <br /> [[File:Dependencies.png]]<br />
<br />
;Model Hierarchy<br />
:Model Hierarchy displays the hierarchical structure of the model. The module type where a selected variable is located is highlighted.<br /> [[File:ModelHierarchy.png]]<br />
<br />
== Custom charts ==<br />
Custom charts are user-defined displays of simulation result data. They can be used and re-used in various places. The three types of custom charts (line, bar and pie charts) provide model developers means for examining and developing their models and communicating the simulation results to others. <br />
<br />
Custom charts are created to the Charts folder in model browser.<br />
<br />
[[File:NewChart.png | Creating a new chart]]<br />
<br />
Charts are configured the same way as variables: first select the chart from model browser and then configure it in the property view. Charts can be viewed in the same active trend view as any variable by selecting the chart from model browser. In addition to trend view, charts can be populated directly to the model diagram or to a separate chart panel that can contain multiple charts. <br />
<br />
=== Line chart ===<br />
<br />
Line char 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.<br />
<br />
[[File:LineChart.png|Line chart with an array variable]]<br />
<br />
[[File:LineChartGeneral.png|General settings of line chart]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|The title of the chart. Displayed in the chart<br />
|-<br />
|Type<br />
|Line chart (default) or area chart<br />
|-<br />
|Hide<br />
|Options to hide chart grid, title or legend<br />
|-<br />
|'''X-axis'''<br />
|<br />
|-<br />
|Variable<br />
|A variable that is used as the x-axis variable. The default variable is time and it needs not to be typed in the field.<br />
|-<br />
|Label<br />
|Optional other label for the variable than its name<br />
|-<br />
|Min<br />
|Minimum value of the x-axis<br />
|-<br />
|Max<br />
|Maximum value of the x-axis<br />
|-<br />
|Hide<br />
|Options to hide x-axis lable, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
[[File:LineChartAxisAndVariables.png|Axis and variables settings of line chart]]<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed.<br />
|-<br />
|Color<br />
|Color for the lines of this variable<br />
|-<br />
|Line width<br />
|The width of the lines drawn for this variable<br />
|}<br />
There are also configuration options for y-axis. They are displayed when an axis is selected in the Axis and variables tab.<br />
{|<br />
|'''Y-axis'''<br />
|<br />
|-<br />
|Label<br />
|Label of the axis<br />
|-<br />
|Min<br />
|Minimum value in the axis<br />
|-<br />
|Max<br />
|Maximum value in the axis<br />
|-<br />
|Color<br />
|The color of the axis lines, ticks and labels<br />
|-<br />
|Hide<br />
|Options to hide parts of the axis: label, axis line, tick marks, tick labels<br />
|-<br />
|}<br />
<br />
=== Bar chart ===<br />
Bar charts display variables in a certain point in time. The point can be defined for the complete chart in cart'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. <br />
<br />
[[File:BarChartGeneral.png|General bar chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Name is displayed in model browser.<br />
|-<br />
|Title<br />
|The title of the chart. Title is displayed in the chart, if not hidden<br />
|-<br />
|Type<br />
|Normal or stacked. Normal type displays all variables in separate bars. Stacked mode is able to display one-dimensional array variables in stacks.<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Option for hiding grid, title and Legend. Legend is hidden by default since it only contains the information that the current simulation is displayed.<br />
|-<br />
|}<br />
<br />
[[File:BarChartInDiagram.png|Bar chart in a model diagram]]<br />
<br />
Charts can be added to model diagrams simply by dragging the chart from model browser to diagram.<br />
<br />
[[File:BarChartVariable.png|Settings for a variable in bar chart]]<br />
<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|}<br />
[[File:BarChartAxis.png|Settings for axis in bar chart]]<br />
{|<br />
|'''Domain axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for x axis<br />
|-<br />
|Label angle<br />
|Axis labels can be displayed in an angle. This value determines the angle in degrees.<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|'''Range axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for y axis<br />
|-<br />
|Min<br />
|Minimum value of y axis<br />
|-<br />
|Max<br />
|Maximum value of y axis<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
=== Pie chart ===<br />
<br />
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.<br />
<br />
[[File:PieChartGeneral.png|General pie chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|Title The title of the chart. Displayed in the chart<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Options for hiding title, section labels and legend<br />
|-<br />
|}<br />
<br />
[[File:PieChartVariable.png|Variable settings in pie chart]]<br />
{|<br />
|'''Variables'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Color<br />
|Color for the sector of this variable<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|Exploded<br />
|If set, the sector(s) of the variable(s) are "exploded" away from the center of the pie chart<br />
|-<br />
|}<br />
<br />
[[File:PieChartChartPanel.png|Pie chart in chart panel]]<br />
<br />
=== Chart panel ===<br />
[[File:ChartPanel.png|right]]<br />
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.<br />
<br />
Chart panel can be either horizontally or vertically oriented. Different orientations help in configuring the workbench perspective. <br />
<br />
[[File:ChartPanelOrientation.png|Chart panel orientation]]<br />
<br />
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.<br />
<br />
By default, chart panel is hidden in the upper-left corner of the system dynamics perspective.<br />
<br style="clear: both" /><br />
<br />
== Multidimensional variables ==<br />
<br />
<br />
=== Modeling ===<br />
<br />
Models with multidimensional variables look just like any other models. The structure of the models is replicated givin multiple indexes to variables. For users with programming background, notation Variable[] may be familiar. In system dynamic modeling we need to give names to the indexes. Instead of using numbers to define the indexes, like in normal programming, we use enumerations. The steps to create a model with multidimensional variables are as follows (with examples):<br />
<br />
# '''Create the model structure''' <BR />Model with multidimensional variables looks just like any other model.<BR /> [[File:ModelWithMultidimensionalVariables.png|300px|Model with multidimensional variables]]<br />
# '''Create Enumerations and define the indexes''' <BR />Enumerations are created by right-clicking configuration and selecting New->Enumeration.<BR /> [[File:NewEnumeration.png|250px|New enumeration]]<BR />Define enumeration indexes by adding as many indexes as you want. Rename the indexes by selecting them and then clicking on them again.<BR />[[File:DefineIndexes.png|200px|Index definitions]]<br />
# '''Add Enumerations for variables''' <BR />Select the variable that you want to be multidimensional. From the Indexes -tab in the property view, move the wanted enumerations to the right. The order of the enumerations does matter.[[File:SelectEnumerations.png|500px|Select enumerations for variables]]<br />
# '''Define equations for all possible indexes''' <BR />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 indexes, so the resulting definition can be {{1,2,3},{4,5,6},{7,8,9}}.<BR />[[File:DefineEquations.png|500px|Define equations for all indexes]]<br />
<br />
<br />
<br />
=== Expressions ===<br />
<br />
Values for all cells in the variable matrix can be defined in a single expression. <br />
<br />
[[File: DefineEquations.png|600px]]<br />
<br />
[[File:DefineEquations2.png|600px]]<br />
<br />
In many situations, it is however more clear to define separate expressions for each cell or blocks. <br />
<br />
# '''Define range for the expression'''<BR /> [[File:DefineRange.png]]<br />
# '''Define the expression''' (dimensions of the defined range and the result of the expression must match!) <BR /> [[File:DefineEquations3.png]]<br />
# '''Create a new expression''' <BR /> [[File:CreateNewExpression.png]]<br />
#''' Select the new expression''' <BR /> [[File:SelectNewExpression.png]]<br />
<br />
Repeat until there is value for each cell. There must be exactly one value for each cell.<br />
<br />
=== Array slices ===<br />
<br />
Many times it is useful to access a slice of a multidimensional variable. In this chapter, we will use the following example variable:<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
The whole variable can be accessed in three different ways:<br />
# Auxiliary<br />
# Auxiliary[E1, E2]<br />
# Auxiliary[:, :]<br />
<br />
The following explains different methods for accessing parts of the variable<br />
<br />
// Single cell<br />
Auxiliary[one, eins] = 1<br />
<br />
// Slices<br />
Auxiliary[one, E2] = {1,2,3}<br />
Auxiliary[E1, zwei] = {{2},{5},{8}}<br />
<br />
// In addition to single cells and the whole enumeration range, a subrange of the enumeration can be used<br />
Auxiliary[two : three, E2] = {{4,5,6},{7,8,9}}<br />
Auxiliary[one : two, zwei : drei] = {{2,3},{5,6}}<br />
<br />
The syntax for accessing parts of variables can be used in both expression range definitions and in expressions.<br />
<br />
=== Arithmetic Operators ===<br />
<br />
Arithmetic operations are defined in Modelica. Below are examples of different operations.<br />
<br />
;Addition and substraction<br />
Addition and substraction are calculated elementwise<br />
<br />
{1,2,3} - {0,2,3} = {1,0,0}<br />
{{2,2},{4,4}} + {{8,8},{1,1}} = {{10,10},{5,5}}<br />
{1,2,3} - {1,2} = ERROR! Different array sizes<br />
<br />
;Division<br />
Division with a scalar<br />
{5,10,15} / 5 = {1,2,3}<br />
5 / {5,10,15} = ERROR! not allowed<br />
<br />
Division with an array<br />
{1,2,3} / {1,2,3} = ERROR! not allowed<br />
<br />
// Elementwise<br />
{1,2,3} ./ {1,2,3} = {1,1,1}<br />
<br />
;Multiplication<br />
<br />
Multiplication with a scalar<br />
{1,2,3} * 2 = {2,4,6}<br />
5 * {1,2,3} = {5,10,15}<br />
<br />
Matrix multiplication with an array<br />
{{3,4},{5,6}} * {1,2} = {11,17}<br />
{{3,4},{5,6}} * {1,2,3} = ERROR! incompatible array sizes<br />
<br />
//Elementwise<br />
{1,2} .* {1,2} = {1,4}<br />
<br />
Real[3,2] c = {{1,2},{3,4},{5,6}}; <br />
Real[2,2] d = {{3,4},{5,6}};<br />
Real[2,2] cd;<br />
cd = c[2:3, :] .* d; // Result: {{9,16},{25,36}}<br />
<br />
;Power<br />
Elementwise power of array variable<br />
{1,2} .^ 2 = {1,4}<br />
<br />
=== Builtin Modelica functions ===<br />
<br />
Modelica has some builtin functions that help using multidimensional variables. This chapter introduces some of the builtin functions. <br />
<br />
;Dimension and size functions<br />
<br />
We will use the same example variable as previously.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
;ndims(A)<br />
The number of dimensions in array A<br />
ndims(Auxiliary) = 2<br />
<br />
;size(A, i)<br />
The size of dimension i in array A<br />
size(Auxiliary, 2) = 3<br />
<br />
;size(A)<br />
A vector of length ndims(A) containing the dimension sizes of A<br />
size(Auxiliary) = {3,3}<br />
<br />
<br />
;Construction functions<br />
In addition to normal array constructing, a special construction functions can be used.<br />
<br />
;zeros(n1,n2,n3,...)<br />
An array full of zeros with dimensions n1 x n2 x n2 x ... <br />
zeros(2, 2) = {{0,0}, {0,0}}<br />
<br />
;ones(n1,n2,n3,...)<br />
An array full of ones with dimensions n1 x n2 x n2 x ... <br />
ones(2, 2) = {{1,1}, {1,1}}<br />
<br />
;fill(s,n1,n2,n3)<br />
Like zeros() and ones(), but with user defined value (s) for array elements.<br />
fill(3,2,2) = {{3,3}, {3,3}}<br />
<br />
;identity(n)<br />
Creates an n x n integer identity matrix with ones on the diagonal and all other elements zero.<br />
identity(3) =<br />
1 0 0<br />
0 1 0<br />
0 0 1<br />
<br />
;diagonal(v)<br />
Constructs a square matrix with elements of vector v on the diagonal and all other elements zero.<br />
diagonal({1,2,3}) =<br />
1 0 0<br />
0 2 0<br />
0 0 3<br />
<br />
;linspace(x1,x2,n)<br />
Constracts a Real vector from x1 to x2 with n equally spaced elements.<br />
linspace(2,5,4) = {2,3,4,5}<br />
<br />
;Reduction functions<br />
<br />
Reduction functions reduce arrays to scalars.<br />
<br />
;min(A)<br />
Returns the minimum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
min(A) = 1<br />
<br />
;max(A)<br />
Returns the maximum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
max(A) = 4<br />
<br />
;sum(A)<br />
Returns the sum of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
sum(A) = 10 // 1 + 2 + 3 + 4<br />
<br />
;product(A)<br />
Returns the product of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
product(A) = 24 // 1 * 2 * 3 * 4<br />
<br />
<br />
;Using functions with iterators<br />
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.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
AuxiliarySum[E1] = {sum( Auxiliary[ i , E2 ] ) for i in E1} // Result: {6, 15, 24}<br />
<br />
/* Same as:<br />
{sum(Auxiliary[one, E2]), sum(Auxiliary[two, E2]), sum(Auxiliary[three, E2])}<br />
{sum({1,2,3}), sum({4,5,6}), sum({7,8,9})}<br />
*/<br />
<br />
One expression can have multiple iterators. The Modelica specification defines the following format, but it is NOT yet supported in OpenModelica:<br />
{sum(Array[ i, j, E3]) for i in E1, j in E2} // Dimensions reduced from 3 to 2<br />
<br />
To use multiple iterators, use the following format (NOTE the reversed order of iterators!):<br />
{{sum(Array[ i, j, E3]) for j in E2} for i in E1} // Dimensions reduced from 3 to 2<br />
<br />
The range doesn't have to be the whole enumeration. Subranges can also be used.<br />
{sum( Auxiliary[ i , eins : zwei ] ) for i in E1.one : E1.two} // Result: {3, 9}<br />
<br />
/* Same as<br />
{sum(Auxiliary[one, eins : zwei]), sum(Auxiliary[two, eins : zwei])}<br />
{sum({1,2}), sum({4,5})}<br />
*/<br />
<br />
=== Simulation results ===<br />
<br />
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. <br />
<br />
[[File:3x3trend.png|300px|Trend view for a 3x3 variable]]<br />
<br />
The clutter can be reduced by selecting which enumeration indexes are shown in charts. Select an enumeration and tick the indexes 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.<br />
<br />
[[File:ShowInCharts.png|500px|Select indexes to show in charts]]<br />
<br />
<br />
=== Array Variables in Modules ===<br />
<br />
[[File:Replaceable.png|frame|Replaceable enumeration inside a module]]<br />
<br />
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 [[Simantics_System_Dynamics#Modeling|Modeling]]). <br />
<br />
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.<br />
<br />
<br />
<br style="clear: both" /><br />
<br />
In this example, the original enumeration that the modeler used had two indexes. We are using an instance of this module, but we need to use array variables that have three indexes instead of two. We are using two variables and an instance of the module.<br />
<br />
[[File:ReplacingEnumerationConfiguration.png|frame|left|500px|Module configuration for replacing enumerations inside the module]]<br />
<br style="clear: both" /><br />
<br />
In the parent configuration, we have used an enumeration with three indexes in the two variables.<br />
<br />
[[File:Replacing.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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 clickin 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.<br />
<br />
<br />
[[File:ReplacingEnumeration.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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!<br />
<br />
== Functions ==<br />
<br />
Modelica provides a convenient way to use functions in your models. You can create your own functions, import complete function libraries and share function libraries to be used in all of your models. <br />
<br />
=== Creating functions ===<br />
<br />
[[File:NewFunction.png|right]]<br />
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.<br />
<br />
Functions that can be found from Functions -folder can be used in your variable definitions.<br />
<br />
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. <br />
<br />
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.<br />
<br />
Below is an example of a simple function. For more examples, see the built-in functions provided with the tool and [https://www.modelica.org/documents/ Modelica specifications].<br />
<br />
<br style="clear: both" /><br />
<br />
[[File:ExampleFunction.png]]<br />
<br />
=== Function libraries ===<br />
<br />
<br />
[[File:NewFunctionLibrary.png|right]]<br />
<br />
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)).<br />
<br />
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. <br />
<br />
Create a new function library by right-clicking on Functions folder, Shared functions folder or other module library.<br />
<br />
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.<br />
<br />
[[File:SharedFunctions.png]]<br />
<br style="clear: both" /><br />
<br />
=== External functions ===<br />
<br />
Modelica allows you to use external functions that are programmed using C language. Below is a simple example of using a function that returns the sum of two arguments. <br />
<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}<br />
<br />
<br />
[[File:ImportCFunctionLibrary.png|right]]<br />
<br />
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 <br />
(e.g. simantics_home/plugins/org.simantics.openmodelica.win32_x/MinGW/bin/mingw32_gcc.exe -g -O -c ExampleCFunctionCode.c). <br />
<br style="clear: both" /><br />
<br />
[[File:ExampleExternalFunction.png]]<br />
<br />
<br />
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.<br />
<br />
[[File:ExternalFunctionResult.png]]<br />
<br />
<br />
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.<br />
<br />
<br />
Small external C function can also be written directly to the function code in Simantics Sysdyn:<br />
function ExampleExternalFunction<br />
input Real x;<br />
input Real y;<br />
output Real z;<br />
external "C" z=exampleCFunction(x,y) annotation(Include="<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}");<br />
end ExampleExternalFunction;<br />
<br />
=== Modelica functions ===<br />
<br />
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 [[Simantics_System_Dynamics#Builtin_functions|builtin functions for arrays]].<br />
<br />
{|<br />
|abs(x)<br />
|Returns the absolute value of x. Expanded into "(if x >= 0 then x else -x)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|acos(x)<br />
|Inverse cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|asin(x)<br />
|Inverse sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan(x)<br />
|Inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan2(x1,x2)<br />
|four quadrant inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cat(n,A,B,...)<br />
|General concatenation function that concatenates arrays A,B,... along the nth dimension.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|ceil(x)<br />
|Returns the smallest integer not less than x, the closest integer above x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cos(x)<br />
|Cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cosh(x)<br />
|Hyperbolic cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cross(x,y)<br />
|Returns the 3-vector cross product of the 3-vectors x and y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|delay(expr, delayTime)<br />
|Returns the value of expr at the time time-delayTime. The value of expr is returned when time <= time.start + delayTime.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|der(x)<br />
|Time derivative of x. X must be have continuous-time variability.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|div(x, y)<br />
|Returns the algebraic quotient x/y with any fractional part discarted. E.g. div(10,3) = 3.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|edge(b)<br />
|Returns true when the value of the boolean expression b changes. Expanded into (b and not pre(b)).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|exp(x)<br />
|Exponential, base e.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|floor(x)<br />
|Returns the largest integer not greater than x, the closest integer below x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|initial()<br />
|Returns true at the beginning of the simulation. <br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|integer(x)<br />
|Returns the largest integer not greater than x as an integer.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log(x)<br />
|Natural logarithm. (base e, x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log10(x)<br />
|Base 10 logarithm. (x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|mod(x, y)<br />
|Returns the integer modulus of x/y: mod(x,y) = x - floor(x/y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|noEvent(expr)<br />
|noEvent around an expression causes the expression to NOT generate event.<br />
'''Important:''' <br />
:If you want a condition to be checked only on time steps, use noEvent.<br />
:(e.g. if noEvent(value >= 1) then ... else ...)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|pre(x)<br />
|Returns the preceding value of y from time event that has occured before current time.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|rem(x, y)<br />
|Returns the integer remainder of x/y: rem(x,y) = x - div(x,y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sample(start, interval)<br />
|Returns true and triggers time events at times start + i * interval (i=0,1,...).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sign(x)<br />
|Returns -1 if x is negative, 1 if x is positive. Expanded into "(if x > 0 then 1 else if x < 0 then -1 else 0)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sin(x)<br />
|Sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sinh(x)<br />
|Hyperbolic sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sqrt(x)<br />
|Square root of x. The value of x must be greater or equal to 0 or an assertion error occurs.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tan(x)<br />
|Tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tanh(x)<br />
|Hyperbolic tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|terminal()<br />
|Returns true at the end of a successful simulation.<br />
|}<br />
<br />
== Spreadsheets ==<br />
<br />
Spreadsheets allow storing and maintaining values in a familiar format. The current spreadsheet implementation is experimental and does not provide much functionality. Some basic tasks can, however, be performed. You cannot type directly to a cell, you need to first copy some value or text into it. Then it can be modified.<br />
<br />
=== Variable values ===<br />
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.<br />
<br />
[[File:AuxiliarySheetReference.png|Sheet reference in an expression]][[File:AuxiliarySheet.png|Value of a variable in sheet]]<br />
<br />
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 indexes are not mandatory, but help reading and maintaining the sheet.<br />
<br />
[[File:SheetForMultidim.png|Spreadsheet for multidimensional variables]]<br />
<br />
Reference to a sheet range creates an array variable.<br />
<br />
[[File:SheetMultidim1.png|Array variable ArrayTest1[2] with sheet reference]]<br />
<br />
ArrayTest2 has two dimensions. Reference to a larger range creates a two-dimensional variable. By default, the indexes are ordered as in this example. However, if you wish to present the indexes in a different order in the spreadsheet, you can transpose the sheet reference (e.g. transpose(ArrayTestSheet(E2:G3)))<br />
<br />
[[File:SheetMultidim2.png|Array variable ArrayTest2[2,3] with sheet reference]]<br />
<br />
=== History data ===<br />
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.<br />
<br />
[[File:Sheet.png|Spreadsheet with history data]]<br />
<br />
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. <br />
<br />
[[File:HistoryDataSettings.png|History data settings]]<br />
<br />
{|<br />
|'''History data properties'''<br />
|<br />
|-<br />
|Name<br />
|Name of the history dataset<br />
|-<br />
|Sheet<br />
|Combo box for selecting a sheet where the history data is located<br />
|-<br />
|Orientation<br />
|Columns or rows. How the data is arranged in the sheet.<br />
|-<br />
|Range start<br />
|The upper-left corner cell of the history data range<br />
|-<br />
|Range end<br />
|The lower-right corner cell of the history data range<br />
|-<br />
|Time variable<br />
|The name of the time variable in the history data, if it is different than "time"<br />
|-<br />
|Variables in range<br />
|This text field displays the found variables in the given sheet and range<br />
|-<br />
|}<br />
<br />
If the history dataset is activated, history data is displayed whenever it is available for a variable that is displayed in a chart.<br />
<br />
[[File:HistoryData.png|History data in two charts]]<br />
<br />
<br />
<center><br />
[[Simantics]] | ''System Dynamics Modelling''<br />
</center><br />
<br />
----<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Basic System Dynamics Modelling]]'''<br><br />
System dynamics modelling in Simantics is a free modelling tool that is included into the basic installation. This tutorial introduces the basic features of the system dynamics modelling tool.<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Advanced System Dynamics Modelling]]'''<br><br />
This tutorial introduces the more advanced features of the system dynamics modelling tool: Modules and Operating interfaces<br />
<br />
[[Category: Simantics System Dynamics]]</div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=Simantics_System_Dynamics&diff=570Simantics System Dynamics2012-06-04T12:40:07Z<p>Teemu Lempinen: /* Spreadsheets */</p>
<hr />
<div>== Simantics System Dynamics ==<br />
<br />
Simantics System Dynamics is currently the only open source modelling and simulating tool for Simantics. Simantics System Dynamics is under development and will go through some changes in the future. New features will be added and old ones improved according to the needs of the modellers. New features include module libraries and different analysis tools.<br />
<br />
This documentation introduces you to the current version of Simantics System Dynamics. Documentation includes the basic modelling principles and a guide on how to model system dynamics models with Simantics System Dynamics. If you like to get to know the tool better and try modelling and simulating yourself, [[#Installation Instructions|install]] the software and try our [[Tutorial: Basic System Dynamics Modelling|basic]] and [[Tutorial: Advanced System Dynamics Modelling|advanced]] tutorials!<br />
<br />
== Introduction to System Dynamics Simulation ==<br />
<br />
===System Dynamics===<br />
System dynamics is an approach to understanding different organizations, markets and other complex systems and their dynamic behavior. System dynamics modelling in Simantics is a free modelling tool. See [[#Installation Instructions|installation instructions]].<br />
<br />
===Model===<br />
[[File:ModelStructure.png|right|thumb|Model structure]]<br />
System dynamics model is generally understood as the model configuration. In this tool, the model contains also other components. Model can have Operating interfaces that enable the use of the model with simple controls. Operating interfaces are configured separately and when using them, the complex model is hidden from the user. Experiments are the way to simulate the model. In the future, you can have experiments with different configurations, for example different initial values for some parameters. In that way, you don't have to always configure the model for different scenarios. Modules folder contains all the different module types in your model and you can create new module types there. <br />
<br />
<br style="clear: both" /><br />
<br />
===Components===<br />
Most of the components you can use in your models are basic system dynamics components. The modularity of the models introduces two additional components, Modules and Inputs. All the components are explained below.<br />
[[File:ComponentTypes.png|right|frame|Component types]]<br />
;Auxiliary<br />
:Auxiliary is the most basic variable you can use. It represents a single value or a mathematical expression. There are different types of auxiliary variables currently in the system: Auxiliary, Parameter, Constant and WithLookup. Auxiliary is the default type. Parameters are single values that the user can change. When only parameters are changed, the model simulates faster, because the system does not have to recompile the model. WithLookup is a special variable that has an expression and a lookup table. The expresssion defines what value is taken from the defined table.<br />
;Dependency<br />
:Dependency is an arrow that connects two components. It means that the value of the variable from which the arrow starts is used to calculate the value of the variable where the arrow ends.<br />
;Flow<br />
:Flow connects clouds, valves and stocks. Flow represents an actual flow of something from stocks or clouds to stocks or clouds. There has to be at least one valve in a flow and the system creates it automatically, if none of the ends of the flow is a valve.<br />
;Valve<br />
:Valve regulates the rate of a flow. The value of a valve is automatically used in calculating the level of an adjacent stock. Valves behave just like Auxiliary variables but look different and you can connect also flows to them.<br />
;Stock<br />
:The value of a stock variable is an integral of flows leaving and flows arriving to the variable. The integral is calculated automatically from the valves that are connected to the variable with flow connections. You must give an initial value to the stock. Initial value can be a single value or an equation. You can use values of other variables to calculate the initial value.<br />
;Cloud<br />
:Cloud is not a variable. It represents a starting or ending point of a flow, if it is not in the scope of the model.<br />
;Module<br />
:Modules enable structural modeling. Modules are defined just like the basic model configuration, but the module component hides the actual configuration. You can only connect dependency connections into the module and dependency connections from the module must end to Input variables. The interface of the module is defined using input and output variables in the configuration of the module. All variable types can be set as output variables. If a variable is an output variable, its font is bold.<br />
;Input<br />
:Input variables are the way of getting values from other modules. Inputs look like auxiliary variables except their font is italics. You can set a default value to the input variable in case it is not connected to any variable. Connections are made from the modules properties, when the module is populated. Input doesn't have to be connected with an arrow to a module. If the variable has no connections, it can get values from a higher level in the hierarchy. If an input is connected to an output, the output and its module are shown below the variable using dot notation.<br />
<br style="clear: both" /><br />
<br />
===Modeling principles===<br />
<br />
System dynamics modelling is much more than just mathematical formulas and nice graphs. Models are ways of communicating. There are some basic principles in system dynamics modelling that make the models easier to read and understand. You do not have to apply these principles to simulate models, but using them makes it easier for you to communicate your model to others.<br />
<br />
;Variable names<br />
:Variables names should be nouns, not verbs. The names should be positive: for example it is easier to understand that satisfaction decreases than dissatisfaction rises. <br />
<br />
:Variable names can and should have multiple words, if they are needed. Unfortunately current version of the tool does not support spaces in variable names. A good practice is to use CamelCase if name contains multiple words. This means that you start every word woth a capital letter (example: ExampleVariable).<br />
<br />
;Connections<br />
:You should try to avoid overlapping dependency arrows. In some situations, however, it is not possible. Dependencies should also form distinctive loops, if there is a loop. It makes it easier to read and understand the model and its behavior.<br />
<br />
;Graphical annotations<br />
:System dynamics contains usually annotations for loops, polarities, delays and so on. Currently those annotations are not supported, but the support will be added later. Annotations are important, again, for communicating the behavior of the model.<br />
<br />
==Installation Instructions==<br />
<br />
System dynamics tool is a provided with the Simantics platform.<br />
<br />
# [https://www.simantics.org/simantics/download Download installer from Simantics download page]<br />
# Install the program to a directory without spaces. <br />
# Run Simantics-Sysdyn.exe <br /><br />
: (Default path in windows: C:\Simantics\Sysdyn\1.4\simantics-sysdyn\Simantics-Sysdyn.exe)<br />
<br />
[http://www.openmodelica.org/ OpenModelica] is used to build and simulate the models. Simantics platform has integrated OpenModelica 1.7 for Windows environments. For other versions and other environments you need to install [http://www.openmodelica.org/index.php/download OpenModelica].<br />
<br />
== Workbench ==<br />
<br />
[[File:BasicWorkbench.png|center|729px]]<br />
<br />
<br />
# '''Diagram''' <br /> Diagram is the area where you will graphically modify your model. Diagrams are built from elements that can be dragged from Symbols view or populated using shortcut keys. <br />
# '''Model Browser''' <br /> Model browser shows the structure of your model and all items related to it. <br /> Symbols view is stacked with the model browser and used for dragging elements to diagrams.<br />
# '''Properties''' <br /> Property view shows the selected variable's properties. Property view has a different layout depending on the type of the selected component. The view can also have different tabs depending on the component type. Basic tabs are with variables are Equation and Additional information.<br />
# '''Trend''' <br /> Trend view shows the graphical representation of the values of the selected value over time. For the trend to be shown, a simulation has to be run. The view shows always the results of the latest run, but you can save results of a simulation and show them in the same trend with results from another simulation. Values view and Dependencies are stacked with Trend view and can also be used for analyzing the model.<br />
# '''Experiment controls''' <br /> Experiment controls are shown when an experiment is active. Experiment is activated by double clicking an experiment in the model browser. With the experiment control, you can start simulation runs and save simulation results.<br />
<br />
<br /><br />
If you accidentally close a view, you can reopen them from Window->Show View->Other...<br />
<br />
== Modelling ==<br />
<br />
===Basic modelling===<br />
<br />
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.<br />
<br />
[[File:Basic_1.png|right]]<br />
;Creating a new model<br />
:Start a new model by right-clicking the model browser and selecting New->Model or from the main menu File->New Model.<br />
<br style="clear: both" /><br />
<br />
[[File:Basic_2.png|right]]<br />
;Creating a new module type<br />
:Create a new module type by right-clicking on the Modules-folder and selecting New->Module. This creates a new module type that you can populate to your other modules and the model configuration. <br />
<br style="clear: both" /><br />
<br />
;Configuring a model<br />
:Model configuration can be opened by double clicking Configuration in the model browser. <br />
<br />
;Configuring modules<br />
: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 module!<br />
<br />
;Populate variables<br />
:You can drag variables to a diagram from symbol view. You can also populate variables using [[#Shortcut and control keys|shortcut keys]]<br />
<br />
;Populate modules<br />
:Modules are populated from the model browser. Just drag the module you want to populate from the Modules folder to a diagram.<br />
<br />
;Create connections<br />
: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.<br />
: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.<br />
: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.<br />
<br />
;Connections between modules<br />
:'''Outside the module''' <br /><br />
:You can connect variables to variables in modules like this:<br />
MODULE -----> INPUT<br />
or<br />
ANY VARIABLE -----> MODULE <br />
:This is just the visual configuration, but you need those connections to really connect variables in the module's properties.<br />
:In Inputs -tab you select which variables you connect to inputs inside the module. In Outputs -tab you select which variables you lift from the module to inputs outside it.<br />
<br />
:'''Inside the module''' <br /><br />
:Input variables get values from outside the module<br />
<br />
:Output variables can send their values outside the module. From the variable properties, select Additional Information and press Is Output<br />
<br />
;Configure variables<br />
:Select a single variable from diagram or model browser. The properties of the variables are shown in the equation view and you can modify them.<br />
<br />
;Export model<br />
: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 to for example create different versions of the model, create backups or to transport it to another database.<br />
<br />
;Import model<br />
:Right-click on the model browser and select Import->Model. Browse to your .tg file and select open. The model is added to your model browser.<br />
<br />
===Shortcut and control keys===<br />
<br />
Shortcut keys for configuring a model on diagram.<br />
<br />
{|<br />
|Esc <br />
|Cancel operations (e.g. connection and rename).<br />
|-<br />
|Shift + A <br />
|Hover Auxiliary at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + S<br />
|Hover Stock at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + C<br />
|Hover Cloud at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + V<br />
|Hover Valve at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + I<br />
|Hover Input at the cursor position, populate with left mouse button.<br />
|-<br />
|Alt + left mouse button<br />
|Start an arrow from a variable. End to another variable by clicking left mouse button.<br />
|-<br />
|Alt + right mouse button<br />
|Start flow from a variable. End by clicking left mouse button.<br />
<br />
If a flow is not started or ended on to a variable, a cloud will be created to that end. <br /><br />
If a new flow does not have a valve at either end, a valve will be created in the middle of the flow.<br />
|-<br />
|Delete<br />
|Remove selected variables<br />
|-<br />
|Ctrl + left mouse button<br />
|Select multiple variables<br />
|-<br />
|Mouse wheel or<br/>+ and -<br />
|Diagram zoom<br />
|-<br />
|drag(mouse3) or<br/>drag(shift + any mouse button)<br />
|Diagram pan<br />
|-<br />
|Ctrl + C<br />
|Copy selected elements<br />
|-<br />
|Ctrl + X<br />
|Cut selected elements<br />
|-<br />
|Ctrl + V<br />
|Paste copied or cut elements<br />
|-<br />
|G<br />
|Show / hide grid<br />
|-<br />
|R<br />
|Show / hide ruler<br />
|}<br />
<br />
Other shortcut keys can be found selecting Window -> Preferences from the main menu. Keys are located in General -> Keys.<br />
<br />
== Simulation ==<br />
There are three different ways for simulating a model. Different simulations are represented as different types of experiments in Simantics System Dynamics. <br />
<br />
Experiments are created from the context menu of experiments folder in a model. <br />
<br />
[[File:NewExperiment.png]]<br />
<br />
Double-click on an experiment activates it and displays experiment type specific controls in the main tool bar.<br />
<br />
;Normal simulation<br />
: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.<br />
<br />
;Game simulation<br />
:Game simulations allow simulating an arbitrary number of steps, changing parameter values and continuing simulation with the new values from where it previously ended.<br />
<br />
;Simulation playback<br />
:Simulation playback works essentially as the basic experiment, but it offers some additional visualization options.<br />
<br />
== Simulation result and model structure analysis ==<br />
Simulation results can be viewed as trends in trend view or as plain numbers in values view. The views display results of variables that are selected in the workbench. Users can also create [[#Custom charts |custom charts]].<br />
<br />
Model structure can be examined in the Structure view. There are two options: Dependency structures of individual variables or the complete hierarchy structure of the model.<br />
<br />
;Trend<br />
:Shows you the values of the selected variable(s) graphically over the simulation time. You can modify the trend and zoom it using the context menu (right-click) of the trend. <br /> [[File:Trend.png]]<br />
<br />
;Values<br />
:Shows you the values of the selected variable(s) in a table form. If the value has a star (*) at the end, it means that the value is an approximate. There is no value for that variable for the given time step. Selected values can be copied to other software in csv format.<br /> [[File:Values.png]]<br />
<br />
;Compare results<br />
:You can compare different results of the same model by saving simulation results and displaying the saved results side by side with other results. You can save your results after simulating by clicking the save button [[File:Saveresults.png]] on your experiment controls. The saved results appear to model browser under the active experiment. To show the results on trends and tables, right-click on the result and select Show on charts. <br /> [[File:CompareTrend.png]]<br />
<br />
;Dependencies<br />
:Dependencies display which variables affect and which are affected by the selected variable. The direction and number of steps that are traveled from the selected variable can be configured at the bottom of the view. <br /> [[File:Dependencies.png]]<br />
<br />
;Model Hierarchy<br />
:Model Hierarchy displays the hierarchical structure of the model. The module type where a selected variable is located is highlighted.<br /> [[File:ModelHierarchy.png]]<br />
<br />
== Custom charts ==<br />
Custom charts are user-defined displays of simulation result data. They can be used and re-used in various places. The three types of custom charts (line, bar and pie charts) provide model developers means for examining and developing their models and communicating the simulation results to others. <br />
<br />
Custom charts are created to the Charts folder in model browser.<br />
<br />
[[File:NewChart.png | Creating a new chart]]<br />
<br />
Charts are configured the same way as variables: first select the chart from model browser and then configure it in the property view. Charts can be viewed in the same active trend view as any variable by selecting the chart from model browser. In addition to trend view, charts can be populated directly to the model diagram or to a separate chart panel that can contain multiple charts. <br />
<br />
=== Line chart ===<br />
<br />
Line char 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.<br />
<br />
[[File:LineChart.png|Line chart with an array variable]]<br />
<br />
[[File:LineChartGeneral.png|General settings of line chart]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|The title of the chart. Displayed in the chart<br />
|-<br />
|Type<br />
|Line chart (default) or area chart<br />
|-<br />
|Hide<br />
|Options to hide chart grid, title or legend<br />
|-<br />
|'''X-axis'''<br />
|<br />
|-<br />
|Variable<br />
|A variable that is used as the x-axis variable. The default variable is time and it needs not to be typed in the field.<br />
|-<br />
|Label<br />
|Optional other label for the variable than its name<br />
|-<br />
|Min<br />
|Minimum value of the x-axis<br />
|-<br />
|Max<br />
|Maximum value of the x-axis<br />
|-<br />
|Hide<br />
|Options to hide x-axis lable, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
[[File:LineChartAxisAndVariables.png|Axis and variables settings of line chart]]<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed.<br />
|-<br />
|Color<br />
|Color for the lines of this variable<br />
|-<br />
|Line width<br />
|The width of the lines drawn for this variable<br />
|}<br />
There are also configuration options for y-axis. They are displayed when an axis is selected in the Axis and variables tab.<br />
{|<br />
|'''Y-axis'''<br />
|<br />
|-<br />
|Label<br />
|Label of the axis<br />
|-<br />
|Min<br />
|Minimum value in the axis<br />
|-<br />
|Max<br />
|Maximum value in the axis<br />
|-<br />
|Color<br />
|The color of the axis lines, ticks and labels<br />
|-<br />
|Hide<br />
|Options to hide parts of the axis: label, axis line, tick marks, tick labels<br />
|-<br />
|}<br />
<br />
=== Bar chart ===<br />
Bar charts display variables in a certain point in time. The point can be defined for the complete chart in cart'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. <br />
<br />
[[File:BarChartGeneral.png|General bar chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Name is displayed in model browser.<br />
|-<br />
|Title<br />
|The title of the chart. Title is displayed in the chart, if not hidden<br />
|-<br />
|Type<br />
|Normal or stacked. Normal type displays all variables in separate bars. Stacked mode is able to display one-dimensional array variables in stacks.<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Option for hiding grid, title and Legend. Legend is hidden by default since it only contains the information that the current simulation is displayed.<br />
|-<br />
|}<br />
<br />
[[File:BarChartInDiagram.png|Bar chart in a model diagram]]<br />
<br />
Charts can be added to model diagrams simply by dragging the chart from model browser to diagram.<br />
<br />
[[File:BarChartVariable.png|Settings for a variable in bar chart]]<br />
<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|}<br />
[[File:BarChartAxis.png|Settings for axis in bar chart]]<br />
{|<br />
|'''Domain axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for x axis<br />
|-<br />
|Label angle<br />
|Axis labels can be displayed in an angle. This value determines the angle in degrees.<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|'''Range axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for y axis<br />
|-<br />
|Min<br />
|Minimum value of y axis<br />
|-<br />
|Max<br />
|Maximum value of y axis<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
=== Pie chart ===<br />
<br />
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.<br />
<br />
[[File:PieChartGeneral.png|General pie chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|Title The title of the chart. Displayed in the chart<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Options for hiding title, section labels and legend<br />
|-<br />
|}<br />
<br />
[[File:PieChartVariable.png|Variable settings in pie chart]]<br />
{|<br />
|'''Variables'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Color<br />
|Color for the sector of this variable<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|Exploded<br />
|If set, the sector(s) of the variable(s) are "exploded" away from the center of the pie chart<br />
|-<br />
|}<br />
<br />
[[File:PieChartChartPanel.png|Pie chart in chart panel]]<br />
<br />
=== Chart panel ===<br />
[[File:ChartPanel.png|right]]<br />
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.<br />
<br />
Chart panel can be either horizontally or vertically oriented. Different orientations help in configuring the workbench perspective. <br />
<br />
[[File:ChartPanelOrientation.png|Chart panel orientation]]<br />
<br />
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.<br />
<br />
By default, chart panel is hidden in the upper-left corner of the system dynamics perspective.<br />
<br style="clear: both" /><br />
<br />
== Multidimensional variables ==<br />
<br />
<br />
=== Modeling ===<br />
<br />
Models with multidimensional variables look just like any other models. The structure of the models is replicated givin multiple indexes to variables. For users with programming background, notation Variable[] may be familiar. In system dynamic modeling we need to give names to the indexes. Instead of using numbers to define the indexes, like in normal programming, we use enumerations. The steps to create a model with multidimensional variables are as follows (with examples):<br />
<br />
# '''Create the model structure''' <BR />Model with multidimensional variables looks just like any other model.<BR /> [[File:ModelWithMultidimensionalVariables.png|300px|Model with multidimensional variables]]<br />
# '''Create Enumerations and define the indexes''' <BR />Enumerations are created by right-clicking configuration and selecting New->Enumeration.<BR /> [[File:NewEnumeration.png|250px|New enumeration]]<BR />Define enumeration indexes by adding as many indexes as you want. Rename the indexes by selecting them and then clicking on them again.<BR />[[File:DefineIndexes.png|200px|Index definitions]]<br />
# '''Add Enumerations for variables''' <BR />Select the variable that you want to be multidimensional. From the Indexes -tab in the property view, move the wanted enumerations to the right. The order of the enumerations does matter.[[File:SelectEnumerations.png|500px|Select enumerations for variables]]<br />
# '''Define equations for all possible indexes''' <BR />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 indexes, so the resulting definition can be {{1,2,3},{4,5,6},{7,8,9}}.<BR />[[File:DefineEquations.png|500px|Define equations for all indexes]]<br />
<br />
<br />
<br />
=== Expressions ===<br />
<br />
Values for all cells in the variable matrix can be defined in a single expression. <br />
<br />
[[File: DefineEquations.png|600px]]<br />
<br />
[[File:DefineEquations2.png|600px]]<br />
<br />
In many situations, it is however more clear to define separate expressions for each cell or blocks. <br />
<br />
# '''Define range for the expression'''<BR /> [[File:DefineRange.png]]<br />
# '''Define the expression''' (dimensions of the defined range and the result of the expression must match!) <BR /> [[File:DefineEquations3.png]]<br />
# '''Create a new expression''' <BR /> [[File:CreateNewExpression.png]]<br />
#''' Select the new expression''' <BR /> [[File:SelectNewExpression.png]]<br />
<br />
Repeat until there is value for each cell. There must be exactly one value for each cell.<br />
<br />
=== Array slices ===<br />
<br />
Many times it is useful to access a slice of a multidimensional variable. In this chapter, we will use the following example variable:<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
The whole variable can be accessed in three different ways:<br />
# Auxiliary<br />
# Auxiliary[E1, E2]<br />
# Auxiliary[:, :]<br />
<br />
The following explains different methods for accessing parts of the variable<br />
<br />
// Single cell<br />
Auxiliary[one, eins] = 1<br />
<br />
// Slices<br />
Auxiliary[one, E2] = {1,2,3}<br />
Auxiliary[E1, zwei] = {{2},{5},{8}}<br />
<br />
// In addition to single cells and the whole enumeration range, a subrange of the enumeration can be used<br />
Auxiliary[two : three, E2] = {{4,5,6},{7,8,9}}<br />
Auxiliary[one : two, zwei : drei] = {{2,3},{5,6}}<br />
<br />
The syntax for accessing parts of variables can be used in both expression range definitions and in expressions.<br />
<br />
=== Arithmetic Operators ===<br />
<br />
Arithmetic operations are defined in Modelica. Below are examples of different operations.<br />
<br />
;Addition and substraction<br />
Addition and substraction are calculated elementwise<br />
<br />
{1,2,3} - {0,2,3} = {1,0,0}<br />
{{2,2},{4,4}} + {{8,8},{1,1}} = {{10,10},{5,5}}<br />
{1,2,3} - {1,2} = ERROR! Different array sizes<br />
<br />
;Division<br />
Division with a scalar<br />
{5,10,15} / 5 = {1,2,3}<br />
5 / {5,10,15} = ERROR! not allowed<br />
<br />
Division with an array<br />
{1,2,3} / {1,2,3} = ERROR! not allowed<br />
<br />
// Elementwise<br />
{1,2,3} ./ {1,2,3} = {1,1,1}<br />
<br />
;Multiplication<br />
<br />
Multiplication with a scalar<br />
{1,2,3} * 2 = {2,4,6}<br />
5 * {1,2,3} = {5,10,15}<br />
<br />
Matrix multiplication with an array<br />
{{3,4},{5,6}} * {1,2} = {11,17}<br />
{{3,4},{5,6}} * {1,2,3} = ERROR! incompatible array sizes<br />
<br />
//Elementwise<br />
{1,2} .* {1,2} = {1,4}<br />
<br />
Real[3,2] c = {{1,2},{3,4},{5,6}}; <br />
Real[2,2] d = {{3,4},{5,6}};<br />
Real[2,2] cd;<br />
cd = c[2:3, :] .* d; // Result: {{9,16},{25,36}}<br />
<br />
=== Builtin Modelica functions ===<br />
<br />
Modelica has some builtin functions that help using multidimensional variables. This chapter introduces some of the builtin functions. <br />
<br />
;Dimension and size functions<br />
<br />
We will use the same example variable as previously.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
;ndims(A)<br />
The number of dimensions in array A<br />
ndims(Auxiliary) = 2<br />
<br />
;size(A, i)<br />
The size of dimension i in array A<br />
size(Auxiliary, 2) = 3<br />
<br />
;size(A)<br />
A vector of length ndims(A) containing the dimension sizes of A<br />
size(Auxiliary) = {3,3}<br />
<br />
<br />
;Construction functions<br />
In addition to normal array constructing, a special construction functions can be used.<br />
<br />
;zeros(n1,n2,n3,...)<br />
An array full of zeros with dimensions n1 x n2 x n2 x ... <br />
zeros(2, 2) = {{0,0}, {0,0}}<br />
<br />
;ones(n1,n2,n3,...)<br />
An array full of ones with dimensions n1 x n2 x n2 x ... <br />
ones(2, 2) = {{1,1}, {1,1}}<br />
<br />
;fill(s,n1,n2,n3)<br />
Like zeros() and ones(), but with user defined value (s) for array elements.<br />
fill(3,2,2) = {{3,3}, {3,3}}<br />
<br />
;identity(n)<br />
Creates an n x n integer identity matrix with ones on the diagonal and all other elements zero.<br />
identity(3) =<br />
1 0 0<br />
0 1 0<br />
0 0 1<br />
<br />
;diagonal(v)<br />
Constructs a square matrix with elements of vector v on the diagonal and all other elements zero.<br />
diagonal({1,2,3}) =<br />
1 0 0<br />
0 2 0<br />
0 0 3<br />
<br />
;linspace(x1,x2,n)<br />
Constracts a Real vector from x1 to x2 with n equally spaced elements.<br />
linspace(2,5,4) = {2,3,4,5}<br />
<br />
;Reduction functions<br />
<br />
Reduction functions reduce arrays to scalars.<br />
<br />
;min(A)<br />
Returns the minimum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
min(A) = 1<br />
<br />
;max(A)<br />
Returns the maximum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
max(A) = 4<br />
<br />
;sum(A)<br />
Returns the sum of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
sum(A) = 10 // 1 + 2 + 3 + 4<br />
<br />
;product(A)<br />
Returns the product of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
product(A) = 24 // 1 * 2 * 3 * 4<br />
<br />
<br />
;Using functions with iterators<br />
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.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
AuxiliarySum[E1] = {sum( Auxiliary[ i , E2 ] ) for i in E1} // Result: {6, 15, 24}<br />
<br />
/* Same as:<br />
{sum(Auxiliary[one, E2]), sum(Auxiliary[two, E2]), sum(Auxiliary[three, E2])}<br />
{sum({1,2,3}), sum({4,5,6}), sum({7,8,9})}<br />
*/<br />
<br />
One expression can have multiple iterators. The Modelica specification defines the following format, but it is NOT yet supported in OpenModelica:<br />
{sum(Array[ i, j, E3]) for i in E1, j in E2} // Dimensions reduced from 3 to 2<br />
<br />
To use multiple iterators, use the following format (NOTE the reversed order of iterators!):<br />
{{sum(Array[ i, j, E3]) for j in E2} for i in E1} // Dimensions reduced from 3 to 2<br />
<br />
The range doesn't have to be the whole enumeration. Subranges can also be used.<br />
{sum( Auxiliary[ i , eins : zwei ] ) for i in E1.one : E1.two} // Result: {3, 9}<br />
<br />
/* Same as<br />
{sum(Auxiliary[one, eins : zwei]), sum(Auxiliary[two, eins : zwei])}<br />
{sum({1,2}), sum({4,5})}<br />
*/<br />
<br />
=== Simulation results ===<br />
<br />
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. <br />
<br />
[[File:3x3trend.png|300px|Trend view for a 3x3 variable]]<br />
<br />
The clutter can be reduced by selecting which enumeration indexes are shown in charts. Select an enumeration and tick the indexes 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.<br />
<br />
[[File:ShowInCharts.png|500px|Select indexes to show in charts]]<br />
<br />
<br />
=== Array Variables in Modules ===<br />
<br />
[[File:Replaceable.png|frame|Replaceable enumeration inside a module]]<br />
<br />
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 [[Simantics_System_Dynamics#Modeling|Modeling]]). <br />
<br />
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.<br />
<br />
<br />
<br style="clear: both" /><br />
<br />
In this example, the original enumeration that the modeler used had two indexes. We are using an instance of this module, but we need to use array variables that have three indexes instead of two. We are using two variables and an instance of the module.<br />
<br />
[[File:ReplacingEnumerationConfiguration.png|frame|left|500px|Module configuration for replacing enumerations inside the module]]<br />
<br style="clear: both" /><br />
<br />
In the parent configuration, we have used an enumeration with three indexes in the two variables.<br />
<br />
[[File:Replacing.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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 clickin 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.<br />
<br />
<br />
[[File:ReplacingEnumeration.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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!<br />
<br />
== Functions ==<br />
<br />
Modelica provides a convenient way to use functions in your models. You can create your own functions, import complete function libraries and share function libraries to be used in all of your models. <br />
<br />
=== Creating functions ===<br />
<br />
[[File:NewFunction.png|right]]<br />
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.<br />
<br />
Functions that can be found from Functions -folder can be used in your variable definitions.<br />
<br />
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. <br />
<br />
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.<br />
<br />
Below is an example of a simple function. For more examples, see the built-in functions provided with the tool and [https://www.modelica.org/documents/ Modelica specifications].<br />
<br />
<br style="clear: both" /><br />
<br />
[[File:ExampleFunction.png]]<br />
<br />
=== Function libraries ===<br />
<br />
<br />
[[File:NewFunctionLibrary.png|right]]<br />
<br />
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)).<br />
<br />
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. <br />
<br />
Create a new function library by right-clicking on Functions folder, Shared functions folder or other module library.<br />
<br />
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.<br />
<br />
[[File:SharedFunctions.png]]<br />
<br style="clear: both" /><br />
<br />
=== External functions ===<br />
<br />
Modelica allows you to use external functions that are programmed using C language. Below is a simple example of using a function that returns the sum of two arguments. <br />
<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}<br />
<br />
<br />
[[File:ImportCFunctionLibrary.png|right]]<br />
<br />
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 <br />
(e.g. simantics_home/plugins/org.simantics.openmodelica.win32_x/MinGW/bin/mingw32_gcc.exe -g -O -c ExampleCFunctionCode.c). <br />
<br style="clear: both" /><br />
<br />
[[File:ExampleExternalFunction.png]]<br />
<br />
<br />
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.<br />
<br />
[[File:ExternalFunctionResult.png]]<br />
<br />
<br />
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.<br />
<br />
<br />
Small external C function can also be written directly to the function code in Simantics Sysdyn:<br />
function ExampleExternalFunction<br />
input Real x;<br />
input Real y;<br />
output Real z;<br />
external "C" z=exampleCFunction(x,y) annotation(Include="<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}");<br />
end ExampleExternalFunction;<br />
<br />
=== Modelica functions ===<br />
<br />
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 [[Simantics_System_Dynamics#Builtin_functions|builtin functions for arrays]].<br />
<br />
{|<br />
|abs(x)<br />
|Returns the absolute value of x. Expanded into "(if x >= 0 then x else -x)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|acos(x)<br />
|Inverse cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|asin(x)<br />
|Inverse sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan(x)<br />
|Inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan2(x1,x2)<br />
|four quadrant inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cat(n,A,B,...)<br />
|General concatenation function that concatenates arrays A,B,... along the nth dimension.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|ceil(x)<br />
|Returns the smallest integer not less than x, the closest integer above x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cos(x)<br />
|Cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cosh(x)<br />
|Hyperbolic cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cross(x,y)<br />
|Returns the 3-vector cross product of the 3-vectors x and y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|delay(expr, delayTime)<br />
|Returns the value of expr at the time time-delayTime. The value of expr is returned when time <= time.start + delayTime.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|der(x)<br />
|Time derivative of x. X must be have continuous-time variability.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|div(x, y)<br />
|Returns the algebraic quotient x/y with any fractional part discarted. E.g. div(10,3) = 3.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|edge(b)<br />
|Returns true when the value of the boolean expression b changes. Expanded into (b and not pre(b)).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|exp(x)<br />
|Exponential, base e.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|floor(x)<br />
|Returns the largest integer not greater than x, the closest integer below x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|initial()<br />
|Returns true at the beginning of the simulation. <br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|integer(x)<br />
|Returns the largest integer not greater than x as an integer.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log(x)<br />
|Natural logarithm. (base e, x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log10(x)<br />
|Base 10 logarithm. (x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|mod(x, y)<br />
|Returns the integer modulus of x/y: mod(x,y) = x - floor(x/y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|noEvent(expr)<br />
|noEvent around an expression causes the expression to NOT generate event.<br />
'''Important:''' <br />
:If you want a condition to be checked only on time steps, use noEvent.<br />
:(e.g. if noEvent(value >= 1) then ... else ...)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|pre(x)<br />
|Returns the preceding value of y from time event that has occured before current time.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|rem(x, y)<br />
|Returns the integer remainder of x/y: rem(x,y) = x - div(x,y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sample(start, interval)<br />
|Returns true and triggers time events at times start + i * interval (i=0,1,...).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sign(x)<br />
|Returns -1 if x is negative, 1 if x is positive. Expanded into "(if x > 0 then 1 else if x < 0 then -1 else 0)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sin(x)<br />
|Sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sinh(x)<br />
|Hyperbolic sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sqrt(x)<br />
|Square root of x. The value of x must be greater or equal to 0 or an assertion error occurs.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tan(x)<br />
|Tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tanh(x)<br />
|Hyperbolic tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|terminal()<br />
|Returns true at the end of a successful simulation.<br />
|}<br />
<br />
== Spreadsheets ==<br />
<br />
Spreadsheets allow storing and maintaining values in a familiar format. The current spreadsheet implementation is experimental and does not provide much functionality. Some basic tasks can, however, be performed. You cannot type directly to a cell, you need to first copy some value or text into it. Then it can be modified.<br />
<br />
=== Variable values ===<br />
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.<br />
<br />
[[File:AuxiliarySheetReference.png|Sheet reference in an expression]][[File:AuxiliarySheet.png|Value of a variable in sheet]]<br />
<br />
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 indexes are not mandatory, but help reading and maintaining the sheet.<br />
<br />
[[File:SheetForMultidim.png|Spreadsheet for multidimensional variables]]<br />
<br />
Reference to a sheet range creates an array variable.<br />
<br />
[[File:SheetMultidim1.png|Array variable ArrayTest1[2] with sheet reference]]<br />
<br />
ArrayTest2 has two dimensions. Reference to a larger range creates a two-dimensional variable. By default, the indexes are ordered as in this example. However, if you wish to present the indexes in a different order in the spreadsheet, you can transpose the sheet reference (e.g. transpose(ArrayTestSheet(E2:G3)))<br />
<br />
[[File:SheetMultidim2.png|Array variable ArrayTest2[2,3] with sheet reference]]<br />
<br />
=== History data ===<br />
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.<br />
<br />
[[File:Sheet.png|Spreadsheet with history data]]<br />
<br />
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. <br />
<br />
[[File:HistoryDataSettings.png|History data settings]]<br />
<br />
{|<br />
|'''History data properties'''<br />
|<br />
|-<br />
|Name<br />
|Name of the history dataset<br />
|-<br />
|Sheet<br />
|Combo box for selecting a sheet where the history data is located<br />
|-<br />
|Orientation<br />
|Columns or rows. How the data is arranged in the sheet.<br />
|-<br />
|Range start<br />
|The upper-left corner cell of the history data range<br />
|-<br />
|Range end<br />
|The lower-right corner cell of the history data range<br />
|-<br />
|Time variable<br />
|The name of the time variable in the history data, if it is different than "time"<br />
|-<br />
|Variables in range<br />
|This text field displays the found variables in the given sheet and range<br />
|-<br />
|}<br />
<br />
If the history dataset is activated, history data is displayed whenever it is available for a variable that is displayed in a chart.<br />
<br />
[[File:HistoryData.png|History data in two charts]]<br />
<br />
<br />
<center><br />
[[Simantics]] | ''System Dynamics Modelling''<br />
</center><br />
<br />
----<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Basic System Dynamics Modelling]]'''<br><br />
System dynamics modelling in Simantics is a free modelling tool that is included into the basic installation. This tutorial introduces the basic features of the system dynamics modelling tool.<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Advanced System Dynamics Modelling]]'''<br><br />
This tutorial introduces the more advanced features of the system dynamics modelling tool: Modules and Operating interfaces<br />
<br />
[[Category: Simantics System Dynamics]]</div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:SheetMultidim2.png&diff=569File:SheetMultidim2.png2012-06-04T12:34:19Z<p>Teemu Lempinen: </p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:SheetMultidim1.png&diff=568File:SheetMultidim1.png2012-06-04T12:34:15Z<p>Teemu Lempinen: </p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:SheetForMultidim.png&diff=567File:SheetForMultidim.png2012-06-04T12:34:11Z<p>Teemu Lempinen: </p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=Simantics_System_Dynamics&diff=566Simantics System Dynamics2012-06-04T12:18:20Z<p>Teemu Lempinen: /* Spreadsheets */</p>
<hr />
<div>== Simantics System Dynamics ==<br />
<br />
Simantics System Dynamics is currently the only open source modelling and simulating tool for Simantics. Simantics System Dynamics is under development and will go through some changes in the future. New features will be added and old ones improved according to the needs of the modellers. New features include module libraries and different analysis tools.<br />
<br />
This documentation introduces you to the current version of Simantics System Dynamics. Documentation includes the basic modelling principles and a guide on how to model system dynamics models with Simantics System Dynamics. If you like to get to know the tool better and try modelling and simulating yourself, [[#Installation Instructions|install]] the software and try our [[Tutorial: Basic System Dynamics Modelling|basic]] and [[Tutorial: Advanced System Dynamics Modelling|advanced]] tutorials!<br />
<br />
== Introduction to System Dynamics Simulation ==<br />
<br />
===System Dynamics===<br />
System dynamics is an approach to understanding different organizations, markets and other complex systems and their dynamic behavior. System dynamics modelling in Simantics is a free modelling tool. See [[#Installation Instructions|installation instructions]].<br />
<br />
===Model===<br />
[[File:ModelStructure.png|right|thumb|Model structure]]<br />
System dynamics model is generally understood as the model configuration. In this tool, the model contains also other components. Model can have Operating interfaces that enable the use of the model with simple controls. Operating interfaces are configured separately and when using them, the complex model is hidden from the user. Experiments are the way to simulate the model. In the future, you can have experiments with different configurations, for example different initial values for some parameters. In that way, you don't have to always configure the model for different scenarios. Modules folder contains all the different module types in your model and you can create new module types there. <br />
<br />
<br style="clear: both" /><br />
<br />
===Components===<br />
Most of the components you can use in your models are basic system dynamics components. The modularity of the models introduces two additional components, Modules and Inputs. All the components are explained below.<br />
[[File:ComponentTypes.png|right|frame|Component types]]<br />
;Auxiliary<br />
:Auxiliary is the most basic variable you can use. It represents a single value or a mathematical expression. There are different types of auxiliary variables currently in the system: Auxiliary, Parameter, Constant and WithLookup. Auxiliary is the default type. Parameters are single values that the user can change. When only parameters are changed, the model simulates faster, because the system does not have to recompile the model. WithLookup is a special variable that has an expression and a lookup table. The expresssion defines what value is taken from the defined table.<br />
;Dependency<br />
:Dependency is an arrow that connects two components. It means that the value of the variable from which the arrow starts is used to calculate the value of the variable where the arrow ends.<br />
;Flow<br />
:Flow connects clouds, valves and stocks. Flow represents an actual flow of something from stocks or clouds to stocks or clouds. There has to be at least one valve in a flow and the system creates it automatically, if none of the ends of the flow is a valve.<br />
;Valve<br />
:Valve regulates the rate of a flow. The value of a valve is automatically used in calculating the level of an adjacent stock. Valves behave just like Auxiliary variables but look different and you can connect also flows to them.<br />
;Stock<br />
:The value of a stock variable is an integral of flows leaving and flows arriving to the variable. The integral is calculated automatically from the valves that are connected to the variable with flow connections. You must give an initial value to the stock. Initial value can be a single value or an equation. You can use values of other variables to calculate the initial value.<br />
;Cloud<br />
:Cloud is not a variable. It represents a starting or ending point of a flow, if it is not in the scope of the model.<br />
;Module<br />
:Modules enable structural modeling. Modules are defined just like the basic model configuration, but the module component hides the actual configuration. You can only connect dependency connections into the module and dependency connections from the module must end to Input variables. The interface of the module is defined using input and output variables in the configuration of the module. All variable types can be set as output variables. If a variable is an output variable, its font is bold.<br />
;Input<br />
:Input variables are the way of getting values from other modules. Inputs look like auxiliary variables except their font is italics. You can set a default value to the input variable in case it is not connected to any variable. Connections are made from the modules properties, when the module is populated. Input doesn't have to be connected with an arrow to a module. If the variable has no connections, it can get values from a higher level in the hierarchy. If an input is connected to an output, the output and its module are shown below the variable using dot notation.<br />
<br style="clear: both" /><br />
<br />
===Modeling principles===<br />
<br />
System dynamics modelling is much more than just mathematical formulas and nice graphs. Models are ways of communicating. There are some basic principles in system dynamics modelling that make the models easier to read and understand. You do not have to apply these principles to simulate models, but using them makes it easier for you to communicate your model to others.<br />
<br />
;Variable names<br />
:Variables names should be nouns, not verbs. The names should be positive: for example it is easier to understand that satisfaction decreases than dissatisfaction rises. <br />
<br />
:Variable names can and should have multiple words, if they are needed. Unfortunately current version of the tool does not support spaces in variable names. A good practice is to use CamelCase if name contains multiple words. This means that you start every word woth a capital letter (example: ExampleVariable).<br />
<br />
;Connections<br />
:You should try to avoid overlapping dependency arrows. In some situations, however, it is not possible. Dependencies should also form distinctive loops, if there is a loop. It makes it easier to read and understand the model and its behavior.<br />
<br />
;Graphical annotations<br />
:System dynamics contains usually annotations for loops, polarities, delays and so on. Currently those annotations are not supported, but the support will be added later. Annotations are important, again, for communicating the behavior of the model.<br />
<br />
==Installation Instructions==<br />
<br />
System dynamics tool is a provided with the Simantics platform.<br />
<br />
# [https://www.simantics.org/simantics/download Download installer from Simantics download page]<br />
# Install the program to a directory without spaces. <br />
# Run Simantics-Sysdyn.exe <br /><br />
: (Default path in windows: C:\Simantics\Sysdyn\1.4\simantics-sysdyn\Simantics-Sysdyn.exe)<br />
<br />
[http://www.openmodelica.org/ OpenModelica] is used to build and simulate the models. Simantics platform has integrated OpenModelica 1.7 for Windows environments. For other versions and other environments you need to install [http://www.openmodelica.org/index.php/download OpenModelica].<br />
<br />
== Workbench ==<br />
<br />
[[File:BasicWorkbench.png|center|729px]]<br />
<br />
<br />
# '''Diagram''' <br /> Diagram is the area where you will graphically modify your model. Diagrams are built from elements that can be dragged from Symbols view or populated using shortcut keys. <br />
# '''Model Browser''' <br /> Model browser shows the structure of your model and all items related to it. <br /> Symbols view is stacked with the model browser and used for dragging elements to diagrams.<br />
# '''Properties''' <br /> Property view shows the selected variable's properties. Property view has a different layout depending on the type of the selected component. The view can also have different tabs depending on the component type. Basic tabs are with variables are Equation and Additional information.<br />
# '''Trend''' <br /> Trend view shows the graphical representation of the values of the selected value over time. For the trend to be shown, a simulation has to be run. The view shows always the results of the latest run, but you can save results of a simulation and show them in the same trend with results from another simulation. Values view and Dependencies are stacked with Trend view and can also be used for analyzing the model.<br />
# '''Experiment controls''' <br /> Experiment controls are shown when an experiment is active. Experiment is activated by double clicking an experiment in the model browser. With the experiment control, you can start simulation runs and save simulation results.<br />
<br />
<br /><br />
If you accidentally close a view, you can reopen them from Window->Show View->Other...<br />
<br />
== Modelling ==<br />
<br />
===Basic modelling===<br />
<br />
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.<br />
<br />
[[File:Basic_1.png|right]]<br />
;Creating a new model<br />
:Start a new model by right-clicking the model browser and selecting New->Model or from the main menu File->New Model.<br />
<br style="clear: both" /><br />
<br />
[[File:Basic_2.png|right]]<br />
;Creating a new module type<br />
:Create a new module type by right-clicking on the Modules-folder and selecting New->Module. This creates a new module type that you can populate to your other modules and the model configuration. <br />
<br style="clear: both" /><br />
<br />
;Configuring a model<br />
:Model configuration can be opened by double clicking Configuration in the model browser. <br />
<br />
;Configuring modules<br />
: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 module!<br />
<br />
;Populate variables<br />
:You can drag variables to a diagram from symbol view. You can also populate variables using [[#Shortcut and control keys|shortcut keys]]<br />
<br />
;Populate modules<br />
:Modules are populated from the model browser. Just drag the module you want to populate from the Modules folder to a diagram.<br />
<br />
;Create connections<br />
: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.<br />
: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.<br />
: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.<br />
<br />
;Connections between modules<br />
:'''Outside the module''' <br /><br />
:You can connect variables to variables in modules like this:<br />
MODULE -----> INPUT<br />
or<br />
ANY VARIABLE -----> MODULE <br />
:This is just the visual configuration, but you need those connections to really connect variables in the module's properties.<br />
:In Inputs -tab you select which variables you connect to inputs inside the module. In Outputs -tab you select which variables you lift from the module to inputs outside it.<br />
<br />
:'''Inside the module''' <br /><br />
:Input variables get values from outside the module<br />
<br />
:Output variables can send their values outside the module. From the variable properties, select Additional Information and press Is Output<br />
<br />
;Configure variables<br />
:Select a single variable from diagram or model browser. The properties of the variables are shown in the equation view and you can modify them.<br />
<br />
;Export model<br />
: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 to for example create different versions of the model, create backups or to transport it to another database.<br />
<br />
;Import model<br />
:Right-click on the model browser and select Import->Model. Browse to your .tg file and select open. The model is added to your model browser.<br />
<br />
===Shortcut and control keys===<br />
<br />
Shortcut keys for configuring a model on diagram.<br />
<br />
{|<br />
|Esc <br />
|Cancel operations (e.g. connection and rename).<br />
|-<br />
|Shift + A <br />
|Hover Auxiliary at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + S<br />
|Hover Stock at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + C<br />
|Hover Cloud at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + V<br />
|Hover Valve at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + I<br />
|Hover Input at the cursor position, populate with left mouse button.<br />
|-<br />
|Alt + left mouse button<br />
|Start an arrow from a variable. End to another variable by clicking left mouse button.<br />
|-<br />
|Alt + right mouse button<br />
|Start flow from a variable. End by clicking left mouse button.<br />
<br />
If a flow is not started or ended on to a variable, a cloud will be created to that end. <br /><br />
If a new flow does not have a valve at either end, a valve will be created in the middle of the flow.<br />
|-<br />
|Delete<br />
|Remove selected variables<br />
|-<br />
|Ctrl + left mouse button<br />
|Select multiple variables<br />
|-<br />
|Mouse wheel or<br/>+ and -<br />
|Diagram zoom<br />
|-<br />
|drag(mouse3) or<br/>drag(shift + any mouse button)<br />
|Diagram pan<br />
|-<br />
|Ctrl + C<br />
|Copy selected elements<br />
|-<br />
|Ctrl + X<br />
|Cut selected elements<br />
|-<br />
|Ctrl + V<br />
|Paste copied or cut elements<br />
|-<br />
|G<br />
|Show / hide grid<br />
|-<br />
|R<br />
|Show / hide ruler<br />
|}<br />
<br />
Other shortcut keys can be found selecting Window -> Preferences from the main menu. Keys are located in General -> Keys.<br />
<br />
== Simulation ==<br />
There are three different ways for simulating a model. Different simulations are represented as different types of experiments in Simantics System Dynamics. <br />
<br />
Experiments are created from the context menu of experiments folder in a model. <br />
<br />
[[File:NewExperiment.png]]<br />
<br />
Double-click on an experiment activates it and displays experiment type specific controls in the main tool bar.<br />
<br />
;Normal simulation<br />
: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.<br />
<br />
;Game simulation<br />
:Game simulations allow simulating an arbitrary number of steps, changing parameter values and continuing simulation with the new values from where it previously ended.<br />
<br />
;Simulation playback<br />
:Simulation playback works essentially as the basic experiment, but it offers some additional visualization options.<br />
<br />
== Simulation result and model structure analysis ==<br />
Simulation results can be viewed as trends in trend view or as plain numbers in values view. The views display results of variables that are selected in the workbench. Users can also create [[#Custom charts |custom charts]].<br />
<br />
Model structure can be examined in the Structure view. There are two options: Dependency structures of individual variables or the complete hierarchy structure of the model.<br />
<br />
;Trend<br />
:Shows you the values of the selected variable(s) graphically over the simulation time. You can modify the trend and zoom it using the context menu (right-click) of the trend. <br /> [[File:Trend.png]]<br />
<br />
;Values<br />
:Shows you the values of the selected variable(s) in a table form. If the value has a star (*) at the end, it means that the value is an approximate. There is no value for that variable for the given time step. Selected values can be copied to other software in csv format.<br /> [[File:Values.png]]<br />
<br />
;Compare results<br />
:You can compare different results of the same model by saving simulation results and displaying the saved results side by side with other results. You can save your results after simulating by clicking the save button [[File:Saveresults.png]] on your experiment controls. The saved results appear to model browser under the active experiment. To show the results on trends and tables, right-click on the result and select Show on charts. <br /> [[File:CompareTrend.png]]<br />
<br />
;Dependencies<br />
:Dependencies display which variables affect and which are affected by the selected variable. The direction and number of steps that are traveled from the selected variable can be configured at the bottom of the view. <br /> [[File:Dependencies.png]]<br />
<br />
;Model Hierarchy<br />
:Model Hierarchy displays the hierarchical structure of the model. The module type where a selected variable is located is highlighted.<br /> [[File:ModelHierarchy.png]]<br />
<br />
== Custom charts ==<br />
Custom charts are user-defined displays of simulation result data. They can be used and re-used in various places. The three types of custom charts (line, bar and pie charts) provide model developers means for examining and developing their models and communicating the simulation results to others. <br />
<br />
Custom charts are created to the Charts folder in model browser.<br />
<br />
[[File:NewChart.png | Creating a new chart]]<br />
<br />
Charts are configured the same way as variables: first select the chart from model browser and then configure it in the property view. Charts can be viewed in the same active trend view as any variable by selecting the chart from model browser. In addition to trend view, charts can be populated directly to the model diagram or to a separate chart panel that can contain multiple charts. <br />
<br />
=== Line chart ===<br />
<br />
Line char 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.<br />
<br />
[[File:LineChart.png|Line chart with an array variable]]<br />
<br />
[[File:LineChartGeneral.png|General settings of line chart]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|The title of the chart. Displayed in the chart<br />
|-<br />
|Type<br />
|Line chart (default) or area chart<br />
|-<br />
|Hide<br />
|Options to hide chart grid, title or legend<br />
|-<br />
|'''X-axis'''<br />
|<br />
|-<br />
|Variable<br />
|A variable that is used as the x-axis variable. The default variable is time and it needs not to be typed in the field.<br />
|-<br />
|Label<br />
|Optional other label for the variable than its name<br />
|-<br />
|Min<br />
|Minimum value of the x-axis<br />
|-<br />
|Max<br />
|Maximum value of the x-axis<br />
|-<br />
|Hide<br />
|Options to hide x-axis lable, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
[[File:LineChartAxisAndVariables.png|Axis and variables settings of line chart]]<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed.<br />
|-<br />
|Color<br />
|Color for the lines of this variable<br />
|-<br />
|Line width<br />
|The width of the lines drawn for this variable<br />
|}<br />
There are also configuration options for y-axis. They are displayed when an axis is selected in the Axis and variables tab.<br />
{|<br />
|'''Y-axis'''<br />
|<br />
|-<br />
|Label<br />
|Label of the axis<br />
|-<br />
|Min<br />
|Minimum value in the axis<br />
|-<br />
|Max<br />
|Maximum value in the axis<br />
|-<br />
|Color<br />
|The color of the axis lines, ticks and labels<br />
|-<br />
|Hide<br />
|Options to hide parts of the axis: label, axis line, tick marks, tick labels<br />
|-<br />
|}<br />
<br />
=== Bar chart ===<br />
Bar charts display variables in a certain point in time. The point can be defined for the complete chart in cart'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. <br />
<br />
[[File:BarChartGeneral.png|General bar chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Name is displayed in model browser.<br />
|-<br />
|Title<br />
|The title of the chart. Title is displayed in the chart, if not hidden<br />
|-<br />
|Type<br />
|Normal or stacked. Normal type displays all variables in separate bars. Stacked mode is able to display one-dimensional array variables in stacks.<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Option for hiding grid, title and Legend. Legend is hidden by default since it only contains the information that the current simulation is displayed.<br />
|-<br />
|}<br />
<br />
[[File:BarChartInDiagram.png|Bar chart in a model diagram]]<br />
<br />
Charts can be added to model diagrams simply by dragging the chart from model browser to diagram.<br />
<br />
[[File:BarChartVariable.png|Settings for a variable in bar chart]]<br />
<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|}<br />
[[File:BarChartAxis.png|Settings for axis in bar chart]]<br />
{|<br />
|'''Domain axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for x axis<br />
|-<br />
|Label angle<br />
|Axis labels can be displayed in an angle. This value determines the angle in degrees.<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|'''Range axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for y axis<br />
|-<br />
|Min<br />
|Minimum value of y axis<br />
|-<br />
|Max<br />
|Maximum value of y axis<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
=== Pie chart ===<br />
<br />
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.<br />
<br />
[[File:PieChartGeneral.png|General pie chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|Title The title of the chart. Displayed in the chart<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Options for hiding title, section labels and legend<br />
|-<br />
|}<br />
<br />
[[File:PieChartVariable.png|Variable settings in pie chart]]<br />
{|<br />
|'''Variables'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Color<br />
|Color for the sector of this variable<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|Exploded<br />
|If set, the sector(s) of the variable(s) are "exploded" away from the center of the pie chart<br />
|-<br />
|}<br />
<br />
[[File:PieChartChartPanel.png|Pie chart in chart panel]]<br />
<br />
=== Chart panel ===<br />
[[File:ChartPanel.png|right]]<br />
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.<br />
<br />
Chart panel can be either horizontally or vertically oriented. Different orientations help in configuring the workbench perspective. <br />
<br />
[[File:ChartPanelOrientation.png|Chart panel orientation]]<br />
<br />
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.<br />
<br />
By default, chart panel is hidden in the upper-left corner of the system dynamics perspective.<br />
<br style="clear: both" /><br />
<br />
== Multidimensional variables ==<br />
<br />
<br />
=== Modeling ===<br />
<br />
Models with multidimensional variables look just like any other models. The structure of the models is replicated givin multiple indexes to variables. For users with programming background, notation Variable[] may be familiar. In system dynamic modeling we need to give names to the indexes. Instead of using numbers to define the indexes, like in normal programming, we use enumerations. The steps to create a model with multidimensional variables are as follows (with examples):<br />
<br />
# '''Create the model structure''' <BR />Model with multidimensional variables looks just like any other model.<BR /> [[File:ModelWithMultidimensionalVariables.png|300px|Model with multidimensional variables]]<br />
# '''Create Enumerations and define the indexes''' <BR />Enumerations are created by right-clicking configuration and selecting New->Enumeration.<BR /> [[File:NewEnumeration.png|250px|New enumeration]]<BR />Define enumeration indexes by adding as many indexes as you want. Rename the indexes by selecting them and then clicking on them again.<BR />[[File:DefineIndexes.png|200px|Index definitions]]<br />
# '''Add Enumerations for variables''' <BR />Select the variable that you want to be multidimensional. From the Indexes -tab in the property view, move the wanted enumerations to the right. The order of the enumerations does matter.[[File:SelectEnumerations.png|500px|Select enumerations for variables]]<br />
# '''Define equations for all possible indexes''' <BR />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 indexes, so the resulting definition can be {{1,2,3},{4,5,6},{7,8,9}}.<BR />[[File:DefineEquations.png|500px|Define equations for all indexes]]<br />
<br />
<br />
<br />
=== Expressions ===<br />
<br />
Values for all cells in the variable matrix can be defined in a single expression. <br />
<br />
[[File: DefineEquations.png|600px]]<br />
<br />
[[File:DefineEquations2.png|600px]]<br />
<br />
In many situations, it is however more clear to define separate expressions for each cell or blocks. <br />
<br />
# '''Define range for the expression'''<BR /> [[File:DefineRange.png]]<br />
# '''Define the expression''' (dimensions of the defined range and the result of the expression must match!) <BR /> [[File:DefineEquations3.png]]<br />
# '''Create a new expression''' <BR /> [[File:CreateNewExpression.png]]<br />
#''' Select the new expression''' <BR /> [[File:SelectNewExpression.png]]<br />
<br />
Repeat until there is value for each cell. There must be exactly one value for each cell.<br />
<br />
=== Array slices ===<br />
<br />
Many times it is useful to access a slice of a multidimensional variable. In this chapter, we will use the following example variable:<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
The whole variable can be accessed in three different ways:<br />
# Auxiliary<br />
# Auxiliary[E1, E2]<br />
# Auxiliary[:, :]<br />
<br />
The following explains different methods for accessing parts of the variable<br />
<br />
// Single cell<br />
Auxiliary[one, eins] = 1<br />
<br />
// Slices<br />
Auxiliary[one, E2] = {1,2,3}<br />
Auxiliary[E1, zwei] = {{2},{5},{8}}<br />
<br />
// In addition to single cells and the whole enumeration range, a subrange of the enumeration can be used<br />
Auxiliary[two : three, E2] = {{4,5,6},{7,8,9}}<br />
Auxiliary[one : two, zwei : drei] = {{2,3},{5,6}}<br />
<br />
The syntax for accessing parts of variables can be used in both expression range definitions and in expressions.<br />
<br />
=== Arithmetic Operators ===<br />
<br />
Arithmetic operations are defined in Modelica. Below are examples of different operations.<br />
<br />
;Addition and substraction<br />
Addition and substraction are calculated elementwise<br />
<br />
{1,2,3} - {0,2,3} = {1,0,0}<br />
{{2,2},{4,4}} + {{8,8},{1,1}} = {{10,10},{5,5}}<br />
{1,2,3} - {1,2} = ERROR! Different array sizes<br />
<br />
;Division<br />
Division with a scalar<br />
{5,10,15} / 5 = {1,2,3}<br />
5 / {5,10,15} = ERROR! not allowed<br />
<br />
Division with an array<br />
{1,2,3} / {1,2,3} = ERROR! not allowed<br />
<br />
// Elementwise<br />
{1,2,3} ./ {1,2,3} = {1,1,1}<br />
<br />
;Multiplication<br />
<br />
Multiplication with a scalar<br />
{1,2,3} * 2 = {2,4,6}<br />
5 * {1,2,3} = {5,10,15}<br />
<br />
Matrix multiplication with an array<br />
{{3,4},{5,6}} * {1,2} = {11,17}<br />
{{3,4},{5,6}} * {1,2,3} = ERROR! incompatible array sizes<br />
<br />
//Elementwise<br />
{1,2} .* {1,2} = {1,4}<br />
<br />
Real[3,2] c = {{1,2},{3,4},{5,6}}; <br />
Real[2,2] d = {{3,4},{5,6}};<br />
Real[2,2] cd;<br />
cd = c[2:3, :] .* d; // Result: {{9,16},{25,36}}<br />
<br />
=== Builtin Modelica functions ===<br />
<br />
Modelica has some builtin functions that help using multidimensional variables. This chapter introduces some of the builtin functions. <br />
<br />
;Dimension and size functions<br />
<br />
We will use the same example variable as previously.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
;ndims(A)<br />
The number of dimensions in array A<br />
ndims(Auxiliary) = 2<br />
<br />
;size(A, i)<br />
The size of dimension i in array A<br />
size(Auxiliary, 2) = 3<br />
<br />
;size(A)<br />
A vector of length ndims(A) containing the dimension sizes of A<br />
size(Auxiliary) = {3,3}<br />
<br />
<br />
;Construction functions<br />
In addition to normal array constructing, a special construction functions can be used.<br />
<br />
;zeros(n1,n2,n3,...)<br />
An array full of zeros with dimensions n1 x n2 x n2 x ... <br />
zeros(2, 2) = {{0,0}, {0,0}}<br />
<br />
;ones(n1,n2,n3,...)<br />
An array full of ones with dimensions n1 x n2 x n2 x ... <br />
ones(2, 2) = {{1,1}, {1,1}}<br />
<br />
;fill(s,n1,n2,n3)<br />
Like zeros() and ones(), but with user defined value (s) for array elements.<br />
fill(3,2,2) = {{3,3}, {3,3}}<br />
<br />
;identity(n)<br />
Creates an n x n integer identity matrix with ones on the diagonal and all other elements zero.<br />
identity(3) =<br />
1 0 0<br />
0 1 0<br />
0 0 1<br />
<br />
;diagonal(v)<br />
Constructs a square matrix with elements of vector v on the diagonal and all other elements zero.<br />
diagonal({1,2,3}) =<br />
1 0 0<br />
0 2 0<br />
0 0 3<br />
<br />
;linspace(x1,x2,n)<br />
Constracts a Real vector from x1 to x2 with n equally spaced elements.<br />
linspace(2,5,4) = {2,3,4,5}<br />
<br />
;Reduction functions<br />
<br />
Reduction functions reduce arrays to scalars.<br />
<br />
;min(A)<br />
Returns the minimum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
min(A) = 1<br />
<br />
;max(A)<br />
Returns the maximum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
max(A) = 4<br />
<br />
;sum(A)<br />
Returns the sum of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
sum(A) = 10 // 1 + 2 + 3 + 4<br />
<br />
;product(A)<br />
Returns the product of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
product(A) = 24 // 1 * 2 * 3 * 4<br />
<br />
<br />
;Using functions with iterators<br />
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.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
AuxiliarySum[E1] = {sum( Auxiliary[ i , E2 ] ) for i in E1} // Result: {6, 15, 24}<br />
<br />
/* Same as:<br />
{sum(Auxiliary[one, E2]), sum(Auxiliary[two, E2]), sum(Auxiliary[three, E2])}<br />
{sum({1,2,3}), sum({4,5,6}), sum({7,8,9})}<br />
*/<br />
<br />
One expression can have multiple iterators. The Modelica specification defines the following format, but it is NOT yet supported in OpenModelica:<br />
{sum(Array[ i, j, E3]) for i in E1, j in E2} // Dimensions reduced from 3 to 2<br />
<br />
To use multiple iterators, use the following format (NOTE the reversed order of iterators!):<br />
{{sum(Array[ i, j, E3]) for j in E2} for i in E1} // Dimensions reduced from 3 to 2<br />
<br />
The range doesn't have to be the whole enumeration. Subranges can also be used.<br />
{sum( Auxiliary[ i , eins : zwei ] ) for i in E1.one : E1.two} // Result: {3, 9}<br />
<br />
/* Same as<br />
{sum(Auxiliary[one, eins : zwei]), sum(Auxiliary[two, eins : zwei])}<br />
{sum({1,2}), sum({4,5})}<br />
*/<br />
<br />
=== Simulation results ===<br />
<br />
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. <br />
<br />
[[File:3x3trend.png|300px|Trend view for a 3x3 variable]]<br />
<br />
The clutter can be reduced by selecting which enumeration indexes are shown in charts. Select an enumeration and tick the indexes 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.<br />
<br />
[[File:ShowInCharts.png|500px|Select indexes to show in charts]]<br />
<br />
<br />
=== Array Variables in Modules ===<br />
<br />
[[File:Replaceable.png|frame|Replaceable enumeration inside a module]]<br />
<br />
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 [[Simantics_System_Dynamics#Modeling|Modeling]]). <br />
<br />
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.<br />
<br />
<br />
<br style="clear: both" /><br />
<br />
In this example, the original enumeration that the modeler used had two indexes. We are using an instance of this module, but we need to use array variables that have three indexes instead of two. We are using two variables and an instance of the module.<br />
<br />
[[File:ReplacingEnumerationConfiguration.png|frame|left|500px|Module configuration for replacing enumerations inside the module]]<br />
<br style="clear: both" /><br />
<br />
In the parent configuration, we have used an enumeration with three indexes in the two variables.<br />
<br />
[[File:Replacing.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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 clickin 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.<br />
<br />
<br />
[[File:ReplacingEnumeration.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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!<br />
<br />
== Functions ==<br />
<br />
Modelica provides a convenient way to use functions in your models. You can create your own functions, import complete function libraries and share function libraries to be used in all of your models. <br />
<br />
=== Creating functions ===<br />
<br />
[[File:NewFunction.png|right]]<br />
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.<br />
<br />
Functions that can be found from Functions -folder can be used in your variable definitions.<br />
<br />
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. <br />
<br />
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.<br />
<br />
Below is an example of a simple function. For more examples, see the built-in functions provided with the tool and [https://www.modelica.org/documents/ Modelica specifications].<br />
<br />
<br style="clear: both" /><br />
<br />
[[File:ExampleFunction.png]]<br />
<br />
=== Function libraries ===<br />
<br />
<br />
[[File:NewFunctionLibrary.png|right]]<br />
<br />
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)).<br />
<br />
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. <br />
<br />
Create a new function library by right-clicking on Functions folder, Shared functions folder or other module library.<br />
<br />
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.<br />
<br />
[[File:SharedFunctions.png]]<br />
<br style="clear: both" /><br />
<br />
=== External functions ===<br />
<br />
Modelica allows you to use external functions that are programmed using C language. Below is a simple example of using a function that returns the sum of two arguments. <br />
<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}<br />
<br />
<br />
[[File:ImportCFunctionLibrary.png|right]]<br />
<br />
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 <br />
(e.g. simantics_home/plugins/org.simantics.openmodelica.win32_x/MinGW/bin/mingw32_gcc.exe -g -O -c ExampleCFunctionCode.c). <br />
<br style="clear: both" /><br />
<br />
[[File:ExampleExternalFunction.png]]<br />
<br />
<br />
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.<br />
<br />
[[File:ExternalFunctionResult.png]]<br />
<br />
<br />
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.<br />
<br />
<br />
Small external C function can also be written directly to the function code in Simantics Sysdyn:<br />
function ExampleExternalFunction<br />
input Real x;<br />
input Real y;<br />
output Real z;<br />
external "C" z=exampleCFunction(x,y) annotation(Include="<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}");<br />
end ExampleExternalFunction;<br />
<br />
=== Modelica functions ===<br />
<br />
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 [[Simantics_System_Dynamics#Builtin_functions|builtin functions for arrays]].<br />
<br />
{|<br />
|abs(x)<br />
|Returns the absolute value of x. Expanded into "(if x >= 0 then x else -x)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|acos(x)<br />
|Inverse cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|asin(x)<br />
|Inverse sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan(x)<br />
|Inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan2(x1,x2)<br />
|four quadrant inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cat(n,A,B,...)<br />
|General concatenation function that concatenates arrays A,B,... along the nth dimension.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|ceil(x)<br />
|Returns the smallest integer not less than x, the closest integer above x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cos(x)<br />
|Cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cosh(x)<br />
|Hyperbolic cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cross(x,y)<br />
|Returns the 3-vector cross product of the 3-vectors x and y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|delay(expr, delayTime)<br />
|Returns the value of expr at the time time-delayTime. The value of expr is returned when time <= time.start + delayTime.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|der(x)<br />
|Time derivative of x. X must be have continuous-time variability.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|div(x, y)<br />
|Returns the algebraic quotient x/y with any fractional part discarted. E.g. div(10,3) = 3.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|edge(b)<br />
|Returns true when the value of the boolean expression b changes. Expanded into (b and not pre(b)).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|exp(x)<br />
|Exponential, base e.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|floor(x)<br />
|Returns the largest integer not greater than x, the closest integer below x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|initial()<br />
|Returns true at the beginning of the simulation. <br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|integer(x)<br />
|Returns the largest integer not greater than x as an integer.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log(x)<br />
|Natural logarithm. (base e, x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log10(x)<br />
|Base 10 logarithm. (x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|mod(x, y)<br />
|Returns the integer modulus of x/y: mod(x,y) = x - floor(x/y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|noEvent(expr)<br />
|noEvent around an expression causes the expression to NOT generate event.<br />
'''Important:''' <br />
:If you want a condition to be checked only on time steps, use noEvent.<br />
:(e.g. if noEvent(value >= 1) then ... else ...)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|pre(x)<br />
|Returns the preceding value of y from time event that has occured before current time.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|rem(x, y)<br />
|Returns the integer remainder of x/y: rem(x,y) = x - div(x,y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sample(start, interval)<br />
|Returns true and triggers time events at times start + i * interval (i=0,1,...).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sign(x)<br />
|Returns -1 if x is negative, 1 if x is positive. Expanded into "(if x > 0 then 1 else if x < 0 then -1 else 0)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sin(x)<br />
|Sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sinh(x)<br />
|Hyperbolic sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sqrt(x)<br />
|Square root of x. The value of x must be greater or equal to 0 or an assertion error occurs.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tan(x)<br />
|Tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tanh(x)<br />
|Hyperbolic tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|terminal()<br />
|Returns true at the end of a successful simulation.<br />
|}<br />
<br />
== Spreadsheets ==<br />
<br />
=== Variable values ===<br />
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.<br />
<br />
[[File:AuxiliarySheetReference.png|Sheet reference in an expression]][[File:AuxiliarySheet.png|Value of a variable in sheet]]<br />
<br />
<br />
<br />
=== History data ===<br />
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.<br />
<br />
[[File:Sheet.png|Spreadsheet with history data]]<br />
<br />
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. <br />
<br />
[[File:HistoryDataSettings.png|History data settings]]<br />
<br />
{|<br />
|'''History data properties'''<br />
|<br />
|-<br />
|Name<br />
|Name of the history dataset<br />
|-<br />
|Sheet<br />
|Combo box for selecting a sheet where the history data is located<br />
|-<br />
|Orientation<br />
|Columns or rows. How the data is arranged in the sheet.<br />
|-<br />
|Range start<br />
|The upper-left corner cell of the history data range<br />
|-<br />
|Range end<br />
|The lower-right corner cell of the history data range<br />
|-<br />
|Time variable<br />
|The name of the time variable in the history data, if it is different than "time"<br />
|-<br />
|Variables in range<br />
|This text field displays the found variables in the given sheet and range<br />
|-<br />
|}<br />
<br />
If the history dataset is activated, history data is displayed whenever it is available for a variable that is displayed in a chart.<br />
<br />
[[File:HistoryData.png|History data in two charts]]<br />
<br />
<br />
<center><br />
[[Simantics]] | ''System Dynamics Modelling''<br />
</center><br />
<br />
----<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Basic System Dynamics Modelling]]'''<br><br />
System dynamics modelling in Simantics is a free modelling tool that is included into the basic installation. This tutorial introduces the basic features of the system dynamics modelling tool.<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Advanced System Dynamics Modelling]]'''<br><br />
This tutorial introduces the more advanced features of the system dynamics modelling tool: Modules and Operating interfaces<br />
<br />
[[Category: Simantics System Dynamics]]</div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:AuxiliarySheet.png&diff=565File:AuxiliarySheet.png2012-06-04T12:12:53Z<p>Teemu Lempinen: </p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:AuxiliarySheetReference.png&diff=564File:AuxiliarySheetReference.png2012-06-04T12:11:47Z<p>Teemu Lempinen: uploaded a new version of "File:AuxiliarySheetReference.png"</p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:AuxiliarySheetReference.png&diff=563File:AuxiliarySheetReference.png2012-06-04T12:10:52Z<p>Teemu Lempinen: </p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=Simantics_System_Dynamics&diff=562Simantics System Dynamics2012-06-04T12:09:54Z<p>Teemu Lempinen: /* Spreadsheets */</p>
<hr />
<div>== Simantics System Dynamics ==<br />
<br />
Simantics System Dynamics is currently the only open source modelling and simulating tool for Simantics. Simantics System Dynamics is under development and will go through some changes in the future. New features will be added and old ones improved according to the needs of the modellers. New features include module libraries and different analysis tools.<br />
<br />
This documentation introduces you to the current version of Simantics System Dynamics. Documentation includes the basic modelling principles and a guide on how to model system dynamics models with Simantics System Dynamics. If you like to get to know the tool better and try modelling and simulating yourself, [[#Installation Instructions|install]] the software and try our [[Tutorial: Basic System Dynamics Modelling|basic]] and [[Tutorial: Advanced System Dynamics Modelling|advanced]] tutorials!<br />
<br />
== Introduction to System Dynamics Simulation ==<br />
<br />
===System Dynamics===<br />
System dynamics is an approach to understanding different organizations, markets and other complex systems and their dynamic behavior. System dynamics modelling in Simantics is a free modelling tool. See [[#Installation Instructions|installation instructions]].<br />
<br />
===Model===<br />
[[File:ModelStructure.png|right|thumb|Model structure]]<br />
System dynamics model is generally understood as the model configuration. In this tool, the model contains also other components. Model can have Operating interfaces that enable the use of the model with simple controls. Operating interfaces are configured separately and when using them, the complex model is hidden from the user. Experiments are the way to simulate the model. In the future, you can have experiments with different configurations, for example different initial values for some parameters. In that way, you don't have to always configure the model for different scenarios. Modules folder contains all the different module types in your model and you can create new module types there. <br />
<br />
<br style="clear: both" /><br />
<br />
===Components===<br />
Most of the components you can use in your models are basic system dynamics components. The modularity of the models introduces two additional components, Modules and Inputs. All the components are explained below.<br />
[[File:ComponentTypes.png|right|frame|Component types]]<br />
;Auxiliary<br />
:Auxiliary is the most basic variable you can use. It represents a single value or a mathematical expression. There are different types of auxiliary variables currently in the system: Auxiliary, Parameter, Constant and WithLookup. Auxiliary is the default type. Parameters are single values that the user can change. When only parameters are changed, the model simulates faster, because the system does not have to recompile the model. WithLookup is a special variable that has an expression and a lookup table. The expresssion defines what value is taken from the defined table.<br />
;Dependency<br />
:Dependency is an arrow that connects two components. It means that the value of the variable from which the arrow starts is used to calculate the value of the variable where the arrow ends.<br />
;Flow<br />
:Flow connects clouds, valves and stocks. Flow represents an actual flow of something from stocks or clouds to stocks or clouds. There has to be at least one valve in a flow and the system creates it automatically, if none of the ends of the flow is a valve.<br />
;Valve<br />
:Valve regulates the rate of a flow. The value of a valve is automatically used in calculating the level of an adjacent stock. Valves behave just like Auxiliary variables but look different and you can connect also flows to them.<br />
;Stock<br />
:The value of a stock variable is an integral of flows leaving and flows arriving to the variable. The integral is calculated automatically from the valves that are connected to the variable with flow connections. You must give an initial value to the stock. Initial value can be a single value or an equation. You can use values of other variables to calculate the initial value.<br />
;Cloud<br />
:Cloud is not a variable. It represents a starting or ending point of a flow, if it is not in the scope of the model.<br />
;Module<br />
:Modules enable structural modeling. Modules are defined just like the basic model configuration, but the module component hides the actual configuration. You can only connect dependency connections into the module and dependency connections from the module must end to Input variables. The interface of the module is defined using input and output variables in the configuration of the module. All variable types can be set as output variables. If a variable is an output variable, its font is bold.<br />
;Input<br />
:Input variables are the way of getting values from other modules. Inputs look like auxiliary variables except their font is italics. You can set a default value to the input variable in case it is not connected to any variable. Connections are made from the modules properties, when the module is populated. Input doesn't have to be connected with an arrow to a module. If the variable has no connections, it can get values from a higher level in the hierarchy. If an input is connected to an output, the output and its module are shown below the variable using dot notation.<br />
<br style="clear: both" /><br />
<br />
===Modeling principles===<br />
<br />
System dynamics modelling is much more than just mathematical formulas and nice graphs. Models are ways of communicating. There are some basic principles in system dynamics modelling that make the models easier to read and understand. You do not have to apply these principles to simulate models, but using them makes it easier for you to communicate your model to others.<br />
<br />
;Variable names<br />
:Variables names should be nouns, not verbs. The names should be positive: for example it is easier to understand that satisfaction decreases than dissatisfaction rises. <br />
<br />
:Variable names can and should have multiple words, if they are needed. Unfortunately current version of the tool does not support spaces in variable names. A good practice is to use CamelCase if name contains multiple words. This means that you start every word woth a capital letter (example: ExampleVariable).<br />
<br />
;Connections<br />
:You should try to avoid overlapping dependency arrows. In some situations, however, it is not possible. Dependencies should also form distinctive loops, if there is a loop. It makes it easier to read and understand the model and its behavior.<br />
<br />
;Graphical annotations<br />
:System dynamics contains usually annotations for loops, polarities, delays and so on. Currently those annotations are not supported, but the support will be added later. Annotations are important, again, for communicating the behavior of the model.<br />
<br />
==Installation Instructions==<br />
<br />
System dynamics tool is a provided with the Simantics platform.<br />
<br />
# [https://www.simantics.org/simantics/download Download installer from Simantics download page]<br />
# Install the program to a directory without spaces. <br />
# Run Simantics-Sysdyn.exe <br /><br />
: (Default path in windows: C:\Simantics\Sysdyn\1.4\simantics-sysdyn\Simantics-Sysdyn.exe)<br />
<br />
[http://www.openmodelica.org/ OpenModelica] is used to build and simulate the models. Simantics platform has integrated OpenModelica 1.7 for Windows environments. For other versions and other environments you need to install [http://www.openmodelica.org/index.php/download OpenModelica].<br />
<br />
== Workbench ==<br />
<br />
[[File:BasicWorkbench.png|center|729px]]<br />
<br />
<br />
# '''Diagram''' <br /> Diagram is the area where you will graphically modify your model. Diagrams are built from elements that can be dragged from Symbols view or populated using shortcut keys. <br />
# '''Model Browser''' <br /> Model browser shows the structure of your model and all items related to it. <br /> Symbols view is stacked with the model browser and used for dragging elements to diagrams.<br />
# '''Properties''' <br /> Property view shows the selected variable's properties. Property view has a different layout depending on the type of the selected component. The view can also have different tabs depending on the component type. Basic tabs are with variables are Equation and Additional information.<br />
# '''Trend''' <br /> Trend view shows the graphical representation of the values of the selected value over time. For the trend to be shown, a simulation has to be run. The view shows always the results of the latest run, but you can save results of a simulation and show them in the same trend with results from another simulation. Values view and Dependencies are stacked with Trend view and can also be used for analyzing the model.<br />
# '''Experiment controls''' <br /> Experiment controls are shown when an experiment is active. Experiment is activated by double clicking an experiment in the model browser. With the experiment control, you can start simulation runs and save simulation results.<br />
<br />
<br /><br />
If you accidentally close a view, you can reopen them from Window->Show View->Other...<br />
<br />
== Modelling ==<br />
<br />
===Basic modelling===<br />
<br />
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.<br />
<br />
[[File:Basic_1.png|right]]<br />
;Creating a new model<br />
:Start a new model by right-clicking the model browser and selecting New->Model or from the main menu File->New Model.<br />
<br style="clear: both" /><br />
<br />
[[File:Basic_2.png|right]]<br />
;Creating a new module type<br />
:Create a new module type by right-clicking on the Modules-folder and selecting New->Module. This creates a new module type that you can populate to your other modules and the model configuration. <br />
<br style="clear: both" /><br />
<br />
;Configuring a model<br />
:Model configuration can be opened by double clicking Configuration in the model browser. <br />
<br />
;Configuring modules<br />
: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 module!<br />
<br />
;Populate variables<br />
:You can drag variables to a diagram from symbol view. You can also populate variables using [[#Shortcut and control keys|shortcut keys]]<br />
<br />
;Populate modules<br />
:Modules are populated from the model browser. Just drag the module you want to populate from the Modules folder to a diagram.<br />
<br />
;Create connections<br />
: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.<br />
: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.<br />
: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.<br />
<br />
;Connections between modules<br />
:'''Outside the module''' <br /><br />
:You can connect variables to variables in modules like this:<br />
MODULE -----> INPUT<br />
or<br />
ANY VARIABLE -----> MODULE <br />
:This is just the visual configuration, but you need those connections to really connect variables in the module's properties.<br />
:In Inputs -tab you select which variables you connect to inputs inside the module. In Outputs -tab you select which variables you lift from the module to inputs outside it.<br />
<br />
:'''Inside the module''' <br /><br />
:Input variables get values from outside the module<br />
<br />
:Output variables can send their values outside the module. From the variable properties, select Additional Information and press Is Output<br />
<br />
;Configure variables<br />
:Select a single variable from diagram or model browser. The properties of the variables are shown in the equation view and you can modify them.<br />
<br />
;Export model<br />
: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 to for example create different versions of the model, create backups or to transport it to another database.<br />
<br />
;Import model<br />
:Right-click on the model browser and select Import->Model. Browse to your .tg file and select open. The model is added to your model browser.<br />
<br />
===Shortcut and control keys===<br />
<br />
Shortcut keys for configuring a model on diagram.<br />
<br />
{|<br />
|Esc <br />
|Cancel operations (e.g. connection and rename).<br />
|-<br />
|Shift + A <br />
|Hover Auxiliary at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + S<br />
|Hover Stock at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + C<br />
|Hover Cloud at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + V<br />
|Hover Valve at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + I<br />
|Hover Input at the cursor position, populate with left mouse button.<br />
|-<br />
|Alt + left mouse button<br />
|Start an arrow from a variable. End to another variable by clicking left mouse button.<br />
|-<br />
|Alt + right mouse button<br />
|Start flow from a variable. End by clicking left mouse button.<br />
<br />
If a flow is not started or ended on to a variable, a cloud will be created to that end. <br /><br />
If a new flow does not have a valve at either end, a valve will be created in the middle of the flow.<br />
|-<br />
|Delete<br />
|Remove selected variables<br />
|-<br />
|Ctrl + left mouse button<br />
|Select multiple variables<br />
|-<br />
|Mouse wheel or<br/>+ and -<br />
|Diagram zoom<br />
|-<br />
|drag(mouse3) or<br/>drag(shift + any mouse button)<br />
|Diagram pan<br />
|-<br />
|Ctrl + C<br />
|Copy selected elements<br />
|-<br />
|Ctrl + X<br />
|Cut selected elements<br />
|-<br />
|Ctrl + V<br />
|Paste copied or cut elements<br />
|-<br />
|G<br />
|Show / hide grid<br />
|-<br />
|R<br />
|Show / hide ruler<br />
|}<br />
<br />
Other shortcut keys can be found selecting Window -> Preferences from the main menu. Keys are located in General -> Keys.<br />
<br />
== Simulation ==<br />
There are three different ways for simulating a model. Different simulations are represented as different types of experiments in Simantics System Dynamics. <br />
<br />
Experiments are created from the context menu of experiments folder in a model. <br />
<br />
[[File:NewExperiment.png]]<br />
<br />
Double-click on an experiment activates it and displays experiment type specific controls in the main tool bar.<br />
<br />
;Normal simulation<br />
: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.<br />
<br />
;Game simulation<br />
:Game simulations allow simulating an arbitrary number of steps, changing parameter values and continuing simulation with the new values from where it previously ended.<br />
<br />
;Simulation playback<br />
:Simulation playback works essentially as the basic experiment, but it offers some additional visualization options.<br />
<br />
== Simulation result and model structure analysis ==<br />
Simulation results can be viewed as trends in trend view or as plain numbers in values view. The views display results of variables that are selected in the workbench. Users can also create [[#Custom charts |custom charts]].<br />
<br />
Model structure can be examined in the Structure view. There are two options: Dependency structures of individual variables or the complete hierarchy structure of the model.<br />
<br />
;Trend<br />
:Shows you the values of the selected variable(s) graphically over the simulation time. You can modify the trend and zoom it using the context menu (right-click) of the trend. <br /> [[File:Trend.png]]<br />
<br />
;Values<br />
:Shows you the values of the selected variable(s) in a table form. If the value has a star (*) at the end, it means that the value is an approximate. There is no value for that variable for the given time step. Selected values can be copied to other software in csv format.<br /> [[File:Values.png]]<br />
<br />
;Compare results<br />
:You can compare different results of the same model by saving simulation results and displaying the saved results side by side with other results. You can save your results after simulating by clicking the save button [[File:Saveresults.png]] on your experiment controls. The saved results appear to model browser under the active experiment. To show the results on trends and tables, right-click on the result and select Show on charts. <br /> [[File:CompareTrend.png]]<br />
<br />
;Dependencies<br />
:Dependencies display which variables affect and which are affected by the selected variable. The direction and number of steps that are traveled from the selected variable can be configured at the bottom of the view. <br /> [[File:Dependencies.png]]<br />
<br />
;Model Hierarchy<br />
:Model Hierarchy displays the hierarchical structure of the model. The module type where a selected variable is located is highlighted.<br /> [[File:ModelHierarchy.png]]<br />
<br />
== Custom charts ==<br />
Custom charts are user-defined displays of simulation result data. They can be used and re-used in various places. The three types of custom charts (line, bar and pie charts) provide model developers means for examining and developing their models and communicating the simulation results to others. <br />
<br />
Custom charts are created to the Charts folder in model browser.<br />
<br />
[[File:NewChart.png | Creating a new chart]]<br />
<br />
Charts are configured the same way as variables: first select the chart from model browser and then configure it in the property view. Charts can be viewed in the same active trend view as any variable by selecting the chart from model browser. In addition to trend view, charts can be populated directly to the model diagram or to a separate chart panel that can contain multiple charts. <br />
<br />
=== Line chart ===<br />
<br />
Line char 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.<br />
<br />
[[File:LineChart.png|Line chart with an array variable]]<br />
<br />
[[File:LineChartGeneral.png|General settings of line chart]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|The title of the chart. Displayed in the chart<br />
|-<br />
|Type<br />
|Line chart (default) or area chart<br />
|-<br />
|Hide<br />
|Options to hide chart grid, title or legend<br />
|-<br />
|'''X-axis'''<br />
|<br />
|-<br />
|Variable<br />
|A variable that is used as the x-axis variable. The default variable is time and it needs not to be typed in the field.<br />
|-<br />
|Label<br />
|Optional other label for the variable than its name<br />
|-<br />
|Min<br />
|Minimum value of the x-axis<br />
|-<br />
|Max<br />
|Maximum value of the x-axis<br />
|-<br />
|Hide<br />
|Options to hide x-axis lable, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
[[File:LineChartAxisAndVariables.png|Axis and variables settings of line chart]]<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed.<br />
|-<br />
|Color<br />
|Color for the lines of this variable<br />
|-<br />
|Line width<br />
|The width of the lines drawn for this variable<br />
|}<br />
There are also configuration options for y-axis. They are displayed when an axis is selected in the Axis and variables tab.<br />
{|<br />
|'''Y-axis'''<br />
|<br />
|-<br />
|Label<br />
|Label of the axis<br />
|-<br />
|Min<br />
|Minimum value in the axis<br />
|-<br />
|Max<br />
|Maximum value in the axis<br />
|-<br />
|Color<br />
|The color of the axis lines, ticks and labels<br />
|-<br />
|Hide<br />
|Options to hide parts of the axis: label, axis line, tick marks, tick labels<br />
|-<br />
|}<br />
<br />
=== Bar chart ===<br />
Bar charts display variables in a certain point in time. The point can be defined for the complete chart in cart'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. <br />
<br />
[[File:BarChartGeneral.png|General bar chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Name is displayed in model browser.<br />
|-<br />
|Title<br />
|The title of the chart. Title is displayed in the chart, if not hidden<br />
|-<br />
|Type<br />
|Normal or stacked. Normal type displays all variables in separate bars. Stacked mode is able to display one-dimensional array variables in stacks.<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Option for hiding grid, title and Legend. Legend is hidden by default since it only contains the information that the current simulation is displayed.<br />
|-<br />
|}<br />
<br />
[[File:BarChartInDiagram.png|Bar chart in a model diagram]]<br />
<br />
Charts can be added to model diagrams simply by dragging the chart from model browser to diagram.<br />
<br />
[[File:BarChartVariable.png|Settings for a variable in bar chart]]<br />
<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|}<br />
[[File:BarChartAxis.png|Settings for axis in bar chart]]<br />
{|<br />
|'''Domain axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for x axis<br />
|-<br />
|Label angle<br />
|Axis labels can be displayed in an angle. This value determines the angle in degrees.<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|'''Range axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for y axis<br />
|-<br />
|Min<br />
|Minimum value of y axis<br />
|-<br />
|Max<br />
|Maximum value of y axis<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
=== Pie chart ===<br />
<br />
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.<br />
<br />
[[File:PieChartGeneral.png|General pie chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|Title The title of the chart. Displayed in the chart<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Options for hiding title, section labels and legend<br />
|-<br />
|}<br />
<br />
[[File:PieChartVariable.png|Variable settings in pie chart]]<br />
{|<br />
|'''Variables'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Color<br />
|Color for the sector of this variable<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|Exploded<br />
|If set, the sector(s) of the variable(s) are "exploded" away from the center of the pie chart<br />
|-<br />
|}<br />
<br />
[[File:PieChartChartPanel.png|Pie chart in chart panel]]<br />
<br />
=== Chart panel ===<br />
[[File:ChartPanel.png|right]]<br />
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.<br />
<br />
Chart panel can be either horizontally or vertically oriented. Different orientations help in configuring the workbench perspective. <br />
<br />
[[File:ChartPanelOrientation.png|Chart panel orientation]]<br />
<br />
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.<br />
<br />
By default, chart panel is hidden in the upper-left corner of the system dynamics perspective.<br />
<br style="clear: both" /><br />
<br />
== Multidimensional variables ==<br />
<br />
<br />
=== Modeling ===<br />
<br />
Models with multidimensional variables look just like any other models. The structure of the models is replicated givin multiple indexes to variables. For users with programming background, notation Variable[] may be familiar. In system dynamic modeling we need to give names to the indexes. Instead of using numbers to define the indexes, like in normal programming, we use enumerations. The steps to create a model with multidimensional variables are as follows (with examples):<br />
<br />
# '''Create the model structure''' <BR />Model with multidimensional variables looks just like any other model.<BR /> [[File:ModelWithMultidimensionalVariables.png|300px|Model with multidimensional variables]]<br />
# '''Create Enumerations and define the indexes''' <BR />Enumerations are created by right-clicking configuration and selecting New->Enumeration.<BR /> [[File:NewEnumeration.png|250px|New enumeration]]<BR />Define enumeration indexes by adding as many indexes as you want. Rename the indexes by selecting them and then clicking on them again.<BR />[[File:DefineIndexes.png|200px|Index definitions]]<br />
# '''Add Enumerations for variables''' <BR />Select the variable that you want to be multidimensional. From the Indexes -tab in the property view, move the wanted enumerations to the right. The order of the enumerations does matter.[[File:SelectEnumerations.png|500px|Select enumerations for variables]]<br />
# '''Define equations for all possible indexes''' <BR />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 indexes, so the resulting definition can be {{1,2,3},{4,5,6},{7,8,9}}.<BR />[[File:DefineEquations.png|500px|Define equations for all indexes]]<br />
<br />
<br />
<br />
=== Expressions ===<br />
<br />
Values for all cells in the variable matrix can be defined in a single expression. <br />
<br />
[[File: DefineEquations.png|600px]]<br />
<br />
[[File:DefineEquations2.png|600px]]<br />
<br />
In many situations, it is however more clear to define separate expressions for each cell or blocks. <br />
<br />
# '''Define range for the expression'''<BR /> [[File:DefineRange.png]]<br />
# '''Define the expression''' (dimensions of the defined range and the result of the expression must match!) <BR /> [[File:DefineEquations3.png]]<br />
# '''Create a new expression''' <BR /> [[File:CreateNewExpression.png]]<br />
#''' Select the new expression''' <BR /> [[File:SelectNewExpression.png]]<br />
<br />
Repeat until there is value for each cell. There must be exactly one value for each cell.<br />
<br />
=== Array slices ===<br />
<br />
Many times it is useful to access a slice of a multidimensional variable. In this chapter, we will use the following example variable:<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
The whole variable can be accessed in three different ways:<br />
# Auxiliary<br />
# Auxiliary[E1, E2]<br />
# Auxiliary[:, :]<br />
<br />
The following explains different methods for accessing parts of the variable<br />
<br />
// Single cell<br />
Auxiliary[one, eins] = 1<br />
<br />
// Slices<br />
Auxiliary[one, E2] = {1,2,3}<br />
Auxiliary[E1, zwei] = {{2},{5},{8}}<br />
<br />
// In addition to single cells and the whole enumeration range, a subrange of the enumeration can be used<br />
Auxiliary[two : three, E2] = {{4,5,6},{7,8,9}}<br />
Auxiliary[one : two, zwei : drei] = {{2,3},{5,6}}<br />
<br />
The syntax for accessing parts of variables can be used in both expression range definitions and in expressions.<br />
<br />
=== Arithmetic Operators ===<br />
<br />
Arithmetic operations are defined in Modelica. Below are examples of different operations.<br />
<br />
;Addition and substraction<br />
Addition and substraction are calculated elementwise<br />
<br />
{1,2,3} - {0,2,3} = {1,0,0}<br />
{{2,2},{4,4}} + {{8,8},{1,1}} = {{10,10},{5,5}}<br />
{1,2,3} - {1,2} = ERROR! Different array sizes<br />
<br />
;Division<br />
Division with a scalar<br />
{5,10,15} / 5 = {1,2,3}<br />
5 / {5,10,15} = ERROR! not allowed<br />
<br />
Division with an array<br />
{1,2,3} / {1,2,3} = ERROR! not allowed<br />
<br />
// Elementwise<br />
{1,2,3} ./ {1,2,3} = {1,1,1}<br />
<br />
;Multiplication<br />
<br />
Multiplication with a scalar<br />
{1,2,3} * 2 = {2,4,6}<br />
5 * {1,2,3} = {5,10,15}<br />
<br />
Matrix multiplication with an array<br />
{{3,4},{5,6}} * {1,2} = {11,17}<br />
{{3,4},{5,6}} * {1,2,3} = ERROR! incompatible array sizes<br />
<br />
//Elementwise<br />
{1,2} .* {1,2} = {1,4}<br />
<br />
Real[3,2] c = {{1,2},{3,4},{5,6}}; <br />
Real[2,2] d = {{3,4},{5,6}};<br />
Real[2,2] cd;<br />
cd = c[2:3, :] .* d; // Result: {{9,16},{25,36}}<br />
<br />
=== Builtin Modelica functions ===<br />
<br />
Modelica has some builtin functions that help using multidimensional variables. This chapter introduces some of the builtin functions. <br />
<br />
;Dimension and size functions<br />
<br />
We will use the same example variable as previously.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
;ndims(A)<br />
The number of dimensions in array A<br />
ndims(Auxiliary) = 2<br />
<br />
;size(A, i)<br />
The size of dimension i in array A<br />
size(Auxiliary, 2) = 3<br />
<br />
;size(A)<br />
A vector of length ndims(A) containing the dimension sizes of A<br />
size(Auxiliary) = {3,3}<br />
<br />
<br />
;Construction functions<br />
In addition to normal array constructing, a special construction functions can be used.<br />
<br />
;zeros(n1,n2,n3,...)<br />
An array full of zeros with dimensions n1 x n2 x n2 x ... <br />
zeros(2, 2) = {{0,0}, {0,0}}<br />
<br />
;ones(n1,n2,n3,...)<br />
An array full of ones with dimensions n1 x n2 x n2 x ... <br />
ones(2, 2) = {{1,1}, {1,1}}<br />
<br />
;fill(s,n1,n2,n3)<br />
Like zeros() and ones(), but with user defined value (s) for array elements.<br />
fill(3,2,2) = {{3,3}, {3,3}}<br />
<br />
;identity(n)<br />
Creates an n x n integer identity matrix with ones on the diagonal and all other elements zero.<br />
identity(3) =<br />
1 0 0<br />
0 1 0<br />
0 0 1<br />
<br />
;diagonal(v)<br />
Constructs a square matrix with elements of vector v on the diagonal and all other elements zero.<br />
diagonal({1,2,3}) =<br />
1 0 0<br />
0 2 0<br />
0 0 3<br />
<br />
;linspace(x1,x2,n)<br />
Constracts a Real vector from x1 to x2 with n equally spaced elements.<br />
linspace(2,5,4) = {2,3,4,5}<br />
<br />
;Reduction functions<br />
<br />
Reduction functions reduce arrays to scalars.<br />
<br />
;min(A)<br />
Returns the minimum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
min(A) = 1<br />
<br />
;max(A)<br />
Returns the maximum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
max(A) = 4<br />
<br />
;sum(A)<br />
Returns the sum of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
sum(A) = 10 // 1 + 2 + 3 + 4<br />
<br />
;product(A)<br />
Returns the product of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
product(A) = 24 // 1 * 2 * 3 * 4<br />
<br />
<br />
;Using functions with iterators<br />
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.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
AuxiliarySum[E1] = {sum( Auxiliary[ i , E2 ] ) for i in E1} // Result: {6, 15, 24}<br />
<br />
/* Same as:<br />
{sum(Auxiliary[one, E2]), sum(Auxiliary[two, E2]), sum(Auxiliary[three, E2])}<br />
{sum({1,2,3}), sum({4,5,6}), sum({7,8,9})}<br />
*/<br />
<br />
One expression can have multiple iterators. The Modelica specification defines the following format, but it is NOT yet supported in OpenModelica:<br />
{sum(Array[ i, j, E3]) for i in E1, j in E2} // Dimensions reduced from 3 to 2<br />
<br />
To use multiple iterators, use the following format (NOTE the reversed order of iterators!):<br />
{{sum(Array[ i, j, E3]) for j in E2} for i in E1} // Dimensions reduced from 3 to 2<br />
<br />
The range doesn't have to be the whole enumeration. Subranges can also be used.<br />
{sum( Auxiliary[ i , eins : zwei ] ) for i in E1.one : E1.two} // Result: {3, 9}<br />
<br />
/* Same as<br />
{sum(Auxiliary[one, eins : zwei]), sum(Auxiliary[two, eins : zwei])}<br />
{sum({1,2}), sum({4,5})}<br />
*/<br />
<br />
=== Simulation results ===<br />
<br />
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. <br />
<br />
[[File:3x3trend.png|300px|Trend view for a 3x3 variable]]<br />
<br />
The clutter can be reduced by selecting which enumeration indexes are shown in charts. Select an enumeration and tick the indexes 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.<br />
<br />
[[File:ShowInCharts.png|500px|Select indexes to show in charts]]<br />
<br />
<br />
=== Array Variables in Modules ===<br />
<br />
[[File:Replaceable.png|frame|Replaceable enumeration inside a module]]<br />
<br />
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 [[Simantics_System_Dynamics#Modeling|Modeling]]). <br />
<br />
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.<br />
<br />
<br />
<br style="clear: both" /><br />
<br />
In this example, the original enumeration that the modeler used had two indexes. We are using an instance of this module, but we need to use array variables that have three indexes instead of two. We are using two variables and an instance of the module.<br />
<br />
[[File:ReplacingEnumerationConfiguration.png|frame|left|500px|Module configuration for replacing enumerations inside the module]]<br />
<br style="clear: both" /><br />
<br />
In the parent configuration, we have used an enumeration with three indexes in the two variables.<br />
<br />
[[File:Replacing.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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 clickin 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.<br />
<br />
<br />
[[File:ReplacingEnumeration.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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!<br />
<br />
== Functions ==<br />
<br />
Modelica provides a convenient way to use functions in your models. You can create your own functions, import complete function libraries and share function libraries to be used in all of your models. <br />
<br />
=== Creating functions ===<br />
<br />
[[File:NewFunction.png|right]]<br />
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.<br />
<br />
Functions that can be found from Functions -folder can be used in your variable definitions.<br />
<br />
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. <br />
<br />
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.<br />
<br />
Below is an example of a simple function. For more examples, see the built-in functions provided with the tool and [https://www.modelica.org/documents/ Modelica specifications].<br />
<br />
<br style="clear: both" /><br />
<br />
[[File:ExampleFunction.png]]<br />
<br />
=== Function libraries ===<br />
<br />
<br />
[[File:NewFunctionLibrary.png|right]]<br />
<br />
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)).<br />
<br />
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. <br />
<br />
Create a new function library by right-clicking on Functions folder, Shared functions folder or other module library.<br />
<br />
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.<br />
<br />
[[File:SharedFunctions.png]]<br />
<br style="clear: both" /><br />
<br />
=== External functions ===<br />
<br />
Modelica allows you to use external functions that are programmed using C language. Below is a simple example of using a function that returns the sum of two arguments. <br />
<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}<br />
<br />
<br />
[[File:ImportCFunctionLibrary.png|right]]<br />
<br />
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 <br />
(e.g. simantics_home/plugins/org.simantics.openmodelica.win32_x/MinGW/bin/mingw32_gcc.exe -g -O -c ExampleCFunctionCode.c). <br />
<br style="clear: both" /><br />
<br />
[[File:ExampleExternalFunction.png]]<br />
<br />
<br />
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.<br />
<br />
[[File:ExternalFunctionResult.png]]<br />
<br />
<br />
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.<br />
<br />
<br />
Small external C function can also be written directly to the function code in Simantics Sysdyn:<br />
function ExampleExternalFunction<br />
input Real x;<br />
input Real y;<br />
output Real z;<br />
external "C" z=exampleCFunction(x,y) annotation(Include="<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}");<br />
end ExampleExternalFunction;<br />
<br />
=== Modelica functions ===<br />
<br />
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 [[Simantics_System_Dynamics#Builtin_functions|builtin functions for arrays]].<br />
<br />
{|<br />
|abs(x)<br />
|Returns the absolute value of x. Expanded into "(if x >= 0 then x else -x)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|acos(x)<br />
|Inverse cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|asin(x)<br />
|Inverse sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan(x)<br />
|Inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan2(x1,x2)<br />
|four quadrant inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cat(n,A,B,...)<br />
|General concatenation function that concatenates arrays A,B,... along the nth dimension.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|ceil(x)<br />
|Returns the smallest integer not less than x, the closest integer above x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cos(x)<br />
|Cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cosh(x)<br />
|Hyperbolic cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cross(x,y)<br />
|Returns the 3-vector cross product of the 3-vectors x and y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|delay(expr, delayTime)<br />
|Returns the value of expr at the time time-delayTime. The value of expr is returned when time <= time.start + delayTime.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|der(x)<br />
|Time derivative of x. X must be have continuous-time variability.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|div(x, y)<br />
|Returns the algebraic quotient x/y with any fractional part discarted. E.g. div(10,3) = 3.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|edge(b)<br />
|Returns true when the value of the boolean expression b changes. Expanded into (b and not pre(b)).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|exp(x)<br />
|Exponential, base e.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|floor(x)<br />
|Returns the largest integer not greater than x, the closest integer below x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|initial()<br />
|Returns true at the beginning of the simulation. <br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|integer(x)<br />
|Returns the largest integer not greater than x as an integer.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log(x)<br />
|Natural logarithm. (base e, x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log10(x)<br />
|Base 10 logarithm. (x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|mod(x, y)<br />
|Returns the integer modulus of x/y: mod(x,y) = x - floor(x/y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|noEvent(expr)<br />
|noEvent around an expression causes the expression to NOT generate event.<br />
'''Important:''' <br />
:If you want a condition to be checked only on time steps, use noEvent.<br />
:(e.g. if noEvent(value >= 1) then ... else ...)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|pre(x)<br />
|Returns the preceding value of y from time event that has occured before current time.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|rem(x, y)<br />
|Returns the integer remainder of x/y: rem(x,y) = x - div(x,y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sample(start, interval)<br />
|Returns true and triggers time events at times start + i * interval (i=0,1,...).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sign(x)<br />
|Returns -1 if x is negative, 1 if x is positive. Expanded into "(if x > 0 then 1 else if x < 0 then -1 else 0)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sin(x)<br />
|Sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sinh(x)<br />
|Hyperbolic sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sqrt(x)<br />
|Square root of x. The value of x must be greater or equal to 0 or an assertion error occurs.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tan(x)<br />
|Tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tanh(x)<br />
|Hyperbolic tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|terminal()<br />
|Returns true at the end of a successful simulation.<br />
|}<br />
<br />
== Spreadsheets ==<br />
<br />
=== Variable values ===<br />
<br />
<br />
[[File:AuxiliarySheetReference.png|Sheet reference in an expression]]<br />
<br />
=== History data ===<br />
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.<br />
<br />
[[File:Sheet.png|Spreadsheet with history data]]<br />
<br />
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. <br />
<br />
[[File:HistoryDataSettings.png|History data settings]]<br />
<br />
{|<br />
|'''History data properties'''<br />
|<br />
|-<br />
|Name<br />
|Name of the history dataset<br />
|-<br />
|Sheet<br />
|Combo box for selecting a sheet where the history data is located<br />
|-<br />
|Orientation<br />
|Columns or rows. How the data is arranged in the sheet.<br />
|-<br />
|Range start<br />
|The upper-left corner cell of the history data range<br />
|-<br />
|Range end<br />
|The lower-right corner cell of the history data range<br />
|-<br />
|Time variable<br />
|The name of the time variable in the history data, if it is different than "time"<br />
|-<br />
|Variables in range<br />
|This text field displays the found variables in the given sheet and range<br />
|-<br />
|}<br />
<br />
If the history dataset is activated, history data is displayed whenever it is available for a variable that is displayed in a chart.<br />
<br />
[[File:HistoryData.png|History data in two charts]]<br />
<br />
<br />
<center><br />
[[Simantics]] | ''System Dynamics Modelling''<br />
</center><br />
<br />
----<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Basic System Dynamics Modelling]]'''<br><br />
System dynamics modelling in Simantics is a free modelling tool that is included into the basic installation. This tutorial introduces the basic features of the system dynamics modelling tool.<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Advanced System Dynamics Modelling]]'''<br><br />
This tutorial introduces the more advanced features of the system dynamics modelling tool: Modules and Operating interfaces<br />
<br />
[[Category: Simantics System Dynamics]]</div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:HistoryData.png&diff=561File:HistoryData.png2012-06-04T12:09:21Z<p>Teemu Lempinen: </p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:HistoryDataSettings.png&diff=560File:HistoryDataSettings.png2012-06-04T12:07:18Z<p>Teemu Lempinen: </p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:Sheet.png&diff=559File:Sheet.png2012-06-04T12:07:12Z<p>Teemu Lempinen: </p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=Simantics_System_Dynamics&diff=558Simantics System Dynamics2012-06-04T11:36:40Z<p>Teemu Lempinen: /* Modelica functions */</p>
<hr />
<div>== Simantics System Dynamics ==<br />
<br />
Simantics System Dynamics is currently the only open source modelling and simulating tool for Simantics. Simantics System Dynamics is under development and will go through some changes in the future. New features will be added and old ones improved according to the needs of the modellers. New features include module libraries and different analysis tools.<br />
<br />
This documentation introduces you to the current version of Simantics System Dynamics. Documentation includes the basic modelling principles and a guide on how to model system dynamics models with Simantics System Dynamics. If you like to get to know the tool better and try modelling and simulating yourself, [[#Installation Instructions|install]] the software and try our [[Tutorial: Basic System Dynamics Modelling|basic]] and [[Tutorial: Advanced System Dynamics Modelling|advanced]] tutorials!<br />
<br />
== Introduction to System Dynamics Simulation ==<br />
<br />
===System Dynamics===<br />
System dynamics is an approach to understanding different organizations, markets and other complex systems and their dynamic behavior. System dynamics modelling in Simantics is a free modelling tool. See [[#Installation Instructions|installation instructions]].<br />
<br />
===Model===<br />
[[File:ModelStructure.png|right|thumb|Model structure]]<br />
System dynamics model is generally understood as the model configuration. In this tool, the model contains also other components. Model can have Operating interfaces that enable the use of the model with simple controls. Operating interfaces are configured separately and when using them, the complex model is hidden from the user. Experiments are the way to simulate the model. In the future, you can have experiments with different configurations, for example different initial values for some parameters. In that way, you don't have to always configure the model for different scenarios. Modules folder contains all the different module types in your model and you can create new module types there. <br />
<br />
<br style="clear: both" /><br />
<br />
===Components===<br />
Most of the components you can use in your models are basic system dynamics components. The modularity of the models introduces two additional components, Modules and Inputs. All the components are explained below.<br />
[[File:ComponentTypes.png|right|frame|Component types]]<br />
;Auxiliary<br />
:Auxiliary is the most basic variable you can use. It represents a single value or a mathematical expression. There are different types of auxiliary variables currently in the system: Auxiliary, Parameter, Constant and WithLookup. Auxiliary is the default type. Parameters are single values that the user can change. When only parameters are changed, the model simulates faster, because the system does not have to recompile the model. WithLookup is a special variable that has an expression and a lookup table. The expresssion defines what value is taken from the defined table.<br />
;Dependency<br />
:Dependency is an arrow that connects two components. It means that the value of the variable from which the arrow starts is used to calculate the value of the variable where the arrow ends.<br />
;Flow<br />
:Flow connects clouds, valves and stocks. Flow represents an actual flow of something from stocks or clouds to stocks or clouds. There has to be at least one valve in a flow and the system creates it automatically, if none of the ends of the flow is a valve.<br />
;Valve<br />
:Valve regulates the rate of a flow. The value of a valve is automatically used in calculating the level of an adjacent stock. Valves behave just like Auxiliary variables but look different and you can connect also flows to them.<br />
;Stock<br />
:The value of a stock variable is an integral of flows leaving and flows arriving to the variable. The integral is calculated automatically from the valves that are connected to the variable with flow connections. You must give an initial value to the stock. Initial value can be a single value or an equation. You can use values of other variables to calculate the initial value.<br />
;Cloud<br />
:Cloud is not a variable. It represents a starting or ending point of a flow, if it is not in the scope of the model.<br />
;Module<br />
:Modules enable structural modeling. Modules are defined just like the basic model configuration, but the module component hides the actual configuration. You can only connect dependency connections into the module and dependency connections from the module must end to Input variables. The interface of the module is defined using input and output variables in the configuration of the module. All variable types can be set as output variables. If a variable is an output variable, its font is bold.<br />
;Input<br />
:Input variables are the way of getting values from other modules. Inputs look like auxiliary variables except their font is italics. You can set a default value to the input variable in case it is not connected to any variable. Connections are made from the modules properties, when the module is populated. Input doesn't have to be connected with an arrow to a module. If the variable has no connections, it can get values from a higher level in the hierarchy. If an input is connected to an output, the output and its module are shown below the variable using dot notation.<br />
<br style="clear: both" /><br />
<br />
===Modeling principles===<br />
<br />
System dynamics modelling is much more than just mathematical formulas and nice graphs. Models are ways of communicating. There are some basic principles in system dynamics modelling that make the models easier to read and understand. You do not have to apply these principles to simulate models, but using them makes it easier for you to communicate your model to others.<br />
<br />
;Variable names<br />
:Variables names should be nouns, not verbs. The names should be positive: for example it is easier to understand that satisfaction decreases than dissatisfaction rises. <br />
<br />
:Variable names can and should have multiple words, if they are needed. Unfortunately current version of the tool does not support spaces in variable names. A good practice is to use CamelCase if name contains multiple words. This means that you start every word woth a capital letter (example: ExampleVariable).<br />
<br />
;Connections<br />
:You should try to avoid overlapping dependency arrows. In some situations, however, it is not possible. Dependencies should also form distinctive loops, if there is a loop. It makes it easier to read and understand the model and its behavior.<br />
<br />
;Graphical annotations<br />
:System dynamics contains usually annotations for loops, polarities, delays and so on. Currently those annotations are not supported, but the support will be added later. Annotations are important, again, for communicating the behavior of the model.<br />
<br />
==Installation Instructions==<br />
<br />
System dynamics tool is a provided with the Simantics platform.<br />
<br />
# [https://www.simantics.org/simantics/download Download installer from Simantics download page]<br />
# Install the program to a directory without spaces. <br />
# Run Simantics-Sysdyn.exe <br /><br />
: (Default path in windows: C:\Simantics\Sysdyn\1.4\simantics-sysdyn\Simantics-Sysdyn.exe)<br />
<br />
[http://www.openmodelica.org/ OpenModelica] is used to build and simulate the models. Simantics platform has integrated OpenModelica 1.7 for Windows environments. For other versions and other environments you need to install [http://www.openmodelica.org/index.php/download OpenModelica].<br />
<br />
== Workbench ==<br />
<br />
[[File:BasicWorkbench.png|center|729px]]<br />
<br />
<br />
# '''Diagram''' <br /> Diagram is the area where you will graphically modify your model. Diagrams are built from elements that can be dragged from Symbols view or populated using shortcut keys. <br />
# '''Model Browser''' <br /> Model browser shows the structure of your model and all items related to it. <br /> Symbols view is stacked with the model browser and used for dragging elements to diagrams.<br />
# '''Properties''' <br /> Property view shows the selected variable's properties. Property view has a different layout depending on the type of the selected component. The view can also have different tabs depending on the component type. Basic tabs are with variables are Equation and Additional information.<br />
# '''Trend''' <br /> Trend view shows the graphical representation of the values of the selected value over time. For the trend to be shown, a simulation has to be run. The view shows always the results of the latest run, but you can save results of a simulation and show them in the same trend with results from another simulation. Values view and Dependencies are stacked with Trend view and can also be used for analyzing the model.<br />
# '''Experiment controls''' <br /> Experiment controls are shown when an experiment is active. Experiment is activated by double clicking an experiment in the model browser. With the experiment control, you can start simulation runs and save simulation results.<br />
<br />
<br /><br />
If you accidentally close a view, you can reopen them from Window->Show View->Other...<br />
<br />
== Modelling ==<br />
<br />
===Basic modelling===<br />
<br />
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.<br />
<br />
[[File:Basic_1.png|right]]<br />
;Creating a new model<br />
:Start a new model by right-clicking the model browser and selecting New->Model or from the main menu File->New Model.<br />
<br style="clear: both" /><br />
<br />
[[File:Basic_2.png|right]]<br />
;Creating a new module type<br />
:Create a new module type by right-clicking on the Modules-folder and selecting New->Module. This creates a new module type that you can populate to your other modules and the model configuration. <br />
<br style="clear: both" /><br />
<br />
;Configuring a model<br />
:Model configuration can be opened by double clicking Configuration in the model browser. <br />
<br />
;Configuring modules<br />
: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 module!<br />
<br />
;Populate variables<br />
:You can drag variables to a diagram from symbol view. You can also populate variables using [[#Shortcut and control keys|shortcut keys]]<br />
<br />
;Populate modules<br />
:Modules are populated from the model browser. Just drag the module you want to populate from the Modules folder to a diagram.<br />
<br />
;Create connections<br />
: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.<br />
: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.<br />
: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.<br />
<br />
;Connections between modules<br />
:'''Outside the module''' <br /><br />
:You can connect variables to variables in modules like this:<br />
MODULE -----> INPUT<br />
or<br />
ANY VARIABLE -----> MODULE <br />
:This is just the visual configuration, but you need those connections to really connect variables in the module's properties.<br />
:In Inputs -tab you select which variables you connect to inputs inside the module. In Outputs -tab you select which variables you lift from the module to inputs outside it.<br />
<br />
:'''Inside the module''' <br /><br />
:Input variables get values from outside the module<br />
<br />
:Output variables can send their values outside the module. From the variable properties, select Additional Information and press Is Output<br />
<br />
;Configure variables<br />
:Select a single variable from diagram or model browser. The properties of the variables are shown in the equation view and you can modify them.<br />
<br />
;Export model<br />
: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 to for example create different versions of the model, create backups or to transport it to another database.<br />
<br />
;Import model<br />
:Right-click on the model browser and select Import->Model. Browse to your .tg file and select open. The model is added to your model browser.<br />
<br />
===Shortcut and control keys===<br />
<br />
Shortcut keys for configuring a model on diagram.<br />
<br />
{|<br />
|Esc <br />
|Cancel operations (e.g. connection and rename).<br />
|-<br />
|Shift + A <br />
|Hover Auxiliary at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + S<br />
|Hover Stock at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + C<br />
|Hover Cloud at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + V<br />
|Hover Valve at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + I<br />
|Hover Input at the cursor position, populate with left mouse button.<br />
|-<br />
|Alt + left mouse button<br />
|Start an arrow from a variable. End to another variable by clicking left mouse button.<br />
|-<br />
|Alt + right mouse button<br />
|Start flow from a variable. End by clicking left mouse button.<br />
<br />
If a flow is not started or ended on to a variable, a cloud will be created to that end. <br /><br />
If a new flow does not have a valve at either end, a valve will be created in the middle of the flow.<br />
|-<br />
|Delete<br />
|Remove selected variables<br />
|-<br />
|Ctrl + left mouse button<br />
|Select multiple variables<br />
|-<br />
|Mouse wheel or<br/>+ and -<br />
|Diagram zoom<br />
|-<br />
|drag(mouse3) or<br/>drag(shift + any mouse button)<br />
|Diagram pan<br />
|-<br />
|Ctrl + C<br />
|Copy selected elements<br />
|-<br />
|Ctrl + X<br />
|Cut selected elements<br />
|-<br />
|Ctrl + V<br />
|Paste copied or cut elements<br />
|-<br />
|G<br />
|Show / hide grid<br />
|-<br />
|R<br />
|Show / hide ruler<br />
|}<br />
<br />
Other shortcut keys can be found selecting Window -> Preferences from the main menu. Keys are located in General -> Keys.<br />
<br />
== Simulation ==<br />
There are three different ways for simulating a model. Different simulations are represented as different types of experiments in Simantics System Dynamics. <br />
<br />
Experiments are created from the context menu of experiments folder in a model. <br />
<br />
[[File:NewExperiment.png]]<br />
<br />
Double-click on an experiment activates it and displays experiment type specific controls in the main tool bar.<br />
<br />
;Normal simulation<br />
: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.<br />
<br />
;Game simulation<br />
:Game simulations allow simulating an arbitrary number of steps, changing parameter values and continuing simulation with the new values from where it previously ended.<br />
<br />
;Simulation playback<br />
:Simulation playback works essentially as the basic experiment, but it offers some additional visualization options.<br />
<br />
== Simulation result and model structure analysis ==<br />
Simulation results can be viewed as trends in trend view or as plain numbers in values view. The views display results of variables that are selected in the workbench. Users can also create [[#Custom charts |custom charts]].<br />
<br />
Model structure can be examined in the Structure view. There are two options: Dependency structures of individual variables or the complete hierarchy structure of the model.<br />
<br />
;Trend<br />
:Shows you the values of the selected variable(s) graphically over the simulation time. You can modify the trend and zoom it using the context menu (right-click) of the trend. <br /> [[File:Trend.png]]<br />
<br />
;Values<br />
:Shows you the values of the selected variable(s) in a table form. If the value has a star (*) at the end, it means that the value is an approximate. There is no value for that variable for the given time step. Selected values can be copied to other software in csv format.<br /> [[File:Values.png]]<br />
<br />
;Compare results<br />
:You can compare different results of the same model by saving simulation results and displaying the saved results side by side with other results. You can save your results after simulating by clicking the save button [[File:Saveresults.png]] on your experiment controls. The saved results appear to model browser under the active experiment. To show the results on trends and tables, right-click on the result and select Show on charts. <br /> [[File:CompareTrend.png]]<br />
<br />
;Dependencies<br />
:Dependencies display which variables affect and which are affected by the selected variable. The direction and number of steps that are traveled from the selected variable can be configured at the bottom of the view. <br /> [[File:Dependencies.png]]<br />
<br />
;Model Hierarchy<br />
:Model Hierarchy displays the hierarchical structure of the model. The module type where a selected variable is located is highlighted.<br /> [[File:ModelHierarchy.png]]<br />
<br />
== Custom charts ==<br />
Custom charts are user-defined displays of simulation result data. They can be used and re-used in various places. The three types of custom charts (line, bar and pie charts) provide model developers means for examining and developing their models and communicating the simulation results to others. <br />
<br />
Custom charts are created to the Charts folder in model browser.<br />
<br />
[[File:NewChart.png | Creating a new chart]]<br />
<br />
Charts are configured the same way as variables: first select the chart from model browser and then configure it in the property view. Charts can be viewed in the same active trend view as any variable by selecting the chart from model browser. In addition to trend view, charts can be populated directly to the model diagram or to a separate chart panel that can contain multiple charts. <br />
<br />
=== Line chart ===<br />
<br />
Line char 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.<br />
<br />
[[File:LineChart.png|Line chart with an array variable]]<br />
<br />
[[File:LineChartGeneral.png|General settings of line chart]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|The title of the chart. Displayed in the chart<br />
|-<br />
|Type<br />
|Line chart (default) or area chart<br />
|-<br />
|Hide<br />
|Options to hide chart grid, title or legend<br />
|-<br />
|'''X-axis'''<br />
|<br />
|-<br />
|Variable<br />
|A variable that is used as the x-axis variable. The default variable is time and it needs not to be typed in the field.<br />
|-<br />
|Label<br />
|Optional other label for the variable than its name<br />
|-<br />
|Min<br />
|Minimum value of the x-axis<br />
|-<br />
|Max<br />
|Maximum value of the x-axis<br />
|-<br />
|Hide<br />
|Options to hide x-axis lable, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
[[File:LineChartAxisAndVariables.png|Axis and variables settings of line chart]]<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed.<br />
|-<br />
|Color<br />
|Color for the lines of this variable<br />
|-<br />
|Line width<br />
|The width of the lines drawn for this variable<br />
|}<br />
There are also configuration options for y-axis. They are displayed when an axis is selected in the Axis and variables tab.<br />
{|<br />
|'''Y-axis'''<br />
|<br />
|-<br />
|Label<br />
|Label of the axis<br />
|-<br />
|Min<br />
|Minimum value in the axis<br />
|-<br />
|Max<br />
|Maximum value in the axis<br />
|-<br />
|Color<br />
|The color of the axis lines, ticks and labels<br />
|-<br />
|Hide<br />
|Options to hide parts of the axis: label, axis line, tick marks, tick labels<br />
|-<br />
|}<br />
<br />
=== Bar chart ===<br />
Bar charts display variables in a certain point in time. The point can be defined for the complete chart in cart'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. <br />
<br />
[[File:BarChartGeneral.png|General bar chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Name is displayed in model browser.<br />
|-<br />
|Title<br />
|The title of the chart. Title is displayed in the chart, if not hidden<br />
|-<br />
|Type<br />
|Normal or stacked. Normal type displays all variables in separate bars. Stacked mode is able to display one-dimensional array variables in stacks.<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Option for hiding grid, title and Legend. Legend is hidden by default since it only contains the information that the current simulation is displayed.<br />
|-<br />
|}<br />
<br />
[[File:BarChartInDiagram.png|Bar chart in a model diagram]]<br />
<br />
Charts can be added to model diagrams simply by dragging the chart from model browser to diagram.<br />
<br />
[[File:BarChartVariable.png|Settings for a variable in bar chart]]<br />
<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|}<br />
[[File:BarChartAxis.png|Settings for axis in bar chart]]<br />
{|<br />
|'''Domain axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for x axis<br />
|-<br />
|Label angle<br />
|Axis labels can be displayed in an angle. This value determines the angle in degrees.<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|'''Range axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for y axis<br />
|-<br />
|Min<br />
|Minimum value of y axis<br />
|-<br />
|Max<br />
|Maximum value of y axis<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
=== Pie chart ===<br />
<br />
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.<br />
<br />
[[File:PieChartGeneral.png|General pie chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|Title The title of the chart. Displayed in the chart<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Options for hiding title, section labels and legend<br />
|-<br />
|}<br />
<br />
[[File:PieChartVariable.png|Variable settings in pie chart]]<br />
{|<br />
|'''Variables'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Color<br />
|Color for the sector of this variable<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|Exploded<br />
|If set, the sector(s) of the variable(s) are "exploded" away from the center of the pie chart<br />
|-<br />
|}<br />
<br />
[[File:PieChartChartPanel.png|Pie chart in chart panel]]<br />
<br />
=== Chart panel ===<br />
[[File:ChartPanel.png|right]]<br />
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.<br />
<br />
Chart panel can be either horizontally or vertically oriented. Different orientations help in configuring the workbench perspective. <br />
<br />
[[File:ChartPanelOrientation.png|Chart panel orientation]]<br />
<br />
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.<br />
<br />
By default, chart panel is hidden in the upper-left corner of the system dynamics perspective.<br />
<br style="clear: both" /><br />
<br />
== Multidimensional variables ==<br />
<br />
<br />
=== Modeling ===<br />
<br />
Models with multidimensional variables look just like any other models. The structure of the models is replicated givin multiple indexes to variables. For users with programming background, notation Variable[] may be familiar. In system dynamic modeling we need to give names to the indexes. Instead of using numbers to define the indexes, like in normal programming, we use enumerations. The steps to create a model with multidimensional variables are as follows (with examples):<br />
<br />
# '''Create the model structure''' <BR />Model with multidimensional variables looks just like any other model.<BR /> [[File:ModelWithMultidimensionalVariables.png|300px|Model with multidimensional variables]]<br />
# '''Create Enumerations and define the indexes''' <BR />Enumerations are created by right-clicking configuration and selecting New->Enumeration.<BR /> [[File:NewEnumeration.png|250px|New enumeration]]<BR />Define enumeration indexes by adding as many indexes as you want. Rename the indexes by selecting them and then clicking on them again.<BR />[[File:DefineIndexes.png|200px|Index definitions]]<br />
# '''Add Enumerations for variables''' <BR />Select the variable that you want to be multidimensional. From the Indexes -tab in the property view, move the wanted enumerations to the right. The order of the enumerations does matter.[[File:SelectEnumerations.png|500px|Select enumerations for variables]]<br />
# '''Define equations for all possible indexes''' <BR />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 indexes, so the resulting definition can be {{1,2,3},{4,5,6},{7,8,9}}.<BR />[[File:DefineEquations.png|500px|Define equations for all indexes]]<br />
<br />
<br />
<br />
=== Expressions ===<br />
<br />
Values for all cells in the variable matrix can be defined in a single expression. <br />
<br />
[[File: DefineEquations.png|600px]]<br />
<br />
[[File:DefineEquations2.png|600px]]<br />
<br />
In many situations, it is however more clear to define separate expressions for each cell or blocks. <br />
<br />
# '''Define range for the expression'''<BR /> [[File:DefineRange.png]]<br />
# '''Define the expression''' (dimensions of the defined range and the result of the expression must match!) <BR /> [[File:DefineEquations3.png]]<br />
# '''Create a new expression''' <BR /> [[File:CreateNewExpression.png]]<br />
#''' Select the new expression''' <BR /> [[File:SelectNewExpression.png]]<br />
<br />
Repeat until there is value for each cell. There must be exactly one value for each cell.<br />
<br />
=== Array slices ===<br />
<br />
Many times it is useful to access a slice of a multidimensional variable. In this chapter, we will use the following example variable:<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
The whole variable can be accessed in three different ways:<br />
# Auxiliary<br />
# Auxiliary[E1, E2]<br />
# Auxiliary[:, :]<br />
<br />
The following explains different methods for accessing parts of the variable<br />
<br />
// Single cell<br />
Auxiliary[one, eins] = 1<br />
<br />
// Slices<br />
Auxiliary[one, E2] = {1,2,3}<br />
Auxiliary[E1, zwei] = {{2},{5},{8}}<br />
<br />
// In addition to single cells and the whole enumeration range, a subrange of the enumeration can be used<br />
Auxiliary[two : three, E2] = {{4,5,6},{7,8,9}}<br />
Auxiliary[one : two, zwei : drei] = {{2,3},{5,6}}<br />
<br />
The syntax for accessing parts of variables can be used in both expression range definitions and in expressions.<br />
<br />
=== Arithmetic Operators ===<br />
<br />
Arithmetic operations are defined in Modelica. Below are examples of different operations.<br />
<br />
;Addition and substraction<br />
Addition and substraction are calculated elementwise<br />
<br />
{1,2,3} - {0,2,3} = {1,0,0}<br />
{{2,2},{4,4}} + {{8,8},{1,1}} = {{10,10},{5,5}}<br />
{1,2,3} - {1,2} = ERROR! Different array sizes<br />
<br />
;Division<br />
Division with a scalar<br />
{5,10,15} / 5 = {1,2,3}<br />
5 / {5,10,15} = ERROR! not allowed<br />
<br />
Division with an array<br />
{1,2,3} / {1,2,3} = ERROR! not allowed<br />
<br />
// Elementwise<br />
{1,2,3} ./ {1,2,3} = {1,1,1}<br />
<br />
;Multiplication<br />
<br />
Multiplication with a scalar<br />
{1,2,3} * 2 = {2,4,6}<br />
5 * {1,2,3} = {5,10,15}<br />
<br />
Matrix multiplication with an array<br />
{{3,4},{5,6}} * {1,2} = {11,17}<br />
{{3,4},{5,6}} * {1,2,3} = ERROR! incompatible array sizes<br />
<br />
//Elementwise<br />
{1,2} .* {1,2} = {1,4}<br />
<br />
Real[3,2] c = {{1,2},{3,4},{5,6}}; <br />
Real[2,2] d = {{3,4},{5,6}};<br />
Real[2,2] cd;<br />
cd = c[2:3, :] .* d; // Result: {{9,16},{25,36}}<br />
<br />
=== Builtin Modelica functions ===<br />
<br />
Modelica has some builtin functions that help using multidimensional variables. This chapter introduces some of the builtin functions. <br />
<br />
;Dimension and size functions<br />
<br />
We will use the same example variable as previously.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
;ndims(A)<br />
The number of dimensions in array A<br />
ndims(Auxiliary) = 2<br />
<br />
;size(A, i)<br />
The size of dimension i in array A<br />
size(Auxiliary, 2) = 3<br />
<br />
;size(A)<br />
A vector of length ndims(A) containing the dimension sizes of A<br />
size(Auxiliary) = {3,3}<br />
<br />
<br />
;Construction functions<br />
In addition to normal array constructing, a special construction functions can be used.<br />
<br />
;zeros(n1,n2,n3,...)<br />
An array full of zeros with dimensions n1 x n2 x n2 x ... <br />
zeros(2, 2) = {{0,0}, {0,0}}<br />
<br />
;ones(n1,n2,n3,...)<br />
An array full of ones with dimensions n1 x n2 x n2 x ... <br />
ones(2, 2) = {{1,1}, {1,1}}<br />
<br />
;fill(s,n1,n2,n3)<br />
Like zeros() and ones(), but with user defined value (s) for array elements.<br />
fill(3,2,2) = {{3,3}, {3,3}}<br />
<br />
;identity(n)<br />
Creates an n x n integer identity matrix with ones on the diagonal and all other elements zero.<br />
identity(3) =<br />
1 0 0<br />
0 1 0<br />
0 0 1<br />
<br />
;diagonal(v)<br />
Constructs a square matrix with elements of vector v on the diagonal and all other elements zero.<br />
diagonal({1,2,3}) =<br />
1 0 0<br />
0 2 0<br />
0 0 3<br />
<br />
;linspace(x1,x2,n)<br />
Constracts a Real vector from x1 to x2 with n equally spaced elements.<br />
linspace(2,5,4) = {2,3,4,5}<br />
<br />
;Reduction functions<br />
<br />
Reduction functions reduce arrays to scalars.<br />
<br />
;min(A)<br />
Returns the minimum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
min(A) = 1<br />
<br />
;max(A)<br />
Returns the maximum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
max(A) = 4<br />
<br />
;sum(A)<br />
Returns the sum of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
sum(A) = 10 // 1 + 2 + 3 + 4<br />
<br />
;product(A)<br />
Returns the product of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
product(A) = 24 // 1 * 2 * 3 * 4<br />
<br />
<br />
;Using functions with iterators<br />
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.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
AuxiliarySum[E1] = {sum( Auxiliary[ i , E2 ] ) for i in E1} // Result: {6, 15, 24}<br />
<br />
/* Same as:<br />
{sum(Auxiliary[one, E2]), sum(Auxiliary[two, E2]), sum(Auxiliary[three, E2])}<br />
{sum({1,2,3}), sum({4,5,6}), sum({7,8,9})}<br />
*/<br />
<br />
One expression can have multiple iterators. The Modelica specification defines the following format, but it is NOT yet supported in OpenModelica:<br />
{sum(Array[ i, j, E3]) for i in E1, j in E2} // Dimensions reduced from 3 to 2<br />
<br />
To use multiple iterators, use the following format (NOTE the reversed order of iterators!):<br />
{{sum(Array[ i, j, E3]) for j in E2} for i in E1} // Dimensions reduced from 3 to 2<br />
<br />
The range doesn't have to be the whole enumeration. Subranges can also be used.<br />
{sum( Auxiliary[ i , eins : zwei ] ) for i in E1.one : E1.two} // Result: {3, 9}<br />
<br />
/* Same as<br />
{sum(Auxiliary[one, eins : zwei]), sum(Auxiliary[two, eins : zwei])}<br />
{sum({1,2}), sum({4,5})}<br />
*/<br />
<br />
=== Simulation results ===<br />
<br />
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. <br />
<br />
[[File:3x3trend.png|300px|Trend view for a 3x3 variable]]<br />
<br />
The clutter can be reduced by selecting which enumeration indexes are shown in charts. Select an enumeration and tick the indexes 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.<br />
<br />
[[File:ShowInCharts.png|500px|Select indexes to show in charts]]<br />
<br />
<br />
=== Array Variables in Modules ===<br />
<br />
[[File:Replaceable.png|frame|Replaceable enumeration inside a module]]<br />
<br />
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 [[Simantics_System_Dynamics#Modeling|Modeling]]). <br />
<br />
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.<br />
<br />
<br />
<br style="clear: both" /><br />
<br />
In this example, the original enumeration that the modeler used had two indexes. We are using an instance of this module, but we need to use array variables that have three indexes instead of two. We are using two variables and an instance of the module.<br />
<br />
[[File:ReplacingEnumerationConfiguration.png|frame|left|500px|Module configuration for replacing enumerations inside the module]]<br />
<br style="clear: both" /><br />
<br />
In the parent configuration, we have used an enumeration with three indexes in the two variables.<br />
<br />
[[File:Replacing.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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 clickin 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.<br />
<br />
<br />
[[File:ReplacingEnumeration.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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!<br />
<br />
== Functions ==<br />
<br />
Modelica provides a convenient way to use functions in your models. You can create your own functions, import complete function libraries and share function libraries to be used in all of your models. <br />
<br />
=== Creating functions ===<br />
<br />
[[File:NewFunction.png|right]]<br />
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.<br />
<br />
Functions that can be found from Functions -folder can be used in your variable definitions.<br />
<br />
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. <br />
<br />
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.<br />
<br />
Below is an example of a simple function. For more examples, see the built-in functions provided with the tool and [https://www.modelica.org/documents/ Modelica specifications].<br />
<br />
<br style="clear: both" /><br />
<br />
[[File:ExampleFunction.png]]<br />
<br />
=== Function libraries ===<br />
<br />
<br />
[[File:NewFunctionLibrary.png|right]]<br />
<br />
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)).<br />
<br />
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. <br />
<br />
Create a new function library by right-clicking on Functions folder, Shared functions folder or other module library.<br />
<br />
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.<br />
<br />
[[File:SharedFunctions.png]]<br />
<br style="clear: both" /><br />
<br />
=== External functions ===<br />
<br />
Modelica allows you to use external functions that are programmed using C language. Below is a simple example of using a function that returns the sum of two arguments. <br />
<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}<br />
<br />
<br />
[[File:ImportCFunctionLibrary.png|right]]<br />
<br />
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 <br />
(e.g. simantics_home/plugins/org.simantics.openmodelica.win32_x/MinGW/bin/mingw32_gcc.exe -g -O -c ExampleCFunctionCode.c). <br />
<br style="clear: both" /><br />
<br />
[[File:ExampleExternalFunction.png]]<br />
<br />
<br />
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.<br />
<br />
[[File:ExternalFunctionResult.png]]<br />
<br />
<br />
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.<br />
<br />
<br />
Small external C function can also be written directly to the function code in Simantics Sysdyn:<br />
function ExampleExternalFunction<br />
input Real x;<br />
input Real y;<br />
output Real z;<br />
external "C" z=exampleCFunction(x,y) annotation(Include="<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}");<br />
end ExampleExternalFunction;<br />
<br />
=== Modelica functions ===<br />
<br />
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 [[Simantics_System_Dynamics#Builtin_functions|builtin functions for arrays]].<br />
<br />
{|<br />
|abs(x)<br />
|Returns the absolute value of x. Expanded into "(if x >= 0 then x else -x)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|acos(x)<br />
|Inverse cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|asin(x)<br />
|Inverse sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan(x)<br />
|Inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan2(x1,x2)<br />
|four quadrant inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cat(n,A,B,...)<br />
|General concatenation function that concatenates arrays A,B,... along the nth dimension.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|ceil(x)<br />
|Returns the smallest integer not less than x, the closest integer above x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cos(x)<br />
|Cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cosh(x)<br />
|Hyperbolic cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cross(x,y)<br />
|Returns the 3-vector cross product of the 3-vectors x and y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|delay(expr, delayTime)<br />
|Returns the value of expr at the time time-delayTime. The value of expr is returned when time <= time.start + delayTime.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|der(x)<br />
|Time derivative of x. X must be have continuous-time variability.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|div(x, y)<br />
|Returns the algebraic quotient x/y with any fractional part discarted. E.g. div(10,3) = 3.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|edge(b)<br />
|Returns true when the value of the boolean expression b changes. Expanded into (b and not pre(b)).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|exp(x)<br />
|Exponential, base e.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|floor(x)<br />
|Returns the largest integer not greater than x, the closest integer below x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|initial()<br />
|Returns true at the beginning of the simulation. <br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|integer(x)<br />
|Returns the largest integer not greater than x as an integer.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log(x)<br />
|Natural logarithm. (base e, x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log10(x)<br />
|Base 10 logarithm. (x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|mod(x, y)<br />
|Returns the integer modulus of x/y: mod(x,y) = x - floor(x/y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|noEvent(expr)<br />
|noEvent around an expression causes the expression to NOT generate event.<br />
'''Important:''' <br />
:If you want a condition to be checked only on time steps, use noEvent.<br />
:(e.g. if noEvent(value >= 1) then ... else ...)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|pre(x)<br />
|Returns the preceding value of y from time event that has occured before current time.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|rem(x, y)<br />
|Returns the integer remainder of x/y: rem(x,y) = x - div(x,y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sample(start, interval)<br />
|Returns true and triggers time events at times start + i * interval (i=0,1,...).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sign(x)<br />
|Returns -1 if x is negative, 1 if x is positive. Expanded into "(if x > 0 then 1 else if x < 0 then -1 else 0)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sin(x)<br />
|Sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sinh(x)<br />
|Hyperbolic sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sqrt(x)<br />
|Square root of x. The value of x must be greater or equal to 0 or an assertion error occurs.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tan(x)<br />
|Tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tanh(x)<br />
|Hyperbolic tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|terminal()<br />
|Returns true at the end of a successful simulation.<br />
|}<br />
<br />
== Spreadsheets ==<br />
<br />
<center><br />
[[Simantics]] | ''System Dynamics Modelling''<br />
</center><br />
<br />
----<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Basic System Dynamics Modelling]]'''<br><br />
System dynamics modelling in Simantics is a free modelling tool that is included into the basic installation. This tutorial introduces the basic features of the system dynamics modelling tool.<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Advanced System Dynamics Modelling]]'''<br><br />
This tutorial introduces the more advanced features of the system dynamics modelling tool: Modules and Operating interfaces<br />
<br />
[[Category: Simantics System Dynamics]]</div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=Simantics_System_Dynamics&diff=557Simantics System Dynamics2012-06-04T11:34:47Z<p>Teemu Lempinen: /* Chart panel */</p>
<hr />
<div>== Simantics System Dynamics ==<br />
<br />
Simantics System Dynamics is currently the only open source modelling and simulating tool for Simantics. Simantics System Dynamics is under development and will go through some changes in the future. New features will be added and old ones improved according to the needs of the modellers. New features include module libraries and different analysis tools.<br />
<br />
This documentation introduces you to the current version of Simantics System Dynamics. Documentation includes the basic modelling principles and a guide on how to model system dynamics models with Simantics System Dynamics. If you like to get to know the tool better and try modelling and simulating yourself, [[#Installation Instructions|install]] the software and try our [[Tutorial: Basic System Dynamics Modelling|basic]] and [[Tutorial: Advanced System Dynamics Modelling|advanced]] tutorials!<br />
<br />
== Introduction to System Dynamics Simulation ==<br />
<br />
===System Dynamics===<br />
System dynamics is an approach to understanding different organizations, markets and other complex systems and their dynamic behavior. System dynamics modelling in Simantics is a free modelling tool. See [[#Installation Instructions|installation instructions]].<br />
<br />
===Model===<br />
[[File:ModelStructure.png|right|thumb|Model structure]]<br />
System dynamics model is generally understood as the model configuration. In this tool, the model contains also other components. Model can have Operating interfaces that enable the use of the model with simple controls. Operating interfaces are configured separately and when using them, the complex model is hidden from the user. Experiments are the way to simulate the model. In the future, you can have experiments with different configurations, for example different initial values for some parameters. In that way, you don't have to always configure the model for different scenarios. Modules folder contains all the different module types in your model and you can create new module types there. <br />
<br />
<br style="clear: both" /><br />
<br />
===Components===<br />
Most of the components you can use in your models are basic system dynamics components. The modularity of the models introduces two additional components, Modules and Inputs. All the components are explained below.<br />
[[File:ComponentTypes.png|right|frame|Component types]]<br />
;Auxiliary<br />
:Auxiliary is the most basic variable you can use. It represents a single value or a mathematical expression. There are different types of auxiliary variables currently in the system: Auxiliary, Parameter, Constant and WithLookup. Auxiliary is the default type. Parameters are single values that the user can change. When only parameters are changed, the model simulates faster, because the system does not have to recompile the model. WithLookup is a special variable that has an expression and a lookup table. The expresssion defines what value is taken from the defined table.<br />
;Dependency<br />
:Dependency is an arrow that connects two components. It means that the value of the variable from which the arrow starts is used to calculate the value of the variable where the arrow ends.<br />
;Flow<br />
:Flow connects clouds, valves and stocks. Flow represents an actual flow of something from stocks or clouds to stocks or clouds. There has to be at least one valve in a flow and the system creates it automatically, if none of the ends of the flow is a valve.<br />
;Valve<br />
:Valve regulates the rate of a flow. The value of a valve is automatically used in calculating the level of an adjacent stock. Valves behave just like Auxiliary variables but look different and you can connect also flows to them.<br />
;Stock<br />
:The value of a stock variable is an integral of flows leaving and flows arriving to the variable. The integral is calculated automatically from the valves that are connected to the variable with flow connections. You must give an initial value to the stock. Initial value can be a single value or an equation. You can use values of other variables to calculate the initial value.<br />
;Cloud<br />
:Cloud is not a variable. It represents a starting or ending point of a flow, if it is not in the scope of the model.<br />
;Module<br />
:Modules enable structural modeling. Modules are defined just like the basic model configuration, but the module component hides the actual configuration. You can only connect dependency connections into the module and dependency connections from the module must end to Input variables. The interface of the module is defined using input and output variables in the configuration of the module. All variable types can be set as output variables. If a variable is an output variable, its font is bold.<br />
;Input<br />
:Input variables are the way of getting values from other modules. Inputs look like auxiliary variables except their font is italics. You can set a default value to the input variable in case it is not connected to any variable. Connections are made from the modules properties, when the module is populated. Input doesn't have to be connected with an arrow to a module. If the variable has no connections, it can get values from a higher level in the hierarchy. If an input is connected to an output, the output and its module are shown below the variable using dot notation.<br />
<br style="clear: both" /><br />
<br />
===Modeling principles===<br />
<br />
System dynamics modelling is much more than just mathematical formulas and nice graphs. Models are ways of communicating. There are some basic principles in system dynamics modelling that make the models easier to read and understand. You do not have to apply these principles to simulate models, but using them makes it easier for you to communicate your model to others.<br />
<br />
;Variable names<br />
:Variables names should be nouns, not verbs. The names should be positive: for example it is easier to understand that satisfaction decreases than dissatisfaction rises. <br />
<br />
:Variable names can and should have multiple words, if they are needed. Unfortunately current version of the tool does not support spaces in variable names. A good practice is to use CamelCase if name contains multiple words. This means that you start every word woth a capital letter (example: ExampleVariable).<br />
<br />
;Connections<br />
:You should try to avoid overlapping dependency arrows. In some situations, however, it is not possible. Dependencies should also form distinctive loops, if there is a loop. It makes it easier to read and understand the model and its behavior.<br />
<br />
;Graphical annotations<br />
:System dynamics contains usually annotations for loops, polarities, delays and so on. Currently those annotations are not supported, but the support will be added later. Annotations are important, again, for communicating the behavior of the model.<br />
<br />
==Installation Instructions==<br />
<br />
System dynamics tool is a provided with the Simantics platform.<br />
<br />
# [https://www.simantics.org/simantics/download Download installer from Simantics download page]<br />
# Install the program to a directory without spaces. <br />
# Run Simantics-Sysdyn.exe <br /><br />
: (Default path in windows: C:\Simantics\Sysdyn\1.4\simantics-sysdyn\Simantics-Sysdyn.exe)<br />
<br />
[http://www.openmodelica.org/ OpenModelica] is used to build and simulate the models. Simantics platform has integrated OpenModelica 1.7 for Windows environments. For other versions and other environments you need to install [http://www.openmodelica.org/index.php/download OpenModelica].<br />
<br />
== Workbench ==<br />
<br />
[[File:BasicWorkbench.png|center|729px]]<br />
<br />
<br />
# '''Diagram''' <br /> Diagram is the area where you will graphically modify your model. Diagrams are built from elements that can be dragged from Symbols view or populated using shortcut keys. <br />
# '''Model Browser''' <br /> Model browser shows the structure of your model and all items related to it. <br /> Symbols view is stacked with the model browser and used for dragging elements to diagrams.<br />
# '''Properties''' <br /> Property view shows the selected variable's properties. Property view has a different layout depending on the type of the selected component. The view can also have different tabs depending on the component type. Basic tabs are with variables are Equation and Additional information.<br />
# '''Trend''' <br /> Trend view shows the graphical representation of the values of the selected value over time. For the trend to be shown, a simulation has to be run. The view shows always the results of the latest run, but you can save results of a simulation and show them in the same trend with results from another simulation. Values view and Dependencies are stacked with Trend view and can also be used for analyzing the model.<br />
# '''Experiment controls''' <br /> Experiment controls are shown when an experiment is active. Experiment is activated by double clicking an experiment in the model browser. With the experiment control, you can start simulation runs and save simulation results.<br />
<br />
<br /><br />
If you accidentally close a view, you can reopen them from Window->Show View->Other...<br />
<br />
== Modelling ==<br />
<br />
===Basic modelling===<br />
<br />
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.<br />
<br />
[[File:Basic_1.png|right]]<br />
;Creating a new model<br />
:Start a new model by right-clicking the model browser and selecting New->Model or from the main menu File->New Model.<br />
<br style="clear: both" /><br />
<br />
[[File:Basic_2.png|right]]<br />
;Creating a new module type<br />
:Create a new module type by right-clicking on the Modules-folder and selecting New->Module. This creates a new module type that you can populate to your other modules and the model configuration. <br />
<br style="clear: both" /><br />
<br />
;Configuring a model<br />
:Model configuration can be opened by double clicking Configuration in the model browser. <br />
<br />
;Configuring modules<br />
: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 module!<br />
<br />
;Populate variables<br />
:You can drag variables to a diagram from symbol view. You can also populate variables using [[#Shortcut and control keys|shortcut keys]]<br />
<br />
;Populate modules<br />
:Modules are populated from the model browser. Just drag the module you want to populate from the Modules folder to a diagram.<br />
<br />
;Create connections<br />
: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.<br />
: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.<br />
: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.<br />
<br />
;Connections between modules<br />
:'''Outside the module''' <br /><br />
:You can connect variables to variables in modules like this:<br />
MODULE -----> INPUT<br />
or<br />
ANY VARIABLE -----> MODULE <br />
:This is just the visual configuration, but you need those connections to really connect variables in the module's properties.<br />
:In Inputs -tab you select which variables you connect to inputs inside the module. In Outputs -tab you select which variables you lift from the module to inputs outside it.<br />
<br />
:'''Inside the module''' <br /><br />
:Input variables get values from outside the module<br />
<br />
:Output variables can send their values outside the module. From the variable properties, select Additional Information and press Is Output<br />
<br />
;Configure variables<br />
:Select a single variable from diagram or model browser. The properties of the variables are shown in the equation view and you can modify them.<br />
<br />
;Export model<br />
: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 to for example create different versions of the model, create backups or to transport it to another database.<br />
<br />
;Import model<br />
:Right-click on the model browser and select Import->Model. Browse to your .tg file and select open. The model is added to your model browser.<br />
<br />
===Shortcut and control keys===<br />
<br />
Shortcut keys for configuring a model on diagram.<br />
<br />
{|<br />
|Esc <br />
|Cancel operations (e.g. connection and rename).<br />
|-<br />
|Shift + A <br />
|Hover Auxiliary at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + S<br />
|Hover Stock at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + C<br />
|Hover Cloud at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + V<br />
|Hover Valve at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + I<br />
|Hover Input at the cursor position, populate with left mouse button.<br />
|-<br />
|Alt + left mouse button<br />
|Start an arrow from a variable. End to another variable by clicking left mouse button.<br />
|-<br />
|Alt + right mouse button<br />
|Start flow from a variable. End by clicking left mouse button.<br />
<br />
If a flow is not started or ended on to a variable, a cloud will be created to that end. <br /><br />
If a new flow does not have a valve at either end, a valve will be created in the middle of the flow.<br />
|-<br />
|Delete<br />
|Remove selected variables<br />
|-<br />
|Ctrl + left mouse button<br />
|Select multiple variables<br />
|-<br />
|Mouse wheel or<br/>+ and -<br />
|Diagram zoom<br />
|-<br />
|drag(mouse3) or<br/>drag(shift + any mouse button)<br />
|Diagram pan<br />
|-<br />
|Ctrl + C<br />
|Copy selected elements<br />
|-<br />
|Ctrl + X<br />
|Cut selected elements<br />
|-<br />
|Ctrl + V<br />
|Paste copied or cut elements<br />
|-<br />
|G<br />
|Show / hide grid<br />
|-<br />
|R<br />
|Show / hide ruler<br />
|}<br />
<br />
Other shortcut keys can be found selecting Window -> Preferences from the main menu. Keys are located in General -> Keys.<br />
<br />
== Simulation ==<br />
There are three different ways for simulating a model. Different simulations are represented as different types of experiments in Simantics System Dynamics. <br />
<br />
Experiments are created from the context menu of experiments folder in a model. <br />
<br />
[[File:NewExperiment.png]]<br />
<br />
Double-click on an experiment activates it and displays experiment type specific controls in the main tool bar.<br />
<br />
;Normal simulation<br />
: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.<br />
<br />
;Game simulation<br />
:Game simulations allow simulating an arbitrary number of steps, changing parameter values and continuing simulation with the new values from where it previously ended.<br />
<br />
;Simulation playback<br />
:Simulation playback works essentially as the basic experiment, but it offers some additional visualization options.<br />
<br />
== Simulation result and model structure analysis ==<br />
Simulation results can be viewed as trends in trend view or as plain numbers in values view. The views display results of variables that are selected in the workbench. Users can also create [[#Custom charts |custom charts]].<br />
<br />
Model structure can be examined in the Structure view. There are two options: Dependency structures of individual variables or the complete hierarchy structure of the model.<br />
<br />
;Trend<br />
:Shows you the values of the selected variable(s) graphically over the simulation time. You can modify the trend and zoom it using the context menu (right-click) of the trend. <br /> [[File:Trend.png]]<br />
<br />
;Values<br />
:Shows you the values of the selected variable(s) in a table form. If the value has a star (*) at the end, it means that the value is an approximate. There is no value for that variable for the given time step. Selected values can be copied to other software in csv format.<br /> [[File:Values.png]]<br />
<br />
;Compare results<br />
:You can compare different results of the same model by saving simulation results and displaying the saved results side by side with other results. You can save your results after simulating by clicking the save button [[File:Saveresults.png]] on your experiment controls. The saved results appear to model browser under the active experiment. To show the results on trends and tables, right-click on the result and select Show on charts. <br /> [[File:CompareTrend.png]]<br />
<br />
;Dependencies<br />
:Dependencies display which variables affect and which are affected by the selected variable. The direction and number of steps that are traveled from the selected variable can be configured at the bottom of the view. <br /> [[File:Dependencies.png]]<br />
<br />
;Model Hierarchy<br />
:Model Hierarchy displays the hierarchical structure of the model. The module type where a selected variable is located is highlighted.<br /> [[File:ModelHierarchy.png]]<br />
<br />
== Custom charts ==<br />
Custom charts are user-defined displays of simulation result data. They can be used and re-used in various places. The three types of custom charts (line, bar and pie charts) provide model developers means for examining and developing their models and communicating the simulation results to others. <br />
<br />
Custom charts are created to the Charts folder in model browser.<br />
<br />
[[File:NewChart.png | Creating a new chart]]<br />
<br />
Charts are configured the same way as variables: first select the chart from model browser and then configure it in the property view. Charts can be viewed in the same active trend view as any variable by selecting the chart from model browser. In addition to trend view, charts can be populated directly to the model diagram or to a separate chart panel that can contain multiple charts. <br />
<br />
=== Line chart ===<br />
<br />
Line char 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.<br />
<br />
[[File:LineChart.png|Line chart with an array variable]]<br />
<br />
[[File:LineChartGeneral.png|General settings of line chart]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|The title of the chart. Displayed in the chart<br />
|-<br />
|Type<br />
|Line chart (default) or area chart<br />
|-<br />
|Hide<br />
|Options to hide chart grid, title or legend<br />
|-<br />
|'''X-axis'''<br />
|<br />
|-<br />
|Variable<br />
|A variable that is used as the x-axis variable. The default variable is time and it needs not to be typed in the field.<br />
|-<br />
|Label<br />
|Optional other label for the variable than its name<br />
|-<br />
|Min<br />
|Minimum value of the x-axis<br />
|-<br />
|Max<br />
|Maximum value of the x-axis<br />
|-<br />
|Hide<br />
|Options to hide x-axis lable, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
[[File:LineChartAxisAndVariables.png|Axis and variables settings of line chart]]<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed.<br />
|-<br />
|Color<br />
|Color for the lines of this variable<br />
|-<br />
|Line width<br />
|The width of the lines drawn for this variable<br />
|}<br />
There are also configuration options for y-axis. They are displayed when an axis is selected in the Axis and variables tab.<br />
{|<br />
|'''Y-axis'''<br />
|<br />
|-<br />
|Label<br />
|Label of the axis<br />
|-<br />
|Min<br />
|Minimum value in the axis<br />
|-<br />
|Max<br />
|Maximum value in the axis<br />
|-<br />
|Color<br />
|The color of the axis lines, ticks and labels<br />
|-<br />
|Hide<br />
|Options to hide parts of the axis: label, axis line, tick marks, tick labels<br />
|-<br />
|}<br />
<br />
=== Bar chart ===<br />
Bar charts display variables in a certain point in time. The point can be defined for the complete chart in cart'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. <br />
<br />
[[File:BarChartGeneral.png|General bar chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Name is displayed in model browser.<br />
|-<br />
|Title<br />
|The title of the chart. Title is displayed in the chart, if not hidden<br />
|-<br />
|Type<br />
|Normal or stacked. Normal type displays all variables in separate bars. Stacked mode is able to display one-dimensional array variables in stacks.<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Option for hiding grid, title and Legend. Legend is hidden by default since it only contains the information that the current simulation is displayed.<br />
|-<br />
|}<br />
<br />
[[File:BarChartInDiagram.png|Bar chart in a model diagram]]<br />
<br />
Charts can be added to model diagrams simply by dragging the chart from model browser to diagram.<br />
<br />
[[File:BarChartVariable.png|Settings for a variable in bar chart]]<br />
<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|}<br />
[[File:BarChartAxis.png|Settings for axis in bar chart]]<br />
{|<br />
|'''Domain axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for x axis<br />
|-<br />
|Label angle<br />
|Axis labels can be displayed in an angle. This value determines the angle in degrees.<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|'''Range axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for y axis<br />
|-<br />
|Min<br />
|Minimum value of y axis<br />
|-<br />
|Max<br />
|Maximum value of y axis<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
=== Pie chart ===<br />
<br />
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.<br />
<br />
[[File:PieChartGeneral.png|General pie chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|Title The title of the chart. Displayed in the chart<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Options for hiding title, section labels and legend<br />
|-<br />
|}<br />
<br />
[[File:PieChartVariable.png|Variable settings in pie chart]]<br />
{|<br />
|'''Variables'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Color<br />
|Color for the sector of this variable<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|Exploded<br />
|If set, the sector(s) of the variable(s) are "exploded" away from the center of the pie chart<br />
|-<br />
|}<br />
<br />
[[File:PieChartChartPanel.png|Pie chart in chart panel]]<br />
<br />
=== Chart panel ===<br />
[[File:ChartPanel.png|right]]<br />
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.<br />
<br />
Chart panel can be either horizontally or vertically oriented. Different orientations help in configuring the workbench perspective. <br />
<br />
[[File:ChartPanelOrientation.png|Chart panel orientation]]<br />
<br />
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.<br />
<br />
By default, chart panel is hidden in the upper-left corner of the system dynamics perspective.<br />
<br style="clear: both" /><br />
<br />
== Multidimensional variables ==<br />
<br />
<br />
=== Modeling ===<br />
<br />
Models with multidimensional variables look just like any other models. The structure of the models is replicated givin multiple indexes to variables. For users with programming background, notation Variable[] may be familiar. In system dynamic modeling we need to give names to the indexes. Instead of using numbers to define the indexes, like in normal programming, we use enumerations. The steps to create a model with multidimensional variables are as follows (with examples):<br />
<br />
# '''Create the model structure''' <BR />Model with multidimensional variables looks just like any other model.<BR /> [[File:ModelWithMultidimensionalVariables.png|300px|Model with multidimensional variables]]<br />
# '''Create Enumerations and define the indexes''' <BR />Enumerations are created by right-clicking configuration and selecting New->Enumeration.<BR /> [[File:NewEnumeration.png|250px|New enumeration]]<BR />Define enumeration indexes by adding as many indexes as you want. Rename the indexes by selecting them and then clicking on them again.<BR />[[File:DefineIndexes.png|200px|Index definitions]]<br />
# '''Add Enumerations for variables''' <BR />Select the variable that you want to be multidimensional. From the Indexes -tab in the property view, move the wanted enumerations to the right. The order of the enumerations does matter.[[File:SelectEnumerations.png|500px|Select enumerations for variables]]<br />
# '''Define equations for all possible indexes''' <BR />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 indexes, so the resulting definition can be {{1,2,3},{4,5,6},{7,8,9}}.<BR />[[File:DefineEquations.png|500px|Define equations for all indexes]]<br />
<br />
<br />
<br />
=== Expressions ===<br />
<br />
Values for all cells in the variable matrix can be defined in a single expression. <br />
<br />
[[File: DefineEquations.png|600px]]<br />
<br />
[[File:DefineEquations2.png|600px]]<br />
<br />
In many situations, it is however more clear to define separate expressions for each cell or blocks. <br />
<br />
# '''Define range for the expression'''<BR /> [[File:DefineRange.png]]<br />
# '''Define the expression''' (dimensions of the defined range and the result of the expression must match!) <BR /> [[File:DefineEquations3.png]]<br />
# '''Create a new expression''' <BR /> [[File:CreateNewExpression.png]]<br />
#''' Select the new expression''' <BR /> [[File:SelectNewExpression.png]]<br />
<br />
Repeat until there is value for each cell. There must be exactly one value for each cell.<br />
<br />
=== Array slices ===<br />
<br />
Many times it is useful to access a slice of a multidimensional variable. In this chapter, we will use the following example variable:<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
The whole variable can be accessed in three different ways:<br />
# Auxiliary<br />
# Auxiliary[E1, E2]<br />
# Auxiliary[:, :]<br />
<br />
The following explains different methods for accessing parts of the variable<br />
<br />
// Single cell<br />
Auxiliary[one, eins] = 1<br />
<br />
// Slices<br />
Auxiliary[one, E2] = {1,2,3}<br />
Auxiliary[E1, zwei] = {{2},{5},{8}}<br />
<br />
// In addition to single cells and the whole enumeration range, a subrange of the enumeration can be used<br />
Auxiliary[two : three, E2] = {{4,5,6},{7,8,9}}<br />
Auxiliary[one : two, zwei : drei] = {{2,3},{5,6}}<br />
<br />
The syntax for accessing parts of variables can be used in both expression range definitions and in expressions.<br />
<br />
=== Arithmetic Operators ===<br />
<br />
Arithmetic operations are defined in Modelica. Below are examples of different operations.<br />
<br />
;Addition and substraction<br />
Addition and substraction are calculated elementwise<br />
<br />
{1,2,3} - {0,2,3} = {1,0,0}<br />
{{2,2},{4,4}} + {{8,8},{1,1}} = {{10,10},{5,5}}<br />
{1,2,3} - {1,2} = ERROR! Different array sizes<br />
<br />
;Division<br />
Division with a scalar<br />
{5,10,15} / 5 = {1,2,3}<br />
5 / {5,10,15} = ERROR! not allowed<br />
<br />
Division with an array<br />
{1,2,3} / {1,2,3} = ERROR! not allowed<br />
<br />
// Elementwise<br />
{1,2,3} ./ {1,2,3} = {1,1,1}<br />
<br />
;Multiplication<br />
<br />
Multiplication with a scalar<br />
{1,2,3} * 2 = {2,4,6}<br />
5 * {1,2,3} = {5,10,15}<br />
<br />
Matrix multiplication with an array<br />
{{3,4},{5,6}} * {1,2} = {11,17}<br />
{{3,4},{5,6}} * {1,2,3} = ERROR! incompatible array sizes<br />
<br />
//Elementwise<br />
{1,2} .* {1,2} = {1,4}<br />
<br />
Real[3,2] c = {{1,2},{3,4},{5,6}}; <br />
Real[2,2] d = {{3,4},{5,6}};<br />
Real[2,2] cd;<br />
cd = c[2:3, :] .* d; // Result: {{9,16},{25,36}}<br />
<br />
=== Builtin Modelica functions ===<br />
<br />
Modelica has some builtin functions that help using multidimensional variables. This chapter introduces some of the builtin functions. <br />
<br />
;Dimension and size functions<br />
<br />
We will use the same example variable as previously.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
;ndims(A)<br />
The number of dimensions in array A<br />
ndims(Auxiliary) = 2<br />
<br />
;size(A, i)<br />
The size of dimension i in array A<br />
size(Auxiliary, 2) = 3<br />
<br />
;size(A)<br />
A vector of length ndims(A) containing the dimension sizes of A<br />
size(Auxiliary) = {3,3}<br />
<br />
<br />
;Construction functions<br />
In addition to normal array constructing, a special construction functions can be used.<br />
<br />
;zeros(n1,n2,n3,...)<br />
An array full of zeros with dimensions n1 x n2 x n2 x ... <br />
zeros(2, 2) = {{0,0}, {0,0}}<br />
<br />
;ones(n1,n2,n3,...)<br />
An array full of ones with dimensions n1 x n2 x n2 x ... <br />
ones(2, 2) = {{1,1}, {1,1}}<br />
<br />
;fill(s,n1,n2,n3)<br />
Like zeros() and ones(), but with user defined value (s) for array elements.<br />
fill(3,2,2) = {{3,3}, {3,3}}<br />
<br />
;identity(n)<br />
Creates an n x n integer identity matrix with ones on the diagonal and all other elements zero.<br />
identity(3) =<br />
1 0 0<br />
0 1 0<br />
0 0 1<br />
<br />
;diagonal(v)<br />
Constructs a square matrix with elements of vector v on the diagonal and all other elements zero.<br />
diagonal({1,2,3}) =<br />
1 0 0<br />
0 2 0<br />
0 0 3<br />
<br />
;linspace(x1,x2,n)<br />
Constracts a Real vector from x1 to x2 with n equally spaced elements.<br />
linspace(2,5,4) = {2,3,4,5}<br />
<br />
;Reduction functions<br />
<br />
Reduction functions reduce arrays to scalars.<br />
<br />
;min(A)<br />
Returns the minimum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
min(A) = 1<br />
<br />
;max(A)<br />
Returns the maximum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
max(A) = 4<br />
<br />
;sum(A)<br />
Returns the sum of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
sum(A) = 10 // 1 + 2 + 3 + 4<br />
<br />
;product(A)<br />
Returns the product of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
product(A) = 24 // 1 * 2 * 3 * 4<br />
<br />
<br />
;Using functions with iterators<br />
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.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
AuxiliarySum[E1] = {sum( Auxiliary[ i , E2 ] ) for i in E1} // Result: {6, 15, 24}<br />
<br />
/* Same as:<br />
{sum(Auxiliary[one, E2]), sum(Auxiliary[two, E2]), sum(Auxiliary[three, E2])}<br />
{sum({1,2,3}), sum({4,5,6}), sum({7,8,9})}<br />
*/<br />
<br />
One expression can have multiple iterators. The Modelica specification defines the following format, but it is NOT yet supported in OpenModelica:<br />
{sum(Array[ i, j, E3]) for i in E1, j in E2} // Dimensions reduced from 3 to 2<br />
<br />
To use multiple iterators, use the following format (NOTE the reversed order of iterators!):<br />
{{sum(Array[ i, j, E3]) for j in E2} for i in E1} // Dimensions reduced from 3 to 2<br />
<br />
The range doesn't have to be the whole enumeration. Subranges can also be used.<br />
{sum( Auxiliary[ i , eins : zwei ] ) for i in E1.one : E1.two} // Result: {3, 9}<br />
<br />
/* Same as<br />
{sum(Auxiliary[one, eins : zwei]), sum(Auxiliary[two, eins : zwei])}<br />
{sum({1,2}), sum({4,5})}<br />
*/<br />
<br />
=== Simulation results ===<br />
<br />
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. <br />
<br />
[[File:3x3trend.png|300px|Trend view for a 3x3 variable]]<br />
<br />
The clutter can be reduced by selecting which enumeration indexes are shown in charts. Select an enumeration and tick the indexes 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.<br />
<br />
[[File:ShowInCharts.png|500px|Select indexes to show in charts]]<br />
<br />
<br />
=== Array Variables in Modules ===<br />
<br />
[[File:Replaceable.png|frame|Replaceable enumeration inside a module]]<br />
<br />
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 [[Simantics_System_Dynamics#Modeling|Modeling]]). <br />
<br />
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.<br />
<br />
<br />
<br style="clear: both" /><br />
<br />
In this example, the original enumeration that the modeler used had two indexes. We are using an instance of this module, but we need to use array variables that have three indexes instead of two. We are using two variables and an instance of the module.<br />
<br />
[[File:ReplacingEnumerationConfiguration.png|frame|left|500px|Module configuration for replacing enumerations inside the module]]<br />
<br style="clear: both" /><br />
<br />
In the parent configuration, we have used an enumeration with three indexes in the two variables.<br />
<br />
[[File:Replacing.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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 clickin 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.<br />
<br />
<br />
[[File:ReplacingEnumeration.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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!<br />
<br />
== Functions ==<br />
<br />
Modelica provides a convenient way to use functions in your models. You can create your own functions, import complete function libraries and share function libraries to be used in all of your models. <br />
<br />
=== Creating functions ===<br />
<br />
[[File:NewFunction.png|right]]<br />
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.<br />
<br />
Functions that can be found from Functions -folder can be used in your variable definitions.<br />
<br />
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. <br />
<br />
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.<br />
<br />
Below is an example of a simple function. For more examples, see the built-in functions provided with the tool and [https://www.modelica.org/documents/ Modelica specifications].<br />
<br />
<br style="clear: both" /><br />
<br />
[[File:ExampleFunction.png]]<br />
<br />
=== Function libraries ===<br />
<br />
<br />
[[File:NewFunctionLibrary.png|right]]<br />
<br />
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)).<br />
<br />
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. <br />
<br />
Create a new function library by right-clicking on Functions folder, Shared functions folder or other module library.<br />
<br />
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.<br />
<br />
[[File:SharedFunctions.png]]<br />
<br style="clear: both" /><br />
<br />
=== External functions ===<br />
<br />
Modelica allows you to use external functions that are programmed using C language. Below is a simple example of using a function that returns the sum of two arguments. <br />
<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}<br />
<br />
<br />
[[File:ImportCFunctionLibrary.png|right]]<br />
<br />
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 <br />
(e.g. simantics_home/plugins/org.simantics.openmodelica.win32_x/MinGW/bin/mingw32_gcc.exe -g -O -c ExampleCFunctionCode.c). <br />
<br style="clear: both" /><br />
<br />
[[File:ExampleExternalFunction.png]]<br />
<br />
<br />
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.<br />
<br />
[[File:ExternalFunctionResult.png]]<br />
<br />
<br />
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.<br />
<br />
<br />
Small external C function can also be written directly to the function code in Simantics Sysdyn:<br />
function ExampleExternalFunction<br />
input Real x;<br />
input Real y;<br />
output Real z;<br />
external "C" z=exampleCFunction(x,y) annotation(Include="<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}");<br />
end ExampleExternalFunction;<br />
<br />
=== Modelica functions ===<br />
<br />
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 [[Simantics_System_Dynamics#Builtin_functions|builtin functions for arrays]].<br />
<br />
{|<br />
|abs(x)<br />
|Returns the absolute value of x. Expanded into "(if x >= 0 then x else -x)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|acos(x)<br />
|Inverse cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|asin(x)<br />
|Inverse sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan(x)<br />
|Inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan2(x1,x2)<br />
|four quadrant inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cat(n,A,B,...)<br />
|General concatenation function that concatenates arrays A,B,... along the nth dimension.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|ceil(x)<br />
|Returns the smallest integer not less than x, the closest integer above x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cos(x)<br />
|Cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cosh(x)<br />
|Hyperbolic cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cross(x,y)<br />
|Returns the 3-vector cross product of the 3-vectors x and y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|delay(expr, delayTime)<br />
|Returns the value of expr at the time time-delayTime. The value of expr is returned when time <= time.start + delayTime.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|der(x)<br />
|Time derivative of x. X must be have continuous-time variability.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|div(x, y)<br />
|Returns the algebraic quotient x/y with any fractional part discarted. E.g. div(10,3) = 3.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|edge(b)<br />
|Returns true when the value of the boolean expression b changes. Expanded into (b and not pre(b)).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|exp(x)<br />
|Exponential, base e.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|floor(x)<br />
|Returns the largest integer not greater than x, the closest integer below x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|initial()<br />
|Returns true at the beginning of the simulation. <br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|integer(x)<br />
|Returns the largest integer not greater than x as an integer.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log(x)<br />
|Natural logarithm. (base e, x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log10(x)<br />
|Base 10 logarithm. (x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|mod(x, y)<br />
|Returns the integer modulus of x/y: mod(x,y) = x - floor(x/y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|noEvent(expr)<br />
|noEvent around an expression causes the expression to NOT generate event.<br />
'''Important:''' <br />
:If you want a condition to be checked only on time steps, use noEvent.<br />
:(e.g. if noEvent(value >= 1) then ... else ...)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|pre(x)<br />
|Returns the preceding value of y from time event that has occured before current time.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|rem(x, y)<br />
|Returns the integer remainder of x/y: rem(x,y) = x - div(x,y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sample(start, interval)<br />
|Returns true and triggers time events at times start + i * interval (i=0,1,...).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sign(x)<br />
|Returns -1 if x is negative, 1 if x is positive. Expanded into "(if x > 0 then 1 else if x < 0 then -1 else 0)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sin(x)<br />
|Sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sinh(x)<br />
|Hyperbolic sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sqrt(x)<br />
|Square root of x. The value of x must be greater or equal to 0 or an assertion error occurs.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tan(x)<br />
|Tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tanh(x)<br />
|Hyperbolic tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|terminal()<br />
|Returns true at the end of a successful simulation.<br />
|}<br />
<br />
<br />
<center><br />
[[Simantics]] | ''System Dynamics Modelling''<br />
</center><br />
<br />
----<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Basic System Dynamics Modelling]]'''<br><br />
System dynamics modelling in Simantics is a free modelling tool that is included into the basic installation. This tutorial introduces the basic features of the system dynamics modelling tool.<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Advanced System Dynamics Modelling]]'''<br><br />
This tutorial introduces the more advanced features of the system dynamics modelling tool: Modules and Operating interfaces<br />
<br />
[[Category: Simantics System Dynamics]]</div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=Simantics_System_Dynamics&diff=556Simantics System Dynamics2012-06-04T11:33:30Z<p>Teemu Lempinen: /* Chart panel */</p>
<hr />
<div>== Simantics System Dynamics ==<br />
<br />
Simantics System Dynamics is currently the only open source modelling and simulating tool for Simantics. Simantics System Dynamics is under development and will go through some changes in the future. New features will be added and old ones improved according to the needs of the modellers. New features include module libraries and different analysis tools.<br />
<br />
This documentation introduces you to the current version of Simantics System Dynamics. Documentation includes the basic modelling principles and a guide on how to model system dynamics models with Simantics System Dynamics. If you like to get to know the tool better and try modelling and simulating yourself, [[#Installation Instructions|install]] the software and try our [[Tutorial: Basic System Dynamics Modelling|basic]] and [[Tutorial: Advanced System Dynamics Modelling|advanced]] tutorials!<br />
<br />
== Introduction to System Dynamics Simulation ==<br />
<br />
===System Dynamics===<br />
System dynamics is an approach to understanding different organizations, markets and other complex systems and their dynamic behavior. System dynamics modelling in Simantics is a free modelling tool. See [[#Installation Instructions|installation instructions]].<br />
<br />
===Model===<br />
[[File:ModelStructure.png|right|thumb|Model structure]]<br />
System dynamics model is generally understood as the model configuration. In this tool, the model contains also other components. Model can have Operating interfaces that enable the use of the model with simple controls. Operating interfaces are configured separately and when using them, the complex model is hidden from the user. Experiments are the way to simulate the model. In the future, you can have experiments with different configurations, for example different initial values for some parameters. In that way, you don't have to always configure the model for different scenarios. Modules folder contains all the different module types in your model and you can create new module types there. <br />
<br />
<br style="clear: both" /><br />
<br />
===Components===<br />
Most of the components you can use in your models are basic system dynamics components. The modularity of the models introduces two additional components, Modules and Inputs. All the components are explained below.<br />
[[File:ComponentTypes.png|right|frame|Component types]]<br />
;Auxiliary<br />
:Auxiliary is the most basic variable you can use. It represents a single value or a mathematical expression. There are different types of auxiliary variables currently in the system: Auxiliary, Parameter, Constant and WithLookup. Auxiliary is the default type. Parameters are single values that the user can change. When only parameters are changed, the model simulates faster, because the system does not have to recompile the model. WithLookup is a special variable that has an expression and a lookup table. The expresssion defines what value is taken from the defined table.<br />
;Dependency<br />
:Dependency is an arrow that connects two components. It means that the value of the variable from which the arrow starts is used to calculate the value of the variable where the arrow ends.<br />
;Flow<br />
:Flow connects clouds, valves and stocks. Flow represents an actual flow of something from stocks or clouds to stocks or clouds. There has to be at least one valve in a flow and the system creates it automatically, if none of the ends of the flow is a valve.<br />
;Valve<br />
:Valve regulates the rate of a flow. The value of a valve is automatically used in calculating the level of an adjacent stock. Valves behave just like Auxiliary variables but look different and you can connect also flows to them.<br />
;Stock<br />
:The value of a stock variable is an integral of flows leaving and flows arriving to the variable. The integral is calculated automatically from the valves that are connected to the variable with flow connections. You must give an initial value to the stock. Initial value can be a single value or an equation. You can use values of other variables to calculate the initial value.<br />
;Cloud<br />
:Cloud is not a variable. It represents a starting or ending point of a flow, if it is not in the scope of the model.<br />
;Module<br />
:Modules enable structural modeling. Modules are defined just like the basic model configuration, but the module component hides the actual configuration. You can only connect dependency connections into the module and dependency connections from the module must end to Input variables. The interface of the module is defined using input and output variables in the configuration of the module. All variable types can be set as output variables. If a variable is an output variable, its font is bold.<br />
;Input<br />
:Input variables are the way of getting values from other modules. Inputs look like auxiliary variables except their font is italics. You can set a default value to the input variable in case it is not connected to any variable. Connections are made from the modules properties, when the module is populated. Input doesn't have to be connected with an arrow to a module. If the variable has no connections, it can get values from a higher level in the hierarchy. If an input is connected to an output, the output and its module are shown below the variable using dot notation.<br />
<br style="clear: both" /><br />
<br />
===Modeling principles===<br />
<br />
System dynamics modelling is much more than just mathematical formulas and nice graphs. Models are ways of communicating. There are some basic principles in system dynamics modelling that make the models easier to read and understand. You do not have to apply these principles to simulate models, but using them makes it easier for you to communicate your model to others.<br />
<br />
;Variable names<br />
:Variables names should be nouns, not verbs. The names should be positive: for example it is easier to understand that satisfaction decreases than dissatisfaction rises. <br />
<br />
:Variable names can and should have multiple words, if they are needed. Unfortunately current version of the tool does not support spaces in variable names. A good practice is to use CamelCase if name contains multiple words. This means that you start every word woth a capital letter (example: ExampleVariable).<br />
<br />
;Connections<br />
:You should try to avoid overlapping dependency arrows. In some situations, however, it is not possible. Dependencies should also form distinctive loops, if there is a loop. It makes it easier to read and understand the model and its behavior.<br />
<br />
;Graphical annotations<br />
:System dynamics contains usually annotations for loops, polarities, delays and so on. Currently those annotations are not supported, but the support will be added later. Annotations are important, again, for communicating the behavior of the model.<br />
<br />
==Installation Instructions==<br />
<br />
System dynamics tool is a provided with the Simantics platform.<br />
<br />
# [https://www.simantics.org/simantics/download Download installer from Simantics download page]<br />
# Install the program to a directory without spaces. <br />
# Run Simantics-Sysdyn.exe <br /><br />
: (Default path in windows: C:\Simantics\Sysdyn\1.4\simantics-sysdyn\Simantics-Sysdyn.exe)<br />
<br />
[http://www.openmodelica.org/ OpenModelica] is used to build and simulate the models. Simantics platform has integrated OpenModelica 1.7 for Windows environments. For other versions and other environments you need to install [http://www.openmodelica.org/index.php/download OpenModelica].<br />
<br />
== Workbench ==<br />
<br />
[[File:BasicWorkbench.png|center|729px]]<br />
<br />
<br />
# '''Diagram''' <br /> Diagram is the area where you will graphically modify your model. Diagrams are built from elements that can be dragged from Symbols view or populated using shortcut keys. <br />
# '''Model Browser''' <br /> Model browser shows the structure of your model and all items related to it. <br /> Symbols view is stacked with the model browser and used for dragging elements to diagrams.<br />
# '''Properties''' <br /> Property view shows the selected variable's properties. Property view has a different layout depending on the type of the selected component. The view can also have different tabs depending on the component type. Basic tabs are with variables are Equation and Additional information.<br />
# '''Trend''' <br /> Trend view shows the graphical representation of the values of the selected value over time. For the trend to be shown, a simulation has to be run. The view shows always the results of the latest run, but you can save results of a simulation and show them in the same trend with results from another simulation. Values view and Dependencies are stacked with Trend view and can also be used for analyzing the model.<br />
# '''Experiment controls''' <br /> Experiment controls are shown when an experiment is active. Experiment is activated by double clicking an experiment in the model browser. With the experiment control, you can start simulation runs and save simulation results.<br />
<br />
<br /><br />
If you accidentally close a view, you can reopen them from Window->Show View->Other...<br />
<br />
== Modelling ==<br />
<br />
===Basic modelling===<br />
<br />
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.<br />
<br />
[[File:Basic_1.png|right]]<br />
;Creating a new model<br />
:Start a new model by right-clicking the model browser and selecting New->Model or from the main menu File->New Model.<br />
<br style="clear: both" /><br />
<br />
[[File:Basic_2.png|right]]<br />
;Creating a new module type<br />
:Create a new module type by right-clicking on the Modules-folder and selecting New->Module. This creates a new module type that you can populate to your other modules and the model configuration. <br />
<br style="clear: both" /><br />
<br />
;Configuring a model<br />
:Model configuration can be opened by double clicking Configuration in the model browser. <br />
<br />
;Configuring modules<br />
: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 module!<br />
<br />
;Populate variables<br />
:You can drag variables to a diagram from symbol view. You can also populate variables using [[#Shortcut and control keys|shortcut keys]]<br />
<br />
;Populate modules<br />
:Modules are populated from the model browser. Just drag the module you want to populate from the Modules folder to a diagram.<br />
<br />
;Create connections<br />
: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.<br />
: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.<br />
: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.<br />
<br />
;Connections between modules<br />
:'''Outside the module''' <br /><br />
:You can connect variables to variables in modules like this:<br />
MODULE -----> INPUT<br />
or<br />
ANY VARIABLE -----> MODULE <br />
:This is just the visual configuration, but you need those connections to really connect variables in the module's properties.<br />
:In Inputs -tab you select which variables you connect to inputs inside the module. In Outputs -tab you select which variables you lift from the module to inputs outside it.<br />
<br />
:'''Inside the module''' <br /><br />
:Input variables get values from outside the module<br />
<br />
:Output variables can send their values outside the module. From the variable properties, select Additional Information and press Is Output<br />
<br />
;Configure variables<br />
:Select a single variable from diagram or model browser. The properties of the variables are shown in the equation view and you can modify them.<br />
<br />
;Export model<br />
: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 to for example create different versions of the model, create backups or to transport it to another database.<br />
<br />
;Import model<br />
:Right-click on the model browser and select Import->Model. Browse to your .tg file and select open. The model is added to your model browser.<br />
<br />
===Shortcut and control keys===<br />
<br />
Shortcut keys for configuring a model on diagram.<br />
<br />
{|<br />
|Esc <br />
|Cancel operations (e.g. connection and rename).<br />
|-<br />
|Shift + A <br />
|Hover Auxiliary at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + S<br />
|Hover Stock at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + C<br />
|Hover Cloud at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + V<br />
|Hover Valve at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + I<br />
|Hover Input at the cursor position, populate with left mouse button.<br />
|-<br />
|Alt + left mouse button<br />
|Start an arrow from a variable. End to another variable by clicking left mouse button.<br />
|-<br />
|Alt + right mouse button<br />
|Start flow from a variable. End by clicking left mouse button.<br />
<br />
If a flow is not started or ended on to a variable, a cloud will be created to that end. <br /><br />
If a new flow does not have a valve at either end, a valve will be created in the middle of the flow.<br />
|-<br />
|Delete<br />
|Remove selected variables<br />
|-<br />
|Ctrl + left mouse button<br />
|Select multiple variables<br />
|-<br />
|Mouse wheel or<br/>+ and -<br />
|Diagram zoom<br />
|-<br />
|drag(mouse3) or<br/>drag(shift + any mouse button)<br />
|Diagram pan<br />
|-<br />
|Ctrl + C<br />
|Copy selected elements<br />
|-<br />
|Ctrl + X<br />
|Cut selected elements<br />
|-<br />
|Ctrl + V<br />
|Paste copied or cut elements<br />
|-<br />
|G<br />
|Show / hide grid<br />
|-<br />
|R<br />
|Show / hide ruler<br />
|}<br />
<br />
Other shortcut keys can be found selecting Window -> Preferences from the main menu. Keys are located in General -> Keys.<br />
<br />
== Simulation ==<br />
There are three different ways for simulating a model. Different simulations are represented as different types of experiments in Simantics System Dynamics. <br />
<br />
Experiments are created from the context menu of experiments folder in a model. <br />
<br />
[[File:NewExperiment.png]]<br />
<br />
Double-click on an experiment activates it and displays experiment type specific controls in the main tool bar.<br />
<br />
;Normal simulation<br />
: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.<br />
<br />
;Game simulation<br />
:Game simulations allow simulating an arbitrary number of steps, changing parameter values and continuing simulation with the new values from where it previously ended.<br />
<br />
;Simulation playback<br />
:Simulation playback works essentially as the basic experiment, but it offers some additional visualization options.<br />
<br />
== Simulation result and model structure analysis ==<br />
Simulation results can be viewed as trends in trend view or as plain numbers in values view. The views display results of variables that are selected in the workbench. Users can also create [[#Custom charts |custom charts]].<br />
<br />
Model structure can be examined in the Structure view. There are two options: Dependency structures of individual variables or the complete hierarchy structure of the model.<br />
<br />
;Trend<br />
:Shows you the values of the selected variable(s) graphically over the simulation time. You can modify the trend and zoom it using the context menu (right-click) of the trend. <br /> [[File:Trend.png]]<br />
<br />
;Values<br />
:Shows you the values of the selected variable(s) in a table form. If the value has a star (*) at the end, it means that the value is an approximate. There is no value for that variable for the given time step. Selected values can be copied to other software in csv format.<br /> [[File:Values.png]]<br />
<br />
;Compare results<br />
:You can compare different results of the same model by saving simulation results and displaying the saved results side by side with other results. You can save your results after simulating by clicking the save button [[File:Saveresults.png]] on your experiment controls. The saved results appear to model browser under the active experiment. To show the results on trends and tables, right-click on the result and select Show on charts. <br /> [[File:CompareTrend.png]]<br />
<br />
;Dependencies<br />
:Dependencies display which variables affect and which are affected by the selected variable. The direction and number of steps that are traveled from the selected variable can be configured at the bottom of the view. <br /> [[File:Dependencies.png]]<br />
<br />
;Model Hierarchy<br />
:Model Hierarchy displays the hierarchical structure of the model. The module type where a selected variable is located is highlighted.<br /> [[File:ModelHierarchy.png]]<br />
<br />
== Custom charts ==<br />
Custom charts are user-defined displays of simulation result data. They can be used and re-used in various places. The three types of custom charts (line, bar and pie charts) provide model developers means for examining and developing their models and communicating the simulation results to others. <br />
<br />
Custom charts are created to the Charts folder in model browser.<br />
<br />
[[File:NewChart.png | Creating a new chart]]<br />
<br />
Charts are configured the same way as variables: first select the chart from model browser and then configure it in the property view. Charts can be viewed in the same active trend view as any variable by selecting the chart from model browser. In addition to trend view, charts can be populated directly to the model diagram or to a separate chart panel that can contain multiple charts. <br />
<br />
=== Line chart ===<br />
<br />
Line char 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.<br />
<br />
[[File:LineChart.png|Line chart with an array variable]]<br />
<br />
[[File:LineChartGeneral.png|General settings of line chart]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|The title of the chart. Displayed in the chart<br />
|-<br />
|Type<br />
|Line chart (default) or area chart<br />
|-<br />
|Hide<br />
|Options to hide chart grid, title or legend<br />
|-<br />
|'''X-axis'''<br />
|<br />
|-<br />
|Variable<br />
|A variable that is used as the x-axis variable. The default variable is time and it needs not to be typed in the field.<br />
|-<br />
|Label<br />
|Optional other label for the variable than its name<br />
|-<br />
|Min<br />
|Minimum value of the x-axis<br />
|-<br />
|Max<br />
|Maximum value of the x-axis<br />
|-<br />
|Hide<br />
|Options to hide x-axis lable, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
[[File:LineChartAxisAndVariables.png|Axis and variables settings of line chart]]<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed.<br />
|-<br />
|Color<br />
|Color for the lines of this variable<br />
|-<br />
|Line width<br />
|The width of the lines drawn for this variable<br />
|}<br />
There are also configuration options for y-axis. They are displayed when an axis is selected in the Axis and variables tab.<br />
{|<br />
|'''Y-axis'''<br />
|<br />
|-<br />
|Label<br />
|Label of the axis<br />
|-<br />
|Min<br />
|Minimum value in the axis<br />
|-<br />
|Max<br />
|Maximum value in the axis<br />
|-<br />
|Color<br />
|The color of the axis lines, ticks and labels<br />
|-<br />
|Hide<br />
|Options to hide parts of the axis: label, axis line, tick marks, tick labels<br />
|-<br />
|}<br />
<br />
=== Bar chart ===<br />
Bar charts display variables in a certain point in time. The point can be defined for the complete chart in cart'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. <br />
<br />
[[File:BarChartGeneral.png|General bar chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Name is displayed in model browser.<br />
|-<br />
|Title<br />
|The title of the chart. Title is displayed in the chart, if not hidden<br />
|-<br />
|Type<br />
|Normal or stacked. Normal type displays all variables in separate bars. Stacked mode is able to display one-dimensional array variables in stacks.<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Option for hiding grid, title and Legend. Legend is hidden by default since it only contains the information that the current simulation is displayed.<br />
|-<br />
|}<br />
<br />
[[File:BarChartInDiagram.png|Bar chart in a model diagram]]<br />
<br />
Charts can be added to model diagrams simply by dragging the chart from model browser to diagram.<br />
<br />
[[File:BarChartVariable.png|Settings for a variable in bar chart]]<br />
<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|}<br />
[[File:BarChartAxis.png|Settings for axis in bar chart]]<br />
{|<br />
|'''Domain axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for x axis<br />
|-<br />
|Label angle<br />
|Axis labels can be displayed in an angle. This value determines the angle in degrees.<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|'''Range axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for y axis<br />
|-<br />
|Min<br />
|Minimum value of y axis<br />
|-<br />
|Max<br />
|Maximum value of y axis<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
=== Pie chart ===<br />
<br />
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.<br />
<br />
[[File:PieChartGeneral.png|General pie chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|Title The title of the chart. Displayed in the chart<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Options for hiding title, section labels and legend<br />
|-<br />
|}<br />
<br />
[[File:PieChartVariable.png|Variable settings in pie chart]]<br />
{|<br />
|'''Variables'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Color<br />
|Color for the sector of this variable<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|Exploded<br />
|If set, the sector(s) of the variable(s) are "exploded" away from the center of the pie chart<br />
|-<br />
|}<br />
<br />
[[File:PieChartChartPanel.png|Pie chart in chart panel]]<br />
<br />
=== Chart panel ===<br />
[[File:ChartPanel.png|right]]<br />
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.<br />
<br />
Chart panel can be either horizontally or vertically oriented. Different orientations help in configuring the workbench perspective. <br />
<br />
[[File:ChartPanelOrientation.png|Chart panel orientation]]<br />
<br />
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.<br />
<br />
<br style="clear: both" /><br />
<br />
== Multidimensional variables ==<br />
<br />
<br />
=== Modeling ===<br />
<br />
Models with multidimensional variables look just like any other models. The structure of the models is replicated givin multiple indexes to variables. For users with programming background, notation Variable[] may be familiar. In system dynamic modeling we need to give names to the indexes. Instead of using numbers to define the indexes, like in normal programming, we use enumerations. The steps to create a model with multidimensional variables are as follows (with examples):<br />
<br />
# '''Create the model structure''' <BR />Model with multidimensional variables looks just like any other model.<BR /> [[File:ModelWithMultidimensionalVariables.png|300px|Model with multidimensional variables]]<br />
# '''Create Enumerations and define the indexes''' <BR />Enumerations are created by right-clicking configuration and selecting New->Enumeration.<BR /> [[File:NewEnumeration.png|250px|New enumeration]]<BR />Define enumeration indexes by adding as many indexes as you want. Rename the indexes by selecting them and then clicking on them again.<BR />[[File:DefineIndexes.png|200px|Index definitions]]<br />
# '''Add Enumerations for variables''' <BR />Select the variable that you want to be multidimensional. From the Indexes -tab in the property view, move the wanted enumerations to the right. The order of the enumerations does matter.[[File:SelectEnumerations.png|500px|Select enumerations for variables]]<br />
# '''Define equations for all possible indexes''' <BR />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 indexes, so the resulting definition can be {{1,2,3},{4,5,6},{7,8,9}}.<BR />[[File:DefineEquations.png|500px|Define equations for all indexes]]<br />
<br />
<br />
<br />
=== Expressions ===<br />
<br />
Values for all cells in the variable matrix can be defined in a single expression. <br />
<br />
[[File: DefineEquations.png|600px]]<br />
<br />
[[File:DefineEquations2.png|600px]]<br />
<br />
In many situations, it is however more clear to define separate expressions for each cell or blocks. <br />
<br />
# '''Define range for the expression'''<BR /> [[File:DefineRange.png]]<br />
# '''Define the expression''' (dimensions of the defined range and the result of the expression must match!) <BR /> [[File:DefineEquations3.png]]<br />
# '''Create a new expression''' <BR /> [[File:CreateNewExpression.png]]<br />
#''' Select the new expression''' <BR /> [[File:SelectNewExpression.png]]<br />
<br />
Repeat until there is value for each cell. There must be exactly one value for each cell.<br />
<br />
=== Array slices ===<br />
<br />
Many times it is useful to access a slice of a multidimensional variable. In this chapter, we will use the following example variable:<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
The whole variable can be accessed in three different ways:<br />
# Auxiliary<br />
# Auxiliary[E1, E2]<br />
# Auxiliary[:, :]<br />
<br />
The following explains different methods for accessing parts of the variable<br />
<br />
// Single cell<br />
Auxiliary[one, eins] = 1<br />
<br />
// Slices<br />
Auxiliary[one, E2] = {1,2,3}<br />
Auxiliary[E1, zwei] = {{2},{5},{8}}<br />
<br />
// In addition to single cells and the whole enumeration range, a subrange of the enumeration can be used<br />
Auxiliary[two : three, E2] = {{4,5,6},{7,8,9}}<br />
Auxiliary[one : two, zwei : drei] = {{2,3},{5,6}}<br />
<br />
The syntax for accessing parts of variables can be used in both expression range definitions and in expressions.<br />
<br />
=== Arithmetic Operators ===<br />
<br />
Arithmetic operations are defined in Modelica. Below are examples of different operations.<br />
<br />
;Addition and substraction<br />
Addition and substraction are calculated elementwise<br />
<br />
{1,2,3} - {0,2,3} = {1,0,0}<br />
{{2,2},{4,4}} + {{8,8},{1,1}} = {{10,10},{5,5}}<br />
{1,2,3} - {1,2} = ERROR! Different array sizes<br />
<br />
;Division<br />
Division with a scalar<br />
{5,10,15} / 5 = {1,2,3}<br />
5 / {5,10,15} = ERROR! not allowed<br />
<br />
Division with an array<br />
{1,2,3} / {1,2,3} = ERROR! not allowed<br />
<br />
// Elementwise<br />
{1,2,3} ./ {1,2,3} = {1,1,1}<br />
<br />
;Multiplication<br />
<br />
Multiplication with a scalar<br />
{1,2,3} * 2 = {2,4,6}<br />
5 * {1,2,3} = {5,10,15}<br />
<br />
Matrix multiplication with an array<br />
{{3,4},{5,6}} * {1,2} = {11,17}<br />
{{3,4},{5,6}} * {1,2,3} = ERROR! incompatible array sizes<br />
<br />
//Elementwise<br />
{1,2} .* {1,2} = {1,4}<br />
<br />
Real[3,2] c = {{1,2},{3,4},{5,6}}; <br />
Real[2,2] d = {{3,4},{5,6}};<br />
Real[2,2] cd;<br />
cd = c[2:3, :] .* d; // Result: {{9,16},{25,36}}<br />
<br />
=== Builtin Modelica functions ===<br />
<br />
Modelica has some builtin functions that help using multidimensional variables. This chapter introduces some of the builtin functions. <br />
<br />
;Dimension and size functions<br />
<br />
We will use the same example variable as previously.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
;ndims(A)<br />
The number of dimensions in array A<br />
ndims(Auxiliary) = 2<br />
<br />
;size(A, i)<br />
The size of dimension i in array A<br />
size(Auxiliary, 2) = 3<br />
<br />
;size(A)<br />
A vector of length ndims(A) containing the dimension sizes of A<br />
size(Auxiliary) = {3,3}<br />
<br />
<br />
;Construction functions<br />
In addition to normal array constructing, a special construction functions can be used.<br />
<br />
;zeros(n1,n2,n3,...)<br />
An array full of zeros with dimensions n1 x n2 x n2 x ... <br />
zeros(2, 2) = {{0,0}, {0,0}}<br />
<br />
;ones(n1,n2,n3,...)<br />
An array full of ones with dimensions n1 x n2 x n2 x ... <br />
ones(2, 2) = {{1,1}, {1,1}}<br />
<br />
;fill(s,n1,n2,n3)<br />
Like zeros() and ones(), but with user defined value (s) for array elements.<br />
fill(3,2,2) = {{3,3}, {3,3}}<br />
<br />
;identity(n)<br />
Creates an n x n integer identity matrix with ones on the diagonal and all other elements zero.<br />
identity(3) =<br />
1 0 0<br />
0 1 0<br />
0 0 1<br />
<br />
;diagonal(v)<br />
Constructs a square matrix with elements of vector v on the diagonal and all other elements zero.<br />
diagonal({1,2,3}) =<br />
1 0 0<br />
0 2 0<br />
0 0 3<br />
<br />
;linspace(x1,x2,n)<br />
Constracts a Real vector from x1 to x2 with n equally spaced elements.<br />
linspace(2,5,4) = {2,3,4,5}<br />
<br />
;Reduction functions<br />
<br />
Reduction functions reduce arrays to scalars.<br />
<br />
;min(A)<br />
Returns the minimum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
min(A) = 1<br />
<br />
;max(A)<br />
Returns the maximum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
max(A) = 4<br />
<br />
;sum(A)<br />
Returns the sum of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
sum(A) = 10 // 1 + 2 + 3 + 4<br />
<br />
;product(A)<br />
Returns the product of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
product(A) = 24 // 1 * 2 * 3 * 4<br />
<br />
<br />
;Using functions with iterators<br />
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.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
AuxiliarySum[E1] = {sum( Auxiliary[ i , E2 ] ) for i in E1} // Result: {6, 15, 24}<br />
<br />
/* Same as:<br />
{sum(Auxiliary[one, E2]), sum(Auxiliary[two, E2]), sum(Auxiliary[three, E2])}<br />
{sum({1,2,3}), sum({4,5,6}), sum({7,8,9})}<br />
*/<br />
<br />
One expression can have multiple iterators. The Modelica specification defines the following format, but it is NOT yet supported in OpenModelica:<br />
{sum(Array[ i, j, E3]) for i in E1, j in E2} // Dimensions reduced from 3 to 2<br />
<br />
To use multiple iterators, use the following format (NOTE the reversed order of iterators!):<br />
{{sum(Array[ i, j, E3]) for j in E2} for i in E1} // Dimensions reduced from 3 to 2<br />
<br />
The range doesn't have to be the whole enumeration. Subranges can also be used.<br />
{sum( Auxiliary[ i , eins : zwei ] ) for i in E1.one : E1.two} // Result: {3, 9}<br />
<br />
/* Same as<br />
{sum(Auxiliary[one, eins : zwei]), sum(Auxiliary[two, eins : zwei])}<br />
{sum({1,2}), sum({4,5})}<br />
*/<br />
<br />
=== Simulation results ===<br />
<br />
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. <br />
<br />
[[File:3x3trend.png|300px|Trend view for a 3x3 variable]]<br />
<br />
The clutter can be reduced by selecting which enumeration indexes are shown in charts. Select an enumeration and tick the indexes 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.<br />
<br />
[[File:ShowInCharts.png|500px|Select indexes to show in charts]]<br />
<br />
<br />
=== Array Variables in Modules ===<br />
<br />
[[File:Replaceable.png|frame|Replaceable enumeration inside a module]]<br />
<br />
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 [[Simantics_System_Dynamics#Modeling|Modeling]]). <br />
<br />
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.<br />
<br />
<br />
<br style="clear: both" /><br />
<br />
In this example, the original enumeration that the modeler used had two indexes. We are using an instance of this module, but we need to use array variables that have three indexes instead of two. We are using two variables and an instance of the module.<br />
<br />
[[File:ReplacingEnumerationConfiguration.png|frame|left|500px|Module configuration for replacing enumerations inside the module]]<br />
<br style="clear: both" /><br />
<br />
In the parent configuration, we have used an enumeration with three indexes in the two variables.<br />
<br />
[[File:Replacing.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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 clickin 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.<br />
<br />
<br />
[[File:ReplacingEnumeration.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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!<br />
<br />
== Functions ==<br />
<br />
Modelica provides a convenient way to use functions in your models. You can create your own functions, import complete function libraries and share function libraries to be used in all of your models. <br />
<br />
=== Creating functions ===<br />
<br />
[[File:NewFunction.png|right]]<br />
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.<br />
<br />
Functions that can be found from Functions -folder can be used in your variable definitions.<br />
<br />
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. <br />
<br />
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.<br />
<br />
Below is an example of a simple function. For more examples, see the built-in functions provided with the tool and [https://www.modelica.org/documents/ Modelica specifications].<br />
<br />
<br style="clear: both" /><br />
<br />
[[File:ExampleFunction.png]]<br />
<br />
=== Function libraries ===<br />
<br />
<br />
[[File:NewFunctionLibrary.png|right]]<br />
<br />
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)).<br />
<br />
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. <br />
<br />
Create a new function library by right-clicking on Functions folder, Shared functions folder or other module library.<br />
<br />
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.<br />
<br />
[[File:SharedFunctions.png]]<br />
<br style="clear: both" /><br />
<br />
=== External functions ===<br />
<br />
Modelica allows you to use external functions that are programmed using C language. Below is a simple example of using a function that returns the sum of two arguments. <br />
<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}<br />
<br />
<br />
[[File:ImportCFunctionLibrary.png|right]]<br />
<br />
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 <br />
(e.g. simantics_home/plugins/org.simantics.openmodelica.win32_x/MinGW/bin/mingw32_gcc.exe -g -O -c ExampleCFunctionCode.c). <br />
<br style="clear: both" /><br />
<br />
[[File:ExampleExternalFunction.png]]<br />
<br />
<br />
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.<br />
<br />
[[File:ExternalFunctionResult.png]]<br />
<br />
<br />
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.<br />
<br />
<br />
Small external C function can also be written directly to the function code in Simantics Sysdyn:<br />
function ExampleExternalFunction<br />
input Real x;<br />
input Real y;<br />
output Real z;<br />
external "C" z=exampleCFunction(x,y) annotation(Include="<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}");<br />
end ExampleExternalFunction;<br />
<br />
=== Modelica functions ===<br />
<br />
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 [[Simantics_System_Dynamics#Builtin_functions|builtin functions for arrays]].<br />
<br />
{|<br />
|abs(x)<br />
|Returns the absolute value of x. Expanded into "(if x >= 0 then x else -x)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|acos(x)<br />
|Inverse cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|asin(x)<br />
|Inverse sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan(x)<br />
|Inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan2(x1,x2)<br />
|four quadrant inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cat(n,A,B,...)<br />
|General concatenation function that concatenates arrays A,B,... along the nth dimension.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|ceil(x)<br />
|Returns the smallest integer not less than x, the closest integer above x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cos(x)<br />
|Cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cosh(x)<br />
|Hyperbolic cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cross(x,y)<br />
|Returns the 3-vector cross product of the 3-vectors x and y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|delay(expr, delayTime)<br />
|Returns the value of expr at the time time-delayTime. The value of expr is returned when time <= time.start + delayTime.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|der(x)<br />
|Time derivative of x. X must be have continuous-time variability.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|div(x, y)<br />
|Returns the algebraic quotient x/y with any fractional part discarted. E.g. div(10,3) = 3.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|edge(b)<br />
|Returns true when the value of the boolean expression b changes. Expanded into (b and not pre(b)).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|exp(x)<br />
|Exponential, base e.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|floor(x)<br />
|Returns the largest integer not greater than x, the closest integer below x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|initial()<br />
|Returns true at the beginning of the simulation. <br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|integer(x)<br />
|Returns the largest integer not greater than x as an integer.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log(x)<br />
|Natural logarithm. (base e, x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log10(x)<br />
|Base 10 logarithm. (x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|mod(x, y)<br />
|Returns the integer modulus of x/y: mod(x,y) = x - floor(x/y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|noEvent(expr)<br />
|noEvent around an expression causes the expression to NOT generate event.<br />
'''Important:''' <br />
:If you want a condition to be checked only on time steps, use noEvent.<br />
:(e.g. if noEvent(value >= 1) then ... else ...)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|pre(x)<br />
|Returns the preceding value of y from time event that has occured before current time.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|rem(x, y)<br />
|Returns the integer remainder of x/y: rem(x,y) = x - div(x,y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sample(start, interval)<br />
|Returns true and triggers time events at times start + i * interval (i=0,1,...).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sign(x)<br />
|Returns -1 if x is negative, 1 if x is positive. Expanded into "(if x > 0 then 1 else if x < 0 then -1 else 0)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sin(x)<br />
|Sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sinh(x)<br />
|Hyperbolic sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sqrt(x)<br />
|Square root of x. The value of x must be greater or equal to 0 or an assertion error occurs.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tan(x)<br />
|Tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tanh(x)<br />
|Hyperbolic tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|terminal()<br />
|Returns true at the end of a successful simulation.<br />
|}<br />
<br />
<br />
<center><br />
[[Simantics]] | ''System Dynamics Modelling''<br />
</center><br />
<br />
----<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Basic System Dynamics Modelling]]'''<br><br />
System dynamics modelling in Simantics is a free modelling tool that is included into the basic installation. This tutorial introduces the basic features of the system dynamics modelling tool.<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Advanced System Dynamics Modelling]]'''<br><br />
This tutorial introduces the more advanced features of the system dynamics modelling tool: Modules and Operating interfaces<br />
<br />
[[Category: Simantics System Dynamics]]</div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=Simantics_System_Dynamics&diff=555Simantics System Dynamics2012-06-04T11:32:55Z<p>Teemu Lempinen: /* Chart panel */</p>
<hr />
<div>== Simantics System Dynamics ==<br />
<br />
Simantics System Dynamics is currently the only open source modelling and simulating tool for Simantics. Simantics System Dynamics is under development and will go through some changes in the future. New features will be added and old ones improved according to the needs of the modellers. New features include module libraries and different analysis tools.<br />
<br />
This documentation introduces you to the current version of Simantics System Dynamics. Documentation includes the basic modelling principles and a guide on how to model system dynamics models with Simantics System Dynamics. If you like to get to know the tool better and try modelling and simulating yourself, [[#Installation Instructions|install]] the software and try our [[Tutorial: Basic System Dynamics Modelling|basic]] and [[Tutorial: Advanced System Dynamics Modelling|advanced]] tutorials!<br />
<br />
== Introduction to System Dynamics Simulation ==<br />
<br />
===System Dynamics===<br />
System dynamics is an approach to understanding different organizations, markets and other complex systems and their dynamic behavior. System dynamics modelling in Simantics is a free modelling tool. See [[#Installation Instructions|installation instructions]].<br />
<br />
===Model===<br />
[[File:ModelStructure.png|right|thumb|Model structure]]<br />
System dynamics model is generally understood as the model configuration. In this tool, the model contains also other components. Model can have Operating interfaces that enable the use of the model with simple controls. Operating interfaces are configured separately and when using them, the complex model is hidden from the user. Experiments are the way to simulate the model. In the future, you can have experiments with different configurations, for example different initial values for some parameters. In that way, you don't have to always configure the model for different scenarios. Modules folder contains all the different module types in your model and you can create new module types there. <br />
<br />
<br style="clear: both" /><br />
<br />
===Components===<br />
Most of the components you can use in your models are basic system dynamics components. The modularity of the models introduces two additional components, Modules and Inputs. All the components are explained below.<br />
[[File:ComponentTypes.png|right|frame|Component types]]<br />
;Auxiliary<br />
:Auxiliary is the most basic variable you can use. It represents a single value or a mathematical expression. There are different types of auxiliary variables currently in the system: Auxiliary, Parameter, Constant and WithLookup. Auxiliary is the default type. Parameters are single values that the user can change. When only parameters are changed, the model simulates faster, because the system does not have to recompile the model. WithLookup is a special variable that has an expression and a lookup table. The expresssion defines what value is taken from the defined table.<br />
;Dependency<br />
:Dependency is an arrow that connects two components. It means that the value of the variable from which the arrow starts is used to calculate the value of the variable where the arrow ends.<br />
;Flow<br />
:Flow connects clouds, valves and stocks. Flow represents an actual flow of something from stocks or clouds to stocks or clouds. There has to be at least one valve in a flow and the system creates it automatically, if none of the ends of the flow is a valve.<br />
;Valve<br />
:Valve regulates the rate of a flow. The value of a valve is automatically used in calculating the level of an adjacent stock. Valves behave just like Auxiliary variables but look different and you can connect also flows to them.<br />
;Stock<br />
:The value of a stock variable is an integral of flows leaving and flows arriving to the variable. The integral is calculated automatically from the valves that are connected to the variable with flow connections. You must give an initial value to the stock. Initial value can be a single value or an equation. You can use values of other variables to calculate the initial value.<br />
;Cloud<br />
:Cloud is not a variable. It represents a starting or ending point of a flow, if it is not in the scope of the model.<br />
;Module<br />
:Modules enable structural modeling. Modules are defined just like the basic model configuration, but the module component hides the actual configuration. You can only connect dependency connections into the module and dependency connections from the module must end to Input variables. The interface of the module is defined using input and output variables in the configuration of the module. All variable types can be set as output variables. If a variable is an output variable, its font is bold.<br />
;Input<br />
:Input variables are the way of getting values from other modules. Inputs look like auxiliary variables except their font is italics. You can set a default value to the input variable in case it is not connected to any variable. Connections are made from the modules properties, when the module is populated. Input doesn't have to be connected with an arrow to a module. If the variable has no connections, it can get values from a higher level in the hierarchy. If an input is connected to an output, the output and its module are shown below the variable using dot notation.<br />
<br style="clear: both" /><br />
<br />
===Modeling principles===<br />
<br />
System dynamics modelling is much more than just mathematical formulas and nice graphs. Models are ways of communicating. There are some basic principles in system dynamics modelling that make the models easier to read and understand. You do not have to apply these principles to simulate models, but using them makes it easier for you to communicate your model to others.<br />
<br />
;Variable names<br />
:Variables names should be nouns, not verbs. The names should be positive: for example it is easier to understand that satisfaction decreases than dissatisfaction rises. <br />
<br />
:Variable names can and should have multiple words, if they are needed. Unfortunately current version of the tool does not support spaces in variable names. A good practice is to use CamelCase if name contains multiple words. This means that you start every word woth a capital letter (example: ExampleVariable).<br />
<br />
;Connections<br />
:You should try to avoid overlapping dependency arrows. In some situations, however, it is not possible. Dependencies should also form distinctive loops, if there is a loop. It makes it easier to read and understand the model and its behavior.<br />
<br />
;Graphical annotations<br />
:System dynamics contains usually annotations for loops, polarities, delays and so on. Currently those annotations are not supported, but the support will be added later. Annotations are important, again, for communicating the behavior of the model.<br />
<br />
==Installation Instructions==<br />
<br />
System dynamics tool is a provided with the Simantics platform.<br />
<br />
# [https://www.simantics.org/simantics/download Download installer from Simantics download page]<br />
# Install the program to a directory without spaces. <br />
# Run Simantics-Sysdyn.exe <br /><br />
: (Default path in windows: C:\Simantics\Sysdyn\1.4\simantics-sysdyn\Simantics-Sysdyn.exe)<br />
<br />
[http://www.openmodelica.org/ OpenModelica] is used to build and simulate the models. Simantics platform has integrated OpenModelica 1.7 for Windows environments. For other versions and other environments you need to install [http://www.openmodelica.org/index.php/download OpenModelica].<br />
<br />
== Workbench ==<br />
<br />
[[File:BasicWorkbench.png|center|729px]]<br />
<br />
<br />
# '''Diagram''' <br /> Diagram is the area where you will graphically modify your model. Diagrams are built from elements that can be dragged from Symbols view or populated using shortcut keys. <br />
# '''Model Browser''' <br /> Model browser shows the structure of your model and all items related to it. <br /> Symbols view is stacked with the model browser and used for dragging elements to diagrams.<br />
# '''Properties''' <br /> Property view shows the selected variable's properties. Property view has a different layout depending on the type of the selected component. The view can also have different tabs depending on the component type. Basic tabs are with variables are Equation and Additional information.<br />
# '''Trend''' <br /> Trend view shows the graphical representation of the values of the selected value over time. For the trend to be shown, a simulation has to be run. The view shows always the results of the latest run, but you can save results of a simulation and show them in the same trend with results from another simulation. Values view and Dependencies are stacked with Trend view and can also be used for analyzing the model.<br />
# '''Experiment controls''' <br /> Experiment controls are shown when an experiment is active. Experiment is activated by double clicking an experiment in the model browser. With the experiment control, you can start simulation runs and save simulation results.<br />
<br />
<br /><br />
If you accidentally close a view, you can reopen them from Window->Show View->Other...<br />
<br />
== Modelling ==<br />
<br />
===Basic modelling===<br />
<br />
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.<br />
<br />
[[File:Basic_1.png|right]]<br />
;Creating a new model<br />
:Start a new model by right-clicking the model browser and selecting New->Model or from the main menu File->New Model.<br />
<br style="clear: both" /><br />
<br />
[[File:Basic_2.png|right]]<br />
;Creating a new module type<br />
:Create a new module type by right-clicking on the Modules-folder and selecting New->Module. This creates a new module type that you can populate to your other modules and the model configuration. <br />
<br style="clear: both" /><br />
<br />
;Configuring a model<br />
:Model configuration can be opened by double clicking Configuration in the model browser. <br />
<br />
;Configuring modules<br />
: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 module!<br />
<br />
;Populate variables<br />
:You can drag variables to a diagram from symbol view. You can also populate variables using [[#Shortcut and control keys|shortcut keys]]<br />
<br />
;Populate modules<br />
:Modules are populated from the model browser. Just drag the module you want to populate from the Modules folder to a diagram.<br />
<br />
;Create connections<br />
: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.<br />
: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.<br />
: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.<br />
<br />
;Connections between modules<br />
:'''Outside the module''' <br /><br />
:You can connect variables to variables in modules like this:<br />
MODULE -----> INPUT<br />
or<br />
ANY VARIABLE -----> MODULE <br />
:This is just the visual configuration, but you need those connections to really connect variables in the module's properties.<br />
:In Inputs -tab you select which variables you connect to inputs inside the module. In Outputs -tab you select which variables you lift from the module to inputs outside it.<br />
<br />
:'''Inside the module''' <br /><br />
:Input variables get values from outside the module<br />
<br />
:Output variables can send their values outside the module. From the variable properties, select Additional Information and press Is Output<br />
<br />
;Configure variables<br />
:Select a single variable from diagram or model browser. The properties of the variables are shown in the equation view and you can modify them.<br />
<br />
;Export model<br />
: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 to for example create different versions of the model, create backups or to transport it to another database.<br />
<br />
;Import model<br />
:Right-click on the model browser and select Import->Model. Browse to your .tg file and select open. The model is added to your model browser.<br />
<br />
===Shortcut and control keys===<br />
<br />
Shortcut keys for configuring a model on diagram.<br />
<br />
{|<br />
|Esc <br />
|Cancel operations (e.g. connection and rename).<br />
|-<br />
|Shift + A <br />
|Hover Auxiliary at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + S<br />
|Hover Stock at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + C<br />
|Hover Cloud at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + V<br />
|Hover Valve at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + I<br />
|Hover Input at the cursor position, populate with left mouse button.<br />
|-<br />
|Alt + left mouse button<br />
|Start an arrow from a variable. End to another variable by clicking left mouse button.<br />
|-<br />
|Alt + right mouse button<br />
|Start flow from a variable. End by clicking left mouse button.<br />
<br />
If a flow is not started or ended on to a variable, a cloud will be created to that end. <br /><br />
If a new flow does not have a valve at either end, a valve will be created in the middle of the flow.<br />
|-<br />
|Delete<br />
|Remove selected variables<br />
|-<br />
|Ctrl + left mouse button<br />
|Select multiple variables<br />
|-<br />
|Mouse wheel or<br/>+ and -<br />
|Diagram zoom<br />
|-<br />
|drag(mouse3) or<br/>drag(shift + any mouse button)<br />
|Diagram pan<br />
|-<br />
|Ctrl + C<br />
|Copy selected elements<br />
|-<br />
|Ctrl + X<br />
|Cut selected elements<br />
|-<br />
|Ctrl + V<br />
|Paste copied or cut elements<br />
|-<br />
|G<br />
|Show / hide grid<br />
|-<br />
|R<br />
|Show / hide ruler<br />
|}<br />
<br />
Other shortcut keys can be found selecting Window -> Preferences from the main menu. Keys are located in General -> Keys.<br />
<br />
== Simulation ==<br />
There are three different ways for simulating a model. Different simulations are represented as different types of experiments in Simantics System Dynamics. <br />
<br />
Experiments are created from the context menu of experiments folder in a model. <br />
<br />
[[File:NewExperiment.png]]<br />
<br />
Double-click on an experiment activates it and displays experiment type specific controls in the main tool bar.<br />
<br />
;Normal simulation<br />
: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.<br />
<br />
;Game simulation<br />
:Game simulations allow simulating an arbitrary number of steps, changing parameter values and continuing simulation with the new values from where it previously ended.<br />
<br />
;Simulation playback<br />
:Simulation playback works essentially as the basic experiment, but it offers some additional visualization options.<br />
<br />
== Simulation result and model structure analysis ==<br />
Simulation results can be viewed as trends in trend view or as plain numbers in values view. The views display results of variables that are selected in the workbench. Users can also create [[#Custom charts |custom charts]].<br />
<br />
Model structure can be examined in the Structure view. There are two options: Dependency structures of individual variables or the complete hierarchy structure of the model.<br />
<br />
;Trend<br />
:Shows you the values of the selected variable(s) graphically over the simulation time. You can modify the trend and zoom it using the context menu (right-click) of the trend. <br /> [[File:Trend.png]]<br />
<br />
;Values<br />
:Shows you the values of the selected variable(s) in a table form. If the value has a star (*) at the end, it means that the value is an approximate. There is no value for that variable for the given time step. Selected values can be copied to other software in csv format.<br /> [[File:Values.png]]<br />
<br />
;Compare results<br />
:You can compare different results of the same model by saving simulation results and displaying the saved results side by side with other results. You can save your results after simulating by clicking the save button [[File:Saveresults.png]] on your experiment controls. The saved results appear to model browser under the active experiment. To show the results on trends and tables, right-click on the result and select Show on charts. <br /> [[File:CompareTrend.png]]<br />
<br />
;Dependencies<br />
:Dependencies display which variables affect and which are affected by the selected variable. The direction and number of steps that are traveled from the selected variable can be configured at the bottom of the view. <br /> [[File:Dependencies.png]]<br />
<br />
;Model Hierarchy<br />
:Model Hierarchy displays the hierarchical structure of the model. The module type where a selected variable is located is highlighted.<br /> [[File:ModelHierarchy.png]]<br />
<br />
== Custom charts ==<br />
Custom charts are user-defined displays of simulation result data. They can be used and re-used in various places. The three types of custom charts (line, bar and pie charts) provide model developers means for examining and developing their models and communicating the simulation results to others. <br />
<br />
Custom charts are created to the Charts folder in model browser.<br />
<br />
[[File:NewChart.png | Creating a new chart]]<br />
<br />
Charts are configured the same way as variables: first select the chart from model browser and then configure it in the property view. Charts can be viewed in the same active trend view as any variable by selecting the chart from model browser. In addition to trend view, charts can be populated directly to the model diagram or to a separate chart panel that can contain multiple charts. <br />
<br />
=== Line chart ===<br />
<br />
Line char 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.<br />
<br />
[[File:LineChart.png|Line chart with an array variable]]<br />
<br />
[[File:LineChartGeneral.png|General settings of line chart]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|The title of the chart. Displayed in the chart<br />
|-<br />
|Type<br />
|Line chart (default) or area chart<br />
|-<br />
|Hide<br />
|Options to hide chart grid, title or legend<br />
|-<br />
|'''X-axis'''<br />
|<br />
|-<br />
|Variable<br />
|A variable that is used as the x-axis variable. The default variable is time and it needs not to be typed in the field.<br />
|-<br />
|Label<br />
|Optional other label for the variable than its name<br />
|-<br />
|Min<br />
|Minimum value of the x-axis<br />
|-<br />
|Max<br />
|Maximum value of the x-axis<br />
|-<br />
|Hide<br />
|Options to hide x-axis lable, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
[[File:LineChartAxisAndVariables.png|Axis and variables settings of line chart]]<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed.<br />
|-<br />
|Color<br />
|Color for the lines of this variable<br />
|-<br />
|Line width<br />
|The width of the lines drawn for this variable<br />
|}<br />
There are also configuration options for y-axis. They are displayed when an axis is selected in the Axis and variables tab.<br />
{|<br />
|'''Y-axis'''<br />
|<br />
|-<br />
|Label<br />
|Label of the axis<br />
|-<br />
|Min<br />
|Minimum value in the axis<br />
|-<br />
|Max<br />
|Maximum value in the axis<br />
|-<br />
|Color<br />
|The color of the axis lines, ticks and labels<br />
|-<br />
|Hide<br />
|Options to hide parts of the axis: label, axis line, tick marks, tick labels<br />
|-<br />
|}<br />
<br />
=== Bar chart ===<br />
Bar charts display variables in a certain point in time. The point can be defined for the complete chart in cart'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. <br />
<br />
[[File:BarChartGeneral.png|General bar chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Name is displayed in model browser.<br />
|-<br />
|Title<br />
|The title of the chart. Title is displayed in the chart, if not hidden<br />
|-<br />
|Type<br />
|Normal or stacked. Normal type displays all variables in separate bars. Stacked mode is able to display one-dimensional array variables in stacks.<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Option for hiding grid, title and Legend. Legend is hidden by default since it only contains the information that the current simulation is displayed.<br />
|-<br />
|}<br />
<br />
[[File:BarChartInDiagram.png|Bar chart in a model diagram]]<br />
<br />
Charts can be added to model diagrams simply by dragging the chart from model browser to diagram.<br />
<br />
[[File:BarChartVariable.png|Settings for a variable in bar chart]]<br />
<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|}<br />
[[File:BarChartAxis.png|Settings for axis in bar chart]]<br />
{|<br />
|'''Domain axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for x axis<br />
|-<br />
|Label angle<br />
|Axis labels can be displayed in an angle. This value determines the angle in degrees.<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|'''Range axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for y axis<br />
|-<br />
|Min<br />
|Minimum value of y axis<br />
|-<br />
|Max<br />
|Maximum value of y axis<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
=== Pie chart ===<br />
<br />
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.<br />
<br />
[[File:PieChartGeneral.png|General pie chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|Title The title of the chart. Displayed in the chart<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Options for hiding title, section labels and legend<br />
|-<br />
|}<br />
<br />
[[File:PieChartVariable.png|Variable settings in pie chart]]<br />
{|<br />
|'''Variables'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Color<br />
|Color for the sector of this variable<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|Exploded<br />
|If set, the sector(s) of the variable(s) are "exploded" away from the center of the pie chart<br />
|-<br />
|}<br />
<br />
[[File:PieChartChartPanel.png|Pie chart in chart panel]]<br />
<br />
=== Chart panel ===<br />
[[File:ChartPanel.png|right]]<br />
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.<br />
<br />
Chart panel can be either horizontally or vertically oriented. Different orientations help in configuring the workbench perspective. <br />
<br />
[[File:ChartPanelOrientation.png|Chart panel orientation]]<br />
<br />
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.<br />
<br />
== Multidimensional variables ==<br />
<br />
<br />
=== Modeling ===<br />
<br />
Models with multidimensional variables look just like any other models. The structure of the models is replicated givin multiple indexes to variables. For users with programming background, notation Variable[] may be familiar. In system dynamic modeling we need to give names to the indexes. Instead of using numbers to define the indexes, like in normal programming, we use enumerations. The steps to create a model with multidimensional variables are as follows (with examples):<br />
<br />
# '''Create the model structure''' <BR />Model with multidimensional variables looks just like any other model.<BR /> [[File:ModelWithMultidimensionalVariables.png|300px|Model with multidimensional variables]]<br />
# '''Create Enumerations and define the indexes''' <BR />Enumerations are created by right-clicking configuration and selecting New->Enumeration.<BR /> [[File:NewEnumeration.png|250px|New enumeration]]<BR />Define enumeration indexes by adding as many indexes as you want. Rename the indexes by selecting them and then clicking on them again.<BR />[[File:DefineIndexes.png|200px|Index definitions]]<br />
# '''Add Enumerations for variables''' <BR />Select the variable that you want to be multidimensional. From the Indexes -tab in the property view, move the wanted enumerations to the right. The order of the enumerations does matter.[[File:SelectEnumerations.png|500px|Select enumerations for variables]]<br />
# '''Define equations for all possible indexes''' <BR />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 indexes, so the resulting definition can be {{1,2,3},{4,5,6},{7,8,9}}.<BR />[[File:DefineEquations.png|500px|Define equations for all indexes]]<br />
<br />
<br />
<br />
=== Expressions ===<br />
<br />
Values for all cells in the variable matrix can be defined in a single expression. <br />
<br />
[[File: DefineEquations.png|600px]]<br />
<br />
[[File:DefineEquations2.png|600px]]<br />
<br />
In many situations, it is however more clear to define separate expressions for each cell or blocks. <br />
<br />
# '''Define range for the expression'''<BR /> [[File:DefineRange.png]]<br />
# '''Define the expression''' (dimensions of the defined range and the result of the expression must match!) <BR /> [[File:DefineEquations3.png]]<br />
# '''Create a new expression''' <BR /> [[File:CreateNewExpression.png]]<br />
#''' Select the new expression''' <BR /> [[File:SelectNewExpression.png]]<br />
<br />
Repeat until there is value for each cell. There must be exactly one value for each cell.<br />
<br />
=== Array slices ===<br />
<br />
Many times it is useful to access a slice of a multidimensional variable. In this chapter, we will use the following example variable:<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
The whole variable can be accessed in three different ways:<br />
# Auxiliary<br />
# Auxiliary[E1, E2]<br />
# Auxiliary[:, :]<br />
<br />
The following explains different methods for accessing parts of the variable<br />
<br />
// Single cell<br />
Auxiliary[one, eins] = 1<br />
<br />
// Slices<br />
Auxiliary[one, E2] = {1,2,3}<br />
Auxiliary[E1, zwei] = {{2},{5},{8}}<br />
<br />
// In addition to single cells and the whole enumeration range, a subrange of the enumeration can be used<br />
Auxiliary[two : three, E2] = {{4,5,6},{7,8,9}}<br />
Auxiliary[one : two, zwei : drei] = {{2,3},{5,6}}<br />
<br />
The syntax for accessing parts of variables can be used in both expression range definitions and in expressions.<br />
<br />
=== Arithmetic Operators ===<br />
<br />
Arithmetic operations are defined in Modelica. Below are examples of different operations.<br />
<br />
;Addition and substraction<br />
Addition and substraction are calculated elementwise<br />
<br />
{1,2,3} - {0,2,3} = {1,0,0}<br />
{{2,2},{4,4}} + {{8,8},{1,1}} = {{10,10},{5,5}}<br />
{1,2,3} - {1,2} = ERROR! Different array sizes<br />
<br />
;Division<br />
Division with a scalar<br />
{5,10,15} / 5 = {1,2,3}<br />
5 / {5,10,15} = ERROR! not allowed<br />
<br />
Division with an array<br />
{1,2,3} / {1,2,3} = ERROR! not allowed<br />
<br />
// Elementwise<br />
{1,2,3} ./ {1,2,3} = {1,1,1}<br />
<br />
;Multiplication<br />
<br />
Multiplication with a scalar<br />
{1,2,3} * 2 = {2,4,6}<br />
5 * {1,2,3} = {5,10,15}<br />
<br />
Matrix multiplication with an array<br />
{{3,4},{5,6}} * {1,2} = {11,17}<br />
{{3,4},{5,6}} * {1,2,3} = ERROR! incompatible array sizes<br />
<br />
//Elementwise<br />
{1,2} .* {1,2} = {1,4}<br />
<br />
Real[3,2] c = {{1,2},{3,4},{5,6}}; <br />
Real[2,2] d = {{3,4},{5,6}};<br />
Real[2,2] cd;<br />
cd = c[2:3, :] .* d; // Result: {{9,16},{25,36}}<br />
<br />
=== Builtin Modelica functions ===<br />
<br />
Modelica has some builtin functions that help using multidimensional variables. This chapter introduces some of the builtin functions. <br />
<br />
;Dimension and size functions<br />
<br />
We will use the same example variable as previously.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
;ndims(A)<br />
The number of dimensions in array A<br />
ndims(Auxiliary) = 2<br />
<br />
;size(A, i)<br />
The size of dimension i in array A<br />
size(Auxiliary, 2) = 3<br />
<br />
;size(A)<br />
A vector of length ndims(A) containing the dimension sizes of A<br />
size(Auxiliary) = {3,3}<br />
<br />
<br />
;Construction functions<br />
In addition to normal array constructing, a special construction functions can be used.<br />
<br />
;zeros(n1,n2,n3,...)<br />
An array full of zeros with dimensions n1 x n2 x n2 x ... <br />
zeros(2, 2) = {{0,0}, {0,0}}<br />
<br />
;ones(n1,n2,n3,...)<br />
An array full of ones with dimensions n1 x n2 x n2 x ... <br />
ones(2, 2) = {{1,1}, {1,1}}<br />
<br />
;fill(s,n1,n2,n3)<br />
Like zeros() and ones(), but with user defined value (s) for array elements.<br />
fill(3,2,2) = {{3,3}, {3,3}}<br />
<br />
;identity(n)<br />
Creates an n x n integer identity matrix with ones on the diagonal and all other elements zero.<br />
identity(3) =<br />
1 0 0<br />
0 1 0<br />
0 0 1<br />
<br />
;diagonal(v)<br />
Constructs a square matrix with elements of vector v on the diagonal and all other elements zero.<br />
diagonal({1,2,3}) =<br />
1 0 0<br />
0 2 0<br />
0 0 3<br />
<br />
;linspace(x1,x2,n)<br />
Constracts a Real vector from x1 to x2 with n equally spaced elements.<br />
linspace(2,5,4) = {2,3,4,5}<br />
<br />
;Reduction functions<br />
<br />
Reduction functions reduce arrays to scalars.<br />
<br />
;min(A)<br />
Returns the minimum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
min(A) = 1<br />
<br />
;max(A)<br />
Returns the maximum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
max(A) = 4<br />
<br />
;sum(A)<br />
Returns the sum of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
sum(A) = 10 // 1 + 2 + 3 + 4<br />
<br />
;product(A)<br />
Returns the product of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
product(A) = 24 // 1 * 2 * 3 * 4<br />
<br />
<br />
;Using functions with iterators<br />
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.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
AuxiliarySum[E1] = {sum( Auxiliary[ i , E2 ] ) for i in E1} // Result: {6, 15, 24}<br />
<br />
/* Same as:<br />
{sum(Auxiliary[one, E2]), sum(Auxiliary[two, E2]), sum(Auxiliary[three, E2])}<br />
{sum({1,2,3}), sum({4,5,6}), sum({7,8,9})}<br />
*/<br />
<br />
One expression can have multiple iterators. The Modelica specification defines the following format, but it is NOT yet supported in OpenModelica:<br />
{sum(Array[ i, j, E3]) for i in E1, j in E2} // Dimensions reduced from 3 to 2<br />
<br />
To use multiple iterators, use the following format (NOTE the reversed order of iterators!):<br />
{{sum(Array[ i, j, E3]) for j in E2} for i in E1} // Dimensions reduced from 3 to 2<br />
<br />
The range doesn't have to be the whole enumeration. Subranges can also be used.<br />
{sum( Auxiliary[ i , eins : zwei ] ) for i in E1.one : E1.two} // Result: {3, 9}<br />
<br />
/* Same as<br />
{sum(Auxiliary[one, eins : zwei]), sum(Auxiliary[two, eins : zwei])}<br />
{sum({1,2}), sum({4,5})}<br />
*/<br />
<br />
=== Simulation results ===<br />
<br />
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. <br />
<br />
[[File:3x3trend.png|300px|Trend view for a 3x3 variable]]<br />
<br />
The clutter can be reduced by selecting which enumeration indexes are shown in charts. Select an enumeration and tick the indexes 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.<br />
<br />
[[File:ShowInCharts.png|500px|Select indexes to show in charts]]<br />
<br />
<br />
=== Array Variables in Modules ===<br />
<br />
[[File:Replaceable.png|frame|Replaceable enumeration inside a module]]<br />
<br />
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 [[Simantics_System_Dynamics#Modeling|Modeling]]). <br />
<br />
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.<br />
<br />
<br />
<br style="clear: both" /><br />
<br />
In this example, the original enumeration that the modeler used had two indexes. We are using an instance of this module, but we need to use array variables that have three indexes instead of two. We are using two variables and an instance of the module.<br />
<br />
[[File:ReplacingEnumerationConfiguration.png|frame|left|500px|Module configuration for replacing enumerations inside the module]]<br />
<br style="clear: both" /><br />
<br />
In the parent configuration, we have used an enumeration with three indexes in the two variables.<br />
<br />
[[File:Replacing.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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 clickin 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.<br />
<br />
<br />
[[File:ReplacingEnumeration.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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!<br />
<br />
== Functions ==<br />
<br />
Modelica provides a convenient way to use functions in your models. You can create your own functions, import complete function libraries and share function libraries to be used in all of your models. <br />
<br />
=== Creating functions ===<br />
<br />
[[File:NewFunction.png|right]]<br />
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.<br />
<br />
Functions that can be found from Functions -folder can be used in your variable definitions.<br />
<br />
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. <br />
<br />
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.<br />
<br />
Below is an example of a simple function. For more examples, see the built-in functions provided with the tool and [https://www.modelica.org/documents/ Modelica specifications].<br />
<br />
<br style="clear: both" /><br />
<br />
[[File:ExampleFunction.png]]<br />
<br />
=== Function libraries ===<br />
<br />
<br />
[[File:NewFunctionLibrary.png|right]]<br />
<br />
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)).<br />
<br />
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. <br />
<br />
Create a new function library by right-clicking on Functions folder, Shared functions folder or other module library.<br />
<br />
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.<br />
<br />
[[File:SharedFunctions.png]]<br />
<br style="clear: both" /><br />
<br />
=== External functions ===<br />
<br />
Modelica allows you to use external functions that are programmed using C language. Below is a simple example of using a function that returns the sum of two arguments. <br />
<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}<br />
<br />
<br />
[[File:ImportCFunctionLibrary.png|right]]<br />
<br />
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 <br />
(e.g. simantics_home/plugins/org.simantics.openmodelica.win32_x/MinGW/bin/mingw32_gcc.exe -g -O -c ExampleCFunctionCode.c). <br />
<br style="clear: both" /><br />
<br />
[[File:ExampleExternalFunction.png]]<br />
<br />
<br />
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.<br />
<br />
[[File:ExternalFunctionResult.png]]<br />
<br />
<br />
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.<br />
<br />
<br />
Small external C function can also be written directly to the function code in Simantics Sysdyn:<br />
function ExampleExternalFunction<br />
input Real x;<br />
input Real y;<br />
output Real z;<br />
external "C" z=exampleCFunction(x,y) annotation(Include="<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}");<br />
end ExampleExternalFunction;<br />
<br />
=== Modelica functions ===<br />
<br />
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 [[Simantics_System_Dynamics#Builtin_functions|builtin functions for arrays]].<br />
<br />
{|<br />
|abs(x)<br />
|Returns the absolute value of x. Expanded into "(if x >= 0 then x else -x)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|acos(x)<br />
|Inverse cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|asin(x)<br />
|Inverse sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan(x)<br />
|Inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan2(x1,x2)<br />
|four quadrant inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cat(n,A,B,...)<br />
|General concatenation function that concatenates arrays A,B,... along the nth dimension.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|ceil(x)<br />
|Returns the smallest integer not less than x, the closest integer above x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cos(x)<br />
|Cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cosh(x)<br />
|Hyperbolic cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cross(x,y)<br />
|Returns the 3-vector cross product of the 3-vectors x and y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|delay(expr, delayTime)<br />
|Returns the value of expr at the time time-delayTime. The value of expr is returned when time <= time.start + delayTime.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|der(x)<br />
|Time derivative of x. X must be have continuous-time variability.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|div(x, y)<br />
|Returns the algebraic quotient x/y with any fractional part discarted. E.g. div(10,3) = 3.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|edge(b)<br />
|Returns true when the value of the boolean expression b changes. Expanded into (b and not pre(b)).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|exp(x)<br />
|Exponential, base e.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|floor(x)<br />
|Returns the largest integer not greater than x, the closest integer below x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|initial()<br />
|Returns true at the beginning of the simulation. <br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|integer(x)<br />
|Returns the largest integer not greater than x as an integer.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log(x)<br />
|Natural logarithm. (base e, x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log10(x)<br />
|Base 10 logarithm. (x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|mod(x, y)<br />
|Returns the integer modulus of x/y: mod(x,y) = x - floor(x/y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|noEvent(expr)<br />
|noEvent around an expression causes the expression to NOT generate event.<br />
'''Important:''' <br />
:If you want a condition to be checked only on time steps, use noEvent.<br />
:(e.g. if noEvent(value >= 1) then ... else ...)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|pre(x)<br />
|Returns the preceding value of y from time event that has occured before current time.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|rem(x, y)<br />
|Returns the integer remainder of x/y: rem(x,y) = x - div(x,y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sample(start, interval)<br />
|Returns true and triggers time events at times start + i * interval (i=0,1,...).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sign(x)<br />
|Returns -1 if x is negative, 1 if x is positive. Expanded into "(if x > 0 then 1 else if x < 0 then -1 else 0)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sin(x)<br />
|Sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sinh(x)<br />
|Hyperbolic sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sqrt(x)<br />
|Square root of x. The value of x must be greater or equal to 0 or an assertion error occurs.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tan(x)<br />
|Tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tanh(x)<br />
|Hyperbolic tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|terminal()<br />
|Returns true at the end of a successful simulation.<br />
|}<br />
<br />
<br />
<center><br />
[[Simantics]] | ''System Dynamics Modelling''<br />
</center><br />
<br />
----<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Basic System Dynamics Modelling]]'''<br><br />
System dynamics modelling in Simantics is a free modelling tool that is included into the basic installation. This tutorial introduces the basic features of the system dynamics modelling tool.<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Advanced System Dynamics Modelling]]'''<br><br />
This tutorial introduces the more advanced features of the system dynamics modelling tool: Modules and Operating interfaces<br />
<br />
[[Category: Simantics System Dynamics]]</div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:ChartPanelOrientation.png&diff=554File:ChartPanelOrientation.png2012-06-04T11:31:41Z<p>Teemu Lempinen: </p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:ChartPanel.png&diff=553File:ChartPanel.png2012-06-04T11:29:30Z<p>Teemu Lempinen: </p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=Simantics_System_Dynamics&diff=552Simantics System Dynamics2012-06-04T11:17:56Z<p>Teemu Lempinen: /* Pie chart */</p>
<hr />
<div>== Simantics System Dynamics ==<br />
<br />
Simantics System Dynamics is currently the only open source modelling and simulating tool for Simantics. Simantics System Dynamics is under development and will go through some changes in the future. New features will be added and old ones improved according to the needs of the modellers. New features include module libraries and different analysis tools.<br />
<br />
This documentation introduces you to the current version of Simantics System Dynamics. Documentation includes the basic modelling principles and a guide on how to model system dynamics models with Simantics System Dynamics. If you like to get to know the tool better and try modelling and simulating yourself, [[#Installation Instructions|install]] the software and try our [[Tutorial: Basic System Dynamics Modelling|basic]] and [[Tutorial: Advanced System Dynamics Modelling|advanced]] tutorials!<br />
<br />
== Introduction to System Dynamics Simulation ==<br />
<br />
===System Dynamics===<br />
System dynamics is an approach to understanding different organizations, markets and other complex systems and their dynamic behavior. System dynamics modelling in Simantics is a free modelling tool. See [[#Installation Instructions|installation instructions]].<br />
<br />
===Model===<br />
[[File:ModelStructure.png|right|thumb|Model structure]]<br />
System dynamics model is generally understood as the model configuration. In this tool, the model contains also other components. Model can have Operating interfaces that enable the use of the model with simple controls. Operating interfaces are configured separately and when using them, the complex model is hidden from the user. Experiments are the way to simulate the model. In the future, you can have experiments with different configurations, for example different initial values for some parameters. In that way, you don't have to always configure the model for different scenarios. Modules folder contains all the different module types in your model and you can create new module types there. <br />
<br />
<br style="clear: both" /><br />
<br />
===Components===<br />
Most of the components you can use in your models are basic system dynamics components. The modularity of the models introduces two additional components, Modules and Inputs. All the components are explained below.<br />
[[File:ComponentTypes.png|right|frame|Component types]]<br />
;Auxiliary<br />
:Auxiliary is the most basic variable you can use. It represents a single value or a mathematical expression. There are different types of auxiliary variables currently in the system: Auxiliary, Parameter, Constant and WithLookup. Auxiliary is the default type. Parameters are single values that the user can change. When only parameters are changed, the model simulates faster, because the system does not have to recompile the model. WithLookup is a special variable that has an expression and a lookup table. The expresssion defines what value is taken from the defined table.<br />
;Dependency<br />
:Dependency is an arrow that connects two components. It means that the value of the variable from which the arrow starts is used to calculate the value of the variable where the arrow ends.<br />
;Flow<br />
:Flow connects clouds, valves and stocks. Flow represents an actual flow of something from stocks or clouds to stocks or clouds. There has to be at least one valve in a flow and the system creates it automatically, if none of the ends of the flow is a valve.<br />
;Valve<br />
:Valve regulates the rate of a flow. The value of a valve is automatically used in calculating the level of an adjacent stock. Valves behave just like Auxiliary variables but look different and you can connect also flows to them.<br />
;Stock<br />
:The value of a stock variable is an integral of flows leaving and flows arriving to the variable. The integral is calculated automatically from the valves that are connected to the variable with flow connections. You must give an initial value to the stock. Initial value can be a single value or an equation. You can use values of other variables to calculate the initial value.<br />
;Cloud<br />
:Cloud is not a variable. It represents a starting or ending point of a flow, if it is not in the scope of the model.<br />
;Module<br />
:Modules enable structural modeling. Modules are defined just like the basic model configuration, but the module component hides the actual configuration. You can only connect dependency connections into the module and dependency connections from the module must end to Input variables. The interface of the module is defined using input and output variables in the configuration of the module. All variable types can be set as output variables. If a variable is an output variable, its font is bold.<br />
;Input<br />
:Input variables are the way of getting values from other modules. Inputs look like auxiliary variables except their font is italics. You can set a default value to the input variable in case it is not connected to any variable. Connections are made from the modules properties, when the module is populated. Input doesn't have to be connected with an arrow to a module. If the variable has no connections, it can get values from a higher level in the hierarchy. If an input is connected to an output, the output and its module are shown below the variable using dot notation.<br />
<br style="clear: both" /><br />
<br />
===Modeling principles===<br />
<br />
System dynamics modelling is much more than just mathematical formulas and nice graphs. Models are ways of communicating. There are some basic principles in system dynamics modelling that make the models easier to read and understand. You do not have to apply these principles to simulate models, but using them makes it easier for you to communicate your model to others.<br />
<br />
;Variable names<br />
:Variables names should be nouns, not verbs. The names should be positive: for example it is easier to understand that satisfaction decreases than dissatisfaction rises. <br />
<br />
:Variable names can and should have multiple words, if they are needed. Unfortunately current version of the tool does not support spaces in variable names. A good practice is to use CamelCase if name contains multiple words. This means that you start every word woth a capital letter (example: ExampleVariable).<br />
<br />
;Connections<br />
:You should try to avoid overlapping dependency arrows. In some situations, however, it is not possible. Dependencies should also form distinctive loops, if there is a loop. It makes it easier to read and understand the model and its behavior.<br />
<br />
;Graphical annotations<br />
:System dynamics contains usually annotations for loops, polarities, delays and so on. Currently those annotations are not supported, but the support will be added later. Annotations are important, again, for communicating the behavior of the model.<br />
<br />
==Installation Instructions==<br />
<br />
System dynamics tool is a provided with the Simantics platform.<br />
<br />
# [https://www.simantics.org/simantics/download Download installer from Simantics download page]<br />
# Install the program to a directory without spaces. <br />
# Run Simantics-Sysdyn.exe <br /><br />
: (Default path in windows: C:\Simantics\Sysdyn\1.4\simantics-sysdyn\Simantics-Sysdyn.exe)<br />
<br />
[http://www.openmodelica.org/ OpenModelica] is used to build and simulate the models. Simantics platform has integrated OpenModelica 1.7 for Windows environments. For other versions and other environments you need to install [http://www.openmodelica.org/index.php/download OpenModelica].<br />
<br />
== Workbench ==<br />
<br />
[[File:BasicWorkbench.png|center|729px]]<br />
<br />
<br />
# '''Diagram''' <br /> Diagram is the area where you will graphically modify your model. Diagrams are built from elements that can be dragged from Symbols view or populated using shortcut keys. <br />
# '''Model Browser''' <br /> Model browser shows the structure of your model and all items related to it. <br /> Symbols view is stacked with the model browser and used for dragging elements to diagrams.<br />
# '''Properties''' <br /> Property view shows the selected variable's properties. Property view has a different layout depending on the type of the selected component. The view can also have different tabs depending on the component type. Basic tabs are with variables are Equation and Additional information.<br />
# '''Trend''' <br /> Trend view shows the graphical representation of the values of the selected value over time. For the trend to be shown, a simulation has to be run. The view shows always the results of the latest run, but you can save results of a simulation and show them in the same trend with results from another simulation. Values view and Dependencies are stacked with Trend view and can also be used for analyzing the model.<br />
# '''Experiment controls''' <br /> Experiment controls are shown when an experiment is active. Experiment is activated by double clicking an experiment in the model browser. With the experiment control, you can start simulation runs and save simulation results.<br />
<br />
<br /><br />
If you accidentally close a view, you can reopen them from Window->Show View->Other...<br />
<br />
== Modelling ==<br />
<br />
===Basic modelling===<br />
<br />
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.<br />
<br />
[[File:Basic_1.png|right]]<br />
;Creating a new model<br />
:Start a new model by right-clicking the model browser and selecting New->Model or from the main menu File->New Model.<br />
<br style="clear: both" /><br />
<br />
[[File:Basic_2.png|right]]<br />
;Creating a new module type<br />
:Create a new module type by right-clicking on the Modules-folder and selecting New->Module. This creates a new module type that you can populate to your other modules and the model configuration. <br />
<br style="clear: both" /><br />
<br />
;Configuring a model<br />
:Model configuration can be opened by double clicking Configuration in the model browser. <br />
<br />
;Configuring modules<br />
: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 module!<br />
<br />
;Populate variables<br />
:You can drag variables to a diagram from symbol view. You can also populate variables using [[#Shortcut and control keys|shortcut keys]]<br />
<br />
;Populate modules<br />
:Modules are populated from the model browser. Just drag the module you want to populate from the Modules folder to a diagram.<br />
<br />
;Create connections<br />
: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.<br />
: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.<br />
: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.<br />
<br />
;Connections between modules<br />
:'''Outside the module''' <br /><br />
:You can connect variables to variables in modules like this:<br />
MODULE -----> INPUT<br />
or<br />
ANY VARIABLE -----> MODULE <br />
:This is just the visual configuration, but you need those connections to really connect variables in the module's properties.<br />
:In Inputs -tab you select which variables you connect to inputs inside the module. In Outputs -tab you select which variables you lift from the module to inputs outside it.<br />
<br />
:'''Inside the module''' <br /><br />
:Input variables get values from outside the module<br />
<br />
:Output variables can send their values outside the module. From the variable properties, select Additional Information and press Is Output<br />
<br />
;Configure variables<br />
:Select a single variable from diagram or model browser. The properties of the variables are shown in the equation view and you can modify them.<br />
<br />
;Export model<br />
: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 to for example create different versions of the model, create backups or to transport it to another database.<br />
<br />
;Import model<br />
:Right-click on the model browser and select Import->Model. Browse to your .tg file and select open. The model is added to your model browser.<br />
<br />
===Shortcut and control keys===<br />
<br />
Shortcut keys for configuring a model on diagram.<br />
<br />
{|<br />
|Esc <br />
|Cancel operations (e.g. connection and rename).<br />
|-<br />
|Shift + A <br />
|Hover Auxiliary at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + S<br />
|Hover Stock at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + C<br />
|Hover Cloud at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + V<br />
|Hover Valve at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + I<br />
|Hover Input at the cursor position, populate with left mouse button.<br />
|-<br />
|Alt + left mouse button<br />
|Start an arrow from a variable. End to another variable by clicking left mouse button.<br />
|-<br />
|Alt + right mouse button<br />
|Start flow from a variable. End by clicking left mouse button.<br />
<br />
If a flow is not started or ended on to a variable, a cloud will be created to that end. <br /><br />
If a new flow does not have a valve at either end, a valve will be created in the middle of the flow.<br />
|-<br />
|Delete<br />
|Remove selected variables<br />
|-<br />
|Ctrl + left mouse button<br />
|Select multiple variables<br />
|-<br />
|Mouse wheel or<br/>+ and -<br />
|Diagram zoom<br />
|-<br />
|drag(mouse3) or<br/>drag(shift + any mouse button)<br />
|Diagram pan<br />
|-<br />
|Ctrl + C<br />
|Copy selected elements<br />
|-<br />
|Ctrl + X<br />
|Cut selected elements<br />
|-<br />
|Ctrl + V<br />
|Paste copied or cut elements<br />
|-<br />
|G<br />
|Show / hide grid<br />
|-<br />
|R<br />
|Show / hide ruler<br />
|}<br />
<br />
Other shortcut keys can be found selecting Window -> Preferences from the main menu. Keys are located in General -> Keys.<br />
<br />
== Simulation ==<br />
There are three different ways for simulating a model. Different simulations are represented as different types of experiments in Simantics System Dynamics. <br />
<br />
Experiments are created from the context menu of experiments folder in a model. <br />
<br />
[[File:NewExperiment.png]]<br />
<br />
Double-click on an experiment activates it and displays experiment type specific controls in the main tool bar.<br />
<br />
;Normal simulation<br />
: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.<br />
<br />
;Game simulation<br />
:Game simulations allow simulating an arbitrary number of steps, changing parameter values and continuing simulation with the new values from where it previously ended.<br />
<br />
;Simulation playback<br />
:Simulation playback works essentially as the basic experiment, but it offers some additional visualization options.<br />
<br />
== Simulation result and model structure analysis ==<br />
Simulation results can be viewed as trends in trend view or as plain numbers in values view. The views display results of variables that are selected in the workbench. Users can also create [[#Custom charts |custom charts]].<br />
<br />
Model structure can be examined in the Structure view. There are two options: Dependency structures of individual variables or the complete hierarchy structure of the model.<br />
<br />
;Trend<br />
:Shows you the values of the selected variable(s) graphically over the simulation time. You can modify the trend and zoom it using the context menu (right-click) of the trend. <br /> [[File:Trend.png]]<br />
<br />
;Values<br />
:Shows you the values of the selected variable(s) in a table form. If the value has a star (*) at the end, it means that the value is an approximate. There is no value for that variable for the given time step. Selected values can be copied to other software in csv format.<br /> [[File:Values.png]]<br />
<br />
;Compare results<br />
:You can compare different results of the same model by saving simulation results and displaying the saved results side by side with other results. You can save your results after simulating by clicking the save button [[File:Saveresults.png]] on your experiment controls. The saved results appear to model browser under the active experiment. To show the results on trends and tables, right-click on the result and select Show on charts. <br /> [[File:CompareTrend.png]]<br />
<br />
;Dependencies<br />
:Dependencies display which variables affect and which are affected by the selected variable. The direction and number of steps that are traveled from the selected variable can be configured at the bottom of the view. <br /> [[File:Dependencies.png]]<br />
<br />
;Model Hierarchy<br />
:Model Hierarchy displays the hierarchical structure of the model. The module type where a selected variable is located is highlighted.<br /> [[File:ModelHierarchy.png]]<br />
<br />
== Custom charts ==<br />
Custom charts are user-defined displays of simulation result data. They can be used and re-used in various places. The three types of custom charts (line, bar and pie charts) provide model developers means for examining and developing their models and communicating the simulation results to others. <br />
<br />
Custom charts are created to the Charts folder in model browser.<br />
<br />
[[File:NewChart.png | Creating a new chart]]<br />
<br />
Charts are configured the same way as variables: first select the chart from model browser and then configure it in the property view. Charts can be viewed in the same active trend view as any variable by selecting the chart from model browser. In addition to trend view, charts can be populated directly to the model diagram or to a separate chart panel that can contain multiple charts. <br />
<br />
=== Line chart ===<br />
<br />
Line char 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.<br />
<br />
[[File:LineChart.png|Line chart with an array variable]]<br />
<br />
[[File:LineChartGeneral.png|General settings of line chart]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|The title of the chart. Displayed in the chart<br />
|-<br />
|Type<br />
|Line chart (default) or area chart<br />
|-<br />
|Hide<br />
|Options to hide chart grid, title or legend<br />
|-<br />
|'''X-axis'''<br />
|<br />
|-<br />
|Variable<br />
|A variable that is used as the x-axis variable. The default variable is time and it needs not to be typed in the field.<br />
|-<br />
|Label<br />
|Optional other label for the variable than its name<br />
|-<br />
|Min<br />
|Minimum value of the x-axis<br />
|-<br />
|Max<br />
|Maximum value of the x-axis<br />
|-<br />
|Hide<br />
|Options to hide x-axis lable, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
[[File:LineChartAxisAndVariables.png|Axis and variables settings of line chart]]<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed.<br />
|-<br />
|Color<br />
|Color for the lines of this variable<br />
|-<br />
|Line width<br />
|The width of the lines drawn for this variable<br />
|}<br />
There are also configuration options for y-axis. They are displayed when an axis is selected in the Axis and variables tab.<br />
{|<br />
|'''Y-axis'''<br />
|<br />
|-<br />
|Label<br />
|Label of the axis<br />
|-<br />
|Min<br />
|Minimum value in the axis<br />
|-<br />
|Max<br />
|Maximum value in the axis<br />
|-<br />
|Color<br />
|The color of the axis lines, ticks and labels<br />
|-<br />
|Hide<br />
|Options to hide parts of the axis: label, axis line, tick marks, tick labels<br />
|-<br />
|}<br />
<br />
=== Bar chart ===<br />
Bar charts display variables in a certain point in time. The point can be defined for the complete chart in cart'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. <br />
<br />
[[File:BarChartGeneral.png|General bar chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Name is displayed in model browser.<br />
|-<br />
|Title<br />
|The title of the chart. Title is displayed in the chart, if not hidden<br />
|-<br />
|Type<br />
|Normal or stacked. Normal type displays all variables in separate bars. Stacked mode is able to display one-dimensional array variables in stacks.<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Option for hiding grid, title and Legend. Legend is hidden by default since it only contains the information that the current simulation is displayed.<br />
|-<br />
|}<br />
<br />
[[File:BarChartInDiagram.png|Bar chart in a model diagram]]<br />
<br />
Charts can be added to model diagrams simply by dragging the chart from model browser to diagram.<br />
<br />
[[File:BarChartVariable.png|Settings for a variable in bar chart]]<br />
<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|}<br />
[[File:BarChartAxis.png|Settings for axis in bar chart]]<br />
{|<br />
|'''Domain axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for x axis<br />
|-<br />
|Label angle<br />
|Axis labels can be displayed in an angle. This value determines the angle in degrees.<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|'''Range axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for y axis<br />
|-<br />
|Min<br />
|Minimum value of y axis<br />
|-<br />
|Max<br />
|Maximum value of y axis<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
=== Pie chart ===<br />
<br />
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.<br />
<br />
[[File:PieChartGeneral.png|General pie chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|Title The title of the chart. Displayed in the chart<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Options for hiding title, section labels and legend<br />
|-<br />
|}<br />
<br />
[[File:PieChartVariable.png|Variable settings in pie chart]]<br />
{|<br />
|'''Variables'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Color<br />
|Color for the sector of this variable<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|Exploded<br />
|If set, the sector(s) of the variable(s) are "exploded" away from the center of the pie chart<br />
|-<br />
|}<br />
<br />
[[File:PieChartChartPanel.png|Pie chart in chart panel]]<br />
<br />
=== Chart panel ===<br />
<br />
== Multidimensional variables ==<br />
<br />
<br />
=== Modeling ===<br />
<br />
Models with multidimensional variables look just like any other models. The structure of the models is replicated givin multiple indexes to variables. For users with programming background, notation Variable[] may be familiar. In system dynamic modeling we need to give names to the indexes. Instead of using numbers to define the indexes, like in normal programming, we use enumerations. The steps to create a model with multidimensional variables are as follows (with examples):<br />
<br />
# '''Create the model structure''' <BR />Model with multidimensional variables looks just like any other model.<BR /> [[File:ModelWithMultidimensionalVariables.png|300px|Model with multidimensional variables]]<br />
# '''Create Enumerations and define the indexes''' <BR />Enumerations are created by right-clicking configuration and selecting New->Enumeration.<BR /> [[File:NewEnumeration.png|250px|New enumeration]]<BR />Define enumeration indexes by adding as many indexes as you want. Rename the indexes by selecting them and then clicking on them again.<BR />[[File:DefineIndexes.png|200px|Index definitions]]<br />
# '''Add Enumerations for variables''' <BR />Select the variable that you want to be multidimensional. From the Indexes -tab in the property view, move the wanted enumerations to the right. The order of the enumerations does matter.[[File:SelectEnumerations.png|500px|Select enumerations for variables]]<br />
# '''Define equations for all possible indexes''' <BR />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 indexes, so the resulting definition can be {{1,2,3},{4,5,6},{7,8,9}}.<BR />[[File:DefineEquations.png|500px|Define equations for all indexes]]<br />
<br />
<br />
<br />
=== Expressions ===<br />
<br />
Values for all cells in the variable matrix can be defined in a single expression. <br />
<br />
[[File: DefineEquations.png|600px]]<br />
<br />
[[File:DefineEquations2.png|600px]]<br />
<br />
In many situations, it is however more clear to define separate expressions for each cell or blocks. <br />
<br />
# '''Define range for the expression'''<BR /> [[File:DefineRange.png]]<br />
# '''Define the expression''' (dimensions of the defined range and the result of the expression must match!) <BR /> [[File:DefineEquations3.png]]<br />
# '''Create a new expression''' <BR /> [[File:CreateNewExpression.png]]<br />
#''' Select the new expression''' <BR /> [[File:SelectNewExpression.png]]<br />
<br />
Repeat until there is value for each cell. There must be exactly one value for each cell.<br />
<br />
=== Array slices ===<br />
<br />
Many times it is useful to access a slice of a multidimensional variable. In this chapter, we will use the following example variable:<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
The whole variable can be accessed in three different ways:<br />
# Auxiliary<br />
# Auxiliary[E1, E2]<br />
# Auxiliary[:, :]<br />
<br />
The following explains different methods for accessing parts of the variable<br />
<br />
// Single cell<br />
Auxiliary[one, eins] = 1<br />
<br />
// Slices<br />
Auxiliary[one, E2] = {1,2,3}<br />
Auxiliary[E1, zwei] = {{2},{5},{8}}<br />
<br />
// In addition to single cells and the whole enumeration range, a subrange of the enumeration can be used<br />
Auxiliary[two : three, E2] = {{4,5,6},{7,8,9}}<br />
Auxiliary[one : two, zwei : drei] = {{2,3},{5,6}}<br />
<br />
The syntax for accessing parts of variables can be used in both expression range definitions and in expressions.<br />
<br />
=== Arithmetic Operators ===<br />
<br />
Arithmetic operations are defined in Modelica. Below are examples of different operations.<br />
<br />
;Addition and substraction<br />
Addition and substraction are calculated elementwise<br />
<br />
{1,2,3} - {0,2,3} = {1,0,0}<br />
{{2,2},{4,4}} + {{8,8},{1,1}} = {{10,10},{5,5}}<br />
{1,2,3} - {1,2} = ERROR! Different array sizes<br />
<br />
;Division<br />
Division with a scalar<br />
{5,10,15} / 5 = {1,2,3}<br />
5 / {5,10,15} = ERROR! not allowed<br />
<br />
Division with an array<br />
{1,2,3} / {1,2,3} = ERROR! not allowed<br />
<br />
// Elementwise<br />
{1,2,3} ./ {1,2,3} = {1,1,1}<br />
<br />
;Multiplication<br />
<br />
Multiplication with a scalar<br />
{1,2,3} * 2 = {2,4,6}<br />
5 * {1,2,3} = {5,10,15}<br />
<br />
Matrix multiplication with an array<br />
{{3,4},{5,6}} * {1,2} = {11,17}<br />
{{3,4},{5,6}} * {1,2,3} = ERROR! incompatible array sizes<br />
<br />
//Elementwise<br />
{1,2} .* {1,2} = {1,4}<br />
<br />
Real[3,2] c = {{1,2},{3,4},{5,6}}; <br />
Real[2,2] d = {{3,4},{5,6}};<br />
Real[2,2] cd;<br />
cd = c[2:3, :] .* d; // Result: {{9,16},{25,36}}<br />
<br />
=== Builtin Modelica functions ===<br />
<br />
Modelica has some builtin functions that help using multidimensional variables. This chapter introduces some of the builtin functions. <br />
<br />
;Dimension and size functions<br />
<br />
We will use the same example variable as previously.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
;ndims(A)<br />
The number of dimensions in array A<br />
ndims(Auxiliary) = 2<br />
<br />
;size(A, i)<br />
The size of dimension i in array A<br />
size(Auxiliary, 2) = 3<br />
<br />
;size(A)<br />
A vector of length ndims(A) containing the dimension sizes of A<br />
size(Auxiliary) = {3,3}<br />
<br />
<br />
;Construction functions<br />
In addition to normal array constructing, a special construction functions can be used.<br />
<br />
;zeros(n1,n2,n3,...)<br />
An array full of zeros with dimensions n1 x n2 x n2 x ... <br />
zeros(2, 2) = {{0,0}, {0,0}}<br />
<br />
;ones(n1,n2,n3,...)<br />
An array full of ones with dimensions n1 x n2 x n2 x ... <br />
ones(2, 2) = {{1,1}, {1,1}}<br />
<br />
;fill(s,n1,n2,n3)<br />
Like zeros() and ones(), but with user defined value (s) for array elements.<br />
fill(3,2,2) = {{3,3}, {3,3}}<br />
<br />
;identity(n)<br />
Creates an n x n integer identity matrix with ones on the diagonal and all other elements zero.<br />
identity(3) =<br />
1 0 0<br />
0 1 0<br />
0 0 1<br />
<br />
;diagonal(v)<br />
Constructs a square matrix with elements of vector v on the diagonal and all other elements zero.<br />
diagonal({1,2,3}) =<br />
1 0 0<br />
0 2 0<br />
0 0 3<br />
<br />
;linspace(x1,x2,n)<br />
Constracts a Real vector from x1 to x2 with n equally spaced elements.<br />
linspace(2,5,4) = {2,3,4,5}<br />
<br />
;Reduction functions<br />
<br />
Reduction functions reduce arrays to scalars.<br />
<br />
;min(A)<br />
Returns the minimum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
min(A) = 1<br />
<br />
;max(A)<br />
Returns the maximum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
max(A) = 4<br />
<br />
;sum(A)<br />
Returns the sum of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
sum(A) = 10 // 1 + 2 + 3 + 4<br />
<br />
;product(A)<br />
Returns the product of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
product(A) = 24 // 1 * 2 * 3 * 4<br />
<br />
<br />
;Using functions with iterators<br />
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.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
AuxiliarySum[E1] = {sum( Auxiliary[ i , E2 ] ) for i in E1} // Result: {6, 15, 24}<br />
<br />
/* Same as:<br />
{sum(Auxiliary[one, E2]), sum(Auxiliary[two, E2]), sum(Auxiliary[three, E2])}<br />
{sum({1,2,3}), sum({4,5,6}), sum({7,8,9})}<br />
*/<br />
<br />
One expression can have multiple iterators. The Modelica specification defines the following format, but it is NOT yet supported in OpenModelica:<br />
{sum(Array[ i, j, E3]) for i in E1, j in E2} // Dimensions reduced from 3 to 2<br />
<br />
To use multiple iterators, use the following format (NOTE the reversed order of iterators!):<br />
{{sum(Array[ i, j, E3]) for j in E2} for i in E1} // Dimensions reduced from 3 to 2<br />
<br />
The range doesn't have to be the whole enumeration. Subranges can also be used.<br />
{sum( Auxiliary[ i , eins : zwei ] ) for i in E1.one : E1.two} // Result: {3, 9}<br />
<br />
/* Same as<br />
{sum(Auxiliary[one, eins : zwei]), sum(Auxiliary[two, eins : zwei])}<br />
{sum({1,2}), sum({4,5})}<br />
*/<br />
<br />
=== Simulation results ===<br />
<br />
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. <br />
<br />
[[File:3x3trend.png|300px|Trend view for a 3x3 variable]]<br />
<br />
The clutter can be reduced by selecting which enumeration indexes are shown in charts. Select an enumeration and tick the indexes 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.<br />
<br />
[[File:ShowInCharts.png|500px|Select indexes to show in charts]]<br />
<br />
<br />
=== Array Variables in Modules ===<br />
<br />
[[File:Replaceable.png|frame|Replaceable enumeration inside a module]]<br />
<br />
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 [[Simantics_System_Dynamics#Modeling|Modeling]]). <br />
<br />
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.<br />
<br />
<br />
<br style="clear: both" /><br />
<br />
In this example, the original enumeration that the modeler used had two indexes. We are using an instance of this module, but we need to use array variables that have three indexes instead of two. We are using two variables and an instance of the module.<br />
<br />
[[File:ReplacingEnumerationConfiguration.png|frame|left|500px|Module configuration for replacing enumerations inside the module]]<br />
<br style="clear: both" /><br />
<br />
In the parent configuration, we have used an enumeration with three indexes in the two variables.<br />
<br />
[[File:Replacing.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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 clickin 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.<br />
<br />
<br />
[[File:ReplacingEnumeration.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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!<br />
<br />
== Functions ==<br />
<br />
Modelica provides a convenient way to use functions in your models. You can create your own functions, import complete function libraries and share function libraries to be used in all of your models. <br />
<br />
=== Creating functions ===<br />
<br />
[[File:NewFunction.png|right]]<br />
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.<br />
<br />
Functions that can be found from Functions -folder can be used in your variable definitions.<br />
<br />
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. <br />
<br />
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.<br />
<br />
Below is an example of a simple function. For more examples, see the built-in functions provided with the tool and [https://www.modelica.org/documents/ Modelica specifications].<br />
<br />
<br style="clear: both" /><br />
<br />
[[File:ExampleFunction.png]]<br />
<br />
=== Function libraries ===<br />
<br />
<br />
[[File:NewFunctionLibrary.png|right]]<br />
<br />
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)).<br />
<br />
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. <br />
<br />
Create a new function library by right-clicking on Functions folder, Shared functions folder or other module library.<br />
<br />
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.<br />
<br />
[[File:SharedFunctions.png]]<br />
<br style="clear: both" /><br />
<br />
=== External functions ===<br />
<br />
Modelica allows you to use external functions that are programmed using C language. Below is a simple example of using a function that returns the sum of two arguments. <br />
<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}<br />
<br />
<br />
[[File:ImportCFunctionLibrary.png|right]]<br />
<br />
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 <br />
(e.g. simantics_home/plugins/org.simantics.openmodelica.win32_x/MinGW/bin/mingw32_gcc.exe -g -O -c ExampleCFunctionCode.c). <br />
<br style="clear: both" /><br />
<br />
[[File:ExampleExternalFunction.png]]<br />
<br />
<br />
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.<br />
<br />
[[File:ExternalFunctionResult.png]]<br />
<br />
<br />
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.<br />
<br />
<br />
Small external C function can also be written directly to the function code in Simantics Sysdyn:<br />
function ExampleExternalFunction<br />
input Real x;<br />
input Real y;<br />
output Real z;<br />
external "C" z=exampleCFunction(x,y) annotation(Include="<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}");<br />
end ExampleExternalFunction;<br />
<br />
=== Modelica functions ===<br />
<br />
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 [[Simantics_System_Dynamics#Builtin_functions|builtin functions for arrays]].<br />
<br />
{|<br />
|abs(x)<br />
|Returns the absolute value of x. Expanded into "(if x >= 0 then x else -x)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|acos(x)<br />
|Inverse cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|asin(x)<br />
|Inverse sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan(x)<br />
|Inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan2(x1,x2)<br />
|four quadrant inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cat(n,A,B,...)<br />
|General concatenation function that concatenates arrays A,B,... along the nth dimension.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|ceil(x)<br />
|Returns the smallest integer not less than x, the closest integer above x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cos(x)<br />
|Cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cosh(x)<br />
|Hyperbolic cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cross(x,y)<br />
|Returns the 3-vector cross product of the 3-vectors x and y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|delay(expr, delayTime)<br />
|Returns the value of expr at the time time-delayTime. The value of expr is returned when time <= time.start + delayTime.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|der(x)<br />
|Time derivative of x. X must be have continuous-time variability.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|div(x, y)<br />
|Returns the algebraic quotient x/y with any fractional part discarted. E.g. div(10,3) = 3.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|edge(b)<br />
|Returns true when the value of the boolean expression b changes. Expanded into (b and not pre(b)).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|exp(x)<br />
|Exponential, base e.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|floor(x)<br />
|Returns the largest integer not greater than x, the closest integer below x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|initial()<br />
|Returns true at the beginning of the simulation. <br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|integer(x)<br />
|Returns the largest integer not greater than x as an integer.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log(x)<br />
|Natural logarithm. (base e, x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log10(x)<br />
|Base 10 logarithm. (x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|mod(x, y)<br />
|Returns the integer modulus of x/y: mod(x,y) = x - floor(x/y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|noEvent(expr)<br />
|noEvent around an expression causes the expression to NOT generate event.<br />
'''Important:''' <br />
:If you want a condition to be checked only on time steps, use noEvent.<br />
:(e.g. if noEvent(value >= 1) then ... else ...)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|pre(x)<br />
|Returns the preceding value of y from time event that has occured before current time.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|rem(x, y)<br />
|Returns the integer remainder of x/y: rem(x,y) = x - div(x,y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sample(start, interval)<br />
|Returns true and triggers time events at times start + i * interval (i=0,1,...).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sign(x)<br />
|Returns -1 if x is negative, 1 if x is positive. Expanded into "(if x > 0 then 1 else if x < 0 then -1 else 0)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sin(x)<br />
|Sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sinh(x)<br />
|Hyperbolic sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sqrt(x)<br />
|Square root of x. The value of x must be greater or equal to 0 or an assertion error occurs.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tan(x)<br />
|Tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tanh(x)<br />
|Hyperbolic tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|terminal()<br />
|Returns true at the end of a successful simulation.<br />
|}<br />
<br />
<br />
<center><br />
[[Simantics]] | ''System Dynamics Modelling''<br />
</center><br />
<br />
----<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Basic System Dynamics Modelling]]'''<br><br />
System dynamics modelling in Simantics is a free modelling tool that is included into the basic installation. This tutorial introduces the basic features of the system dynamics modelling tool.<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Advanced System Dynamics Modelling]]'''<br><br />
This tutorial introduces the more advanced features of the system dynamics modelling tool: Modules and Operating interfaces<br />
<br />
[[Category: Simantics System Dynamics]]</div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:PieChartChartPanel.png&diff=551File:PieChartChartPanel.png2012-06-04T10:24:58Z<p>Teemu Lempinen: </p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:PieChartVariable.png&diff=550File:PieChartVariable.png2012-06-04T10:24:54Z<p>Teemu Lempinen: </p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:PieChartGeneral.png&diff=549File:PieChartGeneral.png2012-06-04T10:24:50Z<p>Teemu Lempinen: </p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=Simantics_System_Dynamics&diff=548Simantics System Dynamics2012-06-04T10:12:28Z<p>Teemu Lempinen: /* Bar chart */</p>
<hr />
<div>== Simantics System Dynamics ==<br />
<br />
Simantics System Dynamics is currently the only open source modelling and simulating tool for Simantics. Simantics System Dynamics is under development and will go through some changes in the future. New features will be added and old ones improved according to the needs of the modellers. New features include module libraries and different analysis tools.<br />
<br />
This documentation introduces you to the current version of Simantics System Dynamics. Documentation includes the basic modelling principles and a guide on how to model system dynamics models with Simantics System Dynamics. If you like to get to know the tool better and try modelling and simulating yourself, [[#Installation Instructions|install]] the software and try our [[Tutorial: Basic System Dynamics Modelling|basic]] and [[Tutorial: Advanced System Dynamics Modelling|advanced]] tutorials!<br />
<br />
== Introduction to System Dynamics Simulation ==<br />
<br />
===System Dynamics===<br />
System dynamics is an approach to understanding different organizations, markets and other complex systems and their dynamic behavior. System dynamics modelling in Simantics is a free modelling tool. See [[#Installation Instructions|installation instructions]].<br />
<br />
===Model===<br />
[[File:ModelStructure.png|right|thumb|Model structure]]<br />
System dynamics model is generally understood as the model configuration. In this tool, the model contains also other components. Model can have Operating interfaces that enable the use of the model with simple controls. Operating interfaces are configured separately and when using them, the complex model is hidden from the user. Experiments are the way to simulate the model. In the future, you can have experiments with different configurations, for example different initial values for some parameters. In that way, you don't have to always configure the model for different scenarios. Modules folder contains all the different module types in your model and you can create new module types there. <br />
<br />
<br style="clear: both" /><br />
<br />
===Components===<br />
Most of the components you can use in your models are basic system dynamics components. The modularity of the models introduces two additional components, Modules and Inputs. All the components are explained below.<br />
[[File:ComponentTypes.png|right|frame|Component types]]<br />
;Auxiliary<br />
:Auxiliary is the most basic variable you can use. It represents a single value or a mathematical expression. There are different types of auxiliary variables currently in the system: Auxiliary, Parameter, Constant and WithLookup. Auxiliary is the default type. Parameters are single values that the user can change. When only parameters are changed, the model simulates faster, because the system does not have to recompile the model. WithLookup is a special variable that has an expression and a lookup table. The expresssion defines what value is taken from the defined table.<br />
;Dependency<br />
:Dependency is an arrow that connects two components. It means that the value of the variable from which the arrow starts is used to calculate the value of the variable where the arrow ends.<br />
;Flow<br />
:Flow connects clouds, valves and stocks. Flow represents an actual flow of something from stocks or clouds to stocks or clouds. There has to be at least one valve in a flow and the system creates it automatically, if none of the ends of the flow is a valve.<br />
;Valve<br />
:Valve regulates the rate of a flow. The value of a valve is automatically used in calculating the level of an adjacent stock. Valves behave just like Auxiliary variables but look different and you can connect also flows to them.<br />
;Stock<br />
:The value of a stock variable is an integral of flows leaving and flows arriving to the variable. The integral is calculated automatically from the valves that are connected to the variable with flow connections. You must give an initial value to the stock. Initial value can be a single value or an equation. You can use values of other variables to calculate the initial value.<br />
;Cloud<br />
:Cloud is not a variable. It represents a starting or ending point of a flow, if it is not in the scope of the model.<br />
;Module<br />
:Modules enable structural modeling. Modules are defined just like the basic model configuration, but the module component hides the actual configuration. You can only connect dependency connections into the module and dependency connections from the module must end to Input variables. The interface of the module is defined using input and output variables in the configuration of the module. All variable types can be set as output variables. If a variable is an output variable, its font is bold.<br />
;Input<br />
:Input variables are the way of getting values from other modules. Inputs look like auxiliary variables except their font is italics. You can set a default value to the input variable in case it is not connected to any variable. Connections are made from the modules properties, when the module is populated. Input doesn't have to be connected with an arrow to a module. If the variable has no connections, it can get values from a higher level in the hierarchy. If an input is connected to an output, the output and its module are shown below the variable using dot notation.<br />
<br style="clear: both" /><br />
<br />
===Modeling principles===<br />
<br />
System dynamics modelling is much more than just mathematical formulas and nice graphs. Models are ways of communicating. There are some basic principles in system dynamics modelling that make the models easier to read and understand. You do not have to apply these principles to simulate models, but using them makes it easier for you to communicate your model to others.<br />
<br />
;Variable names<br />
:Variables names should be nouns, not verbs. The names should be positive: for example it is easier to understand that satisfaction decreases than dissatisfaction rises. <br />
<br />
:Variable names can and should have multiple words, if they are needed. Unfortunately current version of the tool does not support spaces in variable names. A good practice is to use CamelCase if name contains multiple words. This means that you start every word woth a capital letter (example: ExampleVariable).<br />
<br />
;Connections<br />
:You should try to avoid overlapping dependency arrows. In some situations, however, it is not possible. Dependencies should also form distinctive loops, if there is a loop. It makes it easier to read and understand the model and its behavior.<br />
<br />
;Graphical annotations<br />
:System dynamics contains usually annotations for loops, polarities, delays and so on. Currently those annotations are not supported, but the support will be added later. Annotations are important, again, for communicating the behavior of the model.<br />
<br />
==Installation Instructions==<br />
<br />
System dynamics tool is a provided with the Simantics platform.<br />
<br />
# [https://www.simantics.org/simantics/download Download installer from Simantics download page]<br />
# Install the program to a directory without spaces. <br />
# Run Simantics-Sysdyn.exe <br /><br />
: (Default path in windows: C:\Simantics\Sysdyn\1.4\simantics-sysdyn\Simantics-Sysdyn.exe)<br />
<br />
[http://www.openmodelica.org/ OpenModelica] is used to build and simulate the models. Simantics platform has integrated OpenModelica 1.7 for Windows environments. For other versions and other environments you need to install [http://www.openmodelica.org/index.php/download OpenModelica].<br />
<br />
== Workbench ==<br />
<br />
[[File:BasicWorkbench.png|center|729px]]<br />
<br />
<br />
# '''Diagram''' <br /> Diagram is the area where you will graphically modify your model. Diagrams are built from elements that can be dragged from Symbols view or populated using shortcut keys. <br />
# '''Model Browser''' <br /> Model browser shows the structure of your model and all items related to it. <br /> Symbols view is stacked with the model browser and used for dragging elements to diagrams.<br />
# '''Properties''' <br /> Property view shows the selected variable's properties. Property view has a different layout depending on the type of the selected component. The view can also have different tabs depending on the component type. Basic tabs are with variables are Equation and Additional information.<br />
# '''Trend''' <br /> Trend view shows the graphical representation of the values of the selected value over time. For the trend to be shown, a simulation has to be run. The view shows always the results of the latest run, but you can save results of a simulation and show them in the same trend with results from another simulation. Values view and Dependencies are stacked with Trend view and can also be used for analyzing the model.<br />
# '''Experiment controls''' <br /> Experiment controls are shown when an experiment is active. Experiment is activated by double clicking an experiment in the model browser. With the experiment control, you can start simulation runs and save simulation results.<br />
<br />
<br /><br />
If you accidentally close a view, you can reopen them from Window->Show View->Other...<br />
<br />
== Modelling ==<br />
<br />
===Basic modelling===<br />
<br />
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.<br />
<br />
[[File:Basic_1.png|right]]<br />
;Creating a new model<br />
:Start a new model by right-clicking the model browser and selecting New->Model or from the main menu File->New Model.<br />
<br style="clear: both" /><br />
<br />
[[File:Basic_2.png|right]]<br />
;Creating a new module type<br />
:Create a new module type by right-clicking on the Modules-folder and selecting New->Module. This creates a new module type that you can populate to your other modules and the model configuration. <br />
<br style="clear: both" /><br />
<br />
;Configuring a model<br />
:Model configuration can be opened by double clicking Configuration in the model browser. <br />
<br />
;Configuring modules<br />
: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 module!<br />
<br />
;Populate variables<br />
:You can drag variables to a diagram from symbol view. You can also populate variables using [[#Shortcut and control keys|shortcut keys]]<br />
<br />
;Populate modules<br />
:Modules are populated from the model browser. Just drag the module you want to populate from the Modules folder to a diagram.<br />
<br />
;Create connections<br />
: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.<br />
: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.<br />
: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.<br />
<br />
;Connections between modules<br />
:'''Outside the module''' <br /><br />
:You can connect variables to variables in modules like this:<br />
MODULE -----> INPUT<br />
or<br />
ANY VARIABLE -----> MODULE <br />
:This is just the visual configuration, but you need those connections to really connect variables in the module's properties.<br />
:In Inputs -tab you select which variables you connect to inputs inside the module. In Outputs -tab you select which variables you lift from the module to inputs outside it.<br />
<br />
:'''Inside the module''' <br /><br />
:Input variables get values from outside the module<br />
<br />
:Output variables can send their values outside the module. From the variable properties, select Additional Information and press Is Output<br />
<br />
;Configure variables<br />
:Select a single variable from diagram or model browser. The properties of the variables are shown in the equation view and you can modify them.<br />
<br />
;Export model<br />
: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 to for example create different versions of the model, create backups or to transport it to another database.<br />
<br />
;Import model<br />
:Right-click on the model browser and select Import->Model. Browse to your .tg file and select open. The model is added to your model browser.<br />
<br />
===Shortcut and control keys===<br />
<br />
Shortcut keys for configuring a model on diagram.<br />
<br />
{|<br />
|Esc <br />
|Cancel operations (e.g. connection and rename).<br />
|-<br />
|Shift + A <br />
|Hover Auxiliary at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + S<br />
|Hover Stock at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + C<br />
|Hover Cloud at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + V<br />
|Hover Valve at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + I<br />
|Hover Input at the cursor position, populate with left mouse button.<br />
|-<br />
|Alt + left mouse button<br />
|Start an arrow from a variable. End to another variable by clicking left mouse button.<br />
|-<br />
|Alt + right mouse button<br />
|Start flow from a variable. End by clicking left mouse button.<br />
<br />
If a flow is not started or ended on to a variable, a cloud will be created to that end. <br /><br />
If a new flow does not have a valve at either end, a valve will be created in the middle of the flow.<br />
|-<br />
|Delete<br />
|Remove selected variables<br />
|-<br />
|Ctrl + left mouse button<br />
|Select multiple variables<br />
|-<br />
|Mouse wheel or<br/>+ and -<br />
|Diagram zoom<br />
|-<br />
|drag(mouse3) or<br/>drag(shift + any mouse button)<br />
|Diagram pan<br />
|-<br />
|Ctrl + C<br />
|Copy selected elements<br />
|-<br />
|Ctrl + X<br />
|Cut selected elements<br />
|-<br />
|Ctrl + V<br />
|Paste copied or cut elements<br />
|-<br />
|G<br />
|Show / hide grid<br />
|-<br />
|R<br />
|Show / hide ruler<br />
|}<br />
<br />
Other shortcut keys can be found selecting Window -> Preferences from the main menu. Keys are located in General -> Keys.<br />
<br />
== Simulation ==<br />
There are three different ways for simulating a model. Different simulations are represented as different types of experiments in Simantics System Dynamics. <br />
<br />
Experiments are created from the context menu of experiments folder in a model. <br />
<br />
[[File:NewExperiment.png]]<br />
<br />
Double-click on an experiment activates it and displays experiment type specific controls in the main tool bar.<br />
<br />
;Normal simulation<br />
: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.<br />
<br />
;Game simulation<br />
:Game simulations allow simulating an arbitrary number of steps, changing parameter values and continuing simulation with the new values from where it previously ended.<br />
<br />
;Simulation playback<br />
:Simulation playback works essentially as the basic experiment, but it offers some additional visualization options.<br />
<br />
== Simulation result and model structure analysis ==<br />
Simulation results can be viewed as trends in trend view or as plain numbers in values view. The views display results of variables that are selected in the workbench. Users can also create [[#Custom charts |custom charts]].<br />
<br />
Model structure can be examined in the Structure view. There are two options: Dependency structures of individual variables or the complete hierarchy structure of the model.<br />
<br />
;Trend<br />
:Shows you the values of the selected variable(s) graphically over the simulation time. You can modify the trend and zoom it using the context menu (right-click) of the trend. <br /> [[File:Trend.png]]<br />
<br />
;Values<br />
:Shows you the values of the selected variable(s) in a table form. If the value has a star (*) at the end, it means that the value is an approximate. There is no value for that variable for the given time step. Selected values can be copied to other software in csv format.<br /> [[File:Values.png]]<br />
<br />
;Compare results<br />
:You can compare different results of the same model by saving simulation results and displaying the saved results side by side with other results. You can save your results after simulating by clicking the save button [[File:Saveresults.png]] on your experiment controls. The saved results appear to model browser under the active experiment. To show the results on trends and tables, right-click on the result and select Show on charts. <br /> [[File:CompareTrend.png]]<br />
<br />
;Dependencies<br />
:Dependencies display which variables affect and which are affected by the selected variable. The direction and number of steps that are traveled from the selected variable can be configured at the bottom of the view. <br /> [[File:Dependencies.png]]<br />
<br />
;Model Hierarchy<br />
:Model Hierarchy displays the hierarchical structure of the model. The module type where a selected variable is located is highlighted.<br /> [[File:ModelHierarchy.png]]<br />
<br />
== Custom charts ==<br />
Custom charts are user-defined displays of simulation result data. They can be used and re-used in various places. The three types of custom charts (line, bar and pie charts) provide model developers means for examining and developing their models and communicating the simulation results to others. <br />
<br />
Custom charts are created to the Charts folder in model browser.<br />
<br />
[[File:NewChart.png | Creating a new chart]]<br />
<br />
Charts are configured the same way as variables: first select the chart from model browser and then configure it in the property view. Charts can be viewed in the same active trend view as any variable by selecting the chart from model browser. In addition to trend view, charts can be populated directly to the model diagram or to a separate chart panel that can contain multiple charts. <br />
<br />
=== Line chart ===<br />
<br />
Line char 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.<br />
<br />
[[File:LineChart.png|Line chart with an array variable]]<br />
<br />
[[File:LineChartGeneral.png|General settings of line chart]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|The title of the chart. Displayed in the chart<br />
|-<br />
|Type<br />
|Line chart (default) or area chart<br />
|-<br />
|Hide<br />
|Options to hide chart grid, title or legend<br />
|-<br />
|'''X-axis'''<br />
|<br />
|-<br />
|Variable<br />
|A variable that is used as the x-axis variable. The default variable is time and it needs not to be typed in the field.<br />
|-<br />
|Label<br />
|Optional other label for the variable than its name<br />
|-<br />
|Min<br />
|Minimum value of the x-axis<br />
|-<br />
|Max<br />
|Maximum value of the x-axis<br />
|-<br />
|Hide<br />
|Options to hide x-axis lable, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
[[File:LineChartAxisAndVariables.png|Axis and variables settings of line chart]]<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed.<br />
|-<br />
|Color<br />
|Color for the lines of this variable<br />
|-<br />
|Line width<br />
|The width of the lines drawn for this variable<br />
|}<br />
There are also configuration options for y-axis. They are displayed when an axis is selected in the Axis and variables tab.<br />
{|<br />
|'''Y-axis'''<br />
|<br />
|-<br />
|Label<br />
|Label of the axis<br />
|-<br />
|Min<br />
|Minimum value in the axis<br />
|-<br />
|Max<br />
|Maximum value in the axis<br />
|-<br />
|Color<br />
|The color of the axis lines, ticks and labels<br />
|-<br />
|Hide<br />
|Options to hide parts of the axis: label, axis line, tick marks, tick labels<br />
|-<br />
|}<br />
<br />
=== Bar chart ===<br />
Bar charts display variables in a certain point in time. The point can be defined for the complete chart in cart'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. <br />
<br />
[[File:BarChartGeneral.png|General bar chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Name is displayed in model browser.<br />
|-<br />
|Title<br />
|The title of the chart. Title is displayed in the chart, if not hidden<br />
|-<br />
|Type<br />
|Normal or stacked. Normal type displays all variables in separate bars. Stacked mode is able to display one-dimensional array variables in stacks.<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Option for hiding grid, title and Legend. Legend is hidden by default since it only contains the information that the current simulation is displayed.<br />
|-<br />
|}<br />
<br />
[[File:BarChartInDiagram.png|Bar chart in a model diagram]]<br />
<br />
Charts can be added to model diagrams simply by dragging the chart from model browser to diagram.<br />
<br />
[[File:BarChartVariable.png|Settings for a variable in bar chart]]<br />
<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Add / Remove<br />
|Add or remove variables<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed<br />
|-<br />
|Time<br />
|The time for which the value of this variable is displayed. If this is empty, a general (or default) value of the time is used.<br />
|-<br />
|}<br />
[[File:BarChartAxis.png|Settings for axis in bar chart]]<br />
{|<br />
|'''Domain axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for x axis<br />
|-<br />
|Label angle<br />
|Axis labels can be displayed in an angle. This value determines the angle in degrees.<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|'''Range axis'''<br />
|<br />
|-<br />
|Label<br />
|An optional label for y axis<br />
|-<br />
|Min<br />
|Minimum value of y axis<br />
|-<br />
|Max<br />
|Maximum value of y axis<br />
|-<br />
|Color<br />
|The color of the axis line, tick lines and labels<br />
|-<br />
|Hide<br />
|Options for hiding axis label, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
=== Pie chart ===<br />
<br />
<br />
=== Chart panel ===<br />
<br />
== Multidimensional variables ==<br />
<br />
<br />
=== Modeling ===<br />
<br />
Models with multidimensional variables look just like any other models. The structure of the models is replicated givin multiple indexes to variables. For users with programming background, notation Variable[] may be familiar. In system dynamic modeling we need to give names to the indexes. Instead of using numbers to define the indexes, like in normal programming, we use enumerations. The steps to create a model with multidimensional variables are as follows (with examples):<br />
<br />
# '''Create the model structure''' <BR />Model with multidimensional variables looks just like any other model.<BR /> [[File:ModelWithMultidimensionalVariables.png|300px|Model with multidimensional variables]]<br />
# '''Create Enumerations and define the indexes''' <BR />Enumerations are created by right-clicking configuration and selecting New->Enumeration.<BR /> [[File:NewEnumeration.png|250px|New enumeration]]<BR />Define enumeration indexes by adding as many indexes as you want. Rename the indexes by selecting them and then clicking on them again.<BR />[[File:DefineIndexes.png|200px|Index definitions]]<br />
# '''Add Enumerations for variables''' <BR />Select the variable that you want to be multidimensional. From the Indexes -tab in the property view, move the wanted enumerations to the right. The order of the enumerations does matter.[[File:SelectEnumerations.png|500px|Select enumerations for variables]]<br />
# '''Define equations for all possible indexes''' <BR />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 indexes, so the resulting definition can be {{1,2,3},{4,5,6},{7,8,9}}.<BR />[[File:DefineEquations.png|500px|Define equations for all indexes]]<br />
<br />
<br />
<br />
=== Expressions ===<br />
<br />
Values for all cells in the variable matrix can be defined in a single expression. <br />
<br />
[[File: DefineEquations.png|600px]]<br />
<br />
[[File:DefineEquations2.png|600px]]<br />
<br />
In many situations, it is however more clear to define separate expressions for each cell or blocks. <br />
<br />
# '''Define range for the expression'''<BR /> [[File:DefineRange.png]]<br />
# '''Define the expression''' (dimensions of the defined range and the result of the expression must match!) <BR /> [[File:DefineEquations3.png]]<br />
# '''Create a new expression''' <BR /> [[File:CreateNewExpression.png]]<br />
#''' Select the new expression''' <BR /> [[File:SelectNewExpression.png]]<br />
<br />
Repeat until there is value for each cell. There must be exactly one value for each cell.<br />
<br />
=== Array slices ===<br />
<br />
Many times it is useful to access a slice of a multidimensional variable. In this chapter, we will use the following example variable:<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
The whole variable can be accessed in three different ways:<br />
# Auxiliary<br />
# Auxiliary[E1, E2]<br />
# Auxiliary[:, :]<br />
<br />
The following explains different methods for accessing parts of the variable<br />
<br />
// Single cell<br />
Auxiliary[one, eins] = 1<br />
<br />
// Slices<br />
Auxiliary[one, E2] = {1,2,3}<br />
Auxiliary[E1, zwei] = {{2},{5},{8}}<br />
<br />
// In addition to single cells and the whole enumeration range, a subrange of the enumeration can be used<br />
Auxiliary[two : three, E2] = {{4,5,6},{7,8,9}}<br />
Auxiliary[one : two, zwei : drei] = {{2,3},{5,6}}<br />
<br />
The syntax for accessing parts of variables can be used in both expression range definitions and in expressions.<br />
<br />
=== Arithmetic Operators ===<br />
<br />
Arithmetic operations are defined in Modelica. Below are examples of different operations.<br />
<br />
;Addition and substraction<br />
Addition and substraction are calculated elementwise<br />
<br />
{1,2,3} - {0,2,3} = {1,0,0}<br />
{{2,2},{4,4}} + {{8,8},{1,1}} = {{10,10},{5,5}}<br />
{1,2,3} - {1,2} = ERROR! Different array sizes<br />
<br />
;Division<br />
Division with a scalar<br />
{5,10,15} / 5 = {1,2,3}<br />
5 / {5,10,15} = ERROR! not allowed<br />
<br />
Division with an array<br />
{1,2,3} / {1,2,3} = ERROR! not allowed<br />
<br />
// Elementwise<br />
{1,2,3} ./ {1,2,3} = {1,1,1}<br />
<br />
;Multiplication<br />
<br />
Multiplication with a scalar<br />
{1,2,3} * 2 = {2,4,6}<br />
5 * {1,2,3} = {5,10,15}<br />
<br />
Matrix multiplication with an array<br />
{{3,4},{5,6}} * {1,2} = {11,17}<br />
{{3,4},{5,6}} * {1,2,3} = ERROR! incompatible array sizes<br />
<br />
//Elementwise<br />
{1,2} .* {1,2} = {1,4}<br />
<br />
Real[3,2] c = {{1,2},{3,4},{5,6}}; <br />
Real[2,2] d = {{3,4},{5,6}};<br />
Real[2,2] cd;<br />
cd = c[2:3, :] .* d; // Result: {{9,16},{25,36}}<br />
<br />
=== Builtin Modelica functions ===<br />
<br />
Modelica has some builtin functions that help using multidimensional variables. This chapter introduces some of the builtin functions. <br />
<br />
;Dimension and size functions<br />
<br />
We will use the same example variable as previously.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
;ndims(A)<br />
The number of dimensions in array A<br />
ndims(Auxiliary) = 2<br />
<br />
;size(A, i)<br />
The size of dimension i in array A<br />
size(Auxiliary, 2) = 3<br />
<br />
;size(A)<br />
A vector of length ndims(A) containing the dimension sizes of A<br />
size(Auxiliary) = {3,3}<br />
<br />
<br />
;Construction functions<br />
In addition to normal array constructing, a special construction functions can be used.<br />
<br />
;zeros(n1,n2,n3,...)<br />
An array full of zeros with dimensions n1 x n2 x n2 x ... <br />
zeros(2, 2) = {{0,0}, {0,0}}<br />
<br />
;ones(n1,n2,n3,...)<br />
An array full of ones with dimensions n1 x n2 x n2 x ... <br />
ones(2, 2) = {{1,1}, {1,1}}<br />
<br />
;fill(s,n1,n2,n3)<br />
Like zeros() and ones(), but with user defined value (s) for array elements.<br />
fill(3,2,2) = {{3,3}, {3,3}}<br />
<br />
;identity(n)<br />
Creates an n x n integer identity matrix with ones on the diagonal and all other elements zero.<br />
identity(3) =<br />
1 0 0<br />
0 1 0<br />
0 0 1<br />
<br />
;diagonal(v)<br />
Constructs a square matrix with elements of vector v on the diagonal and all other elements zero.<br />
diagonal({1,2,3}) =<br />
1 0 0<br />
0 2 0<br />
0 0 3<br />
<br />
;linspace(x1,x2,n)<br />
Constracts a Real vector from x1 to x2 with n equally spaced elements.<br />
linspace(2,5,4) = {2,3,4,5}<br />
<br />
;Reduction functions<br />
<br />
Reduction functions reduce arrays to scalars.<br />
<br />
;min(A)<br />
Returns the minimum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
min(A) = 1<br />
<br />
;max(A)<br />
Returns the maximum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
max(A) = 4<br />
<br />
;sum(A)<br />
Returns the sum of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
sum(A) = 10 // 1 + 2 + 3 + 4<br />
<br />
;product(A)<br />
Returns the product of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
product(A) = 24 // 1 * 2 * 3 * 4<br />
<br />
<br />
;Using functions with iterators<br />
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.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
AuxiliarySum[E1] = {sum( Auxiliary[ i , E2 ] ) for i in E1} // Result: {6, 15, 24}<br />
<br />
/* Same as:<br />
{sum(Auxiliary[one, E2]), sum(Auxiliary[two, E2]), sum(Auxiliary[three, E2])}<br />
{sum({1,2,3}), sum({4,5,6}), sum({7,8,9})}<br />
*/<br />
<br />
One expression can have multiple iterators. The Modelica specification defines the following format, but it is NOT yet supported in OpenModelica:<br />
{sum(Array[ i, j, E3]) for i in E1, j in E2} // Dimensions reduced from 3 to 2<br />
<br />
To use multiple iterators, use the following format (NOTE the reversed order of iterators!):<br />
{{sum(Array[ i, j, E3]) for j in E2} for i in E1} // Dimensions reduced from 3 to 2<br />
<br />
The range doesn't have to be the whole enumeration. Subranges can also be used.<br />
{sum( Auxiliary[ i , eins : zwei ] ) for i in E1.one : E1.two} // Result: {3, 9}<br />
<br />
/* Same as<br />
{sum(Auxiliary[one, eins : zwei]), sum(Auxiliary[two, eins : zwei])}<br />
{sum({1,2}), sum({4,5})}<br />
*/<br />
<br />
=== Simulation results ===<br />
<br />
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. <br />
<br />
[[File:3x3trend.png|300px|Trend view for a 3x3 variable]]<br />
<br />
The clutter can be reduced by selecting which enumeration indexes are shown in charts. Select an enumeration and tick the indexes 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.<br />
<br />
[[File:ShowInCharts.png|500px|Select indexes to show in charts]]<br />
<br />
<br />
=== Array Variables in Modules ===<br />
<br />
[[File:Replaceable.png|frame|Replaceable enumeration inside a module]]<br />
<br />
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 [[Simantics_System_Dynamics#Modeling|Modeling]]). <br />
<br />
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.<br />
<br />
<br />
<br style="clear: both" /><br />
<br />
In this example, the original enumeration that the modeler used had two indexes. We are using an instance of this module, but we need to use array variables that have three indexes instead of two. We are using two variables and an instance of the module.<br />
<br />
[[File:ReplacingEnumerationConfiguration.png|frame|left|500px|Module configuration for replacing enumerations inside the module]]<br />
<br style="clear: both" /><br />
<br />
In the parent configuration, we have used an enumeration with three indexes in the two variables.<br />
<br />
[[File:Replacing.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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 clickin 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.<br />
<br />
<br />
[[File:ReplacingEnumeration.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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!<br />
<br />
== Functions ==<br />
<br />
Modelica provides a convenient way to use functions in your models. You can create your own functions, import complete function libraries and share function libraries to be used in all of your models. <br />
<br />
=== Creating functions ===<br />
<br />
[[File:NewFunction.png|right]]<br />
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.<br />
<br />
Functions that can be found from Functions -folder can be used in your variable definitions.<br />
<br />
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. <br />
<br />
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.<br />
<br />
Below is an example of a simple function. For more examples, see the built-in functions provided with the tool and [https://www.modelica.org/documents/ Modelica specifications].<br />
<br />
<br style="clear: both" /><br />
<br />
[[File:ExampleFunction.png]]<br />
<br />
=== Function libraries ===<br />
<br />
<br />
[[File:NewFunctionLibrary.png|right]]<br />
<br />
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)).<br />
<br />
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. <br />
<br />
Create a new function library by right-clicking on Functions folder, Shared functions folder or other module library.<br />
<br />
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.<br />
<br />
[[File:SharedFunctions.png]]<br />
<br style="clear: both" /><br />
<br />
=== External functions ===<br />
<br />
Modelica allows you to use external functions that are programmed using C language. Below is a simple example of using a function that returns the sum of two arguments. <br />
<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}<br />
<br />
<br />
[[File:ImportCFunctionLibrary.png|right]]<br />
<br />
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 <br />
(e.g. simantics_home/plugins/org.simantics.openmodelica.win32_x/MinGW/bin/mingw32_gcc.exe -g -O -c ExampleCFunctionCode.c). <br />
<br style="clear: both" /><br />
<br />
[[File:ExampleExternalFunction.png]]<br />
<br />
<br />
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.<br />
<br />
[[File:ExternalFunctionResult.png]]<br />
<br />
<br />
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.<br />
<br />
<br />
Small external C function can also be written directly to the function code in Simantics Sysdyn:<br />
function ExampleExternalFunction<br />
input Real x;<br />
input Real y;<br />
output Real z;<br />
external "C" z=exampleCFunction(x,y) annotation(Include="<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}");<br />
end ExampleExternalFunction;<br />
<br />
=== Modelica functions ===<br />
<br />
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 [[Simantics_System_Dynamics#Builtin_functions|builtin functions for arrays]].<br />
<br />
{|<br />
|abs(x)<br />
|Returns the absolute value of x. Expanded into "(if x >= 0 then x else -x)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|acos(x)<br />
|Inverse cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|asin(x)<br />
|Inverse sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan(x)<br />
|Inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan2(x1,x2)<br />
|four quadrant inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cat(n,A,B,...)<br />
|General concatenation function that concatenates arrays A,B,... along the nth dimension.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|ceil(x)<br />
|Returns the smallest integer not less than x, the closest integer above x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cos(x)<br />
|Cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cosh(x)<br />
|Hyperbolic cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cross(x,y)<br />
|Returns the 3-vector cross product of the 3-vectors x and y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|delay(expr, delayTime)<br />
|Returns the value of expr at the time time-delayTime. The value of expr is returned when time <= time.start + delayTime.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|der(x)<br />
|Time derivative of x. X must be have continuous-time variability.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|div(x, y)<br />
|Returns the algebraic quotient x/y with any fractional part discarted. E.g. div(10,3) = 3.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|edge(b)<br />
|Returns true when the value of the boolean expression b changes. Expanded into (b and not pre(b)).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|exp(x)<br />
|Exponential, base e.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|floor(x)<br />
|Returns the largest integer not greater than x, the closest integer below x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|initial()<br />
|Returns true at the beginning of the simulation. <br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|integer(x)<br />
|Returns the largest integer not greater than x as an integer.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log(x)<br />
|Natural logarithm. (base e, x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log10(x)<br />
|Base 10 logarithm. (x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|mod(x, y)<br />
|Returns the integer modulus of x/y: mod(x,y) = x - floor(x/y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|noEvent(expr)<br />
|noEvent around an expression causes the expression to NOT generate event.<br />
'''Important:''' <br />
:If you want a condition to be checked only on time steps, use noEvent.<br />
:(e.g. if noEvent(value >= 1) then ... else ...)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|pre(x)<br />
|Returns the preceding value of y from time event that has occured before current time.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|rem(x, y)<br />
|Returns the integer remainder of x/y: rem(x,y) = x - div(x,y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sample(start, interval)<br />
|Returns true and triggers time events at times start + i * interval (i=0,1,...).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sign(x)<br />
|Returns -1 if x is negative, 1 if x is positive. Expanded into "(if x > 0 then 1 else if x < 0 then -1 else 0)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sin(x)<br />
|Sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sinh(x)<br />
|Hyperbolic sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sqrt(x)<br />
|Square root of x. The value of x must be greater or equal to 0 or an assertion error occurs.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tan(x)<br />
|Tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tanh(x)<br />
|Hyperbolic tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|terminal()<br />
|Returns true at the end of a successful simulation.<br />
|}<br />
<br />
<br />
<center><br />
[[Simantics]] | ''System Dynamics Modelling''<br />
</center><br />
<br />
----<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Basic System Dynamics Modelling]]'''<br><br />
System dynamics modelling in Simantics is a free modelling tool that is included into the basic installation. This tutorial introduces the basic features of the system dynamics modelling tool.<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Advanced System Dynamics Modelling]]'''<br><br />
This tutorial introduces the more advanced features of the system dynamics modelling tool: Modules and Operating interfaces<br />
<br />
[[Category: Simantics System Dynamics]]</div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=Simantics_System_Dynamics&diff=547Simantics System Dynamics2012-06-04T10:04:32Z<p>Teemu Lempinen: /* Bar chart */</p>
<hr />
<div>== Simantics System Dynamics ==<br />
<br />
Simantics System Dynamics is currently the only open source modelling and simulating tool for Simantics. Simantics System Dynamics is under development and will go through some changes in the future. New features will be added and old ones improved according to the needs of the modellers. New features include module libraries and different analysis tools.<br />
<br />
This documentation introduces you to the current version of Simantics System Dynamics. Documentation includes the basic modelling principles and a guide on how to model system dynamics models with Simantics System Dynamics. If you like to get to know the tool better and try modelling and simulating yourself, [[#Installation Instructions|install]] the software and try our [[Tutorial: Basic System Dynamics Modelling|basic]] and [[Tutorial: Advanced System Dynamics Modelling|advanced]] tutorials!<br />
<br />
== Introduction to System Dynamics Simulation ==<br />
<br />
===System Dynamics===<br />
System dynamics is an approach to understanding different organizations, markets and other complex systems and their dynamic behavior. System dynamics modelling in Simantics is a free modelling tool. See [[#Installation Instructions|installation instructions]].<br />
<br />
===Model===<br />
[[File:ModelStructure.png|right|thumb|Model structure]]<br />
System dynamics model is generally understood as the model configuration. In this tool, the model contains also other components. Model can have Operating interfaces that enable the use of the model with simple controls. Operating interfaces are configured separately and when using them, the complex model is hidden from the user. Experiments are the way to simulate the model. In the future, you can have experiments with different configurations, for example different initial values for some parameters. In that way, you don't have to always configure the model for different scenarios. Modules folder contains all the different module types in your model and you can create new module types there. <br />
<br />
<br style="clear: both" /><br />
<br />
===Components===<br />
Most of the components you can use in your models are basic system dynamics components. The modularity of the models introduces two additional components, Modules and Inputs. All the components are explained below.<br />
[[File:ComponentTypes.png|right|frame|Component types]]<br />
;Auxiliary<br />
:Auxiliary is the most basic variable you can use. It represents a single value or a mathematical expression. There are different types of auxiliary variables currently in the system: Auxiliary, Parameter, Constant and WithLookup. Auxiliary is the default type. Parameters are single values that the user can change. When only parameters are changed, the model simulates faster, because the system does not have to recompile the model. WithLookup is a special variable that has an expression and a lookup table. The expresssion defines what value is taken from the defined table.<br />
;Dependency<br />
:Dependency is an arrow that connects two components. It means that the value of the variable from which the arrow starts is used to calculate the value of the variable where the arrow ends.<br />
;Flow<br />
:Flow connects clouds, valves and stocks. Flow represents an actual flow of something from stocks or clouds to stocks or clouds. There has to be at least one valve in a flow and the system creates it automatically, if none of the ends of the flow is a valve.<br />
;Valve<br />
:Valve regulates the rate of a flow. The value of a valve is automatically used in calculating the level of an adjacent stock. Valves behave just like Auxiliary variables but look different and you can connect also flows to them.<br />
;Stock<br />
:The value of a stock variable is an integral of flows leaving and flows arriving to the variable. The integral is calculated automatically from the valves that are connected to the variable with flow connections. You must give an initial value to the stock. Initial value can be a single value or an equation. You can use values of other variables to calculate the initial value.<br />
;Cloud<br />
:Cloud is not a variable. It represents a starting or ending point of a flow, if it is not in the scope of the model.<br />
;Module<br />
:Modules enable structural modeling. Modules are defined just like the basic model configuration, but the module component hides the actual configuration. You can only connect dependency connections into the module and dependency connections from the module must end to Input variables. The interface of the module is defined using input and output variables in the configuration of the module. All variable types can be set as output variables. If a variable is an output variable, its font is bold.<br />
;Input<br />
:Input variables are the way of getting values from other modules. Inputs look like auxiliary variables except their font is italics. You can set a default value to the input variable in case it is not connected to any variable. Connections are made from the modules properties, when the module is populated. Input doesn't have to be connected with an arrow to a module. If the variable has no connections, it can get values from a higher level in the hierarchy. If an input is connected to an output, the output and its module are shown below the variable using dot notation.<br />
<br style="clear: both" /><br />
<br />
===Modeling principles===<br />
<br />
System dynamics modelling is much more than just mathematical formulas and nice graphs. Models are ways of communicating. There are some basic principles in system dynamics modelling that make the models easier to read and understand. You do not have to apply these principles to simulate models, but using them makes it easier for you to communicate your model to others.<br />
<br />
;Variable names<br />
:Variables names should be nouns, not verbs. The names should be positive: for example it is easier to understand that satisfaction decreases than dissatisfaction rises. <br />
<br />
:Variable names can and should have multiple words, if they are needed. Unfortunately current version of the tool does not support spaces in variable names. A good practice is to use CamelCase if name contains multiple words. This means that you start every word woth a capital letter (example: ExampleVariable).<br />
<br />
;Connections<br />
:You should try to avoid overlapping dependency arrows. In some situations, however, it is not possible. Dependencies should also form distinctive loops, if there is a loop. It makes it easier to read and understand the model and its behavior.<br />
<br />
;Graphical annotations<br />
:System dynamics contains usually annotations for loops, polarities, delays and so on. Currently those annotations are not supported, but the support will be added later. Annotations are important, again, for communicating the behavior of the model.<br />
<br />
==Installation Instructions==<br />
<br />
System dynamics tool is a provided with the Simantics platform.<br />
<br />
# [https://www.simantics.org/simantics/download Download installer from Simantics download page]<br />
# Install the program to a directory without spaces. <br />
# Run Simantics-Sysdyn.exe <br /><br />
: (Default path in windows: C:\Simantics\Sysdyn\1.4\simantics-sysdyn\Simantics-Sysdyn.exe)<br />
<br />
[http://www.openmodelica.org/ OpenModelica] is used to build and simulate the models. Simantics platform has integrated OpenModelica 1.7 for Windows environments. For other versions and other environments you need to install [http://www.openmodelica.org/index.php/download OpenModelica].<br />
<br />
== Workbench ==<br />
<br />
[[File:BasicWorkbench.png|center|729px]]<br />
<br />
<br />
# '''Diagram''' <br /> Diagram is the area where you will graphically modify your model. Diagrams are built from elements that can be dragged from Symbols view or populated using shortcut keys. <br />
# '''Model Browser''' <br /> Model browser shows the structure of your model and all items related to it. <br /> Symbols view is stacked with the model browser and used for dragging elements to diagrams.<br />
# '''Properties''' <br /> Property view shows the selected variable's properties. Property view has a different layout depending on the type of the selected component. The view can also have different tabs depending on the component type. Basic tabs are with variables are Equation and Additional information.<br />
# '''Trend''' <br /> Trend view shows the graphical representation of the values of the selected value over time. For the trend to be shown, a simulation has to be run. The view shows always the results of the latest run, but you can save results of a simulation and show them in the same trend with results from another simulation. Values view and Dependencies are stacked with Trend view and can also be used for analyzing the model.<br />
# '''Experiment controls''' <br /> Experiment controls are shown when an experiment is active. Experiment is activated by double clicking an experiment in the model browser. With the experiment control, you can start simulation runs and save simulation results.<br />
<br />
<br /><br />
If you accidentally close a view, you can reopen them from Window->Show View->Other...<br />
<br />
== Modelling ==<br />
<br />
===Basic modelling===<br />
<br />
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.<br />
<br />
[[File:Basic_1.png|right]]<br />
;Creating a new model<br />
:Start a new model by right-clicking the model browser and selecting New->Model or from the main menu File->New Model.<br />
<br style="clear: both" /><br />
<br />
[[File:Basic_2.png|right]]<br />
;Creating a new module type<br />
:Create a new module type by right-clicking on the Modules-folder and selecting New->Module. This creates a new module type that you can populate to your other modules and the model configuration. <br />
<br style="clear: both" /><br />
<br />
;Configuring a model<br />
:Model configuration can be opened by double clicking Configuration in the model browser. <br />
<br />
;Configuring modules<br />
: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 module!<br />
<br />
;Populate variables<br />
:You can drag variables to a diagram from symbol view. You can also populate variables using [[#Shortcut and control keys|shortcut keys]]<br />
<br />
;Populate modules<br />
:Modules are populated from the model browser. Just drag the module you want to populate from the Modules folder to a diagram.<br />
<br />
;Create connections<br />
: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.<br />
: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.<br />
: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.<br />
<br />
;Connections between modules<br />
:'''Outside the module''' <br /><br />
:You can connect variables to variables in modules like this:<br />
MODULE -----> INPUT<br />
or<br />
ANY VARIABLE -----> MODULE <br />
:This is just the visual configuration, but you need those connections to really connect variables in the module's properties.<br />
:In Inputs -tab you select which variables you connect to inputs inside the module. In Outputs -tab you select which variables you lift from the module to inputs outside it.<br />
<br />
:'''Inside the module''' <br /><br />
:Input variables get values from outside the module<br />
<br />
:Output variables can send their values outside the module. From the variable properties, select Additional Information and press Is Output<br />
<br />
;Configure variables<br />
:Select a single variable from diagram or model browser. The properties of the variables are shown in the equation view and you can modify them.<br />
<br />
;Export model<br />
: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 to for example create different versions of the model, create backups or to transport it to another database.<br />
<br />
;Import model<br />
:Right-click on the model browser and select Import->Model. Browse to your .tg file and select open. The model is added to your model browser.<br />
<br />
===Shortcut and control keys===<br />
<br />
Shortcut keys for configuring a model on diagram.<br />
<br />
{|<br />
|Esc <br />
|Cancel operations (e.g. connection and rename).<br />
|-<br />
|Shift + A <br />
|Hover Auxiliary at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + S<br />
|Hover Stock at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + C<br />
|Hover Cloud at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + V<br />
|Hover Valve at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + I<br />
|Hover Input at the cursor position, populate with left mouse button.<br />
|-<br />
|Alt + left mouse button<br />
|Start an arrow from a variable. End to another variable by clicking left mouse button.<br />
|-<br />
|Alt + right mouse button<br />
|Start flow from a variable. End by clicking left mouse button.<br />
<br />
If a flow is not started or ended on to a variable, a cloud will be created to that end. <br /><br />
If a new flow does not have a valve at either end, a valve will be created in the middle of the flow.<br />
|-<br />
|Delete<br />
|Remove selected variables<br />
|-<br />
|Ctrl + left mouse button<br />
|Select multiple variables<br />
|-<br />
|Mouse wheel or<br/>+ and -<br />
|Diagram zoom<br />
|-<br />
|drag(mouse3) or<br/>drag(shift + any mouse button)<br />
|Diagram pan<br />
|-<br />
|Ctrl + C<br />
|Copy selected elements<br />
|-<br />
|Ctrl + X<br />
|Cut selected elements<br />
|-<br />
|Ctrl + V<br />
|Paste copied or cut elements<br />
|-<br />
|G<br />
|Show / hide grid<br />
|-<br />
|R<br />
|Show / hide ruler<br />
|}<br />
<br />
Other shortcut keys can be found selecting Window -> Preferences from the main menu. Keys are located in General -> Keys.<br />
<br />
== Simulation ==<br />
There are three different ways for simulating a model. Different simulations are represented as different types of experiments in Simantics System Dynamics. <br />
<br />
Experiments are created from the context menu of experiments folder in a model. <br />
<br />
[[File:NewExperiment.png]]<br />
<br />
Double-click on an experiment activates it and displays experiment type specific controls in the main tool bar.<br />
<br />
;Normal simulation<br />
: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.<br />
<br />
;Game simulation<br />
:Game simulations allow simulating an arbitrary number of steps, changing parameter values and continuing simulation with the new values from where it previously ended.<br />
<br />
;Simulation playback<br />
:Simulation playback works essentially as the basic experiment, but it offers some additional visualization options.<br />
<br />
== Simulation result and model structure analysis ==<br />
Simulation results can be viewed as trends in trend view or as plain numbers in values view. The views display results of variables that are selected in the workbench. Users can also create [[#Custom charts |custom charts]].<br />
<br />
Model structure can be examined in the Structure view. There are two options: Dependency structures of individual variables or the complete hierarchy structure of the model.<br />
<br />
;Trend<br />
:Shows you the values of the selected variable(s) graphically over the simulation time. You can modify the trend and zoom it using the context menu (right-click) of the trend. <br /> [[File:Trend.png]]<br />
<br />
;Values<br />
:Shows you the values of the selected variable(s) in a table form. If the value has a star (*) at the end, it means that the value is an approximate. There is no value for that variable for the given time step. Selected values can be copied to other software in csv format.<br /> [[File:Values.png]]<br />
<br />
;Compare results<br />
:You can compare different results of the same model by saving simulation results and displaying the saved results side by side with other results. You can save your results after simulating by clicking the save button [[File:Saveresults.png]] on your experiment controls. The saved results appear to model browser under the active experiment. To show the results on trends and tables, right-click on the result and select Show on charts. <br /> [[File:CompareTrend.png]]<br />
<br />
;Dependencies<br />
:Dependencies display which variables affect and which are affected by the selected variable. The direction and number of steps that are traveled from the selected variable can be configured at the bottom of the view. <br /> [[File:Dependencies.png]]<br />
<br />
;Model Hierarchy<br />
:Model Hierarchy displays the hierarchical structure of the model. The module type where a selected variable is located is highlighted.<br /> [[File:ModelHierarchy.png]]<br />
<br />
== Custom charts ==<br />
Custom charts are user-defined displays of simulation result data. They can be used and re-used in various places. The three types of custom charts (line, bar and pie charts) provide model developers means for examining and developing their models and communicating the simulation results to others. <br />
<br />
Custom charts are created to the Charts folder in model browser.<br />
<br />
[[File:NewChart.png | Creating a new chart]]<br />
<br />
Charts are configured the same way as variables: first select the chart from model browser and then configure it in the property view. Charts can be viewed in the same active trend view as any variable by selecting the chart from model browser. In addition to trend view, charts can be populated directly to the model diagram or to a separate chart panel that can contain multiple charts. <br />
<br />
=== Line chart ===<br />
<br />
Line char 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.<br />
<br />
[[File:LineChart.png|Line chart with an array variable]]<br />
<br />
[[File:LineChartGeneral.png|General settings of line chart]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|The title of the chart. Displayed in the chart<br />
|-<br />
|Type<br />
|Line chart (default) or area chart<br />
|-<br />
|Hide<br />
|Options to hide chart grid, title or legend<br />
|-<br />
|'''X-axis'''<br />
|<br />
|-<br />
|Variable<br />
|A variable that is used as the x-axis variable. The default variable is time and it needs not to be typed in the field.<br />
|-<br />
|Label<br />
|Optional other label for the variable than its name<br />
|-<br />
|Min<br />
|Minimum value of the x-axis<br />
|-<br />
|Max<br />
|Maximum value of the x-axis<br />
|-<br />
|Hide<br />
|Options to hide x-axis lable, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
[[File:LineChartAxisAndVariables.png|Axis and variables settings of line chart]]<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed.<br />
|-<br />
|Color<br />
|Color for the lines of this variable<br />
|-<br />
|Line width<br />
|The width of the lines drawn for this variable<br />
|}<br />
There are also configuration options for y-axis. They are displayed when an axis is selected in the Axis and variables tab.<br />
{|<br />
|'''Y-axis'''<br />
|<br />
|-<br />
|Label<br />
|Label of the axis<br />
|-<br />
|Min<br />
|Minimum value in the axis<br />
|-<br />
|Max<br />
|Maximum value in the axis<br />
|-<br />
|Color<br />
|The color of the axis lines, ticks and labels<br />
|-<br />
|Hide<br />
|Options to hide parts of the axis: label, axis line, tick marks, tick labels<br />
|-<br />
|}<br />
<br />
=== Bar chart ===<br />
Bar charts display variables in a certain point in time. The point can be defined for the complete chart in cart'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. <br />
<br />
[[File:BarChartGeneral.png|General bar chart settings]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Name is displayed in model browser.<br />
|-<br />
|Title<br />
|The title of the chart. Title is displayed in the chart, if not hidden<br />
|-<br />
|Type<br />
|Normal or stacked. Normal type displays all variables in separate bars. Stacked mode is able to display one-dimensional array variables in stacks.<br />
|-<br />
|Time<br />
|A general time setting for the entire chart. The values at this time are displayed in the chart<br />
|-<br />
|Hide<br />
|Option for hiding grid, title and Legend. Legend is hidden by default since it only contains the information that the current simulation is displayed.<br />
|-<br />
|}<br />
<br />
[[File:BarChartInDiagram.png|Bar chart in a model diagram]]<br />
Charts can be added to model diagrams simply by dragging the chart from model browser to diagram.<br />
<br />
[[File:BarChartVariable.png|Settings for a variable in bar chart]]<br />
<br />
[[File:BarChartAxis.png|Settings for axis in bar chart]]<br />
<br />
=== Pie chart ===<br />
<br />
<br />
=== Chart panel ===<br />
<br />
== Multidimensional variables ==<br />
<br />
<br />
=== Modeling ===<br />
<br />
Models with multidimensional variables look just like any other models. The structure of the models is replicated givin multiple indexes to variables. For users with programming background, notation Variable[] may be familiar. In system dynamic modeling we need to give names to the indexes. Instead of using numbers to define the indexes, like in normal programming, we use enumerations. The steps to create a model with multidimensional variables are as follows (with examples):<br />
<br />
# '''Create the model structure''' <BR />Model with multidimensional variables looks just like any other model.<BR /> [[File:ModelWithMultidimensionalVariables.png|300px|Model with multidimensional variables]]<br />
# '''Create Enumerations and define the indexes''' <BR />Enumerations are created by right-clicking configuration and selecting New->Enumeration.<BR /> [[File:NewEnumeration.png|250px|New enumeration]]<BR />Define enumeration indexes by adding as many indexes as you want. Rename the indexes by selecting them and then clicking on them again.<BR />[[File:DefineIndexes.png|200px|Index definitions]]<br />
# '''Add Enumerations for variables''' <BR />Select the variable that you want to be multidimensional. From the Indexes -tab in the property view, move the wanted enumerations to the right. The order of the enumerations does matter.[[File:SelectEnumerations.png|500px|Select enumerations for variables]]<br />
# '''Define equations for all possible indexes''' <BR />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 indexes, so the resulting definition can be {{1,2,3},{4,5,6},{7,8,9}}.<BR />[[File:DefineEquations.png|500px|Define equations for all indexes]]<br />
<br />
<br />
<br />
=== Expressions ===<br />
<br />
Values for all cells in the variable matrix can be defined in a single expression. <br />
<br />
[[File: DefineEquations.png|600px]]<br />
<br />
[[File:DefineEquations2.png|600px]]<br />
<br />
In many situations, it is however more clear to define separate expressions for each cell or blocks. <br />
<br />
# '''Define range for the expression'''<BR /> [[File:DefineRange.png]]<br />
# '''Define the expression''' (dimensions of the defined range and the result of the expression must match!) <BR /> [[File:DefineEquations3.png]]<br />
# '''Create a new expression''' <BR /> [[File:CreateNewExpression.png]]<br />
#''' Select the new expression''' <BR /> [[File:SelectNewExpression.png]]<br />
<br />
Repeat until there is value for each cell. There must be exactly one value for each cell.<br />
<br />
=== Array slices ===<br />
<br />
Many times it is useful to access a slice of a multidimensional variable. In this chapter, we will use the following example variable:<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
The whole variable can be accessed in three different ways:<br />
# Auxiliary<br />
# Auxiliary[E1, E2]<br />
# Auxiliary[:, :]<br />
<br />
The following explains different methods for accessing parts of the variable<br />
<br />
// Single cell<br />
Auxiliary[one, eins] = 1<br />
<br />
// Slices<br />
Auxiliary[one, E2] = {1,2,3}<br />
Auxiliary[E1, zwei] = {{2},{5},{8}}<br />
<br />
// In addition to single cells and the whole enumeration range, a subrange of the enumeration can be used<br />
Auxiliary[two : three, E2] = {{4,5,6},{7,8,9}}<br />
Auxiliary[one : two, zwei : drei] = {{2,3},{5,6}}<br />
<br />
The syntax for accessing parts of variables can be used in both expression range definitions and in expressions.<br />
<br />
=== Arithmetic Operators ===<br />
<br />
Arithmetic operations are defined in Modelica. Below are examples of different operations.<br />
<br />
;Addition and substraction<br />
Addition and substraction are calculated elementwise<br />
<br />
{1,2,3} - {0,2,3} = {1,0,0}<br />
{{2,2},{4,4}} + {{8,8},{1,1}} = {{10,10},{5,5}}<br />
{1,2,3} - {1,2} = ERROR! Different array sizes<br />
<br />
;Division<br />
Division with a scalar<br />
{5,10,15} / 5 = {1,2,3}<br />
5 / {5,10,15} = ERROR! not allowed<br />
<br />
Division with an array<br />
{1,2,3} / {1,2,3} = ERROR! not allowed<br />
<br />
// Elementwise<br />
{1,2,3} ./ {1,2,3} = {1,1,1}<br />
<br />
;Multiplication<br />
<br />
Multiplication with a scalar<br />
{1,2,3} * 2 = {2,4,6}<br />
5 * {1,2,3} = {5,10,15}<br />
<br />
Matrix multiplication with an array<br />
{{3,4},{5,6}} * {1,2} = {11,17}<br />
{{3,4},{5,6}} * {1,2,3} = ERROR! incompatible array sizes<br />
<br />
//Elementwise<br />
{1,2} .* {1,2} = {1,4}<br />
<br />
Real[3,2] c = {{1,2},{3,4},{5,6}}; <br />
Real[2,2] d = {{3,4},{5,6}};<br />
Real[2,2] cd;<br />
cd = c[2:3, :] .* d; // Result: {{9,16},{25,36}}<br />
<br />
=== Builtin Modelica functions ===<br />
<br />
Modelica has some builtin functions that help using multidimensional variables. This chapter introduces some of the builtin functions. <br />
<br />
;Dimension and size functions<br />
<br />
We will use the same example variable as previously.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
;ndims(A)<br />
The number of dimensions in array A<br />
ndims(Auxiliary) = 2<br />
<br />
;size(A, i)<br />
The size of dimension i in array A<br />
size(Auxiliary, 2) = 3<br />
<br />
;size(A)<br />
A vector of length ndims(A) containing the dimension sizes of A<br />
size(Auxiliary) = {3,3}<br />
<br />
<br />
;Construction functions<br />
In addition to normal array constructing, a special construction functions can be used.<br />
<br />
;zeros(n1,n2,n3,...)<br />
An array full of zeros with dimensions n1 x n2 x n2 x ... <br />
zeros(2, 2) = {{0,0}, {0,0}}<br />
<br />
;ones(n1,n2,n3,...)<br />
An array full of ones with dimensions n1 x n2 x n2 x ... <br />
ones(2, 2) = {{1,1}, {1,1}}<br />
<br />
;fill(s,n1,n2,n3)<br />
Like zeros() and ones(), but with user defined value (s) for array elements.<br />
fill(3,2,2) = {{3,3}, {3,3}}<br />
<br />
;identity(n)<br />
Creates an n x n integer identity matrix with ones on the diagonal and all other elements zero.<br />
identity(3) =<br />
1 0 0<br />
0 1 0<br />
0 0 1<br />
<br />
;diagonal(v)<br />
Constructs a square matrix with elements of vector v on the diagonal and all other elements zero.<br />
diagonal({1,2,3}) =<br />
1 0 0<br />
0 2 0<br />
0 0 3<br />
<br />
;linspace(x1,x2,n)<br />
Constracts a Real vector from x1 to x2 with n equally spaced elements.<br />
linspace(2,5,4) = {2,3,4,5}<br />
<br />
;Reduction functions<br />
<br />
Reduction functions reduce arrays to scalars.<br />
<br />
;min(A)<br />
Returns the minimum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
min(A) = 1<br />
<br />
;max(A)<br />
Returns the maximum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
max(A) = 4<br />
<br />
;sum(A)<br />
Returns the sum of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
sum(A) = 10 // 1 + 2 + 3 + 4<br />
<br />
;product(A)<br />
Returns the product of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
product(A) = 24 // 1 * 2 * 3 * 4<br />
<br />
<br />
;Using functions with iterators<br />
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.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
AuxiliarySum[E1] = {sum( Auxiliary[ i , E2 ] ) for i in E1} // Result: {6, 15, 24}<br />
<br />
/* Same as:<br />
{sum(Auxiliary[one, E2]), sum(Auxiliary[two, E2]), sum(Auxiliary[three, E2])}<br />
{sum({1,2,3}), sum({4,5,6}), sum({7,8,9})}<br />
*/<br />
<br />
One expression can have multiple iterators. The Modelica specification defines the following format, but it is NOT yet supported in OpenModelica:<br />
{sum(Array[ i, j, E3]) for i in E1, j in E2} // Dimensions reduced from 3 to 2<br />
<br />
To use multiple iterators, use the following format (NOTE the reversed order of iterators!):<br />
{{sum(Array[ i, j, E3]) for j in E2} for i in E1} // Dimensions reduced from 3 to 2<br />
<br />
The range doesn't have to be the whole enumeration. Subranges can also be used.<br />
{sum( Auxiliary[ i , eins : zwei ] ) for i in E1.one : E1.two} // Result: {3, 9}<br />
<br />
/* Same as<br />
{sum(Auxiliary[one, eins : zwei]), sum(Auxiliary[two, eins : zwei])}<br />
{sum({1,2}), sum({4,5})}<br />
*/<br />
<br />
=== Simulation results ===<br />
<br />
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. <br />
<br />
[[File:3x3trend.png|300px|Trend view for a 3x3 variable]]<br />
<br />
The clutter can be reduced by selecting which enumeration indexes are shown in charts. Select an enumeration and tick the indexes 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.<br />
<br />
[[File:ShowInCharts.png|500px|Select indexes to show in charts]]<br />
<br />
<br />
=== Array Variables in Modules ===<br />
<br />
[[File:Replaceable.png|frame|Replaceable enumeration inside a module]]<br />
<br />
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 [[Simantics_System_Dynamics#Modeling|Modeling]]). <br />
<br />
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.<br />
<br />
<br />
<br style="clear: both" /><br />
<br />
In this example, the original enumeration that the modeler used had two indexes. We are using an instance of this module, but we need to use array variables that have three indexes instead of two. We are using two variables and an instance of the module.<br />
<br />
[[File:ReplacingEnumerationConfiguration.png|frame|left|500px|Module configuration for replacing enumerations inside the module]]<br />
<br style="clear: both" /><br />
<br />
In the parent configuration, we have used an enumeration with three indexes in the two variables.<br />
<br />
[[File:Replacing.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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 clickin 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.<br />
<br />
<br />
[[File:ReplacingEnumeration.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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!<br />
<br />
== Functions ==<br />
<br />
Modelica provides a convenient way to use functions in your models. You can create your own functions, import complete function libraries and share function libraries to be used in all of your models. <br />
<br />
=== Creating functions ===<br />
<br />
[[File:NewFunction.png|right]]<br />
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.<br />
<br />
Functions that can be found from Functions -folder can be used in your variable definitions.<br />
<br />
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. <br />
<br />
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.<br />
<br />
Below is an example of a simple function. For more examples, see the built-in functions provided with the tool and [https://www.modelica.org/documents/ Modelica specifications].<br />
<br />
<br style="clear: both" /><br />
<br />
[[File:ExampleFunction.png]]<br />
<br />
=== Function libraries ===<br />
<br />
<br />
[[File:NewFunctionLibrary.png|right]]<br />
<br />
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)).<br />
<br />
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. <br />
<br />
Create a new function library by right-clicking on Functions folder, Shared functions folder or other module library.<br />
<br />
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.<br />
<br />
[[File:SharedFunctions.png]]<br />
<br style="clear: both" /><br />
<br />
=== External functions ===<br />
<br />
Modelica allows you to use external functions that are programmed using C language. Below is a simple example of using a function that returns the sum of two arguments. <br />
<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}<br />
<br />
<br />
[[File:ImportCFunctionLibrary.png|right]]<br />
<br />
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 <br />
(e.g. simantics_home/plugins/org.simantics.openmodelica.win32_x/MinGW/bin/mingw32_gcc.exe -g -O -c ExampleCFunctionCode.c). <br />
<br style="clear: both" /><br />
<br />
[[File:ExampleExternalFunction.png]]<br />
<br />
<br />
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.<br />
<br />
[[File:ExternalFunctionResult.png]]<br />
<br />
<br />
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.<br />
<br />
<br />
Small external C function can also be written directly to the function code in Simantics Sysdyn:<br />
function ExampleExternalFunction<br />
input Real x;<br />
input Real y;<br />
output Real z;<br />
external "C" z=exampleCFunction(x,y) annotation(Include="<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}");<br />
end ExampleExternalFunction;<br />
<br />
=== Modelica functions ===<br />
<br />
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 [[Simantics_System_Dynamics#Builtin_functions|builtin functions for arrays]].<br />
<br />
{|<br />
|abs(x)<br />
|Returns the absolute value of x. Expanded into "(if x >= 0 then x else -x)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|acos(x)<br />
|Inverse cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|asin(x)<br />
|Inverse sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan(x)<br />
|Inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan2(x1,x2)<br />
|four quadrant inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cat(n,A,B,...)<br />
|General concatenation function that concatenates arrays A,B,... along the nth dimension.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|ceil(x)<br />
|Returns the smallest integer not less than x, the closest integer above x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cos(x)<br />
|Cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cosh(x)<br />
|Hyperbolic cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cross(x,y)<br />
|Returns the 3-vector cross product of the 3-vectors x and y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|delay(expr, delayTime)<br />
|Returns the value of expr at the time time-delayTime. The value of expr is returned when time <= time.start + delayTime.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|der(x)<br />
|Time derivative of x. X must be have continuous-time variability.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|div(x, y)<br />
|Returns the algebraic quotient x/y with any fractional part discarted. E.g. div(10,3) = 3.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|edge(b)<br />
|Returns true when the value of the boolean expression b changes. Expanded into (b and not pre(b)).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|exp(x)<br />
|Exponential, base e.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|floor(x)<br />
|Returns the largest integer not greater than x, the closest integer below x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|initial()<br />
|Returns true at the beginning of the simulation. <br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|integer(x)<br />
|Returns the largest integer not greater than x as an integer.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log(x)<br />
|Natural logarithm. (base e, x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log10(x)<br />
|Base 10 logarithm. (x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|mod(x, y)<br />
|Returns the integer modulus of x/y: mod(x,y) = x - floor(x/y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|noEvent(expr)<br />
|noEvent around an expression causes the expression to NOT generate event.<br />
'''Important:''' <br />
:If you want a condition to be checked only on time steps, use noEvent.<br />
:(e.g. if noEvent(value >= 1) then ... else ...)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|pre(x)<br />
|Returns the preceding value of y from time event that has occured before current time.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|rem(x, y)<br />
|Returns the integer remainder of x/y: rem(x,y) = x - div(x,y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sample(start, interval)<br />
|Returns true and triggers time events at times start + i * interval (i=0,1,...).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sign(x)<br />
|Returns -1 if x is negative, 1 if x is positive. Expanded into "(if x > 0 then 1 else if x < 0 then -1 else 0)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sin(x)<br />
|Sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sinh(x)<br />
|Hyperbolic sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sqrt(x)<br />
|Square root of x. The value of x must be greater or equal to 0 or an assertion error occurs.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tan(x)<br />
|Tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tanh(x)<br />
|Hyperbolic tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|terminal()<br />
|Returns true at the end of a successful simulation.<br />
|}<br />
<br />
<br />
<center><br />
[[Simantics]] | ''System Dynamics Modelling''<br />
</center><br />
<br />
----<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Basic System Dynamics Modelling]]'''<br><br />
System dynamics modelling in Simantics is a free modelling tool that is included into the basic installation. This tutorial introduces the basic features of the system dynamics modelling tool.<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Advanced System Dynamics Modelling]]'''<br><br />
This tutorial introduces the more advanced features of the system dynamics modelling tool: Modules and Operating interfaces<br />
<br />
[[Category: Simantics System Dynamics]]</div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:BarChartAxis.png&diff=546File:BarChartAxis.png2012-06-04T09:50:10Z<p>Teemu Lempinen: </p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:BarChartVariable.png&diff=545File:BarChartVariable.png2012-06-04T09:50:04Z<p>Teemu Lempinen: </p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:BarChartInDiagram.png&diff=544File:BarChartInDiagram.png2012-06-04T09:49:59Z<p>Teemu Lempinen: </p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=File:BarChartGeneral.png&diff=543File:BarChartGeneral.png2012-06-04T09:49:55Z<p>Teemu Lempinen: </p>
<hr />
<div></div>Teemu Lempinenhttps://wiki.simantics.org/index.php?title=Simantics_System_Dynamics&diff=542Simantics System Dynamics2012-06-04T09:14:15Z<p>Teemu Lempinen: /* Line chart */</p>
<hr />
<div>== Simantics System Dynamics ==<br />
<br />
Simantics System Dynamics is currently the only open source modelling and simulating tool for Simantics. Simantics System Dynamics is under development and will go through some changes in the future. New features will be added and old ones improved according to the needs of the modellers. New features include module libraries and different analysis tools.<br />
<br />
This documentation introduces you to the current version of Simantics System Dynamics. Documentation includes the basic modelling principles and a guide on how to model system dynamics models with Simantics System Dynamics. If you like to get to know the tool better and try modelling and simulating yourself, [[#Installation Instructions|install]] the software and try our [[Tutorial: Basic System Dynamics Modelling|basic]] and [[Tutorial: Advanced System Dynamics Modelling|advanced]] tutorials!<br />
<br />
== Introduction to System Dynamics Simulation ==<br />
<br />
===System Dynamics===<br />
System dynamics is an approach to understanding different organizations, markets and other complex systems and their dynamic behavior. System dynamics modelling in Simantics is a free modelling tool. See [[#Installation Instructions|installation instructions]].<br />
<br />
===Model===<br />
[[File:ModelStructure.png|right|thumb|Model structure]]<br />
System dynamics model is generally understood as the model configuration. In this tool, the model contains also other components. Model can have Operating interfaces that enable the use of the model with simple controls. Operating interfaces are configured separately and when using them, the complex model is hidden from the user. Experiments are the way to simulate the model. In the future, you can have experiments with different configurations, for example different initial values for some parameters. In that way, you don't have to always configure the model for different scenarios. Modules folder contains all the different module types in your model and you can create new module types there. <br />
<br />
<br style="clear: both" /><br />
<br />
===Components===<br />
Most of the components you can use in your models are basic system dynamics components. The modularity of the models introduces two additional components, Modules and Inputs. All the components are explained below.<br />
[[File:ComponentTypes.png|right|frame|Component types]]<br />
;Auxiliary<br />
:Auxiliary is the most basic variable you can use. It represents a single value or a mathematical expression. There are different types of auxiliary variables currently in the system: Auxiliary, Parameter, Constant and WithLookup. Auxiliary is the default type. Parameters are single values that the user can change. When only parameters are changed, the model simulates faster, because the system does not have to recompile the model. WithLookup is a special variable that has an expression and a lookup table. The expresssion defines what value is taken from the defined table.<br />
;Dependency<br />
:Dependency is an arrow that connects two components. It means that the value of the variable from which the arrow starts is used to calculate the value of the variable where the arrow ends.<br />
;Flow<br />
:Flow connects clouds, valves and stocks. Flow represents an actual flow of something from stocks or clouds to stocks or clouds. There has to be at least one valve in a flow and the system creates it automatically, if none of the ends of the flow is a valve.<br />
;Valve<br />
:Valve regulates the rate of a flow. The value of a valve is automatically used in calculating the level of an adjacent stock. Valves behave just like Auxiliary variables but look different and you can connect also flows to them.<br />
;Stock<br />
:The value of a stock variable is an integral of flows leaving and flows arriving to the variable. The integral is calculated automatically from the valves that are connected to the variable with flow connections. You must give an initial value to the stock. Initial value can be a single value or an equation. You can use values of other variables to calculate the initial value.<br />
;Cloud<br />
:Cloud is not a variable. It represents a starting or ending point of a flow, if it is not in the scope of the model.<br />
;Module<br />
:Modules enable structural modeling. Modules are defined just like the basic model configuration, but the module component hides the actual configuration. You can only connect dependency connections into the module and dependency connections from the module must end to Input variables. The interface of the module is defined using input and output variables in the configuration of the module. All variable types can be set as output variables. If a variable is an output variable, its font is bold.<br />
;Input<br />
:Input variables are the way of getting values from other modules. Inputs look like auxiliary variables except their font is italics. You can set a default value to the input variable in case it is not connected to any variable. Connections are made from the modules properties, when the module is populated. Input doesn't have to be connected with an arrow to a module. If the variable has no connections, it can get values from a higher level in the hierarchy. If an input is connected to an output, the output and its module are shown below the variable using dot notation.<br />
<br style="clear: both" /><br />
<br />
===Modeling principles===<br />
<br />
System dynamics modelling is much more than just mathematical formulas and nice graphs. Models are ways of communicating. There are some basic principles in system dynamics modelling that make the models easier to read and understand. You do not have to apply these principles to simulate models, but using them makes it easier for you to communicate your model to others.<br />
<br />
;Variable names<br />
:Variables names should be nouns, not verbs. The names should be positive: for example it is easier to understand that satisfaction decreases than dissatisfaction rises. <br />
<br />
:Variable names can and should have multiple words, if they are needed. Unfortunately current version of the tool does not support spaces in variable names. A good practice is to use CamelCase if name contains multiple words. This means that you start every word woth a capital letter (example: ExampleVariable).<br />
<br />
;Connections<br />
:You should try to avoid overlapping dependency arrows. In some situations, however, it is not possible. Dependencies should also form distinctive loops, if there is a loop. It makes it easier to read and understand the model and its behavior.<br />
<br />
;Graphical annotations<br />
:System dynamics contains usually annotations for loops, polarities, delays and so on. Currently those annotations are not supported, but the support will be added later. Annotations are important, again, for communicating the behavior of the model.<br />
<br />
==Installation Instructions==<br />
<br />
System dynamics tool is a provided with the Simantics platform.<br />
<br />
# [https://www.simantics.org/simantics/download Download installer from Simantics download page]<br />
# Install the program to a directory without spaces. <br />
# Run Simantics-Sysdyn.exe <br /><br />
: (Default path in windows: C:\Simantics\Sysdyn\1.4\simantics-sysdyn\Simantics-Sysdyn.exe)<br />
<br />
[http://www.openmodelica.org/ OpenModelica] is used to build and simulate the models. Simantics platform has integrated OpenModelica 1.7 for Windows environments. For other versions and other environments you need to install [http://www.openmodelica.org/index.php/download OpenModelica].<br />
<br />
== Workbench ==<br />
<br />
[[File:BasicWorkbench.png|center|729px]]<br />
<br />
<br />
# '''Diagram''' <br /> Diagram is the area where you will graphically modify your model. Diagrams are built from elements that can be dragged from Symbols view or populated using shortcut keys. <br />
# '''Model Browser''' <br /> Model browser shows the structure of your model and all items related to it. <br /> Symbols view is stacked with the model browser and used for dragging elements to diagrams.<br />
# '''Properties''' <br /> Property view shows the selected variable's properties. Property view has a different layout depending on the type of the selected component. The view can also have different tabs depending on the component type. Basic tabs are with variables are Equation and Additional information.<br />
# '''Trend''' <br /> Trend view shows the graphical representation of the values of the selected value over time. For the trend to be shown, a simulation has to be run. The view shows always the results of the latest run, but you can save results of a simulation and show them in the same trend with results from another simulation. Values view and Dependencies are stacked with Trend view and can also be used for analyzing the model.<br />
# '''Experiment controls''' <br /> Experiment controls are shown when an experiment is active. Experiment is activated by double clicking an experiment in the model browser. With the experiment control, you can start simulation runs and save simulation results.<br />
<br />
<br /><br />
If you accidentally close a view, you can reopen them from Window->Show View->Other...<br />
<br />
== Modelling ==<br />
<br />
===Basic modelling===<br />
<br />
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.<br />
<br />
[[File:Basic_1.png|right]]<br />
;Creating a new model<br />
:Start a new model by right-clicking the model browser and selecting New->Model or from the main menu File->New Model.<br />
<br style="clear: both" /><br />
<br />
[[File:Basic_2.png|right]]<br />
;Creating a new module type<br />
:Create a new module type by right-clicking on the Modules-folder and selecting New->Module. This creates a new module type that you can populate to your other modules and the model configuration. <br />
<br style="clear: both" /><br />
<br />
;Configuring a model<br />
:Model configuration can be opened by double clicking Configuration in the model browser. <br />
<br />
;Configuring modules<br />
: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 module!<br />
<br />
;Populate variables<br />
:You can drag variables to a diagram from symbol view. You can also populate variables using [[#Shortcut and control keys|shortcut keys]]<br />
<br />
;Populate modules<br />
:Modules are populated from the model browser. Just drag the module you want to populate from the Modules folder to a diagram.<br />
<br />
;Create connections<br />
: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.<br />
: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.<br />
: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.<br />
<br />
;Connections between modules<br />
:'''Outside the module''' <br /><br />
:You can connect variables to variables in modules like this:<br />
MODULE -----> INPUT<br />
or<br />
ANY VARIABLE -----> MODULE <br />
:This is just the visual configuration, but you need those connections to really connect variables in the module's properties.<br />
:In Inputs -tab you select which variables you connect to inputs inside the module. In Outputs -tab you select which variables you lift from the module to inputs outside it.<br />
<br />
:'''Inside the module''' <br /><br />
:Input variables get values from outside the module<br />
<br />
:Output variables can send their values outside the module. From the variable properties, select Additional Information and press Is Output<br />
<br />
;Configure variables<br />
:Select a single variable from diagram or model browser. The properties of the variables are shown in the equation view and you can modify them.<br />
<br />
;Export model<br />
: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 to for example create different versions of the model, create backups or to transport it to another database.<br />
<br />
;Import model<br />
:Right-click on the model browser and select Import->Model. Browse to your .tg file and select open. The model is added to your model browser.<br />
<br />
===Shortcut and control keys===<br />
<br />
Shortcut keys for configuring a model on diagram.<br />
<br />
{|<br />
|Esc <br />
|Cancel operations (e.g. connection and rename).<br />
|-<br />
|Shift + A <br />
|Hover Auxiliary at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + S<br />
|Hover Stock at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + C<br />
|Hover Cloud at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + V<br />
|Hover Valve at the cursor position, populate with left mouse button.<br />
|-<br />
|Shift + I<br />
|Hover Input at the cursor position, populate with left mouse button.<br />
|-<br />
|Alt + left mouse button<br />
|Start an arrow from a variable. End to another variable by clicking left mouse button.<br />
|-<br />
|Alt + right mouse button<br />
|Start flow from a variable. End by clicking left mouse button.<br />
<br />
If a flow is not started or ended on to a variable, a cloud will be created to that end. <br /><br />
If a new flow does not have a valve at either end, a valve will be created in the middle of the flow.<br />
|-<br />
|Delete<br />
|Remove selected variables<br />
|-<br />
|Ctrl + left mouse button<br />
|Select multiple variables<br />
|-<br />
|Mouse wheel or<br/>+ and -<br />
|Diagram zoom<br />
|-<br />
|drag(mouse3) or<br/>drag(shift + any mouse button)<br />
|Diagram pan<br />
|-<br />
|Ctrl + C<br />
|Copy selected elements<br />
|-<br />
|Ctrl + X<br />
|Cut selected elements<br />
|-<br />
|Ctrl + V<br />
|Paste copied or cut elements<br />
|-<br />
|G<br />
|Show / hide grid<br />
|-<br />
|R<br />
|Show / hide ruler<br />
|}<br />
<br />
Other shortcut keys can be found selecting Window -> Preferences from the main menu. Keys are located in General -> Keys.<br />
<br />
== Simulation ==<br />
There are three different ways for simulating a model. Different simulations are represented as different types of experiments in Simantics System Dynamics. <br />
<br />
Experiments are created from the context menu of experiments folder in a model. <br />
<br />
[[File:NewExperiment.png]]<br />
<br />
Double-click on an experiment activates it and displays experiment type specific controls in the main tool bar.<br />
<br />
;Normal simulation<br />
: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.<br />
<br />
;Game simulation<br />
:Game simulations allow simulating an arbitrary number of steps, changing parameter values and continuing simulation with the new values from where it previously ended.<br />
<br />
;Simulation playback<br />
:Simulation playback works essentially as the basic experiment, but it offers some additional visualization options.<br />
<br />
== Simulation result and model structure analysis ==<br />
Simulation results can be viewed as trends in trend view or as plain numbers in values view. The views display results of variables that are selected in the workbench. Users can also create [[#Custom charts |custom charts]].<br />
<br />
Model structure can be examined in the Structure view. There are two options: Dependency structures of individual variables or the complete hierarchy structure of the model.<br />
<br />
;Trend<br />
:Shows you the values of the selected variable(s) graphically over the simulation time. You can modify the trend and zoom it using the context menu (right-click) of the trend. <br /> [[File:Trend.png]]<br />
<br />
;Values<br />
:Shows you the values of the selected variable(s) in a table form. If the value has a star (*) at the end, it means that the value is an approximate. There is no value for that variable for the given time step. Selected values can be copied to other software in csv format.<br /> [[File:Values.png]]<br />
<br />
;Compare results<br />
:You can compare different results of the same model by saving simulation results and displaying the saved results side by side with other results. You can save your results after simulating by clicking the save button [[File:Saveresults.png]] on your experiment controls. The saved results appear to model browser under the active experiment. To show the results on trends and tables, right-click on the result and select Show on charts. <br /> [[File:CompareTrend.png]]<br />
<br />
;Dependencies<br />
:Dependencies display which variables affect and which are affected by the selected variable. The direction and number of steps that are traveled from the selected variable can be configured at the bottom of the view. <br /> [[File:Dependencies.png]]<br />
<br />
;Model Hierarchy<br />
:Model Hierarchy displays the hierarchical structure of the model. The module type where a selected variable is located is highlighted.<br /> [[File:ModelHierarchy.png]]<br />
<br />
== Custom charts ==<br />
Custom charts are user-defined displays of simulation result data. They can be used and re-used in various places. The three types of custom charts (line, bar and pie charts) provide model developers means for examining and developing their models and communicating the simulation results to others. <br />
<br />
Custom charts are created to the Charts folder in model browser.<br />
<br />
[[File:NewChart.png | Creating a new chart]]<br />
<br />
Charts are configured the same way as variables: first select the chart from model browser and then configure it in the property view. Charts can be viewed in the same active trend view as any variable by selecting the chart from model browser. In addition to trend view, charts can be populated directly to the model diagram or to a separate chart panel that can contain multiple charts. <br />
<br />
=== Line chart ===<br />
<br />
Line char 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.<br />
<br />
[[File:LineChart.png|Line chart with an array variable]]<br />
<br />
[[File:LineChartGeneral.png|General settings of line chart]]<br />
{|<br />
|'''General'''<br />
|<br />
|-<br />
|Name<br />
|The name of the chart. Displayed in e.g. model browser<br />
|-<br />
|Title<br />
|The title of the chart. Displayed in the chart<br />
|-<br />
|Type<br />
|Line chart (default) or area chart<br />
|-<br />
|Hide<br />
|Options to hide chart grid, title or legend<br />
|-<br />
|'''X-axis'''<br />
|<br />
|-<br />
|Variable<br />
|A variable that is used as the x-axis variable. The default variable is time and it needs not to be typed in the field.<br />
|-<br />
|Label<br />
|Optional other label for the variable than its name<br />
|-<br />
|Min<br />
|Minimum value of the x-axis<br />
|-<br />
|Max<br />
|Maximum value of the x-axis<br />
|-<br />
|Hide<br />
|Options to hide x-axis lable, line, tick marks and tick labels<br />
|-<br />
|}<br />
<br />
[[File:LineChartAxisAndVariables.png|Axis and variables settings of line chart]]<br />
{|<br />
|'''Variable'''<br />
|<br />
|-<br />
|Variable<br />
|The full path of the variable. This field has content assistant, which shows the possible variables as you type.<br />
|-<br />
|Range<br />
|If the variable has multiple dimensions, this field allows to select, which dimensions are displayed. It is also possible to sum the variables in the dimensions.<br />
|-<br />
|Label<br />
|Optional label for the variable. If label is empty, the variable name is displayed.<br />
|-<br />
|Color<br />
|Color for the lines of this variable<br />
|-<br />
|Line width<br />
|The width of the lines drawn for this variable<br />
|}<br />
There are also configuration options for y-axis. They are displayed when an axis is selected in the Axis and variables tab.<br />
{|<br />
|'''Y-axis'''<br />
|<br />
|-<br />
|Label<br />
|Label of the axis<br />
|-<br />
|Min<br />
|Minimum value in the axis<br />
|-<br />
|Max<br />
|Maximum value in the axis<br />
|-<br />
|Color<br />
|The color of the axis lines, ticks and labels<br />
|-<br />
|Hide<br />
|Options to hide parts of the axis: label, axis line, tick marks, tick labels<br />
|-<br />
|}<br />
<br />
=== Bar chart ===<br />
<br />
<br />
=== Pie chart ===<br />
<br />
<br />
=== Chart panel ===<br />
<br />
== Multidimensional variables ==<br />
<br />
<br />
=== Modeling ===<br />
<br />
Models with multidimensional variables look just like any other models. The structure of the models is replicated givin multiple indexes to variables. For users with programming background, notation Variable[] may be familiar. In system dynamic modeling we need to give names to the indexes. Instead of using numbers to define the indexes, like in normal programming, we use enumerations. The steps to create a model with multidimensional variables are as follows (with examples):<br />
<br />
# '''Create the model structure''' <BR />Model with multidimensional variables looks just like any other model.<BR /> [[File:ModelWithMultidimensionalVariables.png|300px|Model with multidimensional variables]]<br />
# '''Create Enumerations and define the indexes''' <BR />Enumerations are created by right-clicking configuration and selecting New->Enumeration.<BR /> [[File:NewEnumeration.png|250px|New enumeration]]<BR />Define enumeration indexes by adding as many indexes as you want. Rename the indexes by selecting them and then clicking on them again.<BR />[[File:DefineIndexes.png|200px|Index definitions]]<br />
# '''Add Enumerations for variables''' <BR />Select the variable that you want to be multidimensional. From the Indexes -tab in the property view, move the wanted enumerations to the right. The order of the enumerations does matter.[[File:SelectEnumerations.png|500px|Select enumerations for variables]]<br />
# '''Define equations for all possible indexes''' <BR />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 indexes, so the resulting definition can be {{1,2,3},{4,5,6},{7,8,9}}.<BR />[[File:DefineEquations.png|500px|Define equations for all indexes]]<br />
<br />
<br />
<br />
=== Expressions ===<br />
<br />
Values for all cells in the variable matrix can be defined in a single expression. <br />
<br />
[[File: DefineEquations.png|600px]]<br />
<br />
[[File:DefineEquations2.png|600px]]<br />
<br />
In many situations, it is however more clear to define separate expressions for each cell or blocks. <br />
<br />
# '''Define range for the expression'''<BR /> [[File:DefineRange.png]]<br />
# '''Define the expression''' (dimensions of the defined range and the result of the expression must match!) <BR /> [[File:DefineEquations3.png]]<br />
# '''Create a new expression''' <BR /> [[File:CreateNewExpression.png]]<br />
#''' Select the new expression''' <BR /> [[File:SelectNewExpression.png]]<br />
<br />
Repeat until there is value for each cell. There must be exactly one value for each cell.<br />
<br />
=== Array slices ===<br />
<br />
Many times it is useful to access a slice of a multidimensional variable. In this chapter, we will use the following example variable:<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
The whole variable can be accessed in three different ways:<br />
# Auxiliary<br />
# Auxiliary[E1, E2]<br />
# Auxiliary[:, :]<br />
<br />
The following explains different methods for accessing parts of the variable<br />
<br />
// Single cell<br />
Auxiliary[one, eins] = 1<br />
<br />
// Slices<br />
Auxiliary[one, E2] = {1,2,3}<br />
Auxiliary[E1, zwei] = {{2},{5},{8}}<br />
<br />
// In addition to single cells and the whole enumeration range, a subrange of the enumeration can be used<br />
Auxiliary[two : three, E2] = {{4,5,6},{7,8,9}}<br />
Auxiliary[one : two, zwei : drei] = {{2,3},{5,6}}<br />
<br />
The syntax for accessing parts of variables can be used in both expression range definitions and in expressions.<br />
<br />
=== Arithmetic Operators ===<br />
<br />
Arithmetic operations are defined in Modelica. Below are examples of different operations.<br />
<br />
;Addition and substraction<br />
Addition and substraction are calculated elementwise<br />
<br />
{1,2,3} - {0,2,3} = {1,0,0}<br />
{{2,2},{4,4}} + {{8,8},{1,1}} = {{10,10},{5,5}}<br />
{1,2,3} - {1,2} = ERROR! Different array sizes<br />
<br />
;Division<br />
Division with a scalar<br />
{5,10,15} / 5 = {1,2,3}<br />
5 / {5,10,15} = ERROR! not allowed<br />
<br />
Division with an array<br />
{1,2,3} / {1,2,3} = ERROR! not allowed<br />
<br />
// Elementwise<br />
{1,2,3} ./ {1,2,3} = {1,1,1}<br />
<br />
;Multiplication<br />
<br />
Multiplication with a scalar<br />
{1,2,3} * 2 = {2,4,6}<br />
5 * {1,2,3} = {5,10,15}<br />
<br />
Matrix multiplication with an array<br />
{{3,4},{5,6}} * {1,2} = {11,17}<br />
{{3,4},{5,6}} * {1,2,3} = ERROR! incompatible array sizes<br />
<br />
//Elementwise<br />
{1,2} .* {1,2} = {1,4}<br />
<br />
Real[3,2] c = {{1,2},{3,4},{5,6}}; <br />
Real[2,2] d = {{3,4},{5,6}};<br />
Real[2,2] cd;<br />
cd = c[2:3, :] .* d; // Result: {{9,16},{25,36}}<br />
<br />
=== Builtin Modelica functions ===<br />
<br />
Modelica has some builtin functions that help using multidimensional variables. This chapter introduces some of the builtin functions. <br />
<br />
;Dimension and size functions<br />
<br />
We will use the same example variable as previously.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
;ndims(A)<br />
The number of dimensions in array A<br />
ndims(Auxiliary) = 2<br />
<br />
;size(A, i)<br />
The size of dimension i in array A<br />
size(Auxiliary, 2) = 3<br />
<br />
;size(A)<br />
A vector of length ndims(A) containing the dimension sizes of A<br />
size(Auxiliary) = {3,3}<br />
<br />
<br />
;Construction functions<br />
In addition to normal array constructing, a special construction functions can be used.<br />
<br />
;zeros(n1,n2,n3,...)<br />
An array full of zeros with dimensions n1 x n2 x n2 x ... <br />
zeros(2, 2) = {{0,0}, {0,0}}<br />
<br />
;ones(n1,n2,n3,...)<br />
An array full of ones with dimensions n1 x n2 x n2 x ... <br />
ones(2, 2) = {{1,1}, {1,1}}<br />
<br />
;fill(s,n1,n2,n3)<br />
Like zeros() and ones(), but with user defined value (s) for array elements.<br />
fill(3,2,2) = {{3,3}, {3,3}}<br />
<br />
;identity(n)<br />
Creates an n x n integer identity matrix with ones on the diagonal and all other elements zero.<br />
identity(3) =<br />
1 0 0<br />
0 1 0<br />
0 0 1<br />
<br />
;diagonal(v)<br />
Constructs a square matrix with elements of vector v on the diagonal and all other elements zero.<br />
diagonal({1,2,3}) =<br />
1 0 0<br />
0 2 0<br />
0 0 3<br />
<br />
;linspace(x1,x2,n)<br />
Constracts a Real vector from x1 to x2 with n equally spaced elements.<br />
linspace(2,5,4) = {2,3,4,5}<br />
<br />
;Reduction functions<br />
<br />
Reduction functions reduce arrays to scalars.<br />
<br />
;min(A)<br />
Returns the minimum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
min(A) = 1<br />
<br />
;max(A)<br />
Returns the maximum value in array A.<br />
Real A = {{1,2},{3,4}}<br />
max(A) = 4<br />
<br />
;sum(A)<br />
Returns the sum of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
sum(A) = 10 // 1 + 2 + 3 + 4<br />
<br />
;product(A)<br />
Returns the product of values in array A.<br />
Real A = {{1,2},{3,4}}<br />
product(A) = 24 // 1 * 2 * 3 * 4<br />
<br />
<br />
;Using functions with iterators<br />
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.<br />
<br />
enumeration E1 = one, two, three<br />
enumeration E2 = eins, zwei, drei<br />
Auxiliary[E1, E2] = {{1,2,3},{4,5,6},{7,8,9}}<br />
<br />
AuxiliarySum[E1] = {sum( Auxiliary[ i , E2 ] ) for i in E1} // Result: {6, 15, 24}<br />
<br />
/* Same as:<br />
{sum(Auxiliary[one, E2]), sum(Auxiliary[two, E2]), sum(Auxiliary[three, E2])}<br />
{sum({1,2,3}), sum({4,5,6}), sum({7,8,9})}<br />
*/<br />
<br />
One expression can have multiple iterators. The Modelica specification defines the following format, but it is NOT yet supported in OpenModelica:<br />
{sum(Array[ i, j, E3]) for i in E1, j in E2} // Dimensions reduced from 3 to 2<br />
<br />
To use multiple iterators, use the following format (NOTE the reversed order of iterators!):<br />
{{sum(Array[ i, j, E3]) for j in E2} for i in E1} // Dimensions reduced from 3 to 2<br />
<br />
The range doesn't have to be the whole enumeration. Subranges can also be used.<br />
{sum( Auxiliary[ i , eins : zwei ] ) for i in E1.one : E1.two} // Result: {3, 9}<br />
<br />
/* Same as<br />
{sum(Auxiliary[one, eins : zwei]), sum(Auxiliary[two, eins : zwei])}<br />
{sum({1,2}), sum({4,5})}<br />
*/<br />
<br />
=== Simulation results ===<br />
<br />
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. <br />
<br />
[[File:3x3trend.png|300px|Trend view for a 3x3 variable]]<br />
<br />
The clutter can be reduced by selecting which enumeration indexes are shown in charts. Select an enumeration and tick the indexes 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.<br />
<br />
[[File:ShowInCharts.png|500px|Select indexes to show in charts]]<br />
<br />
<br />
=== Array Variables in Modules ===<br />
<br />
[[File:Replaceable.png|frame|Replaceable enumeration inside a module]]<br />
<br />
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 [[Simantics_System_Dynamics#Modeling|Modeling]]). <br />
<br />
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.<br />
<br />
<br />
<br style="clear: both" /><br />
<br />
In this example, the original enumeration that the modeler used had two indexes. We are using an instance of this module, but we need to use array variables that have three indexes instead of two. We are using two variables and an instance of the module.<br />
<br />
[[File:ReplacingEnumerationConfiguration.png|frame|left|500px|Module configuration for replacing enumerations inside the module]]<br />
<br style="clear: both" /><br />
<br />
In the parent configuration, we have used an enumeration with three indexes in the two variables.<br />
<br />
[[File:Replacing.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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 clickin 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.<br />
<br />
<br />
[[File:ReplacingEnumeration.png|frame|left|Enumeration in the parent configuration that will replace the enumeration in the module]]<br />
<br style="clear: both" /><br />
<br />
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!<br />
<br />
== Functions ==<br />
<br />
Modelica provides a convenient way to use functions in your models. You can create your own functions, import complete function libraries and share function libraries to be used in all of your models. <br />
<br />
=== Creating functions ===<br />
<br />
[[File:NewFunction.png|right]]<br />
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.<br />
<br />
Functions that can be found from Functions -folder can be used in your variable definitions.<br />
<br />
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. <br />
<br />
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.<br />
<br />
Below is an example of a simple function. For more examples, see the built-in functions provided with the tool and [https://www.modelica.org/documents/ Modelica specifications].<br />
<br />
<br style="clear: both" /><br />
<br />
[[File:ExampleFunction.png]]<br />
<br />
=== Function libraries ===<br />
<br />
<br />
[[File:NewFunctionLibrary.png|right]]<br />
<br />
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)).<br />
<br />
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. <br />
<br />
Create a new function library by right-clicking on Functions folder, Shared functions folder or other module library.<br />
<br />
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.<br />
<br />
[[File:SharedFunctions.png]]<br />
<br style="clear: both" /><br />
<br />
=== External functions ===<br />
<br />
Modelica allows you to use external functions that are programmed using C language. Below is a simple example of using a function that returns the sum of two arguments. <br />
<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}<br />
<br />
<br />
[[File:ImportCFunctionLibrary.png|right]]<br />
<br />
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 <br />
(e.g. simantics_home/plugins/org.simantics.openmodelica.win32_x/MinGW/bin/mingw32_gcc.exe -g -O -c ExampleCFunctionCode.c). <br />
<br style="clear: both" /><br />
<br />
[[File:ExampleExternalFunction.png]]<br />
<br />
<br />
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.<br />
<br />
[[File:ExternalFunctionResult.png]]<br />
<br />
<br />
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.<br />
<br />
<br />
Small external C function can also be written directly to the function code in Simantics Sysdyn:<br />
function ExampleExternalFunction<br />
input Real x;<br />
input Real y;<br />
output Real z;<br />
external "C" z=exampleCFunction(x,y) annotation(Include="<br />
double exampleCFunction(double x, double y)<br />
{<br />
double res;<br />
res = x + y;<br />
return res;<br />
}");<br />
end ExampleExternalFunction;<br />
<br />
=== Modelica functions ===<br />
<br />
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 [[Simantics_System_Dynamics#Builtin_functions|builtin functions for arrays]].<br />
<br />
{|<br />
|abs(x)<br />
|Returns the absolute value of x. Expanded into "(if x >= 0 then x else -x)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|acos(x)<br />
|Inverse cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|asin(x)<br />
|Inverse sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan(x)<br />
|Inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|atan2(x1,x2)<br />
|four quadrant inverse tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cat(n,A,B,...)<br />
|General concatenation function that concatenates arrays A,B,... along the nth dimension.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|ceil(x)<br />
|Returns the smallest integer not less than x, the closest integer above x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cos(x)<br />
|Cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cosh(x)<br />
|Hyperbolic cosine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|cross(x,y)<br />
|Returns the 3-vector cross product of the 3-vectors x and y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|delay(expr, delayTime)<br />
|Returns the value of expr at the time time-delayTime. The value of expr is returned when time <= time.start + delayTime.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|der(x)<br />
|Time derivative of x. X must be have continuous-time variability.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|div(x, y)<br />
|Returns the algebraic quotient x/y with any fractional part discarted. E.g. div(10,3) = 3.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|edge(b)<br />
|Returns true when the value of the boolean expression b changes. Expanded into (b and not pre(b)).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|exp(x)<br />
|Exponential, base e.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|floor(x)<br />
|Returns the largest integer not greater than x, the closest integer below x.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|initial()<br />
|Returns true at the beginning of the simulation. <br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|integer(x)<br />
|Returns the largest integer not greater than x as an integer.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log(x)<br />
|Natural logarithm. (base e, x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|log10(x)<br />
|Base 10 logarithm. (x > 0)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|mod(x, y)<br />
|Returns the integer modulus of x/y: mod(x,y) = x - floor(x/y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|noEvent(expr)<br />
|noEvent around an expression causes the expression to NOT generate event.<br />
'''Important:''' <br />
:If you want a condition to be checked only on time steps, use noEvent.<br />
:(e.g. if noEvent(value >= 1) then ... else ...)<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|pre(x)<br />
|Returns the preceding value of y from time event that has occured before current time.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|rem(x, y)<br />
|Returns the integer remainder of x/y: rem(x,y) = x - div(x,y) * y.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sample(start, interval)<br />
|Returns true and triggers time events at times start + i * interval (i=0,1,...).<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sign(x)<br />
|Returns -1 if x is negative, 1 if x is positive. Expanded into "(if x > 0 then 1 else if x < 0 then -1 else 0)".<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sin(x)<br />
|Sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sinh(x)<br />
|Hyperbolic sine.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|sqrt(x)<br />
|Square root of x. The value of x must be greater or equal to 0 or an assertion error occurs.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tan(x)<br />
|Tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|tanh(x)<br />
|Hyperbolic tangent.<br />
|-style="border-top: 1px solid #CCCCCC;"<br />
|terminal()<br />
|Returns true at the end of a successful simulation.<br />
|}<br />
<br />
<br />
<center><br />
[[Simantics]] | ''System Dynamics Modelling''<br />
</center><br />
<br />
----<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Basic System Dynamics Modelling]]'''<br><br />
System dynamics modelling in Simantics is a free modelling tool that is included into the basic installation. This tutorial introduces the basic features of the system dynamics modelling tool.<br />
[[image:Preferences-system.svg|60px|left]]<br />
'''[[Tutorial: Advanced System Dynamics Modelling]]'''<br><br />
This tutorial introduces the more advanced features of the system dynamics modelling tool: Modules and Operating interfaces<br />
<br />
[[Category: Simantics System Dynamics]]</div>Teemu Lempinen