Reference Manual 20

Reference Manual 20
20-sim 4.6 Reference Manual
© 2017, Controllab Products B.V.
Authors: Ir. C. Kleijn, Ir. M. A. Groothuis, H.G. Differ MSc
Disclaimer
This manual describes the modeling and simulation package 20-sim.
C ontrollab Products B.V. makes every effort to insure this information is accurate and
reliable. C ontrollab Products B.V. will not accept any responsibility for damage that may
arise from using this manual or information, either correct or incorrect, contained in this
manual.
Information in this document is subject to change without notice. No part of this
document may be reproduced or transmitted in any form or by any means, electronic or
mechanical, for any purpose, without the express written permission of C ontrollab
Products B.V.
Windows is a registered trademark of the Microsoft C orporation, USA.
MATLAB is a registered trademark of The MathWorks, Inc., USA.
Portions of this software are copyright © 2017 The FreeType Project (www.freetype.org).
All rights reserved.
Reference
Kleijn, C ., Groothuis, M.A., Differ H.G.
20-sim 4.6 Reference Manual
Enschede, C ontrollab Products B.V., 2017
ISBN 978-90-79499-19-9
Information
C ontrollab Products B.V.
Address: Hengelosestraat 500
7521 AN Enschede
the Netherlands
Phone:
+31-85-7731872
Internet: www.20sim.com
E-mail:
www.controllab.nl
[email protected]
Table of Contents
1
Welcome to 20-sim
1
2
What is new in 20-sim?
2
3
Requirements
5
4
Installation
6
4.1
Versions of 20-sim
6
4.2
Installing 20-sim
7
4.3
Uninstalling
9
4.4
Deactivation
9
4.5
Unattended Installation
10
4.6
Unattended Uninstall
10
4.7
Matlab
10
5
Editor
13
5.1
Introduction
13
5.2
Using Models
21
5.3
Compiling
46
5.4
Icon Editor
56
5.5
Global Relations Editor
58
5.6
Interface Editor
64
5.7
Domains, Quantities and Units
68
6
Simulator
75
6.1
Introduction
75
6.2
Running a Simulation
78
6.3
Run Properties
7
Language Reference
7.1
Introduction
111
7.2
Keywords
120
7.3
Types
129
101
20-sim 4.6 Reference Manual
111
i
7.4
Functions
132
7.5
Operators
201
7.6
Statements
221
7.7
Matrices and Vectors
236
7.8
Advanced Topics
239
8
Toolboxes
8.1
3D Mechanics Toolbox
246
8.2
Animation Toolbox
282
8.3
Control Toolbox
318
8.4
Frequency Domain Toolbox
362
8.5
Mechatronics Toolbox
395
8.6
Real-Time Toolbox
464
8.7
Time Domain Toolbox
475
8.8
Scripting Toolbox
516
9
Library
9.1
Bond Graph
534
9.2
Iconic Diagrams
584
9.3
Signal
921
10
Modeling Tutorial
246
534
1132
10.1 Friction
1132
10.2 Bond Graphs
1142
10.3 Iconic Diagrams
1173
Index
1188
20-sim 4.6 Reference Manual
ii
1. Welcome to 20-sim
1
Welcome to 20-sim
This manual describes 20-sim 4.6 in full detail. It is not a getting started manual but
intended as a detailed reference to the software. If you are a first time user you are
advised to read the Getting Started manual first:
If you are an experienced 20-sim user, you can read the change notes first and then
search the topic of your interest.
20-sim 4.6 Reference Manual
1
2. What is new in 20-sim?
2
What is new in 20-sim?
General
20-sim 4.6 has been updated to support Microsoft Windows 10. While older versions of
20-sim will (mostly) work under Windows 10, 20-sim 4.6 has been specially developed
and tested for this latest version of the Microsoft Windows family.
The following new major features have been added to 20-sim 4.6:
GUI look-and-feel now adapts to the Windows version dependent look-and-feel.
FMI support: The Functional Mockup Interface (FMI) is a tool-independent standard to
support model exchange. 20-sim now supports exporting models as FMUs (Functional
Mockup Units).
Python Scripting: 20-sim supports now scripting from a Python script. This means
that you can now use Python to automate and control 20-sim next to the existing
Octave/Matlab scripting support.
20-sim can be used to develop training simulators.
Editor
1.
Gradient Fill of submodels is standard on. You can turn this off in the General
Properties (click Tools - Options).
2.
Version numbers can be defined for each 20-sim model. The version numbers can
be shown in the model background image. Version numbers are also available as
tokens during the C -code generation.
3.
Use C trl + Mouse Wheel to zoom in and out.
4.
20-sim now also supports the 64-bit version of Matlab for the exchange of data
between 20-sim and Matlab. This applies to the domatlab, tomatlab, frommatlab
functions and the Matlab buttons in the 20-sim GUI (e.g. the Linear System Editor)
5.
Drawing closed curves has been improved.
Simulator
1.
Using the C -code generation command, you can now export models using the FMI
standard. Both version 1.0 and 2.0 of the FMI standard are supported.
2.
The Variables C hooser allows you to show or hide knots.
3.
Faster plot curve drawing on multi-core systems.
Language
1.
A new function realtime is added. It can be used to check if the simulation runs
slower or faster than the wall-clock time.
2.
The bitshift operator now also supports right shift.
Library
1.
Bond graph II-element added.
20-sim 4.6 Reference Manual
2
2. What is new in 20-sim?
2.
Double clicking a library model opens it in the editor.
3D Animation Toolbox
1.
You can show plots and 3D animations in full screen.
2.
Multiple 3D animations are drawn more efficiently resulting in higher frame rates.
3.
You can show or hide individual objects by clicking the Solo or Hide option.
4.
You can show the frame rate in a 3D Animation and set the frame rate to a
maximum.
5.
You can connect the transparency to a variable.
3D Mechanics Toolbox
1.
Support of global parameters for inertia's and global parameters for joints with
spring/dampers.
2.
Support of flexibility in joints by overriding constraint settings.
3.
C trl + Mouse Wheel to zoom in and out.
Scripting
1.
Scripting from Python is now supported with similar functions as in Octave/Matlab.
2.
MIMO linearization support added to xxsimLinearizeModel in Octave/Matlab.
3.
New Octave/Matlab scripting functions:
o
xxsimC lose
o
xxsimSavePlotAsBitmap
o
xxsimStartSimulation
o
xxsimStopSimulation
o
xxsimIsSimulating
o
xxsimC opyStatesToInitials
o
xxsimOpenSimulator
o
xxsimSetTimeout
o
xxsimGetImplementations
o
xxsimGetMemoryUsage
o
xxsimGetPlotIDFromName
o
xxsimGetPlotsFromWindow
o
xxsimGetPlotWindowIDFromName
o
xxsimGetPlotWindows
4.
Support of Octave 4.0 (with GUI).
5.
Scripting API documentation is now also accessible from the Help menu.
20-sim 4.6 Reference Manual
3
2. What is new in 20-sim?
Bugfixes and Improvements
General
1.
All open 20-sim windows will be closed when the Editor is closed.
Editor
1.
When changing the colors of models directly in the Graph Editor these changes are
stored after saving the model.
2.
Models cannot be placed any more outside the border and get out of view.
3.
Line drawing can be stopped with the escape key and stops with right mouse button.
4.
When removing a submodel implementation, it is first asked which implementation
to remove.
5.
Drag-drop of a submodel with one implementation does not ask anymore which
implementation you want to select.
6.
The Global Relations Editor is now also accessible from the Tools menu.
Simulator
1.
Endless simulation does not call finalequations anymore.
2.
Warning given by incorrect input of eye function.
3.
The last selected code-generation path will now be remembered and stored in the
model.
Code generation templates
1.
Add support for XXRealtime() (ANSI-C version of the realtime function).
2.
Slightly faster RungeKutta4 integration routine.
3.
Added VS2015 solutions.
4.
starttime and finishtime are not generated as hardcoded values anymore.
Library
1.
Updated the icons of various sensor blocks to show a proper +/- pair after a rotation
with 90 degrees.
2.
Updated all library blocks with integral symbols to use the Unicode compatible Lucida
Sans font now instead of SymbolProp. This allows proper HTML export for 20-sim
drawings.
20-sim 4.6 Reference Manual
4
3. Requirements
3
Requirements
20-sim is supported on on computers that meet the following requirements:
Operating System: Windows Vista, 7, 8, 8.1 and 10.
Processor requirements: 20-sim requires a C PU with SSE2 support. Supported: Intel
Pentium 4 and above, AMD Athlon x64 and above.
Available Disk Space: 450 MB.
20-sim 4.6 Reference Manual
5
4. Installation
4
Installation
4.1
Versions of 20-sim
20-sim is available in two versions: Viewer and Professional.
Viewer/Demonstration version: This is a freeware version that allows you to load
and run models and evaluate the package. Saving of models is not possible in this
version.
Professional: This is the full version of 20-sim with all toolboxes.
The table below shows in detail the options that are available in the three versions:
Viewer
Professional
Library Models
v*
v
3D Mechanics Toolbox
v*
v
Animation Toolbox
v*
v
C ontrol Toolbox
v*
v
Frequency Domain Toolbox
v*
v
Mechatronics Toolbox
v*
v
Real Time Toolbox
v*
v
Time Domain Toolbox
v*
v
x
v
Scripting Toolbox
v = included
v* = included but no saving possible
x = not available
20-sim is installed, using an Installation Manager that will lock 20-sim to your computer.
There are three types of licenses available:
Free : The demonstration version comes with a license that is not locked to your
computer. No actions have to be taken after installation of the program.
Single License: A single license locks 20-sim to a specific computer. After
installation you have to register to get a valid license.
Floating License: A floating license allows multiple users to work with 20-sim at the
same time. After installation you have to register to get a valid license.
20-sim 4.6 Reference Manual
6
4. Installation
4.2
Installing 20-sim
20-sim can be downloaded from the website www.20sim.com. This is an installation file
that will install 20-sim on your computer. The first 4 steps are equal for all users.
Depending on the type of license (single, floating) you have to follow different steps to
activate 20-sim.
1.
Download and Install 20-sim on your computer.
2.
During Installation you will be asked to install the (optional) Python 3.4 package.
We advise to keep the default setting: Yes.
3.
Start 20-sim (from the Windows Start Menu choose 20-sim 4.6).
If a valid license of 20-sim 4.6 was activated before, the program will start
automatically. If you have not installed 20-sim before, the License Activation dialog will
open:
20-sim License Activation Dialog.
4.
If you have a valid license key or license file, press the Activation button to enter
your license key or browse for the license file.
If you do not yet have a valid license, press the Trial License button request an trial
license or press the Buy button to purchase a license. If you want to continue in Viewer
mode (no save functionality), just close the dialog without activating 20-sim.
5.
Select which kind of license you have and who should use the license.
20-sim 4.6 Reference Manual
7
4. Installation
License installation dialog.
Single License
If you are using a single license, you have to enter a license key or license file.
6.
On the next dialog, select I received a license key by e-mail and enter the key
in the next dialog. When you received a license file, you have to enter the
location of the license file.
Single License dialog.
You will be asked for confirmation (click Activate Now) and activation will be carried
out. After a successful activation process the License Information dialog will show the
new license.
Web Activation dialog.
20-sim 4.6 Reference Manual
8
4. Installation
Floating License
Installing a floating license (Administrator)
If you are using a license that is shared by more users (floating license, also known as
concurrent license or server license), you have enter the received license key and a
location on the server (a normal Windows shared folder) first. This location on the server
should be accessible to all users and have read/write permission. The floating license will
be stored at the selected location.
6.
On the next dialog, select First Installation and then enter the license key and
the location on the server (Windows share).
On the location that you have given, a license file 20sim.lic will be installed. Remember
the location of this file because every new user of 20-sim will need to enter it. You will
be asked for confirmation (click Activate Now) and activation will be carried out. After
a successful activation process the License Information dialog will show the new license.
Using a floating license (Other users, Administrator)
If you are using a floating license that was already installed you have to enter the
location of the license file.
7. On the next dialog, select Administrator already installed server license and
then enter the license location (the location of the file 20sim.lic).
After a successful entry of the location of the license location, the License Information
dialog will show the new license.
4.3
Uninstalling
You can uninstall 20-sim by clicking the Uninstall command from the 20-sim start menu.
Warning: Uninstallation of 20-sim will not deactivate your license. If you want to move
20-sim to another computer, you have to deactivate your license first before
uninstalling.
4.4
Deactivation
If you want to move 20-sim to another computer, you have to deactivate your license
before uninstalling the program. On the new computer you can then install the program
and activate the license. To deactivate your license:
1.
From the Windows Start menu open 20-sim.
2.
From the Help menu choose License Activation.
3.
Press the Activation button.
4.
C hoose Deactivate Current License.
20-sim 4.6 Reference Manual
9
4. Installation
You will be asked for confirmation and deactivation will start. After a successful
deactivation, your version of 20-sim has turned into the demonstration version. You can
now uninstall the software and reinstall it.
4.5
Unattended Installation
An unattended installation is an installation that is performed without user interaction
during its progress or with no user present at all.
To perform an unattended installation the default 'program files' installation directory run
the following command on the 20-sim installer:
20sim.exe /S
It is possible to set an alternative installation directory by specifying the /D argument. It
must be the last parameter used in the command line and must not contain any quotes,
even if the path contains spaces. Only absolute paths are supported.
20sim.exe /S /D=D:\My Installation Files\20-sim 4.6
4.6
Unattended Uninstall
An unattended uninstall is an uninstall that is performed without user interaction during
its progress or with no user present at all.
To perform an unattended uninstall from the default 'program files' installation directory
run the following command on the 20-sim uninstaller:
C:\Program Files (x86)\20-sim 4.6\Uninstall.exe /S
4.7
Matlab
In 20-sim you can exchange data with Matlab / Simulink in various ways:
Export models as m-files
Export models as dll-files
Export a variable to Matlab
Export a parameter to Matlab
Pass a variable value to Matlab every simulation step
Load a variable value from Matlab every simulation step
Pass a command line string to Matlab every simulation step
Export linear systems to Matlab
Import Linear Systems from Matlab
Troubleshooting
If this fails check if the following three points have been fulfilled.
20-sim 4.6 Reference Manual
10
4. Installation
1. Have the correct version of 20-sim and Matlab
To make a connection with Matlab, make sure you have 20-sim 4.1.3.8 or higher
installed and a recent version of Matlab (2007 or above).
64-bit versions of Matlab are supported starting with 20-sim 4.6.
2. Check if it works
To make the connection to Matlab, Matlab needs to be registered as a C OM-component.
Not all Matlab versions register the C OM-component automatically.
1.
In 20-sim, open the Simulator (C trl+R)
2.
Open the Tools menu
3.
C lick the Matlab button
If Matlab starts (be patient this could take some time), the Matlab C OM automation
server is registered properly and you are finished. In case the error message "Could not
start Matlab. Make sure that Matlab is installed and that the Matlab COM automation
server is enabled.", proceed with step 3 and 4.
3. Enable the Matlab COM automation server
To make the connection to Matlab, Matlab needs to be registered as a C OM-component.
This can be done in the following manner from the command line (run: cmd):
matlab /regserver
The C OM-registration only, is not enough for 20-sim to find the DLL's of Matlab. The next
step (setting the PATH variable) must be performed also
4. Matlab registration in PATH
The standard registration of Matlab in the PATH is the following (assuming Matlab is
installed in Program Files and the used version of Matlab is R2015b):
C:\Program Files\MATLAB\R2015b\bin
The following path should be added too in case of a 32-bit version of Matlab:
C:\Program Files\MATLAB\R2015b\bin\win32
In this additional path some important DLL's are present that are necessary to make the
connection. for example: libeng.dll. Please check if this DLL is present at this path. If not
try to find this DLL in your Matlab installation and add the found path to the PATH
environment.
C hanging the PATH environment variable can be done in the following manner:
1.
From "My C omputer", right mouse button: Properties:
2.
On Windows: choose Advanced Properties and go further as Admin
20-sim 4.6 Reference Manual
11
4. Installation
3.
C hoose the tab: Advanced
4.
C hoose: Environment Variables.
20-sim 4.6 Reference Manual
12
5. Editor
5
Editor
5.1
Introduction
5.1.1
Editor
20-sim consists of two main windows and many tools. The first window is the Editor and
the second is the Simulator. The Editor is used to enter and edit models. The Editor
opens automatically when you start 20-sim:
The 20-sim Editor.
The Editor consists of four parts:
Model tab / Library tab: The Model tab shows the model hierarchy, i.e. the
composition of all the elements of the model. The Library tab shows the 20-sim
library.
Graphical Editor / Equation Editor: At the lowest level of the hierarchy this editor
will show the model equations. In the higher levels this editor will show the graphical
parts of your model.
Output tab / Process tab / Find tab: The Output tab shows the files that are
opened and stored. The Process tab shows the compiler messages. The Find tab
shows the search results.
Interface tab / Icon tab / Globals tab: The Interface tab shows the interface
(inputs, outputs, ports) of a selected model. Double clicking it will open the Interface
Editor. The Icon tab shows the icon of a selected model. Double clicking it will open
the Icon Editor. The Globals tab will show the global parameters and variables of
your model. Double clicking it will open the Global Relations Editor.
20-sim 4.6 Reference Manual
13
5. Editor
Using the Editor
The best way to find your way around the Editor is to read the Getting Started manual. It
contains a number of topics that will explain the basics of entering equation models,
graphical models and run a simulation.
5.1.2
Equation Editor
Equations models are the models at the lowest level in the model hierarchy. A model
without an interface (inputs, output, ports), will have no hierarchy and is thus
automatically an equation model. If you have opened an equation model, the right part
of the Editor shows the Equation Editor. In the Equation Editor you can enter and edit
equation models.
Equation model with the Equation Editor (right part).
Use
Put your mouse in the Equation Editor and start typing. If you click on the buttons of the
taskbar, sample code is inserted. Read the language reference section to find out more.
Color Syntax Highlighting
Functions, Variables etc. are given special colors to distiguish them from the other text.
Auto Indent
If a line is indented (using the tab), the next line will start at the same indentation. You
can remove indentation by clicking the Backspace button.
Multi-Line Tabbing
You can give multiple lines of code a new indentation by clicking the tab button. Select
all the lines and click Shift-tab to remove.
20-sim 4.6 Reference Manual
14
5. Editor
5.1.3
Equation Editor Taskbar
When you select an equation model, the corresponding equations are show in the
Equation Editor. A special button bar, called the taskbar, is part of the Equation Editor.
The taskbar helps you to enter functions, statements, templates etc.
The taskbar of the Equation Editor.
Statements: click on this button to insert if-then-else expressions and more.
Functions: click on this button to insert functions.
Specials: click on this button to insert special functions.
Operators: click on this button to insert operators.
Units: click on this button to insert quantities and units.
Declarations: click on this button to insert declarations of parameters, variables
and more.
Constants: click on this button to insert predefined constants.
20-sim 4.6 Reference Manual
15
5. Editor
5.1.4
Graphical Editor
If you have opened a graphical model, the right part of the Editor shows the Graphical
Editor. In the Graphical Editor you can enter and edit block diagram models, iconic
diagram models and bond graphs.
Graphical model with the Graphical Editor (right part).
Use
Select models from the Model Library and drag them to the Graphical Editor.
You can use the buttons of the taskbar, to connect the models and change their
position.
Drag and drop image files (bitmaps, svg images,..) to enhance the appearance of
your model.
Use the buttons of the taskbar, to create your own drawings.
5.1.5
Graphical Editor Taskbar
When you view or enter a graphical model in 20-sim it is shown in the Graphical Editor.
A special button bar, called the taskbar, is part of the Graphical Editor. The taskbar helps
you to select models, connect them and manipulate them. You can also use the taskbar
to enter drawing objects. The taskbar is also part of the Icon Editor.
The taskbar of the Graphical Editor.
20-sim 4.6 Reference Manual
16
5. Editor
Selection Mode: C lick this button to select models and objects
Insert Terminals: (Icon Editor only) C lick this button to insert terminals.
Connection Mode: (Graphical Editor only) C lick this button create connections
between models.
Line: C lick this button to draw lines.
Spline: click this button to draw splines.
Rectangle: click this button to draw rectangles.
Ellipse: click this button to draw ellipses.
Text: click this button insert text.
Bitmap: click this button insert bitmaps and images in svg format.
Line Color: click this button to set the line color of a selected object.
Fill Color: click this button to set the fill color of a selected object.
Rotate and Mirror: click this button to rotate or mirror a selected object.
Arrange and Group: click this button to group objects, put them to the front etc.
Line Styles: click this button to select the line style of selected objects.
Zoom: click this button to select the zoom factor. You can also click C trl + mouse
wheel to zoom in and out.
20-sim 4.6 Reference Manual
17
5. Editor
5.1.6
Search
If you make the Editor wide enough, you will see at the top right a Search box. You can
enter terms here and search them throughout the model. The results are displayed in
the Find tab at the bottom of the Editor.
Using the Find Box to quickly search the model.
Scope: The search scope depends on which level of the model you are in. Only the
current submodel and all submodels below are searched. Select the top element in
the Model Browser (Model tab at the left of the Editor) to search the whole model.
Library: The 20-sim Library is always searched. The library results are shown below
the model search.
Jump: The Find tab shows the found items with an orange hyperlink. C lick on the
hyperlink to quickly jump to the corresponding model.
Find again (F3): C lick the F3 button to quickly jump through the found items in the
Find tab.
Menu: You can also start a search from the menu: from the Edit menu select Find.
5.1.7
Library
In 20-sim, creating models only takes you just a few mouse clicks. By dragging an
element from the library and dropping it in the graphical editor, your model is actually
built the same way as you would draw an engineering scheme. 20-sim supports various
model representations, such as block diagrams and iconic diagrams. These
representations may be combined in one model.
20-sim 4.6 Reference Manual
18
5. Editor
You can find the library at the left of the Editor.
The library contains a various sections:
Bond Graph: bond graph elements
Iconic Diagrams: Physical components
Signal: Block diagram elements
Tutorial: example models that show you how to perform various tasks in 20-sim
Getting Started: al the models that you need in the lessons of the Getting Started
manual.
Custom libraries
You can create your own model libraries in 20-sim:
1.
From the Tools menu click Options - Folders - Library Folders.
2.
Add your folder.
3.
Give it a useful name by clicking Edit Label.
4.
C lick OK to close the dialog.
Then you can add your own library models to the library:
1.
Select the submodel that you want to store in your library.
2.
From the File menu select Save Submodel.
3.
Store the submodel in your library folder.
The next time you start up 20-sim, the library will show the new submodel.
20-sim 4.6 Reference Manual
19
5. Editor
5.1.8
Options
The general properties of 20-sim models are shown in the Options dialog.
From the Settings menu choose the Options command.
From the Tools menu choose the Options command.
Editor
Fonts: Enter the default fonts used in graphical models (Editor) and equation models
(Equation Editor).
Syntax Highlighting Threshold: Select the number of characters that should be
submitted for color syntax highlighting. If this number is too large, the editor may
become very slow.
Submodel Colors: Check this option to turn Gradient Fill on. This option will
apply a slight vertical gradient to all blocks with a background color.
Plots
You can choose the default settings for a simulation plot in this tab.
Default Line Thickness : Enter the default plot line thickness.
Folders
You can choose the location of libraries and files in the Folders tab.
Library Folders: Enter the library paths and corresponding library names here. The
libraries are shown in the Library tab.
C-code Folders: C -code can be generated for various targets. For each target a file
targets.ini defines how the C -code should be generated. You can enter the locations
of ini-files here.
Matlab-Code folders: 20-sim models can be exported to Matlab. Similar to C -code
generation, a file targets.ini defines how the code should be generated. You can enter
the locations of ini-files here.
Model Template Folders: You can enter the location of model templates.
Scripting Interface
20-sim uses the XMLRPC protocol to communicate with external software and run
scripts. By default, 20-sim will only accept scripting connections from your local
computer (Localhost only option is enabled by default). The defaults setting are shown
below.
20-sim 4.6 Reference Manual
20
5. Editor
The Scripting Interface.
C ommunication can be done by:
HTTP: XMLRPC protocol.
TC P: Optimized for performance binary communication protocol.
Serial: Serial communication using the RS232 port of your computer.
In most cases the default settings should be fine. However, for each of these protocols,
settings may be changed. Ask your system administrator for details.
5.2
5.2.1
Using Models
Hierarchical Models
Any main model (or system) in 20-sim may be described as a composition of lower
level submodels. These submodels themselves may again be described as a composition
of lower level submodels etc. The lowest level consists of elementary submodels, which
do not consist of submodels themselves.
20-sim 4.6 Reference Manual
21
5. Editor
20-sim supports hierarchic model. The lowest model in the hierarchy is always an equation model.
You can inspect this in the Editor. If you click the Model tab at the left of the Editor, the
Model Browser shows complete model hierarchy: a tree like structure showing all the
submodels that are used in the model.
The Model Browser at the left of the Editor shows the complete model hierarchy.
To travel through the hierarchy, click any model in the tree. You can also select a model
in the Graphical Editor and click Go Up
or Go Down
20-sim 4.6 Reference Manual
from the Model menu.
22
5. Editor
5.2.2
Open Models
Models in 20-sim are stored with the extension .emx. You can open an existing model in
several ways:
1.
From the File menu, select Open.
2.
C lick the Library tab and from the Library drag and drop your model to the
Graphical Editor.
3.
Open a Windows Explorer. Drag and drop your model to the Graphical Editor.
You can open Packed Files with the Open dialog by selecting a file with the extension
.emz.
5.2.3
Save Models
Models in 20-sim are stored with the extension .emx. You can save an existing model in
several ways.
1.
From the File menu, select Save: This will save the complete model. If no
filename is known a Save dialog is opened.
2.
From the File menu, select Save As: This is essentially the same as the Save
command but now the Save dialog is opened even if a filename is known.
3.
From the File menu, select Save a copy As : This is similar to Save As but now a
copy of the file is saved instead. This allows the user to keep on working on the
model while saving intermediate experiments.
4.
From the File menu, select Save Submodel: This will save the submodel that is
selected in your Graphical Editor.
5.
From the File menu, select Save Encrypted: This will allow you to store a model
using encryption. If a submodel was selected, a menu is opened asking you to store
the submodel or the complete model.
Warning: Once a model is encrypted, you can not decrypt it anymore! So keep
cautious that you always store a non-encrypted original.
Encrypted models are useful if you want others to use your 20-sim model,
without seeing the underlying equations. If an encrypted model is loaded in 20sim, the Go Down command does not work on that model.
20-sim 4.6 Reference Manual
23
5. Editor
5.2.4
Packed Files
To get a simulation running in 20-sim, the data stored in various files may be needed:
.emx: model files
.txt: data files (fileinput)
.bmp: bitmap files (for use in 3D Animation)
.dll: external dll-files (user defined external functions)
etc.
You can pack all these files into one zip-file, using the Pack command from the File
menu. With this command 20-sim will check all the files that are used and store them
into a single zip-file. This option is useful for archiving and sending models by e-mail.
Pack
1. When the Pack command is clicked, a Save As dialog appears asking you to
enter a name. Always save with the default extension .emxz because 20-sim
uses this extension to recognize packed files.
After the Save As dialog, a 20-sim Pack dialog appears, showing the collected files. In
this dialog you can select the files that should be packed.
2.
Select the files that should be packed and click the OK button.
Unpack
You can open Packed Files using the Unpack command from the File menu.
1. When the Unpack command is clicked, an Open dialog appears asking you
open a file. Open a file with the extension .emxz because 20-sim uses this
extension to recognize packed files.
After the Open dialog, a 20-sim Unpack dialog appears. In this dialog you can see the
file that you have selected to unpack and you can choose the method of unpacking.
2.
If you want to unpack all files and put them in their original location, select the
option Unpack with full path.
3.
If you want to unpack all files and to a specific directory, select the option Unpack to
directory.
4.
Select Keep Relative Paths if you want to keep the original folder structure.
20-sim 4.6 Reference Manual
24
5. Editor
5.2.5
Insert Models
You can insert submodels from a library using the built in Library tab:
1.
C lick the Library tab to open the library.
2.
Select the submodel that you want to insert and drag and drop it in the
Graphical Editor.
You can also use a file browser:
1.
From the File menu, select Open Browser. The File Explorer appears.
2.
Select the submodel of interest and drag and drop it in the Graphical Editor.
5.2.6
Connecting Models
In 20-sim, submodels can be connected using the mouse. When a connection is created
it will be displayed using straight lines. When a connection has been made you can
change it into a smooth line using the right mouse menu. You can change the color of a
connection using the colorbar at the bottom of the Editor. 20-sim supports two types of
mouse use. "Tapping Mode" and "Pressing Mode". In the Tapping Mode you click the
mouse button (do not keep it pressed but quickly "tap" the button) while making a
connection. In the Pressing Mode you keep the mouse button pressed while making a
connection.
Tapping Mode
To connect two submodels using straight lines, you have to:
1.
In the toolbar, click
2.
Put the mouse pointer on top of the first submodel and click the left mouse
button (do not keep it pressed but quickly "tap" the button).
3.
Drag the mouse pointer towards the second submodel (you will see a connection
drawn from the first submodel towards the mouse pointer).
4.
Put the mouse pointer on top of the second submodel and click the left mouse
button again (do not keep it pressed but quickly "tap" the button).
5.
While dragging from the first submodel to the second, you can click the left
to change to connection mode.
mouse button (do not keep it pressed but quickly "tap" the button) to
create intermediate points.
Pressing Mode
To connect two submodels using straight lines, you have to:
1.
In the toolbar, click
2.
Put the mouse pointer on top of the first submodel and press left mouse
button (keep it pressed).
to change to connection mode.
20-sim 4.6 Reference Manual
25
5. Editor
3.
Drag the mouse pointer towards the second submodel (you will see a connection
drawn from the first submodel towards the mouse pointer).
4.
Put the mouse pointer on top of the second submodel and release the left mouse
button.
5.
While dragging from the first submodel to the second, you can click the right
mouse button to create intermediate points.
Smooth Line
To connect two submodels using a smooth line, you have to:
1.
Make a straight line connection with intermediate points.
2.
In the toolbar, click
3.
Select the connection that was created.
4.
From the right mouse menu select "smooth line".
to change to selection mode.
Tips
20-sim will automatically detect which connection has to be made: a signals, a bond
or an iconic diagram connection.
Depending on the physical domain, every connection will have a specific color. You
can change these colors in the Units Editor.
You can toggle between connection mode
space bar.
5.2.7
and selection mode
by pressing the
Implode / Explode
Using the Implode command of the Editor menu you can quickly create a new
submodel out of a set of select submodels.
1.
In the toolbar, click
2.
Select the the submodels.
3.
From the Edit menu, click the Implode command.
to change to selection mode.
Using the Explode command of the Editor menu you can quickly open the contents of a
selected submodel in the current model layer.
1.
In the toolbar, click
2.
Select a submodel.
3.
From the Edit menu, click the Explode command.
to change to selection mode.
20-sim 4.6 Reference Manual
26
5. Editor
5.2.8
Simplify Models
Use the Simplify Model command to simplify graphical models according to the following
rules:
Block Diagrams
1. Comb ining splitters.
2. Combining of multiplications and/or divisions.
Bond Graphs
1.
Eliminating junctions.
2.
Melt equal junctions.
3.
Eliminating double differences.
Iconic Diagrams
1.
Eliminating nodes.
To simplify a (sub)model, you have to:
1. Select the complete model or submodel of which you want to simplify.
2. From the Model menu select the Simplify Model command.
5.2.9
Check Models
To check a complete model, you have to:
1. From the Model menu select the Check Complete Model command. Now the
complete model will be checked.
If any warnings or errors are found, they are displayed in Process tab of the Editor.
20-sim 4.6 Reference Manual
27
5. Editor
In the Process tab the compiler messages are displayed.
2. Put you mouse on top of an error message and click.
20-sim will jump to the part where the error was caused. You can try to solve the error
and check again.
5.2.10 Model Properties
The properties of 20-sim models are shown in the Model Properties dialog. You can open
the Model Properties in various ways.
Select the proper model in the Model Browser and then click Properties from the
Right Mouse menu.
Select the model in the Graphical Editor and then click Properties from the Right
Mouse menu.
From the File menu choose the Properties command.
From the Settings menu choose the Model command.
From the Settings menu choose the Submodel command.
Depending if a submodel was selected or a main model, various tabs are visible:
20-sim 4.6 Reference Manual
28
5. Editor
The model properties dialog.
Description
In this tab you can enter the name of the submodel and enter various fields to
classify a model. The most important elements are:
Name: Enter a unique name for the model.
Help Page: Enter the location of a help page that should be displayed when
you click F1 or Help.
Version: The version number of the model. The version number can be
displayed in the background and is included if you generate C-code from the
model.
Library
In this tab you can find information on location of the model and some important
properties.
Version: The version of 20-sim that was used to create the model.
Library Path: If the model was stored in a known library, the path is shown.
Library File: The relative location of the submodel in the library or the absolute
location of the model submodel on your computer.
Created: The date of creation.
Main Model / Submodel: Shows if the model is a main model or submodel.
Allow model updates: Allow the C heck for Model Updates command to check if there
is an update available for this model.
Replace parameters when this model is used to update another model: If you drag
and drop a model from the library on top of an existing model, it will be replaced.
Select this option if you want the original parameters to be replaced as well.
20-sim 4.6 Reference Manual
29
5. Editor
Background Image
In this tab you can specify a background image for the model. If the model is a
graphical model, in the background the image is shown.
None: default, no image shown.
Inherit From Parent: Use the background that was defined one model higher in the
model hierarchy.
Static Bitmap: Specify the bitmap file to be used.
Script File: You can specify a script file if you want to use a dynamic background.
Scaling: Scaling of the background image.
Processing
This tab is only available for main models. 20-sim can operate in two modes: Debug
Mode and Fast Mode. In this tab you can define settings for both modes.
Warnings/Errors
Model contains algebraic variables: See the section on algebraic loops.
Model contains algebraic loops: See the section on algebraic loops.
Algebraic variables solved: See the section on algebraic loops.
Model contains constraint variables: See the section on constraints.
Constraint variables solved: See the section on constraints.
Model contains dependant states: The model contains differential equations which
could not be solved.
Dependent states are transformed: The model contains differential equations which
were solved.
Output is not used: Output signals that are not used for connections to other models.
Input is not used: Input signals that are not used for connections to other models (to
make such models simulate, a zero input value is applied to all not-connected inputs)
Port is not used: Ports that are not connected.
Parameter is not used: Parameters that are defined but not used.
Matrix is assigned a scalar: A matrix is assigned to a scalar.
Variable is not used: Variables that are defined but not used.
Variable Multiple set: Variables that are assigned a value more than once.
Variable is never given a value: Variables that are never assigned a value.
Variable is set but not used: The variable is assigned a value but never used.
Unit Conversion when SI disabled: Not relevant yet.
Unit Conversion when SI enabled: A unit conversion was found.
Unit missing for variable when SI disabled: Not relevant yet.
Quantities Mismatch: Variables with different quantities are compared.
Unit is unknown: A unit has been used that is not available in the Quantities and Units
file.
Equations interpreted as code: Equations can only be valid when interpreted as
sequential code. For example when variables are assigned more then once.
20-sim 4.6 Reference Manual
30
5. Editor
Possible loss of data at type conversion: A type conversion has been found that may
lead to loss of precision digits.
Type conversion found: A type conversion has been found.
Conversion of booleans found: A type conversions involving booleans has been
found.
Model optimization
Transform Dependents States: Try to solve differential equations.
Solve algebraic variables: Try to analytically solve algebraic loops.
Remove Redundant Equations: Try to remove equations that do not influence model
behavior.
Optimize Equation Structure: Try to separate equations into an input section, a
dynamic section and an output section.
Optimize Static Expressions: Move expressions with constant output throughout the
simulation to the static part of the model equations.
Optimize Duplicate Expressions: C alculate and expression only once and use the
result everywhere.
Optimize Divisions: Rewrite divisions as multiplications whenever possible.
Simulator
This tab is only available for main models. You can set the simulator properties here.
Initialize variables at start of simulation: You can choose to set any variable that
was not given a proper value, to zero at the start of a simulation. You can also
choose to set the value to NaN to make detection more easy.
Calculate Hold Instruction During Initialization: C alculate an output for hold
functions during the initialization of the a simulation.
5.2.11 General Properties
The general properties of 20-sim models are shown in the Options dialog.
From the Settings menu choose the Options command.
From the Tools menu choose the Options command.
Editor
Fonts: Enter the default fonts used in graphical models (Editor) and equation models
(Equation Editor).
Syntax Highlighting Threshold: Select the number of characters that should be
submitted for color syntax highlighting. If this number is too large, the editor may
become very slow.
Submodel Colors: Check this option to turn Gradient Fill on. This option will
apply a slight vertical gradient to all blocks with a background color.
Plots
You can choose the default settings for a simulation plot in this tab.
20-sim 4.6 Reference Manual
31
5. Editor
Default Line Thickness : Enter the default plot line thickness.
Folders
You can choose the location of libraries and files in the Folders tab.
Library Folders: Enter the library paths and corresponding library names here. The
libraries are shown in the Library tab.
C-code Folders: C -code can be generated for various targets. For each target a file
targets.ini defines how the C -code should be generated. You can enter the locations
of ini-files here.
Matlab-Code folders: 20-sim models can be exported to Matlab. Similar to C -code
generation, a file targets.ini defines how the code should be generated. You can enter
the locations of ini-files here.
Model Template Folders: You can enter the location of model templates.
Scripting Interface
20-sim uses the XMLRPC protocol to communicate with external software and run
scripts. By default, 20-sim will only accept scripting connections from your local
computer (Localhost only option is enabled by default). The defaults setting are shown
below.
The Scripting Interface.
C ommunication can be done by:
HTTP: XMLRPC protocol.
TC P: Optimized for performance binary communication protocol.
Serial: Serial communication using the RS232 port of your computer.
In most cases the default settings should be fine. However, for each of these protocols,
settings may be changed. Ask your system administrator for details.
20-sim 4.6 Reference Manual
32
5. Editor
5.2.12 Check Energetic Behavior
If you select the Check Energetic Behaviour command of the Model menu, 20-sim
will check the complete model and generate additional variables. The additional
variables will only be generated for submodels with powerports:
power for every power port.
the net power that flows into the submodel (total sum of all the powers).
the net energy of the submodel (integrated net power)
This command is the same as C heck C omplete Model command but will generate extra
variables:
Sumodelname\port.power: the net power flow of the port.
Sumodelname\summated_port_power: the net power flow into the model.
Sumodelname\summated_port_energy: the net energy of the model.
You can inspect these variables during simulation in the Variable C hooser.
5.2.13 Analyze Causality
C ausal analysis is the procedure to get the model equations correct form. For Bond
Graph models this means that the direction of the efforts and flows of the bonds have to
be determined. The result of the analysis is displayed by causal strokes (denoted by |).
For Iconic Diagrams this means that the direction of the across and through variables of
the connections have to be determined. The result of the analysis is displayed by causal
arrows (denoted by -> ).
To perform causal analysis you have to:
1. From the Model menu select the Analyze Causality command. Now causality
will be assigned in the complete model.
Bond Graphs
C ausal strokes are shown in Bond Graphs automatically.
Setting C ausality can also be done by hand. Just select a bond and choose Properties
from the right mouse menu. A menu pops up in which you can set causality by hand.
The corresponding causal stroke is displayed in green (denoted by |).
20-sim 4.6 Reference Manual
33
5. Editor
User defined causality (denoted by |).
If 20-sim fails to perform a causal analysis of the model (a causal conflict), the
corresponding bond is displayed red.
A causal conflict (denoted by the red bond).
Some submodels have a preferred causality. If assignment of the preferred causality
is not possible (because of other constraints), the corresponding causal stroke is
displayed in orange (denoted by |).
Preferred causality not assigned (denoted by |).
To see the order in which automatic causality assignment has been performed,
choose Causality Info from the View menu.
Iconic Diagrams
C ausality in Iconic Diagrams is only shown when you select the Causality Info
command of the View Menu.
Causal Information shown by arrows.
If 20-sim fails to perform a causal analysis of the model (a causal conflict), the
corresponding connection is displayed red.
20-sim 4.6 Reference Manual
34
5. Editor
5.2.14 Implementations
A model may have various implementations. It means that you can combine several
versions of a model and store them in one file. If you drag and drop a model with
implementations, 20-sim will ask which one to use.
Example
A fine example of a model with various implementations is the model
MachineDynamics.emx from the Examples\1D mechanics library. This example model
has several submodels with implementations:
SpringDampers
SignalGenerator-Sweep
The selected implementation is shown between brackets in the Model Browser .
When you drag and drop a model with implementation into the Graphical Editor you will
be asked which implementation to use. In the Model Browser, the chosen
implementation is shown between brackets (Default and ZeroMean in the picture above).
If you hover the mouse above a submodel with an implementation, you also see the
chosen implementation between brackets. While modeling, you may decide to change
the implementation. This can easily be done by selecting the submodel and clicking the
right mouse menu. C hoose Implementation and select the implementation that you want
to use.
Construction
You can make submodels with implementations yourself:
1.
Select a submodel.
20-sim 4.6 Reference Manual
35
5. Editor
2.
From the right mouse menu choose Edit Implementation and Add New.
3.
Enter the name of the implementation and click OK.
4.
Store the submodel using the Save Submodel command of the File menu.
Changes
You can change the implementation:
1.
Select the submodel.
2.
From the right mouse menu choose Edit Implementation and select the
implementation that you want to change.
3.
Make the changes that you want in the submodel.
4.
Store the submodel using the Save Submodel command of the File menu.
5.2.15 Continuous-Time and Discrete-Time Models
In 20-sim you can model continuous-time systems, discrete-time systems and
combinations of continuous-time systems and discrete-time systems (hybrid) systems.
By default, models in 20-sim are continuous-time, and simulated using continuous-time
integration methods. However, the program will automatically identify discrete-time
parts in a model and simulate them at a fixed rate.
Continuous-Time
C ontinuous-time models describe real-world processes. To simulate a continuous-time
model, the model will be calculated many steps per second to get a result that is a good
representation of the real-world process. If you model a car suspension system, about
100 steps per second might be sufficient to give a good representation of the behaviour
of the car. If you model an electronics circuit, 100.000 steps per second might be
required. The default integration method in 20-sim will automatically choose the required
steps per second.
Discrete-Time
Discrete-time models describe processes that run on computers at a fixed rate. To
simulated a discrete-time model, you only have to indicate the rate at which the model
should be calculated. This is called the sample rate or sample frequency. The sample
rate of a discrete-time part can be set in the Simulator.
Mixed Models
In 20-sim you can model in continuous-time and discrete-time. Mixed models containing
discrete-time parts and continuous time parts are supported as well. The example below
shows a continuous time model of a PI-controlled system at the top. At the bottom the
same system is shown with a discrete time controller and a continuous-time system. The
discrete-time part is indicated by green input and output lines.
20-sim 4.6 Reference Manual
36
5. Editor
Discrete-time parts of a model are indicated by green inputs and outputs.
Identification of Discrete-Time Parts
In 20-sim every model is continuous-time by default. Discrete-time parts of a model are
identified by the occurrence of special functions:
sample
hold
next
previous
sampletime
Normally these functions are hidden in the equations that describe a submodel, but 20sim will automatically recognize that the input or output of such a function should be
discrete-time. If the output is discrete-time it is propagated to the next function, which
output is then also "tagged" as discrete-time, and so on until the whole discrete-time
part of a model is identified. A discrete time part of a model is indicated by green inputs
and outputs (see previous picture).
Connection
C ontinuous-time parts of a model can be connected to discrete-time parts, by using the
functions:
sample: The sample function has a discrete-time input and continuous-time output.
hold: The hold function has a continuous-time input and a discrete-time output.
You can find these functions for example in the following library models:
DA.emx (Discrete to Analog C onverter)
20-sim 4.6 Reference Manual
37
5. Editor
AD.emx (Analog to Digital C onverter)
Encoder.emx (Optical Encode)
Forbidden Functions
In a discrete part of a model, certain functions are not allowed, because they
are specifically meant for the use in continuous-time models:
algebraic
constraint
ddt
dly
event
eventdown
eventup
frequencyevent
int
limint
tdelay
timeevent
If you use a library model that contains such a function in a discrete-time part,
an error message will be given.
5.2.16 Working with Multi-Dimensional Models
Multi-Dimensional models are models that have connections which are of a size [n,m]
with either n or m larger than one. Here n is the numbers of rows and m is the numbers
of columns. More information on this matrix notation can be found in the topic on
matrices and vectors.
The advantage of multidimensional models is shown in the example below. On top two
submodels are connected by three (single) signals. The same submodels are also shown
below, connected by one multi-dimensional signal of size [3,1]. If these submodels have
to be used a lot, multi-dimensional signals or multi-signals, are easier to use. Multidimensional signals, bonds and connections are shown in 20-sim by double lines.
20-sim 4.6 Reference Manual
38
5. Editor
The Secret: Multi-Dimensional Ports
The secret of multi-dimensional models is hidden in the model interface. If you open the
Interface Editor to inspect an interface, you will notice that each port (signal, iconic
diagram or bond graph) has a default size (dimension) of 1 (1 Row, 1 C olumn). By
increasing the number of rows and/or columns this size can be increased.
Definition of Multi-ports: increase the number of rows or columns.
20-sim 4.6 Reference Manual
39
5. Editor
The Trick: Automatic Connection
When two submodels are connected, 20-sim will automatically check for the port-sizes
and create a connection:
1.
If the port-sizes are unequal, an error message will be generated.
2.
If both ports have size one, a single signal, bond or connection will be drawn.
3.
If both ports have a size larger then one, a multi-signal, multi-bond or multi-
connection will be drawn.
The Finishing Touch: Matrices and Vectors
Behind each multi-dimensional submodel, there are equations in the end. To combine
multi-dimensional ports with equations, you can use matrices and vectors. 20-sim has a
large connection of matrix and vector functions and operators, to help you define any
possible matrix equation. For example the gain model in the picture on top, could have
been described as shown below.
Use the matrix and vector notation to define the model equations.
5.2.17 Exporting Models
There are several methods to export 20-sim models.
Export to previous versions of 20-sim
20-sim 4.6 Reference Manual
40
5. Editor
You can save a model file using the Save command or the Save As command from the
File menu. If you want to save part of you model, use the Save Submodel command
of the File menu. A Save dialog will be opened in which you can enter the model name
and location. At the bottom of the dialog, you can use the Save As Type box to select the
file type:
Model files (*.emx) Standard 20-sim 4.x format
Packed files (*.emz) Zipped file including all linked files (e.g. datafiles,
dll's, bitmaps etc.)
Sidops
text
files Save model as text file.
(*.txt)
Export to zip file
You can save a model and all externally linked files into one zip-file, using the Pack
command of the File menu. With the Unpack command of the File menu, you can open
these zip-files.
Export to Clipboard
From the File menu click Export and To File to export a selected model as a drawing
to the clipboard (Windows Enhanced Metafile format).
Export to File
From the File menu click Export and To File to export a selected model as a drawing
to a file (Windows Enhanced Metafile format).
Export to HTML
From the File menu click Export and To HTML to export the model, simulations etc. to
an HTML file for the use in a word processor.
Export to Bitmap
From the File menu click Export and To Bitmap to export a selected model as a
drawing to a file (png format).
Export to Matlab (m-file)
To export 20-sim models to Matlab, from the Editor you have to select the File menu
and then click Export to Matlab/Simulink command. This will open a Matlab-Code
Generation dialog. You can choose to export a complete model or a submodel. In both
cases, three m-files are generated:
ModelName.m: A file containing the model equations and special 20-sim functions.
The model equations are directly translated from the equations that are shown with
the Show Equations command of the Model menu.
ModelName_run.m: An example file showing you how to run a simulation with the
exported model in 20-sim.
ModelName_print.m: This file contains a function that is used in the run file.
Export to Simulink (m-file)
20-sim 4.6 Reference Manual
41
5. Editor
20-sim models are exported to Simulink S-functions. S-functions are block diagram
elements of which the internal description can be an m-file or a dll-file. 20-sim can
export both types. M-files can be opened from within Matlab and are therefore more
accessible. Dll-files are compiled out of C -code, which makes them inaccessible, but a lot
faster. Simulink does not support powerports. Therefore the powerports in a 20-sim
model are translated to input and output ports.
To export 20-sim models to Simulink with an m-file description, from the Editor select
the File menu and then click Export to Matlab/Simulink command. This will open a
Matlab-Code Generation dialog. You can choose to export a complete model or a
submodel. In both cases, two files are generated:
ModelName_.mdl: The exported 20-sim model based on a m-file that describes the
model.
ModelName.m: An m-file that contains the model equations and special 20-sim
functions. The model equations are directly translated from the equations that are
shown with the Show Equations command of the Model menu.
Export to Simulink (dll-file)
To export 20-sim models to Simulink with an dll-file description, from the Simulator you
have to select the Tools menu and then click the C-code generation command. This
will open the C-code Generation dialog where you can choose to export to a Simulink Sfunction.
If you select the OK button, ANSI C -C ode will be generated and compiled into a dllfunction. Some files will be generated of which two are needed in Simulink:
ModelName_.mdl: The exported 20-sim model based on a dll-file that describes the
model.
ModelName.dll: A dll-file that contains the model equations and special 20-sim
functions. The model equations are directly translated from the equations that are
shown with the Show Equations command of the Model menu.
5.2.18 Documentation Editor
The Documentation Editor can be open from the File menu in the 20-sim Editor by
clicking Document. The Document Editor can be used to generate an html document that
can be used for Word Processors and Presentation software.
The Document Editor will generate an html document that is fully hyperlinked. From a
table of contents you can click to go to the desired part of the document. You can also
click in pictures to go to the desired submodels.
20-sim 4.6 Reference Manual
42
5. Editor
The 20-sim Documentation Editor.
General Items
File: Select the output file.
Source: Select the whole model or parts of it.
Submodel: If documentation of a part of the model should be documented,
select the desired submodel.
Model
Table of Contents: Select this option to start the document with a table of contents.
Information: Information on the creation date, user, file location etc.
Structure: The model hierarchy (list of all submodels, their submodels etc.).
SubModel
Information: Information on the creation date, user, file location etc.
Icon: The picture of the submodel icon.
Interface: The inputs, outputs and ports.
Implementation: The model implementation with equations at the lowest level.
Simulation
Constants: List of the constants that are used in the model.
Parameters: List of the parameters that are used in the model.
Initial Values: List of the starting values of the states of the model.
Plots: Show pictures of the plots.
Plot Properties: Show the plot settings.
Frequency Response: Show the frequency responses.
Favorite Parameters: List of the favorite parameters that are used in the model.
Favorite Variables: List of the favorite variables.
Variables: List of the variables.
20-sim 4.6 Reference Manual
43
5. Editor
Run: list of the run settings.
Multiple Run: List of the multiple run settings.
5.2.19 Check for Model Updates
Most 20-sim models will be built using predefined submodels from a library. You can use
the Check for Model Updates command of the Models menu to see if there are updates
of these submodels. A window will open, showing you all the predefined library
submodels.
Items
Library Paths: This part shows the libraries that are included in the search for
predefined submodels. You can select or deselect these libraries. You can add
your own libraries in the General Properties window.
Models: This part shows all the submodels of which a match has been found in
the libraries.
Model Name : The local name of the submodel.
Status: Shows if the match is older, equal or newer.
Original Filename : Original name of the submodel file.
Original Directory: Original location of the submodel file.
Model Time Stamp: Time when the used model was saved.
Library Time Stamp: Time when the library model was saved.
Note
The Check for Model Updates command will only check the time stamp of a model. If
you have changed a submodel, without saving it, the time stamp is not altered.
To prevent models from being included in the updates check, switch off the Allow
model updates option of the Model properties.
20-sim 4.6 Reference Manual
44
5. Editor
If you are not sure if a submodel should be changed, open the new library submodel
in a separate Editor first.
5.2.20 Backgrounds
Graphical models may be shown with a background picture. In the Editor from the
Settings menu choose the Model command to define the settings.
Static Backgrounds
Static backgrounds are just bitmaps files that you can define.
Dynamic Backgounds
Dynamic Background are .svg files in which you can enter 20-sim tokens (e.g. the model
name, date, creator etc.). The tokens are replaced by 20-sim and then the .svg file has
to be converted into a bitmap image. 20-sim uses the open source software Inkscape
(http://inkscape.org) to make this conversion.
To get a clear understanding of this mechanism, have a look at the example model
Examples\Tips and Tricks\Background images\BackgroundImage.emx. You can open it
from the model library. In this model backgrounds are explained.
In the same folder where the model is stored, a background image named
background.svg can be found. This an image file which contains 20-sim specific tokens
like %SUBMODELNAME% and %DESC RIPTION%. These tokens will be automatically
replaced by 20-sim. Have a look at the example model to see the list of available
tokens.
In the same folder where the model is stored, an .xml file named
inkscape_background.xml can be found. This is a script file that replaces the tokens
and converts the .svg file into a png bitmap, using inkscape.
To create your own dynamic backgrounds:
1.
C reate an .svg image with the tokens that you want to use. Store it in the folder
where your model is located.
2.
C opy the .xml file inkscape_background.xml to your own .xml file and make it refer
to the new .svg file. Store it in the folder where your model is located.
3.
In the 20-sim model open the Model Properties. In the Background Image tab,
select Script File and enter the name of your .xml file.
5.2.21 Keyboard shortcuts
This is a list of keyboard shortcuts in the graph editor.
Navigation
Command
Open File
Print
Reload
Save File
Shortcut
[C trl] + O
[C trl] + P
[C trl] + S
20-sim 4.6 Reference Manual
45
5. Editor
Current Page
Command
Zoom in
Zoom out
Zoom reset
Zoom to fit
Shortcut
[F4]
[F5]
[F6]
[F7]
Editing
Command
C opy
C ut
Delete
Duplicate
Paste
Redo
Select All
Undo
Shortcut
[C trl] + C
[C trl] + V
[Del]
[C trl] + D
[C trl] + V
[C trl] + Y
[C trl] + A
[C trl] + Z
Search
Command
Find
Find Again
5.3
5.3.1
Shortcut
[C trl] + F
[F3]
Compiling
Compiling Models
When you enter a model and open the Simulator or when you select the Check
Complete Model command of the Model menu, the model will be compiled. During
compilation, 20-sim will perform a number of tasks.
Error Checking
Type checking: 20-sim will search for illegal type conversion and possible loss of
data.
Unit Checking: Many models in 20-sim use units and quantities. 20-sim will check for
a proper use of these units and quantities.
Optimizing Model Structure
Analyze causality: determine the causal order of equations.
Integral Form: Equations are changed to integral form as much as possible.
Solving differential equations: Differential equations are solved directly if possible.
Solving Algebraic Loops: Algebraic loops are solved to their analytical solution, where
possible.
20-sim 4.6 Reference Manual
46
5. Editor
Optimizing Equation Structure: Some equations have to be calculated only once
during each simulation step, because they do not influence the model dynamics.
Depending on their relation to the model dynamics (needed for or a result of) these
equations are calculated before the model dynamics (input equations) or after the
model dynamics (output equations)
Remove redundant equations: A lot of model equations are just assignments like
var1 = var2, where one variable is already known. 20-sim reduces these equations
from the model and maps the unknown variables to known variables.
After these tasks a complete equation model is created, which can be inspected using
the Show Equations command of the Model menu. After the complete equation model
has been created the following tasks are applied:
Compiling
Find the correct order of execution: All equations will split up into their most simple
form and rewritten into the correct order of execution.
Interpreter Code: C reate interpreter like code out of the equations. This is low level
code that can be understood by the simulation algorithms.
Machine Code: When you have the Built-In compiler option selected, the interpreter
code is compiled into platform specific 32-bit machine code. This code uses the full
power of native Pentium and 486 instructions. The result is a dramatic increase of
simulation speed: 100% to 400 %, depending on the kind of model used!
Simulation Code
The resulting code, either interpreter code or machine code, is used in the Simulator to
perform simulation runs with and therefore also know as simulation code. As we have
learned, the simulation code can be quite different from the original model equations. To
denote the function of each original model variable in the simulation code, 20-sim uses
the following names:
independent rate
independent state
dependent rate
dependent state
algebraic loop in
algebraic loop out
interesting variable
hidden variable
5.3.2
Causal Form
Equations within 20-sim may be entered in random form. During compilation, 20-sim will
automatically try to rewrite equations into a causal form and set them in a correct order.
I.e. a form where all output variables are written as function of input variables. C onsider
for example the following model:
20-sim 4.6 Reference Manual
47
5. Editor
variables
real u,z;
equations
u = sin(time);
u = cos(z);
Here the (input) variable u is given by the equation u = sin(time). C onsequently the
(output) variable z should be written as a function of u. This is exactly what 20-sim will
try to do while compiling the model into simulation code. I.e. the function cos will be
inverted and the model will be rewritten to:
variables
real u,z;
equations
u = sin(time);
z = arccos(u);
Some functions cannot be inverted. C onsequently not all equations can be rewritten. 20sim will report this to the user, during model checking.
Indifferent Causality
For some models the causal form is not known beforehand. For example the iconic
diagram model that describes a damper can be written as:
parameters
real d;
equations
p.F = d*p.v;
Here p.F denotes the force and p.v denotes the velocity of the powerport p. There is no
preferred input (force or velocity). This can be explicitly stated, by giving the powerport
p an indifferent causality. During compilation 20-sim will determine whether p.F or p.v is
the input variable and consequently rewrite the equations.
Preferred Causality
For some models there is a preferred causal form. For example the iconic diagram
model that describes a spring can be written as:
parameters
real k;
equations
p.F = (1/k)*int(p.v);
Here p.F denotes the force and p.v denotes the velocity of the powerport p. The equation
is written in integral form which is preferred. C onsequently the preferred input is the
velocity. Should the force be the input, the equation must be rewritten to a differential
form, which is leads to less efficient simulation. This can be explicitly stated, by giving
the powerport p an preferred causality. During compilation 20-sim will try to keep the
model in this preferred form. If this is not possible the equations will be rewritten to the
less preferred form.
Preferred causality has a lower priority than fixed causality. During compilation 20-sim
will first assign all models with a fixed causality and then all models with preferred
causality.
20-sim 4.6 Reference Manual
48
5. Editor
Likes Causality
For some models there is a causal form which is liked more than the other. For example
the iconic diagram model that describes a parasitic volume can be written as:
effortincausality(p) then
p.phi = 0;
else
volume_ratio = int(p.phi/V);
p.p = B * volume_ratio + p_initial;
end;
Here p.phi denotes the volume flow and p.p denotes the pressure of the powerport p.
The equation is written in integral form which is liked. C onsequently the preferred output
is the pressure. Should the pressure be the input, the equation gives a zero flow as
output. During compilation 20-sim will first try to keep all models the liked form. If this is
not possible the equations will be rewritten to the other form.
Liked causality has a lower priority than preferred causality. During compilation 20-sim
will first assign all models with a preferred causality and then all models with likes
causality.
Fixed Causality
For some models there is only one causal form. For example a simple iconic diagram
model that describes coulomb friction can be written as:
parameters
real Rc;
equations
p.F = Rc*abs(p.v);
Here p.F denotes the force and p.v denotes the velocity of the powerport p. The equation
cannot be rewritten to a form where p.F is the input. This can be explicitly stated, by
giving the powerport p a fixed causality. During compilation 20-sim will try to keep the
model in this fixed form. If this is not possible an error message will be generated.
Fixed causality has a lower priority than a likes causality. During compilation 20-sim will
first assign all models with a likes causality and then all models with fixed causality.
Setting Causality
For some models, the equations are too complex to analyze causality. To help 20-sim,
using the right causality, you can set causality for every port in the Interface Editor.
20-sim 4.6 Reference Manual
49
5. Editor
5.3.3
Integral Form
C onsider the following first order linear model:
This model can be described by the dynamic equation:
output = int( input - K*output )
Now look at the following model:
This model can be described by the dynamic equation:
output = ( input - ddt(output) )/K
Note that we can rewrite this equation as:
ddt(output) = input - K*output
or
output = int( input - K*output )
This is the same equation as the previous model! Apparently, both models are the same!
Both models can therefore be described by the dynamic equations:
ddt(output) = input - K*output
output = int( input - K*output )
We call the first equation the differential form (no integrals). The second equation is
called the integral form (no derivatives). In 20-sim, models can be entered in integral
form as well as the differential form.
Solving Differential Equations
During compilation, 20-sim will automatically try to rewrite equations into the integral
form, since this leads to more efficient simulation. Sometimes an integral form cannot be
found. Then algorithms will be applied to solve the differential directly. For example an
equation like:
output = ddt(sin(a*time))
20-sim 4.6 Reference Manual
50
5. Editor
will be replaced by the following equation (applying the chain rule and using the known
derivative for the sine function):
output = a*cos(a*time)
Sometimes a differential cannot be solved directly. Then
Differentiation Methods can be used for simulation.
only
the
Backward-
Simulation Code
After compilation simulation code is generated. The equation in integral form:
output = int( input - K*output )
will be written as:
independent state = output
independent rate = input - K*output
and can be handled by all integration methods. The equation in differential form:
ddt(output) = input - K*output
will be written as:
dependent rate = input - K*output
dependent state = output
and can only be handled by the Backward-Differentiation Methods.
5.3.4
Algebraic Loops
An algebraic loop in a model is a loop consisting of elements without "memory like"
functions. To calculate the variables in this loop, the variable values themselves are
needed. C onsider the following example of an algebraic loop in an amplifier with
negative feedback:
Standard derivation of a simulation model would yield:
x = K*(u-x)
The variable x depends on its own value and must be solved by iteration. In 20-sim
every simulation algorithm is accompanied by an iteration routine. Fortunately 20-sim is
able to solve many algebraic loops at equation level. For this model this leads to the
analytic solution the system:
20-sim 4.6 Reference Manual
51
5. Editor
x = K*u/(1+K)
Simulating algebraic loops
Although 20-sim contains a sophisticated algorithms to find analytic solutions, the
occurrence of unbreakable loops can not always be prevented. The occurrence of
algebraic loops may lead to an increase of simulation time, or even stop simulation when
iteration fails.
The best solution for these problems is to have a critical look at the model and change
the order of calculations in a model. Possible solutions are:
Algebraic Loops occur when the order of calculations is arbitrary. When an algebraic
loop occurs in an equation model or in a set of equation models, you may change the
order of calculation by rewriting the equations. The calculation order in bond graph
models can be changed by introducing hand-defined causality.
Introduce ‘parasitic’ energy storage elements (e.g. a small mass, a small capacitor
etc.) to break an algebraic loop. These elements introduce however, large poles in
the state equations, which might increase the simulation time considerably.
Delete elements in the algebraic loop which are not relevant for the model’s
simulation output (e.g. small dampers, very stiff springs etc.). C are should however
be taken, since correct deletions are not always possible and require considerable
modeling skill and intuition.
C ombine dual elements. Sometimes elements of the same type can be combined by
adding the parameter values (e.g. combining a mass m1 and a mass m2 to a mass
m1 + m2). This will in most cases decrease the amount of algebraic loops.
5.3.5
Order of Execution
Equations within 20-sim may be entered in random form. During compilation, 20-sim will
automatically try to rewrite equations into a correct order of execution. I.e. a form
where all output variables are written as function of input variables and output variables
of previous lines. C onsider for example the following equations:
variables
real u,z;
equations
z = sin(u);
u = cos(time);
Here the (input) variable z is given as a function of u. C onsequently u should be
calculated first. This is exactly what 20-sim will try to do while compiling the model into
simulation code. I.e. the equations will be executed as:
u = cos(time);
z = sin(u);
Code Blocks
Equations in a code block are not reordered. A code block is a set of equations inside a
statement. Suppose we have the following equations:
20-sim 4.6 Reference Manual
52
5. Editor
if condition then
code block 1
...
...
else
code block 2
...
...
end;
To prevent incorrect executions of the if-statement, the equations of the code blocks will
not be separated. Inside a code-block, equations can are not rewritten into an new order
of execution. E.g. the following equations:
if time > 10 then
z = sin(u);
a = z^2;
u = cos(time);
end;
Will be not be reordered and therefore not correctly executed! To get correct code,
enter code blocks in a correct order, e.g.:
if time > 10 then
u = cos(time);
z = sin(u);
a = z^2;
end;
Prevent Order Changes
To make all equations a code block you can use the code section. E.g.
parameters
real y = 8;
variables
real x1, x2, x3;
code
x1 = time;
x2 = sin(time);
x3 = y*x1;
Integration Steps
Some integration algorithms do more calculations before generating the next output
value. These calculations are called minor steps, the output generation is called a major
step. During a minor step, all model equations are executed. In most cases you will not
notice this because only the results of the major step are shown in the simulator. There
are however, exceptions. The next topic will discuss this in more detail.
20-sim 4.6 Reference Manual
53
5. Editor
5.3.6
Integration Steps
Some integration methods do more calculations before generating the next output value.
These calculations are called minor steps, the output generation is called a major
step.
integration method
minor steps
0
Euler
variable
Backward Euler
Adams-Bashford 2
0
Runge Kutta 2
1
Runge-Kutta 4
3
Runge Kutta Dormand Prince 8
variable
Runge-Kutta-Fehlberg
variable
Vode Adams
variable
Backward Differentiation Formula (BDF)
variable
Modified
Backward
Differentiation
Formula
variable
(MBDF)
Execution of Equations
During a minor step, all model equations are executed. In most cases you will not notice
this because only the results of the major step are shown in the simulator. There is one
exception. If you use equations like
variables
real y;
initialequations
y = 0;
equations
y = y + 1;
you will find that the value of y depends on the integration method that is used. The
reason is obvious once your realize that the equations are executed during minor steps.
If you use a Runge Kutta 2 integration method, there is one minor step during which y is
increased and one major step during which y is increased again!
20-sim 4.6 Reference Manual
54
5. Editor
Major
To prevent an equation from being calculated during minor steps, you can us the
predefined variable major. This variable will return the boolean false when calculations
are performed for a minor step and will return true when calculations are performed
during a major step. The major variable is used for example in the library model
Amplitude Sensor:
parameters
real initial = 0.0;
variables
real prev, peak;
initialequations
peak = initial;
prev = 0;
output = initial;
code
if major then
peak = max([abs(input), peak]);
if (input > 0 and prev < 0) or (input < 0 and prev > 0) then
output = peak;
peak = 0;
end;
prev = input;
end;
Note that the initial values are set in the initialequations section, because we do no want
the variables to be set to zero at every integration step. Instead of an equations section,
a code section is used to prevent 20-sim from rewriting the equations in a different
order.
5.3.7
Show Equations
During processing a complete set of equations is generated of each model. To inspect
these equations or copy them for use in other programs, you have to:
1.
From the Model menu select the Check Complete Model command.
2.
From the Model menu select the Show Equations command.
Now a window is popped up showing all the model equations.
20-sim 4.6 Reference Manual
55
5. Editor
The model equations after compiling.
5.4
5.4.1
Icon Editor
Icon Editor
The Icon Editor is a vector oriented drawing editor that can be used to create custom
made icons for any 20-sim model. You can also use the Icon Editor to change the
appearance of existing models.
The 20-sim Icon Editor can be used to create custom made model icons.
20-sim 4.6 Reference Manual
56
5. Editor
Open
1.
In the Editor select the model that you want to give a new appearance.
2.
From the Tools menu select Icon Editor,
3.
or from the right mouse menu select Edit Icon,
4.
or at the bottom left of the Editor click the Icon tab and in the Icon tab double
click.
Use
1.
Use the taskbar buttons or the menu commands to insert objects and edit these
objects.
2.
If you are satisfied with the icon, insert the terminals.
3.
From the Icon Editor menu, select File and Update.
4.
Close the Icon Editor.
5.4.2
Terminals
Most submodels will contain ports (i.e an input signal, an output signal or a power port).
If you are creating submodel icons, you want to indicate the connection points of these
ports. These connection points are called terminals. In the Icon Editor you can define the
position of the terminals.
1.
In the taskbar click the Terminal button
.
2.
C lick with the mouse pointer on the position where you want to insert a terminal.
If you have multiple inputs, outputs or ports, a menu will open to ask you which input,
output or port should be selected.
20-sim 4.6 Reference Manual
57
5. Editor
The inputs, outputs and ports are indicate by small rectangles.
The terminals are visible in the drawing as small rectangles.
3.
You can select a terminal and from the right mouse menu click Properties.
This will open the Terminal Properties showing the name of the input, output or port and
the option to fixate the position. With a fixed position, the connections will start or end
exactly at the position of the terminal. Without a fixed position, the connections will point
to the center of the icon and start or end at the border of the icon.
You can give a terminal a fixed position.
5.5
5.5.1
Global Relations Editor
Introduction
If you want to share parameter values or variable values between submodels, you can
use signals from one submodel to the others. This is not always desired and it will
increase the effort that you have to make in connecting submodels.
20-sim 4.6 Reference Manual
58
5. Editor
Using globals is an alternative for sharing values. By defining a parameter or variable
global, we can instruct 20-sim that a parameter or variable value is shared between
submodels.
Using Globals
If you want to share parameters or variables between submodels, you have to:
1.
Add the keyword global to definition of the parameter or variable.
2.
Define the scope of the globals, i.e. which models share the same parameters and
variables?
5.5.2
Global Parameters and Variables
Global parameters and variables are defined using the keyword global. In equation
models, this keyword is added after the definition of the data type in the Equation Editor:
parameters
real global
real global
variables
real global
real global
..
..
par1 = 100 {Hz};
par2 ;
var1;
var2;
Parameters can only be assigned a value once. The same goes for variables. Only one
submodel must defined their value using an equation. If parameters or variables are
assigned more than once, 20-sim will generate an error.
Example
The best way to describe the use of global parameters and variables is by an example
model. You can find this model in the 20-sim demonstration library (Demo\Tips And
Tricks\Global Parameters and Variables.emx). The model exists of three submodels. In
the first submodel two global parameters (f and A) are assigned and one variable
(sinewave). The variable is assigned a value in the equations section and connected with
the output (out1).
submodel1
parameters
real global f = 100 {Hz};
real global A = 1 {none};
variables
real global sinewave;
equations
sinewave = A*sin(f*2*pi*time);
out1 = sinewave;
In the second submodel, the two global parameters are use to connect them with two
outputs (out1 and out2).
20-sim 4.6 Reference Manual
59
5. Editor
submodel 2
parameters
real global f {Hz};
real global A {none};
variables
real global sinewave;
equations
out1 = f;
out2 = A;
In the third submodel, the global variable is connected with an output (out1).
submodel 3
variables
real global sinewave;
equations
out1 = sinewave;
To prevent conflicts global parameters may be assigned a default value only once. The
same goes for global variables: they may be assigned a value in the equation section
only once.
5.5.3
Scope
Global parameters and variables are defined using the keyword global. In equation
models, this keyword is added after the definition of the data type in the Equation Editor.
In 20-sim we can define which submodels share the same parameter or variable. This is
called the scope of this parameter or variable.
Part of the Model
You can set the scope by using the Global Relations Editor. In this editor you can enter
parameters or variables. All global parameters or variables that are defined in
submodels lower in the hierarchy, share the same value.
20-sim 4.6 Reference Manual
60
5. Editor
Setting the scope of global parameters with the Global Relations Editor.
The image above shows an example. In the model hierarchy we see the submodel
MassSpringDamper2 selected. The Globals Relations Editor, shows three parameters: f,
m and b. If these parameters exists in the submodels lower in the hierarchy (Mass,
SpringDamper, Damper, Spring), and use the keyword global, they share the same
value. Submodels higher in the hierarchy, can never share these parameter values.
Whole Model
If no parameter or variable is defined using the Global Relations Editor, the scope is the
whole model. I.e. global parameters and variables are shared across the whole model.
5.5.4
Global Relations Editor
The Global Relations Editor is used to restrict the scope of global parameters and
variables. You can find the Global Relations Editor at the lower left of the Editor by
selecting the Globals tab.
1.
In the Editor, go to the Model Hierarchy at the left and select the submodel,
you want to add global parameters or variables for.
2.
Select the Globals tab at the lower left of the Editor.
20-sim 4.6 Reference Manual
61
5. Editor
Select the Globals tab, put your mouse pointer on top and click Edit Global Relations.
3.
Put your mouse pointer in the middle of the tab. From the right mouse menu
select Edit Global Relations.
This will open the Global Relations Editor. You can use this editor to enter parameters,
variables and equations.
Use the Global Relations Editor to enter parameters, variables and
equations.
You can enter parameters, variables and equations here just like in the Equations Editor.
The parameters and variables will only be useful if they are used in submodels lower in
the hierarchy as globals.
Example
The best way to describe the use of the Global Relations Editor is by an example model.
You can find this model in the 20-sim demonstration library (Demo\Tips And Tricks
\Global Parameters and Variables for submodels.emx). This model shows two massspring-dampers with shared parameters and variables.
1.
In the Editor, go to the Model Hierarchy at the left and select the submodel
MassSpringDamper1.
2.
Select the Globals tab at the lower left of the Editor.
20-sim 4.6 Reference Manual
62
5. Editor
3.
Put your mouse pointer in the middle of the tab. From the right mouse menu
select Edit Global Relations.
Now you will see the Global Relations Editor, as shown in the previous figure. Three
parameters are defined: f, m and b. The parameter m is use in the submodel Mass lower
in the hierarchy. The variable k is used in the submodel Spring lower in the hierarchy.
The parameter d is use in the submodel Damper lower in the hierarchy.
4.
Now open the Parameters Editor.
Parameters that are shared can be set at the top model.
You will see that it contains the parameters f, m and b at the level of the model
MassSpringDamper1. This allows us to duplicate this model and use a second massspring-damper model with different parameters.
20-sim 4.6 Reference Manual
63
5. Editor
5.6
5.6.1
Interface Editor
Interface Editor
The Interface Editor can be used to define the interface, i.e. the input signals, output
signals and power ports of a submodel.
The 20-sim Interface Editor can be used to define the model interface.
Open
1.
In the Editor select the model of which you want to change the interface.
2.
From the Tools menu select Interface Editor,
3.
or from the right mouse menu select Edit Interface,
4.
or at the bottom right of the Editor click the Interface tab and in the Interface
tab double click.
Use
1. Use the Edit menu to add ports to the list.
20-sim 4.6 Reference Manual
64
5. Editor
2. Select a port from the list and change its properties (make it an input signal,
output signals and power ports etc.)
3. From the Interface Editor menu, select File and Update .
4. Close the Interface Editor.
5.6.2
Port Properties
From the Edit menu select Add Port. A new port will now be added to the list. If you
select the port in the list you can change its properties
Name: Enter the name of the port.
Type: Select the port-type: Signal, Iconic Diagram or Bond Graph.
Signal
Size: If the signal is multi-dimensional, enter the number of rows and columns.
Orientation: C hoose input signal or output signal.
Quantity: If the signal represents a physical quantity, you can choose the quantity
from a predefined list.
Unit: If the signal represents a physical quantity, you can choose the corresponding
unit from a predefined list.
Type: The default type of a signal is a real number. C hoose out of real, integer or
boolean.
Iconic Diagram
Size: If the port is multi-dimensional, enter the number of rows and columns.
Orientation: C hoose an input or output orientation for the port.
Domain: C hoose the physical domain of the port. The most general domain is power.
Depending on your choice you will see the two variables (Across and Through)
associated with the port.
Causality: Select the causality of the port.
Separate High/Low Terminals: You may choose this option for models with a velocity
difference, voltage difference etc.
Any Number of Terminals: You may choose this option for models with a variable
number of connections.
Bond Graph Port
Size: If the port is multi-dimensional, enter the number of rows and columns.
Orientation: C hoose an input or output orientation for the port.
Domain: C hoose the physical domain of the port. The most general domain is power.
Depending on your choice you will see the two variables (Effort and Flow) associated
with the port.
Causality: Select the causality of the port.
20-sim 4.6 Reference Manual
65
5. Editor
5.6.3
Orientation
In the Interface Editor you can set the orientation of a ports. In the Editor this
orientation can be made visible by setting the Orientation Info command from the
View menu. Depending on the type of port the orientation has a different meaning.
Signals: For signals the orientation indicates the direction of the associated variable :
input or output.
Bond Graphs: The orientation of a bond graph port is the direction of the half arrow
at the end of a bond. It indicates the direction of the positive power flow.
Iconic Diagrams: The orientation of an iconic diagram port also indicates the direction
of the positive power flow.
If you select the top of the list in the Interface Editor, you can choose the Port Relations
tab to set multiple port relations:
Equal / Not equal: The equal and not equal restrictions can be used to specify that a
port p1 must have the same or opposite orientation as port p2.
5.6.4
Causality
A powerport is always characterized by two variables. One of these variables should be
an input and one of these variables should be an output. The choice of input and output
variable is called causality. In the Interface Editor you can set the causality of the ports
of a submodel. The following causal forms can be chosen:
1.
Fixed out: One of the two variables is always an output variable.
2.
Preferred out: One of the two variables is preferably an output variable.
3.
Likes: Same as preferred out but with lower priority: one of the two variables is
preferably an output variable
4.
Indifferent: A powerport with an indifferent causality restriction can have both
variables as output.
During processing, the assignment of the causal forms goes with the rank in the list. First
all elements with a fixed out assignment are set, then the elements with a preferred out
assignment, then with a likes assignment and finally with an indifferent assignment.
If you select the top of the list in the Interface Editor, you can choose the Port Relations
tab to set multiple port restrictions:
Equal / Not equal: The equal and not equal restrictions can be used to specify that a
powerport p1 must have the same or opposite causality as powerport p2. This is
denoted as p1 equal p2 and p1 notequal p2 respectively.
One_out: The restriction One_out should only be used for bond graph ports. It is
used to indicate that at a one or zero junction, only one bond may have an effort out
causality.
One_in: The constraint restriction One_in should only be used for bond graph ports.
It is used to indicate that at a one or zero junction, only one bond may have an effort
in causality.
20-sim 4.6 Reference Manual
66
5. Editor
In the Editor this causality can be made visible by setting the Causality Info command
from the View menu.
5.6.5
Ports with more than one Terminal
By default, an iconic diagram port
component and its environment in
Such a port is represented by one
special cases where it is desirable
one terminal.
is a port
terms of
terminal
to define
where power can be exchanged between a
an across variable and a through variable.
(connection point). However, there are two
an iconic diagram port that has more than
Separate High / Low Terminals
C onsider, as an example, an mechanical spring. The power that flows into such a
component is uniquely determined by the velocity difference between the two terminals
of the component and the common force that acts upon both ends. Because of this one
could say that there is one port, whose power is determined by one across value (the
velocity difference) and one through value (the common force), but is represented by
two terminals. To support this, 20-sim allows you to define a special type of iconic
diagram port by indicating that is has Separate High / Low Terminals. The two terminals
of the connection are named high and low. If the port is named p, the formal equations
are:
fixed in orientation:
p.F = p_high.F = p_low.F
p.v = p_high.v - p_low.v
fixed out orientation:
p.F = p_high.F = p_low.F
p.v = - p_high.v + p_low.v
In 20-sim these equations are automatically derived.
Any Number of Terminals
C onsider, as an example, a mass. A characteristic of this component is that you can
connect many springs and dampers to it. Implicitly, one expects that the net force (i.e.,
the summation of the forces applied by the connected components) will be applied to the
mass, and that it will have a single velocity. To support this, 20-sim allows you to define
a special type of iconic diagram port by indicating the kind to be Any Number of
Terminals. The terminals of the connection are named 1, 2, 3 etc.. If the port is named
p, the formal equations are:
fixed in orientation:
p.v = p1.v = p2.v = p3.v = .....
p.F = sign1*p1.F + sign1*p2.F + sign1*p3.F + ....
fixed out orientation:
p.v = p1.v = p2.v = p3.v = .....
p.F = -sign1*p1.F - sign1*p2.F - sign1*p3.F - ....
with
20-sim 4.6 Reference Manual
67
5. Editor
sign = 1 when p1 has a fixed in orientation etc.
sign = -1 when p2 has a fixed out orientation etc.
In 20-sim these equations are automatically derived.
5.7
5.7.1
Domains, Quantities and Units
Domains, Quantities and Units Editor
At various modeling levels you can use information on physical domains, quantities and
units. This information is stored in the file QuantitiesAndUnits.ini in the 20-sim bin
directory. To edit this information you can use the Domains, Quantities and Units Editor.
When opened, the editor automatically reads the file QuantitiesAndUnits.ini. When closed
the editor asks you where to store the file. Note that any changes made become
effective after 20-sim has been restarted.
The Domains, Quantities and Units Editor.
You can start the Domains, Quantities and Units Editor by selecting the Units Editor
command from the Tools menu. In the editor a tree-like structure is shown indicating
the available Domains, Quantities and Units.
1. You can select every items in the tree for editing.
2. Use the Add or Delete button to add new items or delete existing item.
3. Use the Find button
to find items in the tree.
20-sim 4.6 Reference Manual
68
5. Editor
5.7.2
Domains
In the Interface Editor every powertport (Iconic Diagram or Bond Graph) can be
assigned a physical domain. 20-sim will use this information to prevent that ports of
different physical domains may be connected. More popular: in this way you can never
connect a translation model to an electric component.
Use the Interface Editor to assign a physical domain to a port.
In the Interface Editor you can select the physical domain that you want to assign to a
port. The editor will show the corresponding port variables and the notation that should
be used in the model equations.
The tables below show the available domains and their respective port variables.
power domain
across
through
Power
across
through
Mechanical
velocity
force
Translation
velocity
force
Rotation
angular velocity
torque
Pneumatic
pressure
air flow
20-sim 4.6 Reference Manual
69
5. Editor
Thermal
temperature
entropy flow
Electric
voltage
current
Hydraulic
pressure
volume flow
Magnetic
magnetomotoric force
magnetic flux
For the power domains the variables multiply to power. There are also some domains
defined where the variables do not multiply to power. These are called pseudo
domains. The following pseudo domains are defined.
pseudo domain
across
through
Pseudo Pneumatic
pressure
mass flow
PseudoThermal
temperature
heat flow
PseudoThermalH
temperature
enthalpy flow
PseudoHydraulic
pressure
mass flow
You can enter new (pseudo) domains in the Domains, Quantities and Units Editor. If the
port is defined as a bond graph port, effort and flow are used to indicate the domain
variables. The corresponding tables are shown below.
power domain
effort
flow
Power
effort
flow
Mechanical
force
velocity
Translation
force
velocity
Rotation
torque
am
Pneumatic
pressure
angular velocity
Thermal
temperature
air flow
Electric
voltage
entropy flow
Hydraulic
pressure
current
Magnetic
magnetomotoric force
volume flow
magnetic flux
pseudo domain
effort
flow
Pseudo Pneumatic
pressure
mass flow
PseudoThermal
temperature
heat flow
PseudoThermalH
temperature
enthalpy flow
PseudoHydraulic
pressure
mass flow
20-sim 4.6 Reference Manual
70
5. Editor
5.7.3
Quantities and Units
In 20-sim, to every constant, parameter and variable a quantity may be assigned. Well
known quantities are for example position, velocity, time and energy. 20-sim will use
these quantities to check the validity of (basic) equations. The value of a quantity can be
expressed in a specific unit. The quantity time can for example be expressed in the unit
second or in the unit minute:
quantity
unit
multiplication to SI unit
Time
second (SI unit)
1
minute
60
hour
3600
day
86400
year
31556926
meter (SI unit)
1
foot
0.3048
inch
0.0254
yard
0.9144
Position
In 20-sim a quantity can be expressed in every desired unit. To prevent conversion
problems, internal calculations are always performed in standard SI-units. Therefore
non-SI units are stored with a multiplication factor. When a variable has a unit, the
unit can also have common engineering prefixes. For example, a parameter m {kg}
with a value of 0.1 can be selected in the Parameters / Initial Values Editor. If you click
on the unit, you can select other units to enter the mass.
20-sim 4.6 Reference Manual
71
5. Editor
You can use the units in the Parameters / Initial Values Editor to select a desired unit.
You can enter new quantities and units in the Domains, Quantities and Units Editor.
5.7.4
Editing Domains
You can edit existing domains or add new domains in the Domains, Quantities and Units
Editor. In the Domains section you can add new domains or edit existing domains. Each
domain has several edit fields:
Domain name: If you click on a selected domain in the tree, you can edit the name.
Description: Enter a description of the domain.
Quantities: You can enter quantities of these variables in the quantities section.
Mechanical Domain: Select this button if your domain is part of the mechanical
domain.
Pseudo Domain: Select this button if your domain is a pseudo domain.
Color: Double-click the color box to change the color of a domain.
In some domains the integrated effort/flow variables and differentiated effort/flow
variables are of a specific quantity. You can enter these quantities in the according edit
fields. For some domains these values have no meaning and you can leave the edit
fields blank.
20-sim 4.6 Reference Manual
72
5. Editor
5.7.5
Editing Quantities
You can edit existing quantities or add new quantities in the Domains, Quantities and
Units Editor. In the Quantities section you can add new quantities or edit existing
quantities. Each quantity has several edit fields:
Quantity name: If you click on a selected quantity in the tree, you can edit the name.
Description: Enter a description of the quantity.
Variable name: This name is used for display purposes. For example if one of the
variables of a port p has the quantity length it will be denoted as p.x.
SI Symbol: Enter the official SI-symbol here. Enter combinations as nominator/
denominator (e.g. Electric Resistance: kg.m2/A2.s3)
Units: Every quantity can be expressed in several unique units (i.e. a unit can be
assigned to one quantity only). You can enter new units here or edit existing units
that belong to the selected quantity.
Unit Symbol: For display purposes every unit has a specific symbol. It is shown here
in a read-only field.
A quantity can have an alias name. Enter this alias as a subentry of the main quantity.
This alias name refers to the main quantity and therefore to the same associated units.
5.7.6
Editing Units
You can edit existing units or add new units in the Domains, Quantities and Units Editor.
In the Units section you can add new units or edit existing units. Each unit has several
edit fields:
Unit name: If you click on a selected unit in the tree, you can edit the name.
Description: Enter a description of the unit.
Quantity: C hoose the quantity to which the unit should be associated. A unit can be
associated to one quantity only.
Symbol: For display purposes every unit has a specific symbol.
Multiplications: A quantity can be expressed in several units. To prevent conversion
problems, internal calculations are always performed in standard SI-units. Therefore
non-SI units are stored with a multiplication factor. You can enter the multiplication
factor here.
Allow Symbol Prefixes: Some units can be expressed with symbol prefixes. Select
the check box to allow the use of prefixes. 20-sim supports the following
prefixes:
prefix
symbol
value
femto
f
10-15
pico
p
10-12
nano
n
10-9
micro
u
10-6
20-sim 4.6 Reference Manual
73
5. Editor
milli
m
10-3
centi
c
10-2
deci
d
10-1
hecto
h
102
kilo
k
103
mega
M
106
giga
G
109
tera
T
1012
Example
parameters
real mylength = 1 {cm}; // equal to: 0.01 {m}
20-sim 4.6 Reference Manual
74
6. Simulator
6
Simulator
6.1
Introduction
6.1.1
Simulator
20-sim consists of two main windows and many tools. The first window is the Editor and
the second is the Simulator. The Editor is used to enter and edit models. The Simulator is
used to simulate and analyze the models. The Simulator is opened in the Editor by
clicking the Start Simulator button from the Model menu.
The Simulator is used to carry out simulations, show the results and analyze them.
The Simulator consists of three parts:
Simulator Tree: This is the tree at the left. Here plots and plot windows can be added.
Simulation Plot: This is the graph in the middle. Here the simulation results are
shown.
Output tab: The Output tab shows warnings and messages.
Simulation
A modeling and simulation session in 20-sim can be visualized by the diagram shown
below.
20-sim 4.6 Reference Manual
75
6. Simulator
Modeling and Simulation in 20-sim.
Compiling/Debugging
After the model has been successfully entered, it must be checked and compiled to
generate simulation code. This is done in 20-sim automatically when you open the
Simulator or when you check a model. In some cases the model contains errors which
have to be solved by adapting the model. Errors in 20-sim are presented in the Process
tab at the bottom of the Editor.
Settings
After a successful compilation of a model that is created in the Editor you can open the
Simulator. In the Simulator you have to enter specific settings:
Parameters / Initial Values.
Run Properties.
Plot Properties.
Running
After the settings have been entered you can run the simulation.
Plotting
Simulation results can be shown in 20-sim as:
Numerical Plots:
Time Domain (default)
Frequency Domain (FFT Analysis & Linearization)
20-sim 4.6 Reference Manual
76
6. Simulator
Animation in a Graphical Model
3D Animation
Debugging
If you experience problems during simulation you have to resolve them in a debugging
session.
Analysis
After a successful simulation you can analyze your model using various tools:
Parameter Sweeps
C urve Fitting
Optimization
Sensitivity Analysis
Monte C arlo Analysis
Variation Analysis
FFT Analysis
Linearization
Message Log
The bottom of the Simulator shows a tab named Output. This tab contains the Message
Log which shows all the messages, warnings and errors, that are generated during a
simulation.
20-sim 4.6 Reference Manual
77
6. Simulator
6.2
6.2.1
Running a Simulation
Parameters and Initial Values
The Parameters/Initial Values Editor is used to edit the constants, parameters and initial
values of a model. Parameters and initial values can be changed during simulation,
constants cannot be changed. To open the Parameters/Initial Values Editor, you have to:
1. From the Properties menu select the Parameters command.
The Parameters/Initial Values Editor.
The parameter items (Name, Value, Quantity, Unit, Description, Kind, Arithmetic Type,
Value) of the parameters and initial values are listed in right part of the window. The list
of parameters and initial values that is displayed depends on the selected submodel in
the left part of this window.
Items
Model Hierarchy : The left part displays the complete model hierarchy. At each
level of the hierarchy, submodels can be selected. The right part of the
window then shows the parameters and initial values of that submodel. To
see all parameters and initial values, select the top level of the hierarchy, i.e.
the main model listed on top.
Parameters and Initial Values: The order of the parameters or initial values in
the list depends on the order in which the submodels were originally entered
in the Editor. Click on the name box to make the order to alphabetical. Drag
the name box to change the width of the parameters list.
20-sim 4.6 Reference Manual
78
6. Simulator
Value : You can change the default value of a parameter or initial value in the
value list. Select the parameter or initial value (mouse) and enter the desired
value. Use the Enter key to quickly run through a list of parameters.
Unit: If available, select the desired Unit from the drop down list.
From Matlab / To Matlab: Use the buttons to import or exports parameter
values from or to Matlab.
Import: Use this button to import the parameter values from another model.
Note
All equations in 20-sim are calculated using standard SI-units. You can however
enter parameters, using whatever Unit you like. In the Parameters/Initial Values
Editor, you can change the unit using the little drop down list next to the Value
box.
The description of a parameter can be specified in the parameters part of the
equation description of a model.
To see a global parameter, select the top level of the hierarchy, i.e. the main model
listed on top.
Hidden parameters are not visible in the Variables C hooser.
6.2.2
Run Properties
The Run Properties Editor can be used to choose the integration method used for
simulation. An integration method is the algorithm that calculates the model equations
during each simulation and generates the output values for the simulation plots. The
default integration method is the Backward Differentiation Formula (BDF). To open the
Run Properties Editor, you have to:
1. From the Properties menu select the Run command.
20-sim 4.6 Reference Manual
79
6. Simulator
The Run Properties Editor.
Initially, the fields in the Run Properties Editor contain default values if no experiment
was loaded. Two or more tabs can be selected:
Simulator: This tab shows the general simulation settings.
Discrete Systems: This tab is only visible when discrete systems are part of your
model. It contains the settings for the sample frequency.
Algebraic Relations Solver: This tab is only visible when your model contains
algebraic loops that could not be solved during processing.
Integration Method: The last tab contains the specific settings for the selected
integration method.
20-sim 4.6 Reference Manual
80
6. Simulator
6.2.3
Plot Properties
The Plot Properties Editor can be used to enter the plot specifications. To open the Plot
Properties Editor, you have to:
1. From the Properties menu select the Plot command.
The Plot Properties Editor.
The editor shows three tabs which can be used to set the properties of the plot and the x
and y variables.
Plot Properties Tab
The Plot Properties Tab shows the general settings that accompany a plot. A preview is
shown in the lower part of the tab.
Plot Title : Select this option to add a title to the plot. In the text box you can
type the desired title. Use the radio buttons to display the title to the left, in
the middle or to the right of the plot.
Colors: Click the Background, Plot and Grid buttons to select the background,
plot and grid colors.
Grid: Select this option to show the grid.
Background
Windows Default: Select this option to get the default Windows background.
3D Look : Select this option to get a plot with 3D Look (sunken edges).
Axes:
20-sim 4.6 Reference Manual
81
6. Simulator
Select the options Logarithmic X and Logarithmic Y to show logarithmic plots.
Show X-Values: Use this option to show or hide the X-axis values.
Show Legend: Use this option to show to show a legend.
Fonts: Click the Title , Values and Labels buttons to select the font options for
the title, values and labels.
X-Axis Tab
The X-Axis Tab can be used to specify the variable plotted along the X-axis.
The X-Axis tab of the Plot Properties Editor.
Variable Name : Either time or one of the dynamic variables of the model can
be chosen as the X-axis variable. Click the button on the right (Choose) to
open the Variable Chooser and select the desired variable.
Label: Enter the label that should be printed below the X-axis.
Show Unit: Select this option to display the unit of the chosen variable.
Scaling
Manual: Fix the scale of the X-axis by selecting a minimum and maximum
value in the From and To boxes.
Post: During the simulation run, the scale for the variable along the axis is
fixed. When the run is finished or has been interrupted by the user, the
minimal and maximal scale values are automatically updated and the plot
is redrawn to make sure all calculated points are displayed.
20-sim 4.6 Reference Manual
82
6. Simulator
Automatic: When
a variable reaches the end of the scale, during
simulation, the the minimal and maximal scale values are automatically
updated and the plot is redrawn to make sure all calculated points are
displayed.
Clip to Bounds: When a variable reaches the end of the scale, during
simulation, the the minimal and maximal scale values are automatically
updated and the plot is redrawn to make sure all calculated points are
displayed. When the run is finished or has been interrupted by the user,
the minimal and maximal scale values are automatically updated to show
the plot at maximum scope.
Show Values: Use this option to show or hide the X-axis values.
Y-Axis Tab
The Y-Axis Tab is used to specify the curves that should be shown in the plot. For each
selected curve, a tab is shown, displaying the settings of that curve.
The Y-Axis tab of the Plot Properties Editor.
Curves
Add Curve : Add a new tab to specify a new curve to be displayed in the plot.
Delete Curve : Delete the selected tab. As a result, the curve specified in the
tab will not be displayed in the plot, and the settings are lost.
Variable Name : Use this box to connect a variable to a curve. One of the
dynamic variables of the model can be selected. Click the button on the right
(Choose) to open the Variable Chooser and select the desired variable.
20-sim 4.6 Reference Manual
83
6. Simulator
Label: Enter the name of the curve. This label is also printed next to the the Y-
axis.
Show Unit: Select this option to display the unit of the chosen variable.
Line Properties
Line Style : Select the desired line style of the curve.
Thickness: Select the desired line thickness of the curve.
Color: Select the desired line color of the curve.
Order: In the plot a line is drawn from plot point to plot point. You can
choose the line to be of two orders of interpolation:
Zero: the line consists only of horizontal and vertical parts.
First: the line consists of straight parts.
Tick Style Properties
Tick Style : Each calculated point of a curve, can be displayed by a special
marker. Select here the desired marker.
Min. Distance (pixels): To prevent markers from being drawn on top of each
other, you can set the minimum distance between markers. Points that
are to close to a previous marker are not drawn with a marker.
Color: Select the marker.
Scaling: Scaling can be selected for each curve individually or combined for all
curves.
Shared Y Axes: Select this option to use one Y-axis scale for all curves.
Strip Charted: Select this option to display each curve in a separate plot.
Manual: Fix the scale of the variable by selecting a minimum and maximum
value in the From and To boxes.
Post: During the simulation run, the scale for the variable along the axis is
fixed. When the run is finished or has been interrupted by the user, the
minimal and maximal scale values are automatically updated and the plot
is redrawn to make sure all calculated points are displayed.
Automatic: When
a variable reaches the end of the scale, during
simulation, the the minimal and maximal scale values are automatically
updated and the plot is redrawn to make sure all calculated points are
displayed.
Clip to Bounds: When a variable reaches the end of the scale, during
simulation, the the minimal and maximal scale values are automatically
updated and the plot is redrawn to make sure all calculated points are
displayed. When the run is finished or has been interrupted by the user,
the minimal and maximal scale values are automatically updated to show
the plot at maximum scope.
Show Values: Select or de-select this option to show or hide the name and
scale of a curve.
20-sim 4.6 Reference Manual
84
6. Simulator
Separate X-Axis: If you want another x-axis than specified in the X-axis tab,
click the Choose button to select the desired variable.
6.2.4
Running a Simulation
After specification of the Parameters/Initial Values, the Run Properties and Plot
Properties you can start a simulation run by choosing the appropriate command from
the Simulation menu.
Run: Select the Run command to start or continue a simulation run. Once a
run is started, the Stop command becomes active. The run can be interrupted
by selecting this command.
Stop: Use the Stop command to interrupt a simulation. Once a simulation has
stopped it can be continued by selecting the Start Simulation command.
Clear
All Runs: Select the Clear All Runs command to clear all runs that were
performed, from the graphical screen and from the computer memory.
Last Run: Select the Clear Last Run command to clear the run that was
performed last, from the graphical screen and from memory.
Previous Runs: Select the Clear Previous Runs command to clear all runs,
but the last, from the graphical screen and from memory.
One Step: Use the One Step command to calculate one new simulation point.
Using this command repeatedly, allows you to run a simulation step by step.
Brute Force : Using the Brute Force command, curves are displayed after
complete calculation of a simulation run. This saves time (re)drawing curves
during calculations and therefore considerably speeds up simulation.
Multiple Run: Select the Multiple Run command to start multiple runs needed
for the Time Domain Toolbox . Runs can be interrupted by selecting the Stop
command.
Replay
3D Animation: Any 3D Animation that was performed during a simulation
run, can be quickly replayed using this option.
Real Time 3D Animation: Any 3D animation that was performed during a
simulation run, can be replayed in real time (i.e. frames are skipped if
necessary) using this option.
Read Datafile : Use the Read Data File command to read previously stored
simulation runs from file.
Copy States: With the C opy States command the current independent state
variables can be imported as new initial values. C urrent state variables are the state
variables at the end of a simulation run or at the point where a simulation run was
interrupted.
20-sim 4.6 Reference Manual
85
6. Simulator
6.2.5
Numerical Values
In every simulation plot you can inspect the numerical values by selecting the Numerical
Values command of the View menu. The Numerical Values window, can also be popped
up by double clicking the left mouse button, while pointing the mouse at a curve in the
plot.
The Numerical Values window will pop up and display the numerical values of all plotted
variables as a function of time. The last variable shown is always the X-axis variable
(usually time).
The Numerical Values window.
Run Number: The run number indicates the run of which the numerical values
are shown. The highest number indicates the last run simulated. Lower
numbers are used for previous runs. To select another run number, type in
the number of interest or point in the plot at the curve of interest. In the
simulation plot, previous runs are shown with fading colors.
20-sim 4.6 Reference Manual
86
6. Simulator
List: The list shows all variables that are shown in the plot and their
corresponding X-values and Y-values. The variable that is currently selected
is pointed out by an arrow in the plot.
Scroll-bar: Use the scroll-bar to change the selected x-axis variable value
(usually time).
Find: With the Find button, the global maximum etc. of the selected variable
can be found. The following functions can be selected:
Global Maximum
Global Minimum
Next Local Maximum
Next Local Minimum
Previous Local Maximum
Previous Local Minimum
Mark : Click the Mark button to store he set of numerical values. If you drag the
scroll-bar to find a new set of values, the relative changes will be displayed as well as
a first order derivative.
6.2.6
Variable Chooser
The Variable C hooser can be used to select and inspect any dynamic variable of the
loaded model. The names, kinds, types, values, quantities, units and descriptions of the
variables of the loaded model are listed in right part of the window. The list of dynamic
variables displayed, depends on the selected (sub)model in the left part of this window.
The left part displays the complete model hierarchy.
The Variable Chooser shows all variables of a model.
20-sim 4.6 Reference Manual
87
6. Simulator
Items
Model Hierarchy : The model hierarchy shows several keys:
Model: At each level of the hierarchy, submodels can be selected and
inspected. The right part of the window then shows the variables that are
part of that submodel. To see all variables including time, select the top
level of the hierarchy, i.e. the main model listed on top. Click on one of the
variable items (Name, Value, Quantity, Unit, Description, Kind, Arithmetic
Type, Value) to order the variables alphabetically.
Input Probes/Output Probes: In the Frequency Response dialog pairs of input
variables and output variables can be selected for linearization. If input variables
have been selected they are shown under the input probes key. If output
variables have been selected they are shown under the output probes key.
Favorites: variables that are used a lot can be added to the favorites key
for easy use.
Variables: Select the desired variable from the list (use your mouse pointer),
select the desired Unit from the drop down list and click OK to close the
window.
Minimum and Maximum values: If you run a simulation in Debug Mode
, the
minimum and maximum value of every variable is show n.
Unit Selection: If a quantity was assigned to the selected variable with multiple units
(e.g. position -> m , mm , inch , etc.) you can switch units by the unit selection
at the bottom of the variable list.
Expand Vectors/Matrices: Select complete vectors and matrices or only their
elements.
To Matlab: Use the
button to export a variable value to Matlab. You
will be asked to enter a Matlab variable. Data will be exchanged between this
Matlab variable and the variable that is selected in 20-sim.
Show Variables: Select the specific kind of variables (Variables, States/Rates,
Dependent/Algebraic, Knots) that should be displayed in the Variables list.
Actions
If you select a variable in the list and use the right mouse menu several actions can be
performed:
Add to Favorites: add the selected variable to the favorites list.
Add to Input Probes: Add the variable to the list of inputs for linearization. This list is
used in the Frequency Response dialog.
Add to Output Probes: Add the variable to the list of outputs for linearization. This list
is used in the Frequency Response dialog.
Copy: copy the variable value to clipboard.
Copy with Unit: copy the variable value and corresponding value to clipboard.
Copy Specified: Specify the items that should be copied and then copy to clipboard.
20-sim 4.6 Reference Manual
88
6. Simulator
Tips
1.
All equations in 20-sim are calculated using standard SI-units. You can however
display the results, using whatever Unit you like. In the Variable Chooser, you can
change the unit using the little drop down list just above the Show Variables section.
2.
To see global variables, select the top level of the hierarchy, i.e. the main model
listed on top.
3.
To quickly find some variables out of the list, add the keyword interesting in the
equation description. In the Variables list, de-select States, Rates, Algebraic Loops,
Dependent States and Dependent Rates. Then only the interesting variables are
shown.
4.
When using large models, opening the Variable C hooser may take some time. Use
the General Properties window to set the maximum number of variables that should
be shown.
5.
To hide variables from the list, add the keyword hidden in the equation description.
Hidden variables are not visible in the Variable Chooser.
20-sim 4.6 Reference Manual
89
6. Simulator
6.2.7
Debugging
20-sim has various tool to help you to pinpoint and resolve problems that may occur
during a simulation.
Switch to Debug Mode: 20-sim is operating in Debug Mode when you see the
. If your Simulator or Editor is in Fast Mode
button to change to Debug Mode .
Debug Mode button
click on the
Recompile your model: In the editor select Check Complete Model from the Model
menu. This will recompile your model in Debug mode and show a maximum of
warnings. If any warning looks suspicious, solve this first.
Breakpoints: Set breakpoints to monitor time or conditions between variables.
Run to the breakpoint: Use the Run command from the Simulation menu to run
the simulation to a breakpoint. As soon as the breakpoint has been reached,
the simulation will halt. The Output tab at the bottom of the Simulator will display
which breakpoint was active.
Simulate Step-by-Step: Use the command One Step from the Simulation menu to
simulate do one simulation step for the complete model.
Inspect the Results: After each step, open the Variable C hooser to inspect the
various variables of the model. You can also switch to the Editor to inspect results
at model level:
Submodels: Select a specific submodel and choose parameters or variables to
inspect the parameters and variables of that submodel.
Equation submodels: Put the mouse pointer on top of an equation and point
to a variable or parameter of interest. A box will appear, showing the
numerical value associated with that variable or parameter.
Use the mouse pointer to inspect numerical values.
Graphical submodels: Put the mouse pointer on top of a signal, bond or
connection. A box will appear, showing the numerical value associated with that
signal, bond or connection.
20-sim 4.6 Reference Manual
90
6. Simulator
Use the mouse pointer to inspect numerical values.
6.2.8
Breakpoints
20-sim allows you define stops in a simulation called breakpoints. You can set
breakpoints using the Breakpoint Editor. This editor can be opened by selecting the
Breakpoints command from the Properties menu in the Simulator.
Setting Breakpoints.
You can run a simulation from breakpoint to breakpoint, using the Continue command
from the Simulation menu.
Breakpoints are useful when problems occur during simulation. By defining an
appropriate breakpoint and using the Run command, you can run a simulation until the
point where the problem occurs. You can continue the simulation using single steps or
just running it again.
20-sim 4.6 Reference Manual
91
6. Simulator
Items
Add/Delete : Use the Add and Delete buttons to add or delete breakpoints.
When you add a breakpoint, an editor will be opened to enter the breakpoint
conditions.
Breakpoints: The Breakpoints list shows the entered breakpoints.
Enter the ... skip before stopping: A breakpoint may occur more than once
before it should stop the simulation run. Enter here the number of times to
skip the breakpoint.
When: A breakpoint may occur more than once during a simulation run. With
this option you can select the breakpoint to be active only once or always.
Active : Use this option to make a breakpoint effective or not.
Edit Condition: When a breakpoint is selected in the breakpoints list, you can
edit it, using the Edit Condition button. This will open an editor which helps
you to enter the breakpoint condition.
Import: Import breakpoints from another model.
Note
Breakpoints are only active when 20-sim is operating in Debug Mode!
6.2.9
New Simulation Plot
You can open additional plots by selecting the New Plot Window command from the View
menu of the simulator.
You can open additional plots in 20-sim.
Every plot will have a menu bar and buttons to allow you to enter the settings for the
plot and running a simulation.
20-sim 4.6 Reference Manual
92
6. Simulator
6.2.10 New 3D Animation Plot
You can open additional 3D Animations by selecting the New 3D Animation Window
command from the View menu of the simulator.
You can open additional plots in 20-sim.
Every 3D Animation will have a menu bar and buttons to allow you to enter the settings
for the plot and running a simulation.
20-sim 4.6 Reference Manual
93
6. Simulator
6.2.11 Resample Curves
Select the Resample Curves command from the View menu to sample a simulation run
with a fixed sample time. This is useful if you want to use your simulation results in other
programs that need data with a fixed time step. An example is given below where a
curve (red dots) is shown that is simulated with a variable step integration method.
Resampling with a sample time of 0.1 s will result in a curve with only the blue dots.
Use the Resample Curves command to get equidistant timing in the plot.
Selection of the Resample Curves command of the View menu pops up the Resample
Curves dialog. You can enter the amount of data that you want to resample and the
sample time or frequency.
20-sim 4.6 Reference Manual
94
6. Simulator
The Resample Curves dialog.
Note
To get simulation data with a fixed time step, using a fixed step integration method is not
enough, because this data may contain additional steps generated by time or state
events. Only the Resample Curves command will guarantee fixed time step
data!
6.2.12 Copy States
To get the same model behavior, compared to the end of the previous run, we have to
copy the states of a model to the initial values.
When you use the Copy States command of the Simulation menu, 20-sim overwrites
the initial values of the functions ddt, int, limint and resint with their current output
states. This can be done at the end of a simulation run or at any point where a
simulation run was interrupted.
Tip
For some models, behavior at some operating point or "steady state" is of interest. Use
the Copy States command to create simulation that directly starts at working level:
1.
Run a simulation from t = 0 [s] until the operating point is reached. Use the
Copy States command to store the states as new initial values. Now save the
experiment using some special name.
2.
Now each time you open this experiment, simulations directly start at
operating point.
20-sim 4.6 Reference Manual
95
6. Simulator
States
C onsider the following first order linear model:
This model can be described by the dynamic equation:
output = int(0) + int( f(input,output) )
with:
int(0) = the initial value of the integral
f(input,output) = input - K*output
In more general terms this equation can also be described as:
state = int(0) + int(rate)
rate = f(input, state)
When we start to simulate this model at t = 0 [s] the value of the integral is zero. The
state is therefore equal to the initial value int(0):
state(0) = int(0)
At the end of a simulation, the integral may be unequal to zero. The state is therefore
equal to:
state(end) = int(0) + int(rate(end)).
In other words, the value of the state is characteristic for the behavior of the model. To
start a new simulation with the same behavior, we have to change the initial value to:
int(0) = state(end)
This is valid for all dynamic models: The states of a model are characteristic for its
behavior. To get the same behavior, compared to the end of a previous run, we have to
copy the states to the initial values.
20-sim 4.6 Reference Manual
96
6. Simulator
6.2.13 Exporting Simulations
There are several methods to export simulation results:
1.
Export Plot to C lipboard or File.
2.
Export Experiment To C lipboard.
3.
Export Data to File.
Export to Clipboard or File
From the File menu, you can choose Export Plot to MetaFile or Export Plot to Clipboard to
export a drawing of the simulation plot.
Export High Resolution Plot to Clipboard or File
Simulation plots can be very dense. To limit the file size, by default not all details are
exported to clipboard or to file. If you need a detailed plot, from the File menu, you can
choose Export High Resolution Plot to Clipboard or Bitmap. Another option is to use the
right mouse menu, when the mouse on top of a plot and select High Resolution Export.
Export Experiment To Clipboard.
From the File menu, you can choose Export Experiment to Clipboard to export all plot
settings. A dialog will be opened asking you to specify the settings that should be copied.
You can select:
Parameters
Initial Values
Plot Specifications
Run Specifications
Multiple Run Specifications
Export Data Specifications
BreakPoints
Export Data to File
From the File menu, you can choose Save Data To File to export the plotted values to a
data file. A file dialog window will pop up asking you to enter a filename. You can choose
from the following file formats:
C omma Separated File (*.csv): This is the default format and can be used for
exporting data to spreadheet programs such as Microsoft Excel or Open Office C alc.
20-sim data file (*.n): This is the standard 20-sim format.
Data Files (*.dat): The standard ANSI format for data files.
Tip
You can use the Export Data To File command to store simulation results of time
consuming simulations. For later use you can use the Import From Data File command to
read the result from file.
20-sim 4.6 Reference Manual
97
6. Simulator
6.2.14 Importing Simulations
There are several methods to import simulation results:
1.
Import experiment.
2.
Import simulation data.
Export Plot Settings
From the File menu, you can choose Import Experiment to import the simulation settings
from another model. The setting contain all the necessary information that you need to
define a simulation:
parameters
run porperties
plot properties
...
Import Data File
From the File menu, you can choose Import Data From File to import a previously saved
simulation plot. A window will pop up allowing you to specify the filename and variables
that should be plotted.
Import data from file.
If the file contains a header describing the variables inside, they will be shown in the
variables dialog.
20-sim 4.6 Reference Manual
98
6. Simulator
Filename : You can select an existing filename using the browse button or type
one. Data can be read as text file or as binary format.
Read Header: Select this button if you want extra information (variable names
etc.) to be read from the data file.
Variables: The variables box shows the number of columns that were found in
the data file. Each column must be matched with a variable that is shown in
the plot. Click with the mouse on a column number to select it. Then click the
Match Variable button. This opens a Variable Chooser in which you can select
a variable. When a header was used when storing the data file, this
matching is done automatically.
Match Variable : Use this button to select a matching variable for each column
in the variables box.
Plot Variables: Use the Delete button to delete a selected variable
Plot Variables: Use this button to put the same variables as shown in the plot
into the columns of the variables box.
Up/Down: Use the Up and Down buttons to change the order of the variables
shown in the list.
Tip
You can use the Export Data To File command to store simulation results of time
consuming simulations. For later use you can use the Import From Data File command to
read the result from file.
6.2.15 Full Screen Mode
You can show simulation plots and 3D Animations in full screen mode.
1. Put your mouse on top of a plot or animation.
2. From the right mouse menu, select Toggle Full Screen.
To remove the full screen mode:
1. From the right mouse menu, select Toggle Full Screen or press the
Escape key.
6.2.16 Keyboard shortcuts
This is a list of keyboard shortcuts in simulator.
Navigation
Command
Save 20-sim project
Shortcut
[C trl] + S
Current Page
Command
Shortcut
20-sim 4.6 Reference Manual
99
6. Simulator
Zoom
Zoom
Zoom
Zoom
in
normal
out
to fit
[F4]
[F5]
[F6]
[F7]
Control
Command
C lear simulation
Next camera
Process frequency response
Replay simulation
Run simulation
Stop simulation
Single step simulation
Shortcut
[C trl] + e
[C trl] + a
[C trl] + f
[C trl] + q
[C trl] + r
[C trl] + t
[C trl] + w
6.2.17 Training Simulators
Training simulators are simulation model that run real-time and can be used to train
people. 20-sim has some features that allow you to turn 20-sim into a training simulator.
The example model KnuckleBoomC raneKeyboard will show you how it works:
1.Go to the Examples Library and look into the 3D Mechanics folder or in the search bar
enter KnuckleBoomCraneKeyboard. The Find tab will show the results. C lick on the link
to jump to the model.
2.Drag and drop the model to the editor. The keyboard inputs are shown in the model.
3.Run a simulation and use the keyboard inputs to move the crane.
Developing your own training simulator is not difficult. All you have to do is:
1.
Develop a model, that will mimic your training system.
2.
Allow manual inputs, by keyboard or joystick. The library of 20-sim contains special
blocks for keyboard input or joystick input which you can use.
3.
Run the simulation in real-time.
4.
Use 3D animations to show views of your system.
5.
Run the 3D-Animations in full screen.
Tips
Use transparency to show or hide parts of your 3D animation.
20-sim 4.6 Reference Manual
100
6. Simulator
6.3
Run Properties
6.3.1
Simulator Tab
The Simulator tab is the first tab of the Run Properties Editor. This tab shows the general
simulation settings:
The 20-sim Run Properties.
Items
Timing (seconds):
Start: the start time of a simulation run (default: 0)
Finish: the finish time of a simulation run (default: 10)
Event delta : the accuracy for spotting state events. This option can only be
selected if a model contains state events.
Integration Methods: 8 numerical integration methods are available, each with
its own parameters. The parameters can be changed by clicking the Set
Properties button or selecting the tab on top of the editor.
Euler
Backward Euler
20-sim 4.6 Reference Manual
101
6. Simulator
Adams-Bashford 2
Runge Kutta 2
Runge-Kutta 4
Runge Kutta Dormand Prince 8
Runge-Kutta-Fehlberg
Vode Adams
Backward Differentiation Formula (BDF)
Modified Backward Differentiation Formula (MBDF)
Output After Each: This is the plot interval. Use this option to generate output
only after each equidistant time interval has passed. For each interval, the
exact simulation point is used (if available) or the nearest point is used (if not
available, for example when using variable step algorithms).
Related Options
BreakPoints: Click this button to open the Breakpoints Editor.
General Properties: Click this button to open the General Properties Editor.
More : Click this button to set advanced options:
Endless: Select this option if you do not want the simulation to stop.
Attempting Real-Time simulation: Select this option if you want the
simulation to run as fast as the real time. You can choose the option
Catch up with lost time and set the Maximum allowed lost time .
Tips
Use Attempting Real-Time simulation when you have keyboard input or joystick input
in your model.
20-sim 4.6 Reference Manual
102
6. Simulator
6.3.2
Discrete System Tab
The Run Properties Editor can be used to edit the sample frequency of a discrete-time
system in the model. 20-sim automatically detects the existence of discrete systems in a
model. For each discrete system, one extra tab (Discrete System) is shown in the Run
Properties Editor.
The Discrete Systems tab.
Items
Identified with: Each discrete system in a model is assigned a unique identifier.
20-sim detects discrete systems by looking for discrete functions and
variables:
1.
sample
2.
hold
3.
next
4.
previous
5.
sampletime
When a function has been found, the elements of the corresponding discrete
system are identified by propagation of the equations. In order of appearance in
the model, the discrete system is assigned a unique identifier:
1.
sample -> the variable that is assigned to the output of the sample function.
2.
hold -> the variable that is assigned to the output of the hold function.
3.
previous -> the discrete state corresponding with the previous function.
20-sim 4.6 Reference Manual
103
6. Simulator
4.
next -> the discrete state corresponding with the next function.
5.
sampletime -> the variable that is equal to the sampletime.
Timing (Standard): Each discrete system has a default sample frequency of 1
Hz. You can change this frequency to any desired value:
Discrete Time Interval (s): The sample interval (in s) of the discrete system
Frequency (Hz): The sample frequency (in Hz) of the discrete system.
Timing (Advanced): For discrete-time control loops that interact with physical
continuous-time systems through sensors (analog to digital) and actuators
(digital to analog) the specific timing is important. Click the Advanced button to
specify this timing.
6.3.3
Advanced Discrete System Settings
The Advanced Discrete System Settings dialog can be used to set the timing for discretetime control loops that interact with physical continuous-time systems through sensors
(analog to digital) and actuators (digital to analog). You can open the dialog by:
1.
In the Simulator from the Properties menu, click Run to open the Run
Properties Editor.
2.
Select the Discrete System tab and click the Advanced Settings button.
In the Advanced Discrete System Settings dialog you can specify the timing of control
loops with a fixed sampletime (click Global Time) and control loops with a variable
sampletime (click Previous Sample Event Time).
Fixed Sampletime
When you click the Global Time option the following window appears.
20-sim 4.6 Reference Manual
104
6. Simulator
Advanced settings for discrete systems.
The window shows the timing diagram for a fixed sampletime control loop. The loops
starts with an clock interrupt from a timer. It will take some time before the interrupt is
handled and generally some calculations are performed before the sensor signals
(sample) are read. This delay is represented by the sample delay which is divided in a
fixed time and a variable time part. The control loop will proceed and perform the
necessary calculations to generate the actuator output (hold). These calculations will
take some time, which is represented by the fixed time hold delay. After this action the
control loops will come to a halt until the next clock interrupt is generated.
If the control loops is properly designed it will know the task it is performing when a
clock interrupt is getting in. E.g. if it is still calculating the actuator outputs when clock
interrupt is getting in, an error will be generated, specifying that the sampletime is too
small to perform all necessary calculations.
Items
Sample Delay :
Fixed: Enter the fixed sample delay here.
Variable : Enter the
variable delay here. You
can
chose
from two
distributions:
Uniform: The delay is uniformly distributed between the given minimum
and maximum.
Gaussian: The delay has a given mean and standard deviation.
Hold Delay : Enter the fixed hold delay here.
Action on Sample Missed: An error will be generated when the total delay is
larger than the sampletime or when the total delay is negative.
20-sim 4.6 Reference Manual
105
6. Simulator
Variable Sampletime
When you click the Previous Sample Event Time option the following window
appears.
Variable sample time.
The window above shows the timing diagram for a variable sampletime control loop. It
performs the same tasks as a fixed sampletime control loop, but will start the next loop
as soon as the previous loop was finished. The variable sampletime control loop does
not use a clock interrupt!
Items
Sample Delay:
Fixed: Enter the fixed sample delay here.
Variable: Enter the variable delay here. You can chose from two distributions:
Uniform: The delay is uniformly distributed between the given minimum and
maximum.
Gaussian: The delay has a given mean and standard deviation.
Hold Delay: Enter the fixed hold delay here.
Action on Sample Missed: Only an error will be generated when the total delay is
negative.
20-sim 4.6 Reference Manual
106
6. Simulator
6.3.4
Algebraic Relations Solver Tab
The Algebraic Relations Solver tab of the Run Properties Editor is visible when your
model contains algebraic loops that could not be solved during processing. In the tab,
you can specify the tolerance of the algebraic solver algorithm. For each model
evaluation, this solver tries to solve the algebraic loop relations, while standard
integration algorithms, such as Euler, can be use to evaluate the model equations.
The Algebraic Relations Solver tab.
6.3.5
Euler
This is the explicit Euler method. It is a single-step explicit method, which needs one
model calculation per time step. The size of the time step is fixed. This simulation
algorithm requires 1 parameter to be specified:
Step Size : the step time of the integration algorithm (default: 0.01).
6.3.6
Backward Euler
This is a combination of the implicit Backward Euler method and the explicit Forward
Euler method. It is a single-step implicit method, which needs one model calculation per
time step. With the parameter alpha the combination is defined:
alpha combination
-1
100% Forward Euler
explicit
0
50% Forward Euler, 50 % Backward Euler
explicit
1
100% Backward Euler
implicit
20-sim 4.6 Reference Manual
107
6. Simulator
Step Size : the step time of the integration algorithm (default: 0.01).
Relative Tolerance : Relative tolerance for the rootfinding in the Backward Euler
method.
Alpha : Choose between Forward Euler (alpha = -1), Trapezoidal (alpha = 0)
and Backward Euler (alpha = 1).
6.3.7
Adams-Bashford
This is the trapezoidal rule. It is a single-step explicit method, which needs only two
model calculations per time step. The size of the time step is fixed. This simulation
algorithm requires 1 parameter to be specified:
Step Size : the step time of the integration algorithm (default: 0.1).
6.3.8
Runge Kutta 2
This is an explicit single-step second-order derivatives method which needs 2 model
calculations per time step. It is the simple form of the classical Runge-Kutta method. The
size of the time step is fixed. This simulation algorithm requires 1 parameter to be
specified:
Step Size : the step time of the integration algorithm (default: 0.01).
6.3.9
Runge-Kutta 4
This is an explicit single-step fourth-order derivatives method which needs 4 model
calculations per time step. It is the classical Runge-Kutta method. The size of the time
step is fixed. This simulation algorithm requires 1 parameter to be specified:
Step Size: the step time of the integration algorithm (default: 0.01).
6.3.10 Runge-Kutta-Fehlberg
This is an explicit variable-step 4/5-order derivatives method, primarily designed to
solve non-stiff and mildly stiff differential equations. Because the method has very low
overhead costs, it will usually result in the least expensive integration when solving
problems requiring a modest amount of accuracy and having equations that are not
costly to evaluate. This simulation algorithm has 4 parameters:
Integration Error (required)
Absolute : The absolute integration error, valid for every state variable
(default: 1e-6).
Relative : The relative integration error, valid for every state variable
(default: 1e-6).
Step Size (not required)
Initial: The step size for the first simulation step (default: 0.01).
Maximum: The maximum size of a simulation step (default: 1).
20-sim 4.6 Reference Manual
108
6. Simulator
6.3.11 Runge Kutta Dormand Prince 8
This is an explicit variable-step 8-order derivatives method, primarily designed to solve
non-stiff and stiff differential equations. This simulation algorithm has 4 parameters:
Integration Error (required)
Absolute : The absolute integration error, valid for every state variable
(default: 1e-6).
Relative : The relative integration error, valid for every state variable
(default: 1e-6).
Step Size (not required)
Initial: The step size for the first simulation step (default: 0.01).
Maximum: The maximum size of a simulation step (default: 1).
6.3.12 Vode Adams
This is the explicit variable-step stiff integration algorithm of C ohen and Hindmarsh. This
method is specially suited for explicit models that combine high and low frequency
vibrations with little damping (so called "stiff" models). This simulation algorithm has 4
parameters:
Integration Error (required)
Absolute : The absolute integration error, valid for every state variable
(default: 1e-6).
Relative : The relative integration error, valid for every state variable
(default: 1e-6).
Maximum Step Size (not required): The maximum size of a simulation step
(default: 1).
Multistep Method (required): The variable step integration method that is used.
A BDF method is default and best suited for stiff systems.
Iteration Type (required): The method used for iteration loops (algebraic
relations). The Newton method is default and best suited for stiff systems.
6.3.13 Backward Differentiation Formula (BDF)
This is an implicit multi-step variable-order first-order derivatives method. It is Gear's
backward differentiation formula, which is up to fifth order, so 1 to 5 model calculations
are needed per time step. The code of the Dassl library is used. It is suitable for models
having derivative causalities and/or algebraic loops. This simulation algorithm has 4
parameters:
Integration Error (required)
Absolute : The absolute integration error, valid for every state variable
(default: 1e-5).
Relative : The relative integration error, valid for every state variable
(default: 1e-5).
20-sim 4.6 Reference Manual
109
6. Simulator
Step Size (not required)
Initial: The step size for the first simulation step (default: 0.1).
Maximum: The maximum size of a simulation step (default: 1).
Note
Undamped models are not simulated properly with this method.
The default values are suitable for problems with time constants of order of
magnitude of 0.1 to 1. Initial Step Size and Maximal Step Size influence the
behavior of the method and should be tuned with care.
6.3.14 Modified Backward Differentiation Formula
(MBDF)
This is an implicit multi-step variable-order first-order derivatives method. It is Gear's
backward differentiation formula, which is up to fifth order, so 1 to 5 model calculations
are needed per time step. The code of the Dassl library is used. It is suitable for models
having derivative causalities and/or algebraic loops. The MBDF allows the use of
constraint variables when proper initial values are used.
This simulation algorithm has 4 parameters:
Integration Error (required)
Absolute : The absolute integration error, valid for every state variable
(default: 1e-5).
Relative : The relative integration error, valid for every state variable
(default: 1e-5).
Step Size (not required)
Initial: The step size for the first simulation step (default: 0.1).
Maximum: The maximum size of a simulation step (default: 1).
Note
This is the only method that supports the use of the constraint function.
The MeBDFi method cannot handle contraints that do not influence the model.
Therefore 20-sim will check at the beginning of the simulation if contraints have been
properly defined. The contraints that do not influence the model are set to zero
automatically. If you do not want to use this check, deselect the Smart Contraint
Solving option.
Undamped models are not simulated properly with this method.
The default values are suitable for problems with time constants of order of
magnitude of 0.1 to 1. Initial Step Size and Maximal Step Size influence the
behavior of the method and should be tuned with care.
20-sim 4.6 Reference Manual
110
7. Language Reference
7
Language Reference
7.1
Introduction
7.1.1
Language Reference
Every (sub)model has an implementation. This can be a composition of lower level
submodels, which themselves are composed of lower level submodels etc. At the bottom
of this hierarchy the submodels consist of a set of mathematical equations (equation
submodel). These submodels are therefore known as equation submodels.
All equations used in 20-sim are described in the language SIDOPS+. A simple equation
model written in SIDOPS+ is shown below:
20-sim 4.6 Reference Manual
111
7. Language Reference
A simple equation model in 20-sim.
You will find out that in most cases the SIDOPS+ language is equal to standard
mathematical notation. Regardless of your modeling background, you can learn quickly
to build your own equation models. 20-sim comes with over 80 built-in functions that do
most of the work for you. To learn more about equation models, have a look at the
following sections:
1.
Model Layout
2.
Keywords ( C onstants, Parameters, Variables, Equations )
3.
Data Types
4.
Operators
5.
Functions
6.
Statements
7.1.2
Model Layout
The general layout of an equation model is:
constants
// enter your constants here, for a description see constants
parameters
// enter your parameters here, for a description see parameters
variables
20-sim 4.6 Reference Manual
112
7. Language Reference
// enter your variables here, for a description see variables
initialequations
// enter your initial equations here, for a description see initialequations
code
// enter your equations here, for a description see code
equations
// enter your equations here, for a description see equations
finalequations
// enter your final equations here, for a description see finalequations
Only the equations section is required. The other sections are optional.
7.1.3
Equations
The body of an equation model consists of the keywords initialequations, code, equations
and finalequations, each followed by one or more equations. Equations are relations
between variables indicated by an equal (=) sign:
y = x + 1;
z + y = sin(time*2*pi*f);
g = ddt(g + z, g_initial);
An equation can be combination of operators, functions, powerports variables, inputs,
outputs, constants, parameters and variables. Equations in 20-sim follow the standard
mathematical notation.
Rules
The following rules must be obeyed when specifying equations:
1.
An equation may span more than one line but must always be finished by a
semicolon (;).
2.
Parentheses may be used to indicate grouping as in ordinary mathematical notation,
e.g.
u = sin(time*f*2*3.1415 + (a + b)/c );
4.
Extensions like .e or .f are used to indicate the effort and the flow variables of
powerports. These extensions are not allowed for any other type of identifier (i.e.
inputs, outputs, constants, parameters or variables).
5.
20-sim has some predefined variables which have a special meaning.
6.
Each variable must be assigned a value exactly once.
7.
Errors are shown automatically after checking in the Process tab. Double clicking on
the error text will make 20-sim jump to the error, which is then colored red.
Execution
1.
Equations within 20-sim may be entered in random form. During compilation, 20-sim
will automatically try to rewrite equations into a correct order of execution.
20-sim 4.6 Reference Manual
113
7. Language Reference
2.
Some integration algorithms do more calculations before generating the next output
value. These calculations are called minor steps, the output generation is called a
major step. During a minor step, all model equations are executed. In most cases
you will not notice this because only the results of the major step are shown in the
simulator, but in some cases this may cause unwanted results.
7.1.4
Equation Sections
In 20-sim equations can be divided in four sections: initialequations, equations, code and
finalequations.
Initialequations
The initialequations section should contain all equations that should calculated before the
simulation run. The equations are calculated once. The equations in this section form a
code block, i.e. the equations themselves and the order of the equations are not
rewritten during compilation and executed sequentially. The results of the initialequations
section are not shown in the simulator plots and can therefore not be inspected in the
Numerical Values window!
Example
The initialequations section is used in the library model Spring Damper (stiffness):
parameters
real k = 10.0 {N/m};
real m = 1.0 {kg};
real b = 0.05 {};
variables
real x {m};
real d {damping,N.s/m};
initialequations
d = 2*b*sqrt(k*m);
equations
x = int (p.v);
p.F = k * x + d*p.v;
As you can see in the initialequations section the damping d is calculated out of the
relative damping b, mass m and stiffness k.
Equations
The equations section contains all standard equations. They do not have to be entered in
a sequential form. They are rewritten during compilation to get the correct order of
execution. The resulting code is calculated every simulation step. You can see the use of
the equations section in the example above.
Code
The code section contains a code block. A code block contains all equations that must be
calculated sequentially, i.e. the equations themselves and the order of the equations are
not rewritten during compilation. The resulting sequential code is calculated every
simulation step.
Example
The code section is used in the library model Spring Damper (stiffness):
20-sim 4.6 Reference Manual
114
7. Language Reference
parameters
real initial = 0.0;
variables
real prev, peak;
initialequations
peak = initial;
prev = 0;
output = initial;
code
if major then
peak = max([abs(input), peak]);
if (input > 0 and prev < 0) or (input < 0 and prev > 0) then
output = peak;
peak = 0;
end;
prev = input;
end;
Finalequations
The finalequations section should contain all equations that should be calculated after a
simulation run. The equations are calculated once. The equations in this section form a
code block, i.e. the equations themselves and the order of the equations are not
rewritten during compilation and executed sequentially. The results of the finalequations
section are not shown in the simulator plots and can therefore not be inspected in the
Numerical Values window!
Example
The finalequations section is used in the library model DoMatlab-Final:
parameters
string command = '';
finalequations
// send the command to the workspace
doMatlab (command);
As you see you can give the parameter command any value, which is then exported to
Matlab at the end of the simulation run.
7.1.5
Using Port Names
To use port variables in equations, you must use the port names that are defined in the
Interface Editor.
Signal Ports
For signal ports, you can directly use the port names. The example below, shows the
library model Differentiate-SVF.emx. In the Interface Editor, two ports are defined with
the names input and output. In the equations these names are used.
20-sim 4.6 Reference Manual
115
7. Language Reference
The Interface tab shows the contents of the Interface Editor.
Power ports
Power ports describe the flow of power and are always characterized by two variables.
For bond graph ports the extensions .e and .f are used to indicate these variables. For
iconic diagram ports many aliases are known. You can use these variables in equations
by typing the port name followed by a dot and the extension.
You can always find the correct extensions by opening the Interface Editor and selecting
a port. The example below, shows the library model Friction.emx. In the Interface
Editor, one power port is defined with the name p. As shown, the correct description of
both variables is p.v and p.F.
Double clicking in the Interface tab will open the Interface Editor.
The equation description of this model (see below) shows the use of the variables p.v
and p.F.
20-sim 4.6 Reference Manual
116
7. Language Reference
In the equations the port variables p.F and p.v are used.
7.1.6
Reserved Words
While entering equations, the 20-sim Editor will automatically detect reserved words. You
can recognize reserved words, because they will be shown with a different color:
element
color
keywords
black
data types
black
functions
blue
statements
black
predefined variables
blue
20-sim knows the following reserved words:
20-sim 4.6 Reference Manual
117
7. Language Reference
- , * , .* , ./ , .^ , / , ^ , + , < , <= , <> , == , > , >= , abs , adjoint , Adjoint ,
algebraic , and , antisym , arccos , arccosh , arcsin , arcsinh , arctan , arctanh , atan2 ,
boolean , by , ceil , code , collect , columns , constants , constraint , cos , cosh , cross ,
data , ddt , delta , det , diag , direct , discrete , div , dll , dlldynamic , dly , do , doMatlab
, effortincausality , else , end , equal , equations , event , eventdown , eventup , exp ,
exp10 , exp2 , export , externals , eye , false , finalequations , first , floor ,
flowincausality , for , frequencyevent, from , fromMatlab , gauss , global , hidden , hold ,
homogeneous , if , import , initialequations , inner , int , integer , interesting , inverse ,
inverseH, limint , limit , log , log10 , log2 , major , max , min , mod , msum , mul , next
, nonlinear , norm , norminf , not , or , parameters , previous , ramp , ran , random ,
real , repeat , resint , resint , return , round , rows , sample , sampletime , sign , sin ,
sinh , skew , sqr , sqrt , step , stopsimulation , string , sum , sym , table , tan , tanh ,
tdelay , then , tilde , time , timeevent , to , toMatlab , trace , transpose , true , trunc ,
type , types , until, variables , warning , while , xor
7.1.7
White Space
Like C and other programming languages, 20-sim does not recognize white space
(spaces and tabs, carriage returns) except in a string. We recommend that you use
white space to make your model easier to follow. For example, the following model is
dense and difficult to read:
variables
real y,u;
equations
y = step(1);
u = -step(1);
if time > 5 then y = -ramp(1); u = ramp(1);
else y = ramp(1); u = -ramp(1); end;
Adding white space with indentation makes the same code much easier to read:
variables
real y;
real u;
equations
y = step(1);
u = -step(1);
if time > 5 then
y = -ramp(1);
u = ramp(1);
else
y = ramp(1);
u = -ramp(1);
end;
20-sim 4.6 Reference Manual
118
7. Language Reference
7.1.8
Writing Comments
20-sim gives you several options to create comments in a model. You can use each
option add explanatory text to your model or to exclude ("comment out") certain parts
of your model for testing and debugging purposes.
Block Quotes ("...")
You can enclose a block of text between quotes ("). This method makes it easy to write
a comment over multiple lines:
"This is a line of sample code that shows you how to
use the 20-sim comments"
Programming (/*...*/)
You can enclose a block of text between the constructs /* and */. This method is used
often in programming and also allows to write a comment over multiple lines:
/*This is a line of sample code that shows you how to
use the 20-sim comments*/
Single Line Comment (//...)
A option often used in programming is to insert // into a line. The compiler ignores
everything to the right of the double slashes on that line only.
// This is a line of sample code showing the
// 20-sim comments.
You can begin comments anywhere in a model. 20-sim will automatically recognize
comments and color it green.
7.1.9
State and Time Events
Normally an integration algorithm uses a fixed time step or a variable step, depending
only on the model dynamics. In some cases, the algorithm is forced to perform
calculations at a specific time.
Time Events
The most simple form of forced calculation is calculation at a specific time. This is called
a time event. The following functions cause time events.
function
description
timeevent
Forces the integration algorithm perform a calculation at a specific
time.
frequencyevent
Forces the integration algorithm perform a calculation at a specific
frequency.
sample , hold, next, These functions introduce a discrete system in a model. A discrete
system forces the integration algorithm to perform calculations
previous
every sampletime.
20-sim 4.6 Reference Manual
119
7. Language Reference
State Events
Sometimes the integration algorithm must iterate to find the next calculation step. This is
called a state event. The following functions cause state events.
function
description
event
Forces the integration algorithm to find the exact point
input crosses zero.
Forces the integration algorithm to find the exact point
input crosses zero from a negative to a positive value.
Forces the integration algorithm to find the exact point
input crosses zero from a positive to a negative value.
Forces the integration algorithm to find the exact point
output become larger or smaller than the minimum and
parameters.
Forces the integration algorithm to find the exact point
input becomes zero.
eventup
eventdown
limint
resint
where the
where the
where the
where the
maximum
where the
To find the exact point where simulation should be performed iteration is used. The
accuracy of the iteration can be set by the event delta parameter in the Run Properties
window.
7.2
Keywords
7.2.1
Keywords
Before the actual equations, three sections can be entered denoted by the keywords
constants, parameters and variables. This is shown in the example below:
constants
real basefrequency = 60;
real pi = 3.14159265;
parameters
real amplitude = 1;
variables
real plot;
equations
plot = amplitude * sin (basefrequency*2*pi * time);
The order of appearance of these sections must always be: (1) constants, (2)
parameters and (3) variables. The sections are optional. If you do not use constants
parameters or variables, these sections may be omitted.
7.2.2
Constants
C onstants are symbolic representations of numerical quantities that do not change
during or in between simulation runs. C onstants must be defined in 20-sim, using the
constants keyword. After the keyword, lines with constant declarations can be entered.
Every line must be finished by a semicolon (;). An example is given below:
20-sim 4.6 Reference Manual
120
7. Language Reference
constants
real V = 1 {volume, m3};
real hidden D = 0.5 {length, m};
...
// the volume of barrel 1
// the length of part 1
Types
20-sim currently supports four types of constants: boolean, integer, real and string.
These types must be specified explicitly. The use of the type real is shown in the
example above.
Hidden
To prevent users from inspecting constants, the keyword hidden can be applied. This
keyword should follow the data type.
Constant names
C onstant names can consist of characters and underscores. A constant name must
always start with a character. C onstant names are case-sensitive. No reserved words
may be used for constants. If a reserved word is used, an error message will pop-up
while checking the model. In the example above the names V and D are used.
Constant Values
It is advised to assign every constant a value. Otherwise 20-sim will assign a default
value (0, false or an empty string), which can easily lead to misinterpretations. Unlike
parameter values, constant values cannot be overridden in the Simulator.
Quantity and Unit
If a constant is known to represent a physical value, you can define the corresponding
quantity and unit. 20-sim will use this information to do a unit check on equations. The
use of quantities and units is optional. In the example above the quantities volume and
length are used with the units m3 and m.
Example
constants
real pi = 3.14159265359;
real two pi = 6.28318530718;
integer i = 10 {length,m};
integer j = 1 {time,s};
// vehicle length
constants
string filename = 'data.txt';
integer i = 1;
real state = 0.0;
boolean t = true, f = false;
Tip
You can easily enter constants by using the Add button
Taskbar.
in the Equation Editor
You can easily select quantities and units by using the Units button
Equation Editor Taskbar.
20-sim 4.6 Reference Manual
of the
121
7. Language Reference
7.2.3
Predefined Constants
Some constants in 20-sim have a predefined value. These constants do not have to be
declared in the constants section of a model. You can add your own predefined constants
in the file Constants.ini in the 20-sim bin-directory.
Standard
pi
exp1
twopi
sqrt2
log2
Physics
g_n
G
c_0
mu_0
3.1415926535897932384626433832795
2.71828182845904523536028747135266
6.28318530717958647692528676655901
1.41421356237309504880168872420969
0.6931471805599453094172321214581766
epsilon_0
h
m_p
l_p
t_p
e
R_H
mu_B
mu_N
Ry
a_0
N_A
m_u
F
k
sigma
b
R
V_m
n_0
9.80665 {m/s2}
Standard acceleration of gravity
66.7259e-12 {N.m2/kg2}
Newtonian constant of gravitation
299.792458e6 {m/s}
Speed of light (vacuum)
1.256637061435917295385057 Permeability (vacuum)
3533118e-6 {H/m}
8.854188e-12 {F/m}
Permittivity (vacuum)
6.6260755e-34 {J.s}
Planck constant
2.17671e-08 {kg}
Planck mass
1.61605e-35 {m}
Planck length
5.39056e-44 {s}
Planck time
1.60217733e-19 {C }
Elementary charge
25812.8056 {Ohm}
Quantized Hall resistance
9.2740154e-24 {J/T}
Bohr magneton
5.0507866e-27 {J/T}
Nuclear magneton
10973731.534 {1/m}
Rydberg constant
5.29177249e-11 {m}
Bohr radius
6.0221367e+23 {1/mol}
Avogadro constant
1.6605402e-27 {kg}
Atomic mass constant
96485.309 {C /mol}
Faraday constant
1.380658e-23 {J/K}
Boltzmann constant
5.67051e-08 {W/m2.K4}
Stefan-Boltzmann constant
0.002897756 {m.K}
Wien constant
8.31451 {J/mol.K}
Molar gas constant
0.0224141 {m3/mol}
Molar volume (ideal gas)
2.686763e+25 {1/m3}
Loschmidt constant
m_e
m_p
m_n
9.1093897e-31 {kg}
1.6726231e-27 {kg}
1.6749286e-27 {kg}
Electron mass
Proton mass
Neutron mass
20-sim 4.6 Reference Manual
122
7. Language Reference
Conversion
Constants
eV
u
atm
deg
7.2.4
1.60217733e-19 {J};
1.6605402e-27 {kg}
101325 {Pa}
0.017453292519943295769236
9076848861 {rad}
Electron volt
Atomic mass unit
Standard atmosphere
Angular degree
Parameters
Parameters are symbolic representations of numerical quantities which can only be
changed after simulation has been stopped. They can therefore be changed in between
of simulation runs, or after the user has (temporarily) stopped the simulation.
Parameters must be defined in 20-sim, using the parameters keyword. After the
keyword, lines with parameter declarations can be entered. Every line must be finished
by a semicolon (;) and may be followed by comment with a description of the
parameter. An example is given below:
parameters
real V = 1 {volume, m3};
real hidden D = 0.5 {length, m};
...
// the volume of barrel 1
// the length of part 1
Types
20-sim currently supports four types of parameters: boolean, integer, real and string.
These types must be specified explicitly. The use of the type real is shown in the
example above.
Hidden
To prevent users from inspecting parameters or decreasing the list of parameters, the
keyword hidden can be applied. This keyword should follow the data type.
Global
To use the same parameter in other submodels, the keyword global can be applied. This
keyword should follow the data type.
Parameter Names
Parameter names can consist of characters and underscores. A parameter name must
always start with a character. Parameter names are case-sensitive. No reserved words
may be used for parameters. If a reserved word is used, an error message will pop-up
while checking the model. In the example above the names V and D are used.
Parameter Values
Parameters can be assigned default values. These values can be overridden in the
Simulator using the Parameters command.
20-sim 4.6 Reference Manual
123
7. Language Reference
Quantity and Unit
If a parameter is known to represent a physical value, you can define the corresponding
quantity and unit. 20-sim will use this information to do a unit check on equations. The
use of quantities and units is optional. In the example above the quantities volume and
length are used with the units m3 and m.
Comment
If comment is added at the end of the parameter declaration, it is shown in the Variable
C hooser to facilitate the selection between variables.
Example
parameters
real p1 = 12, p2, state = 1.1;
integer i = 10 {length,m};
integer j = 1 {time,s};
// vehicle length
parameters
string filename = 'data.txt';
// This comment appears as a description in
the Parameters/Initial values editor.
integer i = 1;
// Just a parameter
real state;
// Initial velocity [m/s]
boolean t = true;
// T = true
Tip
You can easily enter parameters by using the Add button
Taskbar.
in the Equation Editor
You can easily select quantities and units by using the Units button
Equation Editor Taskbar.
7.2.5
of the
Variables
Variables are symbolic representations of numerical quantities that may change during
simulation runs. Variables must be defined in 20-sim, using the variables keyword. After
the keyword, lines with variable declarations can be entered. Every line must be finished
by a semicolon (;). An example is given below:
variables
real interesting V {volume, m3};
real hidden D {length, m};
...
// the volume of barrel 1
// the length of part 1
Types
20-sim currently supports four types of variables: boolean, integer, real and string.
These types must be specified explicitly. The use of the type real is shown in the
example above.
20-sim 4.6 Reference Manual
124
7. Language Reference
Interesting
By adding the keyword interesting after the variable type, a variable will be given
special focus in the Variable C hooser. The Variable C hooser shows the complete list of
variables of a model and is used to select variables for plotting. The keyword interesting
is shown in the variable list, making it easier to find variables of special interest.
Hidden
To prevent users from inspecting variables or decreasing the list of variables, the
keyword hidden can be applied. This keyword should follow the data type.
Global
To use the same variable in other submodels, the keyword global can be applied. This
keyword should follow the data type.
Variable Names
Variable names can consist of characters and underscores. A variable name must
always start with a character. Variable names are case-sensitive. No reserved words
may be used for variables. If a reserved word is used, an error message will pop-up
while checking the model.
Variable Values
Variables cannot be assigned default values.
Quantity and Unit
If a variable is known to represent a physical value, you can define the corresponding
quantity and unit. 20-sim will use this information to do a unit check on equations. The
use of quantities and units is optional. In the example above the quantities volume and
length are used with the units m3 and m.
Comment
If comment is added at the end of the variable declaration, it is shown in the Variable
Chooser to facilitate the selection between variables.
Predefined Variables
20-sim has some predefined variables which have a special meaning.
Example
variables
real interesting p1,p2,state;
integer i;
integer j;
variables
string filename;
integer interesting i;
real interesting state;
boolean t,f;
20-sim 4.6 Reference Manual
125
7. Language Reference
7.2.6
Predefined Variables
Some variables in 20-sim have a predefined value. These variables do not have to be
declared in the variables section of a model.
time
The variable time is equal to the simulated time. It can for example be used in functions
such as:
u = sin(time*f*2*3.1415);
starttime
The variable starttime is equal to the Start value of the Simulator Run Properties
(typically 0.0 {s}).
finishtime
The variable finishtime is equal to the Finish value of the Simulator Run Properties (e.g.
10.0 {s}). It can be used for example to execute some actions just before finishing the
simulation:
if (time >= finishtime - 1.0) then
// do some action
end;
realtime
The variable realtime contains the elapsed wall-clock time (in seconds) from the start of
the simulation. It can be used to monitor if the simulation runs slower, equally fast or
faster than real time.
if (time >= realtime) then
// simulation is realtime or faster than realtime
else
// simulation is slower that real time
end;
sampletime
The variable sampletime is equal to the sampletime. It is only meaningful when it is used
in an equation model that is part of a discrete loop in your model. 20-sim will
automatically detect, which loop the model belongs to and assign the proper value to the
variable sampletime.
stepsize
The variable stepsize contains the actual stepsize of the integration routine. It can be
used to monitor the variable step sizes of methods like BDF and Vode Adams.
random
The variable random will yield a random variable uniformly distributed in the interval [1,1]. E.g.:
20-sim 4.6 Reference Manual
126
7. Language Reference
u = random;
true
The variable true will return the boolean value true.
false
The variable false will return the boolean value false.
major
Some integration algorithms, will perform model calculations at one or more
intermediate points before calculating the next output value. To prevent equations being
calculated, at these intermediate steps, you can use the variable major. This variable
will return the boolean false when calculations are performed for an intermediate step
and will return true when calculations are performed for the output values.
Example
....
if major then
sim_steps = sim_steps
intermediate points
end;
....
7.2.7
+
1;
// this equation is not evaluated at
Global Parameters and Variables
Global parameters and variables are defined using the keyword global. In equation
models, this keyword is added after the definition of the data type in the Equation Editor:
parameters
real global
real global
variables
real global
real global
..
..
par1 = 100 {Hz};
par2 ;
var1;
var2;
Parameters can only be assigned a value once. The same goes for variables. Only one
submodel must defined their value using an equation. If parameters or variables are
assigned more than once, 20-sim will generate an error.
Example
The best way to describe the use of global parameters and variables is by an example
model. You can find this model in the 20-sim demonstration library (Demo\Tips And
Tricks\Global Parameters and Variables.emx). The model exists of three submodels. In
the first submodel two global parameters (f and A) are assigned and one variable
(sinewave). The variable is assigned a value in the equations section and connected with
the output (out1).
20-sim 4.6 Reference Manual
127
7. Language Reference
submodel1
parameters
real global f = 100 {Hz};
real global A = 1 {none};
variables
real global sinewave;
equations
sinewave = A*sin(f*2*pi*time);
out1 = sinewave;
In the second submodel, the two global parameters are use to connect them with two
outputs (out1 and out2).
submodel 2
parameters
real global f {Hz};
real global A {none};
variables
real global sinewave;
equations
out1 = f;
out2 = A;
In the third submodel, the global variable is connected with an output (out1).
submodel 3
variables
real global sinewave;
equations
out1 = sinewave;
To prevent conflicts global parameters may be assigned a default value only once. The
same goes for global variables: they may be assigned a value in the equation section
only once.
20-sim 4.6 Reference Manual
128
7. Language Reference
7.3
Types
7.3.1
Data Types
For all parameters, variables, initial conditions etc. 20-sim supports the following data
types:
1.
Boolean
2.
Integer
3.
Real
4.
String
The declaration of data types can be done in the constants, parameters and variables
sections of the model. E.g.:
parameters
real a = 1;
integer B[2,2];
variables
string c;
boolean yesno;
Declaration of data types in equations is not allowed. E.g.:
real v = sin(t*a + b); // This is not allowed!
Hidden
To prevent users from inspecting variables, parameters or constants (e.g. for encrypted
models) or decreasing the list of parameters and variables, the keyword hidden can be
applied. This keyword should follow the data type. For example:
parameters
real hidden a = 1;
integer hidden B[2,2];
variables
string hidden c;
boolean hidden yesno;
Interesting
To allow for a quick selection of variables in the Variable C hooser, the keyword
interesting can be applied for variables. This keyword should follow the data type. For
example:
parameters
real a = 1;
integer B[2,2];
variables
string interesting c;
boolean interesting yesno;
20-sim 4.6 Reference Manual
129
7. Language Reference
Interesting variables are shown, even when all options are deselected in the Variable
C hooser. This makes it possible to quickly select variables out of a large list.
7.3.2
Boolean
Either true (1) or false (0). Variables of this type should not be used to store any other
values. Like C ++, 20-sim evaluates non-zero values as true; only the value of zero is
evaluated as false. Normally, the value of one is used to indicate true.
Examples
boolean a;
boolean b = true;
boolean c = false;
boolean D[2,2] = [true,true;false;false];
a = b and c;
Limitations
When used in standard functions, booleans are treated as reals with value 0 or 1. An
equation like:
boolean a = true;
real c;
c = sin(a);
would yield c equal to 0.8415. Try to avoid these constructions, since they lead to
confusions.
7.3.3
Integer
Signed four-byte integer. It can hold any value between -2147483648 and
+2147483647. Integer is the recommended data type for the control of program loops
(e.g. in for-next loops) and element numbering.
Example
parameters
integer i = 1,j = 2;
real B[2,2] = [1,2;3,4]
real b;
equations
b = B[i,j];
for i := 1 to 10 do ....end;
Limitations
When used in standard functions, integers are treated as reals. An equation like:
parameters
integer c;
equations
c = 10*sin(time);
would yield c equal to 0.8415. Try to avoid these constructions, since they lead to
confusions. Us the round function instead:
20-sim 4.6 Reference Manual
130
7. Language Reference
parameters
integer c;
equations
c = round(10*sin(time));
7.3.4
Real
Signed 64 bit floating point number. The maximum representable number is
1.7976931348623158e+308. The minimum positive value unequal to zero is
2.2250738585072014e-308. If reals exceed this range during simulation, the numerical
values window will display the values 1.#INF (positive infinite) or -1.#INF (negative
infinite).
Example
real a = 0.0;
real b = 1.04e-31,c = -3198.023e-64;
real B[2,2] = [1.2,22.4;3.0e3,-4.023e-6];
Limitations
In practice, during simulation, real should not exceed 1e-100 .. 1e100 to prevent
instability in the integration algorithms.
7.3.5
String
A string is an array of characters. There is no limit to the amount of characters a String
may contain. Simple string concatenation (e.g. concatenation that can be done during
processing) is allowed. Strings must always be entered between single quotes ('). A
single quote can be escaped with a second quote, so if a single quote should be part of
the string, it needs to be typed twice.
Example
parameters
string c = 'C:\data.txt';
string b = 'This is a string with a '' single quote';
variables
real d;
string name;
equations
if time > 10 then stopsimulation (b); end;
d = table(c,1);
name = c + ' // file';
toMatlab (d, name)
Limitations
Strings may only be used as input for some special functions (e.g. table).
20-sim 4.6 Reference Manual
131
7. Language Reference
7.4
Functions
7.4.1
Functions
In 20-sim you can use all kind of functions to describe your equations. They are
classified according to the list below.
1.
Arithmetic
2.
Discrete
3.
Event
4.
Expansion
5.
Extern
6.
Matrix
7.
Port
8.
Source
9.
Trigonometric
7.4.2
Arithmetic
abs
Syntax
Y = abs(X);
Description
Returns the absolute value of X or the elements of X.
Examples
X
1
2.1
-2.6
-1e-102
[1.1,2.7;-3.6,-4]
abs(X)
1
2.1
2.6
1e-102
[1.1,2.7;3.6,4]
Limitations
X and Y must have the same size.
For scalars, the abs function can also be written as: Y = |X|;
20-sim 4.6 Reference Manual
132
7. Language Reference
algebraic
Syntax
y = algebraic(x);
Description
y becomes equal to x. This function forces the integration algorithm to find a solution by
using the algebraic loop solver. Normally when algebraic loops occur in a model, 20-sim
will itself will break the algebraic loop using the algebraic loop solver internally. You can
use this function to break an algebraic loop at a user-defined position.
Examples
u = sin(time);
a = algebraic(y);
y = K*(u - a);
Note
Be very careful with this function. In most cases the symbolic engine of 20-sim will find
and exact solution which will lead to much faster simulation!
ceil
Syntax
Y = ceil(X);
Description
Rounds X or the elements of X to the nearest integers greater than or equal to X.
Examples
X
1
2.1
-2.6
3.4
[1.1,-2.7;3.5,-4.1]
ceil(X)
1
3
-2
4
[2,-2;4,-4]
Limitations
X and Y must have the same size.
constraint
Syntax
y = constraint(x);
Description
20-sim 4.6 Reference Manual
133
7. Language Reference
This function iteratively assigns a value to y such that x approaches zero within a given
error margin. It only works in combination with the MBDF simulation method! The
function is very useful for entering constraints in physical systems and inverse
dynamics.
Examples
This example makes a velocity vm equal to a reference velocity vs:
vs = sin(time);
v = vm - vs;
velocity
F = constraint(v);
vm = (1/m)*int(F);
// reference velocity
// If v = 0 then the mass follows the reference
// Make F have a value that yields a zero velocity v
// mass
ddt
Syntax
y = ddt(x,init);
Description
Returns the derivative value of x with respect to the time. The initial value of y is equal
to the value of init.
Method
20-sim will always try to rewrite equations in such a way that only integrals are used
(integral form). This is done automatically and means all integration methods can be
applied. Sometimes an integral form cannot be found. Then only the BackwardDifferentiation Method can be used for simulation.
Examples
equation
integral form
integration
ddt(x,0) = u - k*x;
x = ddt(sin(time),0);
x = int(u - k*x);
not possible!
All methods
Only BDF
Limitations
When no integral form can be found, the use of the derivative function can introduce
noisy signals or may even cause signals to exceed the data range.
derivative
Syntax
y = derivative(x,base);
Description
Returns the derivative value of x with respect to base. E.g:
20-sim 4.6 Reference Manual
134
7. Language Reference
variables
real x, y, z;
equations
x = sin (time);
y = derivative (x, time);
z = derivative (x^2, x);
Limitations
20-sim will use its symbolic engine to solve the derivative and rewrite it to a closed
form. If no solution is found, and error message is generated.
dly
Syntax
y = dly(x,init);
Description
y is equal to the value of x, one simulation-time step delayed. The initial value of y is
equal to init
Example
x = sin(time*0.3);
y = dly(x, 1.0);
Limitations
x,y and init must be scalars.
exp
Syntax
Y = exp(X);
Description
Returns the exponential function of X or the elements of X.
y = e x;
Examples
X
exp(x)
1
2.718282 (= e1)
2.1
8.166170 (= e2.1)
-2.6
0.074274 (= e-2.6)
[1,2.1;-2.6,1]
[2.718282,8.166170;0.074274,2.7
18282]
( = [e1,e2.1;e-2.6,e1] )
20-sim 4.6 Reference Manual
135
7. Language Reference
Limitations
X and Y must have the same size.
exp10
Syntax
Y = exp10(X);
Description
Returns the exponential function (base 10) of X or the elements of X.
y = 10x;
Examples
X
1
exp10(x)
10 (= 101)
2.1
125.89 (= 102.1)
-2.6
0.00251 (= 10-2.6)
[1,2.1;-2.6,1]
[10,125.89;0.00251,10]
( = [101,102.1;10-2.6,101] )
Limitations
X and Y must have the same size.
exp2
Syntax
Y = exp2(X);
Description
Returns the exponential function (base 2) of X or the elements of X.
y = 2x;
Examples
X
1
exp2(x)
2 (= 21)
2.1
4.8709 (= 22.1)
20-sim 4.6 Reference Manual
136
7. Language Reference
-2.6
0.16494 (= 2-2.6)
[1,2.1;-2.6,1]
[2,4.8709;0.16494,2]
( = [21,22.1;2-2.6,21] )
Limitations
X and Y must have the same size.
floor
Syntax
Y = floor(X);
Description
Rounds X or the elements of X to the nearest integers less than or equal to X.
Examples
X
1
floor(X)
1
2.1
2
-2.6
-3
3.4
3
[1.1,-2.7;3.5,-4.1]
[1,-3;3,-5]
Limitations
X and Y must have the same size.
initialvalue
Syntax
Y = initialvalue(X);
Description
Returns the initial value of X or the elements of X. Value should be assigned to X first.
Examples
X
1
initialvalue(X)
1
sin(time)
0
[cos(time); sin(time)]
[1;0]
Limitations
X and Y must have the same size.
20-sim 4.6 Reference Manual
137
7. Language Reference
int
Syntax
y = int(x,init);
Description
Returns the integral of x with respect to the time. The initial value of y is equal to the
value of init. This initial value is optional. If no value is entered, a default initial value of
0 is used.
Examples
y = int(x,0);
z = int( sin(time*w + p) - cos(time*x + z) , b);
limint
Syntax
y = limint(x,min,max,init);
Description
Returns the integral of x with respect to the time. The initial value of y is equal to the
value of init. The output of this integral is limited between a maximum and minimum
bound given by the parameters min and max.
This function forces the integration algorithm to find the exact point where the gets
saturated. If the integral is in saturated condition and the input changes sign, the output
wanders away from the bounds immediately.
The limitedIntegrator block is used for the prevention of wind-up in PI and PID
controllers in control applications. It is also used in kinematics, electrical circuits, process
control, and fluid dynamics.
Examples
x = 10*sin(time*10);
y = limint(x,-1,1,0);
limit
Syntax
y = limit(x,a,b);
Description
This function limits the signal x between a minimum of a and a maximum of b.
20-sim 4.6 Reference Manual
138
7. Language Reference
Examples
x = 10*sin(time);
y = limit(x,-5,5);
Limitations
a,b,x and y must be scalars. a must be smaller than b.
log
Syntax
y = log(x);
Description
Returns the natural logarithm of X or the elements of X.
Examples
X
log(X)
1
0
2.1
0.6931
4
1.3863
[1,2.1;4,1]
[0,0.6931;1.3863,0]
-2.6
not allowed!
20-sim 4.6 Reference Manual
139
7. Language Reference
Limitations
X and Y must have the same size. X or the elements of X must be larger than zero.
log10
Syntax
Y = log10(X);
Description
Returns the base 10 logarithm of X or the elements of X.
Examples
X
log10(X)
1
0
50
1.6990
100
2
[1,50;100,1]
[0,1.6990;2,0]
-2.6
not allowed!
Limitations
X and Y must have the same size. X or the elements of X must be larger than zero.
log2
Syntax
Y = log2(X);
Description
Returns the base 2 logarithm of X or the elements of X.
Examples
X
log2(X)
1
0
2.1
1.0704
4
2
[1,2.1;4,1]
[0,1.0704;2,0]
-2.6
not allowed!
Limitations
X and Y must have the same size. X or the elements of X must be larger than zero.
20-sim 4.6 Reference Manual
140
7. Language Reference
resint
Syntax
y = resint(x,newoutp,reset,init);
Description
Returns the integral of x with respect to the time. The initial value of y is equal to the
value of init. The output of this integral is reset to the value of newoutp when the
Boolean argument reset is TRUE.
Examples
x = 1;
reset = event(sin(time));
y = resint(x,0,reset,0);
or
x = 1;
reset = if y > 10 then true else false end;
y = resint(x,0,reset,0);
round
Syntax
Y = round(X);
Description
Rounds X or the elements of X to the nearest integer.
Examples
X
1
round(X)
1
2.1
2
-2.6
-3
3.7
4
[1.1,-2.7;3.5,-4.1]
[1,-3;4,-4]
Limitations
X and Y must have the same size.
20-sim 4.6 Reference Manual
141
7. Language Reference
sign
Syntax
Y = sign(X);
Description
Returns the sign of X or the elements of X.
X = < 0 : Y = -1
X = 0: Y = 0
X > 0: Y = 1
Examples
X
1
sign(X)
1
2.1
1
-2.6
-1
0
0
[1,2.1;-2.6,0]
[1,1;-1,0]
Limitations
X and Y must have the same size.
square
Syntax
Y = sqr(X);
Description
Returns the square of X or the elements of X.
Examples
X
sqr(X)
1
1 (= 12 )
2.1
4.41 (= 2.12 )
-2.6
6.76 (= -2.62 )
0
0 (= 02 )
[1,2.1;-2.6,0]
[1,4.41;6.76,0]
( = [12,2.12;-2.62,02] )
20-sim 4.6 Reference Manual
142
7. Language Reference
Limitations
x and y must be scalars.
sqrt
Syntax
X = sqrt(Y);
Description
Returns the square root of X or the elements of X.
Examples
X
sqrt(X)
1
1
2.1
1.44913
4
2
[1,2.1;4,1]
[1,1.44913;2,1]
-1
not allowed!
Limitations
X and Y must have the same size. X or the elements of X must be larger than or equal
to zero.
tdelay
Syntax
y = tdelay(x,delaytime);
Description
Returns the (continuous) signal x delayed for an absolute time (given by delaytime). The
initial value of y for time = 0 to delaytime is equal to zero. This block is intended to
model a continuous delay in a continuous simulation. Use the Unit Delay block to model
a digital delay.
Examples
x = 10*sin(time*10);
y = tdelay(x,2);
Limitations
x,y and delaytime must be scalars. delaytime must be a positive constant value.
20-sim 4.6 Reference Manual
143
7. Language Reference
trunc
Syntax
Y = trunc(X);
Description
Rounds X or the elements of X towards zero (i.e. the function trunc removes the
fraction).
Examples
X
trunc(X)
1
1
2.1
2
-2.6
-2
3.4
3
[1.1,-2.7;3.5,-4.1]
[1,-2;3,-4]
Limitations
X and Y must have the same size.
7.4.3
Discrete
hold
Syntax
y = hold(x,init);
Description
The hold function implements a zero order hold function operating at a specified
sampling rate. It provides a mechanism for creating a continuous output signal y out of a
discrete input signal x. The initial value of y is equal to the value of init.
20-sim 4.6 Reference Manual
144
7. Language Reference
Examples
x = sin(time*0.3);
y = sample(x);
z = previous(y);
u = hold(z,-1);
Limitations
x and y must be scalars. x be a discrete signal. y is a continuous signal. 20-sim will
automatically detect the existence of discrete signals. Each chain of discrete signals will
be assigned a specific sampletime. You can set this sample time to any desired value in
the Simulator (choose Properties, Simulation and Discrete System).
next
Syntax
y = next(x,init);
Description
The next function allows you to make constructs like:
x(k+1) = x(k) - 0.1 + u(k)
where k is the k th sample. Using the next function, this can be entered in 20-sim as:
next(x,0) = x - 0.1 + u;
Limitations
x and y will become discrete signals. 20-sim will automatically detect the existence of
discrete signals. Each chain of discrete signals will be assigned a specific sample time.
You can set this sample time to any desired value in the Simulator (choose Properties,
Simulation and Discrete System).
20-sim 4.6 Reference Manual
145
7. Language Reference
previous
Syntax
y = previous(x,init);
Description
The previous function delays the input signal x and holds it for one sample interval. It is
equivalent to the z-1 discrete time operator.
The init argument is the first value for y at t=0 {s}.
Examples
x = sin(time*0.3);
y = sample(x);
z = previous(y);
u = hold(z);
Limitations
x and y will become discrete signals. 20-sim will automatically detect the existence of
discrete signals. Each chain of discrete signals will be assigned a specific sample time.
You can set this sample time to any desired value in the Simulator (choose Properties,
Simulation and Discrete System).
sample
Syntax
y = sample(x,init);
Description
20-sim 4.6 Reference Manual
146
7. Language Reference
The sample function implements a sample and hold function operating at a specified
sampling rate. It provides a mechanism for discretizing a continuous input signal. The
initial value of y is equal to the value of init. This initial value is optional. If no value is
entered, a default initial value of 0 is used.
Examples
x = sin(time*0.3);
y = sample(x);
z = previous(y);
u = hold(z);
Limitations
x and y must be scalars. x represents a continuous signal and y represents a
discrete signal.
y will become a discrete signals. 20-sim will automatically detect the existence of
discrete signals. Each chain of discrete signals will be assigned a specific sample
time. You can set this sample time to any desired value in the Simulator (choose
Properties, Simulation and Discrete System).
20-sim 4.6 Reference Manual
147
7. Language Reference
7.4.4
Event
event
Syntax
y = event(x);
Description
y becomes true when x is zero. This function forces the integration algorithm to find the
exact point where the input crosses zero. This is called a state event.
Examples
x = sin(time*omega +phi);
y = event(x);
Limitations
y must be a boolean, x must be an expression yielding a scalar.
eventdown
Syntax
y = eventdown(x);
Description
y becomes true when x is zero. This function forces the integration algorithm to find the
exact point where the input crosses zero from a positive to a negative value. This is
called a state event.
Examples
x = sin(time*omega +phi);
y = eventdown(x);
Limitations
y must be a boolean, x must be an expression yielding a scalar.
eventup
Syntax
y = event(x);
Description
y becomes true when x is zero. This function forces the integration algorithm to find the
exact point where the input crosses zero from a negative to a positive value. This is
called a state event.
20-sim 4.6 Reference Manual
148
7. Language Reference
Examples
x = sin(time*omega +phi);
y = eventup(x);
Limitations
y must be a boolean, x must be an expression yielding a scalar.
frequencyevent
Syntax
y = frequencyevent(p,o);
Description
y becomes true every time when p [s] have passed. The function starts after an offset
of o [s]. The offset parameter is optional. This function is a time event function.
Examples
parameters
real period = 0.1 {s};
real offset = 0.005 {s};
variables
boolean y,z;
equations
y = frequencyevent(1);
z = frequencyevent(period,offset);
etc.
// y = true every second
// z = true at 0.005 s, 0.105 s, 0.205 s
Limitations
y must be a boolean, p and o must be a parameter or a constant.
timeevent
Syntax
y = timeevent(x);
Description
y becomes true when time is equal to x. This functions forces the integration algorithm
to do a calculation when time y becomes true. This is a time event function.
Examples
The example code below forces the integration algorithm, to do a calculation at the start
of the step:
x = step(start_time);
y = timeevent(start_time);
Limitations
y must be a boolean, x must be an expression yielding a scalar.
20-sim 4.6 Reference Manual
149
7. Language Reference
7.4.5
Expansion
equal
Syntax
equal([x1,x2, ...,xn]);
Description
This function is used to make all elements of a matrix equal. It returns the equations x2
= x1, x3 = x1, .. , xn = x1. During processing the equations will be automatically
reshaped into a proper causal form. This function is created for use in library models
that use a matrix with unknown size which results from the collect function.
Examples
Suppose we have m bonds connected to a submodel, collected in a port p. We could
then use the function:
collect(p.e);
During processing this equation will be expanded as:
[p.e1;p.e2;...;p.n];
If we use the equal function:
equal(collect(p.e));
this results in:
equal([p.e1;p.e2;...;p.n]);
which will be expanded in:
p.e2 = p.e1;
p.e3 = p.e1;
..
p.en = p.e1
Limitations
This function is designed for a special class of models and should be used by
experienced users only!
20-sim 4.6 Reference Manual
150
7. Language Reference
mul
Syntax
y = mul([x1,x2, ...,xn]);
Description
This function is used for multiplication of variables of which one may be unknown. It
returns the equation y = x1 * x2 * .. * xn. During processing this equation will be
automatically reshaped into a causal form.
This function is created for use in library models that have unknown inputs such as
MultiplyDivide model. Try to avoid the use of this function!
Examples
equations
x1 = 1;
after reshaping (processing)
x1 = 1;
x2 = 2;
x2 = 2;
1 = mul([x1,x2,x3]);
x3 = (1/x1)/x2;
y = sin(time);
y = sin(time);
x2 = 2;
x2 = 2;
y = mul([x1,x2]);
x1 = y/x2;
Limitations
This function is designed for a special class of models and should be used by
experienced users only! y, x1, x2, ..,xn must be scalars. n may be 1 or higher1
sum
Syntax
y = sum([x1,x2, ...,xn]);
Description
This function is used for summation of variables of which one may be unknown. It
returns the equation y = x1 + x2 + .. xn. During processing this equation will be
automatically reshaped into a causal form.
This function is created for use in library models that have unknown inputs such as
PlusMinus model. Try to avoid the use of this function!
Examples
equations
x1 = 1;
after reshaping (processing)
x1 = 1;
x2 = 2;
x2 = 2;
0 = sum(x1,x2,x3);
x3 = x1 + x2;
20-sim 4.6 Reference Manual
151
7. Language Reference
y = sin(time);
y = sin(time);
x2 = 2;
x2 = 2;
y = sum(x1,x2);
x1 = y - x2;
Limitations
This function is designed for a special class of models and should be used by
experienced users only! y, x1, x2, ..,xn must be scalars. n may be 1 or higher.
Use the function msum if you want to use a standard summation of multiple
variables.
7.4.6
External
data
Syntax
y = data(filename,column);
Description
This function generates an output by linear interpolation of data read from file. The data
on file is stored in columns. The first column contains the time values (t) and the second
column contains the corresponding output values (y).
The time data of the first column needs to be monotonically increasing.
Discontinuities are allowed, by providing the same time point twice in the table.
Values outside of the range, are computed by linear extrapolation of the last two
points.
The first argument (filename) of this function must be a parameter of the type string and
is used as a reference to a filename. This reference can be specified using the complete
path or relative to the model directory. The second argument (column) of this function
must be a parameter of the type integer denoting a whole number. It is used to denote
the column number.
table
(example):
0
-0.5
0.5
-1
2.5
-1
3.5
0
4.5
1
5.5
1.75
7
2.5
20-sim 4.6 Reference Manual
152
7. Language Reference
8
2.5
The input file must be an ASC II (text) file or a C omma Separated Values (.csv) file and
should consist at least two columns of data. The first column (number 0) should always
contain the time values. The other columns (number 1, 2, 3, etc.) should contain the
corresponding data values. The parameter column is used to specify which column is
used for as output data.
The various values must be separated by a space, a tab or a comma. Each new set of
time and data values must start on a new line. No comment or other text may be part of
the file. The filename of the input file can be specified using the complete path (e.g. c:
\data\data.tbl). When no path is given, the file is assumed to be in the same
directory as your model.
The first row may contain names for the columns. Names should be indicated by
quotation marks (").
Example
parameters
string filename = 'data.txt';
integer col = 2;
variables
real y;
equations
y = data(filename,col);
Example data.txt file with header:
"time","x","y"
0.0, 1, 2
0.1, 5, 10
0.2, 6, 11
Limitations
y must be a scalar. from_file must be string parameter. x must be an integer parameter.
dll
Syntax
Y = dll(filename,functionname,X);
Description
Given a function (functionname) of a dll (filename), the dll function returns the output
values (X) for a given input (Y).
Users can write their own source code using a native compiler such as Visual C ++ or
Borland C ++. With these compilers it is possible to create DLL’s with user defined
functions that have an input- output relation which can be embedded in simulation code.
20-sim 4.6 Reference Manual
153
7. Language Reference
Examples
parameters
string filename = 'example.dll';
string function = 'myFunction';
variables
real x[2],y[2];
equations
x = [ramp(1);ramp(2)];
y = dll(filename,function,x);
Limitations
filename and functionname must be string parameters. Note that the size of Y and X
(scalars or matrices) must correspond with the size that is expected for the given dllfunction.
Search Order
20-sim uses the following search order for the dll-file:
1.
The bin directory of 20-sim (usually C :\Program Files\20-sim 4.6\bin).
2.
The current directory.
3.
The Windows system directory.
4.
The Windows directory.
5.
The directories that are listed in the PATH environment variable.
The simplest place to put the dll-file is the bin directory, but it is always possible to give
a complete path for the dll filename.
Code generation notice
20-sim allows for code generation of the 20-sim model. In case of a DLL call, 20-sim
cannot generate the complete code for a DLL call since it only knows the DLL file name,
function name and arguments and not the internal DLL code.
Therefore, in the generated code, the dll(dll_name, function_name, in) will be generated
as:
%dll_name%_%function_name%(double *inarr, int inputs, double *outarr, int outputs,
int major)
Where %dll_name% and %function_name% are replaced with the actual DLL and
function name. You have to add the C -code implementation of this function yourself to
the generated code before you can compile it.
20-sim 4.6 Reference Manual
154
7. Language Reference
Writing Static DLL's
Almost every compiler that can build Windows applications, can also build dll-files
containing dll-functions. For two compilers an example will be given how to build the
static dll's (i.e. dll functions that do not contain internal model states) in combination
with 20-sim. The two compilers are: Visual C ++ and Borland C ++ .
When the simulator has to call the user defined dll for the first time the dll is linked and
the appropriate function is called. At the end of the simulation run the dll will be
disconnected from the simulator. In general the dll-function called by the simulator has
the following syntax in 20-sim:
Y = dll(filename,functionname,X);
For example (equation model):
parameters
string dll_name = 'example.dll';
string function_name = 'myFunction';
variables
real in[2],out[2];
equations
in = [ramp(1),ramp(2)];
out = dll(dll_name, function_name, in);
The name of the function is the actual name which was given to the corresponding string
parameter. The return value of the function determines whether the function was
successful or not. A return value of 0 means success, every other value error. When a
nonzero value is returned the simulation stops after finishing its current simulation step.
The parameters given to the function correspond directly to the 20-sim parameters:
double pointers for the inputs and outputs point to an array of doubles.
Function arguments
The user-function in the dll must have certain arguments. The function prototype is like
this:
int myFunction(double *inarr, int inputs, double *outarr, int outputs,
int major)
where
inarr: pointer to an input array of doubles. The size of this array is given by
the second argument.
inputs: size of the input array of doubles.
outarr: pointer to an output array of doubles. The size of this array is given by
the fourth argument.
outputs: size of the output array of doubles.
20-sim 4.6 Reference Manual
155
7. Language Reference
major: boolean which is 1 if the integration method is performing a major
integration step, and 0 in the other cases. For example Runge-Kutta 4
method only has one in four model evaluations a major step.
Initializing the DLL-file
When the dll is linked to the simulator it is often useful to perform some initializations.
There are several ways to perform these initializations.
Method 1
When the simulator has attached the dll-file it automatically searches for a function with
the name ‘int Initialize()’. If this function is found it is called. The return value is checked
for success, 1 means success, 0 means error. At the end of the simulation run just
before the dll-file is detached the simulator searches for a function called ‘int
Terminate()’. In this function the necessary termination action can be performed like
cleaning up allocated memory.
At the start of every run the simulator also searches a function with the name 'int
InitializeRun()'. If it is found it is called the same way the Initialize function was called.
At the end the same happens with the function 'int TerminateRun()'. This is very useful in
multiple run simulations, in this case the dll-file is linked only once with the simulator,
and only once the Initialize and Terminate functions are called. But for every subsequent
run the InitializeRun and TerminateRun functions are called so every run can be
initialized and terminated gracefully. In this case in the Terminate function collection of
multiple run data could be collected and saved for example.
So suppose you have a multiple run with 2 runs, the following functions (if they exist)
will be called in the dll-file in this order:
Initialize()
InitializeRun()
TerminateRun()
Terminate()
Method 2
Using the DLLEntryPoint function. This function is automatically called when the library is
linked or detached. Both in Visual C ++ and in Borland C ++ this function has the same
syntax. However when using visual C ++ as the compiler, our simulator which is build
with Visual C ++ does not seem to be able to call this function. So the framework as
given below only works with a Borland C ++ dll.
// Every dll has an entry point LibMain || DllEntryPoint
// and an exit point WEP (windows exit point).
BOOL WINAPI DllEntryPoint(HINSTANCE hinstDll, DWORD fdwRreason, LPVOID
plvReserved)
{
if (fdwRreason == DLL_PROCESS_ATTACH)
{
return 1; // Indicate that the dll was linked successfully.
}
if (fdwRreason == DLL_PROCESS_DETACH)
20-sim 4.6 Reference Manual
156
7. Language Reference
{
return 1; // Indicate that the dll was detached successfully.
}
return 0;
}
Method 3
When using an object oriented language it is possible to have a global variable which is
an instance of a class. When linking the dll-file to the simulator the constructor function
of this global variable will be called automatically. In this constructor the initialization can
be performed. When the dll-file is detached the destructor of the global variable is
called. Some care should be taken with this method of terminating. E.g. if the user is
asked for a filename using a FileDialog this sometimes causes the complete application
to crash. The reason for this is that some of the dll-files contents was already destructed
and that some functionality may not work anymore resulting in an application error. The
solution for this problem is tot use method 1 of initialization and destruction.
Frame work for a Visual C++ dll-file implementation.
#include <windows.h>
#define DllExport __declspec( dllexport )
extern "C"
{
DllExport int myFunction(double *inarr, int inputs, double *outarr,
int outputs, int major)
{
...
// function body
return 0; // return successful
}
DllExport int Initialize()
{
...
// do some initializations here.
return 0; // Indicate that the dll was initialized successfully.
}
DllExport int Terminate()
{
...
// do some cleaning here
return 0; // Indicate that the dll was terminated successfully.
}
}
Frame work for a Borland C++ dll-file implementation.
#include <windows.h>
extern "C"
{
int _export myFunction(double *inarr, int inputs, double *outarr, int
outputs, int major)
{
...
// function body
return 0; // return successful
}
int _export Initialize()
20-sim 4.6 Reference Manual
157
7. Language Reference
{
...
// do some initializations here.
return 0; // Indicate that the dll was initialized successfully.
}
int _export Terminate()
{
...
// do some cleaning here
return 0; // Indicate that the dll was terminated successfully.
}
}
// Every dll has an entry point LibMain || DllEntryPoint
// and an exit point WEP.
BOOL WINAPI DllEntryPoint(HINSTANCE hinstDll, DWORD fdwRreason, LPVOID
plvReserved)
{
if (fdwRreason == DLL_PROCESS_ATTACH)
{
...
// do some initializations here.
return 1; // Indicate that the dll was initialized successfully.
}
if (fdwRreason == DLL_PROCESS_DETACH)
{
...
// do some cleaning here
return 1; // Indicate that the dll was initialized successfully.
}
return 0;
}
Note
Make sure that Borland C ++ does not generate underscores in front of the exported
function names! This can probably be found in the compiler settings.
Working example
Here is a complete working example of how to use a dll-function from within the
simulator. This code will compile with Visual C ++ or gcc. See the Borland C ++
framework how to write this code in Borland C ++.
/* Example C++ DLL for 20-sim */
#include <windows.h>
#include <math.h>
#include <fstream>
#include <stdio.h>
#define DLLEXPORT __declspec( dllexport )
using namespace std;
ofstream outputStream;
20-sim 4.6 Reference Manual
158
7. Language Reference
#ifdef _MSC_VER
#define snprintf _snprintf
#endif
extern "C"
{
char g_lasterrormessage[255]; /* Used to store a DLL error message
for transfer to 20-sim */
const char* g_modelpath;
/**
* This is an example of a function that can be called in your 20-sim
* model using the dll() Sidops call
*
* @param inarr
This double array contains all inputs that will be
*
send from 20-sim to the other side
* @param inputs 20-sim tells the dll how many elements inarr[]
*
contains.
* @param outarr Result from this dll function that will be returned
*
to 20-sim
* @param outputs 20-sim tells the dll how many elements it expects
*
(and allocated) in outarr.
* @param major
1=major integration step, 0=minor step (e.g. an
*
intermediate integration method step in Runge Kutta
*
4)
**/
DLLEXPORT int myFunction(double *inarr, int inputs, double *outarr,
int outputs, int major)
{
// Check the sizes of our input and output arrays
if (inputs != outputs)
{
snprintf(g_lasterrormessage, 255, "%s: expects that the number of
inputs is equal to the number of outputs.", __FUNCTION__);
return 0; // Failure
}
for (int i = 0; i < inputs; i++)
{
outarr[i] = cos(inarr[i]);
outputStream << inarr[i] << " " << outarr[i] << " ";
}
outputStream << endl;
return 1; // Success
}
/****** Initialization and cleanup ******/
/* Note 1:
*
The Initialize(), InitializeRun(), Terminate() and TerminateRun()
20-sim 4.6 Reference Manual
159
7. Language Reference
*
functions are optional.
*
Implement them when you need to initialize something before the
*
actual experiment is started and to cleanup/reset your DLL
*
functionality for a next run.
* Note 2:
*
When these functions are implemented, the "continue run"
*
functionality in 20-sim is disabled.
*/
/**
* Initialize() [optional]
*
* This function is called by the 20-sim simulator BEFORE starting the
* simulation experiment (and only once in a multiple run experiment)
* to initialize the dll properly.
*/
DLLEXPORT int Initialize()
{
outputStream.open("c:\\temp\\data.log");
return 0; // Indicate that the dll was initialized successfully.
}
/**
* InitializeRun() [optional]
*
* This function is called by the 20-sim simulator BEFORE starting the
* simulation experiment (and only once in a multiple run experiment)
* to initialize the dll properly.
*/
DLLEXPORT int InitializeRun()
{
/* Clear lasterrormessage before every run. */
snprintf(g_lasterrormessage, 255, "");
return 0; /* Indicate that the dll was initialized successfully. */
}
/**
* TerminateRun() [optional]
*
* This function is called by 20-sim after each finished run
*/
DLLEXPORT int TerminateRun()
{
/* Cleanup / reset your DLL here for the next run
* (e.g. in a multiple run experiment)
*/
return 0; // Indicate that the dll was terminated successfully.
}
/**
20-sim 4.6 Reference Manual
160
7. Language Reference
* Terminate() [optional]
*
* This function is called by 20-sim on a DLL unload
*/
DLLEXPORT int Terminate()
{
outputStream.close();
return 0; // Indicate that the DLL was terminated successfully.
}
/**
* LastErrorMessage() [optional]
* Used by 20-sim to fetch a string with the last error that occurred
* within the DLL
* @return A char pointer to a string indicating the error message
*/
DLLEXPORT char* LastErrorMessage()
{
return g_lasterrormessage;
}
/**
* RegisterModelPath() [optional]
* This function is called by 20-sim before Initialize() to learn the
* DLL where the model is located. It can be used e.g. to find data
* files stored in the same folder as the model.
*
* @param modelPath char pointer to the model directory
* @return 0 if parameter is set successfully, 1 if not successful.
*/
DLLEXPORT int RegisterModelPath(const char * modelPath)
{
g_modelpath = modelPath;
}
}
Usage within 20-sim
Suppose the dll has been created as "example.dll". With the following code this model
can be tested:
parameters
string dll_name = 'example.dll';
string function_name = 'myFunction';
variables
real in[2],out[2];
equations
in = [ramp(1),ramp(2)];
out = dll(dll_name, function_name, in);
20-sim 4.6 Reference Manual
161
7. Language Reference
Note that the general function "dll" is used. The arguments of this function, dll_name and
function_name, are parameters which are used to denote the dll that should be used and
the function of that dll that should be called. You can load this model from the
Demonstration Models Library:
1. Open the Editor.
2. From the demo library open the model DllFunction.emx (choose File and
Open)
3. Start the simulator (Model menu and Start Simulator).
4. Start a simulation run (select Run from the Simulation menu).
Code generation notice
20-sim allows for code generation of the 20-sim model. In case of a DLL call 20-sim
cannot generate the complete code for a DLL call since it only knows the DLL file name,
function name and arguments and not the internal DLL code.
Therefore, in the generated code, the dll(dll_name, function_name, in) will be generated
as:
%dll_name%_%function_name % (double *inarr, int inputs, double *outarr,
int outputs, int major)
Where %dll_name% and %function_name% are replaced with the actual DLL and
function name. You have to add the C -code implementation of this function yourself to
the generated code before you can compile it.
dlldynamic
Syntax
Y = dlldynamic(filename,functionname,X);
Description
Given a function (functionname) of a dll (filename), the dll function returns the output
values (X) for a given input (Y).
Users can write their own source code using a native compiler such as Visual C ++ or
Borland C ++. With these compilers it is possible to create DLL’s with user defined
functions that have an input- output relation which can be embedded in simulation code.
20-sim 4.6 Reference Manual
162
7. Language Reference
Examples
parameters
string dllName = 'demoDynamicDll.dll';
string functionName = 'SFunctionCalculate';
variables
real x[2],y[2];
equations
x = [ramp(1);ramp(2)];
y = dlldynamic(dllName,functionName,x);
Limitations
The filename and functionname must be string parameters. Note that the size of Y and X
(scalars or matrices) must correspond with the size that is expected for the given dllfunction.
Search Order
20-sim uses the following search order for the dll-file:
1.
The bin directory of 20-sim (usually C :\Program Files\20-sim 4.6\bin).
2.
The current directory.
3.
The Windows system directory.
4.
The Windows directory.
5.
The directories that are listed in the PATH environment variable.
The simplest place to put the dlldynamic-file is the bin directory, but it is always possible
to give a complete path for the dll filename.
Writing Dynamic DLL's
Almost every compiler that can build Windows applications, can also build dll-files
containing dll-functions. For the Visual C ++ compiler an example will be given how to
build the dynamic dll's (i.e. dll functions that may contain internal model states) in
combination with 20-sim.
The functions in the DLL are called in a specific sequence. For communication with the
functions and the Simulator Kernel information is passed in a structure. This structure
looks like this:
20-sim 4.6 Reference Manual
163
7. Language Reference
struct SimulatorSFunctionStruct
{
double versionNumber;
int nrInputs;
int nrOutputs;
int nrIndepStates;
int nrDepStates;
int nrAlgLoops;
double simulationStartTime;
double simulationFinishTime;
double simulationCurrentTime;
BOOL major;
BOOL initialOutputCalculation;
};
1. Initialize
At the start of the simulation the function
int Initialize()
is called. When this function is not present it is not called. Any initializations of data
structures can be performed here.
2. SFunctionInit
During initialization of the Simulator Kernel the function
int SFunctionInit(SimulatorSFunctionStruct *s)
is called. Return value is 0 means error. every other value succes Argument is a pointer
to the simstructure. On initialization the following fields should be filed in:
nrIndepStates
nrDepStates
nrAlgLoop
The following fields already have valid values:
simulationStartTime
giving the start time of the simulation
simulationFinishTime
giving the finish time of the simulation
simulationCurrentTime
giving the current time (actually the start time at
the moment of initialization)
3. Initial values for the states:
20-sim 4.6 Reference Manual
164
7. Language Reference
int SFunctionGetInitialStates(double *initialIndepStates,
double *initialDepRates,
double *initialAlgloopIn,
SimulatorSFunctionStruct *simStruct);
Return value is 0 means error. every other value succes. The initial value for the
independent states, dependent rates and algebraic loop variables can be specified by the
DLL in this function. It is just called before the initial output calculation function in step 3.
If all the initial values are zero, nothing has to be specified.
4. Initial Output Calculation
It is possible that the DLL-function can give an initial output. A separate function is called
so that the DLL can calculate it's initial output values. The
boolean
initialOutputC alculation in the simulatorSFunction structure is used. Just the sFunction is
called. as in point 5.
5. SFunction calling:
Here all the fields of the SimulatorSFunctionStruct are input for the function. The
inputArray, stateArray, outputArray and rateArray are always given as arguments of the
function. Dependent on the number of dependent states and algebraic loop variables
more arguments can be given as shown in the functions below (sFunctionName is the
name defined by the parameter name specified by the user):
Return value is 0 means error. every other value succes
case: no dependent states, no algebraic loop variables
int sFunctionName(double *inputArray,
double *stateArray,
double *outputArray,
double *rateArray,
SimulatorSFunctionStruct *simStruct);
case: dependent states, no algebraic loop variables
int sFunctionName(double *inputArray,
double *stateArray,
double *dependentRateArray,
double *outputArray,
double *rateArray,
double *dependentStateArray,
SimulatorSFunctionStruct *simStruct);
case: no dependent states, algebraic loop variables
int sFunctionName(double *inputArray,
double *stateArray,
double *algLoopInArray,
double *outputArray,
20-sim 4.6 Reference Manual
165
7. Language Reference
double *rateArray,
double *algLoopOutrray,
SimulatorSFunctionStruct *simStruct);
case: dependent states, algebraic loop variables
int sFunctionName(double *inputArray,
double *stateArray,
double *dependentRateArray,
double *algLoopInArray,
double *outputArray,
double *rateArray,
double *dependentStateArray,
double *algLoopOutrray,
SimulatorSFunctionStruct *simStruct);
the boolean major in the SimulatorSFunctionStruct determines whether the evaluation of
the model is done at the time output is generated (major == TRUE ) or that the model is
evaluated because of determining model characteristics. For example Runge-Kutta4
integration method uses three minor steps before taking a major step where output is
generated. Higher order methods can have different number of minor steps before a
major step is taken.
6. Termination
At the end of the simulation the function:
int Terminate()
is called. When this function is not present it is not called. Any terminations of data
structures can be performed here.
Frame work for a Visual C ++ dll-file implementation.
#include <windows.h>
#define DllExport __declspec( dllexport )
extern "C"
{
DllExport int dllfunction(double *inarr, int inputs, double *outarr, int outputs, int major)
{
... // function body
return 0; // return succesfull
}
DllExport int Initialize()
{
... // do some initializations here.
return 0; // Indicate that the dll was initialized successfully.
20-sim 4.6 Reference Manual
166
7. Language Reference
}
DllExport int Terminate()
{
... // do some cleaning here
return 0; // Indicate that the dll was terminated successfully.
}
}
Frame work for a Borland C ++ dll-file implementation.
#include <windows.h>
extern "C"
{
int _export dllfunction(double *inarr, int inputs, double *outarr, int outputs, int major)
{
... // function body
return 0; // return succesfull
}
int _export Initialize()
{
... // do some initializations here.
return 0; // Indicate that the dll was initialized successfully.
}
int _export Terminate()
{
... // do some cleaning here
return 0; // Indicate that the dll was terminated successfully.
}
}
// Every dll has an entry point LibMain || DllEntryPoint
// and an exit point WEP.
BOOL
WINAPI
DllEntryPoint(
HINSTANCE
hinstDll,DWORD
plvReserved)
{
if( fdwRreason == DLL_PROCESS_ATTACH )
{
... // do some initializations here.
return 1; // Indicate that the dll was initialized successfully.
}
if( fdwRreason == DLL_PROCESS_DETACH )
{
... // do some cleaning here
return 1; // Indicate that the dll was initialized successfully.
20-sim 4.6 Reference Manual
fdwRreason,LPVOID
167
7. Language Reference
}
return 0;
}
Working example
Here is a complete working example of how to use a dll-function from within the
simulator. This code will compile with Visual C ++. See the Borland C ++ framework how
to write this code in Borland C ++.
#include <windows.h>
#include "SimulatorSFunctionStruct.h"
/
************************************************************************
*******
* in this source file we are gonna describe a linear system which is defined by
* the following transfer function description:
34
Y = ---------------- * U
s^2 + 6s + 34
or A, B, C, D system:
A = [ 0, -3.4;
10, -6];
B = [ -3.4;
0];
C = [0, -1];
D=0
which has two poles on (-3 + 5i) and (-3 -5i)
steady state = 1
***********************************************************************
*******/
#define DllExport __declspec( dllexport )
extern "C"
{
// called at begin of the simulation run
DllExport int Initialize()
20-sim 4.6 Reference Manual
168
7. Language Reference
{
// you can perform your own initialization here.
// success
return 0;
}
// called at end of the simulation run
DllExport int Terminate()
{
// do some cleaning here
// success
return 0;
}
DllExport int SFunctionInit (SimulatorSFunctionStruct *s)
{
// tell our caller what kind of dll we are
s->nrIndepStates = 2;
s->nrDepStates = 0;
s->nrAlgLoops = 0;
// dubious information, since 20-sim itself does not check and need this info
s->nrInputs = 1;
s->nrOutputs = 1;
// return 1, which means TRUE
return 1;
}
DllExport int SFunctionGetInitialStates (double *x0, double *xd0, double *xa0,
SimulatorSFunctionStruct *s)
{
// fill in the x0 array here. Since we specified no Dependent states, and No algebraic
loop variables
// the xd0 and xa0 may not be used.
// initial value is zero.
x0[0] = 0;
x0[1] = 0;
// return 1, which means TRUE
return 1;
20-sim 4.6 Reference Manual
169
7. Language Reference
}
DllExport int SFunctionCalculate(double *u, double *x, double *y, double *dx,
SimulatorSFunctionStruct *s)
{
// we could check the SimulatorSFunctionStruct here if we are in an initialization state
and/or we are
// in a major integration step.
#if 0
if( s->initialialOutputCalculation )
; // do something
// possibly do some explicit action when we are in a major step.
if( s->major == TRUE )
; // do something
#endif
dx[0] = -3.4 * x[1] -3.4 * u[0];
dx[1] = 10 * x[0] -6 * x[1];
y[0] = -x[1];
// return 1, which means TRUE
return 1;
}
}// extern "C"
BOOL APIENTRY DllMain( HANDLE hModule,
DWORD ul_reason_for_call,
LPVOID lpReserved
)
{
return TRUE;
}
Use within 20-sim
Suppose the dll has been created as "demoDynamicDll.dll". With the following code this
model can be tested:
parameters
string dllName = 'demoDynamicDll.dll';
string functionName = 'SFunctionCalculate';
equations
output = dlldynamic (dllName, functionName, input);
20-sim 4.6 Reference Manual
170
7. Language Reference
Note that the general function "dlldynamic" is used. The arguments of this function,
dllName and functionName, are parameters which are used to denote the dll that should
be used and the function of that dll that should be called. You can load this model from
the Demonstration Models Library:
1. O pen the Editor.
2. From the demo library open the model DllFunction.emx (choose File and
Open)
3. Start the simulator (Model menu and Start Simulator).
4. Start a simulation run (select Run from the Simulation menu).
table
Syntax
y = table(file_name,x);
Description
This model uses a one-dimensional table with data points to calculate the output y = f(x)
as a function of the input x. The output y is calculated using linear interpolation between
the table data points.
The input data x of the first column needs to be monotonically increasing.
Discontinuities are allowed, by providing the same input point twice in the table.
Values outside of the table range, are computed by linear extrapolation of the last
two points.
The first argument (file_name) of this function must be a parameter of the type string
and is used as a reference to a filename. This reference can be specified using the
complete path or relative to the model directory. The second argument (x) should be a
real variable.
table
(example):
-2.5
-0.5
-2
-1
0
-1
1
0
2
2
3
3.0
5
4
6
4.0
20-sim 4.6 Reference Manual
171
7. Language Reference
A table must be stored as an ASC II (text) file or a C omma Separated Values (.csv) file
and should consist two columns of data. The first column consists of the x-values and the
second column of the corresponding y-values. Each line of the file may only contain one
x- and one corresponding y-value. The two values must be separated by a space or a
tab. Each new set of x- and y-values must start on a new line. No comment or other text
may be part of the table-file.
Example
parameters
string filename = 'data.txt';
variables
real y;
real x;
equations
x = ramp(1);
y = table(filename,x);
Example data.txt format:
-2.5, -0.5
-2.0, -1.0
0.0, -1.0
1.0, 0.0
2.0, 2.0
3.0, 3.0
5.0, 4.0
6.0, 4.0
Limitations
x and y must be scalars. from_file must be string parameter.
7.4.7
Matrix
adjoint
Syntax
Y = adjoint(T);
Y = adjoint(W,V);
Description
Returns the adjoint matrix [6,6] of a twist or wrench vector T [6,1]:
20-sim 4.6 Reference Manual
172
7. Language Reference
or returns the adjoint matrix [6,6] of an angular velocity vector W [3,1] and a velocity
vector V [3,1]:
The adjoint function is useful for dynamics described by twists and wrenches.
Examples
W = [w1 ; w2 ; w3];
V = [v1 ; v2 ; v3];
Y = adjoint(W,V);
Limitations
Y must be of size [6,6], W must always be of size[3,1] , V must have the size [3,1] and
T must have size [6,1].
20-sim 4.6 Reference Manual
173
7. Language Reference
Adjoint
Syntax
A = Adjoint(H);
A = Adjoint(R,P);
Description
Returns the adjoint matrix [6,6] of a homogeneous matrix [4,4]:
or returns the adjoint matrix [6,6] of a rotation matrix R [3,3] and position vector P [3]:
The Adjoint function is useful for dynamics described by twists and wrenches.
Examples
R = [cos(alpha),-sin(alpha),0 ; sin(alpha),cos(alpha),0 ; 0,0,0];
P = [p1 ; p2 ; p3];
A = Adjoint(R,P);
Limitations
H must be of size [4,4], R must always be of size[3,3] , P must have the size [3,1] and A
must have size [6,6].
20-sim 4.6 Reference Manual
174
7. Language Reference
antisym
Syntax
y = antisym(A);
Description
Returns an anti-symmetric matrix. This function is equal to:
y = (A - transpose(A))/2;
Examples
A = [1,2;3,4];
Y = antisym(A);
Limitations
A must be a square matrix. Y and A must be of the same size.
columns
Syntax
y = columns(A);
Description
Returns the number of columns of A.
Examples
A = [1,2;3,4;5,6];
y = columns(A);
Limitations
y must be a scalar.
cross
Syntax
Y = cross(A,B);
Description
This functions returns the vector cross product of the vectors A and B. That is Y = A × B
or:
20-sim 4.6 Reference Manual
175
7. Language Reference
Y[1] = A[2]*B[3] - A[3]*B[2]
Y[2] = A[3]*B[1] - A[1]*B[3]
Y[3] = A[1]*B[2] - A[2]*B[1]
Examples
parameters
real A[3] = [1;2;3];
real B[3] = [4;5;6];
variables
real Y[3];
equations
Y = Cross(A,B); // Y = [-3;6;-3]
Limitations
Y, A and B must be column vectors of size 3.
det
Syntax
y = det(A);
or
Y = |A|;
Description
Returns the determinant of the square matrix A.
Examples
A = [1,2;3,ramp(1)];
y = det(A);
Limitations
A must be a square matrix, y must be a scalar.
diag
Syntax
Y = diag(x);
Description
Fills the diagonal elements of the matrix Y with the elements of the columvector x.
Example
variables
real x[3];
real Y[3,3];
equations
x = [1;2;3];
Y = diag(x);
Limitations
Y must be a matrix of size [n,n]. x must be a column vector of size n.
20-sim 4.6 Reference Manual
176
7. Language Reference
eye
Syntax
Y = eye(n);
Description
Returns the the n-by-n identity matrix.
Example
Y = eye(3);
Limitations
Y must be a matrix of size [n,n]. n must be an integer value.
homogeneous
Syntax
H = homogeneous(R,P);
Description
Returns the homogenous matrix [4,4] of a rotation matrix R[3,3] and position vector
P[3]:
The homogeneous matrix gives a full coordinate transformation from one reference
frame to another. It can be used for 3D dynamics.
Examples
R = [cos(alpha),-sin(alpha),0 ; sin(alpha),cos(alpha),0 ; ; 0,0,0];
P = [p1 ; p2 ; p3];
H = homogeneous(R,P);
Limitations
R must always be of size[3,3] , P must have the size [3,1] and H must have size [4,4].
inner
Syntax
y = inner(A,B);
Description
20-sim 4.6 Reference Manual
177
7. Language Reference
Returns the scalar product of the column vectors A and B. A and B must be vectors of
the same length. Inner(A,B) is the same as transpose(A)*B.
Example
A[3] = [1;2;3];
B[3,1] = [4;5;6];
y = inner(A,B);
Limitations
A and B must be vectors of the same size [n,1] or [n]. y must be a scalar.
inverse
Syntax
Y = inverse(A);
Description
Returns the inverse of square non-singular matrix A.
Examples
A = [1,0;0,1+ramp(1)];
Y = inverse(A);
Limitations
A must be a non-singular square matrix. Y must have the same size as A.
inverseH
Syntax
Y = inverseH(H);
Y = inverseH(R,P);
Description
Returns the inverse of a homogeneous matrix H [4,4]. The homogeneous matrix can be
entered directly or by a rotation matrix R[3,3] and position vector P [3,1].
The size of the inverse Y is also [4,4].
This function uses the special nature of a homogeneous matrix. I.e the inverse can be
computed directly instead of the numerical approach of the standard inverse function.
Examples
H = [cos(alpha),-sin(alpha),0,p1 ; sin(alpha),cos(alpha),0,p2 ; 0,0,0,p3 ; 0,0,0,1];
Y = inverseH(H);
or
R = [cos(alpha),-sin(alpha),0 ; sin(alpha),cos(alpha),0 ; 0,0,0];
P = [p1 ; p2 ; p3];
Y = inverseH(R,P);
Limitations
H must be a homogeneous matrix of size [4,4], R must always be of size[3,3] , P must
have the size [3,1] and Y must have size [4,4].
20-sim 4.6 Reference Manual
178
7. Language Reference
linsolve
Syntax
x = linsolve(A,b [,method]);
Description
This function solves the equation
A*x = b;
Where A is a square matrix of arbitrary size n and x and b are vectors of size n.
Returns the inverse of square non-singular matrix A.
The last argument is a string that specifies the desired method to use.
method
description
lu
LU decomposition (default method)
qr
QR factorization
cholesky
C holesky factorization
gmres
Generalized Minimum Residual
The gmres method allows further steering of the method by specifying method
parameters:
method parameter
description
tol
Set the desired tolerance to use
maxiter
Set the maximum number of iterations to use
ortho
Set the method of Gramm-Schmidt orthogonalization:
1
modified Gramm-Schmidt
2
iterative Gramm-Schmidt
3
classical Gramm-Schmidt
4
iterative classical Gramm-Schmidt
The lu, qr and gmres methods allow a non-square matrix A to be entered yielding a
pseudoinverse.
Examples
A = [1,2;0,1+ramp(1)];
b = [1;5];
x = linsolve(A,b);
x2 = linsolve (A, b, 'qr');
x3 = linsolve (A, b, 'gmres tol=1e-8 ortho=4');
Limitations
A must be a non-singular square matrix.
Note
The following equations
A*x = b;
x = inverse(A)*b;
x = (A^-1)*b;
all lead in the calculation of the inverse of A and will give the same result as
20-sim 4.6 Reference Manual
179
7. Language Reference
x = linsolve(A,b);
For the inverse calculation, C ramers rule is used. This is a method which is fast for
small matrix sizes. The linsolve function with the gmres method is superior to C ramers
rule for larger matrix sizes.
max
Syntax
y = max(A);
Description
Returns the value of the largest matrix element of A.
Examples
A = [1,2;3,ramp(1)];
y = max(A);
Limitations
y must be a scalar.
min
Syntax
y = min(A);
Description
Returns the value of the smallest matrix element of A.
Examples
A = [1,2;3,ramp(1)];
y = min(A);
Limitations
y must be a scalar.
msum
Syntax
y = msum(A);
Description
Returns the sum of the matrix elements of A.
Examples
A = [1,2;3,4;5,6];
y = msum(A);
Limitations
y must be a scalar.
20-sim 4.6 Reference Manual
180
7. Language Reference
multiplyH
Syntax
C = multiplyH(A,B);
Description
Returns the multiplication of two homogenous matrices [4,4] or
homogenous matrix [4,4] with one homogeneous position vector [4,1] .
multiplies
one
Examples
parameters
real D[4,4] = [1,0,0,1;
0,1,0,0;
0,0,1,0;
0,0,0,1];
real E[4,4] = [1,0,0,2;
0,1,0,3;
0,0,1,0;
0,0,0,1];
real F[4,1] = [1,1,1,1];
variables
real G[4,4];
real H[4,1];
equations
G = multiplyH(D,E);
H = multiplyH(D,F);
Limitations
When A and B are homogeneous matrices [4,4] then C must be a homogenous matrix
[4,4]. When A is a homogenous matrix [4,4] and B is a homogenous position vector
[4,1] then C must also be a position vector [4,1].
norm
Syntax
y = norm(A);
or
Y = ||A||;
Description
Returns the square root of the sum of the squared matrix elements of A:
20-sim 4.6 Reference Manual
181
7. Language Reference
Examples
A = [1,2;3,ramp(1)];
y = norm(A);
Limitations
y must be a scalar.
norminf
Syntax
y = norminf(A);
Description
Returns the largest row sum of the absolute values of the matrix A:
Examples
A = [1,2;3,ramp(1)];
y = norminf(A);
Limitations
y must be a scalar.
rows
Syntax
y = rows(A);
Description
Returns the number of rows of A.
Examples
A = [1,2;3,4;5,6];
y = rows(A);
Limitations
y must be a scalar.
20-sim 4.6 Reference Manual
182
7. Language Reference
skew
Syntax
Y = skew(X);
Description
Returns the vector product:
Examples
Limitations
X must be a vector of size n. Y must be a matrix of size [n,n].
sym
Syntax
y = sym(A);
Description
Returns a symmetric matrix. This function is equal to:
y = (A + transpose(A))/2;
Examples
A = [1,2;3,4];
Y = sym(A);
Limitations
A must be a square matrix. Y and A must be of the same size.
tilde
Syntax
H = tilde(T);
H = tilde(W,V);
Description
Returns the twist matrix [4,4] of a twist or wrench vector T [6,1]:
20-sim 4.6 Reference Manual
183
7. Language Reference
Or returns the twist matrix [4,4] of an angular velocity vector W [3,1] and a velocity
vector V [3,1]:
The tilde function is useful for dynamics described by twists and wrenches.
Examples
W = [w1 ; w2 ; w3];
V = [v1 ; v2 ; v3];
H = tilde(W,V);
Limitations
H must be of size [4,4], W must always be of size[3,1] , V must have the size [3,1] and
T must have size [6,1].
trace
Syntax
y = trace(A);
Description
Returns the sum of the diagonal elements of the matrix A.
Examples
A = [1,2,3;4,ramp(1),6];
y = trace(A);
Limitations
y must be a scalar.
20-sim 4.6 Reference Manual
184
7. Language Reference
transpose
Syntax
Y = transpose(A);
Description
Returns the transpose of the matrix A.
Examples
A = [1,2;3,ramp(1)];
Y = transpose(A);
Limitations
With the A matrix of size[n,m] , Y must have the size [m,n].
7.4.8
Port
collect
Syntax
y = collect(p.e);
y = collect(p.f);
y = collect(m);
(with p.e and p.f powerportvariables and m a signal)
Description
Some models in 20-sim can have an unknown amount of signals or bonds connected.
They are treated as an array with unknown length.
For example the PlusMinus model can have n signals that must be added and m signals
that must be subtracted. 20-sim treats them as an array plus and an array minus with:
plus = [plus1;plus2;..;plusn] and minus = [minus1;minus2;..;minusm]
To assign an array of unknown length, the collect function is used. It creates an array
with port variables or signals. This function is created for use in library models that have
an unknown amount of bonds or signals connected. Try to avoid the use of this
function!
Examples
Suppose we have m bonds connected to a submodel, collected in a port p. We could
then use the equation:
Y = collect(p.e);
During processing, this equation will be rewritten as:
Y = [p.e1;p.e2;...;p.n];
20-sim 4.6 Reference Manual
185
7. Language Reference
Suppose we have a submodel with n input signals connected. We could then write the
equation:
y = sum(collect(input));
During processing, this equation will be rewritten as:
y = sum([output1;output2;...;outputn]);
which is of course equal to:
y = output1 + output2 + .. + outputn;
Limitations
This function is designed for a special class of models and should be used by
experienced users only! The function is only valid when used in a submodel.
direct
Syntax
y = direct(p.e);
y = direct(p.f);
(with p.e and p.f powerportvariables)
Description
This function is equal to the collect function, but utilizes the direction of the bonds
connected to the submodel to sign the powerportvariables. This function is created
specially for the bond graph submodels OneJunction.emx and ZeroJunction.emx. Try to
avoid the use of this function!
Examples
Suppose we have 4 bonds connected to a 0-junction, collected in a port p. p1 and p4 are
pointing towards the junction and p2 and p3 are pointing from the 0-junction. We could
then use the equation:
Y = direct(p.f);
During processing, this equation will be rewritten as:
Y = [p.f1;-p.f2;-p.f3,p.f4];
Which can of course be used in combination with the sum function:
sum(Y) = 0;
To get the 0-junction equation:
20-sim 4.6 Reference Manual
186
7. Language Reference
p.f1 - p.f2 - p.f3 + p.f4 = 0;
Limitations
This function is designed for a special class of models and should be used by
experienced users only! The function is only valid when used in a submodel.
first
Syntax
y = first(p.e);
y = first(p.f);
y = first(m);
(with p.e and p.f powerportvariables and m a signal)
Description
Some models in 20-sim can have an unknown amount of signals or bonds connected.
They are treated as an array with unknown length. For example the PlusMinus model can
have n signals that must be added and m signals that must be subtracted. 20-sim treats
them as an array plus and an array minus with:
plus = [plus1;plus2;..;plusn] and minus = [minus1;minus2;..;minusm]
The function first returns the value of the first element of an array of unknown length.
This function is created for use in library models that have an unknown amount of bonds
or signals connected. Try to avoid the use of this function!
Examples
Suppose we have m bonds connected to a submodel, collected in a port p. We could
then use the equation:
y = first(p.e);
During processing, this equation will be rewritten as:
y = p.e1;
Limitations
This function is designed for a special class of models and should be used by
experienced users only! The function is only valid when used in a submodel.
20-sim 4.6 Reference Manual
187
7. Language Reference
7.4.9
Source
gauss
Syntax
y = gauss(x,s);
Description
Returns gaussian noise with a variance x and seed s. The seed parameter is
optional. When omitted, the default value (0) is used.
Examples
x = 20;
y = gauss(x);
z = gauss(x,450);
Limitations
x and y must be scalars.The seed s must be a number in the region <0,65535>.
impulse
Syntax
y = impulse(x,w);
Description
Returns a pulse signal with start time x, width w and height 1/w:
time < x: y = 0
time >= x and < x+w: y = 1/w
time >= x+w: y = 0
Note: The integral (i.e the area) of an impulse is always 1. If w is chosen small, the
amplitude of the impulse will be high.
Examples
x = 20, w = 0.01;
y = impulse(x,w);
Limitations
x and w must be scalars, w > 0.
ramp
Syntax
y = ramp(x);
Description
Returns a ramp signal with start time x:
20-sim 4.6 Reference Manual
188
7. Language Reference
time < x: y = 0
time >= x: y is time - x
Examples
x = 20, amplitude = 10;
y = amplitude*ramp(x);
Limitations
x and y must be scalars.
ran
Syntax
y = ran(x,s);
Description
Returns uniformly distributed noise in the interval [-x,x] with seed s. The seed
parameter is optional. When omitted, the default value (0) is used.
Examples
x = 20;
y = ran(x);
z = ran(x,450);
Limitations
x and y must be scalars. The seed s must be a number in the region <0,65000>.
Random Seed
20-sim generates a sequence of random numbers for each simulation differently
depending upon the value of the seed parameter. The random noise function and
gaussian noise function are affected by this. The default value of the seed is 0. The
maximum value is 65535.
default value (0)
When the seed value is 0 (default value), 20-sim generates a new sequence of random
numbers for each simulation and for each new random function. E.g. when two random
functions with default seed value (0) are used in one model, they will generate different
sequences of random numbers during a simulation.
other values (>0)
When the seed value is chosen larger than zero, 20-sim generates the same sequence
of random numbers for each simulation. Moreover 20-sim will generate the same
sequence of random numbers for each random function that uses the same seed
parameter (>0). E.g. when two random functions with seed value 50, are used in one
model, they will generate the same sequence of random numbers during a simulation.
20-sim 4.6 Reference Manual
189
7. Language Reference
step
Syntax
y = step(x);
Description
Returns a step signal with start time x:
time < x: y = 0
time >= x: y = 1
Examples
x = 20, amplitude = 10;
y = amplitude*step(x);
Limitations
x and y must be scalars.
7.4.10 Trigonometric
arcsin
Syntax
Y = arcsin(X);
Description
Returns the arcsine of the elements of X.
Examples
b
a
X
Y
= cos(time);
= arcsin(b);
= [0.5*cos(time);0.75*cos(time)];
= arcsin(X);
Limitations
Y and X must have the same size. The elements of X must be in the range [-1 ,1].
20-sim 4.6 Reference Manual
190
7. Language Reference
arccos
Syntax
Y = arccos(X);
Description
Returns the arccosine of the elements of X.
Examples
b
a
X
Y
= sin(time);
= arccos(b);
= [0.5*sin(time);0.75*sin(time)];
= arccos(X);
Limitations
Y and X must have the same size. The elements of X must be in the range [-1 ,1].
20-sim 4.6 Reference Manual
191
7. Language Reference
arccosh
Syntax
Y = arccosh(X);
Description
Returns the hyperbolic arccosine of the elements of X.
Examples
y = arccosh(time + 1.0);
Limitations
Y and X must have the same size. The elements of X must be 1 or bigger.
20-sim 4.6 Reference Manual
192
7. Language Reference
arcsinh
Syntax
Y = arcsinh(X);
Description
Returns the hyperbolic arcsine of the elements of X.
Examples
a = arcsinh(time);
X = [0.5*cos(time);0.75*cos(time)];
Y = arcsinh(X);
Limitations
Y and X must have the same size.
arctan
Syntax
Y = arctan(X);
Description
Returns the arctangent of the elements of X.
Examples
a = arctan(time);
X = [ramp(1);-0.5*ramp(9)];
Y = arctan(X);
Limitations
Y and X must have the same size.
20-sim 4.6 Reference Manual
193
7. Language Reference
arctanh
Syntax
Y = arctanh(X);
Description
Returns the hyperbolic arctangent of the elements of X.
Examples
b
a
X
Y
= sin(time);
= arctan(b);
= [sin(time);-0.5*cos(time)];
= arctanh(X);
Limitations
Y and X must have the same size. The elements of X must be in the range [-1 ,1].
20-sim 4.6 Reference Manual
194
7. Language Reference
atan2
Syntax
R = atan2(Y,X);
Description
This is the four quadrant arctangent of the elements of Y and X. Unlike arctangent
function, atan2 does distinguish between diametrically opposite directions.
Examples
X, Y
arctan(Y/X);
atan2(Y, X);
1,1
π/4
π/4
-1,-1
π/4
0,1
-
π/2
0,0
-
set
to
0
instead
of
undefined.
y = sin(time);
x = cos(time);
r = atan2(y,x);
X = [ramp(0);ramp(1)];
Y = [1;1];
R = atan2(Y,X);
Limitations
r, x and y must have the same size. It produces results in the range
Atan2(0, 0) is defined as 0 instead of undefined.
20-sim 4.6 Reference Manual
π].
195
7. Language Reference
cos
Syntax
Y = cos(X);
Description
Returns the cosine of the elements of X.
Examples
b
a
X
Y
= ramp(2.5);
= cos(b);
= [ramp(0);ramp(1)];
= cos(X);
Limitations
Y and X must have the same size.
cosh
Syntax
Y = cosh(X);
Description
Returns the hyperbolic cosine of the elements of X.
Examples
b
a
X
Y
= ramp(2.5);
= cosh(b);
= [ramp(0);ramp(1)];
= cosh(X);
Limitations
Y and X must have the same size.
20-sim 4.6 Reference Manual
196
7. Language Reference
sin
Syntax
Y = sin(X);
Description
Returns the sine of the elements of X.
Examples
b
a
X
Y
= ramp(2.5);
= sin(b);
= [ramp(0);ramp(1)];
= sin(X);
Limitations
Y and X must have the same size.
20-sim 4.6 Reference Manual
197
7. Language Reference
sinh
Syntax
Y = sinh(X);
Description
Returns the hyperbolic sine of the elements of X.
Examples
b
a
X
Y
= ramp(2.5);
= sinh(b);
= [ramp(0);ramp(1)];
= sinh(X);
Limitations
Y and X must have the same size.
20-sim 4.6 Reference Manual
198
7. Language Reference
tanh
Syntax
Y = tanh(X);
Description
Returns the hyperbolic tangent of the elements of X.
Examples
b
a
X
Y
= ramp(2.5);
= tan(b);
= [ramp(0);ramp(1)];
= tanh(X);
Limitations
Y and X must have the same size.
20-sim 4.6 Reference Manual
199
7. Language Reference
tan
Syntax
Y = tan(X);
Description
Returns the tangent of the elements of X.
Examples
b
a
X
Y
= ramp(2.5);
= tan(b);
= [ramp(0);ramp(1)];
= tan(X);
Limitations
Y and X must have the same size.
20-sim 4.6 Reference Manual
200
7. Language Reference
7.5
Operators
7.5.1
Operators
In 20-sim you can use the following operators in equations:
Operator
Description
*
Multiplication
+
Addition
-
Subtraction
.*
ArrayMultiplication
./
ArrayDivision
.^
ArrayPower
/
Division
div
Integer division
mod
Modulus operator
^
Power
and
Boolean and
or
Boolean or
xor
Boolean exclusive or
<
Less than
<=
Less than or equal
<>
Not equal
==
Equal
>=
Larger than or equal
>
Larger than
-
Prefix Minus Sign
+
Prefix Plus Sign
not
Prefix Boolean Not
| .. |
Absolute / Determinant / Norm
bitand
Bitwise AND
bitor
Bitwise OR
bitxor
Bitwise XOR
bitcmp
Bitwise complement
bitset
Bitwise set
bitget
Bitwise get
swapbytes
Swap bytes
bitshift
Bitwise shift
20-sim 4.6 Reference Manual
201
7. Language Reference
bitclear
7.5.2
Bitwise clear
Arithmetic
Absolute
Absolute / Determinant / Norm ( |..| )
Syntax
|A| or ||A||
Description
The upright stroke (|) is not a real operator. Depending on what's between the strokes,
the following functions are applied:
| scalar | -> abs(scalar)
| matrix | -> det(matrix)
| vector | -> abs(vector)
|| matrix || -> norm(matrix)
Multiplication
Syntax
A *B
Description
A * B multiplies A with B. For nonscalar A and B, the number of columns of A must equal
the number of rows of B. If C = A*B then the elements of C can be calculated out of the
matrix elements of A and B as:
A scalar can be multiplied with a matrix of any size.
Examples
A
B
A *B
5
3
15
-4.5
5.4
-24.3
2
[1,2;3,4]
[2,4;6,8]
[1,-2;-3,4]
4
[4,-8;-12,16]
[1,2,3;4,5,6]
[1,2;3,4;5,6]
[22,28;49,64]
[1,2;3,4;5,6]
[1,2,3;4,5,6]
not allowed!
20-sim 4.6 Reference Manual
202
7. Language Reference
Limitations
For nonscalar A and B, the number of columns of A must equal the number of rows of B.
Addition
Syntax
A +B
Description
A + B adds A and B. A and B must have the same size, unless one is a scalar. A scalar
can be added to a matrix of any size.
Examples
A
B
A +B
1
3
4
2.1
-3.2
-1.1
[1,2;3,4]
[1,1;5,5]
[2,3;8,9]
2
[1,2;3,4]
[3,4;5,6]
[1,2;3,4]
4
[5,6;7,8]
[1,2;3,4]
[5,6;7,8;9,10]
not allowed!
Limitations
If A and B are matrices, they must have the same size.
Subtraction
Syntax
A -B
Description
A - B subtracts B from A. A and B must have the same size, unless one is a scalar. A
scalar can be subtracted from a matrix of any size.
Examples
A
B
A - B
5
3
2
-4.2
5.5
-9.7
[4, 5; 6, 7]
[1, 1; 5, 5]
[3, 4; 1, 2]
[4, 5; 6, 7]
4
[0, 1; 2, 3]
20-sim 4.6 Reference Manual
203
7. Language Reference
4
[4, 5; 6, 7]
[0,-1;-2,-3]
Array Multiplication
Syntax
A .* B
Description
A .* B multiplies the elements of A by the elements of B. A.*B is the array or matrix with
elements A(i,j)*B(i.j).
Examples
A
B
A .* B
[1,-2,-4,2]
[1,2,1,4]
[1,-4,-4,8]
[2,0;0,2]
[1,2;3,4]
[2,0,0,8]
[2,0;0,2]
1
not allowed!
Limitations
A and B must have the same size.
Array Division
Syntax
A ./ B
Description
A ./ B divides the elements of A by the elements of B. A./B is the matrix with elements
A(i,j)/B(i.j).
Examples
A
B
A ./ B
[1,-2,-4,2]
[1,2,1,4]
[1,-1,-4,0.5]
[2,0;0,2]
[1,2;3,4]
[2,0,0,0.5]
[2,0;0,2]
1
not allowed!
Limitations
A and B must have the same size.
20-sim 4.6 Reference Manual
204
7. Language Reference
Array Power
Syntax
A .^ B
A .^ b
Description
A .^ B raises the elements of A to the power of the elements of B (B is a matrix). A .^ B
is the matrix with elements A(i,j)^B(i,j).
A .^ b raises the elements of A to the power of b (b is a scalar). A.^b is the matrix with
elements A(i,j)^b.
Examples
A
B
A .^ B
[1,-2,-4,2]
[1,2,1,4]
[1,4,-4,16]
[2,2;3,2]
[1,0;3,4]
[2,1;27,16]
A
b
A .^ b
[1, 2; 3, 4]
2
[1, 4; 9, 16]
[16, 4]
0.5
[4, 2]
Limitations
The A and B matrices must have the same size or b should be a scalar.
Division
Syntax
A /B
Description
A / B divides A by B. For a nonscalar B, A/B equals A*inverse(B). For a nonscalar A,
each element of A is divided by the scalar B.
Examples
A
B
A / B
15
3
5
-40.5
5
-8.1
2
[1,2;3,4]
[-4,2;3,-1]
[1,-2;-3,4]
4
[0.25,-0.5;0.75,1]
20-sim 4.6 Reference Manual
205
7. Language Reference
[2,0;0,2]
[1,2;3,4]
[-4,2,3,-1]
1
0
not allowed!
1
[1,2,3;4,5,6]
not allowed!
Limitations
If A and B are matrices, they must have the same size. If B is a matrix and it becomes
singular, simulation is stopped.
Integer Division
Syntax
a div b
Description
a div b divides the scalar a by the scalar b and rounds the output toward zero.
Examples
a
b
a div b
10
5
2
9.9
5
1
-8
2
-4
-7.9
2
-3
-7.9
-2
3
Limitations
a and b must be scalars.
Modulus Operator
Syntax
a mod b
Description
a mod b returns the signed remainder after division:
a mod b = a - trunc(a / b) *b
Examples
a
b
a mod b
10
5
0
20-sim 4.6 Reference Manual
206
7. Language Reference
9.9
5
4.9
-8
2
0
-7.9
2
-1.9
-7.9
-2
-1.9
Limitations
a and b must be scalars.
Power
Syntax
A ^b
Description
A ^ b raises A to the power b. For a nonscalar A and integer b, A^b is computed by
repeated multiplication of A. If b is negative A is inverted first. If b is zero, A^b is the
identity matrix. For other values of b, it is rounded to its nearest integer value. Making b
a nonscalar is not allowed.
Examples
A
b
A ^ b
5
3
125
4
-2.1
0.054409
5.5
0
1
3
2.1
10.04511
[2, 0; 0, 2]
4
[16, 0; 0, 16]
[1, 2; 3, 4]
-2.1
[5.5, -2.5; -3.75, 1.75]
[1, 2; 3, 4]
0
[1, 0; 0, 1]
[1, 2; 3, 4]
[1, 2; 3, 4]
not allowed!
Limitations
b must be a scalar. b is rounded downward to the nearest integer value.
A should be a scalar value or a square matrix.
20-sim 4.6 Reference Manual
207
7. Language Reference
7.5.3
Binary
bitand
Syntax
y = a bitand b
Description
a bitand b performs a bitwise AND between a and b. Both a and b are treated as 32-bit
(4-byte) integer values, so an eventual fraction will be ignored.
Example
In 20-sim, all bitwise function arguments are treated as 32-bit integers. Thus the binary
representation of 30 (ignoring leading zeroes) is equal to 11110 as shown in the figure
below. Similarly, the binary representation of 9 is 1001. The binary value of 30 bitand 9
is equal to 01000, which corresponds with decimal value of 8.
Limitations
a and b must be integers.
bitclear
Syntax
y= a bitclear b
Description
a bitclear b clears the bth bit of a. Both a and b are treated as 32-bit (4-byte) integer
values, so an eventual fraction will be ignored.
20-sim 4.6 Reference Manual
208
7. Language Reference
Example
In 20-sim, all bitwise function arguments are treated as 32-bit integers. Thus the binary
representation of 30 (ignoring leading zeroes) is equal to 11110 as shown in the figure
below. The operation 30 bitclear 3 clears the 3rd bit of 11110 which gives 11010. This
binary value has a decimal value of 26.
Limitations
a and b must be integers.
bitcmp
Syntax
y= a bitcmp b
Description
a bitcmp b performs the b bit complement of a. Both a and b are treated as 32-bit (4byte) integer values, so an eventual fraction will be ignored.
Example
In 20-sim, all bitwise function arguments are treated as 32-bit integers. Thus the binary
representation of 30 (ignoring leading zeroes) is equal to 11110 as shown in the figure
below. The operator 30 bitcmp 9 performs the 9 bit complement of 30. This gives the
binary value 111100001 which corresponds with the decimal value 481.
20-sim 4.6 Reference Manual
209
7. Language Reference
Limitations
a and b must be integers.
bitget
Syntax
y= a bitget b
Description
a bitget b gets the bth bit of a. Both a and b are treated as 32-bit (4-byte) integer
values, so an eventual fraction will be ignored.
Example
In 20-sim, all bitwise function arguments are treated as 32-bit integers. Thus the binary
representation of 30 (ignoring leading zeroes) is equal to 11110 as shown in the figure
below. The operation 30 bitget 5 gets the 5th bit of 11110 which is 1.
20-sim 4.6 Reference Manual
210
7. Language Reference
Limitations
a and b must be integers.
bitor
Syntax
y= a bitor b
Description
a bitor b performs a bitwise OR between a and b. Both a and b are treated as 32-bit (4byte) integer values, so an eventual fraction will be ignored.
Example
In 20-sim, all bitwise function arguments are treated as 32-bit integers. Thus the binary
representation of 30 (ignoring leading zeroes) is equal to 11110 as shown in the figure
below. Similarly, the binary representation of 9 is 1001. The binary value of 30 bitor 9 is
equal to 11111, which corresponds with a decimal value of 31.
Limitations
a and b must be integers.
bitset
Syntax
y = a bitset b
Description
a bitset b sets the bth bit of a. Both a and b are treated as 32-bit (4-byte) integer values,
so an eventual fraction will be ignored.
20-sim 4.6 Reference Manual
211
7. Language Reference
Example
In 20-sim, all bitwise function arguments are treated as 32-bit integers. Thus the binary
representation of 30 (ignoring leading zeroes) is equal to 11110 as shown in the figure
below. The operation 30 bitset 1 sets the last bit of 11110 to one which gives 11111. This
binary value corresponds with a decimal value of 31.
Limitations
a and b must be integers.
bitshift
Syntax
y= a bitshift b
Description
a bitshift b shifts the bits of a with b places. Both a and b are treated as 32-bit (4-byte)
integer values, so an eventual fraction will be ignored.
A positive value of b shifts the bits to the left and a negative value shifts the bits to the
right.
Example
In 20-sim all variables are stored as doubles. This means a decimal value of 30 is 4
bytes as shown in the figure below. Because the binary representation of 30 is equal to
11110, only the last byte is filled with non zero bits. The operation 30 bitshift 1 shifts the
bits of 11110 with one place which gives 111100. This number has a decimal value of
60.
20-sim 4.6 Reference Manual
212
7. Language Reference
Limitations
a and b must be integers. B should be in the range: [-31..31]
bitxor
Syntax
y= a bitxor b
Description
a bitxor b performs a bitwise XOR between a and b. Both a and b are treated as 32-bit
(4-byte) integer values, so an eventual fraction will be ignored.
Example
In 20-sim, all bitwise function arguments are treated as 32-bit integers. Thus the binary
representation of 30 (ignoring leading zeroes) is equal to 11110 as shown in the figure
below. Similarly, the binary representation of 9 is 1001. The binary value of 30 bitxor 9
is equal to 10111, which corresponds with a decimal value of 23.
20-sim 4.6 Reference Manual
213
7. Language Reference
Limitations
a and b must be integers.
7.5.4
Boolean
and
Syntax
a and b
Description
a and b performs a logical AND between a and b. If a or b are not a boolean, 0
represents a logical false and any nonzero value represents a logical true. The truth
table for this operator is shown below.
Table
a
b
a and b
false
false
false
false
true
false
true
false
false
true
true
true
Limitations
a and b must be scalars.
20-sim 4.6 Reference Manual
214
7. Language Reference
or
Syntax
a or b
Description
a or b performs a logical OR between a and b. If a or b are not booleans, 0 represents a
logical false and any nonzero value represents a logical true. The truth table for this
operator is shown below.
Table
a
b
a or b
false
false
false
false
true
true
true
false
true
true
true
true
Limitations
a and b must be scalars.
xor
Syntax
a xor b
Description
a xor b performs a logical Exclusive OR between a and b. If a or b are not booleans, 0
represents a logical false and any nonzero value represents a logical true. The truth
table for this operator is shown below.
Table
a
b
a xor b
false
false
false
false
true
true
true
false
true
true
true
false
Limitations
a and b must be scalars.
20-sim 4.6 Reference Manual
215
7. Language Reference
7.5.5
Comparison
Less than
Syntax
a<b
Description
The < operator compares two arguments and yields a boolean. If a is less than b, then a
< b yields true. If a is equal or larger than b, then a < b yields false.
Example
a
b
a <b
1
2
true
1.01e2
101.0
false
31
1
false
-12
-11
true
Limitations
a and b must be scalars.
Less than or Equal
Syntax
a <= b
Description
The <= operator compares two arguments and yields a boolean. If a is less than or
equal to b, then a <= b yields true. If a is larger than b, then a <= b yields false.
Example
a
b
a <b
1
2
true
1.01e2
101.0
true
31
1
false
-12
-11
true
Limitations
a and b must be scalars.
20-sim 4.6 Reference Manual
216
7. Language Reference
Not Equal
Syntax
a <> b
Description
The <> operator compares two arguments and yields a boolean. If a is equal to b, then
a <> b yields false. If a is not equal to b, then a <> b yields true.
Example
a
b
a <> b
1
1
false
1.01e2
101.0
false
31
1
true
true
false
true
Limitations
a and b must be scalars.
Equal
Syntax
a == b
Description
The == operator compares two arguments and yields a boolean. If a is equal to b, then
a==b yields true. If a is not equal to b, then a==b yields false. It is typically used in an
if-statement.
Example
a
b
a == b
1
1
true
1.01e2
101.0
true
31
1
false
true
false
false
Note
The normal equal sign (=) should only be used for equations. The equal sign (=) makes
the left side of an equation equal to the right side. This is different to the equal
statement (==) which compares two arguments and yields a boolean.
20-sim 4.6 Reference Manual
217
7. Language Reference
Larger Than
Syntax
a>b
Description
The > operator compares two arguments and yields a boolean. If a is less than or equal
to b, then a > b yields false. If a larger than b, then a > b yields false.
Example
a
b
a >b
1
2
false
1.01e2
101.0
false
31
1
true
-12
-11
false
Limitations
a and b must be scalars.
Larger Than or Equal
Syntax
a >= b
Description
The >= operator compares two arguments and yields a boolean. If a is less than b, then
a > b yields false. If a larger than or equal to b, then a > b yields true.
Example
a
b
a >= b
1
2
false
1.01e2
101.0
true
31
1
true
-12
-11
false
Limitations
a and b must be scalars.
20-sim 4.6 Reference Manual
218
7. Language Reference
7.5.6
Prefix
Prefix Plus Sign
Syntax
Y = +A
Description
The plus sign may be used as a prefix for scalars, vectors and matrices.
Examples
A
+A
5
5
[4, 5; -6, 7.1]
[4, 5; -6, 7.1]
Prefix Minus Sign
Syntax
Y = -B
Description
The minus sign may be used as a prefix for scalars, vectors and matrices.
Examples
A
-A
5
-5
[4, 5; -6, 7.1]
[-4; -5; 6; -7.1]
Boolean Not
Syntax
y = not a
Description
The boolean prefix not performs an inversion of a.
Table
a
not a
20-sim 4.6 Reference Manual
219
7. Language Reference
false
true
true
false
Limitations
a must be a boolean.
swapbytes
Syntax
swapbytes a
Description
swapbytes a swaps the bytes of a.
Example
In 20-sim all variables are stored as doubles. This means a decimal value of 30 is 4
bytes as shown in the figure below. Because the binary representation of 30 is equal to
11110, only the last byte is filled with non zero bits. The operation swapbytes 30 swaps
byte D to A, C to B, B to C and A to D (see figure below) which gives a decimal value of
503316480.
Limitations
a and b must be integers.
20-sim 4.6 Reference Manual
220
7. Language Reference
7.6
Statements
7.6.1
Statements
Statements are important to guide the flow of information in equation models. 20-sim
supports the following statements:
1.
For to Do
2.
If Then
3.
If Then Else
4.
If Then Else (expression)
5.
Repeat Until
6.
Switch C ase
7.
Stopsimulation
8.
Warning
9.
While Do
10. toMatlab
11. fromMatlab
12. doMatlab
13. Effortincausality
14. Flowincausality
7.6.2
If Then
Syntax
if condition then
equation;
....
end;
Description
The simplest if statement evaluates a condition and performs the specified equation(s) if
the condition is true. If the condition is not true, 20-sim ignores the equation(s).
20-sim 4.6 Reference Manual
221
7. Language Reference
Examples
b
y
u
if
= false;
= ramp(1);
= -ramp(1);
time > 5 then
y = -ramp(1); // equations to be executed if condition is true,
u = ramp(1); // these are not executed if condition is false
end;
if time == 10 then // note the use of the equal operator ==
b = true; // equations to be executed if condition is true,
end;
Limitations
1.
The output of the condition must be a boolean.
2.
If needed, always use the equal operator (==) in the condition.
Note
1.
Take care when using event functions in if-then-else statements. In if-then-else
statements only the equations of the true parts are evaluated, so event functions
may not always be triggered!
2.
Equations within an if statement have to be written in the correct order of execution,
i.e. they are not rewritten into a causal form but executed sequentially.
7.6.3
If Then Else
Syntax
if condition then
equation;
...
else
equation;
...
end;
Description
The if-then-else statement evaluates a condition and performs the first set of equation(s)
if the condition is true and the second set of equation(s) if the condition is false. If the
condition is true, 20-sim ignores the second set of equation(s). If the condition is false,
20-sim ignores the first set of equation(s).
Nesting
If-then-else statements may be nested as many times as desired. Do not forget to
included the word "end;" to finish every nested statement!
20-sim 4.6 Reference Manual
222
7. Language Reference
Examples
y = step(1);
u = -step(1);
if time > 5 then
y = -ramp(1); // equations to be executed if condition is true,
u = ramp(1); // these are not executed if condition is false
else
y = ramp(1); // equations to be executed if condition is false,
u = -ramp(1); // these are not executed if condition is true
end;
//Nesting
if time
a
b
else
if
< 5 then
= 1;
= sin(time*1);
time == 5 then
a = 2;
b = sin(time*2);
else
a=3
b=sin(time*3);
end;
end;
Limitations
1.
The output of the condition must be a boolean.
2.
If needed, always use the equal operator (==) in the condition.
Note
1.
Take care when using event functions in if-then-else statements. In if-then-else
statements only the equations of the true parts are evaluated, so event functions
may not always be triggered!
2.
There is also an if-then-else expression.
3.
Equations within an if statement have to be written in the correct order of execution,
i.e. they are not rewritten into a causal form but executed sequentially.
20-sim 4.6 Reference Manual
223
7. Language Reference
7.6.4
If Then Else (expression)
Syntax
y = if condition then
expression
else
expression
end;
Description
The if-then-else expression evaluates a condition and makes y equal to the first
expression if the condition is true and makes y equal to the second expression if the
condition is true. If the condition is true, 20-sim ignores the second expression. If the
condition is false, 20-sim ignores the first expression. Because the complete construct
forms one expression, only one semicolon is used at the end.
Nesting
If-then-else expression may be nested. Take care that no semicolons are used,
because no matter how large the construct is, it is still one expression!
Examples
y = if time > 5 then
-ramp(1) // statement to be executed if condition is true,
else
ramp(1) // statement to be executed if condition is false,
end;
// Nesting:
x = if time < 1 then
1
else
if time < 2 then
2
else
if time == 2 then
1
else
0
end
end
end;
Limitations
1.
The output of the condition must be a boolean.
2.
If needed, always use the equal operator (==) in the condition.
Note
1.
Take care when using event functions in if-then-else expressions. In if-then-else
expressions only the equations of the true parts are evaluated, so event functions
may not always be triggered!
20-sim 4.6 Reference Manual
224
7. Language Reference
2.
There is also an if-then-else statement.
3.
Equations within an if statement have to be written in the correct order of execution,
i.e. they are not rewritten into a causal form but executed sequentially.
7.6.5
For To Do
Syntax
for variable = start to stop by step do
equation;
equation;
....
end;
Description
The for statement is designed to execute equation(s) a fixed number of times. It begins
with the keyword for and an expression that specifies the number of times the equations
within the for statement should be executed. The for statement ends with the keyword
end. The default increment in a for statement is one (1), but you can use the keyword
by to adjust the increment.
The equations within the for statement are always executed once. The for statement
stops when the variable has exceeded the stop value.
Examples
variables
real i,y[10];
equations
for i = 1 to 2 do
// executed 2 times: y[1] and y[2]
y[i] = ran (1);
end;
for i = 2 to 4.1 by 2 do
// executed 3 times: y[2], y[4] and y[6]
y[i] = ran (1);
end;
Limitations
1.
The start, stop and step values must be scalars. The step value is optional. There
are no limitations to the number of equations that can be used within the for
statement.
2.
Equations within an for statement have to be written in the correct order of
execution, i.e. they are not rewritten into a causal form but executed sequentially.
20-sim 4.6 Reference Manual
225
7. Language Reference
7.6.6
While Do
Syntax
code
while condition do
equation;
equation;
....
end;
Description
The while statement is designed to execute equation(s) repeatedly, as long as the
condition is true. The condition is evaluated before the equations are executed.
It is the user's responsibility to guarantee that the execution of the while statement
finishes by making the condition become false at a certain time.
Example
variables
real i,y[3];
initialequations
y = 0;
code // Use code to ensure sequential execution
i = 1;
while i <= rows(y) do
// executed 3 times for each model calculate:
// y[1] and y[2] and y[3] are filled
y[i] = sin(time) * i;
// i is incremented to guarantee a stop of the loop
i = i + 1;
end;
Limitations
1.
The output of the condition must be a boolean. If the boolean does not become
false, the loop never ends! There are no limitations to the number of equations that
can be used within the while statement.
2.
Equations within an while statement have to be written in the correct order of
execution, i.e. they are not rewritten into a causal form but executed sequentially.
20-sim 4.6 Reference Manual
226
7. Language Reference
7.6.7
Repeat Until
Syntax
code
repeat
equation;
equation;
....
until condition;
Description
The repeat statement is designed to execute equation(s) repeatedly, as long as the
condition is true. The condition is evaluated after the equations are executed.
It is the user's responsibility to guarantee that the execution of the repeat statement
finishes by making the condition become false at a certain time.
Examples
variables
real i,z[4];
initialequations
z = 0;
code // Use code to ensure sequential execution
i = 1;
repeat
// executed 4 times:
z[i] = cos(time) * i;
// i is incremented to guarantee a stop of the loop
i = i + 1;
until (i > rows(z));
Limitations
1.
The output of the condition must be a boolean. If the boolean does not become
false, the loop never ends! There are no limitations to the number of equations that
can be used within the repeat statement.
2.
If needed, always use the equal operator (==) in the condition.
3.
Equations within an repeat statement have to be written in the correct order of
execution, i.e. they are not rewritten into a causal form but executed sequentially.
20-sim 4.6 Reference Manual
227
7. Language Reference
7.6.8
Switch Case
Syntax
switch variable
case condition1 do
equations;
case condition2 do
equations;
default do
equations;
end;
Description
The switch case statement is designed to execute equation(s) based on the condition of
a variable. Only the equations of the valid branch are executed. If non of the branches is
valid, the equations of the default branch are executed.
Limitations
1.
The switch variable should not be changed inside one of the branches.
2.
Equations within a switch case statement have to be written in the correct order of
execution, i.e. they are not rewritten into a causal form but executed sequentially.
Therefore it is advised only to use this statement in a code section.
7.6.9
Stopsimulation
Syntax
stopsimulation ('string');
Description
The stopsimulation function stops the simulation as soon as it comes to action. It is
useful when used in combination with an if statement. As soon as the simulation stops,
the log window will appear showing the string that is used in the function.
Normal stop: If the string starts with 'Error', the Simulator will stop and the Editor
will jump to the the model containing the stopsimulation function.
Silent stop: If the string does not start with 'Error' the Simulation will jump to the
finalequations section, execute them and stop the simulation.
Examples
In the example below the Simulator will stop the simulation at time > 6 and show a
message 'time > 6' in the output tab. The finalequations are evaluated and number has
a value of 2:
20-sim 4.6 Reference Manual
228
7. Language Reference
variables
integer number;
initialequations
number = 1;
equations
if time > 6 then
stopsimulation ('time > 6' );
end;
finalequations
number = 2;
In the example below the Simulator will stop the simulation at time > 6 and show a
message 'time > 6' in the output tab. The Editor will jump to this model showing an error
message. The finalequations are not evaluated and number has a value of 1:
variables
integer number;
initialequations
number = 1;
equations
if time > 6 then
stopsimulation ('Error time > 6' );
end;
finalequations
number = 2;
7.6.10 Warning
Syntax
warning ('string',boolean);
Description
The warning function displays a message in the the log window. You can choose to
display the string once (boolean = true) or every simulation step (boolean = false). It is
advised to use the warning function in combination with an if-then statement or eventfunction.
Examples
warning('this message will be displayed every simulationstep!',false);
if time > 1
warning('this message will be displayed every simulationstep after time >
1!',false);
end;
if x > 100 then
warning('this message will be displayed only once after x > 100',true);
end;
if event(y) then
warning('this message will be displayed when y is exactly 0',false);
end;
20-sim 4.6 Reference Manual
229
7. Language Reference
7.6.11 toMatlab
Syntax
toMatlab(<20-sim variable>)
toMatlab(<20-sim variable>, 'matlab variable name')
Description
The toMatlab statement allows you to pass a variable from 20-sim to Matlab.
The first argument is the name of the 20-sim variable to send to Matlab (source).
This 20-sim variable can be a scalar variable, a vector or a matrix.
The second (optional) argument 'matlab variable name' is the name of
corresponding matlab variable (destination).
the
When the 'matlab variable name' argument is omitted, 20-sim will use the full
hierarchical name of the 20-sim variable.
A 20-sim variable named Controller\x becomes in Matlab: Controller_x
The corresponding fromMatlab statement allows you to retrieve a variable from Matlab.
Example
// this example shows how a variable can be transferred to matlab and from matlab
during simulation
variables
real x;
real y;
real vector[2];
real matrix[2,2];
// at the start of the simulation
initialequations
// create an empty array a
doMatlab ('a = []; ');
// create a variable
doMatlab ('b=0; ');
// create a vector
doMatlab ('vector=[1 2];');
// create a matrix
doMatlab ('matrix=[1 2; 3 4];');
// during simulation
equations
// calculate x
x = sin (time);
// send it to Matlab
toMatlab (x,'x');
// and add it to array a
doMatlab ('a = [ a x ]; ');
// in Matlab add 2 to x
doMatlab ('b = x + 2;');
// read matlab 'b' into 20-sim variable 'y'
fromMatlab(y, 'b');
// read matlab 'vector' into 20-sim variable 'vector'
20-sim 4.6 Reference Manual
230
7. Language Reference
fromMatlab(vector, 'vector');
// read matlab 'matrix' into 20-sim variable 'matrix'
fromMatlab(matrix, 'matrix');
// at the end of the simulation
finalequations
// plot the resulting array in Matlab
doMatlab (' plot (a); ');
7.6.12 domatlab
Syntax
doMatlab('string')
Description
The doMatlab statement allows you to pass a command line string to Matlab.
Example
// this example shows how a variable can be transferred to matlab and from matlab
during simulation
variables
real x;
real y;
real vector[2];
real matrix[2,2];
// at the start of the simulation
initialequations
// create an empty array a
doMatlab ('a = []; ');
// create a variable
doMatlab ('b=0; ');
// create a vector
doMatlab ('vector=[1 2];');
// create a matrix
doMatlab ('matrix=[1 2; 3 4];');
// during simulation
equations
// calculate x
x = sin (time);
// send it to Matlab
toMatlab (x,'x');
// and add it to array a
doMatlab ('a = [ a x ]; ');
// in Matlab add 2 to x
doMatlab ('b = x + 2;');
// read matlab 'b' into 20-sim variable 'y'
fromMatlab(y, 'b');
// read matlab 'vector' into 20-sim variable 'vector'
fromMatlab(vector, 'vector');
// read matlab 'matrix' into 20-sim variable 'matrix'
fromMatlab(matrix, 'matrix');
20-sim 4.6 Reference Manual
231
7. Language Reference
// at the end of the simulation
finalequations
// plot the resulting array in Matlab
doMatlab (' plot (a); ');
7.6.13 frommatlab
Syntax
fromMatlab(<20-sim variable>)
fromMatlab(<20-sim variable>, 'matlab variable name')
Description
The fromMatlab statement allows you to retrieve a variable from Matlab and store it
into a 20-sim variable.
The first argument is the name of the 20-sim variable to use as storage (destination).
This 20-sim variable can be a scalar variable, a vector or a matrix and should match the
size used at the Matlab side.
The second (optional) argument 'matlab variable name' is the name of the Matlab
variable to retrieve (source).
When the 'matlab variable name' argument is omitted, 20-sim will use the full
hierarchical name of the 20-sim variable.
A 20-sim variable named Controller\x requests from Matlab: Controller_x
The corresponding toMatlab statement allows you to pass a variable from 20-sim to
Matlab.
Example
// this example shows how a variable can be transferred to matlab and from matlab
during simulation
variables
real x;
real y;
real vector[2];
real matrix[2,2];
// at the start of the simulation
initialequations
// create an empty array a
doMatlab ('a = []; ');
// create a variable
doMatlab ('b=0; ');
// create a vector
doMatlab ('vector=[1 2];');
// create a matrix
doMatlab ('matrix=[1 2; 3 4];');
// during simulation
equations
// calculate x
x = sin (time);
// send it to Matlab
20-sim 4.6 Reference Manual
232
7. Language Reference
toMatlab (x,'x');
// and add it to array a
doMatlab ('a = [ a x ]; ');
// in Matlab add 2 to x
doMatlab ('b = x + 2;');
// read matlab 'b' into 20-sim variable 'y'
fromMatlab(y, 'b');
// read matlab 'vector' into 20-sim variable 'vector'
fromMatlab(vector, 'vector');
// read matlab 'matrix' into 20-sim variable 'matrix'
fromMatlab(matrix, 'matrix');
// at the end of the simulation
finalequations
// plot the resulting array in Matlab
doMatlab (' plot (a); ');
7.6.14 Effortincausality
Syntax
effortincausality (portname) then
equation;
equation;
...
else
equation;
equation;
...
end;
Description
The effortincausality statement evaluates if a port has causality effort in and performs
the first set of equation(s) if the condition is true and the second set of equation(s) if the
condition is false. If the condition is true, 20-sim ignores the second set of equation(s). If
the condition is false, 20-sim ignores the first set of equation(s).
Depending on the domain you are working in, effort and flow correspond to particular
variables. The table below shows the variables for the domains that are currently
supported in 20-sim.
Domain
effort (e)
flow (f)
power
effort e
flow f
mechanical
force F [N]
velocity v [m/s]
torque T [Nm]
angular velocity omega [rad/s]
pressure p [Pa]
volume flow phi [m3/s]
(translation)
mechanical
(rotation)
pneumatic
20-sim 4.6 Reference Manual
233
7. Language Reference
thermal
temperature T [K]
entropy flow dS [J/Ks]
electric
voltage u [V]
current i [A]
hydraulic
pressure p [Pa]
volume flow phi [m3/s]
magnetic
current i [A]
voltage u [V]
pseudothermal
temperature T [K]
heat flow dQ [W]
Examples
effortincausality p then
R = if p.u > 0 then Ron else Roff end; // executed if causality of port p is
effort (u) in
else
R = if p.i > 0 then Ron else Roff end; // executed if causality of port p is flow
(i) in
end;
p.i = p.u/R;
Note
1.
Take care when using event functions in effortincausality statements. In this
statement only the equations of the true parts are evaluated, so event functions
may not always be triggered!
2.
There is also a flowincausality statement.
3.
Equations within an effortincausality have to be written in the correct order of
execution, i.e. they are not rewritten into a causal form but executed sequentially.
7.6.15 Flowincausality
Syntax
flowincausality (portname) then
equation;
equation;
...
else
equation;
equation;
...
end;
Description
The effortincausality statement evaluates if a port has causality flow in and performs the
first set of equation(s) if the condition is true and the second set of equation(s) if the
condition is false. If the condition is true, 20-sim ignores the second set of equation(s). If
the condition is false, 20-sim ignores the first set of equation(s).
20-sim 4.6 Reference Manual
234
7. Language Reference
Depending on the domain you are working in, effort and flow correspond to particular
variables. The table below shows the variables for the domains that are currently
supported in 20-sim.
Domain
effort (e)
flow (f)
power
effort e
flow f
mechanical
force F [N]
velocity v [m/s]
torque T [Nm]
angular velocity omega [rad/s]
pneumatic
pressure p [Pa]
volume flow phi [m3/s]
thermal
temperature T [K]
entropy flow dS [J/Ks]
electric
voltage u [V]
current i [A]
hydraulic
pressure p [Pa]
volume flow phi [m3/s]
magnetic
current i [A]
voltage u [V]
pseudothermal
temperature T [K]
heat flow dQ [W]
(translation)
mechanical
(rotation)
Examples
flowincausality p then
R = if p.i > 0 then Ron else Roff end; // executed if causality of port p is flow (i) in
else
R = if p.u > 0 then Ron else Roff end; // executed if causality of port p is effort (u)
in
end;
p.u = p.i*R;
Note
1.
Take care when using event functions in effortincausality statements. In this
statement only the equations of the true parts are evaluated, so event functions
may not always be triggered!
2.
There is also an effortincausality statement.
3.
Equations within an effortincausality have to be written in the correct order of
execution, i.e. they are not rewritten into a causal form but executed sequentially.
20-sim 4.6 Reference Manual
235
7. Language Reference
7.7
Matrices and Vectors
7.7.1
Declaration
Matrices and column vectors are declared in the constants, parameters and variables
sections of a model. Declaration of matrices and column vectors is equal to the
declaration of scalars, the size however has to be specified explicitly. For example:
parameters
real A[3,3], B[3,3];
integer C[2,2] = [1,3;5,7];
real K[4] = [1;2;3;4];
variables
real K[4],L[4],D[4,5];
integer M[2,2],N[2,2];
Matrices and Vectors can only be of the datatype real or integer.
7.7.2
Notation
Matrix sizes in 20-sim are always denoted by [n,m] where n is the numbers of rows and
m is the numbers of columns. Elements can separately be denoted with commas (,)
distinguishing between row elements and semicolons (;) distinguishing between rows.
matrix size
matrix form
20-sim notation
[4,1]
1
[1;3;5;7]
3
5
7
[1,4]
1357
[1,3,5,7]
[2,3]
123
[1,2,3;4,5,6]
456
[3,2]
12
[1,2;3,4;5,6]
34
56
C olumn vectors are matrices with only one column. C onsequently the column size may
be omitted in the notation.
column size
column form
20-sim notation
[4]
1
[1;3;5;7]
20-sim 4.6 Reference Manual
236
7. Language Reference
3
5
7
7.7.3
Use
Matrices and Vectors can be used in equations just like scalars. If possible, the element
notation can be left out. If equations get ambiguous, element notation must be
used!
Whole matrix or vector
K = 1; // Make all elements of K equal to 1.
M = C; // Make matrix M equal to matrix C (sizes have to be equal).
N = D*inverse(L); // Make matrix N equal to the matrix product of D
// and the inverse of L (sizes of N, D and L have to be equal).
Matrix and vector elements
N = [sin(time),cos(time);cos(time),-sin(time)]; // Make elements of N equal to
functions.
L[4] = time; // Make element 4 of columned L equal to time.
D[2,5] = A[2,2]*B[1,1]; // Declare one element
Multiple elements (ranges)
To prevent multiple equations for assigning matrix elements, ranges can be assigned
using a colon. E.g. 1:5 means element 1 to 5, 7:8 means element 7 and 8. Backward
counting ranges (like 10:1) are not allowed!
D[2,1:5] = A[1,1:5]; // D[2,1] = A[1,1], ... , D[2,5] = A[1,5]
variables
real v[3],p[6,6];
equations
v = p[4:6,6]; // v[1] = p[4,6], ... , v[3] = p[6,6]
Operators
Some scalar operators can also be used for matrices and vectors. Depending on the
specific operator, the meaning may differ for scalars, vectors and matrices.
Operator
Description
*
Multiplication
+
Addition
-
Subtraction
.*
ArrayMultiplication
./
ArrayDivision
20-sim 4.6 Reference Manual
237
7. Language Reference
.^
ArrayPower
/
Division
^
Power
-
Prefix Minus Sign
+
Prefix Plus Sign
| .. |
Absolute / Determinant / Norm
Functions
A lot of special matrix and vector functions are supported in 20-sim:
Function
Description
Adjoint
adjoint
Antisym
C olumns
C ross
Determinant
Diag
Eye
Homogeneous
Inner
Inverse
InverseH
Linsolve
Max
Min
Msum
Norm
Norminf
Rows
Skew
Sym
Tilde
Trace
Transpose
20-sim 4.6 Reference Manual
238
7. Language Reference
7.8
Advanced Topics
7.8.1
Algebraic Loops
An algebraic loop in a model is a loop consisting of elements without "memory like"
functions. To calculate the variables in this loop, the variable values themselves are
needed. C onsider the following example of an algebraic loop in an amplifier with
negative feedback:
Standard derivation of a simulation model would yield:
x = K*(u-x)
The variable x depends on its own value and must be solved by iteration. In 20-sim
every simulation algorithm is accompanied by an iteration routine. Fortunately 20-sim is
able to solve many algebraic loops at equation level. For this model this leads to the
analytic solution the system:
x = K*u/(1+K)
Simulating algebraic loops
Although 20-sim contains a sophisticated algorithms to find analytic solutions, the
occurrence of unbreakable loops can not always be prevented. The occurrence of
algebraic loops may lead to an increase of simulation time, or even stop simulation when
iteration fails.
The best solution for these problems is to have a critical look at the model and change
the order of calculations in a model. Possible solutions are:
Algebraic Loops occur when the order of calculations is arbitrary. When an algebraic
loop occurs in an equation model or in a set of equation models, you may change the
order of calculation by rewriting the equations. The calculation order in bond graph
models can be changed by introducing hand-defined causality.
Introduce ‘parasitic’ energy storage elements (e.g. a small mass, a small capacitor
etc.) to break an algebraic loop. These elements introduce however, large poles in
the state equations, which might increase the simulation time considerably.
Delete elements in the algebraic loop which are not relevant for the model’s
simulation output (e.g. small dampers, very stiff springs etc.). C are should however
be taken, since correct deletions are not always possible and require considerable
modeling skill and intuition.
C ombine dual elements. Sometimes elements of the same type can be combined by
adding the parameter values (e.g. combining a mass m1 and a mass m2 to a mass
m1 + m2). This will in most cases decrease the amount of algebraic loops.
20-sim 4.6 Reference Manual
239
7. Language Reference
7.8.2
Causal Form
Equations within 20-sim may be entered in random form. During compilation, 20-sim will
automatically try to rewrite equations into a causal form and set them in a correct order.
I.e. a form where all output variables are written as function of input variables. C onsider
for example the following model:
variables
real u,z;
equations
u = sin(time);
u = cos(z);
Here the (input) variable u is given by the equation u = sin(time). C onsequently the
(output) variable z should be written as a function of u. This is exactly what 20-sim will
try to do while compiling the model into simulation code. I.e. the function cos will be
inverted and the model will be rewritten to:
variables
real u,z;
equations
u = sin(time);
z = arccos(u);
Some functions cannot be inverted. C onsequently not all equations can be rewritten. 20sim will report this to the user, during model checking.
Indifferent Causality
For some models the causal form is not known beforehand. For example the iconic
diagram model that describes a damper can be written as:
parameters
real d;
equations
p.F = d*p.v;
Here p.F denotes the force and p.v denotes the velocity of the powerport p. There is no
preferred input (force or velocity). This can be explicitly stated, by giving the powerport
p an indifferent causality. During compilation 20-sim will determine whether p.F or p.v is
the input variable and consequently rewrite the equations.
Preferred Causality
For some models there is a preferred causal form. For example the iconic diagram
model that describes a spring can be written as:
parameters
real k;
equations
p.F = (1/k)*int(p.v);
20-sim 4.6 Reference Manual
240
7. Language Reference
Here p.F denotes the force and p.v denotes the velocity of the powerport p. The equation
is written in integral form which is preferred. C onsequently the preferred input is the
velocity. Should the force be the input, the equation must be rewritten to a differential
form, which is leads to less efficient simulation. This can be explicitly stated, by giving
the powerport p an preferred causality. During compilation 20-sim will try to keep the
model in this preferred form. If this is not possible the equations will be rewritten to the
less preferred form.
Preferred causality has a lower priority than fixed causality. During compilation 20-sim
will first assign all models with a fixed causality and then all models with preferred
causality.
Likes Causality
For some models there is a causal form which is liked more than the other. For example
the iconic diagram model that describes a parasitic volume can be written as:
effortincausality(p) then
p.phi = 0;
else
volume_ratio = int(p.phi/V);
p.p = B * volume_ratio + p_initial;
end;
Here p.phi denotes the volume flow and p.p denotes the pressure of the powerport p.
The equation is written in integral form which is liked. C onsequently the preferred output
is the pressure. Should the pressure be the input, the equation gives a zero flow as
output. During compilation 20-sim will first try to keep all models the liked form. If this is
not possible the equations will be rewritten to the other form.
Liked causality has a lower priority than preferred causality. During compilation 20-sim
will first assign all models with a preferred causality and then all models with likes
causality.
Fixed Causality
For some models there is only one causal form. For example a simple iconic diagram
model that describes coulomb friction can be written as:
parameters
real Rc;
equations
p.F = Rc*abs(p.v);
Here p.F denotes the force and p.v denotes the velocity of the powerport p. The equation
cannot be rewritten to a form where p.F is the input. This can be explicitly stated, by
giving the powerport p a fixed causality. During compilation 20-sim will try to keep the
model in this fixed form. If this is not possible an error message will be generated.
Fixed causality has a lower priority than a likes causality. During compilation 20-sim will
first assign all models with a likes causality and then all models with fixed causality.
Setting Causality
For some models, the equations are too complex to analyze causality. To help 20-sim,
using the right causality, you can set causality for every port in the Interface Editor.
20-sim 4.6 Reference Manual
241
7. Language Reference
7.8.3
Integral Form
C onsider the following first order linear model:
This model can be described by the dynamic equation:
output = int( input - K*output )
Now look at the following model:
This model can be described by the dynamic equation:
output = ( input - ddt(output) )/K
Note that we can rewrite this equation as:
ddt(output) = input - K*output
or
output = int( input - K*output )
This is the same equation as the previous model! Apparently, both models are the same!
Both models can therefore be described by the dynamic equations:
ddt(output) = input - K*output
output = int( input - K*output )
We call the first equation the differential form (no integrals). The second equation is
called the integral form (no derivatives). In 20-sim, models can be entered in integral
form as well as the differential form.
Solving Differential Equations
During compilation, 20-sim will automatically try to rewrite equations into the integral
form, since this leads to more efficient simulation. Sometimes an integral form cannot be
found. Then algorithms will be applied to solve the differential directly. For example an
equation like:
output = ddt(sin(a*time))
20-sim 4.6 Reference Manual
242
7. Language Reference
will be replaced by the following equation (applying the chain rule and using the known
derivative for the sine function):
output = a*cos(a*time)
Sometimes a differential cannot be solved directly. Then
Differentiation Methods can be used for simulation.
only
the
Backward-
Simulation Code
After compilation simulation code is generated. The equation in integral form:
output = int( input - K*output )
will be written as:
independent state = output
independent rate = input - K*output
and can be handled by all integration methods. The equation in differential form:
ddt(output) = input - K*output
will be written as:
dependent rate = input - K*output
dependent state = output
and can only be handled by the Backward-Differentiation Methods.
7.8.4
Order of Execution
Equations within 20-sim may be entered in random form. During compilation, 20-sim will
automatically try to rewrite equations into a correct order of execution. I.e. a form
where all output variables are written as function of input variables and output variables
of previous lines. C onsider for example the following equations:
variables
real u,z;
equations
z = sin(u);
u = cos(time);
Here the (input) variable z is given as a function of u. C onsequently u should be
calculated first. This is exactly what 20-sim will try to do while compiling the model into
simulation code. I.e. the equations will be executed as:
u = cos(time);
z = sin(u);
Code Blocks
Equations in a code block are not reordered. A code block is a set of equations inside a
statement. Suppose we have the following equations:
20-sim 4.6 Reference Manual
243
7. Language Reference
if condition then
code block 1
...
...
else
code block 2
...
...
end;
To prevent incorrect executions of the if-statement, the equations of the code blocks will
not be separated. Inside a code-block, equations can are not rewritten into an new order
of execution. E.g. the following equations:
if time > 10 then
z = sin(u);
a = z^2;
u = cos(time);
end;
Will be not be reordered and therefore not correctly executed! To get correct code,
enter code blocks in a correct order, e.g.:
if time > 10 then
u = cos(time);
z = sin(u);
a = z^2;
end;
Prevent Order Changes
To make all equations a code block you can use the code section. E.g.
parameters
real y = 8;
variables
real x1, x2, x3;
code
x1 = time;
x2 = sin(time);
x3 = y*x1;
Integration Steps
Some integration algorithms do more calculations before generating the next output
value. These calculations are called minor steps, the output generation is called a major
step. During a minor step, all model equations are executed. In most cases you will not
notice this because only the results of the major step are shown in the simulator. There
are however, exceptions. The next topic will discuss this in more detail.
20-sim 4.6 Reference Manual
244
7. Language Reference
7.8.5
Show Equations
During processing a complete set of equations is generated of each model. To inspect
these equations or copy them for use in other programs, you have to:
1.
From the Model menu select the Check Complete Model command.
2.
From the Model menu select the Show Equations command.
Now a window is popped up showing all the model equations.
The model equations after compiling.
20-sim 4.6 Reference Manual
245
8. Toolboxes
8
Toolboxes
8.1
3D Mechanics Toolbox
8.1.1
Introduction
Introduction
With the 3D Mechanics Editor you can create 3D dynamic models of mechanical
structures. The resulting 3D mechanical model can be connected with other 20-sim
components. In the example shown below (Getting Started\3D Mechanics Toolbox
\ScaraRobotSimulation.emx), you see a robot model that has been generated with the
3D Mechanics Editor. The model has two actuated rotation joints and one actuated
translation joint. The rotation joints are directly coupled to gearboxes. The translation
joint is coupled via a spindle.
In 20-sim you can use plots to show the simulation results and use the 3D Animation
Toolbox to show an animation of the 3D model.
Opening The 3D Mechanics Editor
You can open the 3D Mechanics Editor by:
1.In the 20-sim Editor from the Tools menu select 3D Mechanics Toolbox and 3D
Mechanics Editor.
20-sim 4.6 Reference Manual
246
8. Toolboxes
Now a masked model is inserted in the Editor and the 3D Mechanics Editor will be
opened.
If you select a 3D Mechanics model and select Go Down, the 3D Mechanics Editor will be automatically
opened.
The first time you start 20-sim 3D Mechanics Editor the following screen will appear.
20-sim 4.6 Reference Manual
247
8. Toolboxes
The 3D Mechanics Editor
Migrating from Older Versions
This topic is only important for users who are migrating from older version of 20-sim and
want to use previously constructed 3D Mechanics models. Since 20-sim 4.1, the 3D
Mechanics Editor operates on masked models. I.e. you can open the 3D Mechanics Editor
by selecting a 3D Mechanics model and clicking the Go Down command. If you import a
20-sim 4.0 model, you will notice that this option does not work. We will explain the
actions you have to perform to do make this trick work on older models.
1.
Open the 20-sim model that contains a submodel that was generated by the 3D
Mechanics Editor (make sure you have stored an emergency copy).
20-sim 4.6 Reference Manual
248
8. Toolboxes
The star shaped model was created using the 3D Mechanics Editor of 20-sim 4.0.
2.
Select the model that was generated by the 3D Mechanics Editor and select Go
Down.
The automatically generated equations of a 3D Mechanical Model.
3. At the top of the model enter the following code:
// 20-sim 3D Mechanics Editor
// C :\Program Files\20-sim 4.6\Models\Examples\3D Mechanics\hexapod.3dm
20-sim 4.6 Reference Manual
249
8. Toolboxes
The first line tells 20-sim which editor should be opened. The second line shows the
location of the corresponding 3D Mechanics configuration file. Enter the path and name
of your own file here.
The comment at the top tells 20-sim which editor should be opened and the corresponding configuration
file.
The next time you select the model and select Go Down the 3D Mechanics Editor will be
opened with the proper 3D Mechanics model.
20-sim 4.6 Reference Manual
250
8. Toolboxes
Edit Window
In the center of the 3D Mechanics Editor the Edit window is visible. At the start a
reference frame and a base plane is shown. In the Edit window, you can insert
components and assemble you model.
In the Edit Window you can assemble your model.
20-sim 4.6 Reference Manual
251
8. Toolboxes
Model Tab
One of the two tabs at the left of the 3D Mechanics Editor is the Model tab. The Model
tab contains a tree of all the components of in your current model. This tree can be used
to select components and edit their properties.
20-sim 4.6 Reference Manual
252
8. Toolboxes
Library Tab
One of the two tabs at the left of the 3D Mechanics Editor is the Library tab. The
Library tab contains predefined components, which you can use to construct your model
with. The components in the library tree can be dragged into the Edit window.
20-sim 4.6 Reference Manual
253
8. Toolboxes
Selection Properties
Below the Bodies/Library tabs the properties of the selected component are shown.
When no components are selected the selection properties are empty.
When a component is selected, the edit button will be enabled. You can click the button
to change the component properties.
3D Representation
Below the Selection Properties, the 3D representation of the selected component is
shown. When no components, the 3D Representation is empty.
When a component is selected, the edit button will be enabled. You can click the button
to change the 3D Representation of the component.
20-sim 4.6 Reference Manual
254
8. Toolboxes
A
component
may
be
composed
of
several
representations.
Using
the
Add
Representation and Delete Representation commands of the Actions menu you can add
more representations or remove representations.
Output
In the Output part of the 3D Mechanics Editor, messages will be shown during analysis of
the model.
Edit Modes
At the right of the 3D Mechanics Editor you will find the Edit Mode buttons. You can
select them to enter several edit modes.
Translation Mode
In this mode you can translate components.
C onnection Mode
In this mode you can make connections between
components.
In this mode you can rotate components.
Rotation Mode
C amera Mode
In this mode you can change the camera position
and orientation. I.e. the way you look at your
model.
Ghost Modes
At the right of the 3D Mechanics Editor you will find the Ghost Mode buttons. You can
use these buttons to make components transparent. This is useful when components are
hidden inside other components.
Ghost Mode for Bodies
Make every body transparent.
20-sim 4.6 Reference Manual
255
8. Toolboxes
Ghost Mode for Joints
Make every joint transparent.
Ghost Mode for Sensors/ Make every sensor/actuator transparent.
Actuators
View Modes
In the button bar of the 3D Mechanics Editor you will find the View Mode buttons. You
can select them to select different views.
3D View
Default view.
X-Y plane
View perpendicular to the x-y plane. You can only
move objects along the x-y plane.
X-Z plane
View perpendicular to the x-z plane. You can only
move objects along the x-z plane.
Y-Z plane
View perpendicular to the y-z plane. You can only
move objects along the y-z plane.
All
A combination of the all the views.
20-sim 4.6 Reference Manual
256
8. Toolboxes
Model Settings
The model Settings command of the Tools menu will open the Model Settings dialog. In
this dialog you can change some general settings such as the size of the reference
frames or the amount of gravity.
The Model Setting Dialog.
Items
Gravity: You can set the gravitational acceleration to any desired value.
Hard C oded: choose this option if you want to optimize for speed.
As Parameter: Use a gravity parameter, allowing you to change the value before
the start of a simulation run.
As Input Signal: get the gravity value from an input signal, allowing you to change
the value during simulation.
Spring Dampers for C onstraint Joints: C hoose this option if you want to use spring
dampers for closed kinematic chains. You can override the spring damper values for
individual joints if required.
Rotation Spring: Set the desired stiffness for the rotational spring.
Rotation Damper: Set the desired rotational damping.
Rotation Spring: Set the desired stiffness for the translation spring.
20-sim 4.6 Reference Manual
257
8. Toolboxes
Translation Damper: Set the desired translation damping.
Reference Frames: C hoose the size and thickness of the reference frames.
Grid: Set the grid.
Angle Representation: 20-sim uses SI-units for the model equations (e.g. radians).
You can choose to show them in non-SI-units like degrees or grads.
Power Port Type: C hoose Iconic Diagram power ports or bond Graph power ports.
C onstraint Solver: set the accuracy of the constraint solver.
Camera Settings
At the start of a model session, in the Edit window, a default camera is used. You can
change camera settings by clicking Camera Settings from the Tools menu.
In the C amera Settings dialog you can change the range (front and back plane) and
zooming of the camera, use a perspective view or orthographic, select the camera
position and the point to look at.
20-sim 4.6 Reference Manual
258
8. Toolboxes
Spring Dampers and Constraints
In the 3D Mechanics Editor you can connect bodies with joints. If no path from any body
through a joint to another body and so on never returns to the starting body, we have
an open chain mechanism. Open chain mechanisms are easy to simulate with al known
integration methods.
Open Chain Mechanism.
If a path from any body through a joint to another body and so on returns to the starting
body we have a closed chain mechanism. C losed chain mechanisms are generally more
difficult to simulate.
Closed Chain Mechanism.
20-sim uses a special feature to simulate closed chain mechanisms. At an arbitrary place
a joint is removed to create an open chain mechanism. Then the open chain is closed
again using a spring damper joint or a constraint joint. You can choose which joint to use
in the Model Settings Dialog.
20-sim 4.6 Reference Manual
259
8. Toolboxes
Spring Damper Joint
A spring damper joint is a joint where all rigid connections are replaced by spring
dampers. If weak spring dampers are used a certain amount of (unwanted)
displacement will be possible. By increasing the stiffness and damping, the displacement
can be decreased. You can set the spring stiffness and damping in the Model Settings
Dialog. You can override these spring damper values in the Joint C onstraint Settings
Dialog.
Constraint Joint
The constraint joint works exactly like the original joint but uses constraint forces to do
the job. C onstraint forces can only be simulated with special integration methods. In 20sim the Modified Backward Differentiation Method is able to calculate constraint forces.
The concept of constraint forces is quite easy to understand if we look at the open chain
mechanism below. At the tips of the mechanism a force is applied. If we apply a force
that keeps the tips at the same position at each time step, it will effectively work as a
rotation joint. That is exactly what constraint forces do. At every simulation step, an
iterative procedure is run to find exactly that force that keeps the position offset at zero.
Constraint Force.
This iterative procedure is not standard for most integration methods. In 20-sim only the
Modified Backward Differentiation Method supports it. In the 3D Mechanics Editor you do
not have to worry about closed chain mechanisms. If necessary, standard joints are
replaced automatically by constraint joints. You only have to realize that simulation of a
mechanism with constraint joints in 20-sim should be performed using the Modified
Backward Differentiation Method.
20-sim 4.6 Reference Manual
260
8. Toolboxes
Flexibility
Flexibility in a 3D mechanics structure can be modeled using constraint joints. All you
have to do is:
1.
Insert a joint into the editor.
2.
C lick Edit Joint to open the Joint Properties.
3.
C lick on the More button to show the advanced properties.
4.
Select the As Constraint Joint option.
5.
Now you will see the Constraint Settings button. C lick this button.
The Joint Constraint Settings dialog will open.
4.
In this dialog you can Override the General Spring Damper Values,
5.
and select the desired stiffness and damping for the joint.
20-sim 4.6 Reference Manual
261
8. Toolboxes
If you do not choose Override the General Spring Damper Values, the global settings
for constraint joints are used which can be specified in the Model Settings dialog.
Only the degrees of freedom which are fixed by the joint, can be set by spring damper
values. In the dialog above the spring damper values of an X-rotation joint are shown.
The rotation around the x-axis can not be restricted by a spring damper. If you want
to insert flexibility in all directions and rotations, use a weld joint to override the
general spring damper values.
You can choose the option Generate Global Parameters to make the spring damper
values available as global parameters.
8.1.2
Working Order
3D Mechanics Editor
From the Library tab you can drag and drop components to the Edit window. If you put
the editor in translation mode you can select the components and use the mouse to put
them in the correct position.
20-sim 4.6 Reference Manual
262
8. Toolboxes
A standard model will at least consist of some bodies and joints. The bodies have to be
connected with the joints to define the degrees of freedom of the model. The connecting
of joints and bodies can be done in the connection mode. By clicking on a body and then
on a joint a connection is defined.
If all connections are defined, you can test the possible motions of your model. Return to
the translation mode and click on a body. You will see arrows that indicate the possible
motion of the connected joint. By dragging the mouse you can make the body move.
20-sim 4.6 Reference Manual
263
8. Toolboxes
When the model is ready you can check it. When no errors are found you can update it
to 20-sim.
Generating a 20-sim Model
Checking
When your 3D dynamic model has been created and assembled, you can check for
errors by selecting the Check Model command from the Actions menu. If everything is
OK the Output will show the message "Analysis C ompleted Successfully".
Generating 20-sim Model
After the model has been checked, you can export it as a 20-sim submodel by selecting
the Generate 20-sim Model command from the Actions menu.
20-sim 4.6 Reference Manual
264
8. Toolboxes
20-sim Model
As you may know from the Joint Properties dialog, all joints have an initial value. During
analysis of your model, some joints may have been twisted. You can use the current
(twisted) configuration to generate a 20-sim model for, or reset it to its initial values
first.
Additional Outputs
For advanced users, some additional outputs may be useful. First time users are advised
not to select these outputs.
Output Filename
Use the Browse button to select a folder and a filename for the generated 20-sim model.
20-sim Scenery
In 20-sim you can use the 3D Animation Toolbox to show an animation of the
mechanical structure. You can export the structure to a scenery file, which can be loaded
in the 3D Animation Toolbox.
Don't Generate Joint Representations: Each joint is represented in the 3D Animation
as autonomous component with variables to denote the potion and orientation. For
large models you can save memory space by not exporting the joints.
Submodel Name to be used in 20-sim: The 3D Animation will use 20-sim submodel
names to identify the movements of object. You have to enter the submodel name,
that you will use for the 3D dynamic model in 20-sim.
20-sim 4.6 Reference Manual
265
8. Toolboxes
Scenery Filename: Use the Browse button to select a folder and a filename for the
generated scenery file.
8.1.3
Library
Library
The Library Tab shows all components that can be used to create your 3D Dynamic
model.
Bodies
Joints
Sensors
Actuators
Bodies
Position
When you drag and drop a body into the Edit window, its position (i.e. the position of its
reference frame) will be defined with respect to the base reference frame. You can
change the position with the mouse pointer. From the View menu click Mode and
Translation or click the
button to go to translation mode. If you put the mouse
pointer on top of the body, you can change its position by pressing the left mouse
button. If you pressing the Ctrl-button at the same time, the body will move up and
down.
You can also set the position manually by double clicking the body. This will open the
Body Properties dialog.
20-sim 4.6 Reference Manual
266
8. Toolboxes
Using this dialog you can:
change the name of the body
set the inertia parameters
change the position
change the orientation
make it a fixed body
set more options
Fixed Body
The purpose of building a 3D model in most cases is to construct some kind of
mechanism using bodies and joints. The joints make the bodies move in a particular
way, which can be inspected in the 3D Editor. Every body in 3D mechanics editor is
floating by default, unless specifically set to be attached to the fixed world, or connected
to another body by means of a joint. Any body can be set to be a fixed body by
checking the Is Fixed World option in the Body Properties dialog. C hanging the
position of a fixed body in a mechanism will change the base position of the mechanism.
Dragging the other bodies will only make the mechanism move, but not change the base
position. If you want to model a floating mechanism (e.g. a satellite in space), all bodies
should remain floating.
Orientation
To set the orientation of a body, the same procedure can be followed as for the position
of a body. If you set the Editor in Rotation mode (
), you can change the
orientation of the body with the mouse pointer. You can also use the Body Properties
dialog to set the orientation precisely by clicking the orientation button.
20-sim 4.6 Reference Manual
267
8. Toolboxes
The orientation of a body is specified by the orientation of its reference frame. You can
define this orientation using various representations.
Direction Up Vector: Using the Direction Up vector method you have to specify the Yaxis (Direction) and Z-axis (Up) of the body reference frame.
Bryant angles: Using Bryant angles we start with the initial body reference frame.
First we rotate around the X-axis of the body reference frame, then we rotate around
the Y-axis of the body reference frame en finally around the Z-axis of the body
reference frame. Bryant angles are also known as X-Y-Z relative Euler angles or
C ardan angles.
X-Y-X Euler: Using X-Y-X Euler angles we start with the initial body reference frame.
First we rotate around the X-axis of the body reference frame, then we rotate around
the Y-axis of the body reference frame en finally around the X-axis of the body
reference frame.
Euler Parameters: Using Euler parameters we start with the initial body reference
frame and rotate this frame around a vector K [X,Y,Z] about an angle theta.
Rotation Matrix: Using a 3x3 rotation matrix, you can enter 9 elements that will
transform the initial orientation of the body reference frame to the new orientation.
Inertia Properties
Each body has a mass and rotational inertia. The mass indicates the resistance of the
body to a change in position. Given a fixed force, a body with a large mass will
accelerate more slowly. This property is the same for all directions. Therefore the mass
can be indicated by a single parameter.
The rotational inertia indicates the resistance of a body to a rotation. Given a fixed
torque, a body wit a large rotational inertia will start to rotate more slowly. The
rotational inertia is not the same for all orientations. Generally, for any body three axes
can be identified that indicate a stable rotation. The rotational inertia for these three
principal axes of rotation is sufficient to describe the motion of a body. The connection of
these three principal axes of rotation is generally known as the center of mass.
20-sim 4.6 Reference Manual
268
8. Toolboxes
Any body, indifferent of its shape, which has the same mass, the same principal axes of
rotation and the same rotational inertia, will show the same dynamic behavior. That is
why you can change the representation of a body to any size, it will not change its
dynamic properties.
If you open the Body Properties Dialog you can click the Edit button to change the
inertia properties. You can set mass and the rotational inertias for each of the principle
inertia axis. By selecting the option As Global Parameter you can make the inertia
parameters available as global parameters.
The center of mass does not necessarily have to coincide with the body reference frame
and the orientation of the principal inertia axes do not have to coincide with the
orientation of the body reference frame.
20-sim 4.6 Reference Manual
269
8. Toolboxes
You can enter the offset position of the center of mass and the orientation of the
principal inertia axes, by clicking the offset button.
More Options
If you click the More button in the Body Properties dialog, options are shown which form
a shortcut for the normal way of building models. They are meant for experienced users.
First a list of connection points are shown and some buttons to edit these points.
C onnection points are used to indicate at which point a joint or other element is
connected with the body. C onnection Points are explained in more detail in the next
section.
At the bottom two options are shown. If you choose the Generate Power Interaction Port
option, a power port will be added to the body, which allows you to insert forces and
torques onto the body, from other 20-sim submodels.
The Output Absolute H-matrix option, will create an 4x4 output signal that gives the
position and orientation of the body, using an H-matrix. This signal can be connected to
other 20-sim submodels.
Joints
Properties
In order to make two bodies move with respect to each other, we have to connect them
by joints. Joints do not have any mass or rotational inertia. They only constrain the
motion of bodies. The position of a joint is indicated by its reference frame. Because the
joint position and orientation is completely determined by the bodies that are connected,
you do not have to specify any position or orientation parameters. These are
automatically derived when you make connections.
Connections
Making connections is not difficult when you understand how frames work. We will
explain this with a simple example. Suppose we have two bodies and a rotational joint.
The initial positions of the bodies and joints are indicated by their reference frames.
Now we have to define for each of the two bodies the offset to the joint. This can be
done using connection points. A connection point is in fact a new frame with an offset
from the body reference frame. As you can see, in the picture below, we have defined
C onnectionPoint1 with an offset of [x = 1, y = 1, z = -1] with respect to the Body1 and
we have defined C onnectionPoint2 with an offset of [x = 1, y = -1, z = -0.3] with respect
to Body2.
20-sim 4.6 Reference Manual
270
8. Toolboxes
Now the bodies and the joint can be assembled by changing the body positions in such a
way that the frames of the connection points coincide with the reference frame of the
joint exactly.
Suppose that Body1 is set as the reference body. Now the whole assembly will be
moved until Body1 has its original position.
20-sim 4.6 Reference Manual
271
8. Toolboxes
Creating Connections
In the 3D Mechanics Editor most of the assembly of joints and bodies is automated. You
simply have to make connections between joints and bodies. To make a connection you
have to drag and drop bodies and a joint to the Edit window. Then change to C onnection
mode (
). First click a body and then the joint it should be connected to.
The Create Connection dialog will pop to ask you for the location of the connection point.
In the connection dialog you can set the offset (both the position as well as rotation)
from the body reference frame to the connection point.
20-sim 4.6 Reference Manual
272
8. Toolboxes
The Joint Properties Dialog.
After the dialog is closed the body will automatically assemble with the joint. When two
bodies are assembled with a joint, you can view their constrained motions.
Joint Properties
When you want to change the C onnection Points after the connection has been made,
you have to double clicking the joint. This will open the Joint Properties Dialog.
You can change the name, position, orientation, and the rotation axis of the connection
points. You can also change the joint type and the initial rotation or translation of the
joint. If you lock the joints, it will not move when you want to show the possible motions
of the system.
Advanced Properties
At the bottom of the Joint Properties you can click the More button to see the advanced
properties.
20-sim 4.6 Reference Manual
273
8. Toolboxes
The advanced properties of the Joint Properties Dialog.
As C onstraint Joint: C alculate the joint using constraints. You can use constraint
joints to introduce flexibility into your 3D structure.
Power Interaction Port: add a power port to the joint to make it an actuated joint.
Output Position: C reate an output signal that gives the joint position.
Output Velocity: C reate an output signal that gives the joint velocity.
Output C onstraint Forces: C reate an output signal that gives the forces and torques
that act on the joint.
Constraint Settings
If you click the More button to see the Advanced Joint Properties, you can click the As
Constraint Joint selection box. This box allows you to manually choose to make this joint
a constraint joint. A button will be visible showing the Constraint Settings. if you click this
button a dialog is shown allowing your to override the constraint by a spring damper. In
this way you can set each individual joint by its own spring damper constants.
20-sim 4.6 Reference Manual
274
8. Toolboxes
Spring Damper
If you click the More button to see the Advanced Joint Properties, you can click the
Spring Damper button. This will allow you to add damping to a joint or a spring and
define end-stops.
Has Spring: choose this option to define a spring parallel to the joint.
Has Damping: select this option to define the damping (linear with the velocity).
Has Minimum: set an endstop at the minimum joint rotation/extension.
Has Minimum: set an endstop at the maximum joint rotation/extension.
Joint Types
Several types of joints are available in the library:
20-sim 4.6 Reference Manual
275
8. Toolboxes
Rotation Joints (Non-Actuated)
joint
description
XYZ-Rotation
Joints which rotate around the principal axes.
Hinge XYZ-Rotation
Same as XYZ-Rotation
representation.
Balljoint
connection
but
with
a
different
XYZ- Balljoints with orientations of the principal axes.
Rotation Joints (Actuated)
joint
description
XYZ-Rotation
Joints which rotate around the principal axes.
Hinge XYZ-Rotation
Same as XYZ-Rotation
representation.
but
with
a
different
Translation Joints (Non-Actuated)
joint
description
XYZ-Rotation
Joints which rotate around the principal axes.
Hinge XYZ-Rotation
Same as XYZ-Rotation
representation.
Balljoint
connection
but
with
a
different
XYZ- Balljoints with orientations of the principal axes.
Translation Joints (Actuated)
joint
description
XYZ-Translation
Joints which rotate around the principal axes.
joint
description
XYZ-Translation
Joints which rotate around the principal axes.
joint
description
Weld joint
A joint that welds two bodies together.
Free Moving Joint
Opposite of the weld joint. In practice this joint will
only be used to give a body a fixed starting
position with respect to another body.
Other Joints
20-sim 4.6 Reference Manual
276
8. Toolboxes
Sensors
Sensors are components that indicate the position or velocity of bodies as output signals.
Connecting Sensors
Sensors have to be connected with bodies, just like joints.
The position of the sensor is indicated by its connection point. The connection point is
shown automatically when you make a connection between a body and a sensor. First
change to Connection mode (
), then click the body and then click the sensor.
The Create Connection dialog will pop to ask you for the location of the connection point.
In the connection dialog you can set the offset (both the position as well as rotation)
from the body reference frame to the connection point.
20-sim 4.6 Reference Manual
277
8. Toolboxes
Sensor Types
Various sensor types are available in the library.
Position/Orientation
sensor
output signal
Position-X
A signal with the x-position of the body.
Position-Y
A signal with the y-position of the body.
Position-Z
A signal with the z-position of the body.
Position (3x1)
A signal (size 3) with the x-, y- and z-position of
the body.
H-matrix (4x4)
A 4x4 signal with the H-matrix.
Rotation (3x3)
A 3x3 signal with the rotation-matrix.
sensor
output signal
Velocity-X
A signal with the x-velocity of the body.
Velocity-Y
A signal with the y-velocity of the body.
Velocity-Z
A signal with the z-velocity of the body.
Velocity (3x1)
A signal (size 3) with the x-, y- and z-velocity of
the body.
Velocity
20-sim 4.6 Reference Manual
278
8. Toolboxes
Omega-X
A signal with the rotational velocity in x-direction of
the body.
Omega-Y
A signal with the rotational velocity in y-direction of
the body.
Omega-Z
A signal with the rotational velocity in z-direction of
the body.
Omega (3x1)
A signal (size 3) with all three rotational velocities.
sensor
output signal
Acceleration-X
A signal with the x-acceleration of the body.
Acceleration-Y
A signal with the y-acceleration of the body.
Acceleration-Z
A signal with the z-acceleration of the body.
Acceleration (3x1)
A signal (size 3) with the x-, y- and z-acceleration
of the body.
Rotational
Acceleration-X
A signal with the rotational acceleration in xdirection of the body.
Rotational
Acceleration-Y
A signal with the rotational acceleration in ydirection of the body.
Rotational
Acceleration-Z
A signal with the rotational acceleration in zdirection of the body.
Rotational
Acceleration (3x1)
A signal (size
accelerations.
Acceleration
3)
with
all
three
rotational
Jacobian Matrix
This yields the Jacobian Matrix of the connected mass.
Actuators
Actuators are components that impose a force or torque on bodies, where the force or
torque is given by a power port or input signal.
Connecting Sensors
Actuators have to be connected with bodies, just like joints.
20-sim 4.6 Reference Manual
279
8. Toolboxes
The position of the sensor is indicated by its connection point. The connection point is
shown automatically when you make a connection between a body and a sensor. First
change to Connection mode (
), then click the body and then click the sensor.
The Create Connection dialog will pop to ask you for the location of the connection point.
In the connection dialog you can set the offset (both the position as well as rotation)
from the body reference frame to the connection point.
20-sim 4.6 Reference Manual
280
8. Toolboxes
Local or Global Coordinates
For each actuator, you can change its settings, by double clicking it. This will open the
Actuator Properties dialog.
20-sim 4.6 Reference Manual
281
8. Toolboxes
8.2
Animation Toolbox
8.2.1
3D Animation
3D Animation Window
In the Simulator choose Tools and Animation Toolbox and 3D Animation to open a 3D
Animation window.
The 3D Animation window.
Editing
To start editing, from the Properties menu select 3D Properties
Properties window where you build your animation.
. This will open 3D
Running
You can run an animation by clicking the green run button
the Run command from the Replay menu.
. You can also select
At the top right of the window you see the Speed box
where you can set
the replay speed. The default speed is to replay an animation at real time but you
can set it to play an animation faster or slower.
If you have multiple camera's in your animation, you can switch camera, by clicking
the camera button
.
Ray Trace
Ray Tracing will add shadows and mirror images to a 3D Animation. From the File
menu, select RayTrace to apply Ray Tracing to the current window.
Creating Movies
From the File menu select Create Movie to create movies from your animation.
Full Screen
Right click your mouse when pointing on a 3D Animation. Select Full Screen to see
the animation in full screen. C lick the Escape button to remove the full screen view.
20-sim 4.6 Reference Manual
282
8. Toolboxes
3D Properties
The 3D Properties window allows you to define the various objects that should be shown
in a 3D Animation. The 3D Properties window can be opened, by double clicking the
mouse pointer in the Animation window or using the Properties menu.
The 3D Animation Properties window at start-up.
Menu
The menu of the 3D Animation Properties consists of three parts.
The File menu allows you to store and load scenes (parts of the object tree) and
create movies.
The Edit menu allows you to create and edit objects.
The Properties menu allows you to set the General Properties.
Lights, Cameras and Objects
Two lights and five cameras are standard available when you start a new animation. You
can delete or change these lights and cameras or add new additional lights and cameras.
Inserting new objects can be done with the Edit menu by selecting the Insert Object
command.
Object Tree
The left side of the 3D Animation Properties window shows tree-like listing of the objects
that are inserted. All objects are defined with respect to a reference frame. This can be
done hierarchically by inserting new reference frames.
20-sim 4.6 Reference Manual
283
8. Toolboxes
The 3D Animation Properties window of the model ScaraRobot.emx .
Object Attributes
On the right side of the 3D Animation Properties window shows the attributes of a
selected object (e.g. position, orientation, scaling etc.). Objects can be selected, by
clicking the mouse pointer on top of the object in the objects tree.
Show Frame
Each object has an object attached reference frame. This frame can be shown by
selecting the object and clicking the Show Frame option. This is useful for manipulating
objects. If you press the Control button while selecting the Show Frame option, all
frames in the current branch are shown. Do the same for the top reference frame to
quickly show or hide all reference frames.
Solo
C lick the Solo option, to hide all other objects. This is useful for manipulating a single
object. If you press the Control button while selecting the Solo option, all objects in the
current branch are shown. Do the same for the top reference frame to quickly show or
hide all objects.
Hidden
C lick the Hidden option, to hide a single object. This is useful for manipulating a the
other objects. If you press the Control button while selecting the Hidden option, all
objects in the current branch are hidden. Do the same for the top reference frame to
quickly hide or show all objects.
20-sim 4.6 Reference Manual
284
8. Toolboxes
Next Camera
C lick the Next C amera button to seen the next camera view.
Manipulate
C lick the Manipulate button to move an object with use of your mouse.
Selecting Objects
An object can be selected by pointing with the mouse in the object tree.
Select an object in the 3D Animation Properties window.
This selection is also shown in the 3D Animation window as a pink box around the object.
20-sim 4.6 Reference Manual
285
8. Toolboxes
Indicating the selected object.
It is also possible to select an object with the mouse by clicking in the 3D Animation
window. The selection will automatically jump to the object in the tree of the 3D
Animation Properties window.
20-sim 4.6 Reference Manual
286
8. Toolboxes
Moving Objects
To move an object, you have select it.
Select an object in the 3D Animation Properties window.
Attributes
The right side of the 3D Animation Properties window shows the attributes of a selected
object (e.g. position, orientation, scaling etc.). You can change the position or orientation
to move an object.
Manipulate
You can move an object directly by pushing the Manipulate button.
20-sim 4.6 Reference Manual
287
8. Toolboxes
Manipulate an object directly.
A set of locks will be shown below the Manipulate button. You can use them to lock one
or more directions and orientations. After this you must put the 3D Animation window on
front (click on it with the mouse) and select one of the following keys:
Ke ys
Action
right arrow
move right (positive x-direction)
left arrow
move left (negative x-direction)
up arrow
move up (positive z-direction)
down arrow
move down (negative z-direction)
Ctrl + up arrow
move forward (positive y-direction)
Ctrl + down arrow
move backward (negative y-direction)
Alt+ right arrow
yaw right (positive z-axis rotation)
Alt+ left arrow
yaw left (negative z-axis rotation)
Alt+ up arrow
roll forward (negative x-axis rotation)
Alt + down arrow
roll back (positive x-axis rotation)
Ctrl+ Alt + right arrow
pitch right (positive y-axis rotation)
Ctrl+ Alt + left arrow
pitch left (negative y-axis rotation)
20-sim 4.6 Reference Manual
288
8. Toolboxes
Keys above + Shift
Smaller steps (more accurate)
Ctrl + A
Next Camera
Scenes
In the 3D Animation Properties you can load and store scenes. Scenes are simply part of
an object tree or a complete object tree. This option can be used to obtain scenes from
other experiments or to create pre-defined environments.
Save Scene
The Save Scene command of the File menu, allows you to save a scene on file. Only the
selected object and all object below will be saved.
Load Scene
The Load Scene command of the File menu, allows you to open a scene from file and
insert it under the selected object of the object tree.
Movies
With a few mouse clicks you can create movies from an animation. Right click on the 3D
animation window and select Create Movie.
Target List
You can create movies for various purposes:
YouTube: Movies in mpg-format for placement on YouTube.
20-sim 4.6 Reference Manual
289
8. Toolboxes
Avi: Movies in avi format for use in movie editing software.
Windows Media Video: Movies for the use in Microsoft programs (e.g. Powerpoint).
Flash: Movies in flv format for the use on Internet sites.
Only Frames: For the use in advanced movie editing programs that can handle
collections of pictures
Profiles
You can create movies with three profiles (low, medium, high). The corresponding sizes
are shown in the table below.
low
medium
high
YouT ube
640 * 480
-
1280*720
Avi
640 * 480
1024*768
1920*1080
Windows Media Video
640 * 480
1024*768
1920*1080
Flash
640 * 360
1024*576
-
Only Frames
640 * 480
1024*768
1920*1080
Ray tracing will add shadows and mirror images to a 3D Animation. However ray tracing
cost a lot of processing power. If you select the option Ray Tracing, the quality of your
movie will be improved, but the time to create it will increase tremendously .
More
C hoose the More button if the standard profiles are not up to your demands. You can set
the size of a movie, the frame rate and speed up or slow down the speed.
Create Movie
C lick the Create Movie button to create a movie. The movie will be stored in the output
directory that you have specified using the filename that you have given.
20-sim 4.6 Reference Manual
290
8. Toolboxes
General Properties
Using the General Properties command of the 3D Properties window helps you to select
several options.
Background Color: C hange the background color to any desired color you like.
Background Image: Use a bitmap image for the background.
Wireframe: You can choose to show the animation as Wireframe.
Fogging: Fog in any desired color can be added to the animation. The fog is minimal
at a start plane and maximal at an end plane. You can set the distance of these
planes.
Render Type: C hoose wireframe rendering or full rendering.
Grid: You can choose to show a grid.
Frames: Set the frame scaling and thickness.
General: Show the number of frames per second and maximize the number of
frames per second.
20-sim 4.6 Reference Manual
291
8. Toolboxes
Objects
Reference Frames
All objects in a 3D Animation are be defined with respect to the top reference frame.
The top reference frame is the reference frame on top of the objects tree. If you have
multiple objects that move relative to the top reference frame but have a fixed position
and orientation to with respect to each other, it is useful to introduce an additional
reference frame. Define all the objects with fixed position and orientation with respect
to an additional reference frame and give this frame a movement with respect to the top
reference frame.
Relative reference frames.
In the objects tree frame hierarchy is shown by indentation. In the example above,
the Earth Reference Frame describes the earth motion with respect to the Sun Reference
frame. The Moon Reference Frame describes the moon motion with respect to the Earth
Reference Frame.
Each Reference Frame has a specific position, orientation and scaling. The scaling is
defined with respect to the frame one level higher in the hierarchy. In the example
above, the sphere and circle describing the Earth and the Launch Site can directly be
copied to form the Moon and the Lunar Landing Site. Only the scaling of the Moon
Reference Frame has to be set to correct values.
Properties (Specific)
Override Group Color: You can choose to give all objects that are defined in a frame
the same color.
Properties (General)
position
orientation
scaling
duplication
20-sim 4.6 Reference Manual
292
8. Toolboxes
Line
Properties (Specific)
You can set the start position and end position of the line, enter the line thickness and
set the number of circle elements.
Properties (General)
color
mesh
texture
material
duplication
20-sim 4.6 Reference Manual
293
8. Toolboxes
Cube
Properties (Specific)
You can set the position of the origin and the rib length and choose to show the inside.
Properties (General)
position
orientation
scaling
color
mesh
texture
material
duplication
20-sim 4.6 Reference Manual
294
8. Toolboxes
Sphere
Properties (Specific)
You can choose to show the inside and outside. The number of segments that are
used to draw the circle is fixed.
Properties (General)
position
orientation
scaling
color
mesh
texture
material
duplication
20-sim 4.6 Reference Manual
295
8. Toolboxes
Cylinder
Properties (Specific)
You can set the position of the origin, choose to show the inside and outside, set the
number of circle elements . A cylinder can be shown with open or closed sides.
Properties (General)
position
orientation
scaling
color
mesh
texture
material
duplication
20-sim 4.6 Reference Manual
296
8. Toolboxes
Cone
Properties (Specific)
You can set the number of circle elements and choose to show the cone with an open
or closed side.
Properties (General)
position
orientation
scaling
color
mesh
texture
material
duplication
Torus
Properties (Specific)
A Torus has some specific options:
20-sim 4.6 Reference Manual
297
8. Toolboxes
The Torus Radius denotes the length from the origin to the center of the tube.
The Tube Radius denotes the tub thickness.
With the Number of Segments you can set the total number of segments for one
revolution.
The Points Per Segment are the number of circle elements for each segment.
Properties (General)
position
orientation
scaling
color
mesh
texture
material
duplication
Spiral
Properties (Specific)
The Height is the the length of the spiral.
The Spiral Radius is the length from origin to the center of the tube.
The Tube Radius denotes the tub thickness.
The Number of Turns is the number of revolutions from bottom to top of the spiral.
This may be a non-integer value.
The Number of Segments is the total number of segments from bottom to the top of
the spiral.
The Points Per Segment are the number of circle elements for each segment.
20-sim 4.6 Reference Manual
298
8. Toolboxes
You can set the position of the origin.
Properties (General)
position
orientation
scaling
color
mesh
texture
material
duplication
Beam
Properties (Specific)
Dimensions: You can choose the Segment Length, the Width and Height of the beam.
Variable: The beam offset (in the direction of the height) is given by a vector. The
number of segments is equal to the number of vector elements. You can choose the
vector as a variable from your model.
Properties (General)
position
orientation
scaling
color
mesh
material
duplication
20-sim 4.6 Reference Manual
299
8. Toolboxes
3D-files
You can import object from files, using the 3D-files object. As soon as you insert a 3Dfiles object, 20-sim will open a file browser. Three formats are supported
STL-files (*.stl): The STL file format or stereolithography format is another widely
accepted interchange format between C AD packages.
DXF-files (*.dxf): This is AutoC AD's drawing interchange format. The DXF file format
was originally designed by AutoDesk® to represent 3D models built with AutoC AD®.
Now they are generally accepted as an interchange format between C AD packages.
Lightwave Object files (*.lwo): LightWave is a software package used for rendering
3D images, both animated and static.
Properties (Specific)
Use the Browse button to load another file .
Set the Override Color check box to give the object any desired color.
You can set the position of the origin.
Properties (General)
position
orientation
scaling
color
mesh
texture
material
duplication
20-sim 4.6 Reference Manual
300
8. Toolboxes
Square
Properties (Specific)
You can set the position of the origin.
Properties (General)
position
orientation
scaling
color
mesh
texture
material
duplication
20-sim 4.6 Reference Manual
301
8. Toolboxes
Circle
Properties (Specific)
You can set the number of circle elements .
Properties (General)
position
orientation
scaling
color
mesh
texture
material
duplication
Camera
All objects in a 3D Animation are defined with respect to the Default Lights and Cameras
frame. This frame coincides with the top Reference Frame. When you start up a 3D
animation 5 default cameras are available showing several views of the origin of this
frame.
Two cameras show the Default Lights and Cameras frame from a position of x = 5, y = 5
and z = 10. The cameras are pointed to the center of origin of the frame. The Camera
Looking At Origin will keep looking at the origin, even if its position is changed. The
Perspective Camera will not keep looking at the origin but keep its original orientation
when its position is changed.
20-sim 4.6 Reference Manual
302
8. Toolboxes
The Camera Looking At Origin and Perspective Camera.
Three Front cameras are positioned on top of each of the axes of the Default Lights and
Cameras frame. The front cameras do not show perspective. I.e. they can be used for
2D-Animation.
Properties (Specific)
Camera Properties
Plane Distance : A camera only shows objects that lie between a front plane
and a back plane. You can set the distance of these planes (seen from the
camera).
Projection: You can show all objects in perspective (objects further away look
smaller) or Orthographic (objects further away are shown equally large). You
can choose to show right hand frames or left-hand frames.
Use the slider bar to set the Zooming.
20-sim 4.6 Reference Manual
303
8. Toolboxes
LookAtProperties
When you enable the Look at Position, the camera will always look at a specific
position, regardless the position of the camera itself
You can make the look at position static or connect it to variables of your
model.
Use the Always Look up Vector to let the camera have a fixed angle of view.
Properties (General)
position
orientation
Vector
Properties (Specific)
The Vector object is a combination of a C ylinder object and a C one object. The length of
the Vector can be constant or determined by the value of the variable, the offset and the
multiplication factor. You can set the vector diameter, the cone diameter and the cone
height and set the number of circle elements . The color of the C one and the C ylinder
can be specified separately by the two color property pages. The first page is for the
C ylinder and the second page is for the C one.
Properties (General)
position
orientation
mesh
texture
material
duplication
20-sim 4.6 Reference Manual
304
8. Toolboxes
Ambient Light
An Ambient Light source illuminates everything with a predefined color, regardless of the
orientation, position, and surface characteristics of the objects available. It is
constructed by making a spot light shine everywhere.
Spot Light
A Spotlight emits a cone of light of a certain color. The cone starts at a given position
and the direction is given by the orientation. Only objects within the cone are
illuminated.
Color
Ambient color: This is the main color of point light. For a spot light this option is
turned off.
Diffuse color: This is color of point light when it shines on matt surfaces.
Specular color: This is color of point light when it is reflected in shiny surfaces.
Direction
You can select the shape of the light bundle.
Parallel: Select this option to make the light a parallel bundle (e.g. the sun
light). For a spot light this option is turned off.
Spot Exponent [Wide-Narrow]: Select this option to make the light intensity
equal in all directions (Wide) or more intensive in the center beam of the spot
light (Narrow)
Spot Angle [0..90]: Select the angle of the cone from 0 degrees (very thin
bundle) to 90 degrees (light in all directions).
Attenuation
Light attenuation defines how the intensity of the light weakens as it travels away from
the source. The attenuation is computed based on the following formula:
where k0 is the constant attenuation, k1 is the linear attenuation, k2 is the quadratic
attenuation and d is the distance from the light's position to an object.
Directional Light
A Directional Light illuminate all objects with light of equal intensity, as if it were at an
infinite distance from the objects. The directional source is commonly used to simulate
distant light sources, such as the sun. It is constructed by making a spot light shine in
parallel bundles.
20-sim 4.6 Reference Manual
305
8. Toolboxes
Properties
Position
Most objects in a 20-sim Animation can be positioned with respect to the frame one level
up in the object tree. This position can be fixed (using fixed values) or change (using
model variables) during simulation.
Orientation
All objects in a 3D Animation have an orientation. This orientation can be made visible
by showing the object attached reference frame. This orientation can be fixed (using
fixed values) or changed (using model variables) during simulation.
The orientation of an object is defined as the transformation of the frame one level up
the object tree {A} to the object attached reference frame {B}. Several methods can be
used in 20-sim to define this transformation.
DirectX
Using the DirectX method you have to specify the Y-axis and Z-axis of the frame {B} in
coordinates of frame {A}.
Bryant angles
Start with the frame {B} coincident with a known frame {A}. First rotate {B} about the
X-axis of {B} by an angle of X (rad), then rotate about the Y-axis of {B} by an angle of
Y (rad) and then rotate {B} about the Z-axis of {B} by an angle of Z (rad). Note:
Bryant angles are also known as X-Y-Z Euler angles or C ardan angles.
X-Y-X-Euler
Start with the frame {B} coincident with a known frame {A}. First rotate {B} about the
X-axis of {B} by an angle of x (rad), then rotate about the Y-axis of {B} by an angle of
y (rad) and then rotate {B} about the X-axis of {B} by an angle of z (rad).
Euler Parameters
Start with a frame {A}. Rotate this frame about a vector K [X,Y,Z]T about an angle theta
to get to the frame {B}.
Scaling
Most objects in a 20-sim Animation can be scaled in size. This scaling can be fixed (using
fixed values) or change (using model variables) during simulation.
Color
Most objects in a 20-sim Animation can be shown with a preset color. The colors can be
user defined or defined with respect to a color map.
User Defined
The additive primary colors are red (R), green (G), and blue (B). By mixing these colors
in different percentages, any other color can be created. When blue and green are
mixed, the resulting color is cyan. When blue and red are mixed, the resulting color is
magenta. If all three primary colors are mixed together, the resulting color is white.
20-sim 4.6 Reference Manual
306
8. Toolboxes
The color tab.
C olor ranges can be set from 0 to 1 or 0 to 255. C onstant values or model variables can
be chosen for each primary color. Use the multiplication and addition terms for scaling
and offset.
Color Map
The color that is chosen is defined by a color map. C olor ranges can be set from 0 to 1
or 0 to 255. A constant value or a model variable can be chosen. Use the multiplication
and addition term for scaling and offset.
20-sim 4.6 Reference Manual
307
8. Toolboxes
Mesh
The rendering option defined in the General Properties can be overridden for each
object. The options are: WireFrame, Unlit Flat, Flat and Gouraud.
20-sim 4.6 Reference Manual
308
8. Toolboxes
Texture
Using the Texture attribute, you can wrap a bitmap file around an object. Using the
browse button, you can easily select the desired bitmap file (bmp, jpg, gif, tif, etc.).
Using the transparency option you can select a color in the bitmap that should be
transparent.
Texture Origin
A texture is defined in generalized coordinates (u,v). The bottom right of the texture has
coordinates (0,0) and the top left (1,1). The offset parameters define how much offset is
used to project the bitmap. This is shown in the figure below. At the left an offset of (0,0)
is shown and at the right an offset (0.2,0.2) is shown.
Depending on the type of texture wrapping (Flat, C ylinder, Sphere or C hrome) the three
wrapping vectors () have a different meaning. This is explained in the next sections. To
facilitate the explanation in the pictures below the origin vector equals (0,0,0), the Yvector equals (0,1,0) and the Z-vector equals (0,0,1).
20-sim 4.6 Reference Manual
309
8. Toolboxes
Vectors
Using three vectors (Origin, Y-Axis and Z-Axis) and Offset parameters (X, Y) you can
define how the texture should be wrapped around an object. The vectors are defined
with reference to the object attached reference frame. The object attached reference
frame can be made visible by selecting Show Frame. The vectors use generalized
coordinates. I.e. the length, width and height of the object are defined as 1 and the
vectors are scaled accordingly.
Flat
The flat wrap conforms to the faces of an object as if the texture were a piece of rubber
that was stretched over the object. For a flat texture wrap, the effects of the various
vectors are shown in the following illustration.
The Origin vector defines the base from which the texture wrapping is
performed.
The Y-vector equals the v axis of the texture wrap.
The Z-vector is always perpendicular to the texture wrap.
Cylindrical
The cylindrical wrap treats the texture as if it were a piece of paper that is wrapped
around a cylinder so that the left edge is joined to the right edge. The object is then
placed in the middle of the cylinder and the texture is deformed inward onto the surface
of the object. For a cylindrical texture wrap, the effects of the various vectors are shown
in the following illustration.
20-sim 4.6 Reference Manual
310
8. Toolboxes
The Origin vector defines the base from which the texture wrapping is performed.
The Y-vector specifies the point on the outside of the cylinder where u equals 0.
The Z-vector specifies the axis of the cylinder.
Spherical
For a spherical wrap, the u-coordinate is derived from the angle that the vector [x y 0]
makes with the x-axis (as in the cylindrical map) and the v-coordinate from the angle
that the vector [x y z] makes with the z-axis. Note that this mapping causes distortion of
the texture at the z-axis.
The Origin vector defines the base from which the texture wrapping is performed.
The Y-vector specifies the point on the outside of the sphere where u equals 0.
The Z-vector specifies the point on the outside of the sphere where v equals 0.
Chrome
A chrome wrap allocates texture coordinates so that the texture appears to be reflected
onto the objects. The chrome wrap takes the reference frame position and uses the
vertex normals in the mesh to calculate reflected vectors. The texture u- and vcoordinates are then calculated from the intersection of these reflected vectors with an
imaginary sphere that surrounds the mesh. This gives the effect of the mesh reflecting
whatever is wrapped on the sphere.
20-sim 4.6 Reference Manual
311
8. Toolboxes
Material
A material defines how a surface reflects light. A material has two components: an
emissive property (background color) and a specular property (reflected light), whose
brightness is determined by a power setting. Using the Material tab you can set these
options.
Closed Shapes
Some objects in a 20-sim Animation can be shown as a closed shape (sides closed) or
open shape (sides open).
Circle Elements
All objects in a 20-sim Animation are build out of a set of planar surface elements.
C urved objects have to be build up out of a lot of surface elements to give the
impression of a smooth surface. For some objects you can set the amount of surface
elements used to create circular surfaces.
Attenuation
The Animation Engine in 20-sim is based on the Microsoft® Direct3D. Direct3D uses the
following formula to normalize the distance from a light source to the object surface into
a value from 0.0 to 1.0, inclusive:
20-sim 4.6 Reference Manual
312
8. Toolboxes
In the preceding formula, Dn is the normalized distance, R is the light's range, and D is
the distance, in world space, from the light source to the object surface. A normalized
distance is 1.0 at the light's source, and 0.0 at the light's range.
With the normalized distance in hand, Direct3D then applies the following formula to
calculate light attenuation over distance for point lights and spotlights:
In this attenuation formula, A is the calculated total attenuation and Dn is the normalized
distance from the light source to the object. The constant, linear and quadratic
attenuation factors act as coefficients in the formula. You can produce a wide variety of
attenuation curves by making simple adjustments to them. Most applications will set the
linear attenuation factor to 1.0 and set the remaining factors to 0.0 to produce a light
that steadily falls off over distance. Similarly, you could apply a constant attenuation
factor of 1.0 by itself to make a light that doesn't attenuate (but will still be limited by
range). The following illustration shows the three most common attenuation curves.
20-sim 4.6 Reference Manual
313
8. Toolboxes
Duplication
All objects in a 20-sim Animation can be duplicated. This property is useful when drawing
a lot of the same objects.
You can choose several options:
Number of Duplicates: Select the number of duplicates of the object.
Position Offsets: Select the position offset of the first duplicate from the original
object. This offset is repeated for every next duplicate.
Orientation Offset: Select the orientation offset of the first duplicate from the original
object. This offset is repeated for every next duplicate.
Scaling Offset: Select the scaling of the first duplicate compared to the original
object. This scaling is repeated for every next duplicate.
The example below shows a cube that is duplicated according to the specifications given
in the figure above. As shown, the first duplicate is a little larger than the original object.
The second duplicate is a little larger than the first duplicate etc.
20-sim 4.6 Reference Manual
314
8. Toolboxes
8.2.2
Graph Animation
Graph Animation
To Animate the results of a simulation in the graphical model select the Graph Animation
command from the Tools menu (Simulator). During simulation, the thickness and color
of bonds and signals will correspond with the values they carry.
The color of a bond or signal always corresponds with the sign, red for negative values
and green for positive values. The thickness of signals corresponds with the value. For
signals that is obvious but for bonds or connections carry two variables: effort and flow
(also know as across and through). For bonds and connections you can choose to let the
thickness correspond with the effort, flow or power (effort*flow), depending on the
Animation command that was chosen.
20-sim 4.6 Reference Manual
315
8. Toolboxes
You can start Animation in the Simulator:
1.
Run a simulation until you are satisfied with the results.
2.
From the Tools menu, select Animation Toolbox then Graph Animation.
3.
A menu pops up. C hoose the options you like and click OK to start Animation.
20-sim 4.6 Reference Manual
316
8. Toolboxes
Graph Animation Menu
Items
Animation Kind: For signals, the thickness always corresponds with their value. For
bonds and connections you can choose. Select here to what the thickness of bonds
and connections should represent: effort, flow or power (effort*flow).
Animation Ranges: The thickness of bonds and signals can vary from 1 to 5 pixels.
Select here the range that should correspond with a thickness of 5 pixels.
20-sim 4.6 Reference Manual
317
8. Toolboxes
8.3
Control Toolbox
8.3.1
Controller Design Editor
Controller Design Editor
The 20-sim Controller Design Editor allows you to enter or edit linear time-invariant
models of a plant with control loop. The control loop is separated in a compensator,
prefilter and measurement. You can open the Controller Design Editor from the Tools
menu of the 20-sim Editor or by clicking Go Down on a C ontrolledLinearSystem model
that was inserted in the Editor.
Sub System
You can choose to show a single element in the loop:
Plant (P), Compensator (C), Prefilter (F) or Measurement (M)
or view the response of the system:
Response (H), Loop Transfer (L), Sensitivity (S), Compl. Sensitivity (T),
Plant Sensitivity (PS) or Control Sensititvity (CS).
20-sim 4.6 Reference Manual
318
8. Toolboxes
The corresponding transfer function is show in the editor.
Additional Ports
Select one of the radio buttons Input Disturbance, Output Disturbance,
Measurement Dist. or Feedforward. The first three options allow you to use external
disturbance in your model. The last option allows you to use an external feedforward
controller (e.g. a B-Spline network). The selected inputs are shown in the picture.
System Description
Pressing the Edit button will open a dialog for editing the linear system. Each
description (State Space, Transfer Function, Zeros Poles Gain or Eigen Frequency)
has a special dialog and can be used to specify continuous-time and discrete-time
systems.
In the 20-sim Simulator, out of an existing (non-linear) model a symbolic linearsystem can be derived by means of linearization. This means that the relevant model
parameters are preserved in the Linear System and the parameters button
be used to change parameters.
can
Import/Export
Pressing the s<->z button
will transform a continuous-time linear system
into a discrete-time linear system and back.
Pressing the Filter button opens the Filter Editor, where a filter can be designed. This
filter can then be combined with the current linear system or replace the current
linear system. If the linear system is a discrete-time system, the designed analog
filter is automatically transferred into its digital equivalent.
Pressing the From Matlab button
and the To Matlab button
allows
for an instant exchange of the linear system with the Matlab workspace. Information
is transferred numerically (no parameter relations are preserved)
The
button is only active when a Linear System has been imported through
linearization. C licking the button will import parameters from the simulation.
The
button is only active when a Linear System has been imported through
linearization. C licking the button will export the current parameters to the simulation.
Plots
You can inspect the time- and frequency responses of the selected transfer function
using:
Step Response
Bode Plot
Nyquist Plot
Nichols C hart
Poles and Zeros (including root locus)
Output
C licking the 20-sim button will export the linear system as a new 20-sim submodel.
C licking the Matlab button will export the 20-sim Linear System to a Matlab m-file. If
the Linear System is symbolic, all parameter relations are preserved.
20-sim 4.6 Reference Manual
319
8. Toolboxes
State Space Models
State space models use linear differential equations (continuous) or difference equations
(discrete) to describe system dynamics. They are of the form:
(continuous)
(discrete)
with for example:
where x is the state vector and u and y are the input and output vectors. These models
may arise from the equation of physics, from state space identification or as the result of
linearization.
You can enter state space models by selecting the State Space button and clicking the
Edit button.
20-sim 4.6 Reference Manual
320
8. Toolboxes
This opens an editor in which you can enter the A, B, C and D matrices. Depending on
the selection of the Discrete Linear System check box (and Sample Time) the system is
a continuous-time or discrete-time system. You can enter the matrix elements in the
white space areas. Separate column elements with Spaces or C ommas. Enter new rows
by clicking the Enter key (new line) or using a semicolon. Brackets ( e.g. [ ... ] ) may be
used to denote the a matrix or vector.
The A-matrix, shown in the figure above can for example be entered as:
01
-0.5 -1
or
0,1;-0.5,-1
or
[0,1;
-0.5,-1]
Output Delay
To inspect the effects of time delay in your model, you can add output delay. The result
will be visible in the various plots that you can show of a linear system. The unit of the
output delay is seconds.
Discrete Sample Time
If you want to transfer a linear system from continuous time to discrete time directly
(i.e. replace the s by a z), select Discrete Sample time and fill in the sample time value.
You can also transfer back directly by deselecting Discrete Sample time.
Commands
Help: Open the help file.
Apply: Apply the current changes of the system, recalculate each plot that is active
(step, Bode, Nyquist, Nichols, pole zero).
OK: Apply the current changes of the system, recalculate each plot that is active
(step, Bode, Nyquist, Nichols, pole zero) and close the editor.
Cancel: Do not apply any changes to the system and close the editor.
20-sim 4.6 Reference Manual
321
8. Toolboxes
Transfer Functions
A continuous time or discrete time SISO transfer function:
(continuous)
(discrete)
is characterized by its numerator n and denominator d, both polynomials of the variable
s or z.
You can enter transfer functions by selecting the Transfer Function button and clicking
the Edit button.
20-sim 4.6 Reference Manual
322
8. Toolboxes
This opens an editor in which you can enter the coefficients of the numerator and
denominator polynomials. You can enter the elements in the white space areas.
Separate the elements with Spaces. Polynomials should be entered in descending
powers of s or z. The Steady State Gain, Root Locus Gain and System Gain are
parameters, that are automatically derived from the transfer function.
In the editor shown above the transfer function
was given. You can enter the coefficients as:
0.1 0.1
and
1 1 0.5
or
0.1,0.1
and
1,1,0.5
Output Delay
To inspect the effects of time delay in your model, you can add output delay. The result
will be visible in the various plots that you can show of a linear system. The unit of the
output delay is seconds.
Discrete Sample Time
If you want to transfer a linear system from continuous time to discrete time directly
(i.e. replace the s by a z), select Discrete Sample time and fill in the sample time value.
You can also transfer back directly by deselecting Discrete Sample time.
20-sim 4.6 Reference Manual
323
8. Toolboxes
Commands
Help: Open the help file.
Apply: Apply the current changes of the system, recalculate each plot that is active
(step, Bode, Nyquist, Nichols, pole zero).
OK: Apply the current changes of the system, recalculate each plot that is active
(step, Bode, Nyquist, Nichols, pole zero) and close the editor.
Cancel: Do not apply any changes to the system and close the editor.
Zeros and Poles
A continuous-time SISO transfer function can described by the transfer function:
This transfer function can be rewritten in pole zero notation with
where pi .. p1 are the poles and zi .. z1 are the zeros and KRL is the Root Locus Gain of
the system. The same can be done for a discrete-time SISO transfer function.
20-sim 4.6 Reference Manual
324
8. Toolboxes
You can enter zeros and poles by selecting the Zeros & Poles button and clicking the Edit
button.
20-sim 4.6 Reference Manual
325
8. Toolboxes
This opens an editor in which you can enter the real and imaginary parts of the zeros
and poles as well as the Root Locus Gain. If preferred, you can also enter the System
Gain. Note that zeros and poles always have conjugate when the imaginary part is nonzero. I.e. when you enter a pole with imaginary part 0.5 an extra pole is added with
imaginary part -0.5.
Output Delay
To inspect the effects of time delay in your model, you can add output delay. The result
will be visible in the various plots that you can show of a linear system. The unit of the
output delay is seconds.
Discrete Sample Time
If you want to transfer a linear system from continuous time to discrete time directly
(i.e. replace the s by a z), select Discrete Sample time and fill in the sample time value.
You can also transfer back directly by deselecting Discrete Sample time.
Commands
Add/Delete: Add or delete selected poles or zeros.
Help: Open the help file.
Apply: Apply the current changes of the system, recalculate each plot that is active
(step, Bode, Nyquist, Nichols, pole zero).
OK: Apply the current changes of the system, recalculate each plot that is active
(step, Bode, Nyquist, Nichols, pole zero) and close the editor.
Cancel: Do not apply any changes to the system and close the editor.
20-sim 4.6 Reference Manual
326
8. Toolboxes
Eigen Frequencies
The Eigen Frequencies view is closely related to the pole zero notation and bode plot. It
shows the resonance frequencies and anti-resonance frequencies that result from the
given poles and zeros as well as some characteristic parameters from the bode plot.
You can enter transfer functions by selecting the Eigen Freqs. button and clicking the Edit
button.
20-sim 4.6 Reference Manual
327
8. Toolboxes
Step Response
The Step Response command calculates the systems response y on a unit step input:
u = 0 (time < 0 )
u = 1 (time >= 0 )
20-sim automatically generates an appropriate range for the time response, based on
the system dynamics. With the Plot Properties command (right mouse menu), you can
change this horizon and recalculate the step response (click the Step command again).
Plot Options
Using the right mouse menu, you can use several options:
Plot Properties: Set the general plot properties for the step response and specify the
curve properties.
Numerical Values: Inspect numerical values.
Step Characteristics: Display rise time, overshoot, settling time and the steady state
value of the step response.
Copy to Clipboard: C opy the plot to the windows clipboard.
Print: Print the plot.
Zoom in: Show a detail of the plot.
Zoom out: Show a larger portion of the plot.
Zoom Normal: Show the complete plot.
20-sim 4.6 Reference Manual
328
8. Toolboxes
Bode Plots
Bode Plots show the amplitude and phase of a linear system as function of the
frequency. Bode plots can be shown for every 20-sim model through Linearization.
During Linearization you are asked to enter the input variable and output variable for
which linearization should be performed. After that the linear system is calculated and
shown in the Linear System Editor. From the Linear System Editor you can generate a
bode plot. These actions can also be predefined using the Frequency Response
command of the Properties menu.
20-sim automatically generates a range of logarithmically displayed frequencies, based
on the system dynamics. With the Plot Properties command (right mouse menu),
you can change this horizon and recalculate the bode response (click the Bode command
again).
The magnitude part of the plot can be displayed in dB or in absolute values. The phase
part can be displayed in radians or degrees. The frequency can be displayed in radians
per second or in Hz.
Plot Options
Using the toolbar or the right mouse menu, you can use various options:
Plot Properties: Set the plot properties.
Numerical Values: Inspect numerical values.
Magnitude (dB): Display magnitude in decibels
Magnitude (-): Display magnitude in absolute values.
Phase (rad): Display phase in radians.
Phase (deg): Display phase in degrees.
Frequency (rad/sec): Display frequency in radians per second.
20-sim 4.6 Reference Manual
329
8. Toolboxes
Frequency (Hz): Display frequency in Hz.
Phase/Gain Margins: Display the gain and phase margins.
Modulus Margin: Display the Modulus Margin.
Unwrap Phase: Display the phase plot as a continuous plot by selecting this option or
as a folded plot between -180 and 180 deg. by deselecting this option.
Peak Response: Display the peak response.
Copy to Clipboard: C opy the plot to the windows clipboard.
Print: Print the plot.
Zoom in: Show a detail of the plot.
Zoom out: Show a larger portion of the plot.
Zoom Normal: Show the complete plot.
Pole Zero Diagram
The Pole Zero command plot the poles and zeros of a system and computes the root
locus plot.
20-sim automatically generates a range of real and imaginary parts, based on the
system dynamics. With the Plot Properties command (right mouse menu), you can
change this horizon and recalculate the pole zero diagram (click the Pole Zero
command again).
Root Locus
You can show the rootlocus plot by selecting Root Locus from the right mouse menu.
Inspect the root locus gain by selecting Numerical Values from the right mouse menu.
20-sim 4.6 Reference Manual
330
8. Toolboxes
Plot Options
Using the right mouse menu, you can use several options:
Plot Properties: Set the plot properties.
Numerical Values: Inspect numerical values.
Root Locus: Show or hide the root locus plot.
Copy to Clipboard: C opy the plot to the windows clipboard.
Print: Print the plot.
Zoom in: Show a detail of the plot.
Zoom out: Show a larger portion of the plot.
Zoom Normal: Show the complete plot.
Nichols Chart
The Nichols command computes the Nichols chart of a system.
20-sim automatically generates a range of logarithmically displayed frequencies, based
on the system dynamics. With the Plot Properties command (right mouse menu), you
can change this horizon and recalculate the Nichols chart (click the Nichols command
again). The magnitude part of the plot can be displayed in decibels (dB) or in absolute
values. The phase part can be displayed in radians or degrees.
Plot Options
Using the right mouse menu, you can use several options:
Plot Properties: Set the plot properties.
20-sim 4.6 Reference Manual
331
8. Toolboxes
Numerical Values: Inspect numerical values.
Magnitude (dB): Display magnitude in decibels
Magnitude (-): Display magnitude in absolute values.
Phase (rad): Display phase in radians.
Phase (deg): Display phase in degrees.
Frequency (rad/sec): Display frequency in radians per second.
Frequency (Hz): Display frequency in Hz.
Phase/Gain Margins: Display the gain and phase margins.
Modulus Margin: Display the Modulus Margin.
Copy to Clipboard: C opy the plot to the windows clipboard.
Print: Print the plot.
Zoom in: Show a detail of the plot.
Zoom out: Show a larger portion of the plot.
Zoom Normal: Show the complete plot.
Nyquist Diagram
The Nyquist command computes the Nyquist plot of a system.
20-sim automatically generates a range of real and imaginary parts, based on the
system dynamics. With the Plot Properties command (right mouse menu), you can
change this horizon and recalculate the Nyquist diagram (click the Nyquist command
again).
Plot Options
Using the right mouse menu, you can use several options:
20-sim 4.6 Reference Manual
332
8. Toolboxes
Plot Properties: Set the plot properties.
Numerical Values: Inspect numerical values.
Phase/Gain Margins: Display the gain and phase margins.
Modulus Margin: Display the Modulus Margin.
Copy to Clipboard: C opy the plot to the windows clipboard.
Print: Print the plot.
Zoom in: Show a detail of the plot.
Zoom out: Show a larger portion of the plot.
Zoom Normal: Show the complete plot.
8.3.2
MLP Network Editor
Neural Networks
Human brains consist of billions of neurons that continually process information. Each
neuron is like a tiny computer of limited capability that processes input information from
other neurons into output information to other neurons. C onnected together, these
neurons form the most intelligent system known.
For some years now, researchers have been developing models that mimic the activity
of neurons to produce a form of artificial intelligence. These "Neural Networks" are
formed from tens or hundreds of simulated neurons connected together in much the
same way as the brain's neurons. Just like the neurons of the brain, artificial neurons
can change their response to a given set of inputs, or "learn".
In the past many learning algorithms have been developed, mostly with limited success.
The introduction of the backpropagation paradigm, however, appeared a turning point. It
is an extremely effective learning tool that can be applied to a wide variety of problems.
The backpropagation paradigm require supervised training. This means neural networks
must be trained by repeatedly presenting examples to the network. Each example
includes both inputs (information you would use to make a decision) and desired outputs
(the resulting decision, prediction, or response). Based on a calculation on the inputs,
the desired outputs and the networks own response to the inputs, the backpropagation
paradigms tries to adapt the response of each neuron to achieve an improved neural
network behavior. This trial-and-error process continues until the network reaches a
specified level of accuracy.
Once a network is trained and tested it's neurons can be "frozen". This means the
neurons ability to learn" or adapt is stopped. The network can then be used to perform
the task it was trained for.
20-sim 4.6 Reference Manual
333
8. Toolboxes
BackPropagation Networks
In backpropagation type neural networks, the neurons or "nodes" are grouped in layers.
We can distinct three groups of layers in a backpropagation type neural network: one
input layer, one or more hidden layers and one output layer. The nodes between two
adjacent layers are interconnected. Fully connected networks occur when each node of a
layer is connected with each node of the adjacent layer.
As the figure shows, information (i.e. input signals) enters the network through the input
layer. The sole purpose of the input layer is to distribute the information to the hidden
layers. The nodes of the hidden layers do the actual processing. The processed
information is captured by the nodes of the output layer, and transported as output
signals to the world outside.
y= f ( w1*i1 + w2*i2 + w3*i3 + ... + wn*in )
The nodes of the hidden layers process information by applying factors (weights) to each
input. This is shown in the figure above. The sum of the weighted input information (S) is
applied to an output function. The result is distributed to the nodes of the next layer.
When the network is in being trained, the weights of each node are adapted according to
the backproagation paradigm. When the network is in operation, the weights are
constant.
Depending on the kind neural network, various topologies can be discerned. The 20-sim
Neural Network Editor supports two well-known networks:
1.
Adaptive B-spline networks
2.
Multi-layer Perceptron networks
20-sim 4.6 Reference Manual
334
8. Toolboxes
Introduction to MLP Networks
The basic element of the Multi Layer Perceptron (MLP) neural network, is the artificial
neuron. An artificial neuron, is a unit that performs a simple mathematical operation on
its inputs. In the figure below, the neuron is graphically presented.
The input, x, of the neuron consists of the variables x1 ... xn and a bias term, known as
the momentum constant, which is equal to 1. Each of the input values is multiplied by
a weight, wi , after which the results are added. On the result, a simple mathematical
function, f (x), is performed. This function is also known as the activation function.
The calculations the neuron performs are thus given by:
y = f ( w0 + x1*w1 + ... + xn*wn )
Numerous choices for the functions exist. Frequently used implementations are the
Sigmoid functions:
f(u) = 1 / (1 + e-u )
f (u) = c1 * tanh ( c2 * u)
20-sim 4.6 Reference Manual
335
8. Toolboxes
(in the picture c1 = c2 = 1)
MLP Network
An MLP network, as any type of back-propagation network can consist of many neurons,
which are ordered in layers. The neurons in the hidden layers do the actual processing,
while the neurons in the input and output layer merely distribute and collect the signals.
Although many hidden layers can be used, it has been shown that an MLP with one
hidden layer can approximate any continuous function. Therefore in 20-sim, the MLP
networks only have one hidden layer.
Training the MLP network
The MLP network is trained by adapting the weights. During training the network output
is compared with a desired output. The error between these two signals is used to adapt
the weights. This rate of adaptation is controlled by the learning rate. A high learning
rate will make the network adapt its weights quickly, but will make it potentially
unstable. Setting the learning rate to zero, will make the network keep its weights
constant.
20-sim 4.6 Reference Manual
336
8. Toolboxes
How to use the MLP Editor
The MLP Editor can be used to define a 20-sim Multi Layer Perceptron (MLP) network.
The editor is opened when you try to edit this submodel (using the Go Down command).
General Settings
Network Name: this is the local name of the submodel representing the MLP network
(this option is not yet supported).
Number Hidden Neurons: The MLP network specified by this editor has one layer of
hidden neurons. You can specify here the number of neurons that should be used.
Learning Rate: Specify the learning rate that should be used during training. If you
do not want the network to learn, enter a zero value here.
Initial Weights Fill Scale: To start proper learning of the network, all initial weights will
be given a random value (unequal to zero!) between -scale and +scale. You can
enter the scale factor here.
Activation Function Type: Select one of the following activation functions
Unipolar Sigmoid: act = 1/(1 + exp(-v) )
Bipolar Sigmoid: act = const2*tanh(const1*v)
Bipolar Sigmoid Activation Function Scale: If a Bipolar Sigmoid was chosen as the
activation function, you can enter here the values of const1 and const2.
Momentum Constant: Select the momentum constant here.
Load Weights at Start of Simulation: Select this option, if you want to use predefined
weights stored on file (saved in a previous run). Before each simulation run, you will
be asked to enter the filename of this weights file.
Save Weights at Start of Simulation: Select this option, if you want to store the
weights on file. After each simulation run, you will be asked to enter the filename of
this weights file.
Network is Discrete: Select this option if the B-spline network is connected with
discrete-time models. Deselect this option if the network is connected with continuous
models.
20-sim 4.6 Reference Manual
337
8. Toolboxes
Inputs
Add Input: Add a new input to the network. You will we prompted to give a specific
input name. This name will be shown in the Inputs list.
Delete Input: Delete the input selected in the Inputs list.
Outputs
Add Output: Add a new output to the network. You will we prompted to give a specific
output name. This name will be shown in the Outputs list.
Delete Output: Delete the output selected in the Outputs list.
8.3.3
B-Spline Network Editor
Neural Networks
Human brains consist of billions of neurons that continually process information. Each
neuron is like a tiny computer of limited capability that processes input information from
other neurons into output information to other neurons. C onnected together, these
neurons form the most intelligent system known.
For some years now, researchers have been developing models that mimic the activity
of neurons to produce a form of artificial intelligence. These "Neural Networks" are
formed from tens or hundreds of simulated neurons connected together in much the
same way as the brain's neurons. Just like the neurons of the brain, artificial neurons
can change their response to a given set of inputs, or "learn".
In the past many learning algorithms have been developed, mostly with limited success.
The introduction of the backpropagation paradigm, however, appeared a turning point. It
is an extremely effective learning tool that can be applied to a wide variety of problems.
The backpropagation paradigm require supervised training. This means neural networks
must be trained by repeatedly presenting examples to the network. Each example
includes both inputs (information you would use to make a decision) and desired outputs
(the resulting decision, prediction, or response). Based on a calculation on the inputs,
the desired outputs and the networks own response to the inputs, the backpropagation
paradigms tries to adapt the response of each neuron to achieve an improved neural
network behavior. This trial-and-error process continues until the network reaches a
specified level of accuracy.
Once a network is trained and tested it's neurons can be "frozen". This means the
neurons ability to learn" or adapt is stopped. The network can then be used to perform
the task it was trained for.
Introduction to B-Spline Networks
One-dimensional B-spline network
An adaptive B-spline network can be used to relate k inputs and a single output y on a
restricted domain of the input space. The following network shows a realization with one
input:
20-sim 4.6 Reference Manual
338
8. Toolboxes
The network is shown with two hidden layers. Some authors prefer to show a B-spline
network with only one hidden layer. For a proper understanding of multi-dimensional Bspline networks we prefer to show the network with two hidden layers.
The first hidden layer distributes the inputs over several nodes. In the figure above input
1 is distributed over n nodes. Each node of this layer has only one input. To this input a
"basis function" F is applied. As basis functions, B-splines are used of any desired order.
An N-th order B-spline function consists of pieces of (N-1)th order polynomials, such that
the resulting function is (N-1) times differentiable. The figure below shows examples of
B-spline functions of different order. A spline function differs from zero on a finite
interval.
The second hidden layer also consists of n nodes. Each node of this layer has only one
input. To this input a function G is applied which is merely a multiplication by a weight:
G =w*i
The output node sums the results of all second hidden layer nodes. When the spline
functions of the various nodes are properly spaced, every one dimensional function can
be approximated. This is shown in the figure below where the various splines (F1 to Fn)
combined with the various weights (w1 to wn), together form an output function.
20-sim 4.6 Reference Manual
339
8. Toolboxes
Two-dimensional B-spline network
Two-dimensional B-spline networks have two input nodes. The first hidden layer, as with
the one-dimensional network, consists of nodes, to which a basis function F is applied.
This is shown in the figure below. To the first input a group of n nodes are applied, and
to the second input a group of m nodes are applied.
The second hidden layer now consists of nodes which each have two inputs. For every
combination of a node from one group and and a node from the second group, a node
exists. To each node of the second hidden layer, a function G is applied which is merely
a multiplication of the two inputs multiplied by a weight:
G = w * i1 * i2
Again the output node sums the results of all second hidden layer nodes. When the
spline functions of the various nodes are properly spaced, every two dimensional
function can be approximated. The figure below shows the spacing of various spline
functions of the two inputs and one output of a node of the second hidden layer.
20-sim 4.6 Reference Manual
340
8. Toolboxes
The output node sums the results of all second hidden layer nodes. When the spline
functions of the various nodes are properly spaced, every two dimensional function can
be approximated. This is shown in the figure below.
More-dimensional B-spline networks
In a same way more dimensional B-spline networks can be created, using more inputs.
The 20-sim B-spline Editor supports networks with up to 256 inputs and one output.
Training the B-spline network
The B-spline network is trained by adapting the weights. During training the network
output is compared with a desired output. The error between these two signals is used to
adapt the weights. This rate of adaptation is controlled by the learning rate. A high
learning rate will make the network adapt its weights quickly, but will make it potentially
unstable. Setting the learning rate to zero, will make the network keep its weights
constant. Learning of B-spline networks can either be done after each sample (learn at
each sample), or after series of samples (learn after leaving spline).
20-sim 4.6 Reference Manual
341
8. Toolboxes
Learn at each Sample
When learning at each sample, after every sample the weights are adapted according
to:
Given a certain input (x), only a limited number of splines Fi (x) are nonzero. Therefore
only a few weights are adapted each sample.
Learn after Leaving Spline
When learning after leaving a spline, the network will keep track of the input (x) and the
corresponding nonzero splines Fi (x). For each nonzero spline, a sample will be stored
consisting of the input (x), the output (y) and desired output (yd). Only after the input
has left the region where a spline is nonzero, its weight is updated according to:
Here n is the number of samples that have been taken.
20-sim 4.6 Reference Manual
342
8. Toolboxes
How to use the BSpline Editor
The B-Spline Editor can be used to define a 20-sim B-Spline network. The editor is
opened when you try to edit this submodel (using the Go Down command).
General Settings
Network Name: this is the local name of the submodel representing the B-Spline
network (this option is not yet supported).
Order: Enter the order of the B-Splines that must be used.
Learn at Each Sample: Select this option if you want the network to adapt the
weights after every simulation step
Learn after leaving Spline: Select this option if you want the network to adapt the
weights only leaving the spline region.
Learning Rate: Specify the learning rate that should be used during training. If you
do not want the network to learn, enter a zero value here.
Apply Regularization: This option is not yet supported.
Load Weights at Start of Simulation: Select this option, if you want to use predefined
weights stored on file (saved in a previous run). Before each simulation run, you will
be asked to enter the filename of this weights file.
Save Weights at End of Simulation: Select this option, if you want to store the weights
on file. After each simulation run, you will be asked to enter the filename of this
weights file.
20-sim 4.6 Reference Manual
343
8. Toolboxes
Network is Discrete: Select this option if the B-spline network is connected with
discrete-time models. Deselect this option if the network is connected with continuous
models.
Input Settings
The tabs shown in the editor is used to specify the inputs of the network. Each tab shows
the specific settings of that input.
Add Input: Add a new input to the network. A new tab will be added with default
settings.
Delete Input: Delete the input defined in the selected tab (the tab that is in front).
Each input is associated with a certain number of splines. To give the user more
flexibility, each input can be divided in certain regions that each have their own density
of splines.
Add: Add a new region of splines.
Delete: Delete the selected region of splines.
Split: Split the selected region into two regions.
Each region can be edited. Just select it from the Regions list and use the following
options:
Upper / Lower: The upper and lower bound of a region.
Number of Splines: The number of splines. The more splines you choose, the more
accurate will the network output be, for this region of inputs.
Running a 1-D B-Spline Network
Now we have trained the B-spline network and saved the weights. We can run the
network with every desired input. We only have to keep in mind that the network was
defined for input signals between 0 and 10.
1.
In the Editor from the File menu select Open.
2.
In the model library choose Examples\C ontrol\Neural Networks
3.
Select the model 1DBSplineNetwork-Run.emx. Now the predefined model will be
opened.
20-sim 4.6 Reference Manual
344
8. Toolboxes
As you can see, this is exactly the same model as used for training, but now a ramp
input is used.
4.
From the menu select Model and Start Simulator. Now a Simulator will be opened
with the predefined experiment loaded.
5.
From Simulator menu click Simulation and Run. Do not save the weights file at
the end of the run! The results will look like:
20-sim 4.6 Reference Manual
345
8. Toolboxes
As you can see, the B-Spline Network still has its training settings and still prompts for a
weight file at the end of the simulation. Now we are going to change the settings of the
B-Spline Network.
6.
Open the B-Spline Editor (select the model, Go Down). To create a normal run with
the network, we have to set the learning rate to zero, and load the weights file
before simulation. C hange the settings of the network, until it looks like:
20-sim 4.6 Reference Manual
346
8. Toolboxes
7.
C lick OK to close the B-Spline Editor. From the Editor menu click Model and Check
Complete Model. This will implement the changed settings.
8.
Return to the Simulator and click Simulation and Run. Before the run, an Open
dialog will asking you to enter the name of the Weights File. This is a file that
contains all the weights of the trained B-Spline network. Use the file that you saved
during training, or the predefined weights file 1DBSplineNetwork.wgt. The simulation
results will look like:
As you can see the function is approximated by the B-Spline network by 10 first order
splines.
20-sim 4.6 Reference Manual
347
8. Toolboxes
Training a 1-D B-Spline Network
Non Linear Function
In this lesson we will use a B-spline network with one input to approximate the simple
non-linear function:
F = input2
The input, x , of this function ranges from 0 to 10. It will be approximated by a B-Spline
network with one input. As is shown in the figure below (left), 10 first order B-splines are
used. The tenth B-spline is indicate with fat lines. The output of the B-spline network is a
combination of all ten B-Splines. In other words, the non-linear function will be
approximated by 10 intervals of constant value.
20-sim 4.6 Reference Manual
348
8. Toolboxes
At the start the B-spline has undefined weights. They can either be chosen at random
values or all set to zero. A normal session should therefore start with training the
network to adjust the weights to give a best approximation of the non-linear function.
With these weights we can run the network with any desired input signal.
Defining the B-Spline Network
We will use the model below to train the B-spline network. It has already been prepared
for you.
20-sim 4.6 Reference Manual
349
8. Toolboxes
1.
In the Editor from the File menu select Open.
2.
In the model library choose Examples\C ontrol\Neural Networks
3.
Select the model 1DBSplineNetwork-Train.emx. Now the predefined model will be
opened.
4.
From the menu select Model and Start Simulator. Now a Simulator will be opened
with the predefined experiment loaded.
5.
From Simulator menu click Simulation and Run. The results will look like:
As you can see, the B-Spline output is zero and there is no learning. Now we are going
to change the settings of the B-Spline Network.
Training the Network
6.
Return to the Editor. Select the BSplineNetwork model and click GoDown from the
Model menu. Now the B-Spline Editor will pop-up. C hange the settings (Network
Order, Learning Rate, Input Upper Limit, Save Weights) until it looks like:
20-sim 4.6 Reference Manual
350
8. Toolboxes
7.
C lick OK to close the B-Spline Editor. Not that the icon of the BSplineNetwork model
has changed to correspond with the first order splines that are used. From the Editor
menu click Model and Check Complete Model. This will implement the changes in
settings.
8.
Return to the Simulator and click Simulation and Run. The results will look like:
As you can see the error rapidly descent, due to the network learning. After the
Simulation Run, Save dialog opens, asking you to enter a name for the Weights File. This
is a file that contains all the weights of the trained B-Spline network. We can use these
weights for normal runs with the network.
20-sim 4.6 Reference Manual
351
8. Toolboxes
9.
Enter file name (do not use the predefined weights file!), e.g. test.wgt and click
Save.
10. C lose the Simulator.
Now all is prepared to perform a normal run with the Network.
8.3.4
Filter Editor
Filter Editor
The Filter Editor of 20-sim allows you to create continuous-time filters and controllers.
The result is a linear system presented in the Linear System Editor of 20-sim. The filter
can also be applied to an existing linear system.
You can open the C ontroller Design Editor from the Tools menu of the 20-sim Editor or
by clicking Go Down on a Filter model.
Procedure
1.
Select a filter or controller of your choice from the list of available filters and
controllers.
Filters
Generic Filter
Lead Filter
Lag Filter
Low Pass First Order Filter
Low Pass Second Order Filter
20-sim 4.6 Reference Manual
352
8. Toolboxes
High Pass First Order Filter
High Pass Second Order Filter
Notch Filter
Universal Notch Filter
Controllers
P C ontroller
I C ontroller
D C ontroller
PI C ontroller
PD C ontroller
PID C ontroller
PID-1 C ontroller
PID-2 C ontroller
PID C ompensator
A short description of the selected filter will be given in the description field. Depending
on the filter that was chosen three or more parameters will be shown.
2.
The second step is to fill in the desired parameters.
3.
C hoose the desired output:
4.
Select the Linear System Editor button to export the filter to the Linear System
Editor.
5.
Select the OK button to store the filter model on file or update the filter model in the
Editor.
Controllers
P-Controller
The P C ontroller can be used to create an additional gain for a linear system.
Gain Kp:The controller gain Kp determines the amount of gain the controller adds for
each frequency.
Transfer function of the controller:
20-sim 4.6 Reference Manual
353
8. Toolboxes
I-Controller
The I C ontroller can be used to create an almost ideal integrator (when the frequency
goes to zero).
Gain Ki: The filter gain Ki determines the frequency gain of the controller at
frequency w = 1 [rad/s].
Frequency fi: The integration behavior of the controller stops at frequency fi in Hz. A
decrease of this frequency corresponds to a more pure integration behavior.
Transfer function of the controller
D-Controller
The D C ontroller can be used to create an almost ideal derivative (when the frequency
goes to infinity).
Gain Kd: The controller gain Kd determines the frequency gain of the controller at
frequency w = 1 [rad/s].
Frequency fd: The differentiation behavior of the controller stops at frequency fd in
Hz. An increase of this frequency corresponds to a more pure differentiation
behavior, reducing the tameness of the controller.
Transfer function of the controller
PD-Controller
The PD C ontroller consists of a differentiator with proportional gain.
Gain Kp: The controller gain Kp determines the low frequency gain of the controller.
Gain Kd: The controller gain Kd determines the gain of the controller at frequency w
= 1 [rad/s].
Frequency fd: The differentiation behavior of the controller stops at frequency fd in
Hz. An increase of this frequency corresponds to a more pure differentiation
behavior, reducing the tameness of the controller.
Transfer function of the controller:
that equals
20-sim 4.6 Reference Manual
354
8. Toolboxes
PI-Controller
The PI C ontroller consists of an integrator with a proportional gain.
Gain Kp: The controller gain Kp determines the high frequency gain of the controller.
Gain Ki: The controller gain Ki determines the frequency gain of the controller at
frequency w = 1 [rad/s].
Frequency fi: The integration behavior of the controller stops after frequency fi in Hz.
A decrease of this frequency corresponds to a more pure integration behavior.
Transfer function of the controller:
that equals
PID1-Controller
The PID-1 C ontroller consists of an integrator and differentiator with proportional gain. It
resembles a PID C ontroller, but has different input parameters.
Gain Kp: The controller gain Kp determines the frequency gain of the controller in the
pass band (where integration and differentiation are of no interest).
Length Li: The length Li determines the frequency at which integration starts, that is fi
/ Li in Hz. A decrease of this frequency corresponds to a more pure integration
behavior.
Length Ld: The length Ld determines the frequency at which differentiation stops, that
is fd * Ld in Hz. An increase of this frequency corresponds to a more pure
differentiation behavior, reducing the tameness of the controller.
Frequency fi: The integration behavior of the controller stops at frequency fi in Hz.
Frequency fd: The differentiation behavior of the controller starts at frequency fd in
Hz.
20-sim 4.6 Reference Manual
355
8. Toolboxes
Transfer function of the controller:
that equals
PID2-Controller
The PID-2 C ontroller consists of an integrator and differentiator with proportional gain. It
resembles a serial PID C ontroller, but has different input parameters.
Gain Kp: The controller gain Kp determines the frequency gain of the controller in the
pass band (where integration and differentiation are of no interest).
Length Li: The length Li determines the frequency at which integration starts, that is fi
/ Li in Hz. A decrease of this frequency corresponds to a more pure integration
behavior.
Length Ld: The length Ld determines the frequency at which differentiation stops, that
is fd * Ld in Hz. An increase of this frequency corresponds to a more pure
differentiation behavior, reducing the tameness of the controller.
Frequency fi: The integration behavior of the controller stops at frequency fi in Hz.
Frequency fd: The differentiation behavior of the controller starts at frequency fd in
Hz.
Transfer function of the controller:
that equals
20-sim 4.6 Reference Manual
356
8. Toolboxes
PID-Compensator
The PID C ompensator consists of an integrator and differentiator with proportional gain
(PID C ontroller) together with a high-frequency roll-off filter.
Gain K: The controller gain K determines the frequency gain of the controller in the
pass band (where integration and differentiation are of no interest).
Integration tau_i: The integration time constant tau i determines the frequency fi =
1 / tau_i [rad/s] after which the integrating behavior stops.
Differentiation tau_d: The differentiation time constant tau d determines
frequency fd = 1 / tau_d [rad/s] after which the differentiation behavior starts.
the
HF roll-off tau_h: The filter time constant tau h determines the frequency fh = 1 /
tau_h [rad/s] of the high-frequency roll-off filter. Frequencies higher than fh are
filtered out.
Tameness beta: The tameness factor beta influences the differentiating behavior.
After frequency fdb = fd / beta the differentiation behavior stops. Decreasing beta
increases this frequency fdb, resulting in a more pure differentiating behavior and
therefore in a reduce of differentiation tameness.
Transfer function of the controller:
that equals
PID-Controller
The PID C ontroller consists of an integrator and differentiator with proportional gain.
Gain Kp: The controller gain Kp determines the frequency gain of the controller in the
pass band (where integration and differentiation are of no interest).
Gain Ki: The controller gain Ki determines the shape of the frequency response at
low frequencies.
Gain Kd: The controller gain Kp determines the shape of the frequency response at
high frequencies.
Frequency fi: The integration behavior of the controller starts at frequency fi in Hz. A
decrease of this frequency corresponds to a more pure integration behavior.
Frequency fd: The differentiation behavior of the controller stops at frequency fd in
Hz. An increase of this frequency corresponds to a more pure differentiation
behavior, reducing the tameness of the controller.
Transfer function of the controller:
that equals
20-sim 4.6 Reference Manual
357
8. Toolboxes
Filters
Generic Filter
The Generic Filter can be used to design a filter of a specific order, type and
characteristic shape.
Filter Characteristics
The filter can have a Bessel, Butterworth or C hebychev characteristic shape. Each
characteristic has its own advantages and disadvantages; it depends on the purpose of
the filter what to choose here:
A Bessel filter is maximal flat in both the pass band and the stop band. It is used when
the phase response should be nearly linear throughout the pass band, i.e. the group
delay is almost constant throughout the pass band. This preserves the wave shape of
filtered signals in the pass band. A disadvantage is the low roll-off steepness. Often a
high filter order is required to obtain the desired roll-off.
A Butterworth filter is maximally flat in the pass band and monotonic overall. As a
consequence of this smoothness, the roll-off steepness is rather low. As with Bessel
filters, a rather high filter order is required to obtain the desired roll-off.
A Chebychev 1 filter has a ripple in the pass band and is monotonic in the stop band.
This filter rolls off faster than Bessel, Butterworth and C hebychev 2 filters at the same
filter order. A disadvantage is the greater deviation and discontinuous phase response in
the pass band.
A Chebychev 2 filter is monotonic in the pass band and has a ripple in the stop band.
This filter rolls off faster than Bessel and Butterworth filters at the same filter order. Not
as fast as a C hebychev 1 filter, but it is free of a pass band ripple. A disadvantage is the
ripple and discontinuous phase response in the stop band.
Filter Type
A low pass filter will filter out high frequencies and let low frequencies pass the filter.
A high pass filter does the opposite; it will filter out low frequencies and let high
frequencies pass the filter.
A band pass filter will filter out low and high frequencies and let middle frequencies
pass the filter.
A band stop filter does the opposite; it will filter out the middle frequencies and let
low and high frequencies pass the filter.
Filter Order
The filter order specifies how steep the filter will roll off at a specified filter frequency.
The higher the order, the steeper the roll off will be. Note that the filter order also has a
large influence on the phase response of the filter.
20-sim 4.6 Reference Manual
358
8. Toolboxes
Frequency f1
For a low pass filter f1 is the frequency in Hz where the roll off starts. For a high pass
filter it is the frequency where the roll off ends. For a band pass or band stop filter f1 is
the start frequency of the band.
Frequency f2
For a band pass or band stop filter f2 is the stop frequency in Hz of the band.
disabled for low pass and high pass filters.
It is
Max. Ripple R
Only available when a C hebychev 1 filter is selected. R specifies the maximum allowed
ripple in dB for the filter in the pass band.
Stop Band R
Only available when a C hebychev 2 filter is selected. R specifies the distance of the stop
band to the unity gain axis in dB. This is the amount of attenuation in dB of the filter in
the stop band (the absolute value is used).
High-Pass First Order Filter
The high pass filter can be used to filter out undesired low frequencies.
Gain K: The filter gain K determines the high frequency gain of the filter.
Frequency f: The filter roll off stops at frequency f in Hz. Higher frequencies will pass
the filter, lower frequencies will be filtered out.
Transfer function of the filter:
High-Pass Second Order Filter
The high pass filter can be used to filter out undesired low frequencies.
Gain K: The filter gain K determines the high frequency gain of the filter.
Frequency f: The filter roll off stops at frequency f in Hz. Higher frequencies will pass
the filter, lower frequencies will be filtered out.
Quality Q: The filter quality indicates how steep the phase response will increase up
to the frequency f. A quality Q > 0.707 results in a peak in the magnitude response
at frequency f.
Transfer function of the filter:
20-sim 4.6 Reference Manual
359
8. Toolboxes
Lag Filter
The Lag Filter can be used to add a lag in the phase response of a system.
Gain K: The filter gain K determines the low frequency gain of the filter.
Frequency f1: The lag in the phase response of the filter starts at frequency f1 in Hz.
This corresponds to an integrating behavior in the magnitude response from
frequency f1.
Frequency f2: The lag in the phase response of the filter stops at frequency f2 in Hz.
This corresponds to a constant attenuation in the magnitude response of the filter
after frequency f2.
Transfer function of the filter
Lead Filter
The Lead Filter can be used to add a lead in the phase response of a linear system.
Gain K: The filter gain K determines the low frequency gain of the filter.
Frequency f1: The lead in the phase response of the filter starts at frequency f1 in
Hz. This corresponds to a differentiating behavior in the magnitude response from
frequency f1.
Frequency f2: The lead in the phase response of the filter stops at frequency f2 in Hz.
This corresponds to a constant gain in the magnitude response of the filter after
frequency f2.
Transfer function of the controller
20-sim 4.6 Reference Manual
360
8. Toolboxes
Low-Pass First Order Filter
The low pass filter can be used to filter out undesired high frequencies.
Gain K: The filter gain K determines the low frequency gain of the filter.
Frequency f: The filter roll off starts at frequency f in Hz. Lower frequencies will pass
the filter, higher frequencies will be filtered out.
Transfer function of the filter
Low-Pass Second Order Filter
The low pass filter can be used to filter out undesired high frequencies.
Gain K: The filter gain K determines the low frequency gain of the filter.
Frequency f: The filter roll off starts at frequency f in Hz. Lower frequencies will pass
the filter, higher frequencies will be filtered out.
Quality Q: The filter quality indicates how steep the phase response will decrease at
the frequency f. A quality Q > 0.707 results in a peak in the magnitude response at
frequency f.
Transfer function of the filter
Notch Filter
The notch filter can be used to filter out an undesired frequency.
Gain K: The filter gain K determines the frequency gain of the filter.
Frequency f: The filter attenuates at frequency f in Hz. Lower and higher frequencies
will pass the filter.
Quality Q: The filter quality indicates how steep the magnitude response will be at the
frequency f.
Transfer function of the filter:
20-sim 4.6 Reference Manual
361
8. Toolboxes
Universal Notch Filter
The universal notch filter can be used to filter out an undesired frequencies.
Gain K: The filter gain K determines the low frequency gain of the filter.
Frequency fz: The filter attenuates at the zero frequency fz in Hz. Lower and higher
frequencies will pass the filter. A lead in the phase response will start at this zero
frequency fz.
Frequency fp: The filter amplifies at the pole frequency fp in Hz. The phase lead will
stop at this pole frequency fp.
Damping dz: The filter damping of the zero dz indicates how steep the magnitude
response will be at the frequency fz. More damping will result in a less steep
behavior.
Damping dp: The filter damping of the pole dp indicates how steep the magnitude
response will be at the frequency fp. Again, more damping will result in a less steep
behavior.
Transfer function of the filter:
8.4
8.4.1
Frequency Domain Toolbox
FFT Analysis
FFT Analysis
In FFT-Analysis, the Fast Fourier Transform is used to calculate the frequency contents of
simulation signal. Three representations are supported:
Amplitude and Phase: This representation shows the amplitude and phase of the
signal as function of the frequency, similar to a bode plot. If you want show the
transfer function of a system, you have to choose the option Pair-wise transfer
function, which is explained below in the FFT Settings.
Frequency Plot: This representation shows the frequency contents of the signal.
Summation of the peak values yields the average power of the original time signal.
Power Spectral Density: This representation shows the frequency contents of the
signal. Integration over the frequency range yields the average power of the original
time signal.
20-sim 4.6 Reference Manual
362
8. Toolboxes
FFT plot showing the power spectral density.
FFT analysis can be performed in the Simulator by choosing the FFT Analysis
command from the Tools menu. You can also choose to add an FFT plot in the
Simulator tree. In both cases a new FFT plot is shown.
Plot Properties
You can define the FFT plot by opening the plot properties (from the menu choose
Properties - Plot). Four tabs are shown: Plot Properties, X-Axis, Y-Axis and FFT
Settings.
The Plot Properties tab shows the general settings of the plot, similar to every
standard plot.
The X-axis tab shows the X-Axis variable of the FFT input. The default value is time
and should not be changed.
The Y-axis tab shows the variables that are selected to be shown as FFT curves,
similar to every standard plot.
The FFT-Settings tab shows the options that you can choose for the FFT plot.
20-sim 4.6 Reference Manual
363
8. Toolboxes
FFT Settings
Items
Plot Properties
Pair-wise transfer function: Shows an FFT with the frequency contents of the first
plot variable subtracted from the second plot variable. Select this option if you
want to show the FFT of a transfer function. The first plot variable is the input of
the transfer function and the second plot variable is the output of the transfer
function.
Show Peaks: C hoose this option to show the peak values in the FFT plot.
Filter
Subtract DC-component: If your signal contains a DC -component, the resulting
Spectral Density plot will show a high peak at 0 Hz, which may obscure all other
frequencies. C hoose Subtract DC -component, to remove this peak from the
Spectral Density plot.
Integrate Data: You can integrate the FFT data to inspect the energy contents of
each frequency. This option is useful for analyzing resonance frequencies.
Integrated FFT-data will usually show a sudden increase exactly at these
frequencies.
Anti-Leakage Window: You can choose a Hamming, Hann or Quadratic window to
prevent leakage caused by windowing.
Frequency: Show the results in Herz or radians per second.
Output: select the desired representation of the frequency data:
Amplitude and Phase
Frequency Spectrum
20-sim 4.6 Reference Manual
364
8. Toolboxes
Power Spectral Density
Status Window: The bottom part of the window shows the number of simulation points
and the chosen frequency range.
Quality
The quality of an FFT plot depends on the contents of the time domain simulation:
The number of simulation points per second, determine the frequency range of the
FFT. If you want to increase the frequency range to higher frequencies, choose a
smaller step size or a smaller maximum step size of the integration method.
The quality of the FFT depends on the total time of the simulation. Increase the finish
time of the simulation to get a better FFT plot.
Make sure that you system is excited properly. If you give an input signal that does
not contain higher frequencies, the FFT plot will not show them.
FFT Window
The Fast Fourier Transform is an approximation of the standard Fourier Transform, using
a time limited set of data. The begin and end parts of this limited data set may lead to
spectral leakage effects (i.e. yielding not existing frequency peaks). Especially when
using small data sets leakage may lead to unwanted results.
To reduce spectral leakage, the data set can be preprocessed using special windowing
functions. These windowing functions reduce the values at the begin and end of the data
set and thus reduce the leakage effects. Given an input array A[i] and an output array
B[i], with = 1,2,...,N.
20-sim supports the following windows:
None: no preprocessing; B == A
Hamming Window: B(i) = (0.54 + 0.46*cos(pi*(i-1)/(N-1)))*A(i), i = 1,2,...,N.
Hann Window: B(i) = 0.5*(1 + cos(pi*(i-1)/(N-1)))*A(i), i = 1,2,...,N.
Quadratic Window: B(i) = (1 - 2*((i-1)/(N-1))**2)*(1 - (i-1)/(N-1))*A(i), i = 1,2,...,
(N-1)/2+1; B(i) = 2*(1 - ((i-1)/(N-1))**3)*A(i), i = (N-1)/2+2,...,N.
8.4.2
Model Linearization
Linearize
In the Simulator, select the Tools menu and then click the Linearize Model to start
linearization. Linearization will generate a linear, state-space description (linear system)
out of any 20-sim model:
dx/dt = Ax + Bu
y = Cx + Du
x(0)
Where:
20-sim 4.6 Reference Manual
365
8. Toolboxes
x = state vector
x(0) = state vector initial value
dx/dt = state vector derivative
y = output
u = input
And:
A
B
C
D
=
=
=
=
system matrix
input gain matrix
output gain matrix
direct link gain matrix
This linear system shows an input-output behavior that is closely related to the inputoutput behavior of the original model.
The result is shown in the Linear System Editor. In the Linear System Editor you can
choose out of several plot options to show the response of the linear system, such as
step responses and Bode plots.
Working Point
Non-linear models can show variable behaviour. Think for example of an arm. When you
stretch it and push against a wall, it is very stiff. When your arm is bent and you push it
against a wall, it will be more compliant. Depending on which state it is in, linearization
of a non-linear system will therefore result in different linear systems.
To get the correct linear system, we have to bring the non-linear system into the correct
state. This can be done by giving it the proper inputs and simulate the system for a while
until the desired state is reached. This is called the working point. When the working
point is reached, the simulation must be stopped to perform linearization.
When linearization is performed without simulation, the working point is the initial state
of the non-linear system.
Symbolic and Numeric
In the 20-sim Simulator, out of an existing (non-linear) model, a symbolic linear-system
can be derived. This means that states, rates and matrix elements are related to the
parameters of the original model:
As a result you will get a linear system with the original model parameters that can be
changed at will, without having to linearize again.
Symbolic linearization is not possible if the original model contains functions that cannot
be differentiated. For such models linearization has to be performed numerically. The
resulting linear system has to be recalculated through linearization for different model
parameters.
20-sim 4.6 Reference Manual
366
8. Toolboxes
Procedure
1.
Run a simulation until the working point is reached.
2.
Stop the simulation at operating point an select the Linearize command from the
Tools menu.
3.
Enter your options in the Linearization Dialog.
The Linearization Toolbox.
Items
Input: Use the
Output: Use the
button to select the input (u).
button to select the output (y).
Linearization Kind: C hoose between open loop and closed loop linearization.
Linearize Type: C hoose between Symbolic and Numeric linearization.
Additional Settings: When you are performing numeric linearization, select At current
time when you want to linearize at the operating point where the simulation was
stopped. Select At start of simulation when you want to linearize at the start of the
simulation.
Tolerances: 20-sim calculates a numerical linear state space model by small
deviations of the complete model from the chosen setpoint. The deviations are based
on the given absolute and relative tolerances. For most models the default values are
sufficient. For stiff models you can change these values by hand.
OK: click the OK button to start Linearization.
20-sim 4.6 Reference Manual
367
8. Toolboxes
Linearization Explained
During linearization you are asked to enter an input signal and an output signal of your
(non-linear) model. During linearization, 20-sim will derive a corresponding linear
system. It is important to understand that 20-sim will cut the model at the input. This
will be explained with the example model below. It shows a linear system with feedback.
Closed Loop
Suppose we would choose the following settings:
input u: WaveGenerator\output
output y: Monitor\input
kind: Closed Loop
This means that 20-sim will add an input u and linearize the model between this
variable and the variable Monitor\output (equal to y in the figure below). 20-sim will
thus linearize the system between u en y and (in this example) and yield the closed
loop system.
Open Loop
Suppose we would choose the following settings:
input u: PlusMinus\output
output y: Monitor\input
kind: Open Loop
This means that 20-sim will cut the model at the variable PlusMinus\output (equal to u in
the figure below) and linearize the model between this variable and the variable Monitor
\input (equal to y in the figure below). 20-sim will thus linearize the system between u
en y and (in this example) and yield the open loop system.
20-sim 4.6 Reference Manual
368
8. Toolboxes
Frequency Response
Next to time domain analysis through the standard time domain plots, 20-sim can also
show results in the frequency domain through FFT analysis and Bode Plots. The picture
below shows the various actions and resulting plots.
Bode plots originate from linear systems theory. A bode plot shows the amplitude and
phase response (as a function of the frequency) of a linear system. In 20-sim linear
systems can be derived in the Simulator out of any linear or non-linear model (model
linearization). The resulting linear system is shown in the Linear System Editor. In this
editor you can generate Bode plots. The generation of Bode plots can be automated in
the Frequency Response dialog. In this dialog you can define the linearization settings
and desired linearization output (Linear System Editor or Bode plot).
Procedure
1.
Select the Frequency Response from the command from the Properties menu.
2.
Enter your options in the Frequency Response Dialog.
20-sim 4.6 Reference Manual
369
8. Toolboxes
The Frequency Response dialog.
Items
Input Probes: Enter possible input signals for linearization here.
Output Probes: Enter possible output signals for linearization here.
Frequency Response: With the Add Frequency Response you can add new input/
output pairs. For every input/output pair linearization will be performed with a
corresponding linear system as result.
Symbolic/Numeric: Select the desired linearization method.
Closed Loop: By default all linearization is open loop. Select the Closed Loop option
to preform closed loop linearization.
At start of simulation/At current time: Select the time of the linearization.
Tolerances: For numeric linearization you can enter the absolute and relative
tolerances.
Output: Select the desired output of the linearization.
Frequency Range: Select the desired frequency range.
OK: click the OK button to close the dialog.
20-sim 4.6 Reference Manual
370
8. Toolboxes
Linearization Tolerances
When using numerical linearization, absolute and relative tolerances can be set. In this
section is explained how 20-sim uses these tolerances to derive a linear system for the
model equations.
Algorithm
Suppose you have chosen the following tolerance values.
alpha = absolute tolerance (e.g. 1e-6)
beta = relative tolerance (e.g. 1e-3)
Suppose we have the following model:
ddt (x) = 4 * x + 2 * u; // with u = 1
y = 1 * x + 3 * u; // with x = 2
During the linearization procedure (suppose linearization from u to y ) 20-sim will vary
the input variable and state variables. First we will show the variation for the input u:
u' = (1 + beta)*u + alpha
u'' = (1 - beta)*u - alpha
delta_u = beta*u + alpha
this will yield
x_dot' = 10.002002 and y' = 5.003003
x_dot'' = 9.997998 en y'' = 4.996997
Out of this 20-sim will calculate the B and D vectors of the state-space ABC D
representation:
20-sim 4.6 Reference Manual
371
8. Toolboxes
B = (x_dot' - x_dot'' ) / (2 * delta_u) = 2
D = (y' - y'') / (2 * delta) = 3
The variation of state variables is done accordingly:
x' = (1 + beta)*x + alpha
x'' = (1 - beta)*x - alpha
delta_x = beta*x + alpha
this will yield
x_dot' = 10.008004 en y' = 5.002001
x_dot'' = 9.991996 en y'' = 4.997999
Out of this 20-sim will calculate the A matrix and C vector of the state-space ABC D
representation:
A = (x_dot' - x_dot'') / 2*delta_x = 4
C = (y' - y'') / 2*delta_x = 1
The example system is linear, so the corresponding ABC D representation will give an
equal system. The shown algorithm works equivalent for non-linear models. Suppose we
have the following non-linear model:
ddt (x) = 4 * sin(x) + 2 * u; // with u = 1
y = 1 * x + 3 * u; // with x = 2
This will yield:
B = 2, D = 3, A = -1.668445, C = 1;
Tolerance Values
The absolute tolerance is necessary only if the input or state is zero. In that case the
contribution of the relative tolerance is zero an will not give a contribution to the
algorithm. There is however a problem with the absolute tolerance. Suppose the input =
1e-12 and the state = 1e+6 (ill-scaled model). For the input an absolute tolerance of 1e6 will yield a far too large deviation, while the same absolute tolerance is negligible
compared to the state. Only if both the state and input are nonzero the absolute
tolerance can be made non-zero to yield good results.
20-sim 4.6 Reference Manual
372
8. Toolboxes
8.4.3
Linear System Editor
Linear System Editor
The Linear System Editor of 20-sim allows you to enter or edit linear time- invariant
models. It supports continuous and discrete-time single input / single output (SISO)
systems with and without time delay. You can open the Linear System Editor from the
Tools menu of the 20-sim Editor or by clicking Go Down on the Linear System model. A
linear system can also be the result of a linearization operation in the 20-sim Simulator.
Menu
Some menu items are of particular importance.
File: You can use the file menu to open, import and export linear systems.
Edit - Tolerance: You can specify the tolerance for transforming between state-space
and transfer functions.
Edit - Reduce System: You can reduce the system order by pole-zero cancelation.
The distance between poles and zeros to match for cancelation is given by the
Reduction Tolerance.
View: the view menu can be used for holding, clearing and refreshing plots.
20-sim 4.6 Reference Manual
373
8. Toolboxes
System Description
Pressing the Edit button will open a dialog for editing the linear system. Each
description (State Space, Transfer Function, Zeros Poles Gain or Eigen Frequency)
has a special dialog and can be used to specify continuous-time and discrete-time
systems.
In the 20-sim Simulator, out of an existing (non-linear) model a symbolic linearsystem can be derived by means of linearization. This means that the relevant model
parameters are preserved in the Linear System and the parameters button
be used to change parameters.
can
Import/Export
Pressing the s<->z button
will transform a continuous-time linear system
into a discrete-time linear system and back.
Pressing the Filter button opens the Filter Editor, where a filter can be designed. This
filter can then be combined with the current linear system or replace the current
linear system. If the linear system is a discrete-time system, the designed analog
filter is automatically transferred into its digital equivalent.
Pressing the From Matlab button
and the To Matlab button
allows
for an instant exchange of the linear system with the Matlab workspace. Information
is transferred numerically (no parameter relations are preserved)
The
button is only active when a Linear System has been imported through
linearization. C licking the button will import parameters from the simulation.
The
button is only active when a Linear System has been imported through
linearization. C licking the button will export the current parameters to the simulation.
Plots
You can inspect the time- and frequency responses of the linear system using:
Step Response
Bode Plot
Nyquist Plot
Nichols C hart
Poles and Zeros (including root locus)
Output
C licking the 20-sim button will export the linear system as a new 20-sim submodel.
C licking the Matlab button will export the 20-sim Linear System to a Matlab m-file. If
the Linear System is symbolic, all parameter relations are preserved.
20-sim 4.6 Reference Manual
374
8. Toolboxes
Symbolic Linear Systems
In the 20-sim Simulator, out of an existing (non-linear) model a symbolic linear-system
can be derived by means of linearization. This means that the relevant model
parameters are preserved in the Linear System.
The relation between the original model parameters and the linear system elements is
always shown in the white square of Linear System editor, just below the system
description. An example is shown in the first figure below:
As you can see, the some elements of the A, B, C and D matrix are related to the spring
constant and masses of the original model.
Editing
A symbolic linear system can be edited by changing the original model parameters. C lick
the Edit Parameters button
and a Parameters Editor pops-up. C hange the desired
parameters, close the Parameters Editor and the linear system will updated.
20-sim 4.6 Reference Manual
375
8. Toolboxes
Updating Parameters
When the parameters have been changed in the Linear System Editor you can update
the parameters in the Simulator by clicking the Update to Simulator button
C lick the Update from Simulator button
.
to do it the other way.
Exporting
You can export a symbolic Linear System to Matlab, with preservation of the parameter
relations, by clicking the Matlab button or selecting Export to Matlab command from the
File menu. This will generate an m-file that you can use in Matlab.
Continuous and Discrete Linear Systems
The Linear System Editor works on continuous time as well as discrete time system.
Pressing the s<->z button
will transform a continuous-time linear system into a
discrete-time linear system and back. You can choose between a Bilinear transformation
(Tustin), a Forward Euler transformation and a Backward Difference transformation.
When a continuous-time system is transferred, the user is asked to specify the sample
time of the discrete-time system.
If you want to transfer a linear system directly (i.e. replace the z by and s or vice
versa), click the Edit button and select or deselect the Discrete Sample time.
Output Delay
In the Linear System Editor you can add an output delay. Open the editor and click the
Edit button to edit the system. Now a editor will open where you can set the output
delay. The effects of this output delay is shown in the various plots that you can show of
a linear system. The unit of the output delay is seconds.
The output delay is shown as an exponential added to the transfer function.
Editor
State Space Models
State space models use linear differential equations (continuous) or difference equations
(discrete) to describe system dynamics. They are of the form:
20-sim 4.6 Reference Manual
376
8. Toolboxes
(continuous)
(discrete)
with for example:
where x is the state vector and u and y are the input and output vectors. These models
may arise from the equation of physics, from state space identification or as the result of
linearization.
You can enter state space models by selecting the State Space button and clicking the
Edit button.
This opens an editor in which you can enter the A, B, C and D matrices. Depending on
the selection of the Discrete Linear System check box (and Sample Time) the system is
a continuous-time or discrete-time system. You can enter the matrix elements in the
white space areas. Separate column elements with Spaces or C ommas. Enter new rows
by clicking the Enter key (new line) or using a semicolon. Brackets ( e.g. [ ... ] ) may be
used to denote the a matrix or vector.
20-sim 4.6 Reference Manual
377
8. Toolboxes
The A-matrix, shown in the figure above can for example be entered as:
01
-0.5 -1
or
0,1;-0.5,-1
or
[0,1;
-0.5,-1]
Output Delay
To inspect the effects of time delay in your model, you can add output delay. The result
will be visible in the various plots that you can show of a linear system. The unit of the
output delay is seconds.
Discrete Sample Time
If you want to transfer a linear system from continuous time to discrete time directly
(i.e. replace the s by a z), select Discrete Sample time and fill in the sample time value.
You can also transfer back directly by deselecting Discrete Sample time.
Commands
Help: Open the help file.
Apply: Apply the current changes of the system, recalculate each plot that is active
(step, Bode, Nyquist, Nichols, pole zero).
OK: Apply the current changes of the system, recalculate each plot that is active
(step, Bode, Nyquist, Nichols, pole zero) and close the editor.
Cancel: Do not apply any changes to the system and close the editor.
Transfer Functions
A continuous time or discrete time SISO transfer function:
(continuous)
(discrete)
is characterized by its numerator n and denominator d, both polynomials of the variable
s or z.
20-sim 4.6 Reference Manual
378
8. Toolboxes
You can enter transfer functions by selecting the Transfer Function button and clicking
the Edit button.
This opens an editor in which you can enter the coefficients of the numerator and
denominator polynomials. You can enter the elements in the white space areas.
Separate the elements with Spaces. Polynomials should be entered in descending
powers of s or z. The Steady State Gain, Root Locus Gain and System Gain are
parameters, that are automatically derived from the transfer function.
In the editor shown above the transfer function
20-sim 4.6 Reference Manual
379
8. Toolboxes
was given. You can enter the coefficients as:
0.1 0.1
and
1 1 0.5
or
0.1,0.1
and
1,1,0.5
Output Delay
To inspect the effects of time delay in your model, you can add output delay. The result
will be visible in the various plots that you can show of a linear system. The unit of the
output delay is seconds.
Discrete Sample Time
If you want to transfer a linear system from continuous time to discrete time directly
(i.e. replace the s by a z), select Discrete Sample time and fill in the sample time value.
You can also transfer back directly by deselecting Discrete Sample time.
Commands
Help: Open the help file.
Apply: Apply the current changes of the system, recalculate each plot that is active
(step, Bode, Nyquist, Nichols, pole zero).
OK: Apply the current changes of the system, recalculate each plot that is active
(step, Bode, Nyquist, Nichols, pole zero) and close the editor.
Cancel: Do not apply any changes to the system and close the editor.
Gains
Steady State Gain
Given the transfer function:
the Steady State Gain is defined as:
20-sim 4.6 Reference Manual
380
8. Toolboxes
Note that the steady state gain can be zero or infinite depending on the element values
of the numerator and denominator!
Root Locus Gain
Given an system described by the transfer function:
This transfer function can be rewritten in pole zero notation with
where pi .. p1 are the poles and zi .. z1 are the zeros of the system. The gain KRL is
known as the Root Locus Gain. Note that it can easily be derived from the transfer
function as:
System Gain
Given the transfer function:
If n0 and d0 are unequal to zero, this transfer function can be rewritten in pole zero
notation with:
The gain KS is known as the System Gain. If n0 is zero and n1 is nonzero an equivalent
notation can be found with an extra s multiplied:
If more numerator element are zero, extra multiplications with s are added. The same
goes for denominator elements equal to zero. In general the System Gain can be
derived from the transfer function as:
20-sim 4.6 Reference Manual
381
8. Toolboxes
Relating the Gains
The elements of the System Gain are related to the poles and zeros of the Root Locus
Gain as:
If z0 and p0 are unequal to zero, the following equation holds:
The Root Locus Gain and the Steady State Gain are related as:
Zeros and Poles
A continuous-time SISO transfer function can described by the transfer function:
This transfer function can be rewritten in pole zero notation with
where pi .. p1 are the poles and zi .. z1 are the zeros and KRL is the Root Locus Gain of
the system. The same can be done for a discrete-time SISO transfer function.
20-sim 4.6 Reference Manual
382
8. Toolboxes
You can enter zeros and poles by selecting the Zeros & Poles button and clicking the Edit
button.
20-sim 4.6 Reference Manual
383
8. Toolboxes
This opens an editor in which you can enter the real and imaginary parts of the zeros
and poles as well as the Root Locus Gain. If preferred, you can also enter the System
Gain. Note that zeros and poles always have conjugate when the imaginary part is nonzero. I.e. when you enter a pole with imaginary part 0.5 an extra pole is added with
imaginary part -0.5.
Output Delay
To inspect the effects of time delay in your model, you can add output delay. The result
will be visible in the various plots that you can show of a linear system. The unit of the
output delay is seconds.
Discrete Sample Time
If you want to transfer a linear system from continuous time to discrete time directly
(i.e. replace the s by a z), select Discrete Sample time and fill in the sample time value.
You can also transfer back directly by deselecting Discrete Sample time.
Commands
Add/Delete: Add or delete selected poles or zeros.
Help: Open the help file.
Apply: Apply the current changes of the system, recalculate each plot that is active
(step, Bode, Nyquist, Nichols, pole zero).
OK: Apply the current changes of the system, recalculate each plot that is active
(step, Bode, Nyquist, Nichols, pole zero) and close the editor.
Cancel: Do not apply any changes to the system and close the editor.
20-sim 4.6 Reference Manual
384
8. Toolboxes
Eigen Frequencies
The Eigen Frequencies view is closely related to the pole zero notation and bode plot. It
shows the resonance frequencies and anti-resonance frequencies that result from the
given poles and zeros as well as some characteristic parameters from the bode plot.
You can enter transfer functions by selecting the Eigen Freqs. button and clicking the Edit
button.
20-sim 4.6 Reference Manual
385
8. Toolboxes
Step Response
The Step Response command calculates the systems response y on a unit step input:
u = 0 (time < 0 )
u = 1 (time >= 0 )
20-sim automatically generates an appropriate range for the time response, based on
the system dynamics. With the Plot Properties command (right mouse menu), you can
change this horizon and recalculate the step response (click the Step command again).
Plot Options
Using the right mouse menu, you can use several options:
Plot Properties: Set the general plot properties for the step response and specify the
curve properties.
Numerical Values: Inspect numerical values.
Step Characteristics: Display rise time, overshoot, settling time and the steady state
value of the step response.
Copy to Clipboard: C opy the plot to the windows clipboard.
Print: Print the plot.
Zoom in: Show a detail of the plot.
Zoom out: Show a larger portion of the plot.
Zoom Normal: Show the complete plot.
20-sim 4.6 Reference Manual
386
8. Toolboxes
Bode Plots
Bode Plots show the amplitude and phase of a linear system as function of the
frequency. Bode plots can be shown for every 20-sim model through Linearization.
During Linearization you are asked to enter the input variable and output variable for
which linearization should be performed. After that the linear system is calculated and
shown in the Linear System Editor. From the Linear System Editor you can generate a
bode plot. These actions can also be predefined using the Frequency Response
command of the Properties menu.
20-sim automatically generates a range of logarithmically displayed frequencies, based
on the system dynamics. With the Plot Properties command (right mouse menu),
you can change this horizon and recalculate the bode response (click the Bode command
again).
The magnitude part of the plot can be displayed in dB or in absolute values. The phase
part can be displayed in radians or degrees. The frequency can be displayed in radians
per second or in Hz.
Plot Options
Using the toolbar or the right mouse menu, you can use various options:
Plot Properties: Set the plot properties.
Numerical Values: Inspect numerical values.
Magnitude (dB): Display magnitude in decibels
Magnitude (-): Display magnitude in absolute values.
Phase (rad): Display phase in radians.
Phase (deg): Display phase in degrees.
Frequency (rad/sec): Display frequency in radians per second.
Frequency (Hz): Display frequency in Hz.
20-sim 4.6 Reference Manual
387
8. Toolboxes
Phase/Gain Margins: Display the gain and phase margins.
Modulus Margin: Display the Modulus Margin.
Unwrap Phase: Display the phase plot as a continuous plot by selecting this option or
as a folded plot between -180 and 180 deg. by deselecting this option.
Peak Response: Display the peak response.
Copy to Clipboard: C opy the plot to the windows clipboard.
Print: Print the plot.
Zoom in: Show a detail of the plot.
Zoom out: Show a larger portion of the plot.
Zoom Normal: Show the complete plot.
Nyquist Diagram
The Nyquist command computes the Nyquist plot of a system.
20-sim automatically generates a range of real and imaginary parts, based on the
system dynamics. With the Plot Properties command (right mouse menu), you can
change this horizon and recalculate the Nyquist diagram (click the Nyquist command
again).
Plot Options
Using the right mouse menu, you can use several options:
Plot Properties: Set the plot properties.
Numerical Values: Inspect numerical values.
Phase/Gain Margins: Display the gain and phase margins.
Modulus Margin: Display the Modulus Margin.
20-sim 4.6 Reference Manual
388
8. Toolboxes
Copy to Clipboard: C opy the plot to the windows clipboard.
Print: Print the plot.
Zoom in: Show a detail of the plot.
Zoom out: Show a larger portion of the plot.
Zoom Normal: Show the complete plot.
Nichols Chart
The Nichols command computes the Nichols chart of a system.
20-sim automatically generates a range of logarithmically displayed frequencies, based
on the system dynamics. With the Plot Properties command (right mouse menu), you
can change this horizon and recalculate the Nichols chart (click the Nichols command
again). The magnitude part of the plot can be displayed in decibels (dB) or in absolute
values. The phase part can be displayed in radians or degrees.
Plot Options
Using the right mouse menu, you can use several options:
Plot Properties: Set the plot properties.
Numerical Values: Inspect numerical values.
Magnitude (dB): Display magnitude in decibels
Magnitude (-): Display magnitude in absolute values.
Phase (rad): Display phase in radians.
Phase (deg): Display phase in degrees.
20-sim 4.6 Reference Manual
389
8. Toolboxes
Frequency (rad/sec): Display frequency in radians per second.
Frequency (Hz): Display frequency in Hz.
Phase/Gain Margins: Display the gain and phase margins.
Modulus Margin: Display the Modulus Margin.
Copy to Clipboard: C opy the plot to the windows clipboard.
Print: Print the plot.
Zoom in: Show a detail of the plot.
Zoom out: Show a larger portion of the plot.
Zoom Normal: Show the complete plot.
Pole Zero Diagram
The Pole Zero command plot the poles and zeros of a system and computes the root
locus plot.
20-sim automatically generates a range of real and imaginary parts, based on the
system dynamics. With the Plot Properties command (right mouse menu), you can
change this horizon and recalculate the pole zero diagram (click the Pole Zero
command again).
Root Locus
You can show the rootlocus plot by selecting Root Locus from the right mouse menu.
Inspect the root locus gain by selecting Numerical Values from the right mouse menu.
Plot Options
Using the right mouse menu, you can use several options:
Plot Properties: Set the plot properties.
20-sim 4.6 Reference Manual
390
8. Toolboxes
Numerical Values: Inspect numerical values.
Root Locus: Show or hide the root locus plot.
Copy to Clipboard: C opy the plot to the windows clipboard.
Print: Print the plot.
Zoom in: Show a detail of the plot.
Zoom out: Show a larger portion of the plot.
Zoom Normal: Show the complete plot.
20-sim 4.6 Reference Manual
391
8. Toolboxes
Import Data
You can import data from measurements or other software tools to compare it with the
response of your model. 20-sim accepts data in two formats:
Gain-Phase: The data should be stored in a text-file with three columns. The first
column should contain the frequency and the second and third column, the
corresponding gain and phase data.
Real-Imag: The data should be stored in a text-file with three columns. The first
column should contain the frequency and the second and third column, the
corresponding real and imaginary data.
Import Data
1.
Open the Linear System Editor with your linear system.
2.
Open the plot (e.g. Bode, Nyquist) in which you want to show the data.
3.
Set the Magnitude (- or dB), Phase (rad or deg) and Frequency (rad/s or Hz)
according to the data you want to import.
4.
In the Linear System Editor from the File menu select Import.
5.
Select Import Gain-Phase or Import Real-Imag.
Now a file dialog opens helping you to select the file to import. When you have selected
a file and closed the dialog, the data should be visible in your plot. An example is shown
in the figure above.
20-sim 4.6 Reference Manual
392
8. Toolboxes
8.4.4
Dynamic Error Budgeting
Dynamic Error Budgeting
The performance of precision machines is mostly limited by the disturbances that are
injected in these machines. These disturbances are often stochastic in nature. Dynamic
Error Budgeting is a method whereby the effect of these disturbances on the final
performance can be calculated. The advantage of this method is that it enables the
designer to enter the contributions of the individual disturbances and view and optimize
the overall machine performance.
The Dynamic Error Budgeting toolbox shows the total error as a result of injected disturbances.
Running the Toolbox
1.
Open the example model Dynamic Error Budgetting from the Getting Started/
Frequency Domain Toolbox.
You can open the Dynamic Error Budgeting tool in the Simulator:
2.
From the Tools menu select Frequency Domain Toolbox and Dynamic Error
Budgeting.
20-sim 4.6 Reference Manual
393
8. Toolboxes
The Dynamic Error Budgeting tool.
The tool allows you to enter disturbances (as power spectral density) in the Input Noises
section.
3.
For each disturbance you have to select a corresponding variable by clicking the
Add input noise button.
Each disturbance is effectively a summation to the chosen variable, just like closed loop
linearization. You can inspect each disturbance in the graph on the top right.
Next you have to select an output variable, where the result of the disturbances is
calculated.
4.
Select the output by clicking the Add Output button.
In the graph on the bottom right you can see the resulting error at the selected output
as a result of the disturbances. The error is given in the form of a power spectral density
(PSD) and cumulative power spectral density (C PS). The square root of the final value of
the C PS is equal to the standard deviation of the output error. The standard deviations
are shown in the Output Sigma tab.
20-sim 4.6 Reference Manual
394
8. Toolboxes
8.5
8.5.1
Mechatronics Toolbox
Cam Wizard
How to use the Cam Wizard
C ams and mechanisms are all based on the same principle. The motion of an input axis
is transformed to an output axis or translation. The transformation is a function of the
input angle. This function is called the cam motion profile.
The 20-sim cam wizard helps you to generate cam and mechanism models. You can use
various types of motion profiles which are continuous in velocity, acceleration or even in
jerk! An example of a mechanism that can be generated by the C am wizard is the
crank-rod mechanism, where a rotary input motion is transformed to a translating output
motion.
The models that are generated by the 20-sim C am wizard are fully dynamic! This
means:
The models describe the output velocity as function of the input velocity but also the
input torque as function of the output load.
The speed of the input axis does not have to be constant nor does the output load.
No inertia, stiffness or other dynamic behavior is included, but this can be easily
incorporated by coupling elements from the 20-sim library (inertias, springs etc.) to
the input or output of the model.
To generate a cam or mechanism model in 20-sim, follow the next steps.
1.
Open the model library and drag the model CamManipulator.emx to the editor.
20-sim 4.6 Reference Manual
395
8. Toolboxes
2.
Make an input connection (rotation) and an output connection (rotation/translation)
to the model.
3.
Select the camwizard model and click Go Down. Now the wizard will be opened.
4.
C hoose the desired motion profile, the profile parameters and type of output
(translation/rotation):
5.
Select the type of cam motion profile:
20-sim 4.6 Reference Manual
396
8. Toolboxes
6.
Enter the parameters values (Stroke, Start Angle Stop Angle). If you have chosen a
continuous pulse as output, you must also enter the values for the Return Angle and
End Angle:
20-sim 4.6 Reference Manual
397
8. Toolboxes
7.
In the last page, the resulting values are shown:
20-sim 4.6 Reference Manual
398
8. Toolboxes
Note
1.
If you have changed the settings of this wizard, you have to process the model first
(from the Model menu, choose Check Complete Model) before the changes become
effective.
2.
You can change parameter values during simulation (from the Properties menu
select Parameters).
3.
This is a masked model that uses the dll-file MotionProfile.dll to open the wizard.
This dll-function must be stored in the bin directory of 20-sim. To see the SIDOPS
code of a masked model press the shift-key, while clicking the Go Down command.
20-sim 4.6 Reference Manual
399
8. Toolboxes
Cam Motion Profiles
Motion Types
Two types of motion profiles can be generated by the C am wizard: intermittent steps
and continuous pulses. The intermittent step motion does not return to its starting
position, but gradually moves further away . It is characterized by the parameters
stroke, start_angle and stop_angle.
The continuous pulse motion output returns at the end of each cycle returns to the
starting position. It is characterized by the parameters stroke, start_angle, stop_angle,
return_angle and end_angle.
Motion Profiles
In mechanical engineering an important part of design is the reduction of vibrations.
Every time a construction is in motion, vibrations are induced. When cams or
mechanisms are used, the amount of vibrations, depend on the kind of motion that is
induced. E.g. a sudden step change will induce violent vibrations in comparison with with
a fluent motion. An important parameter to characterize motions, is the order:
1.
Zero Order: Motions that are discontinuous in the position (e.g. a step).
2.
First Order: Motions that are continuous in the position but discontinuous in the
velocity (e.g. a ramp).
3.
Second Order: Motions that are continuous in the position and velocity but
discontinuous in the acceleration.
4.
Third Order: Motions that are continuous in the position, velocity and acceleration.
20-sim 4.6 Reference Manual
400
8. Toolboxes
5.
Fourth Order: Motions that are continuous in the position, velocity, acceleration and
jerk.
The specific shape of a motion profile can have a significant influence on the dynamic
behavior. Some profiles minimize the maximum velocity, some profile minimize
acceleration, while other profiles tend to make a tradeoff between the maximum velocity
and acceleration. If we take a standard motion with stroke 1 and motion time 1 sec., the
following table can be generated:
profile
order
v max
a max
y(0)
y(1/2)
Ramp
1
1
infinite
infinite
0
C rank-Rod2
2
> 1.57
> 4.93
infinite
< -15.5
Trapezoidal
2
2
4
infinite
-infinite
Partial Trapezoidal1 2
1.67
4.17
infinite
0
Geneva Mechanism
2
2.41
8.49
infinite
-118.5
Sine
2
1.57
4.93
infinite
-15.5
C ubic
3
2
4
32
-32
Partial C ubic3
3
1.67
5.55
55.6
0
C ycloidal
3
2
6.28
39.5
-39.5
Modified Sine
3
1.76
5.53
69.4
-23.2
Modified Trapezoidal 3
2
4.88
61.4
-61.4
MSC 50
3
1.26
9.20
173.6
0
MSC %4
3
1.37
7.20
113.1
0
3-4-5 Polynomial
3
1.88
5.77
60
-30
1-3-5-7-9
3/4
2.05
10.25
BB
BM
Polynomial5
1: Parameter C V = 20%
2: For lw >> lc the C rank Rod profile equals the sine profile, for lw > lc performance
deteriorates.
3: Parameter C V = 20%, C A = 20%
4: Parameter n = 30%, alpha = 10%
5: Parameter BB = 30%, BM = 10%
20-sim 4.6 Reference Manual
401
8. Toolboxes
Here y(0) is the initial jerk (derivative of acceleration) and y(1/2) the crossover
(halftime) jerk.
Ramp
The ramp profile is a first order profile. It has a constant velocity and acceleration peaks
at the start and end of the motion.
Crank Rod Mechanism
A C rank Rod mechanism converts a rotary motion into a repeating translation and
If the rod is much longer than the crank, the resulting motion profile will approach the
sine profile. Below the motion profile is shown for half a rotation of the crank (angle
from 0 to 180 degrees in 1 sec.).
20-sim 4.6 Reference Manual
402
8. Toolboxes
If the rod gets smaller, the maximum velocity and acceleration increase.
Note: A real crank-rod mechanism will not suddenly stop at half a rotation and therefore
not show a discontinuous acceleration.
Trapezoidal
The trapezoidal profile is a second order profile. It has a constant acceleration at the
start of the motion and a constant deceleration at the end of the motion.
20-sim 4.6 Reference Manual
403
8. Toolboxes
This profile is most widely used in early servo systems. Because of the discontinuity in
the acceleration this motion profile can still induce a lot of vibrations. Therefore in
modern servo systems third order profiles are preferred.
Partial Trapezoidal
The partial trapezoidal profile is a second order profile. It has is equal to the trapezoidal
motion, but has a constant velocity part, during a fraction CV (%) of the motion.
Geneva Mechanism
A Geneva mechanism is an old motion profile generation mechanism. A continuously
rotating crankshaft (a) generates an intermittent motion of a second shaft (b). The result
is a second order profile.
The motion profile generator yields the motion of the second shaft (b). It is shown
below:
20-sim 4.6 Reference Manual
404
8. Toolboxes
Sine
The sine profile is a second order profile of which the displacement can be described as:
x = 0.5 - cos (p * t) / 2.
Cubic
The cubic profile is a third order profile of which the acceleration is constantly increasing
and decreasing.
Partial Cubic
The partial cubic profile (3rd order) is a modified cubic profile with a constant velocity
during a fraction CV (%) of the motion and a constant acceleration during a fraction CA
(%) of the motion.
20-sim 4.6 Reference Manual
405
8. Toolboxes
Cycloidal
The cycloidal profile is a third order profile, of which the velocity can be described as:
v = stroke*(1-cos(t*a))
Modified Sine
The modified sine profile is also a third order profile. It is a modification of the cycloidal
profile to get a lower maximum velocity and a lower maximum acceleration.
Modified Trapezoidal
The modified trapezoidal profile is a modification of the trapezoidal profile (to make it a
third order profile). This profile yields a very low maximum acceleration.
20-sim 4.6 Reference Manual
406
8. Toolboxes
Modified Sine with Constant Velocity (MSC50)
The modified sine with constant velocity profile (3rd order) is a modification of the
modified sine profile. It has a constant velocity during 50% of the motion.
General Modified Sine with Constant Velocity (MSC%)
The modified sine with constant velocity profile (3rd order) is a modification of the
modified sine profile. It has a constant velocity during a user definable part of the of the
motion. The non-zero acceleration part is defined by two parameters which are both
defined as a fraction of the motion. The first parameters alpha (%) defines the start of
the acceleration and the second parameters n (%) defines the end of the acceleration.
3-4-5 Polynomial
The is a third profile described by a 5th order polynomial.
20-sim 4.6 Reference Manual
407
8. Toolboxes
1-3-5-7-9 Polynomial
The is a third/fourth order profile described by a 9th order polynomial. The profile is
characterized by two parameters that denote the initial jerk, BB, and the crossover
jerk, BM. If BB is chosen zero, this a a fourth order profile. If BB is chosen non-zero,
this is a third order profile.
8.5.2
Motion Profile Wizard
Motion Profile Wizard
The 20-sim Motion Profile Wizard helps you to define motion profiles. To generate such a
profile, follow the next steps.
1.
Open the 20-sim model library an go to the section Signal\Sources.
2.
Drag and drop the model MotionProfileWizard.emx to the editor.
3.
Select the model and click Go Down.
This is a masked model. C licking Go Down will open the Motion Profile Wizard.
4.
Select the inputs and outputs:
20-sim 4.6 Reference Manual
408
8. Toolboxes
A number of inputs and outputs are available:
External Input: Normally the time will be used for the x-axis of the profile. You can
however use an external input as x-axis variable.
On/Off: Use this input signal to start (onoff = TRUE) and stop (onoff = FALSE) the
profile.
Reset: When the reset signal gets high (reset = TRUE) the profile will be started.
Reference: The motion profile reference signal, e.g. position.
First Derivative: The first derivative of the motion profile reference signal, e.g.
velocity.
Second Derivative: The second derivative of the motion profile reference signal, e.g.
velocity.
Profile C ounter: Gives the number of profiles that have been generated.
Ready Signal: Gets high (ready = TRUE) when the profile is completely generated.
5.
C lick Next to enter the desired profile.
6.
You can enter as many profiles as needed to design the complete motion. You can
choose out of a number of predefined profiles.
20-sim 4.6 Reference Manual
409
8. Toolboxes
7.
C hoose the number of times the motion should be repeated.
8.
C lick Next to go to the last page.
In the last page, you can choose to generate Time Events and what to show the next
time (the wizard or the generated code). Use the default settings if you are not sure
what to use.
20-sim 4.6 Reference Manual
410
8. Toolboxes
9.
C lick Next to go to close the Wizard.
10. In the Editor from the Model menu C heck C omplete Model to make the changes
effective.
Motion Profile Wizard (Old Style)
If you select the model MotionProfile.emx and click Go Down, the old style Motion
Profile Wizard will open. This wizard is kept in 20-sim to allow you to run old models. The
wizard has been replaced by a new wizard which is far more powerful.
Description
The 20-sim Motion Profile Wizard helps you to define motion profiles. To generate such a
profile, follow the next steps.
1.
Open the 20-sim model library an go to the section Signal\Sources.
2.
Drag and drop the model MotionProfile.emx to the editor.
3.
Select the model and click Go Down. Now the wizard will be opened.
4.
Select the type of motion.
5.
C hoose the desired profile and output signals.
20-sim 4.6 Reference Manual
411
8. Toolboxes
6.
Enter the profile parameters.
7.
C lose the wizard.
During simulation the parameter values are used that you have selected in the wizard.
These parameters are available in the Parameters Editor where you can change them as
you would do with any other model. If you have changed the settings of this wizard, you
have to process the model first (from the Model menu, choose Check Complete Model)
before the changes become effective.
Motion Profiles
You can choose out of a number of predefined motion profiles in the Motion Profile
Wizard.
Flat
Ramp
Trapezoidal
Partial Trapezoidal
Geneva Mechanism
Sine
C ubic
Partial C ubic
C ycloidal
Standard Modified Sine
Modified Trapezoidal
Modified Sine with C onstant Velocity (MSC 50)
General Modified Sine with C onstant Velocity (MSC %)
3-4-5 Polynomial
1-3-5-7-9 Polynomial
Flat
The flat profile is a zero order profile. It has a constant position, zero velocity and
acceleration.
Ramp
The ramp profile is a first order profile. It has a constant velocity and acceleration peaks
at the start and end of the motion.
20-sim 4.6 Reference Manual
412
8. Toolboxes
The ramp profile.
Trapezoidal
The trapezoidal profile is a second order profile. It has a constant acceleration at the
start of the motion and a constant deceleration at the end of the motion.
The trapezoidal profile.
This profile is most widely used in early servo systems. Because of the discontinuity in
the acceleration this motion profile can still induce a lot of vibrations. Therefore in
modern servo systems third order profiles are preferred.
Partial Trapezoidal
The partial trapezoidal profile is a second order profile. It has is equal to the trapezoidal
motion, but has a constant velocity part, during a fraction CV (%) of the motion.
20-sim 4.6 Reference Manual
413
8. Toolboxes
The partial trapezoidal profile.
Geneva Mechanism
A Geneva mechanism is an old motion profile generation mechanism. A continuously
rotating crankshaft (a) generates an intermittent motion of a second shaft (b). The result
is a second order profile.
A Geneva mechanism.
The motion profile generator yields the motion of the second shaft (b). It is shown
below:
The Geneva mechanism profile.
Sine
The sine profile is a second order profile of which the displacement can be described as:
20-sim 4.6 Reference Manual
414
8. Toolboxes
x = 0.5 - cos (p * t) / 2.
The sine profile.
Cubic
The cubic profile is a third order profile of which the acceleration is constantly increasing
and decreasing.
The cubic profile.
Partial Cubic
The partial cubic profile (3rd order) is a modified cubic profile with a constant velocity
during a fraction CV (%) of the motion and a constant acceleration during a fraction CA
(%) of the motion.
20-sim 4.6 Reference Manual
415
8. Toolboxes
The partial cubic profile.
Cycloidal
The cycloidal profile is a third order profile, of which the velocity can be described as:
v = stroke*(1-cos(t*a))
The cycloidal profile.
Modified Sine
The modified sine profile is also a third order profile. It is a modification of the cycloidal
profile to get a lower maximum velocity and a lower maximum acceleration.
20-sim 4.6 Reference Manual
416
8. Toolboxes
The modified sine profile.
Modified Trapezoidal
The modified trapezoidal profile is a modification of the trapezoidal profile (to make it a
third order profile). This profile yields a very low maximum acceleration.
The modified trapezoidal profile.
Modified Sine with Constant Velocity (MSC50)
The modified sine with constant velocity profile (3rd order) is a modification of the
modified sine profile. It has a constant velocity during 50% of the motion.
The modified sine with constant velocity profile.
20-sim 4.6 Reference Manual
417
8. Toolboxes
General Modified Sine with Constant Velocity (MSC%)
The modified sine with constant velocity profile (3rd order) is a modification of the
modified sine profile. It has a constant velocity during a user definable part of the of the
motion. The non-zero acceleration part is defined by two parameters which are both
defined as a fraction of the motion. The first parameters alpha (%) defines the start of
the acceleration and the second parameters n (%) defines the end of the acceleration.
The general modified sine with constant velocity profile.
3-4-5 Polynomial
The is a third profile described by a 5th order polynomial.
The 1-3-5 polynomial profile.
1-3-5-7-9 Polynomial
The is a third/fourth order profile described by a 9th order polynomial. The profile is
characterized by two parameters that denote the initial jerk, BB, and the crossover
jerk, BM. If BB is chosen zero, this a a fourth order profile. If BB is chosen non-zero,
this is a third order profile.
20-sim 4.6 Reference Manual
418
8. Toolboxes
The 1-3-5-7-9 polynomial profile.
To keep the polynomial consistent, i.e. the polynomial does not change when the
amplitude is changed, the initial jerk (BB) and the crossover jerk (BM) are defined for a
standard motion with:
stroke = 1
start_time = 0
stop_time = 1
Comparison of Profiles
The specific shape of a motion profile can have a significant influence on the dynamic
behavior. Some profiles minimize the maximum velocity, some profile minimize
acceleration, while other profiles tend to make a tradeoff between the maximum velocity
and acceleration. If we take a standard motion with stroke 1 and motion time 1 sec., the
following table can be generated:
profile
order
vmax
amax
j(0)
j(1/2)
Flat
0
0
0
0
0
Ramp
1
1
infinite
infinite
0
Trapezoidal
2
2
4
infinite
-infinite
Partial Trapezoidal1 2
1.67
4.17
infinite
0
Geneva Mechanism
2
2.41
8.49
infinite
-118.5
Sine
2
1.57
4.93
infinite
-15.5
C ubic
3
2
4
32
-32
Partial C ubic3
3
1.67
5.55
55.6
0
C ycloidal
3
2
6.28
39.5
-39.5
Modified Sine
3
1.76
5.53
69.4
-23.2
Modified Trapezoidal 3
2
4.88
61.4
-61.4
MSC 50
3
1.26
9.20
173.6
0
MSC %4
3
1.37
7.20
113.1
0
3-4-5 Polynomial
3
1.88
5.77
60
-30
20-sim 4.6 Reference Manual
419
8. Toolboxes
1-3-5-7-9
Polynomial5
3/4
2.05
10.25
BB
BM
1: Parameter C V = 20%
2: For lw >> lc the C rank Rod profile equals the sine profile, for lw > lc performance
deteriorates.
3: Parameter C V = 20%, C A = 20%
4: Parameter n = 30%, alpha = 10%
5: Parameter BB = 30%, BM = 10%
Here j(0) is the initial jerk yerk (derivative of acceleration) and j(1/2) the crossover
(halftime) jerk.
8.5.3
Servo Motor Editor
Servo Motor Editor
Introduction
The 20-sim Servo Motor Editor is a tool to generate dynamic models of servo motors for
the use in 20-sim. These models describe the complete dynamic behaviour of servo
motors, including the electrical, mechanical and thermal behaviour. The following classes
of motors are supported in the editor:
1.
Brush DC
2.
Brushless DC (trapezoidal EMC and square wave currents)
3.
AC synchronous (sinusoidal EMC and sinusoidal currents)
4.
AC synchronous linear (sinusoidal EMC and sinusoidal currents)
The dynamic models are generated automatically from data files containing
commercially available motors, but you can also enter your own motor parameters. The
following motors are available on data files:
1.
The complete Maxon 2005 / 2006 program.
2.
The complete Tecnotion 2006 program.
3.
The Faulhaber 2006 program.
In the first part of these help files, the use of the 20-sim Servo Motor Editor is explained.
The Editor uses a data table with motor parameters of commercial servo motors. You
can select any motor from the table, inspect the corresponding torque speed curve and
let the Servo Motor Editor generate a 20-sim dynamic model from the parameters.
20-sim 4.6 Reference Manual
420
8. Toolboxes
The second part of these help files, explains the operating principles of the motors. A
good indication of the performance of permanent magnet motors can be given by the
torque speed plot. Various curves of the torque speed plot and how this can be used to
choose the proper motor for a given task. An important part of the torque speed plot is
the maximum continuous torque. It is the maximum torque that a motor can deliver
without overheating. This curve is based on a thermal model of the motor, which is also
explained.
Use
The 20-sim Servo Motor Editor is part of the Mechatronics Toolbox of 20-sim. You can
open the editor by selecting the Servo Motor Editor command (Tools - Mechatronics
Toolbox). If you have a valid license, a servo motor model will be inserted:
Normally the editor will be opened automatically. If this does not happen, force the
editor to open by clicking the Go Down button. This Editor looks like:
20-sim 4.6 Reference Manual
421
8. Toolboxes
The top of the editor shows a list of motors. You can select one of the motors from the
list by selecting it with your mouse pointer. The selected motor is shown with the blue
line. The parameters of the selected motor are shown below the list.
To see the torque speed plot of the selected motor, click the Plot tab at the bottom of the
editor. To find a motor based on specific searching conditions, click the Search tab. By
clicking the OK button, a dynamic model will be created automatically, based on the
selected motor in the list.
Using the Edit menu, new motors can be added to the list or deleted. By double clicking
the mouse pointer on a parameter value, it can be changed.
20-sim 4.6 Reference Manual
422
8. Toolboxes
Data Files
If you open the Servo motor Editor, default data from file ServoMotor.csv is shown. You
can open other data files by using the file menu.
C urrently the following data files are available:
1.
ServoMotor.csv: A selection of various motors to show the capabilities of the Servo
Motor Editor.
2.
Maxon 2006.cse: The complete list of Maxon motors, program 2005 / 2006.
3.
Tecnotion 2006.cse: The complete list of Tecnotion motors, program 2006.
4.
Faulhaber 2006.cse.: Most of the Faulhaber motors, program 2006.
Parameters
Unfortunately not all motor suppliers use the same parameters in the data sheets.
Therefore the Servo Motor Editor uses the most common parameters as described in this
section. All parameters are defined using a motor temperature and ambient temperature
of 25° C .
General Data
This general section contains the unique identifier of the motor (Keyname) and some
additional data, which can be filled in freely.
Name
The name of the motor
Info
Additional Info
Keyname
A unique name (no duplicates allowed in the motor list)
to identify the motor.
Type
The motor type:
1. AC Synchronous
20-sim 4.6 Reference Manual
423
8. Toolboxes
2. Brush DC Iron
3. Brush DC moving coil
4. Brush DC Disc Rotor
5. AC Synchronous Linear
6. Brushless DC
In the Editor, you can select from a drop down list. In
the data file (see next section, the
corresponding
numbers are used).
Date
Date at which the motor info was entered
Price
The price of the motor
Delivery Time
Delivery Time
Library
The name of the data file that is used
Nominal Data
Many data sheets describe the nominal operating point of a motor. The nominal
operation point is characterized by a fixed current that is supplied to a motor with an
initial temperature of 25º C that will result in a heating up of the coils to the exactly the
maximum temperature. Because a current alone is not enough to describe the state of a
motor, the operating point is always given at a certain speed. Although the other
parameters (torque and power) can be derived from the current and speed they are
usually printed in most data sheets.
Torque [N.m]or Force[N] Torque or force at nominal operation.
C urrent [A] or [Arms]
C urrent at nominal operation.
Speed [rpm]or [m/s]
Speed at nominal operation.
Voltage [V] or [Vrms]
Voltage at nominal operation.
Power [W]
The output power at nominal operation.
Life [hour]
Expected Lifetime of the motor under normal operation.
As described, the definition of current and voltage depends on the selected motor:
motor
current
voltage
1. AC Synchronous
rms phase current (A)
rms phase to phase voltage
(V)
2. Brush DC Iron
current (A)
voltage (V)
3. Brush DC moving coil current (A)
voltage (V)
4. Brush DC Disc Rotor
voltage (V)
5.
AC
Linear
current (A)
Synchronous rms phase current (A)
rms phase to phase voltage
(V)
20-sim 4.6 Reference Manual
424
8. Toolboxes
6. Brushless DC
peak current (A)
peak phase to phase voltage
(V)
Max/Peak Values
The maximum parameters indicate the maximum performance of the motor and are
used to show the limits in the torque speed plot as explained in chapter 3. The
parameters do not indicate an operating point on the torque speed curve. The maximum
parameters are preferably measured at a temperature of 25º C .
Torque [N.m]or Force[N] The maximum short-time or torque or force (also known
as stall torque).
C urrent [A] or [Arms]
The maximum short-time current.
Speed [rpm]or [m/s]
The maximum speed.
Voltage [V] or [Vrms]
Maximum short-time voltage.
Power [W]
The maximum short time power.
The currents and voltages are defined the same as for the nominal parameters.
Electrical Data
R [ohm]
The resistance at 25° C .
L [H]
The terminal inductance.
alpha_c [1/degC ]
The temperature dependency of the coil resistance.
ktc [1/degC ]
The temperature dependency of the magnets.
poles [-] or pitch[m]
The number of poles (always an even number) or pole
pitch (distance N-N poles).
As described, the definition of resistance and inductance depends on the selected motor:
motor
resistance
1. AC Synchronous
phase
to
inductance
phase phase to phase inductance (H)
resistance (ohm)
2. Brush DC Iron
resistance (ohm)
inductance (H)
3. Brush DC moving coil resistance (ohm)
inductance (H)
4. Brush DC Disc Rotor
inductance (H)
5.
AC
resistance (ohm)
Synchronous phase
to
Linear
resistance (ohm)
6. Brushless DC
phase
to
phase phase to phase inductance (H)
phase phase to phase inductance (H)
resistance (ohm)
Mechanical Data
The mechanical data describes the motor inertia and losses.
20-sim 4.6 Reference Manual
425
8. Toolboxes
J_rotor [kg.m2] or m_motor [kg]
The rotor inertia or the the moving mass of
the motor.
d [N.m.s/rad]or [N.s/m]
Mechanical
damping
and
eddy
current
losses.
T_fric [N.m] or [N]
Mechanical friction and hysteresis losses.
T_cog [N.m] or [N]
The amplitude of the cogging torque.
Thermal Data
The thermal data is used for the thermal model as explained in chapter 4. Zero values
for the thermal resistances are replace by a small value (1e-2) to prevent division by
zero.
Temp_amb [degC ]
The ambient temperature.
Temp_initial [degC ]
The initial temperature of the coils and
housing.
Temp_max [degC ]
The maximum coil temperature.
RT1 [degC /W]
The thermal resistance between rotor and
stator.
RT2 [degC /W]
The thermal resistance between stator and
environment.
C T1 [J/degC ]
Thermal capacity of the rotor.
C T2 [J/degC ]
Thermal capacity of the stator.
Physical Data
This section describes the motor dimensions and maximal load.
F_axial [N]
The maximum axial force applied to the
motor shaft.
F_radial [N]
The maximum radial force applied to the
motor shaft.
m [kg]
The motor weight.
D_motor [m]
The motor diameter.
L_motor [m]
The motor length.
D_shaft [m]
The shaft diameter.
L_shaft [m]
The shaft length.
Derived Data
These are values that can be found in many data sheets. They are useful for selection
criteria when searching for motors.
20-sim 4.6 Reference Manual
426
8. Toolboxes
K_nom [N.m/A], [N.m/Arms] or [N/ The torque constant or force constant at
Arms]
25° C and nominal currents.
K_max [N.m/A], [N.m/Arms] or [N/ The torque constant or force constant at
Arms]
25° C and at peak currents.
S [N.m.s/rad] or [N.s/m]
The steepness.
tau_m [s]
The mechanical time constant (J_rotor/S or
m_motor/S).
P_dis [W]
The maximal continuous dissipation.
tau_T1 [s]
The thermal time constant of the rotor
(RT1* C T1).
tau_T2 [s]
The thermal time constant of the stator
(RT2* C T2).
Additional Data
20-sim model []
Not implemented yet.
How to use the Parameters
When you enter a new motor, not all parameters have to be filled in. In this section the
critical and non critical parameters are listed.
Critical
Only a few parameters are critical. I.e. they are necessary to generate a 20-sim
dynamic model.
Keyname
A unique name to identify the motor.
Type
The motor type.
Maximum Torque or Force
The maximum
short-time
or
torque
or
force.
Maximum C urrent
The maximum short-time current.
R
The resistance at 25° C .
L
The terminal inductance.
J_rotor or m_motor
The rotor inertia or the the moving mass of
the motor.
Desired
Some parameters are desired. I.e. they add more detail to the model:
20-sim 4.6 Reference Manual
427
8. Toolboxes
Nominal Torque or Force
Torque or force at nominal operation.
Nominal C urrent
C urrent at nominal operation.
Nominal Speed
Speed at nominal operation.
alpha_c
The temperature dependency of the coil
resistance.
ktc
The
temperature
dependency
of
the
magnets.
poles or pitch
The number of poles (always an even
number) or pole pitch (distance N-N poles).
d
Mechanical
damping
and
eddy
current
losses.
T_fric
Mechanical friction and hysteresis losses.
T_cog
The amplitude of the cogging torque.
Temp_amb
The ambient temperature.
Temp_initial
The initial temperature of the coils and
housing.
Temp_max
The maximum coil temperature.
RT1
The thermal resistance between rotor and
stator.
RT2
The thermal resistance between stator and
environment.
C T1
Thermal capacity of the rotor.
C T2
Thermal capacity of the stator.
If you do not know the values of these parameters, fill in zero. 20-sim will automatically
change some into small numbers to prevent division by zero. Because the nominal
torque and current are used to derive the torque constant at nominal operation, they will
be replaced by the maximum current and torque if you fill in a zero value.
Torque Speed Plot
Some parameters will add more detail to the torque speed plot:
Speed
The maximum speed.
Voltage
Maximum short-time voltage.
Power
The maximum short time power.
20-sim 4.6 Reference Manual
428
8. Toolboxes
Additional
The remaining parameters are not used in the torque speed plot or the 20-sim model.
They are useful for selection criteria when searching motors. If you do not know the
values of these parameters, fill in zero.
Dynamic Model
If you have selected a motor, clicking the OK button will close the editor and generate a
dynamic model. The model will be filled with the parameters from the selected motor
and is ready for the use in a simulation. The model contains a number of variables that
may be useful to show in a simulation plot.
General Part
R
resistance
at
simulated
(fluctuating)
temperature
K
torque constant at simulated (fluctuating)
temperature
u_rms_ff
effective terminal (phase-phase) voltage
u_tt_ff
maximum terminal (phase-phase)
i_tt
maximum phase current
phi
shaft angle
Thermal part
Temp_coil
coil temperature
Temp_housing
housing temperature
Torque speed plot
omega_range
speed ranging from zero to over 5% of
maximum speed
T_range
torque ranging from zero to over 5% of
maximum torque
Torquemax
maximum torque
Speedmax
maximum speed
T_max_power
torque at maximum power
T_max_current
torque at maximum current
T_max_outputpower
line of maximum output torque
T_max_voltage
torque at maximum voltage
T_max_efficiency
line of torque at maximum efficiency
T_100
maximum allowable continuous torque, (i.e.
a 100% duty cycle)
20-sim 4.6 Reference Manual
429
8. Toolboxes
T_50
maximum allowable torque for a 50% duty
cycle
T_25
maximum allowable torque for a 25% duty
cycle
T_10
maximum allowable torque for a 10% duty
cycle
T_abs
absolute output (load) torque
omega_abs
absolute velocity
Creating your own data files
The motor parameters are visible in the Grid tab. These parameters are stored in a
coma separated data file (extension .csv) or in an encrypted coma separated data file
(extension .cse).
By default, the file ServoMotor.csv is shown. Using the File menu you can store and
open csv files. The csv files can be edited with the Servo Motor Editor or an external
spreadsheet program like OpenOffice. In OpenOffice Calc the file looks like:
The top 5 rows contain the description of the motor parameters and the corresponding
units. The first and second row are used for rotation motors and the third and fourth row
are used for linear (translation) motors. The fifth row contains the parameter names.
The other rows contain the motor parameters. The meaning of these parameters is
described in the previous sections. Please use the following guidelines when editing data
files:
1.
Never change the first five lines
2.
Do no use duplicate names in the first column (keyname)
3.
Do use commas
20-sim 4.6 Reference Manual
430
8. Toolboxes
4.
Do no use strange formatting (in Excel use the General format)
5.
Do no enter extra columns
6.
Do net enter other information in additional rows or columns. The Servo Motor Editor
will try to read all cells and halt if the content is not according the specifications.
7.
Do no add comment.
8.
The last column entry (20-sim) should contain one white space character.
9.
Store as comma separated file.
Data Files
Maxon 2005 / 2006
File
20-sim 3.6\Tools\Servo Motor Dynamics\Maxon 2006.cse
Date
November 2005
More information
www.maxonmotors.com
Description
The data file Maxon 2006.cse contains the complete set of Maxon motors, program
2005 / 2006. Most of the data has been extracted from the Maxon data sheets. The
tables below shows the 20-sim names and the corresponding data sheet names. Some
parameters were not available in the data sheets and have been given by the Maxon
motor company. These parameters are indicated as Given by Maxon. Some parameters
were calculated. These are indicated as Calculated.
DC motors
Servo Motor Editor
Maxon Data Sheets
General Data
Name
Keyname
Info
Type
Date
Price
Delivery Time
Library
Nominal Data
Motor Series
Maxon Order Number
Additional Information
DC
21 October 2005
stock / standard / special
Maxon 2006.cse
Torque
C urrent
Speed
Voltage
Max. continuous torque
Max. continuous current
No load speed divided by 2
C alculated
20-sim 4.6 Reference Manual
431
8. Toolboxes
Power
Max/Peak Data
C alculated
Torque
C urrent
Power
Voltage
Speed
Thermal Data
Stall torque
Starting current
Assigned Power Rating
C alculated*
Max. permissible speed
Temp_amb
Temp_initial
Temp_max
RT1
RT2
C T1
C T2
Physical Data
F_axial
F_Radial
m
D_motor
L_motor
D_shaft
L_shaft
Electrical Data
Set to 25
Set to 25
Maximum rotor temperature
Thermal resistance rotor-housing
Thermal resistance housing-ambient
C alculated
Given by Maxon
R
L
alpha_c
Ktc
Poles
Mechanical Data
Terminal resistance
Terminal inductance
Given by Maxon
Given by Maxon
Number of poles
J_rotor
d
T_fric
T_cog
Derived Data
Rotor inertia
Given by Maxon
Given by Maxon
0
K_nom
K_max
S_nom
P_dis
C alculated
C alculated
C alculated
C alculated
Maximum Axial load
Maximum radial load
Weight of motor
Diameter of motor
Length of motor
Diameter shaft
Length Shaft
* In the data sheets Maxon only gives a nominal voltage. According to Maxon higher
operating voltages are permissible provided that other limits are not exceeded.
Therefore the maximum voltage is chosen equal to the voltage that is needed to run a
motor with zero load at maximum speed.
EC motors with block commutation
Maxon EC motors can be driven by block commutation and sine commutation. The
Maxon data sheets give the parameters for block commutation. To distinguish between
block commutation and sine commutation the character b or s is added to the keyname.
20-sim 4.6 Reference Manual
432
8. Toolboxes
Servo Motor Editor
General Data
Name
Keyname
Info
Type
Date
Price
Delivery Time
Library
Nominal Data
Torque
C urrent
Speed
Voltage
Power
Max/Peak Data
Torque
C urrent
Power
Voltage
Speed
Thermal Data
Temp_amb
Temp_initial
Temp_max
RT1
RT2
C T1
C T2
Physical Data
F_axial
F_Radial
m
D_motor
L_motor
D_shaft
L_shaft
Electrical Data
R
L
alpha_c
Ktc
Poles
Mechanical Data
J_rotor
d
T_fric
T_cog
Derived Data
K_nom
Maxon Data Sheets
Motor Series
Maxon Order Number + b
Additional Information
Brushless DC
21 October 2005
stock / standard / special
Maxon 2006.csv
C alculated
Max. continuous current
Nominal speed
C alculated
C alculated
Stall torque
C alculated
Assigned Power Rating
C alculated*
Max. permissible speed
Set to 25
Set to 25
Maximum rotor temperature
Thermal resistance rotor-housing
Thermal resistance housing-ambient
C alculated
C alculated
Maximum Axial load
Maximum radial load
Weight of motor
Diameter of motor
Length of motor
Diameter shaft
Length Shaft
Terminal resistance phase to phase
Terminal inductance phase to phase
Given by Maxon
Given by Maxon
Number of poles
Rotor inertia
Given by Maxon
Given by Maxon
0
C alculated
20-sim 4.6 Reference Manual
433
8. Toolboxes
K_max
S_nom
P_dis
C alculated
C alculated
C alculated
* In the data sheets Maxon only gives a nominal voltage. According to Maxon higher
operating voltages are permissible provided that other limits are not exceeded.
Therefore the maximum voltage is chosen equal to the voltage that is needed to run a
motor with zero load at maximum speed.
EC motors with sine commutation
Maxon EC motors can be driven by block commutation and sine commutation. The
Maxon data sheets give the parameters for block commutation. The parameters for sine
commutation can be calculated from the block commutation parameters. To distinguish
between block commutation and sine commutation the character b or s is added to the
keyname.
Servo Motor Editor
General Data
Name
Keyname
Info
Type
Date
Price
Delivery Time
Library
Nominal Data
Torque
C urrent
Speed
Voltage
Power
Max/Peak Data
Torque
C urrent
Power
Voltage
Speed
Thermal Data
Temp_amb
Temp_initial
Temp_max
RT1
RT2
C T1
C T2
Physical Data
F_axial
F_Radial
m
D_motor
Maxon Data Sheets
Motor Series
Maxon Order Number + s
Additional Information
AC Synchronous
21 October 2005
stock / standard / special
Maxon 2006.csv
C alculated
C alculated
Nominal speed
C alculated
C alculated
C alculated
C alculated
Assigned Power Rating
C alculated*
C alculated
Set to 25
Set to 25
Maximum rotor temperature
Thermal resistance rotor-housing
Thermal resistance housing-ambient
C alculated
C alculated
Maximum Axial load
Maximum radial load
Weight of motor
Diameter of motor
20-sim 4.6 Reference Manual
434
8. Toolboxes
L_motor
D_shaft
L_shaft
Electrical Data
R
L
alpha_c
Ktc
Poles
Mechanical Data
J_rotor
d
T_fric
T_cog
Derived Data
K_nom
K_max
S_nom
P_dis
Length of motor
Diameter shaft
Length Shaft
Terminal resistance phase to phase
Terminal inductance phase to phase
Given by Maxon
Given by Maxon
Number of poles
Rotor inertia
Given by Maxon
Given by Maxon
0
C alculated
C alculated
C alculated
C alculated
* In the data sheets Maxon only gives a nominal voltage. According to Maxon higher
operating voltages are permissible provided that other limits are not exceeded.
Therefore the maximum voltage is chosen equal to the voltage that is needed to run a
motor with zero load at maximum speed.
Tecnotion 2006
File
20-sim 3.6\Tools\Servo Motor Dynamics\Tecnotion 2006.cse
Date
November 2006
More information
www.tecnotion.com
Description
The data file Tecnotion 2006.cse contains the complete set of Tecnotion motors, program
2006. Most of the data has been extracted from the Tecnotion data sheets. The tables
below shows the 20-sim names and the corresponding data sheet names. Some
parameters were not available in the data sheets and have been given by the Tecnotion
motor company. These parameters are indicated as Given by Tecnotion. Some
parameters were calculated. These are indicated as Calculated.
Important: The nominal data and the default value of the thermal resistance RT2 are
calculated for air cooling. The value for RT2 can be changed using a slider. If water
cooling is used, change the value of RT2 to its minimum value.
Servo Motor Editor
Tecnotion Data Sheets
General Data
20-sim 4.6 Reference Manual
435
8. Toolboxes
Name
Keyname
Info
Type
Date
Price
Delivery Time
Library
Nominal Data
Motor Series
Order Number
Additional Information
AC Synchronous Linear
21 October 2005
Tecnotion 2006.cse
Force
C urrent
Speed
Voltage
Power
Max/Peak Data
C ontinuous Force (air cooled*)
C ontinuous C urrent (air cooled*)
0 m/s
C alculated
-
Force
C urrent
Power
Voltage
Speed
Thermal Data
Ultimate Force / Peak Force
Ultimate C urrent / Peak C urrent
C alculated
Max. voltage ph-ph
Maximum speed
Temp_amb
Temp_initial
Temp_max
RT1
RT2
C T1
C T2
Physical Data
F_axial
F_Radial
m
D_motor
L_motor
D_shaft
L_shaft
Set to 25
Set to 25
Maximum Temperature
Thermal Resistance coil - housing
C alculated*
Given by Tecnotion
Given by Tecnotion
-
Electrical Data
R
L
alpha_c
Ktc
Pitch
Mechanical Data
2 * Resistance per phase
2 * Induction per phase
0.004
0
Magnet Pitch NN
m_motor
d
F_fric
F_cog
Derived Data
Weight of C oilunit
Given by Tecnotion
0
20-sim 4.6 Reference Manual
436
8. Toolboxes
K_nom
K_max
S_nom
P_dis
C alculated
C alculated
C alculated
C alculated
* Note: The nominal data and the default value of the thermal resistance RT2 are
calculated for air cooling. The value for RT2 can be changed using a slider. If water
cooling is used, change the value of RT2 to its minimum value.
Faulhaber 2006
File
20-sim 3.6\Tools\Servo Motor Dynamics\Faulhaber 2006.cse
Date
February 2006
More information
www.faulhaber-group.com or www.minimotor.ch
Description
The data file Faulhaber 2006.cse contains the most of the Faulhaber servo motors,
program 2006. Most of the data has been extracted from the Faulhaber data sheets. The
tables below shows the 20-sim names and the corresponding data sheet names. Some
parameters were not available in the data sheets and have been given by Faulhaber.
These parameters are indicated as Given by Faulhaber. Some parameters were
calculated. These are indicated as Calculated.
DC motors
Servo Motor Editor
Faulhaber Data Sheets
General Data
Name
Keyname
Info
Type
Date
Price
Delivery Time
Library
Nominal Data
Motor Name
Faulhaber Order Number
Additional Information
DC
23 February 2006
Faulhaber 2006.cse
Torque
C urrent
Speed
Voltage
Power
Max/Peak Data
C alculated
C urrent up to
No load speed divided by 2
C alculated
C alculated
Torque
C urrent
Stall torque
C alculated
20-sim 4.6 Reference Manual
437
8. Toolboxes
Power
Voltage
Speed
Thermal Data
Output Power
Nominal Voltage
No-load speed
Temp_amb
Temp_initial
Temp_max
RT1
RT2
C T1
C T2
Physical Data
F_axial
F_Radial
m
D_motor
L_motor
D_shaft
L_shaft
Electrical Data
Set to 25
Set to 25
Maximum coil temperature
Thermal resistance rotor – housing Rth1
Thermal resistance housing-ambient Rth1
C alculated
C alculated
R
L
alpha_c
Ktc
Poles
Mechanical Data
Terminal resistance
Rotor Inductance
Temperature coefficient of resistance of copper
Given by Faulhaber
Given by Faulhaber
J_rotor
d
T_fric
T_cog
Derived Data
Rotor inertia
Friction torque, dynamic
Friction torque, static
0
K_nom
K_max
S_nom
P_dis
C alculated
C alculated
C alculated
C alculated
Maximum Axial load
Maximum radial load
Weight of motor
Diameter of motor
Length of motor
Diameter shaft
Length Shaft
DC Brushless motors with block commutation
Servo Motor Editor
Faulhaber Data Sheets
General Data
Name
Keyname
Info
Type
Date
Price
Delivery Time
Library
Motor Name
Faulhaber Order Number
Additional Information
DC Brushless
23 February 2006
Faulhaber 2006.cse
20-sim 4.6 Reference Manual
438
8. Toolboxes
Nominal Data
Torque
C urrent
Speed
Voltage
Power
Max/Peak Data
Torque up to
C urrent up to
At speed
C alculated
C alculated
Torque
C urrent
Power
Voltage
Speed
Thermal Data
Stall torque
C alculated
Output Power
Nominal Voltage
No-load speed
Temp_amb
Temp_initial
Temp_max
RT1
RT2
C T1
C T2
Physical Data
F_axial
F_Radial
m
D_motor
L_motor
D_shaft
L_shaft
Electrical Data
Set to 25
Set to 25
Maximum coil temperature
Thermal resistance rotor – housing Rth1
Thermal resistance housing-ambient Rth1
C alculated
C alculated
R
L
alpha_c
Ktc
Poles
Mechanical Data
Terminal resistance
Rotor Inductance
Temperature coefficient of resistance of copper
Given by Faulhaber
Given by Faulhaber
J_rotor
d
T_fric
T_cog
Derived Data
Rotor inertia
Friction torque, dynamic
Friction torque, static
0
K_nom
K_max
S_nom
P_dis
C alculated
C alculated
C alculated
C alculated
Maximum Axial load
Maximum radial load
Weight of motor
Diameter of motor
Length of motor
Diameter shaft
Length Shaft
20-sim 4.6 Reference Manual
439
8. Toolboxes
Theory
Basic Principles
Permanent Magnet Motors
When permanent magnets are used in a motor, a magnetic field will be present with a
magnetic flux density B. Suppose an electric coil is placed in this magnetic field. When
an electric current i is forced to flow through this coil, a force acting on the coil will
occur.
The resulting torque can be found as:
where Ktc(q) denotes the transfer of current to torque. It is a function of the angle,
shape of the coil, magnetic field density, current distribution etc. When the current is
kept equal to zero and we start to rotate the coil, a voltage will be induced. This voltage
is called the electromotive force (EMF) and can be found as:
where Kec(q) denotes the transfer of speed to voltage. It is also function of the angle,
shape of the coil, magnetic field density, current distribution etc. For an ideal coil the
input power should be equal to the output power
and thus
20-sim 4.6 Reference Manual
440
8. Toolboxes
In most literature the Kc(q) is calculated out of the magnetic field and coil distribution.
Here it is simply assumed to be given and is called the torque function.
In normal operation a coil will have a resistance and inductance. A basic coil model is
thus equal to:
By a proper design of the motor, i.e. geometry of the coil windings, magnets etc., the
torque function Kc(q) can be given a particular shape. Then by proper manipulation of
the current a positive torque can be created during the whole rotation of the coil. All
permanent magnet motors are based on this principle.
Brush DC Motors
In DC motors, the torque function Kc(q) is sinusoidal:
In DC motors a constant current is supplied. Through a process called commutation, the
coil is connected the other way around (i.e the current changes sign) when the coil
function crosses zero. The resulting torque will then always be positive but will vary
between zero and maximum:
By combining coils, the resulting torque variation or ripple will decrease. The graph
below shows the resulting torque when three coils are used.
20-sim 4.6 Reference Manual
441
8. Toolboxes
The more coils are used the more the torque ripple decreases.
number of coils
torque ripple (top-top)
3
14%
5
5%
7
2.5%
9
1.5%
11
1%
If we neglect the torque ripple, we get the common DC motor equations:
Commutation
In practical motors, the rotor is equipped with a commutator. A commutator consists of
insulated collector bars that are connected with the coils. Each coil is connected with one
end to a collector and the next end to the neighboring collector. A pair of brushes is used
to connect an outside current source to the collectors.
20-sim 4.6 Reference Manual
442
8. Toolboxes
Every rotation the current changes sign twice, resulting in a continuous positive torque
addition of every coil.
Limits
C ommutation is the largest limiting factor in DC motor performance. Sparks between the
brushes and the collectors are the main causes for brush wear. There are several
causes for sparking, which limit the maximum speed, current, voltage and power of a
brush DC motor.
When the brush leaves a collector, the current has to be reversed. The time that is
needed to reverse the current depends directly on the current amplitude and thus on the
generated torque. Because the time that is available depends on the motor speed, the
result is a limit on the power that can be generated.
Another limitation of the motor speed is due to imperfect dimensions of the collectors.
Differences in height of a few microns may cause the brushes to jump at high speeds.
Just a small part of the contact area of a brush and collector is actually used for the
current transfer. As a result highly localized, short time "hot spots" develop. When the
currents get greater than permitted, local temperatures occur that lead to material
evaporation.
Above a voltage of 15 to 18V experience shows that the air will experience ionization
phenomena, which leads to arcing. This arc extends from one collector bar to another.
When enough voltage is applied, the arc will extend several collector bars and reach the
other brush, leading to serious damage. The maximum motor voltage is therefore the
result of multiplying the number of collector bars between the brushes and the maximum
collector bar voltage.
Permanent magnets can lose their strength when operating above temperatures of 60
ºC and suppressed by a high external magnetic field. Such a field can occur when large
current changes occur. Therefore the maximum current of a motor should be limited.
20-sim 4.6 Reference Manual
443
8. Toolboxes
Brushless DC Motors
Given motor with three coils, where the coils are mounted in the stator with a spatial
displacement of 120°. The coils are connected in a star-formation as shown in the figure
below.
In Brushless DC motors, the coils and magnets are designed so that a trapezoidal torque
function Kc(q) is found as shown below:
To get a constant torque each coil current is a block wave as shown in the figure below.
Although the current is thus alternating, the term DC is used to distinguish this type of
motor from motors that used a sinusoidal current. The block wave current is provided
through "electronic commutation". The current is generated by a three phase amplifier
that gets the exact switching points from a motor controller.
20-sim 4.6 Reference Manual
444
8. Toolboxes
As can easily be seen from the graphs, the resulting torque is constant and twice the
current times the amplitude of the coil function:
To get an equivalent of the coil model we can write this equation as:
We have to realize that here i is not a constant current anymore but the maximum coil
current! Because the coil current is the current of one of the three phases, in literature i
is mostly written as the maximum phase current. It is the maximum current that can
be measured at each of the three terminals of the motor.
In a derivation that goes beyond the scope of this introduction (see C ompter, 2004), it
can be shown that the electromotive force can be found as:
Here the electromotive force is defined as the maximum induced voltage between two
phases. The resulting motor model is shown below:
20-sim 4.6 Reference Manual
445
8. Toolboxes
The voltage of the motor model is commonly known as the maximum phase to phase
voltage. It is the maximum voltage that can be measured between any pair of two
terminals. The phase to phase resistance and phase to phase inductance are
defined equivalent as the resistance and inductance that can be measured between any
pair of two terminals.
Limits
Brushless DC motors have no mechanical commutation, and therefore do not suffer
from the limits caused by mechanical commutation. C onsequently Brushless DC motors
can run at much higher speeds and are not limited by a maximum voltage. The speed of
Brushless DC motors is only limited by the bearings.
Just like brush DC motors the magnets impose an upper limit for the current and torque
in a Brushless DC motor.
AC synchronous motor
AC synchronous motors use the same principle as Brushless DC -motors. The coils are
also mounted in the stator with a spatial displacement of 120°.
The coils and magnets are designed so that a sinusoidal torque function Kc(q) is found
as shown below:
20-sim 4.6 Reference Manual
446
8. Toolboxes
To get a constant torque each coil current is a sinusoidal wave as shown in the figure
below.
As can be seen from the graph, the resulting torque is constant and one and a half times
the current times the amplitude of the coil function:
To get an equivalent of the coil model we can write this equation as:
We have to realize that here i is not a constant current anymore but the root mean
square coil current! Because the coil current is the current of one phase in literature i is
mostly denoted as the rms phase current. It is the rms current that can be measured
at each of the three terminals of the motor.
20-sim 4.6 Reference Manual
447
8. Toolboxes
In a derivation that goes beyond the scope of this introduction (see C ompter, 2004), it
can be shown that the electromotive force can be found as:
Here the electromotive force is defined as the induced rms voltage between two phases.
The resulting motor model is shown below:
The voltage of the motor model is mostly denoted as the rms phase to phase
voltage. It is the rms voltage that can be measured between any pair of two terminals.
The phase to phase resistance and phase to phase inductance are defined
equivalent as the resistance and inductance that could be measured between any pair of
two terminals.
Limits
AC synchronous motors have no mechanical commutation, and therefore do not suffer
from the limits caused by mechanical commutation. C onsequently AC synchronous
motors can run at much higher speeds and are not limited by a maximum voltage. The
speed of AC synchronous motors is only limited by the bearings.
Just like brush DC motors the magnets impose an upper limit for the current and torque
in a AC synchronous motor.
Linear Motors
The working principle of linear motors is exactly the same as for rotary motors. Magnets
are place on a flat surface, as shown in the figure below. A carriage holding the coils can
run over the magnets.
When the carriage runs over the magnets an electromotive voltage will be induced:
20-sim 4.6 Reference Manual
448
8. Toolboxes
with Kc(x) the force function of the coil. It is a function of the carriage position, shape
of the coil, magnetic field density, current distribution etc. The force function in a linear
motor is equivalent to the torque function of a rotary motor. When a current runs
through the coil a force results:
The principle for linear motor is the same as the principle of rotary motors. By a proper
design of the motor, i.e. geometry of the coil windings, magnets etc., the force function
Kc(x) can be given a particular shape. By proper manipulation of the current a positive
force can be created during the movement of the carriage. Because mechanical
commutation is not very useful for linear movements, linear motors use electronic
commutation. Like their rotary counterparts, linear motors can be driven by block shape
currents (Brushless DC Linear) and sinusoidal currents (AC Synchronous Linear).
Limits
The limits for linear motors are equal to the Brushless DC and AC synchronous motors
when torque is replaced by force and angular speed by linear speed.
Star and Delta Networks
Brushless DC motors and AC synchronous motors use three phase currents to connect
to three groups of coils. The connection can be made use a star network or a delta
network. C ompared to star networks, in a delta network less voltage and more current
is needed to produce the same amount of torque. For amplifiers the maximum current is
directly related to the costs. That is why delta networks are only used in special cases
where higher speeds than normal are required.
In 20-sim the electrical resistance and inductance are measured between the terminals
(e.g. between 1 and 2 or 2 and 3 or 3 an 1). This is known as the terminal resistance
and inductance or as the phase to phase resistance and inductance. There are
two reasons for using terminal values. Most motor suppliers give the terminal values in
their data sheet and by using terminal values the same dynamic model can be used for
star networks and delta networks.
20-sim 4.6 Reference Manual
449
8. Toolboxes
If the motor supplier gives coil values instead of terminal values, you have to calculate
them by hand. The relation between the terminal values and the coil values is:
Torque Speed Plot
General Model
The DC motor model can serve as a prototype model for all permanent magnet motors.
Although the models for DC Brushless and AC synchronous motors are slightly different,
the DC motor model is still very useful to explain their operation. In this chapter the DC
motor model will be used to derive the torque speed plot of a motor and show the use of
the torque speed plot for motor selection.
The working principle for all permanent magnet motors is the same: get a constant
torque by manipulation of the coil function and the current. The relation between the
torque and current is:
The constant KT is generally known as the torque constant. The relation between the
induced current and the rotational speed is:
The constant Ke is generally known as the voltage constant. For DC motors the torque
constant and voltage constant have the same value. Therefore the subscripts T and e
are usually omitted. The total voltage can be described as:
If we assume the current is changing only very slowly, the current derivative can be
neglected:
20-sim 4.6 Reference Manual
450
8. Toolboxes
With the torque equation:
this leads to
The torque at zero speed (stall torque) is found as
which enables us to write the torque as:
where S is commonly know as the steepness. The steepness has many definitions:
The speed where the current is zero (no load speed) is equal to
The relation between stall torque and no load speed is obvious:
which leads to the general torque equation:
This equation can be displayed graphically and is commonly known as the torque speed
plot. The graph shows the generated torque as a function of the speed. For constant
voltages a straight line from the stall torque to the no load speed is found. The slope of
the line is equal to the steepness S.
20-sim 4.6 Reference Manual
451
8. Toolboxes
The torque speed plot is a useful representation of a motor because we can draw the
desired load torque in this plot and to see if the motor is able to produce this torque. In
the figure below the load curve is shown in red. It is a constant torque applied to a load,
which makes it accelerate until a certain velocity is reached and the torque gets zero.
The red dot indicates the point of maximum load power. This point is important because
it indicates the maximum power that the motor has to deliver.
Limits
To find out if a motor is sufficient, we have to plot the motor limits in the torque speed
plot. In the previous chapter we have described the following limits:
Limit
Brush DC
torque / current
V
V
speed
V
V
power
V
X
20-sim 4.6 Reference Manual
Brushl
452
8. Toolboxes
voltage
V
X
Maximum Voltage
For higher voltages, a higher stall torque and no load speed is found but the steepness
does not change.
Maximum Torque / Maximum Current
In many data sheets a maximum torque is given. This is directly connected with a
maximum current limit through the equation:
So both the maximum current and the maximum torque appear as horizontal lines in the
torque speed plot.
Maximum Velocity
The maximum velocity can be directly indicated in the torque speed plot as a vertical
line.
20-sim 4.6 Reference Manual
453
8. Toolboxes
Maximum Power
The line of maximum power can be indicated as a parabola in the torque speed plot.
20-sim 4.6 Reference Manual
454
8. Toolboxes
Safe Operating Area
If the limits are plotted in the torque speed plot, an Area of Safe Operation is found. For
a proper motor, the torque speed curve of the load should be inside the Safe
Operating Area (SOA). The figures below show the safe operating areas for the
various motor types. Brush DC -motors (left figure) have a safe operating area that is
more limited than Brushless DC motors and AC synchronous motor (right figure).
In practice motor suppliers of Brushless DC motors and AC synchronous motors may
impose limits on the maximum voltage and power. This is mostly done to prevent
heating up the motor too quickly during continuous operation, or material limits. This
makes the Safe Operating Area of these motors look like that of a DC motor. C ompared
to DC motors, Brushless DC motors and AC synchronous motors will always allow higher
torques and speeds because of the absence of mechanical commutation.
Losses
Every motor will experience losses, which results in a temperature rise. The maximum
allowed temperature is limited by the magnets, the oil in the bearings and the
mechanical behaviour of the brushes. Analysis of the cause of losses is therefore
important for the correct choice of a motor.
Electric Dissipation
All motor coils have resistance and will therefore generate heat. The heat flow generated
is equal to:
which can also be written as:
with irms the root mean square current:
20-sim 4.6 Reference Manual
455
8. Toolboxes
For constant DC currents the root mean square value is equal to the current itself. For
sinusoidal currents, the root mean square value is equal to the amplitude of the current
times the square root of 2.
Hysteresis losses
In all motors except from hollow rotor motors, the magnets move with respect to the
iron core of the motor. This results in a reversing magnetic field in the iron which leads
to hysteresis.
Each rotation produces an energy loss proportional to the area of the hysteresis curve
(B/H). The power loss due to hysteresis is proportional to the motor speed and can
therefore be represented as a friction torque. Due to this friction torque the motor can
produce less output torque. This friction torque can therefore be represented in the
torque speed plot as a drop down of all curves.
Eddy Current losses
A reversing magnetic field in iron also leads to an induce voltage. The resistance of the
iron determines the resulting currents in the iron. These currents are named eddy
currents.
20-sim 4.6 Reference Manual
456
8. Toolboxes
Eddy currents heat up the iron because of its resistance. If a massive iron return is used
large eddy currents will be induced with high power losses. Therefore in most motors
laminated is applied, which reduce eddy currents by decreasing the path length and thus
lead to smaller small power losses. The power loss due to eddy currents is proportional
to the square of the motor speed and can therefore be modeled as mechanical damping.
Damping will decrease the performance of the motor. It can be represented in the
torque speed plot as a falling down of curves that increases with the speed.
Cogging
In a permanent magnet motors cogging torque manifests itself by the tendency of the
rotor to align in a number of stable positions when unexcited. The cogging torque can be
described as:
where q is the motor angle and p the number of poles. Although cogging does not
consume power and is not visible in the torque speed plot, under dynamic conditions it
may cause undesirable speed pulsation and also may induce vibrations and acoustic
noise.
Mechanical Losses
Mechanical losses in motors are caused by bearings, brushes and air friction. Only when
an air fan is mounted air friction becomes significant. The effects of brushes and
bearings can be represented by coulomb friction and damping.
20-sim 4.6 Reference Manual
457
8. Toolboxes
Temperature
As a result of the heat flow, the motor will warm up leading to two major effects. First of
all the coil resistance will increase. Because all coils are made of copper, the
temperature dependency of the coil resistance can be written as:
where R25 is the coil resistance at room temperature (25 degrees centigrade) and Tcoil
the actual coil temperature in degrees centigrade. As a result of the increase of motor
temperature, the performance of the magnets will decrease. The result is a decrease of
the torque constant :
where K25 is the torque constant at room temperature (25 degrees centigrade),
Tmagnet the actual magnet temperature in degrees centigrade and ktc the temperature
dependency of the used magnet.
Magnets
ktc
Ferrites
-0.002
Nd2Fe 14B
-0.0013
SmC o
-0.0005
AlNiC o
-0.0002
Because the steepness is directly dependent of the torque constant and motor resistance
an increase of temperature will lead to a decrease of the steepness. The results of a
temperature increase can therefore be shown in the torque speed plot indirectly through
the decrease of the maximum torque and steepness.
20-sim 4.6 Reference Manual
458
8. Toolboxes
Thermal Duty Cycle
Motor losses result in an increase of the temperature. During short term operation the
temperature increase will be limited. During long-term operation, the generated heat
and the amount of heat that can be removed via the air and motor mounting determine
the temperature increase.
In most motors, the largest portion of the generated heat is cause by electric dissipation.
The generated heat is therefore directly proportional to the current and thus the torque.
Imagine a motor in long-term operation generating a constant torque. A small torque will
lead to only a moderate increase of the motor temperature, but there will be a certain
torque where the generated heat leads to an increase of the maximum motor
temperature. This is called the maximum continuous torque or the 100% Thermal
Duty Cycle (TDC). The line of the maximum continuous torque can be shown in the
torque speed plot and is often denoted as T100. For lower speeds the T100 curve will be
straight because the heat generation mainly depends on depends on electric dissipation.
For higher speeds the T100 curve will decrease because eddy current losses start to
become significant.
If the motor is in continuous operation, but a constant torque is just delivered 50% of
the time, a higher torque is permissible. This torque is denoted as T50 and sometimes
called the 50% thermal duty cycle. In a similar way T25 and T10 are defined.
20-sim 4.6 Reference Manual
459
8. Toolboxes
Nominal Operating Point
Many motor manufacturers give in their data sheets a nominal or continuous current at a
certain speed. This indicates an operating point on the T100 curve. The nominal or
continuous current is the current that continuously be continuously be supplied to the
motor at the given speed, which will result in a heating up of the coils to the maximum
temperature.
The nominal operating point is always based on a certain ambient temperature. In the
20-sim Servo Motor Editor an ambient temperature of 25 ºC is used.
The choice of the speed for the nominal operation point is arbitrary. Some motor
suppliers use the speed that results in a maximum power output at the motor shaft.
Some motor suppliers use a speed that is half of the maximum allowed speed.
Maximum Power and Maximum Efficiency
The purpose of a motor is to deliver power to a load. Given a certain voltage u, the
delivered power is equal to the torque times the speed:
The maximum delivered power Pout,max for a given voltage can be found by
differentiating this function and setting it to zero. The result will be a specific torque and
speed. If this process is repeated for other voltages, a line of points where maximum
power is delivered will result.
The efficiency h of a motor is
power. For a given voltage, the
power and will lead to a certain
voltages, a line of points where
defined as the net output power divided by the input
maximum efficiency can be found just like the maximum
torque and speed. By repeating this procedure for other
maximum efficiency is obtained will result.
20-sim 4.6 Reference Manual
460
8. Toolboxes
The resulting lines of maximum power and maximum efficiency can be shown in the
torque speed plot. C hoosing a good motor is always a compromise between efficiency
and output power. A good choice is to choose a motor that has the major part of the
load curve inside the lines of maximum power and maximum efficiency. This area is
called the Desired Operating Area.
Choosing a Motor
If we combine the results of the previous sections, a torque speed plot results as shown
below. The arrows indicate the load curve with the circle as point of maximum load
power. The Safe Operating Area shows the limits of operation due to motor specific
parameters such as the maximum torque and speed.
The lines of maximum output power and maximum efficiency are the edges of the
Desired Operating Area.The procedure for choosing a proper motor is:
1.Determine the load curve and the point of maximum load power.
2.Determine the duty cycle d (the percentage of the time that torque is required) and
estimate the corresponding Td line with help of the shown T100, T50 , T25 and T10
lines.
3.Select a motor such that the following demands are satisfied:
20-sim 4.6 Reference Manual
461
8. Toolboxes
The load curve is completely beneath the Td line (no overheating).
The complete load curve is in the Save Operating Area.
The point of maximum load power is in the Desired Operating Area.
The point of maximum load power is as close to maximum voltage line as possible
(we want to choose the smallest motor that can do the job).
The load curve is as much in the Desired Operating Area as possible.
Thermal Behaviour
DC Motors
Every motor generates heat, even when at zero speed, and this will lead to an increase
of the motor temperature. Especially when running in continuous operation, there is a
good change that a motor, which is perfectly capable of generating the needed output
power, will heat up beyond its thermal limit and break down.
As explained in the previous section the thermal limit is indicated in the torque speed
curve by the maximum continuous torque line. To generate such a line, a thermal model
is used. This thermal model is also part of the dynamic model that is used in 20-sim.
This section describes the thermal model of permanent magnets motors.
In standard brush DC motors the coils are part of the rotor. To create a thermal model,
various components will be identified first.
Heat Generation
Heat is generated in the motor at every place where energy is lost: coils, bearings, iron
etc. Because the main source of energy loss is in the coils due to the coil resistance, we
start at the coils. The coils act as a heat source and generate a heat flow equal to:
Thermal Capacity
The rotor package, consisting of the coils and possibly iron and other material, will heat
up due to the generated heat. The temperature increase depends on the generated heat
dQ, the heat capacity of the rotor Ccoil and the transfer of heat to the stationary housing
of the motor dQcoil-housing:
Thermal Resistance
The heat flow from the coils to the housing dQcoil-housing depends on the temperature
difference between the rotor and the housing and the thermal resistance Rcoil-housing :
20-sim 4.6 Reference Manual
462
8. Toolboxes
Thermal Capacity
Like the rotor, the housing will also heat up. The temperature increase depends on the
heat coming from the rotor dQrotor-stator, the heat capacity of the housing C housing
and the transfer of heat to the environment dQhousing-amb:
Thermal Resistance
The heat flow from the stator to the environment stator dQhousing-amb depends on the
temperature difference between the housing and the environment and the thermal
resistance Rhousing-amb:
The thermal resistance Rhousing-amb depends on the motor mounting and external
cooling. In most data sheets, a value for the thermal resistance can be found based on
standard motor mounting.
Environment
The environment is supposed to have a fixed temperature Tamb.
Other Motors
The same components as found for the DC brush motor can be found for other motor
types. We only have to realize that for Brushless DC motors and AC Synchronous
motors the coils are mounted on the housing. This means the thermal resistance Rcoilhousing is relatively small and excess heat can be transferred relatively easy. Therefore
these motors are very robust for overheating.
In AC synchronous linear motors, the coils are mounted are part of a platform, on which
the load can be attached. To get the same thermal model we consider the platform to be
the housing. Depending on the type of motor the housing can have a medium thermal
capacity (iron core motors) or a very small thermal capacity (ironless motors). Because
the all excess heat has to be removed through the air, linear motors will heat up easily.
That is why sometimes forced cooling (water) is applied.
20-sim 4.6 Reference Manual
463
8. Toolboxes
Thermal Model
If we combine all components we get the complete thermal model. It can be represented
as shown in the figure below.
The values for thermal capacities and resistances can be found in most data sheets.
These values are, however based on general conditions. The value of the thermal
resistance Rhousing-amb can vary considerably, based on the specific mounting of the
motor and use of passive or active cooling. Most motor suppliers will indicate the how
the thermal parameters were derived and how the motor should be mounted to meet the
general conditions.
8.6
8.6.1
Real-Time Toolbox
Introduction
Real Time Toolbox
The Real Time toolbox of 20-sim allows you to create C -code out of any 20-sim model
for the use in real-time applications:
1.
C reate ANSI-C code for use in a real-time environment.
2.
C reate Matlab / Simulink S-functions for the use in the Matlab Real-Time Workshop.
The generation of Matlab / Simulink code is can be performed using the Export
command of the Editor File menu. You can also use the C -code generation command of
the Simulator Tools menu.
The generation of C -code can be done with the C -code generation command of the
Simulator Tools menu.
20-sim 4.6 Reference Manual
464
8. Toolboxes
8.6.2
C-Code Generation
C-Code Generation
20-sim has a C -C ode Generator which automatically converts a complete 20-sim model
or submodel into C -C ode. The application can be used to generate Matlab™/Simulink™
S-Functions, to generate Stand-Alone executables or to generate input/output functions
for use in other C and C ++ programs. The ANSI C -C ode Generator can be opened from
the Simulator (Tools menu, C-Code Generation command).
Depending on the target selected, 20-sim will generate specific C -code.
You can add more targets by adding paths in the General Properties.
By default, the following targets are supported:
1.
20-sim Dynamic DLL: Generate C -code of a 20-sim submodel and compile the
code into a DLL-call for use inside 20-sim.
2.
20-sim submodel for Arduino/AVR: Generate C -code for the use on a Arduino/
AVR. Note: not all functions (e.g. matrix) are supported!
3.
C-Code for 20-sim submodel: Generate C -code of a 20-sim submodel.
4.
C++ class for 20-sim submodel: Generate object oriented C -code of a 20-sim
submodel.
5.
Simulink S-function: Generate C -code of a 20-sim submodel in the Simulink
format and compile it into an S-function. Note: this option requires the Matlab mexcompiler.
6.
Stand-alone C-code: Generate C -code of a 20-sim main model including
integration method.
20-sim 4.6 Reference Manual
465
8. Toolboxes
7.
FMU 1.0 export for 20-sim submodel: Export a 20-sim submodel using the FMI
1.0 standard.
8.
FMU 2.0 export for 20-sim submodel: Export a 20-sim submodel using the FMI
2.0 standard.
Generating ANSI C-Code
Overview
The modeling and simulation package 20-sim is capable of generating ANSI C -C ode for
several targets. Possible targets are Stand-Alone C , a C -Function, or a Simulink SFunction. Since 20-sim generates well-documented ANSI C -C ode, it is easy for a user to
make modifications or extensions to the generated code by hand. However it is also
possible to fully define your own code target using C -C ode templates, and to make
modifications in these templates, so the resulting source code is tailor made for your
application.
General Structure
The code generation process of 20-sim typically has the following structure:
Step 1
1.
The process starts with a model and simulation in 20-sim.
2.
In the 20-sim Simulator, the user selects the C-Code Generation command from
the Tools menu.
3.
20-sim collects information about the current model.
4.
A target configuration file is read that specifies the different code generation targets
that exist.
5.
The C-code generation dialog is opened, allowing the user to specify the target
to use.
Step 2
1.
The selected target refers to specific template files (source files) in a target specific
subdirectory.
2.
20-sim adapts these template files with the model information and generated code
for the model.
20-sim 4.6 Reference Manual
466
8. Toolboxes
Step 3
1.
The resulting files are placed in a destination directory.
2.
These files are now specific for the target and the model.
3.
If desired, 20-sim can call additional commands for further processing (f.i. make,
run etc).
Code Generation Dialog
After 20-sim reads the target configuration file, the code generation dialog is shown with
the information of this file:
The target list shows the names of the available targets. When a selection is made, the
description of the selected target is given at the right. A submodel can be selected when
the target requires this. The output directory can be overruled.
Targets
The user can create own targets. All targets are defined in the target definition file
Targets.ini. This file has a typical INI-file structure and starts with a section that
simply enumerates which targets exist. Each target then has its own section that holds
the remaining information, like a short description of the target, the name of the
template directory, the names of the template source files, additional commands to
perform, etc. The following keywords may appear in a target section:
20-sim 4.6 Reference Manual
467
8. Toolboxes
Templates
Each target can point to a set of template files that are used to create C -C ode with. Own
template files can be created by the user, with the help of the most powerful feature of
20-sim C -C ode generation: the use of tokens! A token is a placeholder for modeldependent information. For instance in the C -C ode Generation Dialog, the target
destination directory contains the name of the selected submodel (e.g. c:\ temp\%
SUBMODEL_NAME%) by default. Since this information is not yet known when the
targets.ini file is created, a specific token that refers to this name is used instead. A
complete description of predefined tokens is described in the section about Available 20sim Tokens.
Generation Result
After the tokens in the target template files are replaced, the resulting target and model
specific files will be placed in the destination directory. If commands are specified in the
Targets.ini file, these commands are performed. This allows the user to call scripts
automatically. E.g. for automatic compilation, linking and running of the code in a certain
target environment.
Target.Ini File
The user can create own targets. All targets are defined in the target definition file
Targets.ini. This file has a typical INI-file structure and starts with a section that
simply enumerates which targets exist. Each target then has its own section that holds
the remaining information, like a short description of the target, the name of the
template directory, the names of the template source files, additional commands to
perform, etc. The following keywords may appear in a target section:
targetName
="string"
The name that will appear in the 20-sim C -C ode Generation Dialog.
iconFile
="string"
The name of an icon file (.ico) that contains an icon to appear in the 20-sim C -C ode
Generation Dialog.
description
="string"
The string that will appear in the description field in the 20-sim C -C ode Generation
Dialog.
templateDirectory
="string"
Here the path name where the template files for the c-code can be found can be
specified. The default name is the target name in the C C ode directory of 20-sim. If no
full path is specified, the C code directory in 20-sim is taken as a starting point.
20-sim 4.6 Reference Manual
468
8. Toolboxes
templateFiles
=filename1; filename2; filename3...
A list of files, semicolon-separated, that specify the files that are generated in the
targetDirectory.
targetDirectory
="string"
This holds the default target directory where the files will be generated. This directory
name will appear in the 20-sim dialog box when C -C ode is generated and can be
overruled by the user.
submodelSelection
=TRUE (default)
=FALSE
Determines whether C -C ode is generated for the complete 20-sim model, or that a
submodel selection is required.
preCommand
="string"
A command which will be executed in the target directory before that the C -C ode will be
generated.
postCommand
="string"
A command which will be executed in the target directory after that the C -C ode has
been generated. For example a "make" command can be given to automatically compile
the generated code for the specific target.
newLineCharacter
=0
C RLF (0x0d0a = DOS Standard)
=1
C R (0x0d = Macintosh Standard)
=2
LF (0x0a = Unix Standard)
Enter a number for the kind of newline character that should be used.
%KEYWORD%
=value
This (re)defines the keyword "KEYWORD" and gives it the contents "value". Own
keywords can be defined in this manner as well.
example:
%XX_TIME%=someTime
will redefine the time variable with the value "someTime"
20-sim 4.6 Reference Manual
469
8. Toolboxes
Example
A valid Targets.ini file (defining three targets) may look like below. The file may also
contain specific 20-sim tokens (%MODEL_NAME%) that are described later on.
; Possible targets for 20-sim C -C ode Generation
;
[targets]
StandAloneC
C Function
20simDLL
Simulink
; Generate Stand-Alone C -C ode for the complete 20-sim model
;
[StandAloneC ]
targetName="Stand-Alone C -C ode"
iconFile="20sim.ico"
description="Use this target when testing the complete 20-sim model as a single
process."
SubmodelSelection=FALSE
templateDirectory="StandAloneC "
templateFiles=xxfuncs.c;xxfuncs.h;xxinteg.c;xxinteg.h;xxinverse.c
templateFiles=xxmain.c;xxmatrix.c;xxmatrix.h;xxmodel.c;xxmodel.h
templateFiles=xxtypes.h;%MODEL_NAME%.dsp;%MODEL_NAME%.dsw
targetDirectory="c:\temp\%MODEL_NAME%"
; Generate C -C ode for a selected Submodel
;
[C Function]
targetName="C -C ode for 20-sim submodel"
iconFile="20sim.ico"
description="This is the C -C ode as it was generated for a submodel in 20-sim version
3.1"
templateDirectory="C Function"
templateFiles=xxfuncs.c;xxfuncs.h;xxinteg.c;xxinteg.h;xxinverse.c
templateFiles=xxmain.c;xxmatrix.c;xxmatrix.h;xxmodel.c;xxmodel.h
templateFiles=xxsubmod.c;xxsubmod.h;xxtypes.h;%SUBMODEL_NAME%.dsp;%
SUBMODEL_NAM
E%.dsw
targetDirectory="c:\temp\%SUBMODEL_NAME%"
; Generate C -C ode for a dynamic DLL-call to be used in 20-sim
;
[20simDLL]
targetName="20sim Dynamic Dll"
iconFile="20sim.ico"
description="Generate C -C ode for a dynamic DLL-call to be used in 20-sim"
templateDirectory="20simDLL"
templateFiles=xxfuncs.c;xxfuncs.h;xxinverse.c
templateFiles=xxmatrix.c;xxmatrix.h;xxmodel.c;xxmodel.h
templateFiles=xxtypes.h;%SUBMODEL_NAME%.c
20-sim 4.6 Reference Manual
470
8. Toolboxes
templateFiles=%SUBMODEL_NAME%.dsw;%SUBMODEL_NAME%.dsp;%
SUBMODEL_NAME%.emx
targetDirectory="c:\temp\%SUBMODEL_NAME%"
; Generate C -C ode for a Simulatink S-Function
;
[Simulink]
targetName="Simulink S-Function"
iconFile="mdl.ico"
description="This generates C -C ode for a submodel to be used in Matlab/Simulink"
templateDirectory="Simulink"
templateFiles=%SUBMODEL_NAME%.c;xxinverse.c;xxmatrix.c;xxmatrix.h
templateFiles=xxmexfcs.c;xxmextps.h;xxtypes.h;%SUBMODEL_NAME%_.mdl
targetDirectory=c:\temp\%SUBMODEL_NAME%
postC ommand=mex %SUBMODEL_NAME%.c
Available 20-sim Tokens
Both the target configuration file and the code generation dialog revealed the most
important part of the 20-sim code generation process, the use of tokens!
A token is a placeholder for model-dependent information. For instance in the code
generation dialog, the target destination directory contains the name of the selected
submodel by default. Since this information is not yet known when the targets.ini file
is created, a specific token that refers to this name is used instead.
The idea is to create targets from template source files that contain tokens instead of
actual model-dependent information (like equations, names, parameters, inputs etc).
The files that are specified in a target section will be scanned for these tokens and
tokens will be replaced by the corresponding model-dependent information.
Predefined variable names
The following variables should be declared in the C -C ode template, because 20-sim uses
these names in the generation of the equations:
c: constant array
P: parameters array
V: variables array
s: states array
R: rates array
M: matrix array
U: unnamed variables array
F: favorite variables array
f: favorite parameters array
Note that these parameters are case-sensitive!
Model Data
The following tokens will be replaced by numbers indicating the number of model
parameters etc., typically used in memory allocation parts and loops.
20-sim 4.6 Reference Manual
471
8. Toolboxes
%
The number of constants in the model
NUMBER_CONSTANTS
The number of parameters in the model
%
The number of variables in the model
%
The number of states in the model
NUMBER_PARAMETERS The number of inputs of the model
%
The number of outputs of the model
%NUMBER_VARIABLES The number of matrices used in the model
%
The number of unnamed variables in the model
%NUMBER_STATES%
The number of favorite parameters in the model
%NUMBER_INPUTS%
The number of favorite variables in the model
%NUMBER_OUTPUTS% The size of the largest workarray necessary in calculating
%NUMBER_MATRICES
some matrix functions
%
%NUMBER_UNNAMED
%
%
NUMBER_FAVORITE_PA
RAMETERS%
%
NUMBER_FAVORITE_VA
RIABLES%
%WORK_ARRAY_SIZE
%
The following tokens are already reserved for future use:
%NUMBER_DEPSTATES The number of dependent states in the model
%
The number of algebraic loop variables pairs in the model
%NUMBER_ALGLOOPS
The number of constraint variable pairs in the model
%
The number of import variables in the model
%
The number of export variables in the model
NUMBER_CONSTRAINT
S%
%NUMBER_IMPORTS%
%NUMBER_EXPORTS%
Example
Variable name arrays
If you want to use parameters etc. that are specific to a model you can use arrays of
names using the following tokens:
20-sim 4.6 Reference Manual
472
8. Toolboxes
%CONSTANT_NAMES% All the constants used in the model.
%PARAMETER_NAMES All the parameters used in the model.
%
All the variables used in the model.
%VARIABLE_NAMES% All the states used in the model.
%STATE_NAMES%
All the rates used in the model.
%RATE_NAMES%
All the dependent states used in the model.
%DEPSTATE_NAMES% All the dependent rates used in the model.
%DEPRATE_NAMES%
All the algebraic loop variables used in the model.
%ALGLOOP_NAMES%
All the constraint variables used in the model.
%CONSTRAINT_NAMES All the inputs used in the model.
%
All the outputs used in the model.
%INPUT_NAMES%
All the matrices used in the model.
%OUTPUT_NAMES%
All the favorite parameters used in the model.
%MATRIX_NAMES%
All the favorite variables used in the model.
%
FAVORITE_PARAMETER
_NAMES%
%
FAVORITE_VARIABLE_
NAMES%
Example
Initialization code
An important part of a model are the parameters, initial values states etc. To match
these with the generated model code and use the correct values the following tokens can
be used:
%INITIALIZE_CONSTANTS%
%INITIALIZE_PARAMETERS%
%INITIALIZE_MATRICES%
%INITIALIZE_STATES%
%INITIALIZE_DEPSTATES%
%INITIALIZE_ALGLOOPS%
%INITIALIZE_CONSTRAINTS%
%INITIALIZE_INPUTS%
%INITIALIZE_OUTPUTS%
%INITIALIZE_FAVORITE_PARS%
%INITIALIZE_FAVORITE_VARS%
Example
Equations
The following tokens can be used to place 20-sim simulation model equations into the C C ode:
20-sim 4.6 Reference Manual
473
8. Toolboxes
%INITIAL_EQUATIONS Equations that should be calculated once for initialization of
%
the model
%STATIC_EQUATIONS Equations that should be calculated once
%
%INPUT_EQUATIONS
Equations that should be calculated once at the beginning of
%
every simulation step
%
Equations that calculates the dynamic part of the model,
DYNAMIC_EQUATIONS calculates the rates
%
%OUTPUT_EQUATIONS Equations that should be calculated once at the end of every
%
simulation step
%
Reduced set of equations that should be calculated at the end
OUTPUT2_EQUATIONS of every simulation step
%
%FINAL_EQUATIONS
Equations that should be calculated once for termination of the
%
model
Inputs/Outputs
To match model inputs and model outputs to for example sensor signals and actuator
signals you can use:
%INPUT_TO_VARIABLE_EQUATIONS%
%VARIABLE_TO_OUTPUT_EQUATIONS%
%ALIAS_EQUATIONS%
%FAVORITE_PARS_EQUATIONS%
%FAVORITE_VARS_EQUATIONS%
Example
Additional tokens
%
A string representing the name of the selected integration
INTEGRATION_METHO method, for now only Euler, RungeKutta4 and Discrete are
D_NAME%
available.
%XX_TIME%
The name of the simulation time variable (combined with %
%XX_INITIALIZE%
VARPREFIX%)
The name of the variable that indicates the initialization
phase(combined with %VARPREFIX%).
%START_TIME%
Start time of the simulation (floating point notation).
%FINISH_TIME%
Finish time of the simulation (floating point notation).
%TIME_STEP_SIZE%
Step size of the simulation (floating point notation).
Either TRUE or FALSE, depending if the model is discrete in
time or continuous in time.
20-sim 4.6 Reference Manual
474
8. Toolboxes
%
MODEL_IS_DISCRETE
%
Experiment Tokens
Tokens which hold information about the model, experiment, user and system:
%FILE_NAME%
The file name of the generated C -C ode.
%MODEL_FILE%
The complete path and file name of the original 20-sim model.
%MODEL_NAME%
The name of the 20-sim model out of which C -C ode was
%SUBMODEL_NAME%
generated.
%EXPERIMENT_NAME
The name of the 20-sim submodel out of which C -C ode was
%
generated.
%GENERATION_TIME
The experiment name accompanying the 20-sim (sub)model.
%
The time of C -C ode generation.
%GENERATION_DATE
The date of C -C ode generation.
%
The 20-sim version and build number.
%GENERATION_BUILD The directory where the generated C -C ode files are stored.
%
The user name given in the 20-sim license.
%GENERATION_DIR% The company name given in the 20-sim license.
%USER_NAME%
The directory where 20-sim is installed.
%COMPANY_NAME%
%20SIM_DIR%
8.7
Time Domain Toolbox
8.7.1
Time Domain Toolbox
The Time Domain Toolbox contains powerful tools to inspect the behaviour of your
model using time domain simulation.
Parameter sweep: Perform a number of simulation runs, while changing model
parameters.
Optimization: Optimize a given result by changing parameters.
Curve Fitting: Fit your model to a given result by changing parameters.
Tolerance Analysis
Sensitivity: C hange parameters by a given percentage and monitor results.
Monte Carlo: C hange parameters statistically and monitor results.
20-sim 4.6 Reference Manual
475
8. Toolboxes
Variation Analysis: Find the statistical range of parameters to yield a given result.
External DLL: Let the multiple run be controlled by a user-defined function in a DLL.
Procedure
1.
From the Toolbox menu select the Time Domain Toolbox and then the tool that
you want to use.
2.
This will open the Multiple Run Wizard. Follow the instructions and after all settings
have been entered, close the wizard.
3.
Select the Multiple Run command from the Simulation menu to perform the
specified analysis.
4.
After simulation is completed a special window will open to showing the results. If it
is not available, you can always open this window, by selecting the Multiple Run
Results command of the View Menu.
Multiple Run Wizard
All tools of the Time Domain Toolbox are started use the Multiple Run Wizard. You can
open this Wizard directly by selecting the Multiple Run command from the Properties
menu.
8.7.2
Parameter Sweep
Using the Parameter Sweep option of the Time Domain Toolbox, you can perform a
predefined number of simulation runs with variation of parameters / initial values.
Parameters / Initial Values
1.
From the Tools menu select the Time Domain Toolbox and then Parameter
Sweep.
A window will open, asking you which parameters / initial values should be changed
during the multiple simulations:
20-sim 4.6 Reference Manual
476
8. Toolboxes
2.
Add the parameters / initial values of your choice:
3.
C lick the Next button.
Result
A window opens asking you which result (optional) should be shown after the
simulations:
20-sim 4.6 Reference Manual
477
8. Toolboxes
4.
If you do not want to use a result after simulation, enter nothing here. If you like to
present a result after the simulation, enter it here using the various options of the
window.
5.
C lick the Next button.
Run options
A window will open, asking some simulation run options:
20-sim 4.6 Reference Manual
478
8. Toolboxes
You can select the following items:
Steps: Number of simulations runs.
Copy from States: Use the result of the previous simulation runs as the starting value
numerical output of the parameter sweep.
Join Parameter Variation: C hange all parameters simultaneously.
Clear After Every Run: C lear the simulation plot when a new simulation run starts.
Redraw After Every Run: Update the scaling after every run.
6.
Select the desired run options and click the Next button.
A window will open with a summary of the chosen options. If your are not satisfied you
can use the Back button to go to a previous window and change settings.
7.
C lick the Finish button to close the Multiple Run Wizard.
8.
From the Simulation menu click the Multiple Run command to perform the
Parameter Sweep.
Parameter Sweep Results
After simulation has been done, a Multiple Run Results window will open, showing the
minimum and maximum value of the result and chosen parameters:
20-sim 4.6 Reference Manual
479
8. Toolboxes
You can select the following items:
Values: C hoose this button to open the list that shows the numerical output of the
parameter sweep.
Matlab: Export the results to Matlab.
OK: C lose the Multiple Run Results Window.
You can always re-open the Multiple Run Results window, by selecting the Multiple Run
Results command of the View Menu.
9.
By choosing the Values button, a new window is opened, showing the numerical
results of the parameter sweep.
In the Results list of this window the subsequent runs are shown and (if available) the
value of the chosen result:
20-sim 4.6 Reference Manual
480
8. Toolboxes
You can select the following items:
Set Values: C hoose the values of the selected run, as new parameter values of your
model.
Create Datafile: Use this button to store the values of the selected variables on file.
Use the control-key and shift-key to make multiple selections.
8.7.3
Optimization
Using the Optimization option of the Time Domain Toolbox, you can optimize a given
result using variation of parameters / initial values.
Optimization Method
1.
From the Tools menu select the Time Domain Toolbox and then Optimization.
A window opens asking you which optimization method should used:
20-sim 4.6 Reference Manual
481
8. Toolboxes
2.
Select the Optimization method that should be used.
3.
Select the Tolerance (accuracy of the found optimum) that should be used and click
Next.
Parameters / Initial Values
A window opens asking you which parameters / initial values should be varied during
optimization:
20-sim 4.6 Reference Manual
482
8. Toolboxes
4.
Add the parameters / initial values of your choice:
5.
C lick the Next button.
Result
A window opens asking you which result should optimized:
20-sim 4.6 Reference Manual
483
8. Toolboxes
6.
Enter the result here using the various options of the window.
7.
C lick the Next button.
Run options
A window opens asking some simulation run options:
20-sim 4.6 Reference Manual
484
8. Toolboxes
8.
Select the desired run options and click the Next button.
A window opens with a summary of the chosen options. If your are not satisfied you can
use the Back button to go to a previous window and change settings.
9.
C lick the Finish button to close the Multiple Run Wizard.
10. From the Simulation menu click the Multiple Run command to perform the
Optimization.
Optimization Results
After simulation has been done, an Optimization Results window will open, showing the
optimum value of the result and corresponding parameters:
20-sim 4.6 Reference Manual
485
8. Toolboxes
You can select the following items:
Values: C hoose this button to open the list that shows the numerical output of the
optimization runs.
Matlab: Export the results to Matlab.
OK: C lose the Optimization Results Window.
You can always re-open the Multiple Run Results window, by selecting the Multiple Run
Results command of the View Menu.
11. By choosing the Values button, a new window is opened, showing the numerical
results of the parameter sweep.
In the Results list of this window the subsequent runs are shown and (if available) the
value of the chosen result:
20-sim 4.6 Reference Manual
486
8. Toolboxes
You can select the following items:
Set Values: C hoose the values of the selected run, as new parameter values of your
model.
Create Datafile: Use this button to store the values of the selected variables on file.
Use the control-key and shift-key to make multiple selections.
8.7.4
Optimization Methods
In the Multiple Run Wizard you have to specify a result which will be optimized. The
result is a function of model variables and the simulation run:
result = f(i,v1,v2,...)
with i the number of the simulation run. You also have to specify the parameters that
should be varied to find the optimum result. We can group these parameters in a
parameter vector:
parameter vector = p(i)
with again i the number of the simulation run. All methods in 20-sim for finding an
optimum of the result use the same iterative process:
1.
The initial parameter vector is determined, e.g. p(1) and the corresponding function
value f(1).
2.
A search direction r(1) and a stepsize s(1) are determined.
3.
Perform a new simulation run to find the parameter vector p(2) = p(1) + s(1)*r(1).
20-sim 4.6 Reference Manual
487
8. Toolboxes
4.
C alculate f(2).
5.
When the f(2) is smaller than f(1) and the difference between the two is smaller than
a given tolerance, stop the process. The optimum has been found.
6.
When the f(2) is smaller than f(1) and the difference between the two is larger than
a given tolerance, proceed the process at step 2
7.
Otherwise a new stepsize and/or a new search direction are determined and the
process is proceeded at step 3.
The choice of the stepsize is of importance for the speed an accuracy of the search
process. A small stepsize will make the optimization process last very long. A large
stepsize will make it less accurate. Most methods will therefore use a variable stepsize.
Of equal importance is the proper choice of the search direction. Methods for finding the
search direction, can be divided in two groups: direct search methods and gradient
search methods. The gradient of a function, is its slope at a certain point. Gradient
search methods use this slope to find the optimal direction of search.
Methods
The optimization methods that are supported in 20-sim will now be explained. The
pictures at the right visualize the methods with two varying parameters x (horizontal)
and y (horizontal) and the corresponding result (vertical).
1. Perpendicular Search
(direct search)
The perpendicular search method
uses a search direction that is
always
perpendicular
to
the
parameter axis. This means that
only one parameter at a time is
varied. All other parameters keep
the same value. After one step, a
next parameter is taken and the
process continues.
20-sim 4.6 Reference Manual
488
8. Toolboxes
2. Line Climber (direct search)
The line climber method uses a
search direction that is always
perpendicular to the parameter
axis. This means that only one
parameter at a time is varied. All
other parameters keep the same
value. After a minimum has been
found the next parameter is varied
and the process continues.
3. Steepest Descent (gradient
search)
The steepest descent method starts
its search in the direction of the
steepest slope. This direction is
kept for each new step until a
minimum has been found. Then a
new search direction is determined
and the process continues.
20-sim 4.6 Reference Manual
489
8. Toolboxes
4. Continuous Descent
(gradient search)
The continuous descent method
starts its search in the direction of
the steepest slope. After each new
step a new search direction is
determined
and
the
process
continues.
5. Newton Raphson
(gradient search)
The Newton Raphson method
not only uses the gradient of a
function, but also the second
order gradient to determine the
search direction. This direction
is kept for each new step until a
minimum has been found. Then
a new search direction is
determined and the process
continues. Note: The method
only converges for a positive
second order gradient, i.e. near
the minimum. This is shown in
the figure to the right. For x = 0.7 and y = -0.9 the method
does not converge. For x = -0.5
and y = -0.3 the method does
converge.
20-sim 4.6 Reference Manual
490
8. Toolboxes
6. Polack Ribiere (gradient
search)
The Polack Ribiere method not only
uses the gradient of a function, but
also the second order gradient to
determine the search direction.
The second order gradient is
estimated based
on
previous
search directions. The search
direction is kept for each new step
until a minimum has been found.
Then a new search direction is
determined
and
the
process
continues.
7. Davidson Fletcher Powel
(gradient search)
The
Davidson
Fletcher
Powel
method not only uses the gradient
of a function, but also the second
order gradient to determine the
search direction. The second order
gradient is estimated based on
previous search directions. The
search direction is kept for each
new step until a minimum has been
found. Then a new search direction
is determined and the process
continues
20-sim 4.6 Reference Manual
491
8. Toolboxes
8. Broydon Fletcher Goldfarb
Shanno (gradient search)
The Broydon Fletcher Goldfarb
Shanno method not only uses the
gradient of a function, but also the
second order gradient to determine
the search direction. The second
order gradient is estimated based
on previous search directions. The
search direction is kept for each
new step until a minimum has been
found. Then a new search direction
is determined and the process
continues.
What method should be used?
There is no general answer to this question. Some remarks can however be made:
1.
Gradient search methods (3 to 8), need more steps (note that each step means a
simulation run) to determine the gradient. The Newton Raphson methods needs the
most steps, because this method also needs additional steps for the determination of
the second order gradient.
2.
When the direction of the slope is not exactly the same as the search direction,
direct search methods (1 and 2) may start to bounce, i.e. continuously change
direction while making little progress. this is shown in the figure below:
20-sim 4.6 Reference Manual
492
8. Toolboxes
Users are therefore advised to use methods 1 and 2 only for optimizations with one
parameter, and use the methods 7 and 8 for optimizations with more parameters. Use
the other methods for checking the results or educational purposes.
More information on these methods can be found in:
Bazaraa, M.S., Sherali, H.D., Shetty C .M. (1990), Nonlinear Programming, Theory and
Algorithms, John Wiley & Sons Inc. New York, ISBN 0-471-59973-5.
8.7.5
Curve Fitting
Using the Parameter Sweep option of the Time Domain Toolbox, you can fit your model
to a given result using variation of parameters / initial values.
Optimization Method
1.
From the Tools menu select the Time Domain Toolbox and then Curve Fittting.
A window opens asking you which optimization method should used for curve fitting:
2.
Select the Optimization method that should be used.
3.
Select the Tolerance (accuracy of the found fit) that should be used and click Next.
Parameters / Initial Values
A window opens asking you which parameters / initial values should be varied during
curve fitting:
20-sim 4.6 Reference Manual
493
8. Toolboxes
4.
Add the parameters / initial values of your choice:
5.
C lick the Next button.
Result
A window opens asking you which result should minimized to fit your model (variable 1)
to a given result (variable 2):
20-sim 4.6 Reference Manual
494
8. Toolboxes
6.
Enter the result here using the various options of the window.
7.
C lick the Next button.
Run options
A window opens asking some simulation run options:
20-sim 4.6 Reference Manual
495
8. Toolboxes
8.
Select the desired run options and click the Next button.
A window opens with a summary of the chosen options. If your are not satisfied you can
use the Back button to go to a previous window and change settings.
9.
C lick the Finish button to close the Multiple Run Wizard.
10. From the Simulation menu click the Multiple Run command to perform the C urve
Fitting.
Optimization Results
After simulation has been done, the Optimization Results window will open, showing the
minimum value of the result and corresponding parameters:
20-sim 4.6 Reference Manual
496
8. Toolboxes
You can select the following items:
Values: C hoose this button to open the list that shows the numerical output of the
curve fitting runs.
Matlab: Export the results to Matlab.
OK: C lose the Optimization Results Window.
You can always re-open the Multiple Run Results window, by selecting the Multiple
Run Results command of the View Menu.
11. By choosing the Values button, a new window is opened, showing the numerical
results of the parameter sweep.
In the Results list of this window the subsequent runs are shown and the value of the
chosen result:
20-sim 4.6 Reference Manual
497
8. Toolboxes
You can select the following items:
Set Values: C hoose the values of the selected run, as new parameter values of your
model.
Create Datafile: Use this button to store the values of the selected variables on file.
Use the control-key and shift-key to make multiple selections.
8.7.6
Sensitivity Analysis
Using the Tolerance Analysis option of the Multiple Run Wizard, you can analyze the
effects of variation of parameters / initial values on the performance of your model.
Three methods of Tolerance analysis are supported in the Multiple Run Wizard. One of
these methods is Sensitivity analysis.
Sensitivity analysis starts with a simulation run with nominal parameter values. After the
run a given result is monitored (r). Then, one by one, each parameter (pi) is changed
with a given percentage (to pi + dpi) and a simulation run is performed. After the
simulation run the changed result is monitored (r + dri). After all the runs, the results
are displayed as sensitivities, where sensitivity is defined as the change in result divided
by the change in parameter:
Si = dri / dpi
A large sensitivity means that the result is highly dependant of the parameter value. This
can be used for optimization (change the parameter value) or design (change the design
to make it less dependant of the parameter).
20-sim 4.6 Reference Manual
498
8. Toolboxes
Parameters / Initial Values
1.
From the Tools menu select the Time Domain Toolbox and then Sensitivity
Analysis.
A window opens asking you which parameters / initial values should be changed for the
Sensitivity analysis:
3.
Add the parameters / initial values of your choice:
4.
C lick the Next button.
Result
A window opens asking you which result should be monitored for the sensitivity:
20-sim 4.6 Reference Manual
499
8. Toolboxes
5.
Enter the result here using the various options of the window.
6.
C lick the Next button.
Run options
A window opens asking some simulation run options:
20-sim 4.6 Reference Manual
500
8. Toolboxes
7.
Select the desired run options and click the Next button.
A window opens with a summary of the chosen options. If your are not satisfied you can
use the Back button to go to a previous window and change settings.
8.
C lick the Finish button to close the Multiple Run Wizard.
9.
From the Simulation menu click the Multiple Run command to perform the
Sensitivity Analysis.
Sensitivity Analysis Results
After simulation has been done, a Sensitivity Analysis Results window will open, showing
the sensitivities:
20-sim 4.6 Reference Manual
501
8. Toolboxes
You can select the following items:
Multiple Run Values: C hoose this button to open the list that shows the output of the
various runs performed during the sensitivity analysis.
Close: C lose the Sensitivity Analysis Results Window.
You can always re-open the Multiple Run Results window, by selecting the Multiple Run
Results command of the View Menu.
10. By choosing the Multiple Run Values button, a new window is opened, showing
output of the various runs performed during the sensitivity analysis:
In the Results list of this window the subsequent runs are shown and the corresponding
sensitivities.
20-sim 4.6 Reference Manual
502
8. Toolboxes
You can select the following items:
Set Values: C hoose the values of the selected run, as new parameter values of your
model.
Create Datafile: Use this button to store the values of the selected variables on file.
Use the control-key and shift-key to make multiple selections.
8.7.7
Monte Carlo Analysis
Using the Tolerance Analysis option of the Multiple Run Wizard, you can analyze the
effects of variation of parameters / initial values on the performance of your model.
Three methods of Tolerance analysis are supported in the Multiple Run Wizard. One of
these methods is Monte C arlo Analysis. Using Monte C arlo analysis, you can perform a
predefined number of simulation runs with variation of parameter values according to a
predefined distribution function.
Parameters / Initial Values
1.
From the Tools menu select the Time Domain Toolbox and then Monte Carlo
Analysis.
A window opens asking you which parameters / initial values should be varied for the
Monte C arlo analysis:
20-sim 4.6 Reference Manual
503
8. Toolboxes
2.
Add the parameters / initial values of your choice:
3.
C lick the Next button.
Result
A window opens asking you which result should be monitored during the Monte C arlo
Analysis:
20-sim 4.6 Reference Manual
504
8. Toolboxes
4.
Enter the result here using the various options of the window.
5.
C lick the Next button.
Run options
A window opens asking some simulation run options:
20-sim 4.6 Reference Manual
505
8. Toolboxes
6.
Select the desired run options and click the Next button.
A window opens with a summary of the chosen options. If your are not satisfied you can
use the Back button to go to a previous window and change settings.
7.
C lick the Finish button to close the Multiple Run Wizard.
8.
From the Simulation menu click the Multiple Run command to perform the Monte
C arlo Analysis.
Monte Carlo Analysis Results
After simulation has been done, a Monte C arlo Analysis Results window will open,
showing the results:
20-sim 4.6 Reference Manual
506
8. Toolboxes
You can select the following items:
Values: C hoose this button to open the list that shows the output of the various runs
performed during the Monte C arlo analysis.
Histogram: C hoose this button to open a histogram of the selected item.
Matlab: Export the results to Matlab.
OK: C lose the Multiple Run Results Window.
You can always re-open the Multiple Run Results window, by selecting the Multiple
Run Results command of the View Menu.
9.
By choosing the Multiple Run Values button, a new window is opened, showing
output of the various runs performed during the Monte C arlo analysis.
20-sim 4.6 Reference Manual
507
8. Toolboxes
You can select the following items:
Set Values: C hoose the values of the selected run, as new parameter values of your
model.
Create Datafile: Use this button to store the values of the selected variables on file.
Use the control-key and shift-key to make multiple selections.
By choosing the Histogram button, a new window is opened, showing distribution of the
result variable:
20-sim 4.6 Reference Manual
508
8. Toolboxes
8.7.8
Variation Analysis
Using the Tolerance Analysis option of the Multiple Run Wizard, you can analyze the
effects of variation of parameters / initial values on the performance of your model.
Three methods of Tolerance analysis are supported in the Multiple Run Wizard. One of
these methods is Variation Analysis.
Using Variation analysis, you can perform a predefined number of simulation runs with
variation of parameter values according to a predefined distribution function. During the
runs a given result is monitored. After the runs the statistical range of the result is
presented. You can restrict the parameter distributions to get the result between desired
bounds.
Parameters / Initial Values
1.
From the Tools menu select the Time Domain Toolbox and then Variation
Analysis.
A window opens asking you which parameters / initial values should be varied for the
Variation analysis:
20-sim 4.6 Reference Manual
509
8. Toolboxes
2.
Add the parameters / initial values of your choice:
3.
C lick the Next button.
Result
A window opens asking you which result should be monitored during the Variation
Analysis:
20-sim 4.6 Reference Manual
510
8. Toolboxes
4.
Enter the result here using the various options of the window.
5.
C lick the Next button.
Run options
A window opens asking some simulation run options:
20-sim 4.6 Reference Manual
511
8. Toolboxes
6.
Select the desired run options and click the Next button.
A window opens with a summary of the chosen options. If your are not satisfied you can
use the Back button to go to a previous window and change settings.
7.
C lick the Finish button to close the Multiple Run Wizard.
8.
From the Simulation menu click the Multiple Run command to perform the
Variation Analysis.
Variation Analysis Results
After simulation has been done, a Variation Analysis Results window will open, showing
the results. A histogram shows the distribution of the result. Using the slider bar you can
see how restraining the distribution of the parameters effects the distribution of the
result.
20-sim 4.6 Reference Manual
512
8. Toolboxes
You can select the following items:
Slider Bar: Select a parameter and restrict its distribution with the slider bar. You will
see the histogram showing the result change.
Multiple Run Values: C hoose this button to open the list that shows the output of the
various runs performed during the Variation Analysis.
OK: C lose the Multiple Run Results Window.
You can always re-open the Multiple Run Results window, by selecting the Multiple Run
Results command of the View Menu.
9.
By choosing the Multiple Run Values button, a new window is opened, showing
output of the various runs performed during the Variation analysis:
20-sim 4.6 Reference Manual
513
8. Toolboxes
You can select the following items:
Set Values: C hoose the values of the selected run, as new parameter values of your
model.
Create Datafile: Use this button to store the values of the selected variables on file.
Use the control-key and shift-key to make multiple selections.
8.7.9
Multiple Run Wizard - External DLL
You can analyze the effects of variation of parameters / initial values using your own
method with the use of an external DLL-function.
Ask C ontrollab Products for details.
Deprecation warning
20-sim provides a Scripting toolbox since 20-sim 4.4 that allows you to write your own
automation scripts around a 20-sim model.
It is strongly advised to implement new customized multiple run experiments is by
means of a script in either Octave/Matlab or Python.
The multiple run external DLL feature will be removed in a future version of 20-sim.
20-sim 4.6 Reference Manual
514
8. Toolboxes
8.7.10 Cost Function
In the Multiple Run Wizard, the Result window allows you to define a result (the Cost
Function) that will be used during simulations (Optimization, C urve Fitting) and displayed
after the simulations runs (Parameter sweep, Optimization, C urve Fitting, Sensitivity,
Monte C arlo, Variation Analysis, External DLL).
The result can be a function of one or two variables. Instead of the second variable an
(offset) value can be entered.
Items
Choose Variable: Select this button to select a model variable
Clear: Use this button the remove a chosen model variable.
Function:
End value: The value at the end of the simulation run.
Sum Absolute Value: The sum of all absolute values during a simulation run.
Sum Square Value: The sum of all values squared during a simulation run.
Integral Absolute Value: The integral of all absolute values during a simulation run
(uses Euler integration).
Integral Square Value: The integral of all values squared during a simulation run
(uses Euler integration).
User Defined Cost Function
You can easily use your own Cost Function for the result variable:
1.
C reate your own cost function in the model.
2.
Use the Choose button to select as var1 the output of your function.
20-sim 4.6 Reference Manual
515
8. Toolboxes
3.
Set var2 to a zero value.
4.
C hoose End Value to prevent further operations on your function.
8.8
Scripting Toolbox
8.8.1
Introduction
20-sim scripting allows you to run tasks in 20-sim automatically using specialized
scripting functions. With these functions you can open models, run simulations, change
parameters, store results and much more. Scripting support was introduced in 20-sim
4.4.
20-sim session automated by a script in Octave, Matlab or Python.
These scripting functions are not very useful stand-alone, but you can use them to write
scripts to automate various tasks in 20-sim.
20-sim provides a set of script functions for numerical computation environments like
Octave and Matlab and for the Python programming language (since 20-sim 4.6).
The 20-sim scripting functions are based on XML-RPC calls, so any other programming
language with support for XML-RPC can be used to automate various 20-sim steps.
In this chapter you will learn how to run basic scripts and make scripts on your own.
The next sections explain:
Installation for scripting:
o
20-sim: enabling the XML-RPC scripting interface in 20-sim
o
Octave: installing Octave as scripting environment
o
Matlab: installing Matlab as scripting environment
o
Python: installing Python as scripting environment
Prepare Scripting Folder: extract
documentation to your work directory.
the
20-sim
scripting
functions
and
Basic Script: run your first script and see how a basic script is made in Octave/
Matlab or Python.
Advanced Scripts: see how you can expand the basic script to perform more
advanced tasks in Octave/Matlab.
Writing your own Scripts: How to write your own scripts in Octave/Matlab or
Python.
20-sim 4.6 Reference Manual
516
8. Toolboxes
Note: Scripting is not supported in the 20-sim Viewer/Demonstration Version. If you
would like to try the scripting functionality, you will need licensed 20-sim version or a
trial license.
8.8.2
Installation for Scripting: 20-sim
20-sim uses XML-RPC as a protocol to communicate scripting functions with external
packages. By default the XML-RPC interface is turned on only for your local computer.
To enable/disable and configure the 20-sim scripting support:
1.
Open 20-sim.
2.
Go to Tools/Options and select the Scripting Interface tab.
Scripting Interface settings tab.
3.
To enable the 20-sim scripting support, make sure that the HTTP and TCP
checkboxes under XMLRPC Interface are enabled.
By default, 20-sim will only accept scripting connections from your local computer
(Localhost only option is enabled).
Your firewall may generate a warning message and ask you to allow network
communication for 20-sim.
4.
Set the firewall to allow communication.
20-sim 4.6 Reference Manual
517
8. Toolboxes
8.8.3
Scripting in Octave/Matlab
Installation for Scripting: Octave
What is Octave?
GNU Octave is a high-level language, primarily intended for numerical computations. The
package is open source and can be freely distributed. GNU Octave offers functionality
similar to Matlab users. If you have experience with Matlab, running Octave will be very
easy. Users with no experience with Octave nor Matlab are advised to read a proper
introduction to GNU Octave first. You will find lot of pages and videos on the Internet.
Installation
The Windows versions of Octave 4.2.0, Octave-4.0.x, Octave-3.8.x, Octave-3.6.x have
been tested with 20-sim scripting at the time of this release.
Note that only the 32-bit Octave is supported. The 64-bit version will not work.
1.
Go to: http://www.20sim.com/product/octave.html and follow the latest instructions.
If this web page is unavailable, you can follow the instructions below:
First choose the Octave version you wish to install and go to the corresponding section
below:
Octave 4.2.0 / Octave 4.0.x
1.
Go to: http://www.gnu.org/software/octave/
2.
Go to the download page and download the Windows installer (direct link: https://
ftp.gnu.org/gnu/octave/windows/octave-4.2.0-w32-installer.exe
3.
Run the installer and follow the wizard. The steps below assume default installation
settings.
4.
Unfortunately Octave 4.0.x has a Windows specific bug in its internal run() function.
This bug is resolved in Octave 4.2.
For Octave 4.0.x you will need to manually replace the default run() implementation
with a corrected version. Copy the file:
C:\Program Files (x86)\20-sim 4.6\Scripting\Octave-patch\4.0.0
\run.m
or on 32-bit versions of Windows:
C:\Program Files\20-sim 4.6\Scripting\Octave-patch\4.0.0\run.m
to:
C:\Octave\Octave-4.0.0\share\octave\4.0.0\m\miscellaneous\run.m
5.
Launch Octave from the Start menu or using the script: C:\Octave\Octave-4.0.0
\octave.bat
20-sim 4.6 Reference Manual
518
8. Toolboxes
6.
Execute the following
pkg install -forge
pkg install -forge
pkg install -forge
commands to install packages io, control and signal:
io
control
signal
The Octave GUI.
Your Octave installation is now ready to use.
Octave 3.8.x
1.
Go to: http://www.20sim.com/downloads/files/ThirdParty/octave-3.8.2-2installer.exe
2.
Run the installer and follow the wizard.
3.
Launch Octave using the script: C :\Octave\Octave-3.8.2\octave.bat
4.
Execute the following
pkg install -forge
pkg install -forge
pkg install -forge
commands to install packages io, control and signal:
io
control
signal
20-sim 4.6 Reference Manual
519
8. Toolboxes
Your Octave installation is now ready to use.
Octave 3.6.x
1.
Go to the Octave download site (http://sourceforge.net/projects/octave/.).
2.
C lick on the Files tab and click on Octave Windows Binaries.
3.
Select the Octave 3.6.4 for Windows MinGW installer.
4.
Now you can download the files Octave3.6.4_gcc4.6.2_yyyyxxxx.7z
(Octave Installation) and Octave3.6.4_gcc4.6.2_pkgs_yyyyxxxx.7z
(Octaveforge Packages).
5.
C reate an installation directory which doesn't have space chars (i.e. C :\Octave).
6.
Unzip the file Octave3.6.4_gcc4.6.2_yyyyxxxx.7z and copy it to the
installation directory.
7.
C opy the shortcut link C:\Octave\Octave3.6.4_gcc4.6.2.lnk to your desktop.
This is a shortcut to start Octave.exe.
Note: Unzipping can be done with programs like 7-zip (http://www.7-zip.org/)
Note: There is a bug with Windows 8 and running Octave. In order to use Octave start
Octave with octave.exe -i --line-editing. See the Octave wiki webpage for more
information.
8.
Unzip the file Octave3.6.4_gcc4.6.2_pkgs_yyyyxxxx.7z and copy it to the
installation directory.
9.
Launch Octave (e.g. the link to Octave.exe).
10. Execute the following five rebuild commands from the Octave console (e.g. re-type
every line followed by ENTER):
pkg rebuild -auto
pkg
pkg
pkg
pkg
rebuild
rebuild
rebuild
rebuild
-noauto ad
-noauto nan % shadows many statistics functions
-noauto gsl % shadows some core functions
-auto java
20-sim 4.6 Reference Manual
520
8. Toolboxes
The Octave command window.
11. C lose and restart Octave.
Installation for Scripting: Matlab
What is Matlab?
Matlab is a high-level language, primarily intended for numerical computations. The
package is commercially distributed by the Mathworks. If you don't have the resources
to purchase Matlab, you can run use Octave, which offers similar functionality.
Versions
Matlab R2011, R2012, R2013, R2014 and R2015 have been tested with 20-sim scripting
but older versions may also work fine.
Installation
See the Matlab documentation from the Mathworks for information on installing Matlab.
No special (additional) installation is needed to use 20-sim scripting from Matlab.
Note: Scripting in Matlab is similar to Octave. You can type exactly the same commands
as given for Octave in the next sections.
Prepare Scripting Folder
20-sim comes with a Scripting Folder that contains documentation of all scripting
functions, the function library and example scripts. You have to install this folder to use
scripting.
Installation
1.
Open the Install Scripting program from the Windows Start menu (located under
20-sim 4.6)
- or Go to the folder where 20-sim is installed (e.g. C:\Program Files\20-sim 4.6
\Scripting or C:\Program Files (x86)\20-sim 4.6\Scripting) and open
20simScripting.exe
20-sim 4.6 Reference Manual
521
8. Toolboxes
2.
This will open a dialog where you can choose where to extract the 20-sim scripting
files. Change the path to a local working folder of your choice (for example: C:
\Users\yourusername\Documents\20simscripting)
20-sim Scripts extraction
Note: To write/modify scripts, the scripting folder should be accessible and writable by
the user. Do not install the scripting folder on C:\Program Files (x86) or C:\Program
Files.
For the remainder of this chapter, we use the name scripting working folder when we
refer to the folder where you just extracted the 20-sim scripting files.
Contents
Your newly created scripting working folder contains a number of subfolders:
1.
Models: This folder contains the 20-sim models and data files that are used for the
example and tutorial scripts .
2.
Octave: This folder contains all Octave/Matlab scripting functionality and
documentation
a.
documentation: This folder contains the scripting API documentation: a list of
supported functions and their syntax. It is a copy of the help file that you can
open in the 20-sim Editor by selecting Help - Octave Scripting API.
Note: the API documentation is also accessible from the Windows Start menu
under 20-sim 4.6\Scripting API documentation
b.
library: This folder contains the core scripting functions.
c.
tutorials: This folder contains basis scripts with a step by step explanation. You
can use these scripts as a base for your own scripts.
d.
examples: This folder contains some more advanced scripts.
3.
Octave-patch: This folder contains modified Octave scripts for certain Octave
versions to fix bugs in the core Octave scripts that are not yet fixed in the latest
release (currently 4.0.3)
4.
Python: This folder contains all Python scripting functionality and documentation
(see the Scripting in Python section for more information).
20-sim 4.6 Reference Manual
522
8. Toolboxes
Basic Script
When the scripting files are properly installed in your scripting working folder, we can
run some tutorial scripts. Tutorial scripts are a step by step demonstrations of usage of
the scripting functionality in 20-sim. These scripts are found in the tutorials subfolder of
the scripting working folder. We will start with a basic script that opens and runs a 20sim model.
1.
Open 20-sim.
2.
Open Octave (or Matlab).
3.
In Octave/Matlab, change the local working directory to the tutorial folder inside
your scripting working folder . E.g . type:
cd 'C:\Users\yourusername\Documents\20simscripting\Octave\tutorials'
Note: 20-sim should be open before running the script!
4.
In Octave/Matlab, execute the following command (e.g. type the following case
sensitive command followed by ENTER):
runSimulation
Note: Octave may give a cryptic "undefined near line x column 1" message, if you type
the command as runsimulation instead of runSimulation!
5.
Now Octave / Matlab will give a message and ask you to press ENTER to continue.
The model ControlledSystem.emx is loaded into 20-sim and simulated.
6.
Again Octave/Matlab will give a message and ask you to press ENTER to continue.
Now the simulation and model will be unloaded.
Inspecting the script
To see how the script is made, you can inspect it with a text editor.
1.
Open a file browser and go to the tutorials folder (e.g. C :\Users\yourusername
\Documents\20simscripting\Octave\tutorials)
20-sim 4.6 Reference Manual
523
8. Toolboxes
2.
Open the file runSimulation.m with a text editor like Notepad.
Core Functions
The core functions of the runSimulation script are:
addpath: The script starts with the command addpath('../library/xxsim'); This will
enable Octave / Matlab to use the 20-sim scripting functions that are stored in the
library subfolder of your scripting working folder.
xxsimConnect: This command opens a connection to 20-sim.
xxSimOpenModel: This command opens a model in 20-sim by giving the filename
including the full path.
xxsimProcessModel: This command will process the model.
xxsimRun: This command will run a simulation.
xxsimCloseModel: This command will remove the simulation model from 20-sim.
These functions are the basis of scripting in 20-sim and will be present in this order in
most scripts. Therefore you can use the script runSimulation.m as a template for any
new script that you create.
Advanced Scripts
Now that we have seen the core functions of a script we will run and check some more
advanced scripts.
1.
Open 20-sim.
2.
Open Octave (or Matlab).
3.
In Octave/Matlab, change the local working directory to the tutorial folder inside
your scripting working folder. E.g . type:
cd 'C:\Users\yourusername\Documents\20simscripting\Octave\tutorials'
Set Parameter Values
4.
In Octave/Matlab, execute the following script (e.g. type the command followed by
ENTER):
SetParameterAndRun
This script will open the model ControlledSystem.emx and run a simulation. Then a
model parameter is changed and a second simulation run is performed. As explained in
the previous topic, you can inspect the script in a text editor.
C ompared to the basic script you will find a new function:
xxsimSetParameters: This function is used to set the parameter in the model with
the new value.
20-sim 4.6 Reference Manual
524
8. Toolboxes
Multiple Runs
5.
In Octave/Matlab, execute the following script (e.g. type the command followed by
ENTER):
multipleRun
This script will open the model ControlledSystem.emx and run a simulation multiple
times while changing a parameter. Then a model parameter is changed and a second
simulation run is performed.
Read Parameter Values
6.
In Octave/Matlab, execute the following script (e.g. type the command followed by
ENTER):
readAndSetParameters
This script will open the model ControlledSystem.emx and run a simulation. Then a
model parameter is read from file and changed accordingly in the model, followed by a
second simulation run.
You will find these new functions:
addpath: An additional path is given (../library/xxlib) to allow addtional (user
defined) functions.
xxlibReadCsv: This function is used to read a parameter name and value from a
spreadsheet file.
Store Simulation Results
7.
In Octave/Matlab, execute the following script (e.g. type the command followed by
ENTER):
modelVerification
This script will open the model ControlledSystem.emx and run a simulation. After the run
the simulation results are stored and plotted in Octave/Matlab. You will find these new
functions:
xxsimSetLogVariables: Define which variables are going to be logged during the
simulation run.
xxsimGetLogVariables: Export the logged variables after the simulation run to
Octave/Matlab.
Examples
8.
In Octave/Matlab, change the local working directory to the tutorial folder. E.g. type:
cd 'C:\Users\yourusername\Documents\20simscripting\examples'
here you can find more example scripts.
20-sim 4.6 Reference Manual
525
8. Toolboxes
Writing your own Scripts
Example
We will show you how to write your own scripts using a simple example. We assume that
you have installed a scripting folder and its location is:
'C:\Users\yourusername\Documents\20simscripting'
of course you can use own location. We will copy a 20-sim model to the scripting folder
and write a script that will open this model in 20-sim and run a simulation.
1.
Copy the example model FastManipulator.emx tot the Octave\tutorials folder. E.g
copy:
'C:\Program Files (x86)\20-sim 4.6\Models\Examples\Drivetrains\FastManipulator.em
to
'C:\Users\yourusername\Documents\20simscripting\Octave\tutorials
\FastManipulator.emx'
2.
Open a text editor (e.g. notepad) and enter the following lines:
run('../library/xxsim/xxsimAddToPath.m');
xxsimConnect();
xxsimOpenModel( 'FastManipulator.emx' );
xxsimProcessModel();
xxsimRun();
xxsimDisconnect();
3.
Save the text file as:
'C:\Users\yourusername\Documents\20simscripting\Octave\tutorials
\MyScript.m'
4.
Open 20-sim.
5.
Open Octave (or Matlab).
6.
In Octave/Matlab, change the local working directory. Type in the command line:
cd 'C:\Users\yourusername\Documents\20simscripting\Octave\tutorials'
7.
In Octave/Matlab, run your own script. Type in the command line:
20-sim 4.6 Reference Manual
526
8. Toolboxes
MyScript
Now you will see the model being loaded in 20-sim and a simulation being run.
Writing your own scripts
In the tutorial folder there are more scripts. Use these as a template for writing you own
scripts and follow the guidelines below:
Location
C reate your own subfolder inside your scripting working folder. This allows you to
update the 20-sim scripting files when new versions of 20-sim are released.
Functions
You can find help on scripting functions in the 20-sim Editor by selecting Help - Octave
Scripting API.
8.8.4
Scripting in Python
Installation for Scripting: Python
What is Python
Python is a general-purpose high-level programming language with an emphasis on code
readability and writing algorithms in fewer lines of code than other programming
languages. Python is open-source and managed by the Python Software Foundation. It
has an extensive standard library and can be extended with many external libraries
including a rapidly growing set of scientific and mathematical libraries such as SciPy,
NumPy and Sympy and an extensive plotting library Matplotlib. 20-sim scripting has
been tested with the following versions of Python: Python 2.7.x, Python 3.4.x and Python
3.5.x (32-bit and 64-bit).
Installation
During installation of 20-sim, you are asked to install the (optional) Python 3.4
package. We advise to keep the default setting (Yes) which will install the Python 3.4
installation that includes 20-sim scripting support and the following packages: NumPy,
Matplotlib and IPython. This installation provides just enough support to get started with
20-sim scripting. However, it does not provide a development IDE or an extensive set of
scientific and mathematical libraries.
20-sim 4.6 Reference Manual
527
8. Toolboxes
Prepare Scripting Folder
20-sim comes with a Scripting Folder that contains documentation of all scripting
functions, the function library and example scripts. You have to install this folder to use
scripting.
Installation
1.
Open the Install Scripting program from the Windows Start menu (located under
20-sim 4.6)
- or Go to the folder where 20-sim is installed (e.g. C:\Program Files (x86)\20-sim
4.6\Scripting or C:\Program Files (x86)\20-sim 4.6\Scripting) and open
20simScripting.exe
2.
This will open a dialog where you can choose where to extract the 20-sim scripting
files. Change the path to a local working folder of your choice (for example: C:
\Users\yourusername\Documents\20simscripting)
20-sim Scripts extraction
Note: To write/modify scripts, the scripting folder should be accessible and writable by
the user. Do not install the scripting folder on C:\Program Files (x86) or C:\Program
Files.
For the remainder of this chapter, we use the name scripting working folder when we
refer to the folder where you just extracted the 20-sim scripting files.
Contents
Your newly created scripting working folder contains a number of subfolders:
1.
Models: This folder contains the 20-sim models and data files that are used for the
example and tutorial scripts .
2.
Octave and Octave-patch: These folders contain Octave/Matlab scripting
functionality and documentation (see the Scripting in Octave/Matlab section for more
information)
3.
Python: This folder contains all Python scripting functionality and documentation:
a.
controllab: Folder containing the Python classes that allow communication with
20-sim.
b.
documentation: This folder contains the scripting API documentation: a list of
supported functions and their syntax. It is a copy of the help file that you can
open in the 20-sim Editor by selecting Help - Python Scripting API.
c.
examples: This folder contains some more advanced scripts.
20-sim 4.6 Reference Manual
528
8. Toolboxes
d.
tutorials: This folder contains basis scripts with a step by step explanation. You
can use these scripts as a base for your own scripts.
Basic Script
When the scripting files are properly installed in your scripting working folder, we can
run some tutorial scripts. Tutorial scripts are step by step demonstrations of usage of the
scripting functionality in 20-sim. These scripts can be found in the tutorials subfolder of
the scripting working folder. We will start with a basic script that opens and runs a 20sim model.
1.
Open 20-sim.
2.
Open IPython (Interactive Python shell) from the Start menu (under 20-sim 4.6).
3.
In IPython, change the local working directory to the tutorial folder inside your
scripting working folder . E.g . type:
cd 'C:\Users\yourusername\Documents\20simscripting\Python'
4.
In IPython, execute the following command (e.g. type the following case
sensitive command followed by ENTER):
run main_menu
Note that the run command is specific for IPython. For a standard Python session, you
can start this script on the command line using: python.exe menu.py. This command
will show a menu with several options including T for Tutorials.
IPython session for the tutorials
20-sim 4.6 Reference Manual
529
8. Toolboxes
5.
Select option T - Tutorials (press t, ENTER) to show the tutorial menu:
- Tutorial menu Select a tutorial:
1 - Run a simulation.
2 - Set a parameter in 20-sim, then run a simulation.
3 - Execute multiple runs with a changing parameter.
4 - Basic simulation result analysis.
5 - Read a parameter from a CSV file and set it in 20-sim.
6 - Retrieve 20-sim model variables and their properties.
Or choose a menu option:
Q - Quit
I - Show the introduction text again.
Your choice > 1
6.
Press ENTER again to show the available tutorials and choose option 1 Run a
simulation followed by ENTER.
In
-
7.
this tutorial the scripting interface will:
Open a 20-sim model (starting 20-sim if necessary)
Process and run the model
Close the 20-sim model
Press ENTER
The Python scripting interface will now connect to 20-sim.
If 20-sim is not running it will be started automatically.
8.
Press ENTER
Connecting, please wait...
The scripting interface has successfully connected to 20-sim.
The tutorial model will be opened.
If you still have an open model. SAVE YOUR MODEL, unsaved changes
will be overwritten.
9.
Press ENTER
The model ControlledSystem.emx has been opened in 20-sim.
The model will be processed and simulated.
The 20-sim plot window will open.
10. Press ENTER to load the model ControlledSystem.emx in 20-sim and to simulate it.
The tutorial will now close the 20-sim model and exit.
11. Press ENTER to close the simulation and this 20-sim model
20-sim 4.6 Reference Manual
530
8. Toolboxes
Inspecting the script
Tutorial completed!
Do you want to see the source code? [y/N]
To see how the script is made, you can inspect it by choosing y. This will print the
relevant script lines on the Python console. You can also open the real script in a text
editor like Notepad by opening the file: C:\Users\yourusername\Documents
\20simscripting\Python\tutorials\run_simulation.py.
Important Functions
The important functions / lines of the runSimulation script are:
import controllab: Tell Python to load the C ontrollab package with the 20-sim
scripting functions in the XXSim() class.
my20sim = controllab.XXSim(): create a 20-sim scripting object
my20sim.connect(): This command opens a connection to 20-sim.
my20sim.set_scriptmode(): Tell 20-sim that we are in scripting mode (does not
show confirmation dialogs)
my20sim.open_model(): This command opens a model in 20-sim by giving the file
name including the full path.
my20sim.process_model(): This command will process the model.
my20sim.run(): This command will run a simulation.
my20sim.close_model(): This command will remove the simulation model from
20-sim.
These functions are the basis of scripting in 20-sim and will be present in this order in
most scripts.
Writing your own Scripts
Example
We will show you how to write your own scripts using a simple example. We assume that
you have installed a scripting folder and its location is:
'C:\Users\yourusername\Documents\20simscripting'
Of course you can use own location. We will copy a 20-sim model to the scripting folder
and write a script that will open this model in 20-sim and run a simulation.
1.
Copy the example model FastManipulator.emx to the Octave\tutorials folder. E.g
copy:
20-sim 4.6 Reference Manual
531
8. Toolboxes
'C:\Program
Files
\FastManipulator.emx'
(x86)\20-sim
4.6\Models\Examples\Drivetrains
to
'C:\Users\yourusername\Documents\20simscripting\Python\tutorials
\FastManipulator.emx'
2.
Open a text editor (e.g. notepad) and enter the following lines:
import controllab
xxsim = controllab.XXSim()
xxsim.connect()
xxsim.open_model('FastManipulator.emx')
xxsim.process_model()
xxsim.run()
xxsim.disconnect()
3.
Save the text file as:
'C:\Users\yourusername\Documents\20simscripting\Python\tutorials
\myscript.py'
4.
Open 20-sim.
5.
Open IPython.
6.
In IPython, change the local working directory. Type in the command line:
cd 'C:\Users\yourusername\Documents\20simscripting\Python\tutorials'
7.
In IPython, run your own script. Type in the command line:
run myscript
Now you will see the model being loaded in 20-sim and a simulation being run.
Writing your own scripts
In the tutorial folder there are more scripts. Use these as a template for writing your
own scripts and follow the guidelines below:
Location
C reate your own subfolder inside your scripting working folder. This allows you to
update the 20-sim scripting files when new versions of 20-sim are released.
20-sim 4.6 Reference Manual
532
8. Toolboxes
Functions
You can find help on scripting functions in the 20-sim Editor by selecting Help - Python
Scripting API.
Advanced Functionality
Python Distributions
When you need more functionality or prefer to use an IDE with syntax highlighting and
debugging support, it is strongly advised to install one of the following external Python
distributions or IDEs:
PyZo: a free and open-source Python distribution that comes with many scientific
packages and the powerful IEP IDE.
Spyder: the Scientific PYthon Development EnviRonment with a powerful IDE for the
Python language with advanced editing, interactive testing, debugging and
introspection features and a a numerical computing environment based on SciPy,
NumPy, Matplotlib and IPython.
Python, extended with the Visual Studio IDE and Python Tools for Visual Studio.
Running 20-sim scripts in Python distributions
To add the 20-sim scripting support to your Python distribution, you can use the Python
pip command (installed by default since Python 2.7.10 and 3.4.x) to install the C ontrollab
package.
1.
Open a Windows command prompt (cmd.exe) and type:
cd YOUR_PYTHON_INSTALLATION_DIR\
python -m pip install --no-cache-dir --upgrade "C:\Program Files (x86)
\20-sim 4.6\Scripting\Python\whl\controllab-1.0.0-py2.py3-none-any.whl"
Note: use C :\Program Files\20-sim 4.6\ on 32-bit Windows systems.
Manual installation of the Controllab package in Python
20-sim 4.6 Reference Manual
533
9. Library
9
Library
9.1
Bond Graph
9.1.1
Bond Graph Models
Bond graphs are a network-like description of physical systems in terms of ideal physical
processes. With the bond graph method we split up the system characteristics into an
(imaginary) set of separate elements. Each element describes an idealized physical
process. To facilitate drawing of bond graphs, the common elements are denoted by
special symbols. This library contains all kind of bond graph elements. If you want to
know more about modeling with bond graphs, please have a look at the modeling
tutorial.
The standard library contains single dimensional bond graph elements. The 2d Library
contains elements with multi-bonds of size 2 and the 3d library contains elements with
multi-bonds of size 3.
9.1.2
C
Library
Bond Graph
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams, Bond Graphs.
Description
This model represents a power continuous storage element. The element has a
preferred effort out causality. The corresponding constitutive equations then contain an
integration. The element can also have the non-preferred flow out causality. The
constitutive equations then contain a derivation.
effort out causality (preferred):
state = int(p.f) + state(0);
p.e = state/c;
output = state;
flow out causality:
state = c*p.e;
p.f = d state / dt;
output = state;
Interface
Ports
Description
p
Input port of the storage element.
20-sim 4.6 Reference Manual
534
9. Library
Causality
preferred effort out
A
flow
out
causality
results
in
a
derivative
constitutive equation.
Outputs
output
The output signal is equal to the state.
Parameters
c
The storage element constant.
Initial Values
state(0)
9.1.3
The initial value of the storage element.
CC
Library
Bond Graph
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams, Bond Graphs.
Description
This model represents a two port C -element. Normally the equation of a two port C element is written in vector notation as:
p.e = (1/C) * int(p.f)
When the C matrix is singular simulation will not be possible. Therefore the element is
described in a safer notation as:
p.e = A * int(p.f) , with A = (1/C);
Both ports have a preferred effort out causality:
state1 = int (p1.f);
state2 = int (p2.f);
p1.e = a11*state1 + a12*state2;
p2.e = a21*state1 + a22*state2;
Interface
Ports
Description
p1,p2
Input ports of the storage element.
Causality
20-sim 4.6 Reference Manual
535
9. Library
preferred effort out p1
A
preferred effort out p2
constitutive equation.
flow
out
causality
results
in
a
derivative
Outputs
state1
state2
Parameters
a11, a12, a21, a22
The storage element constants.
Initial Values
state1_initial
The initial values of the storage element.
state2_initial
9.1.4
EffortSensor
Library
System , Bond Graph
Use
Domains: C ontinuous. Size: [n,m]. Kind: Bond Graphs.
Description
This model can be inserted in any bond to yield the effort of that bond as an output
signal.
To ensure success, use drag and drop to place the sensor exactly on top in the middle
of the bond. As a result the model will be automatically connected.
Interface
Ports
p1, p2
Input and output port of the effort sensor.
Outputs
effort
Effort of the bond.
20-sim 4.6 Reference Manual
536
9. Library
9.1.5
EnergySensor
Library
System , Bond Graph
Use
Domains: C ontinuous. Size: [n,m]. Kind: Bond Graphs.
Description
This model can be inserted in any bond to yield the energy that is carried through that
bond as an output signal.
To ensure success, use drag and drop to place the sensor exactly on top in the middle
of the bond. As a result the model will be automatically connected.
Interface
Ports
p1, p2
Input and output port of the energy sensor.
Outputs
E
9.1.6
Energy carried through the bond.
FlowSensor
Library
System , Bond Graph
Use
Domains: C ontinuous. Size: [n,m]. Kind: Bond Graphs.
Description
This model can be inserted in any bond to yield the flow of that bond as an output signal.
To ensure success, use drag and drop to place the sensor exactly on top in the middle of
the bond. As a result the model will be automatically connected.
20-sim 4.6 Reference Manual
537
9. Library
Interface
Ports
p1, p2
Input and output port of the flow sensor.
Outputs
flow
Flow of the bond.
9.1.7
GY
Library
Bond Graph
Use
Domains: C ontinuous. Size: 1-D. Kind: Bond Graphs.
Description
This model represents an ideal gyrator, a power continuous relation between the effort
of one port and the flow of the other port and vice-versa. The model can have both ports
with an effort out causality or both ports with a flow out causality:
effort out causality:
p1.e = r * p2.f;
p2.e = r * p1.f;
flow out causality:
p1.f = 1/r * p2.e;
p2.f = 1/r * p1.e;
Interface
Ports
Description
p1, p2
Input and output port of the gyrator.
Causality
p1 equal p2
The causality of both ports must be equal.
Parameters
r
Gyration ratio.
20-sim 4.6 Reference Manual
538
9. Library
9.1.8
I
Library
Bond Graph
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams, Bond Graphs.
Description
This model represents a power continuous storage element. The element has a
preferred flow out causality. The corresponding constitutive equations then contain an
integration. The element can also have the non-preferred effort out causality. The
constitutive equations then contain a derivation.
flow out causality (preferred):
state = int(p.e) + state(0);
p.f = state/i;
output = state;
effort out causality:
state = i*p.f;
p.e = d state / dt;
output = state;
Interface
Ports
Description
p
Input port of the storage element.
Causality
preferred flow out
An effort out causality results in
a
derivative
constitutive equation.
Outputs
output
The output signal is equal to the state.
Parameters
i
The storage element constant.
Initial Values
state(0)
The initial value of the storage element.
20-sim 4.6 Reference Manual
539
9. Library
9.1.9
II
Library
Bond Graph
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams, Bond Graphs.
Description
This model represents a two port I-element. Normally the equation of a two port Ielement is written in vector notation as:
p.f = (1/I) * int(p.e)
When the I matrix is singular simulation will not be possible. Therefore the element is
described in a safer notation as:
p.f = A * int(p.e) , with A = (1/I);
Both ports have a preferred effort out causality:
state1
state2
p1.f =
p2.f =
= int (p1.e);
= int (p2.e);
a11*state1 + a12*state2;
a21*state1 + a22*state2;
Interface
Ports
Description
p1,p2
Input ports of the storage element.
Causality
preferred effort out p1
A
preferred effort out p2
constitutive equation.
flow
out
causality
results
in
a
derivative
Outputs
state1
state2
Parameters
a11, a12, a21, a22
The storage element constants.
Initial Values
state1_initial
The initial values of the storage element.
state2_initial
20-sim 4.6 Reference Manual
540
9. Library
9.1.10 IC
Library
Bond Graph
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams, Bond Graphs.
Description
This model is a combination of an I storage element and a C storage element.
C onsequently the constitutive equation must be written as a matrix-vector multiplication.
The constitutive equation of this element is given below:
state1 = int(p1.f);
state2 = int(p2.e);
p1.e = state1*a11 + state2*a21;
p2.f = state1*a21 + state2*a22;
output2 = state1;
output2 = state2;
The Maxwell reciprocity demands a12 = a21. Therefore only 3 matrix parameters are
necessary.
Interface
Ports
Description
p1,p2
Input ports of the storage element.
Causality
fixed effort out p1
fixed flow out p2
Outputs
output1, output2
The output signals are equal to the states.
Parameters
a11,a21,a22
The storage element constants.
Initial Values
state1(0), state2(0)
The initial values of the storage element.
20-sim 4.6 Reference Manual
541
9. Library
9.1.11 MGY
Library
Bond Graph
Use
Domains: C ontinuous. Size: 1-D. Kind: Bond Graphs.
Description
This model represents an ideal modulated gyrator, a power continuous relation between
the effort of one port and the flow of the other port and vice-versa. The gyration ratio
can be set to a certain (fluctuating) value, given by an input signal. The model can have
both ports with an effort causality or both ports with a flow causality:
effort out causality:
p1.e = input * p2.f;
p2.e = input * p1.f;
flow out causality:
p1.f = 1/input * p2.e;
p2.f = 1/input * p1.e;
Interface
Ports
Description
p1, p2
Input and output port of gyrator.
Causality
p1 equal p2
The causality of both ports must be equal.
Inputs
input
Modulated gyration ratio.
9.1.12 MR
Library
Bond Graph
Use
Domains: C ontinuous. Size: 1-D. Kind: Bond Graphs.
Description
This model represents a linear friction/resistor equation. It can have an effort as well as
a flow causality. In that case the constitutive equation, as shown below, is simply
inverted. The friction/resistor parameter can be set to a (fluctuating) value, given by an
input signal.
effort out causality:
20-sim 4.6 Reference Manual
542
9. Library
p.e = input*p.f
flow out causality:
p.f = p.e/input
Interface
Ports
Description
p
Input port of the R-element.
Causality
indifferent
Inputs
input
The (modulated) friction/resistor parameter.
9.1.13 MSe
Library
Bond Graph
Use
Domains: C ontinuous. Size: 1-D. Kind: Bond Graphs.
Description
This model represents an ideal modulated effort source. The effort can be set to a
(fluctuating) value given by an input signal. The flow is indifferent.
p.e = input;
Interface
Ports
Description
p
Output port of the effort source.
Causality
fixed effort out
Inputs
input
Modulation signal.
20-sim 4.6 Reference Manual
543
9. Library
9.1.14 MSf
Library
Bond Graph
Use
Domains: C ontinuous. Size: 1-D. Kind: Bond Graphs.
Description
This model represents an ideal modulated flow source. The flow can be set to a
(fluctuating) value given by an input signal. The effort is indifferent.
p.f = input;
Interface
Ports
Description
p
Output port of the flow source.
Causality
fixed flow out
Inputs
input
Modulation signal.
9.1.15 MTF
Library
Bond Graph
Use
Domains: C ontinuous. Size: 1-D. Kind: Bond Graphs.
Description
This model represents an ideal modulated transformer. The model represents a power
continuous relation between the efforts and flows of both its ports. The transform ratio
can be set to a certain (fluctuating) value, given by an input signal. The causality is
always mixed: one port has an effort out causality while the other has a
flow out causality:
p1.e = input * p2.e;
p2.f = input * p1.f;
or:
20-sim 4.6 Reference Manual
544
9. Library
p2.e = 1/input * p1.e;
p1.f = 1/input * p2.f;
Interface
Ports
Description
p1, p2
Input and output port of the transformer.
Causality
p1 notequal p2
Inputs
input
Modulated transform ratio.
9.1.16 OneJunction
Library
Bond Graph
Use
Domains: C ontinuous. Size: [n,m]. Kind: Bond Graphs.
Description
This junction represents a power continuous (no energy storage, dissipation or
generation) connection of elements. The sum of the efforts on all ports is zero and the
flows on all ports are equal. The constitutive equations are for example:
p1.e + p2.e - p3.e - p4.e = 0;
p1.f = p2.f = p3.f = p4.f;
flow = p4.f;
A one junction has only one initial port p defined. Because any number of bonds may be
connected, successive connected bonds are named p1, p2, p3 etc.
The plus or minus signs of the effort equation depend on the direction of the bonds. A
bond pointing towards the one junction results in a plus sign and vice-versa. Only one
port of a one junction may determine the flow. In the example port p4 determines the
flow.
Multi Bonds
Bonds with a size larger than one (multi bonds) can also be connected to a one junction.
Al connected bonds, however, must have the same size.
20-sim 4.6 Reference Manual
545
9. Library
p1.e + p2.e - p3.e + p4.e = 0;
p1.f = p2.f = p3.f = p4.f;
flow = p4.f;
Naming conventions are equal to those of the single bond (size 1) junctions. Successive
connected bonds are named p1, p2, p3 etc. To denote single elements of a multibond,
matrix notation is used. E.g. the effort of bond number 3 of a multibond p2 can be
denoted as p2.e[3] (columnvector notation) or p2.e[3,1] (matrix notation).
Interface
Ports
Description
p[any]
Any number of ports may be connected.
Causality
1_effort p
Only one port may have an effort out causality (as
seen from the element).
Outputs
flow
The output signal is equal to the flow of the ports.
Limitations
All connected bonds must have the same size.
9.1.17 OneJunction-Activity
Library
Bond Graph
Use
Domains: C ontinuous. Size: 1-D. Kind: Bond Graphs.
Description
This junction is equal to a normal one junction but monitors the powerflows through the
connected bonds. If you use this junction and connect some bonds, it could look like the
figure below. The bond numbers are important for identification. You can see them by
clicking Port Names from the View menu.
20-sim 4.6 Reference Manual
546
9. Library
The constitutive equations for this example are:
p1.e - p2.e - p3.e - p4.e = 0;
p1.f = p2.f = p3.f = p4.f;
flow = p4.f;
The powerflows through the junction are monitored:
power = p.e .* p.f;
Note that power is a vector with a size equal to the number of bonds that are attached to
the junction. The first element of the vector is the power of the first bond (p1 in the
example figure), the second element is the power of the second bond (p2 in the example
figure) and so on. To see which bonds are active and which bonds are not, the activity is
calculated:
activity = int (abs (power));
To get an easy comparison, the relative activity is calculated:
maximum_activity = max (activity);
relative_activity = activity ./ maximum_activity
Interface
Ports
Description
p[any]
Any number of ports may be connected.
Causality
1_effort p
Only one port may have a effort out causality (as
seen from the element).
Outputs
flow
The output signal is equal to the effort of the ports.
Variables
power
Vector of which the elements are the powers of the
connected bonds.
20-sim 4.6 Reference Manual
547
9. Library
activity
Vector of which the elements are the integrated
absolute powers of the connected bonds.
relative_activity
Vector of which the elements are the relative
activities of the connected bonds.
Limitations
All connected bonds must have size 1.
9.1.18 PowerSensor
Library
System , Bond Graph
Use
Domains: C ontinuous. Size: [n,m]. Kind: Bond Graphs.
Description
This model can be inserted in any bond to yield the power that is carried through that
bond as an output signal.
To ensure success, use drag and drop to place the sensor exactly on top in the middle of
the bond. As a result the model will be automatically connected.
Interface
Ports
p1, p2
Input and output port of the power sensor.
Outputs
E
Power carried through the bond.
20-sim 4.6 Reference Manual
548
9. Library
9.1.19 Power Splitter
Library
System , Bond Graph
Use
Domains: C ontinuous. Size: n-D. Kind: Bond Graphs.
Description
This model can be used to split a multi-bond into single bonds or vice versa. Default 2
bonds can be connected. Use the right mouse menu and choose Edit Implementation to
change the number of bonds.
Interface
Inputs/Outputs
P(any)
Multi-bond (dimension [n,m]).
p
single bonds (a total of n*m)
Note
The multi-bond and corresponding single bonds must have opposite orientations. I.e.
when the multi-bond is pointing towards the the power-splitter, all single bonds must
point from the power splitter and when the multi-bond is pointing from the the powersplitter, all single bonds must point towards the signal splitter.
9.1.20 PSensor
Library
System , Bond Graph
Use
Domains: C ontinuous. Size: [n,m]. Kind: Bond Graphs.
Description
This model can be inserted in any bond to yield the integral of the effort of that bond as
an output signal.
To ensure success, use drag and drop to place the sensor exactly on top in the middle of
the bond. As a result the model will be automatically connected.
Interface
Ports
p1, p2
Input and output port of the flow sensor.
20-sim 4.6 Reference Manual
549
9. Library
Outputs
p
Integral of the effort of the bond.
9.1.21 Qsensor
Library
System , Bond Graph
Use
Domains: C ontinuous. Size: [n,m]. Kind: Bond Graphs.
Description
This model can be inserted in any bond to yield the integral of the flow of that bond as
an output signal.
To ensure success, use drag and drop to place the sensor exactly on top in the middle of
the bond. As a result the model will be automatically connected.
Interface
Ports
p1, p2
Input and output port of the flow sensor.
Outputs
q
Integral of the flow of the bond.
9.1.22 R
Library
Bond Graph
Use
Domains: C ontinuous. Size: 1-D. Kind: Bond Graphs.
20-sim 4.6 Reference Manual
550
9. Library
Description
This model represents a linear friction/resistor equation. It can have an effort out as well
as a flow out causality. In the last case the constitutive equation, as shown below, is
simply inverted.
effort out causality:
p.e = r*p.f;
flow out causality:
p.f = p.e/r;
Interface
Ports
Description
p
Input port of the R-element.
Causality
indifferent
Parameters
r
The friction/resistor parameter.
9.1.23 Se
Library
Bond Graph
Use
Domains: C ontinuous. Size: 1-D. Kind: Bond Graphs.
Description
This model represents an ideal effort source. The effort can be set to a certain constant
value, the flow is indifferent.
p.e = s;
Ports
Description
p
Output port of the effort source.
Causality
fixed effort out
Parameters
s
The constant value of the generated effort
20-sim 4.6 Reference Manual
551
9. Library
9.1.24 Sf
Library
Bond Graph
Use
Domains: C ontinuous. Size: 1-D. Kind: Bond Graphs.
Description
This model represents an ideal flow source. The flow can be set to a certain constant
value, the effort is indifferent.
p.f = s;
Interface
Ports
Description
p
Output port of the flow source.
Causality
fixed flow out
Parameters
s
The constant value of the generated flow.
9.1.25 SGY
Library
Bond Graph
Use
Domains: C ontinuous. Size: 1-D. Kind: Bond Graphs.
Description
This model represents an ideal gyrator with gyration ratio 1. The model represents a one
to one power continuous relation between the effort of one port and the flow of the other
port and vice-versa. The model can be used to transform a C element into a I element
etc. The model can have both ports with an effort causality or both ports with a flow
causality:
effort out causality:
p1.e = p2.f;
p2.e = p1.f;
flow out causality:
20-sim 4.6 Reference Manual
552
9. Library
p1.f = p2.e;
p2.f = p1.e;
Interface
Ports
Description
p1, p2
Input and output port of the gyrator.
Causality
p1 equal p2
9.1.26 STF
Library
Bond Graph
Use
Domains: C ontinuous. Size: 1-D. Kind: Bond Graphs.
Description
This model represents an ideal transformer with transform ratio 1. The model has no
real effect but allows for domain changes (one port having another domain as the
other). The model represents a power continuous relation between the efforts and flows
of both its ports. The causality is always mixed: one port has an effort causality while
the other has a flow causality:
p1.e = p2.e
p2.f = p1.f
or:
p2.e = p1.e
p1.f = p2.f
Interface
Ports
Description
p1, p2
Input and output port of the simple transformer.
Causality
p1 notequal p2
The causality of both ports must be different.
20-sim 4.6 Reference Manual
553
9. Library
9.1.27 SwitchingOneJunction
Library
Bond Graph
Use
Domains: C ontinuous. Size: [n,m]. Kind: Bond Graphs.
Description
This junction represents a switching 1 junction. Depending on the condition value it can
connect / disconnect additional elements to / from the bond graph.
The p12 junction port is connected when condition <> 0. The sum of the efforts on all
three ports is zero and the flows on all ports are equal.
When disconnected (condition == 0), the effort and flow of port p12 are both zero. Ports
p1 and p2 are still connected (flow = zero, efforts are equal).
Interface
Ports
p1, p2
Input and output port of the 1 junction.
p12
C onditional port (only connected when condition evaluates
to a non-zero value)
Inputs
condition
Switching condition (non-zero value = connected)
Limitations
All connected bonds must have the same size.
9.1.28 SwitchingZeroJunction
Library
Bond Graph
Use
Domains: C ontinuous. Size: [n,m]. Kind: Bond Graphs.
Description
This junction represents a switching 0 junction. Depending on the condition value it can
connect / disconnect additional elements to / from the bond graph.
The p12 junction port is connected when condition <> 0. The sum of the flows on all
three ports is zero and the efforts on all ports are equal.
When disconnected (condition == 0), the effort and flow of port p12 are both zero. Ports
p1 and p2 are still connected (effort = zero, flows are equal).
20-sim 4.6 Reference Manual
554
9. Library
Interface
Ports
p1, p2
Input and output port of the 1 junction.
p12
C onditional port (only connected when condition evaluates
to a non-zero value)
Inputs
condition
Switching condition (non-zero value = connected)
Limitations
All connected bonds must have the same size.
9.1.29 TF
Library
Bond Graph
Use
Domains: C ontinuous. Size: 1-D. Kind: Bond Graphs.
Description
This model represents an ideal transformer. The model represents a power continuous
relation between the efforts and flows of both its ports. The causality is always mixed:
one port has an effort causality while the other has a flow causality:
p1.e = r * p2.e
p2.f = r * p1.f
or:
p2.e = 1/r * p1.e
p1.f = 1/r * p2.f
Interface
Ports
Description
p1, p2
Input and output port of the transformer.
Causality
p1 notequal p2
The causality of both ports must be different.
Parameters
r
Transform ratio
20-sim 4.6 Reference Manual
555
9. Library
9.1.30 ZeroJunction
Library
Bond Graph
Use
Domains: C ontinuous. Size: [n,m]. Kind: Bond Graphs.
Description
This junction represents a power continuous (no energy storage, dissipation or
generation) connection of elements. The sum of the flows on all ports is zero and the
efforts on all ports are equal. The constitutive equations are for example:
p1.f + p2.f - p3.f - p4.f = 0;
p1.e = p2.e = p3.e = p4.e;
effort = p1.e;
A zero junction has only one initial port p defined. Because any number of bonds may be
connected, successive connected bonds are named p1, p2, p3 etc.
The plus or minus signs of the flow equation depend on the direction of the bonds. A
bond pointing towards the zero junction results in a plus sign and vice-versa. Only one
port of a zero junction may determine the effort. In the example port p1 determines the
effort.
Multi Bonds
Bonds with a size larger than one (multi bonds) can also be connected to a zero junction.
Al connected bonds, however, must have the same size.
20-sim 4.6 Reference Manual
556
9. Library
p1.f + p2.f - p3.f + p4.f = 0;
p1.e = p2.e = p3.e = p4.e;
effort = p1.e;
Naming conventions are equal to those of the single bond (size 1) junctions. Successive
connected bonds are named p1, p2, p3 etc. To denote single elements of a multibond,
matrix notation is used. E.g the effort of bond number 3 of a multibond p2 can be
denoted as p2.e[3] (columnvector notation) or p2.e[3,1] (matrix notation).
Interface
Ports
Description
p[any]
Any number of ports may be connected.
Causality
1_flow p
Only one port may have a flow out causality (as
seen from the element).
Outputs
effort
The output signal is equal to the effort of the ports.
Limitations
All connected bonds must have the same size.
9.1.31 ZeroJunction-Activity
Library
Bond Graph
Use
Domains: C ontinuous. Size: 1-D. Kind: Bond Graphs.
Description
This junction is equal to a normal zero junction but monitors the powerflows through the
connected bonds. If you use this junction and connect some bonds, it could look like the
figure below. The bond numbers are important for identification. You can see them by
clicking Port Names from the View menu.
20-sim 4.6 Reference Manual
557
9. Library
The constitutive equations for this example are:
p1.f - p2.f - p3.f - p4.f = 0;
p1.e = p2.e = p3.e = p4.e;
output = p2.e;
The powerflows through the junction are monitored:
power = p.e .* p.f;
Note that power is a vector with a size equal to the number of bonds that are attached to
the junction. The first element of the vector is the power of the first bond (p1 in the
example figure), the second element is the power of the second bond (p2 in the example
figure) and so on. To see which bonds are active and which bonds are not, the activity is
calculated:
activity = int (abs (power));
To get an easy comparison, the relative activity is calculated:
maximum_activity = max (activity);
relative_activity = activity ./ maximum_activity
Interface
Ports
Description
p[any]
Any number of ports may be connected.
Causality
1_flow p
Only one port may have a flow out causality (as
seen from the element).
Outputs
effort
The output signal is equal to the effort of the ports.
Variables
power
Vector of which the elements are the powers of the
connected bonds.
20-sim 4.6 Reference Manual
558
9. Library
activity
Vector of which the elements are the integrated
absolute powers of the connected bonds.
relative_activity
Vector of which the elements are the relative
activities of the connected bonds.
Limitations
All connected bonds must have size 1.
9.1.32 3d
C-3
Library
Bond Graph
Use
Domains: C ontinuous. Size: 3-D. Kind: Block Diagrams, Bond Graphs.
Description
This model is the multiport equivalent of the single C storage element. C onsequently the
constitutive equation must be written as a matrix-vector multiplication. The element has
a preferred effort out causality. The corresponding constitutive equations then contain an
integration. The element can also have the non-preferred flow out causality. The
constitutive equations then contain a derivation, which can only be simulated when the
Backward Differentiation Formula integration algorithm is available:
effort out causality (preferred):
state = int(p.f) + state(0);
p.e = inverse(C)*state;
outp = state;
flow out causality:
state = C*p.e;
p.f = d state / dt;
output = state;
Interface
Ports
Description
p[3]
Input
port
of
the
storage
element
(columnvector with size 3).
20-sim 4.6 Reference Manual
559
9. Library
Causality
preferred effort out
A flow out causality results in a derivative
constitutive equation.
Outputs
output[3]
The output signal is equal to the state
(columnvector with size 3).
Parameters
C [3,3]
The storage element constants (matrix of
size [3,3]).
Initial Values
state(0)[3]
The initial values of the storage element
(columnvector with size 3).
Limitations
The preferred equation contains an inverted C matrix. The elements of this matrix
should be chosen with care to prevent this matrix from becoming singular.
GY-3
Library
Bond Graph
Use
Domains: C ontinuous. Size: 3-D. Kind: Bond Graphs.
Description
This model is the multiport equivalent of the single gyrator. C onsequently the
constitutive equation must be written as a matrix-vector multiplication. The model can
have both ports with an effort out causality or both ports with a flow out causality:
effort out causality:
p1.e = transpose(R) * p2.f;
p2.e = R * p1.f;
flow out causality:
p1.f = inverse(transpose(R)) * p2.e;
p2.f = inverse(R) * p1.e;
20-sim 4.6 Reference Manual
560
9. Library
Interface
Ports
Description
p1[3], p2[3]
Input and
output port of
the
gyrator
(columnvectors with size 3).
Causality
p1 equal p2
The causality of both ports must be equal.
Parameters
R[3]
Gyration ratio (matrix of size [3,3]).
Limitations
The flow out equations contain an inverted R matrix. The elements of this matrix should
be chosen with care to prevent this matrix from becoming singular.
I-3
Library
Bond Graph
Use
Domains: C ontinuous. Size: 3-D. Kind: Block Diagrams, Bond Graphs.
Description
This model is the multiport equivalent of the single I storage element. C onsequently the
constitutive equation must be written as a matrix-vector multiplication. The element has
a preferred flow out causality. The corresponding constitutive equations then contain an
integration. The element can also have the non-preferred effort out causality. The
constitutive equations then contain a derivation, which can only be simulated when the
Backward Differentiation Formula integration algorithm is available:
flow out causality (preferred):
state = int(p.e) + state(0);
p.f = inverse(I)*state;
output = state;
20-sim 4.6 Reference Manual
561
9. Library
effort out causality:
state = I*p.f;
p.e = d state / dt;
output = state;
Interface
Ports
Description
p[3]
Input
port
of
the
storage
element
(columnvector with size 3).
Causality
preferred effort out
A flow out causality results in a derivative
constitutive equation.
Outputs
output[3]
The output signal is equal to the state
(columnvector with size 3).
Parameters
I[3,3]
The storage element constants (matrix of
size [3,3]).
Initial Values
state(0)[3]
The initial values of the storage element
(columnvector with size 3).
Limitations
The preferred equation contains an inverted I matrix. The elements of this matrix should
be chosen with care to prevent this matrix from becoming singular.
MGY-3
Library
Bond Graph
Use
Domains: C ontinuous. Size: 3-D. Kind: Bond Graphs.
20-sim 4.6 Reference Manual
562
9. Library
Description
This model is the multiport equivalent of the single modulated gyrator. C onsequently the
constitutive equation must be written as a matrix-vector multiplication. The gyration ratio
can be set to a certain (fluctuating) value, given by an input signal. The model can have
both ports with an effort out causality or both ports with a flow out causality:
effort out causality:
p1.e = transpose(r) * p2.f;
p2.e = r * p2.f;
flow out causality:
p1.f = inverse(transpose(r)) * p2.e;
p2.f = inverse(r) * p1.e;
Interface
Ports
Description
p1[3], p2[3]
Input and
output port of
the
gyrator
(columnvectors with size 3).
Causality
p1 equal p2
The causality of both ports must be equal.
Inputs
r[3,3]
Modulated gyration ratio (size [3,3]).
Limitations
The flow out equations contain a matrix inversion of the modulation signal. The elements
of this input signal should always have non-singular values.
20-sim 4.6 Reference Manual
563
9. Library
MR-3
Library
Bond Graph
Use
Domains: C ontinuous. Size: 3-D. Kind: Bond Graphs.
Description
This model is the multiport equivalent of the single dissipative element. C onsequently
the constitutive equation must be written as a matrix-vector multiplication. This model
can have an effort out as well as a flow out causality. In the last case the constitutive
equation, as shown below, is simply inverted. The friction/resistor parameter can be set
to a (fluctuating) value, given by an input signal.
effort out causality:
p.e = r*p.f;
flow out causality:
p.f = inverse(r)*p.e;
Interface
Ports
Description
p[3]
Input port of the R-element (columnvector
with size 3).
Causality
indifferent
Input
r[3,3]
The
(modulated)
friction/resistor
parameter (size [3,3]).
Parameters
R
The friction parameters (matrix of size
[3,3]).
Limitations
The flow out equation contains an inverted R matrix. The elements of this matrix should
be chosen with care to prevent this matrix from becoming singular.
20-sim 4.6 Reference Manual
564
9. Library
MSe-3
Library
Bond Graph
Use
Domains: C ontinuous. Size: 3-D. Kind: Bond Graphs.
Description
This model is the multiport equivalent of the single modulated effort source. The effort
can be set to a (fluctuating) value given by an input signal. The flow is indifferent.
p.e = input;
Ports
Description
p[3]
Output
port
of
the
effort
source
(columnvector with size 3).
Causality
fixed effort out
Inputs
input[3]
Modulation signal (columnvector with size
3).
MSf-3
Library
Bond Graph
Use
Domains: C ontinuous. Size: 3-D. Kind: Bond Graphs.
Description
This model is the multiport equivalent of the single modulated flow source. The flow can
be set to a (fluctuating) value given by an input signal. The flow is indifferent.
p.f = input;
Ports
Description
p[3]
Output
port
of
the
flow
source
(columnvector with size 3).
Causality
fixed flow out
20-sim 4.6 Reference Manual
565
9. Library
Inputs
input[3]
Modulation signal (columnvector with size
3).
MTF-3
Library
Bond Graph
Use
Domains: C ontinuous. Size: 3-D. Kind: Bond Graphs.
Description
This model is the multiport equivalent of the single modulated transformer.
C onsequently the constitutive equation must be written as a matrix-vector multiplication.
The transform ratio can be set to a certain (fluctuating) value, given by an input signal.
The causality is always mixed: one port has an effort out causality while the other has a
flow out causality:
p1.e = transpose(r) * p2.e;
p2.f = r * p1.f;
or:
p2.e = inverse(transpose(r)) * p1.e;
p1.f = inverse(r) * p2.f;
Interface
Ports
Description
p1[3], p2[3]
Input and
output port of
the
gyrator
(columnvectors with size 3).
Causality
p1 notequal p2
Inputs
r[3,3]
Modulated transform ratio (size [3,3]).
Limitations
The second set of equations contain a matrix inversion of the modulation signal. The
elements of this input signal should always have non-singular values.
20-sim 4.6 Reference Manual
566
9. Library
R-3
Library
Bond Graph
Use
Domains: C ontinuous. Size: 3-D. Kind: Bond Graphs.
Description
This model is the multiport equivalent of the single dissipative element. C onsequently
the constitutive equation must be written as a matrix-vector multiplication. This model
can have an effort out as well as a flow out causality. In the last case the constitutive
equation, as shown below, is simply inverted.
effort out causality:
p.e = R*p.f;
flow out causality:
p.f = inverse(R)*p.e;
Interface
Ports
Description
p[3]
Input port of the R-element (columnvector
with size 3).
Causality
indifferent
Parameters
R
The friction parameters (matrix of size
[3,3]).
Limitations
The flow out equation contains an inverted R matrix. The elements of this matrix should
be chosen with care to prevent this matrix from becoming singular.
20-sim 4.6 Reference Manual
567
9. Library
Se-3
Library
Bond Graph
Use
Domains: C ontinuous. Size: 3-D. Kind: Block Diagrams, Bond Graphs.
Description
This model is the multiport equivalent of the single effort source. The effort can be set to
a certain constant value, the flow is indifferent.
p.e = S;
Ports
Description
p[3]
Output
port
of
the
effort
source
(columnvector with size 3).
Causality
fixed effort out
Parameters
S[3]
The constant value of the generated effort
(columnvector with size 3).
Sf-3
Library
Bond Graph
Use
Domains: C ontinuous. Size: 3-D. Kind: Block Diagrams, Bond Graphs.
Description
This model is the multiport equivalent of the single flow source. The effort can be set to
a certain constant value, the flow is indifferent.
p.f = S;
Ports
Description
p[3]
Output
port
of
the
flow
source
(columnvector with size 3).
Causality
fixed flow out
20-sim 4.6 Reference Manual
568
9. Library
Parameters
s[3]
The constant value of the generated flow
(columnvector with size 3).
SGY-3
Library
Bond Graph
Use
Domains: C ontinuous. Size: 3-D. Kind: Bond Graphs.
Description
This model is the multiport equivalent of the single symplectic gyrator. C onsequently the
constitutive equation must be written as a matrix-vector multiplication. This model
represents an ideal gyrator with gyration ratio equal to the identity matrix. The model
represents a one to one power continuous relation between the effort of one port and
the flow of the other port and vice-versa. The model can be used to transform a C -3
element into a I-3 element etc. The model can have both ports with an effort causality or
both ports with a flow causality:
effort out causality:
p1.e = p2.f;
p2.e = p1.f;
flow out causality:
p1.f = p2.e;
p2.f = p1.e;
Interface
Ports
Description
p1[3], p2[3]
Input and
output port of
the
gyrator
(columnvectors with size 3).
Causality
p1 equal p2
The causality of both ports must be equal.
20-sim 4.6 Reference Manual
569
9. Library
STF-3
Library
Bond Graph
Use
Domains: C ontinuous. Size: 3-D. Kind: Bond Graphs.
Description
This model is the multiport equivalent of the single symplectic transformer. This model
represents an ideal transformer with a transform ratio equal to the identity matrix. The
model represents a one to one power continuous relation between the effort of one port
and the flow of the other port and vice-versa. The causality is always mixed: one port
has an effort causality while the other has a flow causality:
p1.e = p2.e;
p2.f = p1.f;
or:
p2.e = p1.e
p1.f = p2.f
Interface
Ports
Description
p1[3], p2[3]
Input and output port of the transformer
(columnvectors with size 3).
Causality
p1 notequal p2
The
causality
of
both
ports
must
be
different.
TF-3
Library
Bond Graph
Use
Domains: C ontinuous. Size: 3-D. Kind: Bond Graphs.
Description
This model is the multiport equivalent of the single transformer. C onsequently the
constitutive equation must be written as a matrix-vector multiplication. The causality is
always mixed: one port has an effort causality while the other has a flow causality:
20-sim 4.6 Reference Manual
570
9. Library
p1.e = transpose(R) * p2.e;
p2.f = R * p1.f;
or:
p2.e = inverse(transpose(R)) * p1.e
p1.f = inverse(R) * p2.f
Interface
Ports
Description
p1[3], p2[3]
Input and output port of the transformer
(columnvectors with size 3).
Causality
p1 notequal p2
The
causality
of
both
ports
must
be
different.
Parameters
R[3,3]
Transform ratio (matrix of size [3,3]).
Limitations
The lower set of equations contain an inverted R matrix. The elements of this matrix
should be chosen with care to prevent this matrix from becoming singular.
9.1.33 2d
C-2
Library
Bond Graph
Use
Domains: C ontinuous. Size: 2-D. Kind: Block Diagrams, Bond Graphs.
Description
This model is the multiport equivalent of the single C storage element. C onsequently the
constitutive equation must be written as a matrix-vector multiplication. The element has
a preferred effort out causality. The corresponding constitutive equations then contain an
integration. The element can also have the non-preferred flow out causality. The
constitutive equations then contain a derivation, which can only be simulated when the
Backward Differentiation Formula integration algorithm is available:
effort out causality (preferred):
20-sim 4.6 Reference Manual
571
9. Library
state = int(p.f) + state(0);
p.e = inverse(C)*state;
outp = state;
flow out causality:
state = C*p.e;
p.f = d state / dt;
output = state;
Interface
Ports
Description
p[2]
Input port of the storage element (columnvector
with size 2).
Causality
preferred effort out
A
flow
out
causality
results
in
a
derivative
constitutive equation.
Outputs
output[2]
The
output
signal
is
equal
to
the
state
(columnvector with size 2).
Parameters
C [2,2]
The storage element constants (matrix of size
[2,2]).
Initial Values
state(0)[2]
The
initial
values
of
the
storage
element
(columnvector with size 2).
Limitations
The preferred equation contains an inverted C matrix. The elements of this matrix
should be chosen with care to prevent this matrix from becoming singular.
20-sim 4.6 Reference Manual
572
9. Library
GY-2
Library
Bond Graph
Use
Domains: C ontinuous. Size: 2-D. Kind: Bond Graphs.
Description
This model is the multiport equivalent of the single gyrator. C onsequently the
constitutive equation must be written as a matrix-vector multiplication. The model can
have both ports with an effort out causality or both ports with a flow out causality:
effort out causality:
p1.e = transpose(R) * p2.f;
p2.e = R * p1.f;
flow out causality:
p1.f = inverse(transpose(R)) * p2.e;
p2.f = inverse(R) * p1.e;
Interface
Ports
Description
p1[2], p2[2]
Input and output port of the gyrator (columnvectors
with size 2).
Causality
p1 equal p2
The causality of both ports must be equal.
Parameters
R[2]
Gyration ratio (matrix of size [2,2]).
Limitations
The flow out equations contain an inverted R matrix. The elements of this matrix should
be chosen with care to prevent this matrix from becoming singular.
20-sim 4.6 Reference Manual
573
9. Library
I-2
Library
Bond Graph
Use
Domains: C ontinuous. Size: 2-D. Kind: Block Diagrams, Bond Graphs.
Description
This model is the multiport equivalent of the single I storage element. C onsequently the
constitutive equation must be written as a matrix-vector multiplication. The element has
a preferred flow out causality. The corresponding constitutive equations then contain an
integration. The element can also have the non-preferred effort out causality. The
constitutive equations then contain a derivation, which can only be simulated when the
Backward Differentiation Formula integration algorithm is available:
flow out causality (preferred):
state = int(p.e) + state(0);
p.f = inverse(I)*state;
output = state;
effort out causality:
state = I*p.f;
p.e = d state / dt;
output = state;
Interface
Ports
Description
p[2]
Input port of the storage element (columnvector
with size 2).
Causality
preferred effort out
A
flow
out
causality
results
in
a
derivative
constitutive equation.
Outputs
output[2]
The
output
signal
is
equal
to
the
state
(columnvector with size 2).
Parameters
I[2,2]
The storage element constants (matrix of size
[2,2]).
Initial Values
20-sim 4.6 Reference Manual
574
9. Library
state(0)[2]
The
initial
values
of
the
storage
element
(columnvector with size 2).
Limitations
The preferred equation contains an inverted I matrix. The elements of this matrix should
be chosen with care to prevent this matrix from becoming singular.
MGY-2
Library
Bond Graph
Use
Domains: C ontinuous. Size: 2-D. Kind: Bond Graphs.
Description
This model is the multiport equivalent of the single modulated gyrator. C onsequently the
constitutive equation must be written as a matrix-vector multiplication. The gyration ratio
can be set to a certain (fluctuating) value, given by an input signal. The model can have
both ports with an effort out causality or both ports with a flow out causality:
effort out causality:
p1.e = transpose(r) * p2.f;
p2.e = r * p2.f;
flow out causality:
p1.f = inverse(transpose(r)) * p2.e;
p2.f = inverse(r) * p1.e;
Interface
Ports
Description
p1[2], p2[2]
Input and output port of the gyrator (columnvectors
with size 2).
Causality
p1 equal p2
The causality of both ports must be equal.
Inputs
r[2,2]
Modulated gyration ratio (size [2,2]).
20-sim 4.6 Reference Manual
575
9. Library
Limitations
The flow out equations contain a matrix inversion of the modulation signal. The elements
of this input signal should always have non-singular values.
MR-2
Library
Bond Graph
Use
Domains: C ontinuous. Size: 2-D. Kind: Bond Graphs.
Description
This model is the multiport equivalent of the single dissipative element. C onsequently
the constitutive equation must be written as a matrix-vector multiplication. This model
can have an effort out as well as a flow out causality. In the last case the constitutive
equation, as shown below, is simply inverted. The friction/resistor parameter can be set
to a (fluctuating) value, given by an input signal.
effort out causality:
p.e = r*p.f;
flow out causality:
p.f = inverse(r)*p.e;
Interface
Ports
Description
p[2]
Input port of the R-element (columnvector with size
2).
Causality
indifferent
Input
20-sim 4.6 Reference Manual
576
9. Library
r[2,2]
The (modulated) friction/resistor parameter (size
[2,2]).
Parameters
R
The friction parameters (matrix of size [2,2]).
Limitations
The flow out equation contains an inverted R matrix. The elements of this matrix should
be chosen with care to prevent this matrix from becoming singular.
MSe-2
Library
Bond Graph
Use
Domains: C ontinuous. Size: 2-D. Kind: Bond Graphs.
Description
This model is the multiport equivalent of the single modulated effort source. The effort
can be set to a (fluctuating) value given by an input signal. The flow is indifferent.
p.e = input;
Ports
Description
p[2]
Output port of the effort source (columnvector with
size 2).
Causality
fixed effort out
Inputs
input[2]
Modulation signal (columnvector with size 2).
20-sim 4.6 Reference Manual
577
9. Library
MSf-2
Library
Bond Graph
Use
Domains: C ontinuous. Size: 2-D. Kind: Bond Graphs.
Description
This model is the multiport equivalent of the single modulated flow source. The flow can
be set to a (fluctuating) value given by an input signal. The flow is indifferent.
p.f = input;
Ports
Description
p[2]
Output port of the flow source (columnvector with
size 2).
Causality
fixed flow out
Inputs
input[2]
Modulation signal (columnvector with size 2).
MTF-2
Library
Bond Graph
Use
Domains: C ontinuous. Size: 2-D. Kind: Bond Graphs.
Description
This model is the multiport equivalent of the single modulated transformer.
C onsequently the constitutive equation must be written as a matrix-vector multiplication.
The transform ratio can be set to a certain (fluctuating) value, given by an input signal.
The causality is always mixed: one port has an effort out causality while the other has a
flow out causality:
p1.e = transpose(r) * p2.e;
p2.f = r * p1.f;
or:
p2.e = inverse(transpose(r)) * p1.e;
20-sim 4.6 Reference Manual
578
9. Library
p1.f = inverse(r) * p2.f;
Interface
Ports
Description
p1[2], p2[2]
Input and output port of the gyrator (columnvectors
with size 2).
Causality
p1 notequal p2
Inputs
r[2,2]
Modulated transform ratio (size [2,2]).
Limitations
The second set of equations contain a matrix inversion of the modulation signal. The
elements of this input signal should always have non-singular values.
R-2
Library
Bond Graph
Use
Domains: C ontinuous. Size: 2-D. Kind: Bond Graphs.
Description
This model is the multiport equivalent of the single dissipative element. C onsequently
the constitutive equation must be written as a matrix-vector multiplication. This model
can have an effort out as well as a flow out causality. In the last case the constitutive
equation, as shown below, is simply inverted.
effort out causality:
p.e = R*p.f;
flow out causality:
p.f = inverse(R)*p.e;
20-sim 4.6 Reference Manual
579
9. Library
Interface
Ports
Description
p[2]
Input port of the R-element (columnvector with size
2).
Causality
indifferent
Parameters
R
The friction parameters (matrix of size [2,2]).
Limitations
The flow out equation contains an inverted R matrix. The elements of this matrix should
be chosen with care to prevent this matrix from becoming singular.
Se-2
Library
Bond Graph
Use
Domains: C ontinuous. Size: 2-D. Kind: Block Diagrams, Bond Graphs.
Description
This model is the multiport equivalent of the single effort source. The effort can be set to
a certain constant value, the flow is indifferent.
p.e = S;
Ports
Description
p[2]
Output port of the effort source (columnvector with
size 2).
Causality
fixed effort out
Parameters
S[2]
The
constant
value
of
the
generated
effort
(columnvector with size 2).
20-sim 4.6 Reference Manual
580
9. Library
Sf-2
Library
Bond Graph
Use
Domains: C ontinuous. Size: 2-D. Kind: Block Diagrams, Bond Graphs.
Description
This model is the multiport equivalent of the single flow source. The effort can be set to
a certain constant value, the flow is indifferent.
p.f = S;
Ports
Description
p[2]
Output port of the flow source (columnvector with
size 2).
Causality
fixed flow out
Parameters
s[2]
The
constant
value
of
the
generated
flow
(columnvector with size 2).
SGY-2
Library
Bond Graph
Use
Domains: C ontinuous. Size: 2-D. Kind: Bond Graphs.
Description
This model is the multiport equivalent of the single symplectic gyrator. C onsequently the
constitutive equation must be written as a matrix-vector multiplication. This model
represents an ideal gyrator with gyration ratio equal to the identity matrix. The model
represents a one to one power continuous relation between the effort of one port and
the flow of the other port and vice-versa. The model can be used to transform a C -2
element into a I-2 element etc. The model can have both ports with an effort causality or
both ports with a flow causality:
effort out causality:
p1.e = p2.f;
p2.e = p1.f;
20-sim 4.6 Reference Manual
581
9. Library
flow out causality:
p1.f = p2.e;
p2.f = p1.e;
Interface
Ports
Description
p1[2], p2[2]
Input and output port of the gyrator (columnvectors
with size 2).
Causality
p1 equal p2
The causality of both ports must be equal.
STF-2
Library
Bond Graph
Use
Domains: C ontinuous. Size: 2-D. Kind: Bond Graphs.
Description
This model is the multiport equivalent of the single simple transformer. This model
represents an ideal transformer with a transform ratio equal to the identity matrix. The
model has no real effect but allows for domain changes (one port having another domain
as the other). The model represents a power continuous relation between the efforts and
flows of both its ports. The causality is always mixed: one port has an effort causality
while the other has a flow causality:
p1.e = p2.e;
p2.f = p1.f;
or:
p2.e = p1.e
p1.f = p2.f
Interface
Ports
Description
20-sim 4.6 Reference Manual
582
9. Library
p1[2], p2[2]
Input
and
output
port
of
the
transformer
(columnvectors with size 2).
Causality
p1 notequal p2
The causality of both ports must be different.
TF-2
Library
Bond Graph
Use
Domains: C ontinuous. Size: 2-D. Kind: Bond Graphs.
Description
This model is the multiport equivalent of the single transformer. C onsequently the
constitutive equation must be written as a matrix-vector multiplication. The causality is
always mixed: one port has an effort causality while the other has a flow causality:
p1.e = transpose(R) * p2.e;
p2.f = R * p1.f;
or:
p2.e = inverse(transpose(R)) * p1.e
p1.f = inverse(R) * p2.f
Interface
Ports
Description
p1[2], p2[2]
Input
and
output
port
of
the
transformer
(columnvectors with size 2).
Causality
p1 notequal p2
The causality of both ports must be different.
Parameters
R[2,2]
Transform ratio (matrix of size [2,2]).
Limitations
The lower set of equations contain an inverted R matrix. The elements of this matrix
should be chosen with care to prevent this matrix from becoming singular.
20-sim 4.6 Reference Manual
583
9. Library
9.2
Iconic Diagrams
9.2.1
Iconic Diagrams
The Iconic Diagram library contains components which are very useful for modeling
physical systems. The following libraries are available.
Electric
Hydraulics
Mechanical
Thermal
9.2.2
Electric
Electric
The Electric library contains components which are very useful for modeling electrical
systems. The library contains the following sections:
Actuators
C omponents
Sources
Actuators
CMABender
Library
Iconic Diagrams\Electric\Actuators
Iconic Diagrams\Mechanical\Translation\Actuators
Use
Domains:
Diagrams.
C ontinuous. Size:
1-D.
Kind:
Iconic
Diagrams
(Translation),
Block
Description
This model represents a piezo actuator. The actuator translates a voltage difference at
port p1 to a mechanical position difference between the base at port p2 and the end
effector at port p3.
Although the underlying equations of this model are equal to the equations of the
CMAStrecher.emx model, the default parameter values are typical for bending.
Interface
Ports
Description
p
Translation port.
Causality
20-sim 4.6 Reference Manual
584
9. Library
fixed force out
Input
C
KF
m
k
B
KB
C apacitance [F]
Voltage to force conversion factor [N/V]
Equivalent mass [kg]
Stiffness [N/m]
Relative damping ratio []
Force to voltage conversion factor [V/N]
CMAStretcher
Library
Iconic Diagrams\Electric\Actuators
Iconic Diagrams\Mechanical\Translation\Actuators
Use
Domains:
Diagrams.
C ontinuous. Size:
1-D.
Kind:
Iconic
Diagrams
(Translation),
Block
Description
This model represents a piezo actuator. The actuator translates a voltage difference at
port p1 to a mechanical position difference between the base at port p2 and the end
effector at port p3.
Although the underlying equations of this model are equal to the equations of the
C MABender.emx model, the default parameter values are typical for stretching.
Interface
Ports
Description
p
Translation port.
Causality
fixed force out
Input
C
KF
m
k
B
KB
C apacitance [F]
Voltage to force conversion factor [N/V]
Equivalent mass [kg]
Stiffness [N/m]
Relative damping ratio []
Force to voltage conversion factor [V/N]
20-sim 4.6 Reference Manual
585
9. Library
DCMotor
Library
Iconic Diagrams\Electric\Actuators
Iconic Diagrams\Mechanical\Electric
Implementations
Default
IR
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric, Electric).
Description - Default
This models represents an ideal DC -motor with no energy loss. The electric port has
separate high and low terminals. The equations are
p1.i = p1_high.i = p1_low.i;
p1.u = p1_high.u - p1_low.u;
The model can have mixed forms of causality
p1.u = k * p2.omega;
p2.T = k * p1.i;
or:
p2.omega = p1.u / k;
p1.i = p2.T / k;
Interface - Default
Ports
Description
p1_high, p1_low
Both terminals of the Electric port p1.
p2
Rotation port.
Causality
mixed
See equations above.
Parameters
k
motor constant [Nm/A]
Description - IR
This models represents an ideal DC -motor with inductance and resistance.
20-sim 4.6 Reference Manual
586
9. Library
The electric port has separate high and low terminals. The equations are
p1.i = p1_high.i = p1_low.i;
p1.u = p1_high.u - p1_low.u;
Interface - IR
Ports
Description
p1_high, p1_low
Both terminals of the Electric port p1.
p2
Rotation port.
Causality
mixed
See equations above.
Parameters
k
motor constant [Nm/A]
L
motor inductance [H]
R
motor resistance [Ohm]
Components
Capacitor
Library
Iconic Diagrams\Electric\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric).
Description
This model represents an ideal capacitor. The element has a preferred voltage out
causality. The corresponding constitutive equations then contain an integration. The
element can also have the non-preferred current out causality. The constitutive
equations then contain a derivation. The port p of the inductor model has separate high
and low terminals. The equations are:
p.i = p_high.i = p_low.i;
p.u = p_high.u - p_low.u;
20-sim 4.6 Reference Manual
587
9. Library
voltage out causality (preferred):
p.u = (1/C)*int(p.i);
current out causality:
p.i = C * ddt(p.u);
Interface
Ports
Description
p_high, p_low
Both terminals of the Electric port p.
Causality
preferred voltage out
A current out causality results in a derivative
constitutive equation.
Parameters
C
capacitance [F]
Initial Values
p.u_initial
The initial charge of the capacitor [V].
CurrentSensor
Library
Iconic Diagrams\Electric\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric), Block Diagrams.
Description
This model translates a current to an output signal. It has a voltage out causality. The
port p of the model has separate high and low terminals. The equations are:
p.i = p_high.i = p_low.i;
p.u = p_high.u - p_low.u;
p.u = 0;
i = p.i;
Interface
Ports
Description
p_high, p_low
Both terminals of the Electric port p.
Causality
fixed voltage out
20-sim 4.6 Reference Manual
588
9. Library
Output
i
C urrent [A].
Diode
Library
Iconic Diagrams\Electric\C omponents
Implementations
Default
Exponential
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric).
Description - Default
This is an ideal electrical diode. The model is a switch which is open when the voltage
drop v < 0 and closed when the voltage drop v > 0. The heart of the model consist of a
resistance that is changed by the input voltage from almost zero (on) to a very large
value (off). By proper selection of the on and off resistances, they can be effectively
zero and infinity in comparison to other circuit elements. The port p of the diode model
has separate high and low terminals. The equations are:
p.i = p_high.i = p_low.i;
p.u = p_high.u - p_low.u;
voltage out causality:
R = if p.i > 0 then Ron else Roff end;
p.u = R * p.i;
current out causality:
R = if p.u > 0 then Ron else Roff end;
p.i = p.u / R;
Interface - Default
Ports
Description
p_high, p_low
Both terminals of the Electric port p.
Causality
indifferent p
Parameters
Ron
Resistance when diode is turned on [Ohm]
Roff
Resistance when diode is turned off [Ohm]
20-sim 4.6 Reference Manual
589
9. Library
Description - Exponential
This is an electrical diode described by an exponential expression. The port p of the
diode model has separate high and low terminals. The equations are:
p.i = p_high.i = p_low.i
p.u = p_high.u - p_low.u
uT = (k * T) / e;
p.i = Is * (exp (p.u / uT) - 1);
with k the Boltzmann constant (k = 1.380658e-23 {J/K}
Interface - Exponential
Ports
Description
p_high, p_low
Both terminals of the Electric port p.
Causality
indifferent p
Parameters
T
operating temperature [K]
Is
reverse saturation current [A]
DoubleSwitch
Library
Iconic Diagrams\Electric\C omponents
Implementations
Level
Amplitude
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric).
Description - Level
This model represents an almost ideal switch. The switch connects port p1 with p2 when
the input signal is larger than the threshold value vt and connects port p1 with p3 when
the input signal is smaller or equal to the threshold value vt.
The heart of the model consist of two resistances that can be changed by an input signal
from almost zero (on) to a very large value (off). By proper selection of the on and off
resistances, they can be effectively zero and infinity in comparison to other circuit
elements.
20-sim 4.6 Reference Manual
590
9. Library
Layout of the switch model.
The equations of the resistances are:
R = if input > vt then Ron else Roff end;
p.u = R * p.i;
Interface - Level
Ports
Description
p1, p2, p3
The electric ports (Electric).
input
The switching signal.
Causality
indifferent p1, p2,
p3
Parameters
R1\R
Ground resistance at port 1 [Ohm]
R2\R
Ground resistance at port 2 [Ohm]
R3\R
Ground resistance at port 3 [Ohm]
Resistance12\Ron Resistance between p1 and p2 when switch is turned on [Ohm]
Resistance12\Roff Resistance between p1 and p2 when switch is turned off [Ohm]
Resistance12\vt
Threshold value between p1 and p2, switch is turned on when input >
Resistance12\vt
Resistance13\Ron Resistance between p1 and p3 when switch is turned on [Ohm]
Resistance13\Roff Resistance between p1 and p3 when switch is turned off [Ohm]
Resistance13\vt
Threshold value between p1 and p3, switch is turned on when input >
Resistance13\vt
20-sim 4.6 Reference Manual
591
9. Library
Description - Amplitude
This model represents an almost ideal switch. The switch connects port p1 with p2 when
the absolute value of the input signal is larger than the threshold value Resistance12
\vt and connects port p1 with p3 when the absolute value of the input signal is smaller
or equal to the threshold value Resistance13\vt.
The heart of the model consist of two resistances that can be changed by an input signal
from almost zero (on) to a very large value (off). By proper selection of the on and off
resistances, they can be effectively zero and infinity in comparison to other circuit
elements.
Layout of the switch model.
The equations of the resistances are:
R = if abs(input) > vt then Ron else Roff end;
p.u = R * p.i;
Interface - Amplitude
Ports
Description
p1, p2, p3
The electric ports (Electric).
input
The switching signal.
Causality
indifferent p1, p2,
p3
Parameters
R1\R
Ground resistance at port 1 [Ohm]
R2\R
Ground resistance at port 2 [Ohm]
R3\R
Ground resistance at port 3 [Ohm]
Resistance12\Ron Resistance between p1 and p2 when switch is turned on [Ohm]
Resistance12\Roff Resistance between p1 and p2 when switch is turned off [Ohm]
Resistance12\vt
20-sim 4.6 Reference Manual
592
9. Library
Threshold value between p1 and p2, switch is turned on when
abs(input) > Resistance12\vt
Resistance13\Ron Resistance between p1 and p3 when switch is turned on [Ohm]
Resistance13\Roff Resistance between p1 and p3 when switch is turned off [Ohm]
Resistance13\vt
Threshold value between p1 and p3, switch is turned on when
abs(input) > Resistance13\vt
Note
To get a simple switching behavior, pay attention to chose the parameters Resistance12
\vt and Resistance13\vt equal. When these parameters are not chosen equal a more
complex switching behavior can be obtained.
Ground
Library
Iconic Diagrams\Electric\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric).
Description
This model represents the ground (voltage = 0). The model has only one initial port p
defined. Because any number of connections can be made, successive ports are named
p1, p2, p3 etc. which gives the constitutive equations:
p1.u = p2.u = .. = pn.u = 0;
p1.i = free; p2.i = free; ..; pn.i = free;
Interface
Ports
Description
p [any]
Any number of connections can be made (Electric).
Causality
Fixed voltage out All ports have a fixed voltage out causality.
20-sim 4.6 Reference Manual
593
9. Library
Inductor
Library
Iconic Diagrams\Electric\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric).
Description
This model represents an ideal electrical inductance. The element has a preferred
current out causality. The corresponding constitutive equations then contain an
integration. The element can also have the non-preferred voltage out causality. The
constitutive equations then contain a derivation. The port p of the inductor model has
separate high and low terminals. The equations are:
p.i = p_high.i = p_low.i;
p.u = p_high.u - p_low.u;
current out causality (preferred):
p.i = (1/L)int(p.u);
voltage out causality:
p.u = L * ddt(p.i);
Interface
Ports
Description
p_high, p_low
Both terminals of the Electric port p.
Causality
preferred current out
An voltage out causality results in a derivative
constitutive equation.
Parameters
L
Inductance [H]
Initial Values
p.i_initial
The initial flux in the inductor.
20-sim 4.6 Reference Manual
594
9. Library
Node
Library
Iconic Diagrams\Electric\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric).
Description
This node model represents a structural connection between two or more branches of an
electrical circuit. The model has only one initial port p defined. Because any number of
connections can be made, successive ports are named p1, p2, p3 etc.
Interface
Ports
Description
p [any]
Any number of connections can be made.
OpAmp
Library
Iconic Diagrams\Electric\C omponents
Implementations
Default
Universal
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric).
Description - Default
This model represents an ideal operational amplifier. The input resistance is infinite and
the output resistance is zero. The port p_in of the OpAmp model has separate high and
low terminals:
p_in.u = p_in_high.u - p_in_low.u;
p_in_high.i = p_in_low.i = p_in.i = 0;
p_out.u = A*p_in.u;
Interface - Default
Ports
Description
p_in_high,
Both terminals of the input port p_in (Electric).
P_in_low
Output port (Electric).
p_out
Causality
20-sim 4.6 Reference Manual
595
9. Library
fixed current out
p_in
fixed voltage out
p_out
Parameters
A
Amplification []
Description - Universal
This model represents an operational amplifier with a first order decreasing voltage
amplification.
The amplification is parameterized by a DC -gain (A) and a cut-off frequency (f). This
yields a unity gain frequency of:
unity gain frequency = A*f;
The gain is limited to yield an output that is between the positive (VDD) and negative
(VEE) supply voltage.
20-sim 4.6 Reference Manual
596
9. Library
The input resistance is infinite and the output resistance is equal to the parameter R.
The port p_in of the OpAmp model has separate high and low terminals:
p_in.u = p_in_high.u - p_in_low.u
p_in_high.i = p_in_low.i = p_in.i = 0;
p_out.u = Adiff*p_in.u - R*p_out.u;
where Adiff is a dynamic gain according to the bode and gain plot.
Interface - Universal
Ports
Description
p_in_high,
Both terminals of the input port p_in (Electric).
P_in_low
Output port (Electric).
p_out
Causality
fixed current out
p_in
preferred voltage
out p_out
Parameters
A
DC gain or DC Amplification
f
C ut-off frequency [Hz]
VDD
Positive supply voltage [V], choose VDD > VEE!
VEE
Negative supply voltage [V], choose VDD > VEE!
R
Output impedance [Ohm]
20-sim 4.6 Reference Manual
597
9. Library
Potentiometer
Library
Iconic Diagrams\Electric\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric).
Description
This model represents an ideal potentiometer.
It can have various forms of causality. The equations are:
R1 = (1 - alpha) * R;
R2 = alpha * R;
p_high.u - p_var.u = p_high.i * R1;
p_var.u - p_low.u = p_low.i * R2;
p_high.i + p_var.i = p_low.i;
where alpha denotes the position of the indicator and can vary from zero to one.
Interface
Ports
Description
p_high, p_low
Both terminals of the resistor.
p_var
Indicator terminal.
Causality
indifferent
Parameters
R
Resistance [Ohm].
alpha
Indicator position (0 <= alpha <= 1).
20-sim 4.6 Reference Manual
598
9. Library
Rectifier
Library
Iconic Diagrams\Electric\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric).
Description
This model represents an diode bridge rectifier consisting of a set four diodes. Given an
alternating input current, the bridge produces an output current which is always
positively oriented and has the same amplitude as the input current. The bridge behavior
is ideal. No diode characteristics are implemented and no power is dissipated.
A circuit with a diode bridge rectifier.
Interface
Ports
Description
p1_high, p1_low
Both terminals of the Electric input port p1.
p2_high, p2_low
Both terminals of the Electric output port p2.
Causality
p1 not equal p2
Resistor
Library
Iconic Diagrams\Electric\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric).
Description
This model represents an ideal electrical resistor. It can have an voltage out as well as a
current out causality. In the last case the constitutive equation, as shown below, is
simply inverted. The port p of the damper model has separate high and low terminals.
The equations are:
20-sim 4.6 Reference Manual
599
9. Library
p.i = p_high.i = p_low.i;
p.u = p_high.u - p_low.u;
Voltage out causality:
p.u = R * p.i;
C urrent out causality:
p.i = p.u / R;
Interface
Ports
Description
p_high, p_low
Both terminals of the Electric port p.
Causality
indifferent
Parameters
R
Resistance [Ohm].
Switch
Library
Iconic Diagrams\Electric\C omponents
Implementations
Level
Amplitude
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric).
Description - Level
This model represents an almost ideal switch. The switch is turned on when the input
signal is larger than the threshold value vt and it is turned off when the input signal is
smaller or equal to the threshold value vt.
The heart of the model consist of a resistance that can be changed by an input signal
from almost zero (on) to a very large value (off). By proper selection of the on and off
resistances, they can be effectively zero and infinity in comparison to other circuit
elements.
20-sim 4.6 Reference Manual
600
9. Library
Layout of the switch model.
The equations of the resistance are:
R = if input > vt then Ron else Roff end;
p.u = R * p.i;
Interface - Level
Ports
Description
p1, p2
Both electric ports (Electric).
input
The switching signal.
Causality
indifferent p1, p2
Parameters
R1\R
Ground resistance at port 1 [Ohm]
R2\R
Ground resistance at port 2 [Ohm]
Resistance12\Ron Resistance when switch is turned on [Ohm]
Resistance12\Roff Resistance when switch is turned off [Ohm]
Resistance12\vt
Threshold value, switch is turned on when input > vt
Description - Amplitude
This model represents an almost ideal switch. The switch is turned on when the
amplitude of the input signal is larger than the threshold value vt and it is turned off
when the amplitude of the input signal is smaller or equal to the threshold value vt.
The heart of the model consist of a resistance that can be changed by an input signal
from almost zero (on) to a very large value (off). By proper selection of the on and off
resistances, they can be effectively zero and infinity in comparison to other circuit
elements.
20-sim 4.6 Reference Manual
601
9. Library
Layout of the switch model.
The equations of the resistance are:
R = if abs(input) > vt then Ron else Roff end;
p.u = R * p.i;
Interface - Amplitude
Ports
Description
p1, p2
Both electric ports (Electric).
input
The switching signal.
Causality
indifferent p1,p2
Parameters
R1\R
Ground resistance at port 1 [Ohm]
R2\R
Ground resistance at port 2 [Ohm]
Resistance12\Ron Resistance when switch is turned on [Ohm]
Resistance12\Roff Resistance when switch is turned off [Ohm]
Resistance12\vt
Threshold value, switch is turned on when abs(input) > vt
Transformer
Library
Iconic Diagrams\Electric\C omponents
Implementations
Default
Induction
20-sim 4.6 Reference Manual
602
9. Library
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric).
Description - Default
This models represents an ideal transformer. The transformer does not have internal
resistors, capacitance or inductance. The causality of this model is always mixed: one
port has a voltage causality while the other has a current out causality:
p_1.u = n * p_2.u;
p_2.i = n * p_1.i;
or:
p_2.u = 1/n * p_1.u;
p_1.i = 1/n * p_2.i;
Interface - Default
Ports
Description
p_1,p_2
Electrical ports
Causality
p_small notequal
p_large
Parameters
n
turns ratio []
Description - Induction
This models represents a transformer with inductance and mutual inductance. The
equations are:
p_1.u = L1 * ddt(p_1.i) + M * ddt(p_2.i);
p_2.u = M * ddt(p_1.i) + L2 * ddt(p_2.i);
Interface - Induction
Ports
Description
p_1,p_2
Electrical ports
Causality
indifferent
Parameters
L1
Primary inductance [H]
L2
Secondary Inductance [H]
M
C oupling Inductance [H]
20-sim 4.6 Reference Manual
603
9. Library
VoltageSensor
Library
Iconic Diagrams\Electric\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric), Block Diagrams.
Description
This model translates a voltage difference to an output signal. It has a current out
causality. The port p of the model has separate high and low terminals. The equations
are:
p.i = p_high.i = p_low.i;
p.u = p_high.u - p_low.u;
p.i = 0;
u = p.u;
Interface
Ports
Description
p_high, p_low
Both terminals of the Electric port p.
Causality
fixed current out
Output
u
Voltage [V].
Sources
ControlledCurrentSource
Library
Iconic Diagrams\Electric\Sources
Implementations
Voltage
C urrent
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric).
Description - Voltage
This model represents an ideal voltage controlled current source. Both ports of the
model have separate high and low terminals:
20-sim 4.6 Reference Manual
604
9. Library
p_in.u = p_in_high.u - p_in_low.u;
p_in_high.i = p_in_low.i = p_in.i;
p_out.u = p_out_high.u - p_out_low.u = 0
p_out_high.i = p_out_low.i = p_in.i;
The equations of this model are:
p_in.i = 0;
p_out.i = p_in.u;
p_out.u = indifferent;
Interface - Voltage
Ports
Description
p_in_high,
Both terminals of the input port p_in (Electric).
P_in_low
Both terminals of the output port p_out (Electric).
p_out_high,
P_out_low
Causality
fixed current out
p_in
fixed current out
p_out
Description - Current
This model represents an ideal current controlled current source. Both ports of the
model have separate high and low terminals:
p_in.u = p_in_high.u - p_in_low.u;
p_in_high.i = p_in_low.i = p_in.i;
p_out.u = p_out_high.u - p_out_low.u = 0
p_out_high.i = p_out_low.i = p_in.i;
The equations of this model are:
p_in.u = 0;
p_out.i = p_in.i;
p_out.u = indifferent;
Interface - Current
Ports
Description
p_in_high,
Both terminals of the input port p_in (Electric).
P_in_low
Both terminals of the output port p_out (Electric).
p_out_high,
P_out_low
20-sim 4.6 Reference Manual
605
9. Library
Causality
fixed voltage out
p_in
fixed current out
p_out
ControlledVoltageSource
Library
Iconic Diagrams\Electric\Sources
Implementations
Voltage
C urrent
PI
KP
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric).
Description - Voltage
This model represents an ideal voltage controlled voltage source. Both ports of the
model have separate high and low terminals:
p_in.u = p_in_high.u - p_in_low.u;
p_in_high.i = p_in_low.i = p_in.i;
p_out.u = p_out_high.u - p_out_low.u = 0
p_out_high.i = p_out_low.i = p_in.i;
The equations of this model are:
p_in.i = 0;
p_out.u = p_in.u;
p_out.i = indifferent;
Interface - Voltage
Ports
Description
p_in_high,
Both terminals of the input port p_in (Electric).
P_in_low
Both terminals of the output port p_out (Electric).
p_out_high,
P_out_low
Causality
fixed current out
p_in
20-sim 4.6 Reference Manual
606
9. Library
fixed voltage out
p_out
Description - Current
This model represents an ideal current controlled voltage source. Both ports of the
model have separate high and low terminals:
p_in.u = p_in_high.u - p_in_low.u;
p_in_high.i = p_in_low.i = p_in.i;
p_out.u = p_out_high.u - p_out_low.u = 0
p_out_high.i = p_out_low.i = p_in.i;
The equations of this model are:
p_in.u = 0;
p_out.u = p_in.i;
p_out.i = indifferent;
Interface - Current
Ports
Description
p_in_high,
Both terminals of the input port p_in (Electric).
P_in_low
Both terminals of the output port p_out (Electric).
p_out_high,
P_out_low
Causality
fixed voltage out
p_in
fixed voltage out
p_out
Description - PI
This model represents a voltage controlled voltage source. The output voltage is
connected to the input voltage through a PI-controller and limited to a maximum and
minimum value of ±Vmax. The output voltage is subjected to an output resistance R.
Both ports of the model have separate high and low terminals:
20-sim 4.6 Reference Manual
607
9. Library
p_in.u = p_in_high.u - p_in_low.u;
p_in_high.i = p_in_low.i = p_in.i;
p_out.u = p_out_high.u - p_out_low.u = 0
p_out_high.i = p_out_low.i = p_in.i;
Interface - PI
Ports
Description
p_in_high,
p_in_low
Both terminals of the input port p_in (Electric).
p_out_high,
p_out_low
Both terminals of the output port p_out (Electric).
Causality
fixed current out
p_in
fixed voltage out
p_out
Parameters
Kp
f
Vmax
R
Proportional gain []
Integration frequency [Hz]
Maximum output voltage [V]
Output resistance [Ohm]
Description - KP
This model represents a voltage controlled voltage source. The output voltage is
proportional to the input voltage and is limited to a maximum and minimum value of
±Vmax. The output voltage is subjected to an output resistance R.
Both ports of the model have separate high and low terminals:
p_in.u = p_in_high.u - p_in_low.u;
p_in_high.i = p_in_low.i = p_in.i;
p_out.u = p_out_high.u - p_out_low.u = 0
p_out_high.i = p_out_low.i = p_in.i;
20-sim 4.6 Reference Manual
608
9. Library
Interface - KP
Ports
Description
p_in_high,
Both terminals of the input port p_in (Electric).
p_in_low
p_out_high,
Both terminals of the output port p_out (Electric).
p_out_low
Causality
fixed current out
p_in
fixed voltage out
p_out
Parameters
Kp
Proportional gain []
Vmax
Maximum output voltage [V]
R
Output resistance [Ohm]
CurrentSource
Library
Iconic Diagrams\Electric\Sources
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric).
Description
This model represents an ideal current source with a constant current. The current can
be set to a certain constant value, the voltage is indifferent. The port p of the model has
separate high and low terminals. The equations are:
p.i = p_high.i = p_low.i;
p.u = p_high.u - p_low.u;
p.u = indifferent;
p.i = i;
Interface
Ports
Description
p_low, p_high
Both terminals of the Electric port p.
Causality
fixed current out
Parameters
i
C urrent [A].
20-sim 4.6 Reference Manual
609
9. Library
ModulatedCurrentSource
Library
Iconic Diagrams\Electric\Sources
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric), Block Diagrams.
Description
This model represents an ideal current source with a variable current. The current can
be set to a (fluctuating) value given by the input signal i, the voltage is indifferent.
p.i = i;
Interface
Ports
Description
p
Electric port.
Causality
fixed current out
Input
i
C urrent [A].
ModulatedVoltageSource
Library
Iconic Diagrams\Electric\Sources
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric), Block Diagrams.
Description
This model represents an ideal voltage source with a variable voltage. The voltage can
be set to a (fluctuating) value given by the input signal u, the current is indifferent.
p.u = u;
Interface
Ports
Description
p
Electric port.
Causality
20-sim 4.6 Reference Manual
610
9. Library
fixed voltage out
Input
u
Voltage [V].
VoltageSource
Library
Iconic Diagrams\Electric\Sources
Implementations
DC
AC
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric).
Description - DC
This model represents an ideal voltage source with a constant voltage. The voltage can
be set to a certain constant value, the current is indifferent. The port p of the model has
separate high and low terminals. The equations are:
p.i = p_high.i = p_low.i;
p.u = p_high.u - p_low.u;
p.i = indifferent;
p.u = u;
Interface - DC
Ports
Description
p
Both terminals of the Electric port p.
Causality
fixed voltage out
Parameters
u
Voltage [V].
Description - AC
This model represents an ideal voltage source with a sinusoidal voltage. The voltage can
be set to a certain constant value, the current is indifferent. The port p of the model has
separate high and low terminals. The equations are:
20-sim 4.6 Reference Manual
611
9. Library
p.i = p_high.i = p_low.i;
p.u = p_high.u - p_low.u;
p.i = indifferent;
p.u = U*sin(2*pi*f*time);
Interface - AC
Ports
Description
p
Both terminals of the Electric port p.
Causality
fixed voltage out
Parameters
U
Voltage amplitude [V].
f
Voltage frequency [Hz]
9.2.3
Hydraulics
Hydraulics
The 20-sim Hydraulics library contains components to model the dynamic behavior of
hydraulic circuits. Most components have lumped volumes to ensure a seamless
connection with other components. Therefore almost all components can be connected
arbitrarily. C are has to be taken that physically relevant circuits are created.
The elementary components (without lumped volumes) are stored in the basic libraries.
These models should only be used by experienced modelers who want to create their
own library components.
Hydraulic components can easily be coupled to other library models. The pumps and
motors have a rotation port that can be coupled to models of the Rotation library. The
cylinder models have a translation port that can be coupled to models of the Translation
library. Some models have a variable input that can be coupled to models of the Signal
library.
To get a good impression of the use the components of this library, have a look at the
example circuits.
Ports
Every library component has one or more hydraulic connectors, which are called ports in
20-sim. Ports always have two variables: pressure [Pa] and volume flow [m3/s]. The
following ports a and b are usually provided:
a
20-sim 4.6 Reference Manual
612
9. Library
a.p
Pressure in [Pa] with respect to atmospheric pressure (p stands for
pressure).
a.phi
Volume flow [m3/s], positive if oil is entering the component at port a
(phi stands for flow).
b
b.p
Pressure in [Pa] with respect to atmospheric pressure (p stands for
pressure).
b.phi
Volume flow [m3/s], negative if oil is entering the component at port b
(phi stands for flow).
Pressure
The 20-sim hydraulics library uses the common definition of pressure in Pa:
1 Pa = 1 N/m2 = 1e-5 bar
The air pressure at sea level is taken as the zero value:
0 Pa = air pressure
C onsequently the pressure for liquid oil that starts to vaporize is negative. In 20-sim the
default value of the vapour pressure is:
p_vapour = -0.999e5 Pa
The vapour pressure is the minimum pressure. Some models have a safeguard on the
pressure to prevent it to become smaller. You can change the value of the vapour
pressure but take care that always a value is chosen that is smaller than zero. Otherwise
some of the models will not work correctly.
Bulk modulus
No liquid is fully incompressible. The compliance characteristics of the oil in a hydraulic
system is a vital parameters affecting the response. The effect of compressibility is
incorporated by entering the bulk modulus of the fluid:
dp = -B*dV/V
Here dp is the pressure , V the volume and B the bulk modulus. For small pressure
variations the compressibility effect my be rewritten as:
p = B/V*int(flow)
The bulk modulus is a very uncertain parameter. It depends on the percentage of air
dissolved in the fluid, the pressure and the temperature. In most textbooks a values of
1.5 to 1.75 [GPa] is used. 20-sim uses a default value of 1.6 [GPa]. If fluid should be
simulated at elevated temperatures or with a high percentage or air dissolved, you
should use a smaller value for the bulk modulus.
20-sim 4.6 Reference Manual
613
9. Library
Units
20-sim uses SI-units for the hydraulic components. If you want to use other units select
them in the Parameters Editor or the Variables C hooser.
Laminar flow
Many hydraulic models have a laminar (leakage) flow:
flow = G * dp
with G the flow conductance and dp the pressure difference. The table below shows the
flow rates for various conductance values and pressure differences of 10 [bar] and 400
[bar].
G
P
P
flow
flow
m3/s.Pa
Pa
bar
m3/s
l/min
1.0e-14
1.0e6
10
2.89e-8
0.002
1.0e-14
4.0e7
400
1.82e-7
0.01
1.0e-12
1.0e6
10
1.44e-6
0.09
1.0e-12
4.0e7
400
9.12e-6
0.6
1.0e-10
1.0e6
10
1.44e-4
9
1.0e-10
4.0e7
400
9.12e-4
55
1.0e-8
1.0e6
10
2.89e-3
173
1.0e-8
4.0e7
400
1.82e-2
1095
If the flow rate is very small (leakage flow), choose G below 1.0e-14 [m3/s.Pa]. If the
flow rate is very large (open connection to a tank), choose G 1.0e-9 or higher if desired.
Turbulent flow
Some hydraulic models have a turbulent (orifice) flow described by:
flow = Cd * A * sqrt( 2/ rho * dp)
with Cd the discharge coefficient, A the orifice area, rho the fluid density and dp the
pressure difference. Except for small pressure around zero, the discharge coefficient is
constant. In most textbooks a value of 0.6 is recommended. The table below shows the
flow rates for various orifice areas and pressure differences of 10 [bar] and 400 [bar].
Cd
A
rho
dp
dp
flow
flow
m3/s.Pa
m2
kg/m3
Pa
bar
m3/s
l/min
0.6
1.0e-9
865
1.0e6
10
1.0e-8
0.0006
0.6
1.0e-9
865
4.0e7
400
4.0e-7
0.024
20-sim 4.6 Reference Manual
614
9. Library
0.6
5.0e-8
865
1.0e6
10
1.0e-6
0.06
0.6
5.0e-8
865
4.0e7
400
4.0e-5
2.4
0.6
5.0e-6
865
1.0e6
10
1.0e-4
6
0.6
5.0e-6
865
4.0e7
400
4.0e-3
240
0.6
1.0e-4
865
1.0e6
10
1.0e-2
600
0.6
1.0e-4
865
4.0e7
400
4.0e-1
24000
If the flow rate is very small (leakage flow) choose A smaller than 1.0e-9 [m2]. If the
flow rate should be very large (open connection) choose A equal to 1.0e-4 or higher if
desired. For very small pressure differences the flow will become laminar and the
discharge coefficient will drop. For such cases, specialized models should be applied. If
they are not available, use a laminar flow model with a small conductance value.
Simulation
Hydraulic circuits can be simulated with all the available integration methods. In practice
the default integration method (BDF) will give the most accurate and quickest response.
Take care with hydraulic circuits that will give high pressure peaks and small flow rates.
These circuits are sometimes hard to simulate. In practice high pressure peaks should
be reduced with pressure relief valves to avoid damage. Fortunately adding pressure
relief valves will in most cases improve the simulation response.
Disclaimer
All models have been tested with standard configurations. This will however not ensure
that valid results will be found at all times. For example temperature effects are not
included and certain parameter values will lead to unstable simulations. Therefore any
application of the library without validation of the user is at its own risk!
Literature
The 20-sim hydraulic library has been based on the following literature:
P. Dransfield, Hydraulic C ontrol Systems - Design and Analysisi of Their Dynamics,
Springer 1981,ISBN 3-540-10890-4.
P. Beater, Entwurf Hydraulischer Maschinen, Modelbildung, Stabilitätsanalyse und
Simulation hydrostatischer Antriebe und Steurungen, Springer 1999, ISBN 3-540-654445.
The models have been designed as close as possible to the Modelica hydraulic library
(www.modelica.org). To compare both libraries the example model C losed C ircuit Drive
Train.emx has been added.
20-sim 4.6 Reference Manual
615
9. Library
Components
HydraulicInertia
Library
Iconic Diagrams\Hydraulics\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
When a fluid flow changes speed, a force is needed to accelerate the fluid. This force is
equal to the acceleration multiplied by the mass of the fluid.
F = m * dv/dt
The fluid mass is equal to the pipe area multiplied by the pipe length and the fluid
density:
m = A * l * rho
The force will result in a pressure differential:
F = A * dp = A * (pa.p - pb.p)
We can rewrite the formulas as
dp = rho * l * dv/dt
and by introducing the fluid flow phi:
v = phi/A
we get the formula for an hydraulic inertia:
dp = (rho * l / A) * d phi/dt
Interface
Ports
Description
pa, pb
Both terminals of the hydraulic inertia.
Causality
fixed pressure out
pa
20-sim 4.6 Reference Manual
616
9. Library
fixed pressure out
pb
Parameters
rho
Mass density of the fluid [kg/m3].
d
pipe diameter [m]
l
pipe length [m]
Node
Library
Iconic Diagrams\Hydraulics\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric).
Description
This node model represents a connection between two or more lines of an hydraulic
circuit. The model has only one initial port p defined. Because any number of
connections can be made, successive ports are named p1, p2, p3 etc.
Interface
Ports
Description
p [any]
Any number of connections can be made.
20-sim 4.6 Reference Manual
617
9. Library
Cylinders
Basic Cylinders
Cylinder
Library
Iconic Diagrams\Hydraulics\C ylinders\Basic C ylinders
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics/Translational).
Description
This is an ideal model of cylinder with no mass and no friction. The volume of the
chambers is given by:
Va = Vdead + Aa*(x + x_initial)
Vb = Vdead + Ab*(stroke - x - x_initial)
with Aa the piston area and Ab the effective area at the rod side. x is the piston position
and Vdead the initial volume when piston position is zero. The piston areas Aa and Ab
are related to the piston diameter dp and rod diameter dr by:
Aa = pi * dp^2 / 4
Ab = pi * dp^2 / 4 - pi * dr^2 / 4
There is no restriction on the travel of the piston. Only a warning is given when the
maximum stroke is exceeded or the piston position gets negative.
Interface
Ports
Description
20-sim 4.6 Reference Manual
618
9. Library
pa, pb
hydraulic port
pm
translation port
Causality
preferred pressure out pa
preferred force out pm
Parameters
Vdead
rest volume of oil in cylinder chamber when closed [N.s/
B
m]
stroke
effective bulk modulus [Pa]
x_initial
stroke length [m]
dp
starting position of piston [m]
dr
piston diameter [m]
rod diameter [m]
CylinderSpringReturn
Library
Iconic Diagrams\Hydraulics\C ylinders\Basic C ylinders
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics/Translational).
Description
This is an ideal model of a single acting cylinder with no mass and no friction and a
return spring to drive the cylinder back when there is no pressure in the chamber. The
volume of the chamber is given by:
V = Vdead + Aa*(x + x_initial)
with Aa the piston area, x the piston position and Vdead the initial volume when piston
position is zero. The piston area Aa is related to the piston diameter dp by:
20-sim 4.6 Reference Manual
619
9. Library
Aa = pi * dp^2 / 4
The driving force of the return spring is determined by two parameters: the force for
piston position zero (Fspr_min) and the force when the piston is at the other side
(Fspr_max). The spring constant (kspr) and initial spring position (x0) are calculated out
of these parameters by:
kspr = (Fspr_max - Fspr_min)/stroke
x0 = -Fspr_min/kspr
There is no restriction on the travel of the piston. Only a warning is given when the
maximum stroke is exceeded or the piston position gets negative.
Interface
Ports
Description
pa
hydraulic port
pm
translation port
Causality
preferred pressure out pa
preferred force out pm
Parameters
Vdead
rest volume of oil in cylinder chamber when closed [N.s/
B
m]
stroke
effective bulk modulus [Pa]
x_initial
stroke length [m]
dp
starting position of piston [m]
Fspr_min
piston diameter [m]
Fspr_max
minimum return spring force (at x = 0) [N]
maximum return spring force (at x = stroke) [N]
20-sim 4.6 Reference Manual
620
9. Library
CylinderChamberA
Library
Iconic Diagrams\Hydraulics\C ylinders\Basic C ylinders
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics/Translational).
Description
This is an ideal model of a single acting cylinder with no mass and no friction. The
volume of the chamber is given by:
V = Vdead + Aa*(x + x_initial)
with Aa the piston area, x the piston position and Vdead the initial volume when piston
position is zero. The piston area Aa is related to the piston diameter dp by:
Aa = pi * dp^2 / 4
There is no restriction on the travel of the piston. Only a warning is given when the
maximum stroke is exceeded or the piston position gets negative.
Interface
Ports
Description
pa
hydraulic port
pm
translation port
Causality
preferred pressure out pa
preferred force out pm
Parameters
20-sim 4.6 Reference Manual
621
9. Library
Vdead
rest volume of oil in cylinder chamber when closed [N.s/
B
m]
stroke
effective bulk modulus [Pa]
x_initial
stroke length [m]
dp
starting position of piston [m]
piston diameter [m]
CylinderChamberB
Library
Iconic Diagrams\Hydraulics\C ylinders\Basic C ylinders
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics/Translational).
Description
This is an ideal model of a single acting cylinder with no mass and no friction. The
volume of the chamber is given by:
V = Vdead + Aa*(x + x_initial)
with Aa the piston area, x the piston position and Vdead the initial volume when piston
position is zero. The piston area Aa is related to the piston diameter dp by:
Aa = pi * dp^2 / 4
There is no restriction on the travel of the piston. Only a warning is given when the
maximum stroke is exceeded or the piston position gets negative.
20-sim 4.6 Reference Manual
622
9. Library
Interface
Ports
Description
pa
hydraulic port
pm
translation port
Causality
preferred pressure out pa
preferred force out pm
Parameters
Vdead
rest volume of oil in cylinder chamber when closed [N.s/
B
m]
stroke
effective bulk modulus [Pa]
x_initial
stroke length [m]
dp
starting position of piston [m]
piston diameter [m]
CylinderDouble
Library
Iconic Diagrams\Hydraulics\C ylinders
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics/Translational).
Description
This is the extended model of a double acting cylinder with mass, friction and end stops.
20-sim 4.6 Reference Manual
623
9. Library
The volume of the chambers is given by:
Va = Vdead + Aa*(x + x_initial)
Vb = Vdead + Ab*(stroke - x - x_initial)
with Aa the piston area and Ab the effective area at the rod side. x is the piston position
and Vdead the initial volume when piston position is zero. The piston areas Aa and Ab
are related to the piston diameter dp and rod diameter dr by:
Aa = pi * dp^2 / 4
Ab = pi * dp^2 / 4 - pi * dr^2 / 4
The travel of the piston is restricted. At the cylinder heads two collision models prevent
the piston from traveling any further. The friction between the piston and the cylinder
walls is modeled by static and viscous friction.
Interface
Ports
Description
pa, pb
hydraulic ports
p_barrel, p_rod
translation ports
Causality
preferred pressure out pa
preferred force out pm
Parameters
Vdead
rest volume of oil in cylinder chamber when closed, [m3]
20-sim 4.6 Reference Manual
624
9. Library
B
effective bulk modulus [Pa]
stroke
stroke length [m]
x_initial
starting position of piston [m]
dp
piston diameter [m]
dr
rod diameter [m]
m_barrel
barrel mas [kg]
m_rod
rod and piston mass [kg]
kc
stiffness during collision with cylinder heads [N/m]
dc
damping during collision with cylinder heads [N.s/m]
Fc
static friction [N]
dv
viscous friction coefficient [N.s/m]
slope
steepness of the static friction curve []
Note
When a the cylinder piston collides with the cylinder heads, simulation may get very slow
or even become unstable. In these cases you are advised to use the BDF-method with
default settings. Try to change the absolute integration error until a stable simulation is
obtained!
CylinderSingleSpringReturn
Library
Iconic Diagrams\Hydraulics\C ylinders
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics/Translational).
Description
This is the extended model of a single acting cylinder with mass, friction, end stops and
a return spring to drive the cylinder back when there is no pressure in the chamber.
20-sim 4.6 Reference Manual
625
9. Library
The volume of the chamber is given by:
V = Vdead + Aa*(x + x_initial)
with Aa the piston area, x the piston position and Vdead the initial volume when piston
position is zero. The piston area Aa is related to the piston diameter dp by:
Aa = pi * dp^2 / 4
The driving force of the return spring is determined by two parameters: the force for
piston position zero (Fspr_min) and the force when the piston is at the other side
(Fspr_max). The spring constant (kspr) and initial spring position (x0) are calculated out
of these parameters by:
kspr = (Fspr_max - Fspr_min)/stroke
x0 = -Fspr_min/kspr
The travel of the piston is restricted. At the cylinder heads two collision models prevent
the piston from traveling any further. The friction between the piston and the cylinder
walls is modeled by static and viscous friction.
Interface
Ports
Description
pa
hydraulic port
p_barrel, p_rod
translation ports
Causality
20-sim 4.6 Reference Manual
626
9. Library
preferred pressure out pa
preferred force out pm
Parameters
Vdead
rest volume of oil in cylinder chamber when closed [m3]
B
effective bulk modulus [Pa]
stroke
stroke length [m]
x_initial
starting position of piston [m]
dp
piston diameter [m]
m_barrel
barrel mass [kg]
m_rod
rod and piston mass [kg]
kc
stiffness during collision with cylinder heads [N/m]
dc
damping during collision with cylinder heads [N.s/m]
Fc
static friction [N]
dv
viscous friction coefficient [N.s/m]
slope
steepness of the static friction curve []
Note
When a the cylinder piston collides with the cylinder heads, simulation may get very slow
or even become unstable. In these cases you are advised to use the BDF-method with
default settings. Try to change the absolute integration error until a stable simulation is
obtained!
CylinderSingle
Library
Iconic Diagrams\Hydraulics\C ylinders
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics/Translational).
Description
This is the extended model of a single acting cylinder with mass, friction and end stops.
20-sim 4.6 Reference Manual
627
9. Library
The volume of the chamber is given by:
V = Vdead + Aa*(x + x_initial)
with Aa the piston area, x the piston position and Vdead the initial volume when piston
position is zero. The piston area Aa is related to the piston diameter dp by:
Aa = pi * dp^2 / 4
The travel of the piston is restricted. At the cylinder heads two collision models prevent
the piston from traveling any further. The friction between the piston and the cylinder
walls is modeled by static and viscous friction.
Interface
Ports
Description
pa
hydraulic port
p_barrel, p_rod
translation ports
Causality
preferred pressure out pa
preferred force out pm
Parameters
Vdead
rest volume of oil in cylinder chamber when closed [m3]
B
effective bulk modulus [Pa]
stroke
stroke length [m]
20-sim 4.6 Reference Manual
628
9. Library
x_initial
starting position of piston [m]
dp
piston diameter [m]
m_barrel
barrel mass [kg]
m_rod
rod and piston mass [kg]
kc
stiffness during collision with cylinder heads [N/m]
dc
damping during collision with cylinder heads [N.s/m]
Fc
static friction [N]
dv
viscous friction coefficient [N.s/m]
slope
steepness of the static friction curve []
Note
When a the cylinder piston collides with the cylinder heads, simulation may get very slow
or even become unstable. In these cases you are advised to use the BDF-method with
default settings. Try to change the absolute integration error until a stable simulation is
obtained!
Pumps
Basic Pumps
DisplacementMotor
Library
Iconic Diagrams\Hydraulics\Pumps\Basic Pumps
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes an ideal motor with an axial speed that is proportional to the input
flow rate:
pa.phi = pb.phi = i * p_rot.omega;
i = D / (2*pi);
The torque is equal to:
p.T = i*(pa.p - pb.p);
If the port pressure is smaller than the vapour pressure (p < p_vapour), the flow is
zero. If the port pressure becomes larger than the vapour pressure the flow gradually
grows to its normal value, until the atmospheric pressure (p = 0) is reached.
Interface
Ports
Description
pa
inlet port (hydraulic)
20-sim 4.6 Reference Manual
629
9. Library
pb
outlet port (hydraulic)
p_rot
axis (rotation)
Causality
fixed volume flow
out pa
fixed volume flow
out pb
fixed torque
out
p_rot
Parameters
D
displacement per revolution [m3]
DisplacementPump
Library
Iconic Diagrams\Hydraulics\Pumps\Basic Pumps
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes an ideal pump with a displacement that is proportional to the speed
of the input axis:
pa.phi = pb.phi = i * p_rot.omega;
i = D / (2*pi);
The torque is equal to:
p.T = i*(pa.p - pb.p);
If the inlet pressure is smaller than the vapour pressure(p < p_vapour), the flow is zero.
If the inlet pressure is larger than the vapour pressure the flow gradually grows to its
normal value, until the atmospheric pressure (p = 0) is reached.
Interface
Ports
Description
pa
inlet port (hydraulic)
pb
outlet port (hydraulic)
p_rot
axis (rotation)
Causality
fixed volume flow
out pa
20-sim 4.6 Reference Manual
630
9. Library
fixed volume flow
out pb
preferred angular
velocity out p_rot
Parameters
D
displacement per revolution [m3]
FlowSource
Library
Iconic Diagrams\Hydraulics\Pumps\Basic Pumps
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model represents an ideal flow source with a fixed flow given by the parameter phi:
p.phi = phi;
The model has no leakage.
Interface
Ports
Description
p
Causality
fixed volume flow
out p
Parameters
phi
Volume flow [m3/s]
ModulatedFlowSource
Library
Iconic Diagrams\Hydraulics\Pumps\Basic Pumps
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model represents an ideal flow source with a variable flow that is given by input
signal phi:
20-sim 4.6 Reference Manual
631
9. Library
p.phi = phi;
The model has no leakage.
Interface
Ports
Description
p
Causality
fixed volume flow
out p
Input
phi
Volume flow [m3/s]
ModulatedPressureSource
Library
Iconic Diagrams\Hydraulics\Pumps\Basic Pumps
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model represents an ideal pressure source with a fixed pressure given by the
parameter pressure:
p.p = pressure;
The model has no leakage.
Interface
Ports
Description
p
Causality
fixed pressure out
Input
pressure
Pressure [Pa]
20-sim 4.6 Reference Manual
632
9. Library
PressureSource
Library
Iconic Diagrams\Hydraulics\Pumps\Basic Pumps
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model represents an ideal pressure source with a fixed pressure given by the
parameter pressure:
p.p = pressure;
The model has no leakage.
Interface
Ports
Description
p
Causality
fixed pressure out
Parameters
p
Pressure [Pa]
VariableDisplacementMotor
Library
Iconic Diagrams\Hydraulics\Pumps\Basic Pumps
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes an ideal motor with an axial speed that is proportional to the input
flow rate:
pa.phi = pb.phi = i * p_rot.omega;
i = D * c / (2*pi);
The torque is equal to:
p.T = i*(pa.p - pb.p);
The displacement is controllable by the input signal c. For a positive rotation of the
driving axis the flow is:
c >= 1
maximum flow from port 1 to port 2
20-sim 4.6 Reference Manual
633
9. Library
c=0
zero flow
c <= -1
maximum flow from port 2 to port 1
If the port pressure is smaller than the vapour pressure (p < p_vapour), the flow is
zero. If the port pressure becomes larger than the vapour pressure the flow gradually
grows to its normal value, until the atmospheric pressure (p = 0) is reached.
Interface
Ports
Description
pa
inlet port (hydraulic)
pb
outlet port (hydraulic)
p_rot
axis (rotation)
Causality
fixed volume flow
out pa
fixed volume flow
out pb
fixed torque
out
p_rot
Input
c
relative displacement
Parameters
D
displacement per revolution [m3]
VariableDisplacementPump
Library
Iconic Diagrams\Hydraulics\Pumps\Basic Pumps
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes an ideal pump with a displacement that is proportional to the speed
of the input axis:
pa.phi = pb.phi = i * p_rot.omega;
i = D * c / (2*pi);
The torque is equal to:
p.T = i*(pb.p - pa.p);
20-sim 4.6 Reference Manual
634
9. Library
The displacement is controllable by the input signal c. For a positive rotation of the
driving axis the flow is:
c >= 1
maximum flow from port 1 to port 2
c=0
zero flow
c <= -1
maximum flow from port 2 to port 1
If the port pressure is smaller than the vapour pressure (p < p_vapour), the flow is
zero. If the port pressure is larger than the vapour pressure the flow gradually grows to
its normal value, until the atmospheric pressure (p = 0) is reached.
Interface
Ports
Description
pa
inlet port (hydraulic)
pb
outlet port (hydraulic)
p_rot
axis (rotation)
Causality
fixed volume flow
out pa
fixed volume flow
out pb
fixed torque
out
p_rot
Input
c
relative displacement
Parameters
D
displacement per revolution [m3]
CentrifugalPump
Library
Iconic Diagrams\Hydraulics\Pumps
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
A centrifugal pump converts the input power of a rotating shaft into kinetic energy of a
the liquid by accelerating the liquid through an impeller.
20-sim 4.6 Reference Manual
635
9. Library
The pump is characterized by two curves:
1.
The head (H) as function of the volume flow at a preset speed.
2.
The efficiency (n) of the pump as a function of the fluid flow at a present speed. The
efficiency is defined as the flow output power divided by rotational input power.
The pump curves are approximated by two second order polynomials:
H = ha*q2 + hb*q + hc
n = na*q2 + nb*q + nc
To fit the polynomial curves, the heads and efficiencies have to be specified at three
different flows. The first flow ( q0) is zero. The other two flows ( q1 and q2) can be chosen
arbitrary.
Note: some pump flows extrapolate the efficiency curves to zero at zero fluid flow. This
would mean that at a zero fluid flow no power can be transmitted and the pump can
20-sim 4.6 Reference Manual
636
9. Library
never start! Therefore in this model always use an efficiency that is non-zero at zero
flow.
Some pump characteristics give multiple input speeds. This model automatically takes
into account for varying input speeds of the input axis by transforming the pump curve
using the affinity rules.
Ha = Hb *(v b /v a)2
Q a = Q b *(v b /v a)
Some pump characteristics give the efficiencies as regions. You have then have to
estimate the efficiencies at the chosen flows q0, q1 and q2.
Interface
Ports
Description
p_t
inlet port, tank (hydraulic)
p_a
outlet port (hydraulic)
p_rot
axis (rotation)
Causality
velocity out p_rot
Input
phi
Volume flow [m3/s]
Parameters
q1
flow 1 (choose an arbitrary point between zero and nominal)
q2
flow 2 (nominal flow)
H0
head at zero flow
20-sim 4.6 Reference Manual
637
9. Library
H1
head at flow 1
H2
head at flow 2 (nominal flow)
n0
efficiency (0 < n < 1) at zero flow
n1
efficiency (0 < n < 1) at flow 1
n2
efficiency (0 < n < 1) at flow 2 (nominal flow)
v_nom
nominal speed of the pump
rho
fluid density
DisplacementMotor-Leakage
Library
Iconic Diagrams\Hydraulics\Pumps
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes an motor with internal and external leakage and an axial speed
that is proportional to the input flow rate:
20-sim 4.6 Reference Manual
638
9. Library
pa.phi = pb.phi = i * p_rot.omega;
i = D / (2*pi);
The actual flows at the inlet and outlet port may be slightly different because of the flow
into the lumped volumes and the leakage flows. The leakage flows are modeled by
laminar resistances. The torque is equal to:
p.T = i*(pa.p - pb.p);
If the port pressure is smaller than the vapour pressure (p < p_vapour), the flow is
zero. If the port pressure is larger than the vapour pressure the flow gradually grows to
its normal value, until the atmospheric pressure (p = 0) is reached.
Interface
Ports
Description
pa
inlet port (hydraulic)
pb
outlet port (hydraulic)
p_rot
axis (rotation)
Causality
preferred pressure out pa
preferred pressure out pa
preferred angular velocity out
p_rot
Parameters
ExternalLeakage1\p_preload Tank pressure [Pa]
ExternalLeakage1\G
C onductance of laminar resistance [m3/s.Pa]
ExternalLeakage2\p_preload Tank pressure [Pa]
ExternalLeakage2\G
C onductance of laminar resistance [m3/s.Pa]
InternalLeakage\G
C onductance of laminar resistance [m3/s.Pa]
Va\V
Volume of oil under pressure [m3]
Va\B
Effective bulk modulus [Pa]
Va\p_initial
The starting pressure of the volume [Pa]
Vb\V
Volume of oil under pressure [m3]
Vb\B
Effective bulk modulus [Pa]
Vb\p_initial
The starting pressure of the volume [Pa]
Motor\D
Displacement per revolution [m3]
Friction\d
Damping [N.m.s/rad]
Inertia\J
Moment of inertia [kg.m2]
20-sim 4.6 Reference Manual
639
9. Library
DisplacementPump-Leakage
Library
Iconic Diagrams\Hydraulics\Pumps
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes a pump with internal and external leakage and a displacement that
is proportional to the speed of the input axis:
i = D * c / (2*pi);
pa.phi = pb.phi = i * p_rot.omega;
The actual flows at the inlet and outlet port may be slightly different because of the flow
into the lumped volumes and the leakage flows. The leakage flows are modeled by
laminar resistances. The torque of the pump is equal to:
p.T = i*(pa.p - pb.p);
If the inlet pressure is smaller than the vapour pressure(p < p_vapour), the flow is zero.
If the inlet pressure becomes larger than the vapour pressure the flow gradually grows
to its normal value, until the atmospheric pressure (p = 0) is reached.
Interface
Ports
Description
pa
inlet port (hydraulic)
20-sim 4.6 Reference Manual
640
9. Library
pb
outlet port (hydraulic)
p_rot
axis (rotation)
Causality
preferred pressure out pa
preferred pressure out pa
preferred angular velocity out
p_rot
Parameters
ExternalLeakage1\p_preload Tank pressure [Pa]
ExternalLeakage1\G
C onductance of laminar resistance [m3/s.Pa]
ExternalLeakage2\p_preload Tank pressure [Pa]
ExternalLeakage2\G
C onductance of laminar resistance [m3/s.Pa]
InternalLeakage\G
C onductance of laminar resistance [m3/s.Pa]
Va\V
Volume of oil under pressure [m3]
Va\B
Effective bulk modulus [Pa]
Va\p_initial
The starting pressure of the volume [Pa]
Vb\V
Volume of oil under pressure [m3]
Vb\B
Effective bulk modulus [Pa]
Vb\p_initial
The starting pressure of the volume [Pa]
Pump\D
Displacement per revolution [m3]
Friction\d
Damping [N.m.s/rad]
Inertia\J
Moment of inertia [kg.m2]
20-sim 4.6 Reference Manual
641
9. Library
FlowSource-Leakage
Library
Iconic Diagrams\Hydraulics\Pumps
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model represents a flow source with a fixed flow and leakage. The flow is given by
the parameter phi:
p.phi = phi - G*p.p;
The actual flow at the outlet port may be slightly different because of the flow into the
lumped volume at the outlet port and the leakage flow.
Interface
Ports
Description
p
Causality
fixed volume flow out
p
Input
phi
Volume flow [m3/s]
Parameters
FlowSource\phi
Volume flow [m3/s]
TankRes\p_preload
Tank pressure [Pa]
TankRes\G
C onductance of laminar resistance [m3/s.Pa]
V\V
Volume of oil under pressure [m3]
V\B
Effective bulk modulus [Pa]
20-sim 4.6 Reference Manual
642
9. Library
V\p_initial
The starting pressure of the volume [Pa]
ModulatedFlowSource-Leakage
Library
Iconic Diagrams\Hydraulics\Pumps
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model represents a flow source with a variable flow and leakage. The variabele flow
is given by an input signal:
p.phi = phi - G*p.p;
The actual flow at the outlet port may be slightly different because of the flow into the
lumped volume at the outlet port and the leakage flow.
Interface
Ports
Description
p
Causality
fixed volume flow out
p
Input
phi
Volume flow [m3/s]
Parameters
TankRes\p_preload
tank pressure [Pa]
TankRes\G
C onductance of laminar resistance [m3/s.Pa]
V\V
Volume of oil under pressure [m3]
V\B
Effective bulk modulus [Pa]
20-sim 4.6 Reference Manual
643
9. Library
V\p_initial
The starting pressure of the volume [Pa]
VariableDisplacementMotor-Leakage
Library
Iconic Diagrams\Hydraulics\Pumps
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes an motor with internal and external leakage and an axial speed
that is proportional to input flow rate:
pa.phi = pb.phi = i * p_rot.omega;
i = D / (2*pi);
The actual flows at the inlet and outlet port may be slightly different because of the flow
into the lumped volumes and the leakage flows. The leakage flows are modeled by
laminar resistances. The torque is equal to:
p.T = i*(pa.p - pb.p);
The displacement is controllable by the input signal c. For a positive rotation of the
driving axis the flow is:
c >= 1
maximum flow from port 1 to port 2
20-sim 4.6 Reference Manual
644
9. Library
c=0
zero flow
c <= -1
maximum flow from port 2 to port 1
If the port pressure is smaller than the vapour pressure (p < p_vapour), the flow is
zero. If the port pressure is larger than the vapour pressure the flow gradually grows to
its normal value, until the atmospheric pressure (p = 0) is reached.
Interface
Ports
Description
pa
inlet port (hydraulic)
pb
outlet port (hydraulic)
p_rot
axis (rotation)
Causality
preferred pressure out pa
preferred pressure out pa
preferred angular velocity out
p_rot
Input
c
relative displacement
Parameters
ExternalLeakage1\p_preload Tank pressure [Pa]
ExternalLeakage1\G
C onductance of laminar resistance [m3/s.Pa]
ExternalLeakage2\p_preload Tank pressure [Pa]
ExternalLeakage2\G
C onductance of laminar resistance [m3/s.Pa]
InternalLeakage\G
C onductance of laminar resistance [m3/s.Pa]
Va\V
Volume of oil under pressure [m3]
Va\B
Effective bulk modulus [Pa]
Va\p_initial
The starting pressure of the volume [Pa]
Vb\V
Volume of oil under pressure [m3]
Vb\B
Effective bulk modulus [Pa]
Vb\p_initial
The starting pressure of the volume [Pa]
Motor\D
Displacement per revolution [m3]
Friction\d
Damping [N.m.s/rad]
Inertia\J
Moment of inertia [kg.m2]
20-sim 4.6 Reference Manual
645
9. Library
VariableDisplacementPump-Leakage
Library
Iconic Diagrams\Hydraulics\Pumps
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes a pump with internal and external leakage and a displacement that
is proportional to the speed of the input axis:
i = D * c / (2*pi);
pa.phi = pb.phi = i * p_rot.omega;
The actual flows at the inlet and outlet port may be slightly different because of the flow
into the lumped volumes and the leakage flows. The leakage flows are modeled by
laminar resistances. The torque of the pump is equal to:
p.T = i*(pa.p - pb.p);
The displacement is controllable by the input signal c. For a positive rotation of the
driving axis the flow is:
c >= 1
maximum flow from port 1 to port 2
20-sim 4.6 Reference Manual
646
9. Library
c=0
zero flow
c <= -1
maximum flow from port 2 to port 1
If the port pressure is smaller than the vapour pressure (p < p_vapour), the flow is
zero. If the port pressure becomes larger than the vapour pressure the flow gradually
grows to its normal value, until the atmospheric pressure (p = 0) is reached.
Interface
Ports
Description
pa
inlet port (hydraulic)
pb
outlet port (hydraulic)
p_rot
axis (rotation)
Causality
preferred pressure out pa
preferred pressure out pa
preferred angular velocity out
p_rot
Input
c
relative displacement
Parameters
ExternalLeakage1\p_preload Tank pressure [Pa]
ExternalLeakage1\G
C onductance of laminar resistance [m3/s.Pa]
ExternalLeakage2\p_preload Tank pressure [Pa]
ExternalLeakage2\G
C onductance of laminar resistance [m3/s.Pa]
InternalLeakage\G
C onductance of laminar resistance [m3/s.Pa]
Va\V
Volume of oil under pressure [m3]
Va\B
Effective bulk modulus [Pa]
Va\p_initial
The starting pressure of the volume [Pa]
Vb\V
Volume of oil under pressure [m3]
Vb\B
Effective bulk modulus [Pa]
Vb\p_initial
The starting pressure of the volume [Pa]
Pump\D
Displacement per revolution [m3]
Friction\d
Damping [N.m.s/rad]
Inertia\J
Moment of inertia [kg.m2]
20-sim 4.6 Reference Manual
647
9. Library
Restrictions
LaminarResistance
Library
Iconic Diagrams\Hydraulics\Restrictions
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes the laminar flow through a component:
pa.phi = pb.phi = G*(pa.p - pb.p);
The pressure at both ports has a lower limit which is equal to the vapour pressure.
Therefore the actual equations used in this component are:
p1_lim = if pa.p < p_vapour then p_vapour else pa.p end;
p2_lim = if pb.p < p_vapour then p_vapour else pb.p end;
dp = p1_lim - p2_lim;
pa.phi = G*dp;
pb.phi = pa.phi;
There is no check on the validity of laminar flow in this component!
Interface
Ports
Description
pa, pb
Both terminals of the hydraulic component.
Causality
fixed volume flow
out pa
fixed volume flow
out pb
Parameters
G
C onductance of laminar resistance [m3/s.Pa], G >= 0!.
Orifice
Library
Iconic Diagrams\Hydraulics\Restrictions
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
20-sim 4.6 Reference Manual
648
9. Library
Description
This model describes the laminar/turbulent flow through an orifice if no cavitation occurs.
The flow depends on the pressure difference:
dp = pa.p - pb.p
phi = sign(dp) * Cd * A * sqrt( (2/rho) * abs(dp) ) + GLeak * dp;
Here Cd is the discharge coefficient which normally has a value between 0.55 and 0.7
and A is the area of the orifice opening. Gleak is the conductance of laminar leakage
flow when the valve is closed.
The pressure at both ports has a lower limit that is equal to the vapour pressure.
Therefore the actual equations used in this component are:
p1_lim = if pa.p < p_vapour then p_vapour else pa.p end;
p2_lim = if pb.p < p_vapour then p_vapour else pb.p end;
dp = p1_lim - p2_lim;
Interface
Ports
Description
pa, pb
Both terminals of the hydraulic component.
Causality
fixed volume flow
out pa
fixed volume flow
out pb
Parameters
rho
Mass density of the fluid [kg/m3].
GLeak
C onductance of the laminar leakage flow [m3/s.Pa], GLeak >= 0!
20-sim 4.6 Reference Manual
649
9. Library
A
Orifice Area [m2], A >= 0!
Cd
Discharge coefficient [].
VariableLaminarResistance
Library
Iconic Diagrams\Hydraulics\Restrictions
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes the laminar flow through a component:
pa.phi = pb.phi = G*(pa.p - pb.p);
The variable conductance G is given by an input signal. The pressure at both ports has a
lower limit that is equal to the vapour pressure. Therefore the actual equations used in
this component are:
p1_lim = if pa.p < p_vapour then p_vapour else pa.p end;
p2_lim = if pb.p < p_vapour then p_vapour else pb.p end;
dp = p1_lim - p2_lim;
pa.phi = G*dp;
pb.phi = pa.phi;
There is no check on the validity of laminar flow in this component!
Interface
Ports
Description
pa, pb
Both terminals of the hydraulic component.
Causality
fixed volume flow
out pa
fixed volume flow
out pb
Input
G
C onductance of laminar resistance [m3/s.Pa], G >= 0.
20-sim 4.6 Reference Manual
650
9. Library
VariableOrifice
Library
Iconic Diagrams\Hydraulics\Restrictions
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes the laminar/turbulent flow through an orifice if no cavitation occurs.
The flow depends on the pressure difference:
dp = pa.p - pb.p;
phi = sign(dp) * Cd * A * sqrt( (2/rho) * abs(dp) ) + GLeak * dp;
Here Cd is the discharge coefficient that normally has a value between 0.55 and 0.7 and
A is the area of the orifice opening. The area A is given as an input signal.
The pressure at both ports has a lower limit that is equal to the vapour pressure.
Therefore the actual equations used in this component are:
p1_lim = if pa.p < p_vapour then p_vapour else pa.p end;
p2_lim = if pb.p < p_vapour then p_vapour else pb.p end;
dp = p1_lim - p2_lim;
Interface
Ports
Description
pa, pb
Both terminals of the hydraulic component.
Causality
fixed volume flow
out pa
20-sim 4.6 Reference Manual
651
9. Library
fixed volume flow
out pb
Input
A
Orifice Area [m2], A >= 0.
Parameters
rho
Mass density of the fluid [kg/m3].
GLeak
C onductance of the laminar leakage flow [m3/s.Pa], GLeak >=0!
Cd
Discharge coefficient [], C d >=0!
Sensors
FlowSensor
Library
Iconic Diagrams\Hydraulics\Sensors
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model gives the measured flow as an output signal. The port p of the model has
separate high and low terminals. The equations are:
p.phi = p_high.phi = p_low.phi;
p.p = p_high.p - p_low.p;
p.p = 0;
phi = p.phi;
The model has no leakage.
Interface
Ports
Description
p
Causality
fixed volume flow
out
Output
phi
Volume flow [m3/s]
20-sim 4.6 Reference Manual
652
9. Library
HeadSensor
Library
Iconic Diagrams\Hydraulics\Sensors
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This sensor gives the pressure in head:
H = p / (rho * g)
with rho the density of the fluid and g the specific gravity. The head is the rise of fluid in
meters if an open tube would be connected. The figure below shows an example for
water at 1 bar and 20 degrees (rho = 998 kg/m3 giving a head of 10.2 m.
Interface
Ports
Description
p
Causality
indifferent
Parameters
rho
Mass density of the fluid [kg/m3].
PowerSensor
Library
Iconic Diagrams\Hydraulics\Sensors
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model gives the power that is tranferred over a hydraulic line:
p_high.p = p_low.p;
p_high.phi = p_low.phi;
P = p_high.phi*p_high.p;
The model has no leakage.
20-sim 4.6 Reference Manual
653
9. Library
Interface
Ports
Description
p
Causality
indifferent
Output
P
Power [W].
PressureSensor
Library
Iconic Diagrams\Hydraulics\Sensors
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model gives the measured pressure as an output signal:
pressure = p.p;
p.phi = 0;
The model has no leakage.
Interface
Ports
Description
p
Causality
fixed volume flow
out
Output
pressure
Absolute velocity [m/s].
20-sim 4.6 Reference Manual
654
9. Library
Valves
Basic Valves
CheckValve
Library
Iconic Diagrams\Hydraulics\Valves\Basic Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes a spring-loaded check valve. The resistance depends on the
pressure difference:
dp < pclosed => valve closed, only leakage: pa.phi = pb.phi = dp * GLeak
pclosed < dp < popen => working range, i. e. valve partially opened
popen < dp => valve wide open: pa.phi = pb.phi = Cd * A * sqrt(dp - pclosed);
Interface
Ports
Description
pa, pb
Both terminals of the hydraulic component.
Causality
fixed volume flow
out pa
fixed volume flow
out pb
Parameters
20-sim 4.6 Reference Manual
655
9. Library
pclosed
Valve is closed under this pressure [Pa].
popen
Valve is fully open above this pressure [Pa].
GLeak
C onductance of closed valve [m3/s.Pa].
A
Maximum valve area when the valve is open [m2], A >= 0!
Cd
Discharge coefficient [].
FlowControlValve
Library
Iconic Diagrams\Hydraulics\Valves\Basic Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
Flow control valves have the purpose to provide a constant flow, independent of the
downstream pressure. The flow is obtained by means of a pressure difference controller
using the pressure drop over an orifice. Therefore flow control valves always need a
certain pressure drop before the desired flow can be achieved.
In this model the flow is modeled by an tanh function. The pressure drop is defined as
the pressure where 95% of the desired flow rate is achieved.
dp = pa.p - pb.p
phi = if dp > 0 then
phi*arctanh( (arctan(0.95)/p_drop) * dp) + GLeak * dp;
else
GLeak * dp
end;
20-sim 4.6 Reference Manual
656
9. Library
Here phi is the desired flow and p_drop is the 95% pressure drop. Gleak is the
conductance of laminar leakage flow when the valve is closed. The pressure at both
ports has a lower limit that is equal to the vapour pressure. Therefore the actual
equations used in this model are:
p1_lim = if pa.p < p_vapour then p_vapour else pa.p end;
p2_lim = if pb.p < p_vapour then p_vapour else pb.p end;
dp = p1_lim - p2_lim;
Interface
Ports
Description
pa, pb
Both terminals of the hydraulic component.
Causality
fixed volume flow
out pa
fixed volume flow
out pb
Parameters
phi
Desired flow [m3/s]
p_drop
pressure drop at 95% flow [Pa]
GLeak
C onductance of the laminar leakage flow [m3/s.Pa], GLeak >= 0!
FourThreeWayDirectionalValve
Library
Iconic Diagrams\Hydraulics\Valves\Basic Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model is equal to the four three way proportional valve model, except for the spool
position. The spool position is rounded to 0, 1 or -1:
-0.5 < spoolpos < 0.5 => pos = 0
spoolpos >= 0.5 => pos = 1
spoolpos <= -0.5 => pos = -1
The spool dynamics is modeled by a second order transfer function:
sp = SO(f,d,discrete(pos))
which is characterized by the bandwidth (f) and damping (d).
20-sim 4.6 Reference Manual
657
9. Library
Implementation
The 4/3-way directional control valve is implemented with various spool centre
configurations. The configurations are shown in the picture below:
When you drag and drop a model in the editor, you will be asked which implementation
you want to choose. During modeling you can easily change the spool center
configuration:
1.
Select the valve model.
2.
C lick the right mouse button to open the right mouse menu.
3.
C lick Edit Implementation and choose another implementation.
Interface
Ports
Description
pp, pt, pa, pb,
All terminals of the valve.
Causality
fixed volume flow
out pp
fixed volume flow
out pt
fixed volume flow
out pa
fixed volume flow
out pb
Inputs
spoolpos
position of the spool valve: 0 =closed, 1 = open
0 <= spoolpos <= 1
Parameters
rho
Mass density of the fluid [kg/m3].
GLeak
C onductance of the laminar leakage flows [m3/s.Pa], GLeak >= 0.
Amax
Maximum spool valve areas when the valves are open [m2], Amax >
Cd
0.
20-sim 4.6 Reference Manual
658
9. Library
overlap
Discharge coefficient [], C d > 0.
f
The valve overlaps in closed position [], -1 < overlap < 1.
d
Bandwidth of the spool dynamics [Hz], f > 0.
Damping of the spool dynamics [], d > 0
FourThreeWayProportionalValve
Library
Iconic Diagrams\Hydraulics\Valves\Basic Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes a 4/3-way proportional control valve with second order spool
dynamics.
The spool position is indicated by the variable sp:
sp = -1
Flow from p to b and a to t
-1 < sp < 0 Partial flow from p to b and a to t
sp = 0
No flow
0 < sp < 1
Partial flow from p to a and b to t
20-sim 4.6 Reference Manual
659
9. Library
sp = 1
Flow from p to a and b to t
The flow through the valves is described as laminar/turbulent flow through an orifice. A
detailed description of the flow equations can be found in the description of the model
TwoTwoWayDirectionalValve.
In the neutral spool position (sp = 0) all valves are closed. A positive overlap indicates
that the spool must travel a certain distance before the valves open. A negative overlap
indicates that the valves are already open in the neutral position. A 4/3-way directional
control valve with negative overlap could therefore also be indicated by the figure below.
The overlap is indicated by the parameter overlap, which is given as a fraction of the
spool position. Note that overlap is only active in the neutral position. For the spool
position equal to 1 or -1 the valves are completely open or completely closed.
The spool position sp is a function of the input signal spoolpos:
sp = SO(f,d,discrete(spoolpos))
where SO is a second order transfer function to model the spool dynamics. The function
is characterized by the bandwidth (f) and damping (d). The valve input position spoolpos
should be limited to the range between -1 and 1.
Implementation
The 4/3-way proportional control valve is implemented with various spool centre
configurations. The configurations are shown in the picture below:
20-sim 4.6 Reference Manual
660
9. Library
When you drag and drop a model in the editor, you will be asked which implementation
you want to choose. During modeling you can easily change the spool center
configuration:
1.
Select the valve model.
2.
C lick the right mouse button to open the right mouse menu.
3.
C lick Edit Implementation and choose another implementation
Interface
Ports
Description
pp, pt, pa, pb,
All terminals of the valve.
Causality
fixed volume flow
out pp
fixed volume flow
out pt
fixed volume flow
out pa
fixed volume flow
out pb
Inputs
spoolpos
position of the spool valve: 0 =closed, 1 = open
0 <= spoolpos <= 1
Parameters
rho
Mass density of the fluid [kg/m3].
GLeak
C onductance of the laminar leakage flows [m3/s.Pa], GLeak >= 0.
Amax
Maximum spool valve areas when the valves are open [m2], Amax >
Cd
0.
overlap
Discharge coefficient [], C d > 0.
f
The valve overlaps in closed position [], -1 < overlap < 1.
d
Bandwidth of the spool dynamics [Hz], f > 0.
20-sim 4.6 Reference Manual
661
9. Library
Damping of the spool dynamics [], d > 0
LoopFlushingValve
Library
Iconic Diagrams\Hydraulics\Valves\Basic Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
Loop flushing valves are used to maintain a high quality working fluid in closed hydraulic
circuits. In closed hydraulic circuits the oil is continuously flowing from a pump to an
actuator. A loop flushing valve allows the oil to leave the circuit for cooling and filtering.
If one side (pa) of the valve has a higher pressure, oil will flow from the other side (pb)
out of the closed circuit and vice versa.
The circuit is always equipped (not shown above) with a charge pump to keep the
suction side of the pump on a pre-pressure to avoid cavitation and so damage to the
pump, and to exchange the fluid that is flushed.
Loop flushing valves are spring operated. I.e. a certain pressure difference between
port a and b is required to open the valve. This pressure can be adjusted and is
indicated by the parameter p_sw.
20-sim 4.6 Reference Manual
662
9. Library
A small pressure difference is required to turn a valve from completely closed to
completely opened. This overlap pressure is indicated by the parameter p_o.
Interface
Ports
Description
pa, pb
Input terminals of the valve.
p_out
Output terminal.
Causality
fixed volume flow
out pa
fixed volume flow
out pb
fixed volume flow
out p_out
Inputs
spoolpos
position of the spool valve: 0 =closed, 1 = open
0 <= spoolpos <= 1
Parameters
rho
Mass density of the fluid [kg/m3].
GLeak
C onductance of the laminar leakage flows [m3/s.Pa], GLeak >= 0.
Amax
Maximum spool valve areas when the valves are open [m2], Amax >
Cd
0.
f
Discharge coefficient [], C d > 0.
d
Bandwidth of the spool dynamics [Hz], f > 0.
p_o
Damping of the spool dynamics [], d > 0
p_sw
Overlap pressure [Pa].
Switching pressure [Pa].
20-sim 4.6 Reference Manual
663
9. Library
PilotOperatedCheckValve
Library
Iconic Diagrams\Hydraulics\Valves\Basic Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
A pilot operated check valve is a check valve that is normally closed but can be opened
for reverse flow by a signal from an external pilot supply.
The figure above shows the standard design using a pilot piston with a stem to unseat
the check valve poppet for reverse flow. The pilot piston has an area three to four times
that of the poppet seat. This produces enough force to open the poppet against
backpressure. Some pilot-operated check valves have area ratios up to 100:1, allowing
a very low pilot pressure to open the valve against high backpressure.
The flow through a pilot operated check depends on the differential pressure dp between
the inlet port pa and the outlet port pb and is equal to:
flow = Cd * A * valve * sqrt(dp);
The variable valve indicates the valve opening and varies between zero (closed) and 1
(open). The opening depends on a force balance which depends on the pressures of the
inlet and outlet port, the spring force and the pressure of the pilot port px:
valve = limit( ( pa.p - pb.p - pclosed + px.p*kp )/(popen - pclosed) , 0 , 1 )
The pilot ratio kp is ratio of the pilot piston area and the check valve area. For a large
pilot ratio a relatively small pilot pressure is sufficient to open the valve against a large
outlet pressure.
20-sim 4.6 Reference Manual
664
9. Library
Interface
Ports
Description
pa
Inlet port
pb
Outlet port
px
Pilot port
Causality
fixed volume flow
out pa
fixed volume flow
out pb
fixed volume flow
out pt
Parameters
pclosed
Valve is closed under this pressure [Pa] and zero pilot pressure.
popen
Valve is fully open above this pressure [Pa] and zero pilot pressure.
GLeak
C onductance of closed valve [m3/s.Pa].
A
Maximum valve area when the valve is open [m2], A >= 0!
Cd
Discharge coefficient [].
kp
Pilot ratio [].
20-sim 4.6 Reference Manual
665
9. Library
PressureCompensator
Library
Iconic Diagrams\Hydraulics\Valves\Basic Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description - Default
A pressure compensator is an component that maintains a constant differential pressure
across it sensing ports px and py by regulating the flow through the component from
port pa to port pb. A pressure compensator can be used to maintain a constant flow over
a valve by keeping the pressure drop over the valve constant. The sensing ports py and
px are then connected with the input and output of the valve.
The flow through the element is laminar or turbulent depending on the pressure drop
p_ab over pa and pb:
p_ab = pa.p - pb.p;
phi = sign(p_ab) * Cd * A * sqrt( (2/rho) * abs(dp) ) + GLeak * p_ab;
The opening A depends on the pressure drop p_xy over pa and pb:
20-sim 4.6 Reference Manual
666
9. Library
The maximum opening A_max is determined by the maximum flow phi_max at the
maximum pressure drop p_in_max over the component:
A_max = phi_max / ( Cd * sqrt( (2/rho) * p_in_max ) );
The opening is at its maximum value when the differential pressure across it sensing
ports px and py is below the pressure ((k-1)/k)*p_set. If the differential pressure across
it sensing ports px and py is too high, the opening is closed. In between it varies
between fully open and fully closed. The speed of response of the components is
determined by the proportional gain k (typical choose k = 2 to 5). The proportional gain
determines the slope of the valve opening. If k is large the regulator will respond quickly
but also induce oscillations in the circuit.
The valve is implemented with second order spool dynamics. I.e. the spool opening is
characterized by the bandwidth (f) and damping (d).
Interface
Ports
Description
pa, pb
Input and output terminals of the component.
px, py
Sensing terminals of the component. These are used to measure the
pressure and have almost zero flow.
Causality
fixed volume flow
out pa
fixed volume flow
out pb
fixed volume flow
out px
fixed volume flow
out py
Parameters
20-sim 4.6 Reference Manual
667
9. Library
rho
Mass density of the fluid [kg/m3].
GLeak
C onductance of the laminar leakage flows [m3/s.Pa], GLeak >= 0.
Cd
Discharge coefficient [], C d > 0.
p_set
Desired differential pressure over xy (px.p - py.p), [Pa]
p_in_max
maximum inlet pressure, [Pa]
phi_max
maximum
flow at maximum inlet pressure (pa.p) and zero outlet
pressure (pb.p), [m3/s]
f
natural frequency of the second order spool dynamics [Hz]
d
relative damping of the second order spool dynamics [Hz]
k
proportional gain [-]
PressureReliefValve
Library
Iconic Diagrams\Hydraulics\Valves\Basic Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes a pressure relief valve. The resistance depends on the pressure
difference:
20-sim 4.6 Reference Manual
668
9. Library
dp = pa.p - pb.p
dp < pclosed => valve closed, only leakage: pa.phi = pb.phi = dp * GLeak
pclosed < dp < popen => working range, i. e. valve partially opened
popen < dp => valve wide open: pa.phi = pb.phi = dp * GOpen
Interface
Ports
Description
pa, pb
Both terminals of the hydraulic component.
Causality
fixed volume flow
out pa
fixed volume flow
out pb
Parameters
pclosed
Valve is closed under this pressure [Pa].
popen
Valve is fully open above this pressure [Pa].
GLeak
C onductance of closed valve [m3/s.Pa].
GOpen
C onductance of open valve [m3/s.Pa].
20-sim 4.6 Reference Manual
669
9. Library
PressureReducingValve
Library
Iconic Diagrams\Hydraulics\Valves\Basic Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
Pressure reducing valves have the purpose to provide a constant pressure (p_nom),
independent of the upstream pressure. They are used to limit the pressure of a primary
circuit to a desired pressure for a secondary circuit.
The desired pressure (p_nom) is obtained by means of a flow over a valve between an
input port (pa) and an output port (pb). The valve is modeled by a variable
conductance). Depending on the pressure downstream (pb.p) the valve is opened (large
conductance) or closed (zero conductance). Therefore pressure reducing valves always
need a small flow to establish the correct downstream pressure.
When the downstream pressure (pb.p) increases over the desired pressure a second
valve opens to allow flow from the downstream port (pb) to a third port (pt). The third
port is mostly connected to the tank.
20-sim 4.6 Reference Manual
670
9. Library
The valves have a pressure region for opening an closing. This region is indicated by the
parameter range.
Interface
Ports
Description
pa
Upstream port
pb
Downstram port
pt
Relief port
Causality
fixed volume flow
out pa
fixed volume flow
out pb
fixed volume flow
out pt
Parameters
p_nom
Desired downstream pressure [Pa].
range
Range for opening and closing the valves [Pa].
Gab
The maximum conductance from a to b [m3/s.Pa].
Gbt
The maximum conductance from b to t [m3/s.Pa].
20-sim 4.6 Reference Manual
671
9. Library
ShuttleValve
Library
Iconic Diagrams\Hydraulics\Valves\Basic Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description - Default
A shuttle valve is a type of valve which allows fluid to flow through it from one of two
sources. Shuttle valves accept flow from two different sources (pa) and (pb) and divert
the highest pressure to a single outlet port (p_out). Shuttle valves are commonly used in
Load Sensing circuits and at a cylinder to measure the working pressure, as well as
Brake circuits. Normal shuttle valve are mostly ball and poppet types valves.
The default implementation of the shuttle valve assumes ideal behaviour:
p.out.p = maximum(pa.p, pb.p)
pa.phi = pb.phi = 0;
This model sets the flows of the input ports to zero and assumes the output flow is zero
as well. However the output flow is determined by the component that is connected with
the output port. A warning is given when the output flow exceeds 1.0e-5 m3. If flows are
important in your model, use the Spool Dynamics implementation of this model (see
below).
Interface - Default
Ports
Description
pa, pb
Input terminals of the valve.
p_out
Output terminal.
Causality
fixed volume flow
out pa
fixed volume flow
out pb
20-sim 4.6 Reference Manual
672
9. Library
fixed pressure out
p_out
Description - BallDynamics
This implementation is equal to the default implementation but with modeled dynamics.
A small pressure difference between the inlet ports pa and pb is enough to make the ball
switch from one side to the other. This pressure is called the overlap pressure po.
Interface - BallDynamics
Ports
Description
pa, pb
Input terminals of the valve.
p_out
Output terminal.
Causality
fixed volume flow
out pa
fixed volume flow
out pb
fixed volume flow
out p_out
Parameters
rho
Mass density of the fluid [kg/m3].
GLeak
C onductance of the laminar leakage flows [m3/s.Pa], GLeak >= 0.
Amax
Maximum valve areas when the valves are open [m2], Amax > 0.
Cd
Discharge coefficient [], C d > 0.
f
Bandwidth of the valve dynamics [Hz], f > 0.
d
Damping of the valve dynamics [], d > 0
p_o
Overlap pressure [Pa].
20-sim 4.6 Reference Manual
673
9. Library
TwoTwoWayDirectionalValve
Library
Iconic Diagrams\Hydraulics\Valves\Basic Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes a 2/2-way directional control valve with second order spool
dynamics. The flow through the valve is described as laminar/turbulent flow through an
orifice:
dp = pa.p - pb.p
phi = sign(dp) * Cd * A(sp) * sqrt( (2/rho) * abs(dp) ) + GLeak * dp;
Here Cd is the discharge coefficient which normally has a value between 0.55 and 0.7.
A(sp) is the area of the orifice opening. A(sp) depends linearly on the spool position sp
and varies between 0 (sp = 0) and the maximum area Amax (sp = 1). Gleak is the
conductance of laminar leakage flow when the valve is closed. The relative opening of
the spool valve is indicated by sp. For a closed valve the spool position (sp) is equal to
zero and for an open valve the spool position (sp) is equal to 1.
In the neutral spool position (sp = 0) the valve is just closed. A positive overlap
indicates that the spool must travel a certain distance before the valve opens.
20-sim 4.6 Reference Manual
674
9. Library
A negative overlap indicates that the valve is already open in the neutral position.
The overlap is indicated by the parameter overlap, which is given as a fraction of the
spool position.
The spool position sp is a function of the input signal spoolpos:
sp = SO(f,d,discrete(spoolpos))
where SO is a second order transfer function to model the spool dynamics. The function
is characterized by the bandwidth (f) and damping (d). The model acts as a directional
valve (a valve which is either open or closed) because the input signal spoolpos is
rounded to 0 or 1:
spoolpos < 0.5 => 0
spoolpos >= 0.5 => 1
The pressure at both ports has a lower limit which is equal to the vapour pressure.
Therefore the actual equations used in this component are:
pa_lim = if pa.p < p_vapour then p_vapour else pa.p end;
pb_lim = if pb.p < p_vapour then p_vapour else pb.p end;
20-sim 4.6 Reference Manual
675
9. Library
Interface
Ports
Description
pa, pb
Both terminals of the valve.
Causality
fixed volume flow
out pa
fixed volume flow
out pb
Inputs
spoolpos
position of the spool valve
spoolpos < 0.5 => valve is closed
spoolpos >= 0.5 => valve is open
Parameters
rho
Mass density of the fluid [kg/m3].
GLeak
C onductance of the laminar leakage flow [m3/s.Pa], GLeak >= 0.
Amax
Maximum spool valve area when the valve is open [m2], Amax > 0.
Cd
Discharge coefficient [], C d > 0.
overlap
The valve overlap in closed position [], -1 < overlap < 1.
f
Bandwidth of the spool dynamics [Hz], f > 0.
d
Damping of the spool dynamics [], d > 0.
TwoTwoWayProportionalValve
Library
Iconic Diagrams\Hydraulics\Valves\Basic Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
20-sim 4.6 Reference Manual
676
9. Library
Description
This model describes a 2/2-way proportional control valve with second order spool
dynamics. The flow through the valve is described as laminar/turbulent flow through an
orifice:
dp = pa.p - pb.p
phi = sign(dp) * Cd * A(sp) * sqrt( (2/rho) * abs(dp) ) + GLeak * dp;
Here Cd is the discharge coefficient which normally has a value between 0.55 and 0.7.
A(sp) is the area of the orifice opening. A(sp) depends linearly on the spool position sp
and varies between 0 (sp = 0) and the maximum area Amax (sp = 1). Gleak is the
conductance of laminar leakage flow when the valve is closed. The relative opening of
the spool valve is indicated by sp. For a closed valve the spool position (sp) is equal to
zero and for an open valve the spool position (sp) is equal to 1.
In the neutral spool position (sp = 0) the valve is just closed. A positive overlap
indicates that the spool must travel a certain distance before the valve opens.
20-sim 4.6 Reference Manual
677
9. Library
A negative overlap indicates that the valve is already open in the neutral position.
The overlap is indicated by the parameter overlap, which is given as a fraction of the
spool position.
The spool position sp is a function of the input signal spoolpos:
sp = SO(f,d,spoolpos)
where SO is a second order transfer function to model the spool dynamics. The function
is characterized by the bandwidth (f) and damping (d). The valve input position spoolpos
should be limited to the range between 0 and 1.
The pressure at both ports has a lower limit which is equal to the vapour pressure.
Therefore the actual equations used in this component are:
pa_lim = if pa.p < p_vapour then p_vapour else pa.p end;
pb_lim = if pb.p < p_vapour then p_vapour else pb.p end;
Interface
Ports
Description
pa, pb
Both terminals of the valve.
20-sim 4.6 Reference Manual
678
9. Library
Causality
fixed volume flow
out pa
fixed volume flow
out pb
Inputs
spoolpos
position of the spool valve: 0 =closed, 1 = open
0 <= spoolpos <= 1
Parameters
rho
Mass density of the fluid [kg/m3].
GLeak
C onductance of the laminar leakage flow [m3/s.Pa], GLeak >= 0.
Amax
Maximum spool valve area when the valve is open [m2], Amax > 0.
Cd
Discharge coefficient [], C d > 0.
overlap
The valve overlap in closed position [], -1 < overlap < 1.
f
Bandwidth of the spool dynamics [Hz], f > 0.
d
Damping of the spool dynamics [], d > 0.
CheckValve-States
Library
Iconic Diagrams\Hydraulics\Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes a spring-loaded check valve with lumped volumes. The resistance
depends on the pressure difference:
20-sim 4.6 Reference Manual
679
9. Library
dp < pclosed => valve closed, only leakage: pa.phi = pb.phi = dp * GLeak
pclosed < dp < popen => working range, i. e. valve partially opened
popen < dp => valve wide open: pa.phi = pb.phi = K * sqrt(dp - pclosed);
Interface
Ports
Description
pa, pb
Both terminals of the hydraulic component.
Causality
preferred pressure out pa
preferred pressure out pb
Parameters
C heckValve\pclosed
Valve is closed under this pressure [Pa].
C heckValve\popen
Valve is fully open above this pressure [Pa].
C heckValve\GLeak
C onductance of closed valve [m3/s.Pa].
C heckValve\A
Maximum valve area when the valve is open [m2], A >=
C heckValve\C d
0!
Va\V
Discharge coefficient [].
Va\B
Volume of oil under pressure [m3]
Va\p_initial
Effective bulk modulus [Pa]
Vb\V
The starting pressure of the volume [Pa]
Vb\B
Volume of oil under pressure [m3]
Vb\p_initial
Effective bulk modulus [Pa]
The starting pressure of the volume [Pa]
20-sim 4.6 Reference Manual
680
9. Library
CounterbalanceValve
Library
Iconic Diagrams\Hydraulics\Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model an externally piloted counter balance valve. The model consists of an
externally piloted pressure relief valve with a check valve in parallel. The ports of the
model are connected to lumped volumes.
The C ounterbalance valve is applied as a brake valve to get a positive control on a
hydraulic cylinder or motor with a negative load. The check valve is used to get a free
running actuator in one direction and the pressure relief valve is used to control the
actuator in the other direction. The relief valve is controlled by the external pilot
pressure.
Interface
Ports
Description
pa, pb
Both terminals of the hydraulic component.
pt.
Causality
fixed volume flow out pa
fixed volume flow out pb
fixed volume flow out pt
20-sim 4.6 Reference Manual
681
9. Library
Parameters
C heckValve\pclosed
Valve is closed under this pressure [Pa].
C heckValve\popen
Valve is fully open above this pressure [Pa].
C heckValve\GLeak
C onductance of closed valve [m3/s.Pa].
C heckValve\A
Maximum valve area when the valve is open [m2], A >=
C heckValve\C d
0!
PressureReliefValve\pclosed Discharge coefficient [].
PressureReliefValve\popen
Valve is closed under this pressure [Pa].
PressureReliefValve\GLeak
Valve is fully open above this pressure [Pa].
PressureReliefValve\GOpen
C onductance of closed valve [m3/s.Pa].
Va\V
C onductance of open valve [m3/s.Pa].
Va\B
Volume of oil under pressure [m3]
Va\p_initial
Effective bulk modulus [Pa]
Vb\V
The starting pressure of the volume [Pa]
Vb\B
Volume of oil under pressure [m3]
Vb\p_initial
Effective bulk modulus [Pa]
Vt\V
The starting pressure of the volume [Pa]
Vt\B
Volume of oil under pressure [m3]
Vt\p_initial
Effective bulk modulus [Pa]
The starting pressure of the volume [Pa]
FlowControlValve-States
Library
Iconic Diagrams\Hydraulics\Valves\Basic Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes a flow control valve with with lumped volumes.
20-sim 4.6 Reference Manual
682
9. Library
In this model the flow is modeled by an tanh function. The pressure drop is defined as
the pressure where 95% of the desired flow rate is achieved.
dp = pa.p - pb.p
phi = if dp > 0 then
phi*arctanh( (arctan(0.95)/p_drop) * dp) + GLeak * dp;
else
GLeak * dp
end;
Here phi is the desired flow and p_drop is the 95% pressure drop. Gleak is the
conductance of laminar leakage flow when the valve is closed. The pressure at both
ports has a lower limit that is equal to the vapour pressure. Therefore the actual
equations used in this model are:
p1_lim = if pa.p < p_vapour then p_vapour else pa.p end;
p2_lim = if pb.p < p_vapour then p_vapour else pb.p end;
dp = p1_lim - p2_lim;
Interface
Ports
Description
pa, pb
Both terminals of the hydraulic component.
Causality
fixed volume flow out pa
fixed volume flow out pb
Parameters
FlowC ontrolValve\phi
Desired flow [m3/s]
FlowC ontrolValve\p_drop
pressure drop at 95% flow [Pa]
FlowC ontrolValve\GLeak
C onductance of the laminar leakage flow [m3/s.Pa],
Va\V
GLeak >= 0!
Va\B
Volume of oil under pressure [m3]
20-sim 4.6 Reference Manual
683
9. Library
Va\p_initial
Effective bulk modulus [Pa]
Vb\V
The starting pressure of the volume [Pa]
Vb\B
Volume of oil under pressure [m3]
Vb\p_initial
Effective bulk modulus [Pa]
The starting pressure of the volume [Pa]
FourThreeWayDirectionalValve-States
Library
Iconic Diagrams\Hydraulics\Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes a 4/3-way directional control valve with second order spool
dynamics and lumped volumes. The flow through the valves is described as laminar/
turbulent flow through an orifice. A detailed description of the valve can be found in
FourThreeWayDirectionalValve.htm.
The spool position is indicated by the input spoolpos:
sp = -1
Flow from p to b and a to t
sp = 0
No flow
sp = 1
Flow from p to a and b to t
Values between -1 and 0 or between 0 and 1 are rounded to the nearest value.
Implementation
The 4/3-way proportional control valve is implemented with various spool center
configurations. The configurations are shown in the picture below:
20-sim 4.6 Reference Manual
684
9. Library
When you drag and drop a model in the editor, you will be asked which implementation
you want to choose. During modeling you can easily change the spool center
configuration:
1.
Select the valve model.
2.
C lick the right mouse button to open the right mouse menu.
3.
C lick Edit Implementation and choose another implementation.
Interface
Ports
Description
pp, pt, pa, pb
All terminals of the valve.
Causality
preferred effort out pp
preferred effort out pt
preferred effort out pa
preferred effort out pb
Inputs
spoolpos
position of the spool valve
spoolpos < 0.5 => valve is closed
spoolpos >= 0.5 => valve is open
Parameters
FourThreeWayDirectionalValv Mass density of the fluid [kg/m3].
e\rho
C onductance of the laminar leakage flow [m3/s.Pa],
FourThreeWayDirectionalValv GLeak >= 0.
e\GLeak
Maximum spool valve area when the valve is open [m2],
FourThreeWayDirectionalValv Amax > 0.
e\Amax
Discharge coefficient [], C d > 0.
FourThreeWayDirectionalValv The valve overlap in closed position [], -1 < overlap < 1.
e\C d
Bandwidth of the spool dynamics [Hz], f > 0.
FourThreeWayDirectionalValv Damping of the spool dynamics [], d > 0.
e\overlap
Volume of oil under pressure [m3]
20-sim 4.6 Reference Manual
685
9. Library
FourThreeWayDirectionalValv Effective bulk modulus [Pa]
e\f
The starting pressure of the volume [Pa]
FourThreeWayDirectionalValv Volume of oil under pressure [m3]
e\d
Effective bulk modulus [Pa]
Va\V
The starting pressure of the volume [Pa]
Va\B
Va\p_initial
Vb\V
Vb\B
Vb\p_initial
FourThreeWayProportionalValve-States
Library
Iconic Diagrams\Hydraulics\Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes a 4/3-way proportional control valve with second order spool
dynamics and lumped volumes. The flow through the valves is described as laminar/
turbulent flow through an orifice. A detailed description of the valve can be found in
FourThreeWayProportionalValve.htm.
The spool position is indicated by the input spoolpos:
sp = -1
Flow from p to b and a to t
-1 < sp < 0 Partial flow from p to b and a to t
20-sim 4.6 Reference Manual
686
9. Library
sp = 0
No flow
0 < sp < 1
Partial flow from p to a and b to t
sp = 1
Flow from p to a and b to t
Implementation
The 4/3-way proportional control valve is implemented with various spool centre
configurations. The configurations are shown in the picture below:
When you drag and drop a model in the editor, you will be asked which implementation
you want to choose. During modeling you can easily change the spool center
configuration:
1.
Select the valve model.
2.
C lick the right mouse button to open the right mouse menu.
3.
C lick Edit Implementation and choose another implementation.
Interface
Ports
Description
pp, pt, pa, pb
All terminals of the valve.
Causality
preferred effort out pp
preferred effort out pt
preferred effort out pa
preferred effort out pb
Inputs
spoolpos
value of the spool position
Parameters
FourThreeWayProportionalVal Mass density of the fluid [kg/m3].
ve\rho
C onductance of the laminar leakage flow [m3/s.Pa],
FourThreeWayProportionalVal GLeak >= 0.
ve\GLeak
20-sim 4.6 Reference Manual
687
9. Library
FourThreeWayProportionalVal Maximum spool valve area when the valve is open [m2],
ve\Amax
Amax > 0.
FourThreeWayProportionalVal Discharge coefficient [], C d > 0.
ve\C d
The valve overlap in closed position [], -1 < overlap < 1.
FourThreeWayProportionalVal Bandwidth of the spool dynamics [Hz], f > 0.
ve\overlap
Damping of the spool dynamics [], d > 0.
FourThreeWayProportionalVal Volume of oil under pressure [m3]
ve\f
Effective bulk modulus [Pa]
FourThreeWayProportionalVal The starting pressure of the volume [Pa]
ve\d
Volume of oil under pressure [m3]
Va\V
Effective bulk modulus [Pa]
Va\B
The starting pressure of the volume [Pa]
Va\p_initial
Vb\V
Vb\B
Vb\p_initial
LoopFlushingValve-States
Library
Iconic Diagrams\Hydraulics\Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes a loop flushing valve with lumped volumes.
20-sim 4.6 Reference Manual
688
9. Library
Loop flushing valves are used to maintain a high quality working fluid in closed hydraulic
circuits. In closed hydraulic circuits the oil is continuously flowing from a pump to an
actuator. A loop flushing valve allows the oil to leave the circuit for cooling and filtering.
If one side (pa) of the valve has a higher pressure, oil will flow from the other side (pb)
out of the closed circuit and vice versa.
The circuit is always equipped (not shown above) with a charge pump to keep the
suction side of the pump on a pre-pressure to avoid cavitation and so damage to the
pump, and to exchange the fluid that is flushed.
Loop flushing valves are spring operated. I.e. a certain pressure difference between
port a and b is required to open the valve. This pressure can be adjusted and is
indicated by the parameter p_sw.
20-sim 4.6 Reference Manual
689
9. Library
A small pressure difference is required to turn a valve from completely closed to
completely opened. This overlap pressure is indicated by the parameter p_o.
Interface
Ports
Description
pa, pb
Input terminals of the valve.
p_out
Output terminal.
Causality
preferred
pressure out pa
preferred
pressure out pb
preferred
pressure
out
p_out
Inputs
spoolpos
position of the spool valve: 0 =closed, 1 = open
0 <= spoolpos <= 1
Parameters
rho
Mass density of the fluid [kg/m3].
GLeak
C onductance of the laminar leakage flows [m3/s.Pa], GLeak >= 0.
Amax
Maximum spool valve areas when the valves are open [m2], Amax >
Cd
0.
f
Discharge coefficient [], C d > 0.
d
Bandwidth of the spool dynamics [Hz], f > 0.
p_o
Damping of the spool dynamics [], d > 0
p_sw
Overlap pressure [Pa].
Switching pressure [Pa].
20-sim 4.6 Reference Manual
690
9. Library
PilotOperatedCheckValve-States
Library
Iconic Diagrams\Hydraulics\Valves\Basic Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model is a pilot operated check valve with lumped volumes.
The flow through a pilot operated check depends on the differential pressure dp between
the inlet port pa and the outlet port pb and is equal to:
flow = Cd * A * valve * sqrt(dp);
The variable valve indicates the valve opening and varies between zero (closed) and 1
(open). The opening depends on a force balance which depends on the pressures of the
inlet and outlet port, the spring force and the pressure of the pilot port px:
valve = limit( ( pa.p - pb.p - pclosed + px.p*kp )/(popen - pclosed) , 0 , 1 )
The pilot ratio kp is ratio of the pilot piston area and the check valve area. For a large
pilot ratio a relatively small pilot pressure is sufficient to open the valve against a large
outlet pressure.
20-sim 4.6 Reference Manual
691
9. Library
Interface
Ports
Description
pa
Inlet port
pb
Outlet port
px
Pilot port
Causality
fixed volume flow
out pa
fixed volume flow
out pb
fixed volume flow
out pt
Parameters
pclosed
Valve is closed under this pressure [Pa] and zero pilot pressure.
popen
Valve is fully open above this pressure [Pa] and zero pilot pressure.
GLeak
C onductance of closed valve [m3/s.Pa].
A
Maximum valve area when the valve is open [m2], A >= 0!
Cd
Discharge coefficient [].
kp
Pilot ratio [].
PressureCompensator-States
Library
Iconic Diagrams\Hydraulics\Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description - Default
This model is a pressure compensator with lumped volumes. A pressure compensator is
an component that maintains a constant differential pressure across it sensing ports px
and py by regulating the flow through the component from port pa to port pb. A pressure
compensator can be used to maintain a constant flow over a valve by keeping the
pressure drop over the valve constant. The sensing ports py and px are then connected
with the input and output of the valve.
20-sim 4.6 Reference Manual
692
9. Library
The flow through the element is laminar or turbulent depending on the pressure drop
p_ab over pa and pb:
p_ab = pa.p - pb.p;
phi = sign(p_ab) * Cd * A * sqrt( (2/rho) * abs(dp) ) + GLeak * p_ab;
The opening A depends on the pressure drop p_xy over pa and pb:
The maximum opening A_max is determined by the maximum flow phi_max at the
maximum pressure drop p_in_max over the component:
A_max = phi_max / ( Cd * sqrt( (2/rho) * p_in_max ) );
20-sim 4.6 Reference Manual
693
9. Library
The opening is at its maximum value when the differential pressure across it sensing
ports px and py is below the pressure ((k-1)/k)*p_set. If the differential pressure across
it sensing ports px and py is too high, the opening is closed. In between it varies
between fully open and fully closed. The speed of response of the components is
determined by the proportional gain k (typical choose k = 2 to 5). The proportional gain
determines the slope of the valve opening. If k is large the regulator will respond quickly
but also induce oscillations in the circuit.
The valve is implemented with second order spool dynamics. I.e. the spool opening is
characterized by the bandwidth (f) and damping (d).
Interface
Ports
Description
pa, pb
Input and output terminals of the component.
px, py
Sensing terminals of the component. These are used to measure the
pressure and have almost zero flow.
Causality
preferred
pressure out pa
preferred
pressure out pb
preferred
pressure out px
preferred
pressure out py
Parameters
rho
Mass density of the fluid [kg/m3].
GLeak
C onductance of the laminar leakage flows [m3/s.Pa], GLeak >= 0.
Cd
Discharge coefficient [], C d > 0.
p_set
Desired differential pressure over xy (px.p - py.p), [Pa]
p_in_max
maximum inlet pressure, [Pa]
phi_max
maximum
flow at maximum inlet pressure (pa.p) and zero outlet
pressure (pb.p), [m3/s]
f
natural frequency of the second order spool dynamics [Hz]
d
relative damping of the second order spool dynamics [Hz]
k
proportional gain [-]
20-sim 4.6 Reference Manual
694
9. Library
PressureReducingValve-States
Library
Iconic Diagrams\Hydraulics\Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes a pressure reducing valve with lumped volumes. Pressure reducing
valves have the purpose to provide a constant pressure (p_nom), independent of the
upstreamstream pressure. They are used to limit the pressure of a primary circuit to a
desired pressure for a secondary circuit.
Interface
Ports
Description
pa, pb
Both terminals of the hydraulic component.
pt
Pilot
Causality
fixed volume flow out pa
fixed volume flow out pb
Parameters
FlowC ontrolValve\phi
Desired flow [m3/s]
FlowC ontrolValve\p_drop
pressure drop at 95% flow [Pa]
FlowC ontrolValve\GLeak
C onductance of the laminar leakage flow [m3/s.Pa],
Va\V
GLeak >= 0!
Va\B
Volume of oil under pressure [m3]
Va\p_initial
Effective bulk modulus [Pa]
Vb\V
The starting pressure of the volume [Pa]
Vb\B
Volume of oil under pressure [m3]
Vb\p_initial
Effective bulk modulus [Pa]
20-sim 4.6 Reference Manual
695
9. Library
The starting pressure of the volume [Pa]
PressureReliefValve-States
Library
Iconic Diagrams\Hydraulics\Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes a pressure relief valve with lumped volumes. The resistance
depends on the pressure difference:
20-sim 4.6 Reference Manual
696
9. Library
dp = pa.p - pb.p
dp < pclosed => valve closed, only leakage: pa.phi = pb.phi = dp * GLeak
pclosed < dp < popen => working range, i. e. valve partially opened
popen < dp => valve wide open: pa.phi = pb.phi = dp * GOpen
Interface
Ports
Description
pa, pb
Both terminals of the hydraulic component.
Causality
preferred pressure out pa
preferred pressure out pb
Parameters
PressureReliefValve\pclosed
Valve is closed under this pressure [Pa].
PressureReliefValve\popen
Valve is fully open above this pressure [Pa].
PressureReliefValve\GLeak
C onductance of closed valve [m3/s.Pa].
PressureReliefValve\GOpen
C onductance of open valve [m3/s.Pa].
Va1\V
Volume of oil under pressure [m3]
Va\B
Effective bulk modulus [Pa]
Va\p_initial
The starting pressure of the volume [Pa]
Vb\V
Volume of oil under pressure [m3]
Vb\B
Effective bulk modulus [Pa]
Vb\p_initial
The starting pressure of the volume [Pa]
20-sim 4.6 Reference Manual
697
9. Library
ShuttleValve-States
Library
Iconic Diagrams\Hydraulics\Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description - Default
This model describes a loop shuttle valve with lumped volumes. A shuttle valve is a type
of valve which allows fluid to flow through it from one of two sources. Shuttle valves
accept flow from two different sources (pa) and (pb) and divert the highest pressure to a
single outlet port (p_out). Shuttle valves are commonly used in Load Sensing circuits
and at a cylinder to measure the working pressure, as well as Brake circuits. Normal
shuttle valve are mostly ball and poppet types valves.
The default implementation of the shuttle valve assumes ideal behaviour:
p.out.p = maximum(pa.p, pb.p)
pa.phi = pb.phi = 0;
This model sets the flows of the input ports to zero and assumes the output flow is zero
as well. However the output flow is determined by the component that is connected with
the output port. A warning is given when the output flow exceeds 1.0e-5 m3. If flows are
important in your model, use the Spool Dynamics implementation of this model (see
below).
Interface - Default
Ports
Description
pa, pb
Input terminals of the valve.
p_out
Output terminal.
Causality
20-sim 4.6 Reference Manual
698
9. Library
preferred
pressure out pa
preferred
pressure out pb
preferred
pressure
out
p_out
Description - BallDynamics
This model describes a loop shuttle valve with lumped volumes. This implementation is
equal to the default implementation but with modeled dynamics. A small pressure
difference between the inlet ports pa and pb is enough to make the ball switch from one
side to the other. This pressure is called the overlap pressure po.
Interface - BallDynamics
Ports
Description
pa, pb
Input terminals of the valve.
p_out
Output terminal.
Causality
preferred
pressure out pa
preferred
pressure out pb
preferred
pressure
out
p_out
Parameters
rho
Mass density of the fluid [kg/m3].
GLeak
C onductance of the laminar leakage flows [m3/s.Pa], GLeak >= 0.
20-sim 4.6 Reference Manual
699
9. Library
Amax
Maximum valve areas when the valves are open [m2], Amax > 0.
Cd
Discharge coefficient [], C d > 0.
f
Bandwidth of the valve dynamics [Hz], f > 0.
d
Damping of the valve dynamics [], d > 0
p_o
Overlap pressure [Pa].
TwoTwoWayValve-States
Library
Iconic Diagrams\Hydraulics\Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes a 2/2-way directional control valve with second order spool
dynamics and lumped volumes. The flow through the valve is described as laminar/
turbulent flow through an orifice. A detailed description of the valve can be found in
TwoTwoWayDirectionalValve.htm.
Interface
Ports
Description
pa, pb
Both terminals of the valve.
Causality
preferred effort out pa
preferred effort out pb
Inputs
spoolpos
position of the spool valve
spoolpos < 0.5 => valve is closed
spoolpos >= 0.5 => valve is open
20-sim 4.6 Reference Manual
700
9. Library
Parameters
TwoTwoWayDirectionalValve Mass density of the fluid [kg/m3].
\rho
C onductance of the laminar leakage flow [m3/s.Pa],
TwoTwoWayDirectionalValve GLeak >= 0.
\GLeak
Maximum spool valve area when the valve is open [m2],
TwoTwoWayDirectionalValve Amax > 0.
\Amax
Discharge coefficient [], C d > 0.
TwoTwoWayDirectionalValve The valve overlap in closed position [], -1 < overlap < 1.
\C d
Bandwidth of the spool dynamics [Hz], f > 0.
TwoTwoWayDirectionalValve Damping of the spool dynamics [], d > 0.
\overlap
Volume of oil under pressure [m3]
TwoTwoWayDirectionalValve Effective bulk modulus [Pa]
\f
The starting pressure of the volume [Pa]
TwoTwoWayDirectionalValve Volume of oil under pressure [m3]
\d
Effective bulk modulus [Pa]
Va\V
The starting pressure of the volume [Pa]
Va\B
Va\p_initial
Vb\V
Vb\B
Vb\p_initial
20-sim 4.6 Reference Manual
701
9. Library
TwoTwoWayProportionalValve-States
Library
Iconic Diagrams\Hydraulics\Valves
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model describes a 2/2-way proportional control valve with second order spool
dynamics and lumped volumes. The flow through the valve is described as laminar/
turbulent flow through an orifice. A detailed description of the valve can be found in
TwoTwoWayProportionalValve.htm.
Interface
Ports
Description
pa, pb
Both terminals of the valve.
Causality
preferred effort out pa
preferred effort out pb
Inputs
spoolpos
position of the spool valve: 0 =closed, 1 = open
0 <= spoolpos <= 1
Parameters
TwoTwoWayDirectionalValve Mass density of the fluid [kg/m3].
\rho
C onductance of the laminar leakage flow [m3/s.Pa],
TwoTwoWayDirectionalValve GLeak >= 0.
\GLeak
Maximum spool valve area when the valve is open [m2],
TwoTwoWayDirectionalValve Amax > 0.
\Amax
Discharge coefficient [], C d > 0.
The valve overlap in closed position [], -1 < overlap < 1.
20-sim 4.6 Reference Manual
702
9. Library
TwoTwoWayDirectionalValve Bandwidth of the spool dynamics [Hz], f > 0.
\C d
Damping of the spool dynamics [], d > 0.
TwoTwoWayDirectionalValve Volume of oil under pressure [m3]
\overlap
Effective bulk modulus [Pa]
TwoTwoWayDirectionalValve The starting pressure of the volume [Pa]
\f
Volume of oil under pressure [m3]
TwoTwoWayDirectionalValve Effective bulk modulus [Pa]
\d
The starting pressure of the volume [Pa]
Va\V
Va\B
Va\p_initial
Vb\V
Vb\B
Vb\p_initial
Volumes
Accumulator
Library
Iconic Diagrams\Hydraulic\Volumes
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
Accumulators consist of a gas filled chamber, pressurized by an oil filled chamber. The
chambers are separated by a bladder or piston. If oil enters the chamber the gas
chamber will reduce in size and the pressure will rise. If the oil pressures sinks, the gas
chamber will expand and drive oil out of the oil chamber. The accumulator thus acts a a
storage of hydraulic energy. Most accumulators are filled with nitrogen gas which is also
used in this model. You can change to other gasses by changing the gas parameters.
20-sim 4.6 Reference Manual
703
9. Library
Use
When preparing an accumulator for use with the oil at ambient pressure, the gas is precharged to a certain pressure p_pr. The gas chamber will expand its maximum size
which is called the accumulator volume V. During operation, oil will flow into the
chamber and the gas chamber will change size. The oil and gas pressure will be in
balance and indicated with the gas pressure p_gas. The resulting gas volume is name
V_gas. We assume that during pre-charging the gas temperature is constant and equal
to the ambient temperature T_amb. During operation, the gas temperature may change
but the ambient temperature is assumed constant.
Thermal Model
Due to compression, the gas temperature will increase and the accumulator will heat up.
This heat may be lost to the environment. In this model the heat loss is modeled by a
first order transfer function using a thermal time constant tau. If the accumulator is
heated up and the gas keeps its volume, an exponential temperature decrease will be
found. The thermal time constant is the time where the temperature is decreased by
63%. However, the gas will be compressed if the temperature sinks. As a rule of thumb
take for the thermal time constant the time it takes for the temperature to sink by 50%.
By making tau infinite, the accumulator does not convert heat to the environment.The
change is gas volume is then called adiabatic expansion or compression. By making tau
very small, the accumulator instantly convert all heat to the environment.The change is
gas volume is then called isothermal expansion or compression.
20-sim 4.6 Reference Manual
704
9. Library
Gas Laws
The accumulator model is based on the Van der Waals equation for a real gas. This
model takes into account that gas gas particles have finite size and attractive forces. The
Van der Waals model uses the critical gas temperature T_cr and the critical gas
pressure p_cr as parameters. By taking the parameter T_cr = 0 the Van der Waals
model changes into the ideal gas model.
By changing the parameters, the accumulator model can represent various gas models:
1) Ideal Gas: set T_cr = 0
2) Ideal Gas, Adiabatic Expansion: set T_cr = 0 and tau very large (i.e 1.0e9)
3) Ideal Gas, Isothermal Expansion: set T_cr = 0 and tau very small (i.e 1.0e-9)
4) Real Gas: set the critical temperature of the gas (i.e. nitrogen: T_cr = 126.2 {K}) and
set the thermal time constant to a specific value
Interface
Ports
p
Description
hydraulic port
Causality
fixed volume flow
out
Parameters
p_vapour
vapour pressure [Pa].
G
conductance of the accumulator input [m3/s.Pa].
V
max gas volume of the accumulator [m3]
p_pr
pre-charge pressure [Pa]
p_oil
oil pressure at the start [Pa]
T_amb
ambient temperature [K]
tau
thermal time constant [s]
R_s
specific gas constant [J/kg.K]
c_v
specific heat of the gas at constant volume [J/kg.K]
T_cr
critical gas temperature [K]
p_cr
critical gas pressure [Pa]
TankNoRes.em
Library
Iconic Diagrams\Hydraulic\Volumes
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
20-sim 4.6 Reference Manual
705
9. Library
Description
This model represents a tank with a preload pressure against atmosphere. The default
preload pressure of 0 [Pa] means that the tank has atmospheric pressure. A preload
pressure of 1e5 [Pa] means that the tank has an absolute pressure of 2e5 [Pa] etc.
Interface
Ports
Description
p
Causality
fixed pressure out
Parameters
p_preload
tank pressure [Pa]
TankRes
Library
Iconic Diagrams\Hydraulic\Volumes
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model represents a tank with a preload pressure against atmosphere and a
resistance of the tank pipe. The default preload pressure of 0 [Pa] means that the tank
has atmospheric pressure. A preload pressure of 1e5 [Pa] means that the tank has an
absolute pressure of 2e5 [Pa] etc.
There is no check on the validity of laminar flow in this component!
Interface
Ports
Description
p
Causality
fixed volume flow
out p
Parameters
p_preload
tank pressure [Pa]
G
C onductance of laminar resistance [m3/s.Pa]
20-sim 4.6 Reference Manual
706
9. Library
Volume
Library
Iconic Diagrams\Hydraulic\Volumes
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model represents a lumped volume with a constant bulk modulus. If the calculated
pressure falls below the vapour pressure the pressure is NOT limited to the vapour
pressure.
Interface
Ports
Description
p
Causality
preferred
pressure out
Parameters
V
Volume of oil under pressure [m3]
B
Effective bulk modulus [Pa]
p_initial
The starting pressure of the volume [Pa]
ParasiticVolume
Library
Iconic Diagrams\Hydraulic\Volumes
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Hydraulics).
Description
This model represents a tiny volume (default: 1 ml) if the causality of the port is
pressure out, and a zero flow, if the causality is flow out. A parasitic volume is a tiny
volume that can be added to elements to make them more easy to simulate. Some
elements require a pressure as input variable. C oupling two such elements leads to a
mathematical problem: both yield a volume flow as function of the input pressure.
Adding a parasitic volume in between will solve the mathematical problem (the parasitic
volume calculates the pressure) without changing the dynamics much (the volume is
small).
The parasitic element has a likes causality. If two parasitic volumes are coupled, one of
them will get a pressure out causality (representing a tiny volume) and the other will get
a flow out casuality (representing a zero flow). I.e only one of them is a volume and the
other becomes ineffective.
20-sim 4.6 Reference Manual
707
9. Library
Interface
Ports
Description
p
Causality
likes pressure out
Parameters
(hidden)
V
Volume of oil under pressure [m3]
B
Effective bulk modulus [Pa]
p_initial
The starting pressure of the volume [Pa]
9.2.4
Mechanical
Mechanical
The Mechanical library contains components which are very useful for modeling
mechanical systems. The library contains the following sections:
Mechanics
Rotation
Actuators
C omponents
Friction
Gears
Sensors
Translation
2D Small Rotation
3D Small Rotation
Actuators
C omponents
Friction
Sensors
Transmission
20-sim 4.6 Reference Manual
708
9. Library
Rotation
Actuators
AccelerationActuator-Relative
Library
Iconic Diagrams\Mechanical\Rotation\Actuators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation), Block Diagrams.
Description
This model represents an ideal actuator. An angular acceleration input signal is
integrated to an angular velocity difference between its two terminals:
p_high.omega = p_low.omega + int(alpha,omega_initial);
p_low.T = p_high.T = indifferent;
Interface
Ports
Description
p_high, p_low
Both terminals of the Rotation port p.
Causality
fixed
angular
velocity out
Input
alpha
Angular acceleration [rad/s2].
Parameters
omega_initial
Initial angular velocity output of the integration [rad/s].
AccelerationActuator
Library
Iconic Diagrams\Mechanical\Rotation\Actuators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation), Block Diagrams.
Description
This model represents an ideal actuator. An angular acceleration input signal is
integrated to an angular velocity at the rotation port. The actuator is mounted to the
fixed world:
20-sim 4.6 Reference Manual
709
9. Library
p.omega = int(alpha,omega_initial);
p.T = indifferent;
Interface
Ports
Description
p
Rotation port.
Causality
fixed
angular
velocity out
Input
alpha
Angular acceleration [rad/s2].
Parameters
omega_initial
Initial angular velocity at the port [rad/s].
ACMotor-TorqueLoop.em
Note
This model was named ServoMotor.emx in previous versions of 20-sim!
Library
Iconic Diagrams\Mechanical\Rotation\Actuators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Description
Industrial servo motors in the medium to high power range generally consist of an AC electric and drive (the digital controlled current supply of the motor). The drive takes
care of the correct supply of current to let the motor follow every desired path.
Unfortunately the exact implementation and performance of drives and motors is one of
the trade secrets of the commercial motor suppliers. Fortunately modern servo-motors
are designed well enough to be described by general parameters that can be found in
every data sheet.
20-sim 4.6 Reference Manual
710
9. Library
The servo motor model describes a digitally controlled AC -motor that is described by
general parameters. The model is suited for modeling machine dynamics, i.e. models
where the machine behavior is the topic of interest and not the motor itself. For studying
the exact motor behavior (temperature, wear, vibration etc.) other motor models should
be used. A complete description of the motor is given in the second part of this topic.
Interface
Ports
Description
p
Rotation port.
Causality
preferred angular
velocity out p
Inputs
v
velocity setpoint [rad/s]
Parameters
VelocityLimit
Maximum motor speed (>0) [rad/s]
\v_max
Maximum allowed acceleration (>0) [rad/s2]
AccelerationLimit
\a_max
AccelerationLimit
\f_e
PI\K
PI\Ti
Bandwidth drive (half of the sample frequency, >0) [Hz]
Proportional gain []
Integral time constant (>0) [s]
Tracking time constant (>0) [s]
Maximum motor torque (>0) [Nm]
Motor speed where torque gain starts to drop (>0) [rad/s]
PI\Ta
PI\T_max
TorqueGain\vd
TorqueGain\g0
Torque gain at zero motor speed (>0, choose equal to 1 to turn off
torque gain drop []
MotorDynamics\fc Bandwidth drive and motor electronics [Hz]
Inertia\J
Motor inertia [kg.m2/rad]
Variables
There are some variables that can be of interest when inspecting the
servo performance:
PI\error
The error between setpoint and motor velocity [rad/s].
PositionSensor
Motor Angle [rad]
\phi
Motor Speed [rad/s]
VelocitySensor
Motor Acceleration [rad/s2]
\omega
Output Torque [Nm].
Inertia\alpha
Output Power [W].
PowerSensor\T
20-sim 4.6 Reference Manual
711
9. Library
PowerSensor\P
Model
The complete servo motor model is shown below. Every block that is used to form this
model will be explained in the next sections. The model has a velocity input signal v and
a rotary output port p.
The servo motor model can be used in a machine model as shown in the example below.
Blocks
Velocity Limit
Most servo motors have a velocity limit to prevent the motor from damage. This limit
can be set in the velocity VelocityLimit block. If no limit is known choose twice the
nominal velocity.
Acceleration Limit
To prevent the motor from damage, most servos have a maximum acceleration limit.
This limit is very important in a model because it can seriously degrade the systems
performance.
To find the acceleration, the derivative of the input must be calculated. This is done by
means of a first order differentiation with bandwidth f_c. The bandwidth is equal to one
half the of the sample frequency of the velocity control loop. Older drives may have
loops that run on sample frequencies ranging from 100 Hz to 500 Hz. Modern drives can
run the velocity control loop on sample frequencies of 2 kHz or more.
20-sim 4.6 Reference Manual
712
9. Library
To switch the maximum acceleration limit off, choose the maximum acceleration
parameter high enough and choose the bandwidth sufficiently high, preferably 10 times
as large as the bandwidth f_e of the motor electronics (specified in the motor dynamics
block).
PI-Controller
Most servos will use velocity as the setpoint signal. To calculate the desired torque out of
the velocity setpoint, PI-controllers are widely used. For many servos, the controller
parameters can be changed by the user, but this is not a very easy task. Therefore
these servos often offer automatic tuning facilities.
In 20-sim you can use the Optimization toolbox for automatic tuning. A good starting
point is to take the error variable of the PI-controller and minimize it by changing the
controller parameters Kp , Ti and Ta. It is important to realize that automatic tuning will
tune the controller parameters for a certain task. If you run another task, i.e. perform a
simulation with another setpoint, the results may degrade. For varying tasks it is better
to use parameters the give a good response over a wide area of loads. To help the user
find good starting values, the table below shows some motors, loads and corresponding
starting value for the controller parameters.
The user has to find the load that should be driven in terms of the rotational inertia. If
there is a gear that changes the rotary motion to a linear motion this means the load has
to be divided by the square of the gear ratio to get the corresponding load in the
rotational domain. Do not forget to add the inertia of the motor itself! For many gear
ratios the load in terms of rotational inertia will be of the same magnitude as the motor
inertia.
In this model PI-controller with an anti-windup facility is used. This controller is the heart
of the servo motor model. It is therefore important to know something about PI-control.
More information can be found in the PID controllers section of the library.
AC -motors have a limited output torque which is a complex function of the controller
settings, the applied speed, duty cycle, temperature and more. In the servo motor
model simply the torque limit of the PI-controller T_max is used which limits the
generated torque to a maximum. Because this is a simplification of the real behavior,
the maximum torque limit should only be used to inspect what happens to the system
when the motor torque is approaching its maximum value. For a proper evaluation of its
system, the user should also look at the unconstrained torque. Run a simulation and
note the amount of time that the motor runs at a maximum torque. This is called the
duty cycle. Every motor manual will have tables showing duty cycles and the
corresponding chances of overheating.
20-sim 4.6 Reference Manual
713
9. Library
Torque Gain
Standard AC -motors, normally designed to run at base speeds between 850 to 3500
rpm, are not particularly well suited for low-speed operation, as their efficiency drops
with the reduction in speed. They may also be unable to deliver sufficient smooth torque
at low speeds.
An ideal motor will always have a torque gain of 1, i.e. an input signal of 1 Nm will
always result in an output torque of 1 Nm. Most industrial motors have a torque gain that
is only equal to 1 for higher speeds. At low speeds the torque gain will drop due to
electronic limitations. This behavior is represented by the graph below. At speeds below
a drop-off speed vd the torque gain drops linearly to a user defined zero speed torque
gain g0. If no torque gain drop is desired, choose g0 equal to 1.
Motor Dynamics
The electrical circuits of the drive and wiring of the motor have a limited bandwidth. This
is modeled with a first order low-pass filter with a bandwidth f_e. Typical motor
bandwidths vary from 3 kHz tot 20 kHz.
Torque source
In the torque source block the torque signal is converted to an iconic diagram port p.
Inertia
This block describes the rotor inertia. The equations of motion of the inertia are used to
get the angular acceleration without needing derivatives.
Sensors
20-sim 4.6 Reference Manual
714
9. Library
Finally four sensors are available to plot the position, velocity, acceleration and output
power.
Variables
There are some variables in the model that may be of special interest
PI\error
The error between setpoint and motor velocity [rad/s].
PositionSensor
Motor Angle [rad]
\phi
Motor Speed [rad/s]
VelocitySensor
Motor Acceleration [rad/s2]
\omega
Output Torque [Nm].
Inertia\alpha
Output Power [W].
PowerSensor\T
PowerSensor\P
All these variables are output signals of their respective blocks. By inserting extra
outputs in the servo motor model you can use as output signals for usage in other parts
of your model. In the pictures below is shown how to define signals for the torque and
power.
In the servo model define a torque and a power output and connect them.
One level higher you can use these signals for modeling, for example in a high level
control unit.
20-sim 4.6 Reference Manual
715
9. Library
ACMotor
Library
Iconic Diagrams\Mechanical\Rotation\Actuators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Description
This is a model of an industrial AC electric motor with squirrel cage rotor. The motor is
not controlled by a power electric convertor. Instead its performance is directly defined
by a torque speed curve.
The torque speed curve is fully defined by the parameters shown in the picture. The
synchronous speed is defined as:
n = 2 * voltage frequency / no. of poles
Interface
Ports
Description
p
Output axis (Rotation)
Parameters
Ts
start torque (zero speed) [Nm]
n
synchronous speed (zero torque) [rad/s]
Tm
maximum torque [Nm]
nm
speed at maximum torque [rad/s]
Tf
full load torque [Nm]
nf
speed at full load torque [rad/s]
J
motor inertia [kgm^2/rad]
20-sim 4.6 Reference Manual
716
9. Library
DCMotor
Library
Iconic Diagrams\Electric\Actuators
Iconic Diagrams\Mechanical\Electric
Implementations
Default
IR
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric, Electric).
Description - Default
This models represents an ideal DC -motor with no energy loss. The electric port has
separate high and low terminals. The equations are
p1.i = p1_high.i = p1_low.i;
p1.u = p1_high.u - p1_low.u;
The model can have mixed forms of causality
p1.u = k * p2.omega;
p2.T = k * p1.i;
or:
p2.omega = p1.u / k;
p1.i = p2.T / k;
Interface - Default
Ports
Description
p1_high, p1_low
Both terminals of the Electric port p1.
p2
Rotation port.
Causality
mixed
See equations above.
Parameters
k
motor constant [Nm/A]
Description - IR
This models represents an ideal DC -motor with inductance and resistance.
20-sim 4.6 Reference Manual
717
9. Library
The electric port has separate high and low terminals. The equations are
p1.i = p1_high.i = p1_low.i;
p1.u = p1_high.u - p1_low.u;
Interface - IR
Ports
Description
p1_high, p1_low
Both terminals of the Electric port p1.
p2
Rotation port.
Causality
mixed
See equations above.
Parameters
k
motor constant [Nm/A]
L
motor inductance [H]
R
motor resistance [Ohm]
PositionActuator-Relative
Library
Iconic Diagrams\Mechanical\Rotation\Actuators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation), Block Diagrams.
Description
This model represents an ideal actuator. An angle input signal is differentiated by a state
variable filter to an angular velocity difference between its two terminals:
p_high.omega = p_low.omega + dphi/dt;
p_low.T = p_high.T = indifferent;
Differentiation is performed by a state variable filter:
20-sim 4.6 Reference Manual
718
9. Library
The S-domain function of this filter is equal to:
where f is the cut-off frequency. For very high values of f, the output becomes the pure
derivative of the input. High values of f, however, increase simulations times. A good
trade-off is a starting value of 1e5.
Interface
Ports
Description
p_high, p_low
Both terminals of the Rotation port p.
Causality
fixed
angular
velocity out
Input
phi
Angle [rad].
Parameters
f
C ut-off frequency of the differentiation [Hz].
omega_initial
Initial angular velocity output of the differentiation [rad/s].
20-sim 4.6 Reference Manual
719
9. Library
ServoMotor
Library
Iconic Diagrams\Mechanical\Rotation\Actuators
Iconic Diagrams\Mechanical\Translation\Actuators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric).
Description
This is a masked model which opens the Servo Motor Editor when edited. The servo
Motor Editor is a tool that can shows the torque speed plots numerous permanent
magnet motors and can generate a dynamic model from any motor that you select. The
following motor types are supported:
1.
Brush DC
2.
Brushless DC (trapezoidal EMC and square wave currents)
3.
AC synchronous (sinusoidal EMC and sinusoidal currents)
4.
AC synchronous linear (sinusoidal EMC and sinusoidal currents)
Interface
Depending on the type of motor that you have selected, the interface can vary:
DC Brush
Ports
Description
p
Rotation port.
Causality
fixed
rotational
velocity out
Input
i
The input current [A]
DC Brushless
Ports
Description
p
Rotation port.
Causality
fixed
rotational
velocity out
Input
i
The maximum input current [A]
20-sim 4.6 Reference Manual
720
9. Library
AC Synchronous
Ports
Description
p
Rotation port.
Causality
fixed
rotational
velocity out
Input
i_rms
The rms phase current [A]
AC Synchronous Linear
Ports
Description
p
Translation port.
Causality
fixed velocity out
Input
i_rms
The rms phase current [A]
For more information on the parameters an variables of this model is referred to the
Mechatronic Toolbox.
PositionActuator
Library
Iconic Diagrams\Mechanical\Rotation\Actuators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation), Block Diagrams.
Description
This model represents an ideal actuator. An angle input signal is differentiated by a state
variable filter to an angular velocity at the rotation port. The actuator is mounted to the
fixed world:
p.omega = dphi/dt;
p.T = indifferent;
Differentiation is performed by a state variable filter:
20-sim 4.6 Reference Manual
721
9. Library
The S-domain function of this filter is equal to:
where f is the cut-off frequency. For very high values of f, the output becomes the pure
derivative of the input. High values of f, however, increase simulations times. A good
trade-off is a starting value of 1e5.
Interface
Ports
Description
p
Rotation port.
Causality
fixed
angular
velocity out
Input
phi
Angle [rad].
Parameters
f
omega_initial
C ut-off frequency of the differentiation [Hz].
Initial angular velocity at the port [m/s].
20-sim 4.6 Reference Manual
722
9. Library
Steppermotor
Library
Iconic Diagrams\Mechanical\Rotation\Actuators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Description
A stepper motor is a device used to convert electrical pulses into discrete mechanical
rotational movements. The minimum movement, invoked by one pulse, is called the step
angle. The electrical pulses are mostly generated by a pulse generator that converts a
setpoint change in a corresponding amount of pulses. This model describes a
combination of a pulse generator and stepper motor.
At standstill the torque required to deflect the motor a full step is called the holding
torque. The holding torque normally is much higher than required to drive the load, and
thus acts as a strong brake to hold the load. The holding torque as function of the output
angle is shown in the graph below. Around zero angle the curves shows the behavior of
a spring. By changing the input by one step, the force will increase to its maximum and
move the the load.
Motor torque a s function of the angle (holding toque = 1 [N], step angle = [10°] ).
If the subsequent steps are generated fast enough the holding torque will start to
decrease. The maximum holding torque as function of the rotation speed is shown in the
figure below. This force curve is commonly describe as the pull out curve.
20-sim 4.6 Reference Manual
723
9. Library
Pull out curve: maximum generated torque as a function of the rotational speed.
Ports
Description
input
Desired output angle.
p_out
Rotation port.
Causality
fixed current out
p_in
preferred angular
velocity out p_out
Inputs
input
Stepper motor input
Parameters
step_angle
Minimum change of the output axis [deg].
tau
Time constant coil [s].
Th
Holding torque [Nm].
J
Inertia rotor [Nm^2]
B
Relative damping at the stepper motor resonance [].
fmax
Maximum frequency motor (frequency at which the torque gets zero)
[rad/s].
20-sim 4.6 Reference Manual
724
9. Library
Torque-Relative
Library
Iconic Diagrams\Mechanical\Rotation\Actuators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Description
This model represents an ideal actuator. The actuator applies a torque between its two
terminals. This torque can be set to a certain constant value, the angular velocity is
indifferent.
p_high.T = p_low.T = T
Interface
Ports
Description
p_high, p_low
Both terminals of the Rotational port p.
Causality
fixed torque out
Input
T
Torque [Nm].
Torque
Library
Iconic Diagrams\Mechanical\Rotation\Actuators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Description
This model represents an ideal actuator. The actuator is mounted to the fixed world and
applies a torque. The torque can be set to a certain constant value, the angular velocity
is indifferent.
p.T = T;
Interface
Ports
Description
p
Rotation port.
Causality
20-sim 4.6 Reference Manual
725
9. Library
fixed torque out
Parameters
T
Torque [Nm].
TorqueActuator-Relative
Library
Iconic Diagrams\Mechanical\Rotation\Actuators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation), Block Diagrams.
Description
This model represents an ideal actuator. The actuator applies a torque between its two
terminals. This torque can be set to a (fluctuating) value given by the input signal T, the
angular velocity is indifferent.
p_high.T = p_low.T = T
Interface
Ports
Description
p_high, p_low
Both terminals of the Rotation port p.
Causality
fixed torque out
Input
T
Torque [Nm].
20-sim 4.6 Reference Manual
726
9. Library
TorqueActuator
Library
Iconic Diagrams\Mechanical\Rotation\Actuators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation), Block Diagrams.
Description
This model represents an ideal actuator. The actuator is mounted to the fixed world and
applies a torque. The torque can be set to a (fluctuating) value given by the input signal
T, the angular velocity is indifferent.
p.T = T;
Interface
Ports
Description
p
Rotation port.
Causality
fixed torque out
Input
T
Torque [Nm].
Velocity-Relative
Library
Iconic Diagrams\Mechanical\Rotation\Actuators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Description
This model represents an ideal actuator. The actuator applies an angular velocity
difference between its two terminals. This angular velocity can be set to a constant
value omega, the force is indifferent.
p_low.omega = p_high.omega + omega
Interface
Ports
Description
20-sim 4.6 Reference Manual
727
9. Library
p_high, p_low
Both terminals of the Rotation port p.
Causality
fixed
angular
velocity out
Parameter
v
Angular velocity [rad/s].
Velocity
Library
Iconic Diagrams\Mechanical\Rotation\Actuators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Description
This model represents an ideal actuator. The actuator is mounted to the fixed world and
applies an angular velocity. This angular velocity can be set to a certain constant value,
the torque is indifferent.
p.omega = omega;
Interface
Ports
Description
p
Rotation port.
Causality
fixed
angular
velocity out
Parameters
omega
Angular velocity [rad/s].
VelocityActuator-Relative
Library
Iconic Diagrams\Mechanical\Rotation\Actuators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation), Block Diagrams.
20-sim 4.6 Reference Manual
728
9. Library
Description
This model represents an ideal actuator. The actuator applies an angular velocity
difference between its two terminals. This angular velocity can be set to a (fluctuating)
value given by the input signal v, the force is indifferent.
p_low.omega = p_high.omega + omega
Interface
Ports
Description
p_high, p_low
Both terminals of the Rotation port p.
Causality
fixed
angular
velocity out
Input
omega
Angular velocity [rad/s].
VelocityActuator
Library
Iconic Diagrams\Mechanical\Rotation\Actuators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation), Block Diagrams.
Description
This model represents an ideal actuator. The actuator is mounted to the fixed world and
applies an angular velocity. This angular velocity can be set to a (fluctuating) value
given by the input signal omega, the torque is indifferent.
p.omega = omega;
Interface
Ports
Description
p
Rotation port.
Causality
fixed
angular
velocity out
Input
20-sim 4.6 Reference Manual
729
9. Library
omega
Angular velocity [rad/s].
Components
Backlash
Library
Iconic Diagrams\Mechanical\Rotation\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Description
This model represents backlash by a spring damper system equivalent to the
translational backlash model. The port p of this model has separate high and low
terminals. The equations are:
p.T = p_high.T = p_low.T
p.omega = p_high.omega - p_low.omega
Interface
Ports
Description
p_high, p_low
Both terminals of port p (Rotation).
Causality
fixed torque out
Parameters
s
Interval of the play [rad]
k1
Stiffness in the play [Nm/rad]
k2
Stiffness outside the play [Nm/rad]
d1
Damping inside the play [Nms/rad]
d2
Damping outside the play [Nms/rad]
ep
Relative round off (1e-6 -> sharp edges, 1e-2 -> smoother)
Parameters
x_initial
Initial position in the play [rad], -s/2 < x_initial < s/2
20-sim 4.6 Reference Manual
730
9. Library
Bearing
Library
Iconic Diagrams\Mechanical\Rotation\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Description
In this model bearing friction is represented as linear viscous friction. The model has
only one initial port p defined. Because any number of connections can be made,
successive ports are named p1, p2, p3 etc. 20-sim will automatically create equations
such that the resulting torque p.T is equal to the sum of the torques of all connected
ports p1 .. pn. The angular velocities of all connected ports are equal to p.omega. The
model can have an torque out as well as an angular velocity out causality. In the last
case the constitutive equation, as shown below, is simply inverted:
p.T = sum(p1.T, p2.T, ....)
p.omega = p1.omega = p2.omega = ....
Torque out causality:
p.T = d * p.omega;
Angular velocity out causality:
p.omega = p.T / d;
Interface
Ports
Description
p[any]
Any number of connections can be made (Rotation).
Causality
indifferent
Parameters
d
Damping [Nms/rad]
Brake
Library
Iconic Diagrams\Mechanical\Rotation\C omponents
Implementations
C
20-sim 4.6 Reference Manual
731
9. Library
V
CV
SC VS
LuGre
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Introduction
The brake models represent a disk brake or other type of brake where a rotation is
stopped by applying a friction force. The amount of friction depends on the normal force
that is applied and the friction function that is used. The normal force is given by the
input signal Fn. The brake is mounted to the fixed world.
The model has only one initial port p defined. Because any number of connections can
be made, successive ports are named p1, p2, p3 etc. 20-sim will automatically create
equations such that the resulting torque p.T is equal to the sum of the torques of all
connected ports p1 .. pn. The angular velocities of all connected ports are equal to
p.omega.
p.T = sum(p1.T, p2.T, ....)
p.omega = p1.omega = p2.omega = ....
Due to the use of normal force, the brake models all have a fixed torque out causality.
The constitutive equations are therefore described as:
p.T = Fn * f(p.omega);
with f the friction function.
Description - C
This model represents a brake with braking force described as coulomb friction. The
brake is mounted to the fixed world. The amount of friction depends on the normal force
that is applied:
p.T = Fn*mu_c*tanh(slope*p.omega);
Fn: normal force (given by the input signal Fn)
mu_c: the coulomb friction coefficient
slope: the steepness of the coulomb friction curve.
20-sim 4.6 Reference Manual
732
9. Library
Interface - C
Ports
Description
p[any]
Any number of connections can be made (Rotation).
Causality
Fixed torque out
Input
Fn
Normal force [N]
Parameters
mu_c
C oulomb friction coefficient [m]
slope
Steepness of C oulomb friction curve [s/rad]
Description - V
This model represents a brake with braking force described as viscous friction. The
brake is mounted to the fixed world. The amount of friction depends on the normal force
that is applied:
p.T = Fn*mu_v*p.omega;
Fn: normal force (given by the input signal Fn)
mu_v: the viscous friction coefficient
20-sim 4.6 Reference Manual
733
9. Library
Interface - V
Ports
Description
p[any]
Any number of connections can be made (Rotation).
Causality
Fixed torque out
Input
Fn
Normal force [N]
Parameters
mu_v
Viscous friction coefficient [m.s/rad]
Description - CV
This model represents a brake with braking force described as coulomb plus viscous
friction. The brake is mounted to the fixed world. The amount of friction depends on the
normal force that is applied:
p.T = Fn*(mu_c*tanh(slope*p.omega) + mu_v*p.omega);
Fn: normal force (given by the input signal Fn)
mu_v: the viscous friction coefficient
mu_c: the coulomb friction coefficient
slope: the steepness of the coulomb friction curve.
20-sim 4.6 Reference Manual
734
9. Library
Interface - CV
Ports
Description
p[any]
Any number of connections can be made (Rotation).
Causality
Fixed torque out
Input
Fn
Normal force [N]
Parameters
mu_v
Viscous friction coefficient [ms/rad]
mu_v
C oulomb friction coefficient [m]
slope
Steepness of C oulomb friction curve [s/rad]
Description - SCVS
This model represents a brake with braking force described as static plus coulomb plus
viscous plus Stribeck friction. The brake is mounted to the fixed world. The amount of
friction depends on the normal force that is applied:
p.T = Fn *
(( mu_c + (mu_st*abs(tanh( slope*p.omega )) - mu_c)
* exp( -((p.omega / v_st)^2 )) ) * sign(p.omega)
+ mu_v * p.omega);
Fn: normal force (given by the input signal Fn)
mu_s: the static friction coefficient
mu_v: the viscous friction coefficient
mu_c: the coulomb friction coefficient
slope: the steepness of the coulomb and static friction curve.
v_st: the characteristic Stribeck velocity.
20-sim 4.6 Reference Manual
735
9. Library
Interface - SCVS
Ports
Description
p[any]
Any number of connections can be made (Rotation).
Causality
Fixed torque out
Input
Fn
Normal force [N]
Parameters
mu_s
Static friction coefficient [m]
mu_v
Viscous friction coefficient [m.s/rad]
mu_c
C oulomb friction coefficient [m]
slope
Steepness of C oulomb friction curve [s/rad]
v_st
C haracteristic Stribeck velocity [rad/s]
Description - LuGre
This model represents a brake with braking force described by the LuGre friction model.
The brake is mounted to the fixed world. The amount of friction depends on the normal
force that is applied:
p.T = FN*f_lg(p.omega);
Fn: normal force (given by the input signal Fn)
f_lg: the LuGre friction model
Interface - LuGre
Ports
Description
p[any]
Any number of connections can be made (Rotation).
Causality
Fixed Torque out
20-sim 4.6 Reference Manual
736
9. Library
Input
Fn
Normal force [N]
Parameters
mu_c
C oulomb friction coefficient
mu_s
Static friction coefficient [m]
mu_v
Viscous friction coefficient [ms/rad]
v_st
C haracteristic Stribeck velocity [rad/s]
mu_k
rotational stiffness coefficient at zero speed [m/rad]
Clutch
Iconic Diagrams\Mechanical\Rotation\C omponents
Implementations
C
V
CV
SC VS
LuGre
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Introduction
The clutch models model represent friction relative to other objects. The amount of
friction depends on the normal force that is applied and the friction function that is used.
The normal force is given by the input signal FN.
The port p of the clutch model has separate high and low terminals. The equations are:
p.T = p_high.T = p_low.T
p.omega = p_high.omega - p_low.omega
Due to the use of normal force, the clutch models all have a fixed torque out causality.
The constitutive equations are therefore described as:
p.T = Fn * f(p.omega);
with f the friction function.
20-sim 4.6 Reference Manual
737
9. Library
Description - C
This model represents bearing with friction force described as coulomb friction. The
amount of friction depends on the normal force that is applied and the friction function
that is used:
p.T = Tc*tanh(slope*p.omega);
Tc: coulomb friction
slope: the steepness of the coulomb friction curve.
Interface - C
Ports
Description
p
Both terminals of port p (Rotation).
Causality
Fixed torque out
Input
Fn
Normal force [N]
Parameters
Tc
C oulomb friction [N.m]
slope
Steepness of C oulomb friction curve [s/rad]
Description - V
This model represents a clutch with friction force described as viscous friction. The
amount of friction depends on the normal force that is applied and the friction function
that is used:
p.T = Fn*mu_v*p.omega;
Fn: normal force (given by the input signal Fn)
mu_v: the viscous friction coefficient
20-sim 4.6 Reference Manual
738
9. Library
Interface - V
Ports
Description
p_high, p_low
Both terminals of port p (Rotation).
Causality
Fixed torque out
Input
Fn
Normal force [N]
Parameters
mu_v
Viscous friction coefficient [m.s/rad]
Description - CV
This model represents a clutch with friction force described as coulomb plus viscous
friction. The amount of friction depends on the normal force that is applied and the
friction function that is used:
p.T = Fn*(Tc*tanh(slope*p.omega) + mu_v*p.omega);
Fn: normal force (given by the input signal Fn)
mu_v: the viscous friction coefficient
Tc: the coulomb friction coefficient
slope: the steepness of the coulomb friction curve.
20-sim 4.6 Reference Manual
739
9. Library
Interface - CV
Ports
Description
p_high, p_low
Both terminals of port p (Rotation).
Causality
Fixed torque out
Input
Fn
Normal force [N]
Parameters
mu_v
Viscous friction coefficient [m.s/rad]
Tc
C oulomb friction [N.m]
slope
Steepness of C oulomb friction curve [s/rad]
Description - SCVS
This model represents a clutch with friction force described as static plus coulomb plus
viscous plus Stribeck friction. The amount of friction depends on the normal force that is
applied and the friction function that is used:
p.T = Fn *
(( Tc + (mu_st*abs(tanh( slope*p.omega )) - Tc)
* exp( -((p.omega / v_st)^2 )) ) * sign(p.omega)
+ mu_v * p.omega);
Fn: normal force (given by the input signal Fn)
mu_s: the static friction coefficient
mu_v: the viscous friction coefficient
Tc: the coulomb friction coefficient
slope: the steepness of the coulomb and static friction curve.
v_st: the characteristic Stribeck velocity.
20-sim 4.6 Reference Manual
740
9. Library
Interface - SCVS
Ports
Description
p_high, p_low
Both terminals of port p (Rotation).
Causality
Fixed torque out
Input
Fn
Normal force [N]
Parameters
mu_s
Static friction coefficient [m]
mu_v
Viscous friction coefficient [m.s/rad]
Tc
C oulomb friction [N.m]
slope
Steepness of C oulomb friction curve [s/rad]
v_st
C haracteristic Stribeck velocity [rad/s]
Description - LuGre
This model represents a clutch with friction force described by the LuGre friction model.
The amount of friction depends on the normal force that is applied and the friction
function that is used:
p.T = FN*f_lg(p.omega);
Fn: normal force (given by the input signal Fn)
f_lg: the LuGre friction model
Interface- LuGre
Ports
Description
p_high, p_low
Both terminals of port p (Rotation).
Causality
Fixed torque out
20-sim 4.6 Reference Manual
741
9. Library
Input
Fn
Normal force [N]
Parameters
Tc
C oulomb friction coefficient
mu_s
Static friction coefficient [m]
mu_v
Viscous friction coefficient [m.s/rad]
v_st
C haracteristic Stribeck velocity [rad/s]
mu_k
rotational stiffness coefficient at zero speed [m/rad]
Damper
Library
Iconic Diagrams\Mechanical\Rotation\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Description
This model represents a linear damper. It can have an torque out as well as an angular
velocity out causality. In the last case the constitutive equation, as shown below, is
simply inverted. The port p of the damper model has separate high and low terminals.
The equations are:
p.T = p_high.T = p_low.T
p.omega = p_high.omega - p_low.omega
Torque out causality:
p.T = d * p.omega;
Angular velocity out causality:
p.omega = p.T / d;
Interface
Ports
Description
p_high, p_low
Both terminals of the Rotation port p.
Causality
indifferent
Parameters
d
damping [Nms/rad]
20-sim 4.6 Reference Manual
742
9. Library
FixedWorld
Library
Iconic Diagrams\Mechanical\Rotation\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Description
This model represents the fixed world (angular velocity = 0). The model has only one
initial port p defined. Because any number of connections can be made, successive ports
are named p1, p2, p3 etc. which gives the constitutive equations:
p1.omega = p2.omega = .. = pn.omega = 0;
p1.T = free; p2.T = free; ..; pn.T = free;
Interface
Ports
Description
p [any]
Any number of connections can be made.
Causality
Fixed
angular All ports have a fixed angular velocity out causality.
velocity out
Friction
Iconic Diagrams\Mechanical\Rotation\C omponents
Implementations
C
V
CV
SC VS
LuGre
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Introduction
The friction model represent bearing friction with various friction models. The model
have only one initial port p defined. Because any number of connections can be made,
successive ports are named p1, p2, p3 etc. 20-sim will automatically create equations
such that the resulting force p.F is equal to the sum of the forces of all connected ports
p1 .. pn. The velocities of all connected ports are equal to p.v.
20-sim 4.6 Reference Manual
743
9. Library
p.F = sum(p1.F, p2.F, ....)
p.v = p1.v = p2.v = ....
Description - C
This model represents a bearing with friction torque described as coulomb friction:
p.T = Tc*tanh(slope*p.omega);
Tc: the coulomb friction
slope: the steepness of the coulomb friction curve.
Interface - C
Ports
Description
p[any]
Any number of connections can be made (Rotation).
Causality
Fixed torque out
Parameters
Tc
C oulomb friction [N.m]
slope
Steepness of C oulomb friction curve [s/rad]
Description - V
This model represents a bearing with friction force described as viscous friction:
p.T = d*p.omega;
d: the viscous damping
20-sim 4.6 Reference Manual
744
9. Library
Interface - V
Ports
Description
p[any]
Any number of connections can be made (Rotation).
Causality
Fixed torque out
Input
Fn
Normal force [N]
Parameters
d
Viscous friction torque or damping [N.m.s/rad]
Description - CV
This model represents a bearing with friction force described as coulomb plus viscous
friction:
p.T = Tc*tanh(slope*p.omega) + d*p.omega;
d: the viscous damping
Tc: the coulomb friction
slope: the steepness of the coulomb friction curve.
20-sim 4.6 Reference Manual
745
9. Library
Interface - CV
Ports
Description
p[any]
Any number of connections can be made (Rotation).
Causality
Fixed torque out
Input
Fn
Normal force [N]
Parameters
mu_v
Viscous damping [N.m.s/rad]
Tc
C oulomb friction [N.m]
slope
Steepness of C oulomb friction curve [s/rad]
Description - SCVS
This model represents a bearing with friction force described as static plus coulomb plus
viscous plus Stribeck friction:
p.T = (( Tc + (Tst*abs(tanh( slope*p.omega )) - Tc)
* exp( -((p.omega / v_st)^2 )) ) * sign(p.omega)
+ d * p.omega);
Tst: the static friction
d: the viscous damping
Tc: the coulomb friction
slope: the steepness of the coulomb and static friction curve.
v_st: the characteristic Stribeck velocity.
Interface - SCVS
Ports
Description
p[any]
Any number of connections can be made (Rotation).
Causality
20-sim 4.6 Reference Manual
746
9. Library
Fixed torque out
Input
Fn
Normal force [N]
Parameters
Tst
Static friction torque [N.m]
d
Viscous friction torque or damping [N.m.s/rad]
Tc
C oulomb friction [N.m]
slope
Steepness of C oulomb friction curve [s/rad]
v_st
C haracteristic Stribeck velocity [rad/s]
Description - LuGre
This model represents a bearing with friction force described by the LuGre friction
model:
p.T = f_lg(p.omega);
f_lg: the LuGre friction model
Interface- LuGre
Ports
Description
p[any]
Any number of connections can be made (Rotation).
Causality
Fixed torque out
Input
Fn
Normal force [N]
Parameters
Tc
C oulomb friction [N.m]
Tst
Static friction torque [m]
d
Viscous damping [N.m.s/rad]
v_st
C haracteristic Stribeck velocity [rad/s]
c
Stiffness at zero speed [N.m/rad]
20-sim 4.6 Reference Manual
747
9. Library
Inertia
Library
Iconic Diagrams\Mechanical\Rotation\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Description
This model represents an ideal rotational inertia. The element has a preferred angular
velocity out causality. The corresponding constitutive equations then contain an
integration. The element can also have the non-preferred torque out causality. The
constitutive equations then contain a derivation. The model has only one initial port p
defined. Because any number of connections can be made, successive ports are named
p1, p2, p3 etc. 20-sim will automatically create equations such that the resulting torque
p.T is equal to the sum of the torques of all connected ports p1 .. pn and that the angular
velocities of all connected prots is equal to p.omega.
p.T = sum(p1.T, p2.T, ....)
p.omega = p1.omega = p2.omega = ....
angular velocity out causality (preferred):
alpha = p.T/J;
p.omega = int(alpha);
phi = int(p.omega);
torque out causality:
alpha = ddt(p.omega);
p.T = J*alpha;
phi = int(p.omega);
Interface
Ports
Description
p[any]
Any
number
of
connections
can
be
made
(Rotation).
Causality
preferred angular velocity out
An torque out causality results in a derivative
constitutive equation.
Variables
phi
angle [rad]
alpha
angular acceleration [rad/s^2]
Parameters
J
moment of inertia [kgm^2]
20-sim 4.6 Reference Manual
748
9. Library
Initial Values
p.omega_initial
The initial velocity of the inertia [rad/s].
phi_initial
The initial angle of the inertia [rad].
Node
Library
Iconic Diagrams\Mechanical\Rotation\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Description
This node model represents a structural connection between two (or more) shafts, where
the velocity of all connected shafts is equal. The model has only one initial port p
defined. Because any number of connections can be made, successive ports are named
p1, p2, p3 etc.
Interface
Ports
Description
p [any]
Any number of connections can be made (Rotation).
Spring
Library
Iconic Diagrams\Mechanical\Rotation\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Description
This model represents an ideal rotational spring. The element has a preferred torque out
causality. The corresponding constitutive equations then contain an integration. The
element can also have the non-preferred angular velocity out causality. The constitutive
equations then contain a derivation. The port p of the spring model has separate high
and low terminals. The equations are:
p.T = p_high.T = p_low.T
p.omega = p_high.omega - p_low.omega
torque out causality (preferred):
20-sim 4.6 Reference Manual
749
9. Library
phi = int(p.omega);
p.T = c * phi;
angular velocity out causality:
p.omega = ddt(phi);
phi = p.T/k;
Interface
Ports
Description
p_high, p_low
Both terminals of the Rotational port p.
Causality
preferred torque out
An angular velocity out causality
results
in
a
derivative constitutive equation.
Variables
phi
torsion of the spring [rad]
Parameters
c
Stiffness [Nm/rad]
Initial Values
phi_initial
The initial torsion of the spring [rad].
SpringDamper
Library
Iconic Diagrams\Mechanical\Rotation\C omponents
Implementations
Default
Stiffness
Frequency
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description - Default
This model represents an ideal rotational spring with damper. The element has a
preferred torque out causality. The corresponding constitutive equations then contain an
integration. The element can also have the non-preferred angular velocity out causality.
The constitutive equations then contain a derivation. The port p of the spring model has
separate high and low terminals. The equations are:
p.T = p_high.T = p_low.T
p.omega = p_high.omega - p_low.omega
Torque out causality (preferred):
20-sim 4.6 Reference Manual
750
9. Library
phi = int(p.omega);
p.T = c * phi + d*p.omega;
Angular velocity out causality:
p.omega = ddt(phi);
phi = (p.T - d*p.omega)/c;
Interface - Default
Ports
Description
p_high
Two ports of the spring (Rotation).
p_low
Causality
preferred torque out
An angular velocity out causality
results
in
a
derivative constitutive equation.
Variables
phi
torsion of the spring [rad]
Parameters
c
Rotational stiffness [Nm /rad]
d
Damping [Nms/rad]
Initial Values
phi_initial
The initial torsion of the spring [rad].
Description - Stiffness
This model represents an ideal rotational spring with damper. The damping value (d) is
calculated on the basis of a known stiffness (c), relative damping (b) and reference
inertia (J). The inertia is only used to compute the damping (no actual mass is used in
this component).
The element has a preferred torque out causality. The corresponding constitutive
equations then contain an integration. The element can also have the non-preferred
angular velocity out causality. The constitutive equations then contain a derivation. The
port p of the spring model has separate high and low terminals. The equations are:
p.T = p_high.T = p_low.T
p.omega = p_high.omega - p_low.omega
Torque out causality (preferred):
phi = int(p.omega);
p.F = c * phi + d*p.omega;
d = 2*b*sqrt(c*J);
Angular velocity out causality:
20-sim 4.6 Reference Manual
751
9. Library
p.omega = ddt(phi);
phi = (p.T - d*p.omega)/c;
d = 2*b*sqrt(c*J);
Interface - Stiffness
Ports
Description
p_high
Two ports of the spring (Rotation).
p_low
Causality
preferred torque out
An angular velocity out causality
results
in
a
derivative constitutive equation.
Variables
phi
torsion of the spring [rad]
d
damping [Nms/rad]
Parameters
c
Rotational stiffness [Nm /rad]
b
Relative damping []
J
Moment of inertia [kgm^2]
Initial Values
phi_initial
The initial torsion of the spring [rad].
Description - Frequency
This model represents an ideal rotational spring with damper. The stiffness (c) is
calculated on basis of a known resonance frequency (f). The damping value (d) is
calculated on the basis of the stiffness, relative damping (b) and reference inertia (J).
The inertia is only used to compute the damping (no actual mass is used in this
component).
The element has a preferred torque out causality. The corresponding constitutive
equations then contain an integration. The element can also have the non-preferred
angular velocity out causality. The constitutive equations then contain a derivation. The
port p of the spring model has separate high and low terminals. The equations are:
p.T = p_high.T = p_low.T
p.omega = p_high.omega - p_low.omega
Torque out causality (preferred):
phi = int(p.omega);
p.T = c * phi + d*p.omega;
c = J*(2*pi*f)^2;
d = 2*b*sqrt(c*J);
Angular velocity out causality:
20-sim 4.6 Reference Manual
752
9. Library
p.omega = ddt(phi);
phi = (p.T - d*p.omega)/c;
c = J*(2*pi*f)^2;
d = 2*b*sqrt(c*J);
Interface - Frequency
Ports
Description
p_high
Two ports of the spring (Rotation).
p_low
Causality
preferred torque out
An angular velocity out causality
results
in
a
derivative constitutive equation.
Variables
phi
torsion of the spring [rad]
c
rotational stiffness [Nm /rad]
d
damping [Nms/rad]
Parameters
f
Resonance frequency [Hz]
b
Relative damping []
J
Moment of inertia [kgm^2]
Initial Values
phi_initial
The initial torsion of the spring [rad].
Unbalance
Library
Iconic Diagrams\Mechanical\Rotation\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Description
This model represents an unbalanced mass with an offset r to the axis of rotation and a
starting angle phi_initial.
20-sim 4.6 Reference Manual
753
9. Library
The mass will act as an inertia J with a gravity induced disturbance torque:
J = r^2 * m;
alpha = (p.T + m*r*g_n*sin(phi))/ J;
p.omega = int (alpha);
phi = int (p.omega, phi_initial);
The element has a preferred angular velocity out causality. The corresponding
constitutive equations then contain an integration. The element can also have the nonpreferred torque out causality. The constitutive equations then contain a derivation. The
model has only one rotation port p defined. Because any number of connections can be
made, successive ports are named p1, p2, p3 etc. 20-sim will automatically create
equations such that the resulting torque p.T is equal to the sum of the torques of all
connected ports p1 .. pn and that the angular velocities of all connected ports is equal to
p.omega.
p.T = sum(p1.T, p2.T, ....)
p.omega = p1.omega = p2.omega = ....
Interface
Ports
Description
p[any]
Any
number
of
connections
can
be
made
(Rotation).
Causality
preferred angular velocity out
An torque out causality results in a derivative
constitutive equation.
Variables
J
moment of inertia [kgm^2]
phi
angle [rad]
alpha
angular acceleration [rad/s^2]
Parameters
20-sim 4.6 Reference Manual
754
9. Library
m
mass [kg]
r
distance of mass from center line of rotation [m]
Initial Values
p.omega_initial
The initial velocity of the inertia [rad/s].
phi_initial
The starting angle of the mass [rad].
ZeroTorque
Library
Iconic Diagrams\Mechanical\Rotation\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Description
This model can be used to connect any open end of another model that is not connected
to the fixed world. It generates a fixed torque of 0 N while the angular velocity is free:
p.omega = indifferent;
p.T = 0;
Interface
Ports
Description
p
rotation port
Causality
Fixed torque out
20-sim 4.6 Reference Manual
755
9. Library
Gears
BeltPulley
Library
Iconic Diagrams\Mechanical\Rotation\Gears
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation/Translation).
Description
This models represents a belt and pulley. The connection to the pulley is through the
rotation port p_rot. The connection to the belt is through the translation port p_trans.
The model is ideal, i.e. there are no compliances or inertias. The causality of this model
is always mixed: torque out & velocity out or angular velocity out & force out:
p_rot.T = radius * p_trans.F
p_trans.v = radius * p_rot.omega
or:
p_trans.F = 1/radius * p_rot.T
p_rot.omega = 1/radius * p_trans.v
Interface
Ports
Description
p_rot
Rotation port.
p_trans
Translation port.
Causality
p_rot
notequal
p_trans
Parameters
radius
pulley radius [m]
Cam-Wizard
Library
Iconic Diagrams\Mechanical\Rotation\Gears
Iconic Diagrams\Mechanical\Translation\Transmission
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation/Translation).
Description
This is a masked model which opens the C am Wizard when edited. Depending on the
selections entered, various cam motion profiles can be generated.
20-sim 4.6 Reference Manual
756
9. Library
Interface
Ports
Description
p_in
Driving axis (Rotation)
p_out
Output port with resulting motion (Rotation or Translation)
Parameters
stroke
amplitude of resulting motion
start_angle
start angle motion
stop_angle
angle when the maximum is reached
return_angle
start angle of the return motion
end_angle
finish angle of the return motion
CamRod
Library
Iconic Diagrams\Mechanical\Rotation\Gears
Iconic Diagrams\Mechanical\Translation\Transmission
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description
This models represents a cam and rod mechanism. If the input shaft is rotating with a
constant speed, the output motion is a pure sinusoidal.
The mechanism is ideal, i.e., it does not have inertia, friction or geometrical limitations.
It has one rotation port (p_in) and one translation port (p_out). The causality of this
model is always mixed: one port has a force out causality while the other has a velocity
out causality:
p_in.T = i * p_out.F
p_out.v = i * p_in.omega
The transmission ratio (i) is the ratio of the velocities of both ports (in fact a sinusoidal
function of the shaft angle).
20-sim 4.6 Reference Manual
757
9. Library
Interface
Ports
Description
p_in
Driving axis (Rotation)
p_out
Output port with resulting motion (Translation)
Causality
fixed torque
out
p_in
fixed velocity out
p_out
Parameters
stroke
Stroke of the translation port (is equal to half the length of the rod).
CrankRod
Library
Iconic Diagrams\Mechanical\Rotation\Gears
Iconic Diagrams\Mechanical\Translation\Transmission
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description
This models represents a crank and rod mechanism. The mechanism is ideal, i.e., it
does not have inertia, friction or geometrical limitations. It has one rotation port (p_in)
and one translation port (p_out). The causality of this model is always mixed: one port
has a force out causality while the other has a velocity out causality:
p_in.T = i * p_out.F
p_out.v = i * p_in.omega
The transmission ratio (i) is the ratio of the velocities of both ports. It is a function of the
shaft angle, the crank length and the rod length.
20-sim 4.6 Reference Manual
758
9. Library
Interface
Ports
Description
p_in
Driving axis (Rotation)
p_out
Output port with resulting motion (Translation)
Causality
fixed torque
out
p_in
fixed velocity out
p_out
Parameters
crank_length
C rank length [m]
rod_length
Rod length [m]
DifferentialGear
Library
Iconic Diagrams\Mechanical\Rotation\Gears
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Description
A differential gear is well known for its use in automotive mechanics. It transfers power
from the engine to the wheels, dividing the force equally between them but permitting
them to follow paths of different lengths when turning a corner.
20-sim 4.6 Reference Manual
759
9. Library
When p3 is the drive-shaft and p1 and p3 the shafts connected to the wheels, the
constitutive equations for this model are:
p3.omega*2*i = p1.omega + p2.omega;
p1.T = p2.T = p3.T/(2*i);
with i the gear ratio. The gear ratio is equal to the diameter of the drive shaft pinion
divided by the diameter of the ring gear, which makes it equivalent to the angular
velocity of the drive shaft divided by the average angular velocity of the wheel shafts:
i = p3.omega / ((p1.omega + p2.omega)/2);
Interface
Ports
Description
p1
drive shaft port (Rotation)
p2,p3
driven shafts ports (Rotation)
Parameters
i
gear ratio []
20-sim 4.6 Reference Manual
760
9. Library
Differential
Library
Iconic Diagrams\Mechanical\Rotation\Gears
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Description
This model is equivalent to the fork model of the Translation library. It represents a
special type of node where the torques are equal and the angular velocities are added:
p3.omega = p1.omega + p2.omega;
p1.T = p2.T = p3.T;
This model can for example be used for actuators that generate a torque difference.
With the differential model an equivalent model can be found with the actuator attached
to the fixed world:
Interface
Ports
Description
p1,p2,p3
Rotation ports.
Gear
Library
Iconic Diagrams\Mechanical\Rotation\Gears
Implementations
Ideal
20-sim 4.6 Reference Manual
761
9. Library
Lossy
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Description - Ideal
This models represents any type of gearbox with two counter rotating shafts. The gear is
ideal, i.e., it does not have inertia or friction. The gear has one fast moving shaft and
one slow moving shaft. The gearbox has a reduction of i : 1 and thus a transmission
ratio of 1/i.
The causality of this model is always mixed: one port has a torque out causality while
the other has an angular velocity out causality:
p_in.T = -1/i * p_out.T
p_out.omega = -1/i * p_in.omega
or:
p_out.T = -i * p_in.T
p_in.omega = -i * p_out.omega
Interface - Ideal
Ports
Description
p_in
p_out
Input port
Output port
Causality
p_in not
p_out
equal
Parameters
i
gearbox reduction, i > 1
Description - Efficiency
This models represents any type of gearbox with two counter rotating shafts. The
gearbox has a reduction of i : 1 and thus a transmission ratio of 1/i.
p_in.omega = -i * p_out.omega
Unlike the model of an ideal gearbox, this model includes power loss. The power loss is
represented by the efficiency, where the efficiency is defined as the output power
divided by the input power:
eff = Pout / Pin
The efficiency is a value between zero and one and given by the gearbox manufacturer.
If you do no know the value, a good guess is a power loss of 3% per stage (eff = 0.97).
If your gearbox for example contains three stages, you can set the efficiency as:
eff = 0.97*0.97*0.97 = 0.91
20-sim 4.6 Reference Manual
762
9. Library
Interface - Efficiency
Ports
Description
p_in
p_out
Input port
Output port
Causality
p_in not
p_out
equal
Parameters
i
gearbox reduction [-], i > 1
eff
gearbox efficiency [-]
Description - Lossy
This models represents any type of gearbox with two counter rotating shafts. The
gearbox has a reduction of i : 1 and thus a transmission ratio of 1/i.
p_in.omega = -i * p_out.omega
Unlike the model of an ideal gearbox, this model includes rotational inertia and power
loss. The inertia is defined at the input axis. If the gearbox manufacturer gives the
inertia at the output axis you can calculate the inertia at input axis as:
Jinput = Joutput/i^2
The power loss is represented by the efficiency, where the efficiency is defined as the
output power divided by the input power:
eff = Pout / Pin
The efficiency is a value between zero and one and given by the gearbox manufacturer.
If you do no know the value, a good guess is a power loss of 3% per stage (eff = 0.97).
If your gearbox for example contains three stages, you can set the efficiency as:
eff = 0.97*0.97*0.97 = 0.91
Interface - Lossy
Ports
Description
p_in
Input port
p_out
Output port
Causality
preferred angular
velocity out p_in
preferred angular
velocity out p_out
Parameters
20-sim 4.6 Reference Manual
763
9. Library
i
gearbox reduction [-], i > 1
J
moment of inertia [kgm^2]
eff
gearbox efficiency [-]
PlanetaryGear
Library
Iconic Diagrams\Mechanical\Rotation\Gears
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Description
A planetary gear is well known for its use in automotive mechanics. It transfers power
from a sun wheel to the planet wheels and the ring. In standard planetary gears, the
planet wheels are connected by a carriage. I.e the gear has three rotation ports: the
sun, the carriage and the ring.
The model that is used here is ideal. I.e. there is only power flow between the three
axes. No internal dynamics or friction are incorporated. If the inertia cannot be
neglected, you can easily add inertia models to the ports of the planetary gear model.
The number of teeth of the planet wheels are uniquely defined by the number of teeth of
the sun wheel and the ring by:
zp = (zr - zs)/2;
Therefore the ratio between the sun teeth and the ring teeth:
z = zr / zs;
20-sim 4.6 Reference Manual
764
9. Library
determine the transmission ratio of the gearbox and therefore the dynamic equations of
the gearbox:
carriage.omega = sun.omega * (1/(1 + z)) + ring.omega * (z/(1 + z));
ring.T = carriage.T * (z/(1 + z));
sun.T = carriage.T * (1/(1 + z));
Interface
Ports
Description
sun
shaft attached to the sun wheel (Rotation)
carriage
shaft attached to the carriage (Rotation)
ring
shaft attached to the ring (Rotation)
Parameters
z
number of ring teeth divided by the number of sun teeth []
RackPinionGear
Library
Iconic Diagrams\Mechanical\Rotation\Gears
Iconic Diagrams\Mechanical\Translation\Transmission
Implementations
FixedPinion
FixedRack
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation/Translation).
Description - FixedPionion
This models represents a rack and pinion gear. The connection to the pinion gear is
through the rotation port p_rot. The connection to the rack is through the translation
port p_trans. The model is ideal, i.e. there is no compliance nor inertia nor backlash.
20-sim 4.6 Reference Manual
765
9. Library
In this model the pinion bearing is connected to the fixed world and the rack is free to
move. This in contrary to the model FixedRackPinionGear where the pinion bearing is
free to move and the rack is connected to the fixed world.
The causality of this model is always mixed: torque out & velocity out or angular velocity
out & force out:
p_rot.T = radius * p_trans.F
p_trans.v = radius * p_rot.omega
or:
p_trans.F = 1/radius * p_rot.T
p_rot.omega = 1/radius * p_trans.v
The rack position is determined by the internal variable x. For x = 0, the pinion gear is
at the middle of the rack. When the pinion crosses the end of the rack, i.e.
abs(x) > rack_length/2
a warning is given, "WARNING: rack length has been exceeded at the rack and pinion
gear!", and the simulation is stopped.
Interface - FixedPionion
Ports
Description
p_rot
Rotation port.
p_trans
Translation port.
Causality
p_rot
notequal
p_trans
Parameters
radius
pinion gear pitch radius [m]
rack_length
rack length [m]
Variables
20-sim 4.6 Reference Manual
766
9. Library
x
Internal
variable
which
denotes
the
rack
position,
abs(x)
<
rack_length/2 else simulation halted.
Initial values
x_initial
Initial rack position, abs(x_initial) < rack_length/2
Description - FixedRack
This models represents a fixed rack and pinion gear. The connection to the pinion gear is
through the rotation port p_rot. The connection to the rack is through the translation
port p_trans. The model is ideal, i.e. there is no compliance nor inertia nor backlash.
In this model the pinion bearing is free to move and the rack is connected to the fixed
world. This in contrary to the model RackPinionGear where the pinion bearing is
connected to the fixed world and the rack is free to move.
The causality of this model is always mixed: torque out & velocity out or angular velocity
out & force out:
p_rot.T = radius * p_trans.F
p_trans.v = radius * p_rot.omega
or:
p_trans.F = 1/radius * p_rot.T
p_rot.omega = 1/radius * p_trans.v
The rack position is determined by the internal variable x. For x = 0 the pinion gear is at
the middle of the rack. When the pinion crosses the end of the rack, i.e.
abs(x) > rack_length/2
a warning is given, "WARNING: rack length has been exceeded at the rack and pinion
gear!", and the simulation is stopped.
20-sim 4.6 Reference Manual
767
9. Library
Interface - FixedRack
Ports
Description
p_rot
Rotation port.
p_trans
Translation port.
Causality
p_rot
notequal
p_trans
Parameters
radius
pinion gear pitch radius [m]
rack_length
rack length [m]
Variables
x
Internal
variable
which
denotes
the
rack
position,
abs(x)
<
rack_length/2 else simulation halted.
Initial values
x_initial
Initial rack position, abs(x_initial) < rack_length/2
Spindle
Library
Iconic Diagrams\Mechanical\Rotation\Gears
Iconic Diagrams\Mechanical\Translation\Transmission
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Introduction
This models represents a spindle and nut. It transfers an angular motion of the spindle
into a translational motion of the nut. The model is ideal, i.e., it does not have inertia or
friction. The causality of this model is always mixed: one port has a torque out causality
while the other has an angular velocity out causality:
p_spindle.T = i * p_nut.F
p_nut.v = i * p_spindle.omega
or:
p_nut.F = 1/i * p_spindle.T
p_spindle.omega = 1/i * p_nut.v
The model has two implementations which calculate the transform ratio i out of different
parameters.
20-sim 4.6 Reference Manual
768
9. Library
Description - Pitch
In this implementation the transform ratio is calculated using the pitch (the advance of
the nut during one revolution of the spindle):
i = pitch / (2 * pi);
Interface - Pitch
Ports
Description
p_spindle
Port at the spindle shaft (Rotation).
p_nut
Port at the wheel (Translation).
Causality
p_spindle
notequal p_nut
Parameters
pitch
translation of the nut during one revolution of the spindle [m]
Description - LeadAngle
This implementation calculates the transform ratio out of the lead angle alpha and the
radius r_spindle of the spindle:
i = tan(alpha)*r_spindle;
The pitch angle is shown in the figure below. r_spindle is the effective radius of the
spindle, i.e. the radius from the center of the spindle to the pitch point p.
Interface -LeadAngle
Ports
Description
p_spindle
Port at the spindle shaft (Rotation).
p_nut
Port at the wheel (Translation).
20-sim 4.6 Reference Manual
769
9. Library
Causality
p_spindle
notequal p_nut
Parameters
r_spindle
alpha
effective radius of the spindle [m]
lead angle of the spindle [rad]
TimingBelt
Library
Iconic Diagrams\Mechanical\Rotation\Gears
Iconic Diagrams\Mechanical\Translation\Transmission
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation/Translation).
Introduction
This models represents a timing belt, used for linear positioning.
It has a rotating pulley which drives the the belt and clamp. The timing belt is modeled
by a series of spring damper elements that convey the rotation of the pulley to a clamp
translation. Because the output position is moving, stiffness and damping values are not
constant.
The stiffness for a piece of belt can be expressed as:
k = E*A / l
20-sim 4.6 Reference Manual
770
9. Library
with
E = Modulus of elasticity {N/m2}
A = Belt area {m2}
l = belt length {m}
If the belt is sufficiently pre-tensioned, the stiffness experienced at the clamp can be
expressed as the combination of three individual belt parts:
k = E*A/(0.5*l+x) + 1/( 1 / E*A/(0.5*l - x) + 1 / E*A / l )
which can be rewritten to:
k = E*A*( 1/(0.5*l+x) + 1/(1.5*l - x) )
The stiffness approaches infinity as the clamp moves to the driven pulley (x = -l/2) and
has a minimum value when the clamp moves to the other pulley (x = 0.5*l). The
minimum stiffness is equal to:
k = 2*E*A / l
The belt position is determined by the internal variable x. For x = 0 the clamp is in the
middle. When the position crosses the driven pulley, i.e.
x < - belt_length/2
the simulation is stopped: "Error: clamp position larger than belt end!". When the
position crosses the other pulley, i.e.
x > belt_length/2
the simulation is also stopped, "Error: clamp position smaller than belt start!".
Description - Default
In this model the minimum stiffness is used, based on an output position at a length L of
the driven pulley.
k = 2*E*A / l
Description - VariableStiffness
In this model a variable stiffness is used equal to:
k = E*A*( 1/(0.5*l+x) + 1/(1.5*l - x) )
Take care not to let the clamp get too close to the driven pulley, because the stiffness
will then grow to infinity!
Interface
Ports
Description
p_rot
Rotation port.
p_trans
Translation port.
20-sim 4.6 Reference Manual
771
9. Library
Causality
p_rot
notequal
p_trans
Parameters
radius
pinion gear pitch radius [m]
d
damping N.s/m]
E
Modulus of elasticity [N/m2]
A
A = Belt area [m2]
l
belt length [m]
Variables
x
clamp position, abs(x) < belt length/2
Initial values
x_initial
Initial clamp position, abs(x_initial) < belt length/2
Transmission
Library
Iconic Diagrams\Mechanical\Rotation\Gears
Implementations
Ideal
Lossy
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Description - Ideal
This models represents any type of gearbox with two shafts rotating in the same
direction. The gear is ideal, i.e., it does not have inertia or friction. The gear has one fast
moving shaft and one slow moving shaft. The gearbox has a reduction of i : 1 and thus a
transmission ratio of 1/i.
The causality of this model is always mixed: one port has a torque out causality while
the other has an angular velocity out causality:
p_in.T = 1/i * p_out.T
p_out.omega = 1/i * p_in.omega
or:
20-sim 4.6 Reference Manual
772
9. Library
p_out.T = i * p_in.T
p_in.omega = i * p_out.omega
Interface - Ideal
Ports
Description
p_in
Input port
p_out
Output port
Causality
p_in
not
equal
p_out
Parameters
i
gearbox reduction, i > 1
Description - Efficiency
This models represents any type of gearbox with two shafts rotating in the same
direction. The gearbox has a reduction of i : 1 and thus a transmission ratio of 1/i.
p_in.omega = i * p_out.omega
Unlike the model of an ideal gearbox, this model includes power loss. The power loss is
represented by the efficiency, where the efficiency is defined as the output power
divided by the input power:
eff = Pout / Pin
The efficiency is a value between zero and one and given by the gearbox manufacturer.
If you do no know the value, a good guess is a power loss of 3% per stage (eff = 0.97).
If your gearbox for example contains three stages, you can set the efficiency as:
eff = 0.97*0.97*0.97 = 0.91
Interface - Efficiency
Ports
Description
p_in
p_out
Input port
Output port
Causality
p_in not
p_out
equal
Parameters
i
gearbox reduction [-], i > 1
eff
gearbox efficiency [-]
20-sim 4.6 Reference Manual
773
9. Library
Description - Lossy
This models represents any type of gearbox with two shafts rotating in the same
direction. The gearbox has a reduction of i : 1 and thus a transmission ratio of 1/i.
p_in.omega = i * p_out.omega
Unlike the model of an ideal gearbox, this model includes rotational inertia and power
loss. The inertia is defined at the input axis. If the gearbox manufacturer gives the
inertia at the output axis you can calculate the inertia at input axis as:
Jinput = Joutput/i^2
The power loss is represented by the efficiency, where the efficiency is defined as the
output power divided by the input power:
eff = Pout / Pin
The efficiency is a value between zero and one and given by the gearbox manufacturer.
If you do no know the value, a good guess is a power loss of 3% per stage (eff = 0.98).
If your gearbox for example contains three stages, you can set the efficiency as:
eff = 0.97*0.97*0.97 = 0.91
Interface - Lossy
Ports
Description
p_in
Input port
p_out
Output port
Causality
preferred angular
velocity out p_in
preferred angular
velocity out p_out
Parameters
i
gearbox reduction [-], i > 1
J
moment of inertia [kgm^2]
eff
gearbox efficiency [-]
20-sim 4.6 Reference Manual
774
9. Library
UniversalCoupling
Library
Iconic Diagrams\Mechanical\Rotation\Gears
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Description
Universal Joint couplings are used to couple axes which are not aligned. The can be used
in single or double set-up. C onsider the single Universal Joint coupling, shown in the
picture below.
Due to the nature of the coupling, the output angular velocity w1 will show a sinusoidal
ripple, compared to the input angular velocity w2:
with
the angle between the two axes and 1 the initial rotation of the input axis. The
initial rotation 1 is defined with respect to a plane that is spanned by the axes (1 and
2).
When two Universal Joint couplings are combined, the angular velocity of the output axis
will be equal to the angular velocity of the input axis (e.g. no ripple) when two conditions
are met. When the output axis of the first coupling is connected to the input axis of the
second coupling, these conditions are:
1. For both couplings the absolute value of the angle
should be equal.
20-sim 4.6 Reference Manual
775
9. Library
2. The difference in initial rotation of both couplings ( 1 - 2) should be equal to
+ /2 [rad] or - /2 [rad].
Two alignments are shown in the figure below.
= 0.35
' = -0.35 , 1 = 0,
'
/2 [rad]
= 0.35
' = 0.35 , 1 = 0,
'
/2 [rad]
Interface
Ports
Description
p1, p2
The input and output axes (Rotation)
Causality
Input
p1 not equal p2
Parameters
alpha
The angle between the two axes ( ).
Initial Values
phi1_initial
The initial rotation of the input axis
1).
Wormgear
Library
Iconic Diagrams\Mechanical\Rotation\Gears
Implementations
Ideal
Backlash
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
20-sim 4.6 Reference Manual
776
9. Library
Description - Ideal
This models represents a worm gear with spindle (also referred to as worm) and wheel
(also referred to as gear). The gear is ideal, i.e., it does not have inertia or friction. The
causality of this model is always mixed: one port has a torque out causality while the
other has an angular velocity out causality:
p_spindle.T = i * p_wheel.T
p_wheel.omega = i * p_spindle.omega
or:
p_wheel.T = 1/i * p_spindle.T
p_spindle.omega = 1/i * p_wheel.omega
with
i = tan(alpha)*r_spindle/r_wheel;
Alpha is the pitch angle as shown in the figure below. r_wheel and r_spindle are the
effective radii of the wheel and spindle, i.e. the radii from the center of the wheel and
spindle to the pitch point p.
20-sim 4.6 Reference Manual
777
9. Library
Interface - Ideal
Ports
Description
p_spindle
Port at the spindle shaft (Rotation).
p_wheel
Port at the wheel (Rotation).
Causality
p_wheel notequal
p_spindle
Parameters
r_spindle
pitch radius spindle [m]
r_wheel
pitch radius wheel [m]
alpha
lead angle of the spindle [rad]
Description - Backlash
This models represents a worm gear with spindle (also referred to as worm) and wheel
(also referred to as gear). Between spindle and wheel, backlash and friction is modelled.
The causality of this model is always fixed: both ports have a torque out causality.
20-sim 4.6 Reference Manual
778
9. Library
Analysis
The spindle and wheel have one ore more pair of teeth contacting each other. The
effective point of contact is called the pitch point P. At the pitch point a frame is defined,
with an x- and y-direction. During rotation of the wheel and spindle, the teeth will
experience a normal force Fn in the x-direction and a friction force Ff in the y-direction.
Between each pair of teeth, a clearance exists (y-direction), causing backlash. This
effect is time-dependent, because of the tooth pairs coming in and out of contact. During
normal operation this is a high frequency effect, which is filtered out by the damping of
the construction. We therefore only use an average backlash at the pitch point. Using
the same reasoning as backlash, an average friction is used at the pitch point.
To define both backlash and friction a frame is used at the pitch point (see picture
above) to indicate velocities. The velocity in x-direction is the sliding velocity between
the teeth and used to calculate the friction force. The position in y-direction is the
position in the clearance and used to calculate the backlash force.
Backlash
The backlash is described by the standard formula that is also used in the Backlash.emx
model. The normal force is modelled by a spring-damper system. Inside the clearance a
low damping and stiffness is used (k1 and d1), while a high stiffness and damping (k2
and d2) is used at both ends of the clearance. This yields a normal force Fn of:
Friction
Friction is described as static plus coulomb plus viscous plus Stribeck friction:
p.F = Fn *
(( mu_c + (mu_st*abs(tanh( slope*p.v )) - mu_c)
* exp( -((p.v / v_st)^2 )) ) * sign(p.v)
+ mu_v * p.v);
20-sim 4.6 Reference Manual
779
9. Library
with:
Fn: the normal force (given by the backlash formula)
mu_s: the static friction coefficient
mu_v: the viscous friction coefficient
mu_c: the coulomb friction coefficient
slope: the steepness of the coulomb and static friction curve.
v_st: the characteristic Stribeck velocity.
Self-Locking
A worm gear is said to be self-locking, or irreversible when the wheel cannot drive the
spindle. This condition is obtained, if the lead angle of the worm is small and the friction
force between the teeth is high enough. Then the friction force becomes larger than the
driving force on the teeth. Suppose we only consider static and C oulomb friction and
both friction coefficients are equal. Then self locking is obtained when the following
condition holds:
mu_s > tan(alpha)
mu_c > tan(alpha)
Interface - Backlash
Ports
Description
p_spindle
Port at the spindle shaft (Rotation).
p_wheel
Port at the wheel (Rotation).
Causality
fixed torque
out
p_spindle
Parameters
r_spindle
pitch radius spindle [m]
r_wheel
pitch radius wheel [m]
alpha
lead angle of the spindle [rad]
s
Interval of the play [m]
k1
Stiffness in the play [N/m]
k2
Stiffness outside the play [N/m]
d1
Damping inside the play [Ns/m]
d2
Damping outside the play [Ns/m]
ep
Relative round off (1e-6 -> sharp edges, 1e-2 -> smoother)
mu_s
Static friction coefficient []
mu_v
Viscous friction coefficient [s/m]
mu_c
C oulomb friction coefficient []
slope
Steepness of C oulomb friction curve [s/m]
v_st
C haracteristic Stribeck velocity [m/s]
Interesting
Variables
20-sim 4.6 Reference Manual
780
9. Library
Fn
Average normal force between teeth [N]
Ff
Average friction force between teeth [N]
v_x
Velocity in x-direction at the pitch frame [m/s] (used in friction
v_y
formula)
x_x
Velocity in y-direction at the pitch frame [m/s] (used in backlash
x_y
formula)
Position in x-direction at the pitch frame [m/s] (used in friction
formula)
Position in y-direction at the pitch frame [m/s] (used in backlash
formula)
Sensors
AccelerationSensor-Absolute
Library
Iconic Diagrams\Mechanical\Rotation\Sensors
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation), Block Diagrams.
Description
This model describes an acceleration sensor which derives an angular acceleration
output out of a port angular velocity by differentiation. Differentiation is performed by a
state variable filter:
The S-domain function of this filter is equal to:
where f is the cut-off frequency. For very high values of f, the output becomes the pure
derivative of the input. High values of f, however, increase simulations times. A good
trade-off is a starting value of 1e5.
The equations of this model are:
20-sim 4.6 Reference Manual
781
9. Library
alpha = d( p.omega)/dt;
p.T = indifferent;
Interface
Ports
Description
p
Rotation port p.
Causality
fixed force out
Output
alpha
Absolute angular acceleration [rad/s2]
Parameters
f
C ut-off frequency of the differentiation [Hz].
alpha_initial
Initial angular acceleration [m/s].
AccelerationSensor-Relative
Library
Iconic Diagrams\Mechanical\Rotation\Sensors
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation), Block Diagrams.
Description
This model describes an acceleration sensor which derives an angular acceleration
output out of a angular velocity difference (between high and low terminals) by
differentiation. Differentiation is performed by a state variable filter:
The S-domain function of this filter is equal to:
where f is the cut-off frequency. For very high values of f, the output becomes the pure
derivative of the input. High values of f, however, increase simulations times. A good
trade-off is a starting value of 1e5.
20-sim 4.6 Reference Manual
782
9. Library
The equations of this model are:
alpha = d( p_high.omega - p_low.omega)/dt;
p_low.T = p_high.T = indifferent;
Interface
Ports
Description
p_high, p_low
Both terminals of the Mechanical port p.
Causality
fixed force out
Output
alpha
Angular acceleration (measured as the difference between both
terminals) [rad/s2]
Parameters
f
C ut-off frequency of the differentiation [Hz].
alpha_initial
Initial angular acceleration [m/s].
Encoder
Library
Iconic Diagrams\Mechanical\Rotation\Sensors
Implementations
Ideal
Absolute
Incremental
Use
Domains: C ontinuous/Discrete. Size: 1-D. Kind: Iconic Diagrams (Rotation) / Block
Diagrams.
Description - Ideal
This is a model of an optical encoder combined with sampling. The Encoder has no
internal friction. The output signal is equal to the sampled shaft shaft angle (in radians).
Example
The shaft angle is equal to a sine with amplitude 2*pi (one revolution forward and one
back), the sampling rate is 5 Hz.
20-sim 4.6 Reference Manual
783
9. Library
Interface - Ideal
Ports
Description
p
Rotation port
Causality
fixed torque out
(The output torque is zero)
Outputs
Description
output
sampled shaft angle (rad)
Description - Absolute
This is a model of an optical encoder combined with counting logic and analog to digital
conversion. The encoder has no internal friction. C ounting is absolute. The shaft angle is
measured with an accuracy of a given number of counts per revolution.
Example
An encoder has an accuracy of 10 counts per revolution. This means an input signal with
value 6.283185307 gives an output of 10. This is illustrated in the figure below. The input
is a sine with amplitude 2*pi (one revolution forward and one back).
20-sim 4.6 Reference Manual
784
9. Library
Overflow
This model has no overflow.
Interface - Absolute
Ports
Description
p
Rotation port
Causality
fixed torque out
(The output torque is zero)
Outputs
Description
output
number of counts
Parameters
counts
counts per revolution.
Description - Incremental
This is a model of an optical encoder combined with counting logic and analog to digital
conversion. The encoder has no internal friction. C ounting is incremental. The shaft
angle is measured with an accuracy of a given number of counts per revolution and a
window defined by the number of bits.
Example
An encoder has an accuracy of 2000 counts per revolution. This means an input signal
with value 6.283185307 gives an output of 2000.
Example
An encoder has an accuracy of 10 counts per revolution and a 5 bits counter. This
means an input signal with value 6.283185307 gives an output of 10 and the output is
clipping between +15 and -16. This is illustrated in the figure below. The input is a sine
with amplitude 2*pi (one revolution forward and one back).
20-sim 4.6 Reference Manual
785
9. Library
Encoder output without overflow.
The next figure shows the same settings but only 4 bits are used. This means the output
is clipping between +7 and -8.
Encoder output with overflow.
Overflow
The maximum and minimum number of counts are equal to 2(bits-1) -1 and -2(bits-1). If
the number of counts passes 2(bits-1) -1, counting continues at -2(bits-1) and vice
versa.
Interface - Incremental
Ports
Description
p
Rotation port
20-sim 4.6 Reference Manual
786
9. Library
Causality
fixed torque out
(The output torque is zero)
Outputs
Description
output
number of counts
Parameters
counts
counts per revolution.
bits
maximum counting interval is between 2(bits-1) -1 and -2(bits-1).
Limitations
The output of this model is a discrete signal. 20-sim will automatically detect the
existence of discrete models. Each chain of discrete models will be assigned a specific
sampletime. You can set this sample time to any desired value in the Simulator (choose
Properties, Simulation and Discrete System).
PositionSensor-Absolute
Library
Iconic Diagrams\Mechanical\Rotation\Sensors
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (, Block Diagrams.), Block
Diagrams.
Description
This model translates a angular position to an output signal. It has a force out causality.
The equations are:
p.T = 0;
phi = int(p.omega);
Interface
Ports
Description
p_high, p_low
Rotation port p.
Causality
fixed force out
Output
phi
Absolute angular position [rad]
Initial Values
phi_initial
Initial angular position [rad]
20-sim 4.6 Reference Manual
787
9. Library
PositionSensor-Relative
Library
Iconic Diagrams\Mechanical\Rotation\Sensors
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation), Block Diagrams.
Description
This model translates a angular position difference to an output signal. It has a force out
causality. The port p of the model has separate high and low terminals. The equations
are:
p.T = p_high.T = p_low.T;
p.omega = p_high.omega - p_low.omega;
p.T = 0;
phi = int(p.omega);
Interface
Ports
Description
p_high, p_low
Both terminals of the Rotation port p.
Causality
fixed force out
Output
phi
Relative angular position [rad]
Initial Values
phi_initial
Initial angular position [rad]
Potentiometer
Library
Iconic Diagrams\Mechanical\Rotation\Sensors
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation / Electric).
Description
Potentiometers have a variable resistance according to a certain rotation. By
establishing a voltage (see picture below) across the resistor it is possible to get a
proportional relation between the angle and the output voltage.
20-sim 4.6 Reference Manual
788
9. Library
with
Uout = Umax * angle / (turns*2*pi)
Here Umax is the maximum voltage and turns is the maximum number of turns.
Interface
Ports
Description
p1
Rotation port.
p2
Electric port.
Causality
fixed torque
out (The output torque is zero)
p1
The output is equal to Uout.
fixed voltage out
p2
Parameters
Umax
Maximum output voltage [V]
turns
maximum allowed number of turns []
PowerSensor
Library
Iconic Diagrams\Mechanical\Rotation\Sensors
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation), Block Diagrams.
Description
This is an ideal sensor (no dissipation or other effects) that yields the power that flows
through the model as output signal. The equations are:
p_high.T = p_low.T
p_high.omega = p_low.omega
P = p_high.T * p_high.omega;
Interface
Ports
Description
20-sim 4.6 Reference Manual
789
9. Library
p_high, p_low
Both rotation ports.
Causality
p_high not equal
p_low
Output
P
Power [w].
Tachometer
Library
Iconic Diagrams\Mechanical\Rotation\Sensors
Use
Domains: C ontinuous/Discrete. Size: 1-D. Kind: Iconic Diagrams (Rotation) / Block
Diagrams.
Description
A tachometer is a transducer for measuring the rotation speed. It is normally mounted
at the shaft of a motor and gives a voltage signal proportional to the rotation speed:
with Kv the tachometer gradient [V / rad/s] and v the shaft velocity [rad/s]. This
equation represents the ideal case. Due to the slots and commutator segments of the
tachometer, a noise ripple will exists:
with N the ripple frequency [cycles per turn] and Kn the peak to peak noise Ripple [in %
of the output voltage]. To convert the Voltage Gradient parameter from RPM units [V /
RPM] to radian units [V / rad/s], use the conversion formula:
Interface
Ports
Description
p
Rotation port.
Causality
fixed torque out
(The output torque is zero)
Outputs
Description
output
Output voltage [V]
20-sim 4.6 Reference Manual
790
9. Library
Parameters
Kv
Voltage Gradient [ V / rad/s ].
Kn
Noise Ripple , relative to output voltage [%].
N
Ripple frequency in cycles per turn [].
TorqueSensor
Library
Iconic Diagrams\Mechanical\Rotation\Sensors
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation), Block Diagrams.
Description
This model translates an applied torque to an output signal. It has an angular velocity
out causality. The port p of the model has separate high and low terminals. The
equations are:
p.T = p_high.T = p_low.T;
p.omega = p_high.omega - p_low.omega;
p.omega = 0;
T = p.T;
Interface
Ports
Description
p_high, p_low
Both terminals of the Rotation port p.
Causality
fixed
angular
velocity out
Output
T
Applied torque [N/m]
VelocitySensor-Absolute
Library
Iconic Diagrams\Mechanical\Rotation\Sensors
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation), Block Diagrams.
Description
This model translates an angular velocity to an output signal. It has a force out causality.
The equations are:
20-sim 4.6 Reference Manual
791
9. Library
p.T = 0;
omega = p.omega;
Interface
Ports
Description
p
Mechanical port p.
Causality
fixed force out
Output
omega
Absolute angular velocity [rad/s]
VelocitySensor-Relative
Library
Iconic Diagrams\Mechanical\Rotation\Sensors
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation), Block Diagrams.
Description
This model translates a velocity difference to an output signal. It has a force out
causality. The port p of the model has separate high and low terminals. The equations
are:
p.T = p_high.T = p_low.T;
p.omega = p_high.omega - p_low.omega;
p.T = 0;
omega = p.omega;
Interface
Ports
Description
p_high, p_low
Both terminals of the Rotation port p.
Causality
fixed force out
Output
omega
Relative angular velocity [rad/s]
20-sim 4.6 Reference Manual
792
9. Library
Translation
2DSmallRotation
2D Library (Small Rotations)
Introduction
The 2DSmallRotation library contains models that describe 2-D planar motion and are
valid for small rotations. Due to these small rotations, the dynamic equations that
describe the various models are simple and can be linearized symbolically. The library is
therefore suited for modeling mechanical systems that experience small rotations and
must be thoroughly analyzed in the frequency domain.
C onsider the guidance system below. Due to the limited stiffness of the guidance wheels,
the central body will experience a small rotation that results in a movement in the xdirection at the end-effector. To properly model the end-effector movement as a
function of the driven force, this rotation has to be incorporated. To inspect the resulting
resonance frequencies in a bode plot, the model must be linearized. If linearization is
performed symbolically, the effect of parameter changes (af, b, J) can be inspected
directly in the bode plot, which is very useful when the system is still in the design
phase.
To perform symbolic linearization, the example system should be modeled using the
models of the 2DSmallAngles library.
2D
When we speak of 2D motion we often mean all planar motion. However, to describe
this motion, three degrees of freedom (displacement x and y and rotation ) are
used. In 20-sim we keep to the common naming standard of 2D for planar motion (3
degrees of freedom) and 3D for spatial motion (6 degrees of freedom). In 20-sim the
three degrees of freedom for planar motion are combined in a vector notation:
d.o.f.
identity
forces
velocities
x
position
P.F[1] [N]
P.v[1] [m/s]
20-sim 4.6 Reference Manual
793
9. Library
y
position
P.F[2] [N]
P.v[2] [m/s]
angle
P.F[3] [Nm]
P.v[3] [rad/s]
Note
It is not possible in 20-sim to use vector elements with mixed units. Therefore element
number 3 will be displayed with units [m/s] and [N] although it really is [rad/s] and
[Nm]!
Ports
1D
The models in the 2DSmallRotation library have two types of connection ports: 1D and
2D. The 1D ports can represent movement and force (x- or y-direction) or an angular
displacement and torque.
The models of the standard translation and rotation libraries can be used connect to
these 1D ports as is shown in the picture below.
2D
The 2D connection port is a vector that represents three degrees of freedom. The vector
notation that is used in 20-sim is:
d.o.f.
identity
forces
velocities
x
position
P.F[1] [N]
P.v[1] [m/s]
y
position
P.F[2] [N]
P.v[2] [m/s]
angle
P.F[3] [Nm]
P.v[3] [rad/s]
In 20-sim it is not possible to use vector ports with mixed units. This means that element
number 3 will be always be displayed with the units [m/s] and [N] although it should be
interpreted as [rad/s] and [Nm].
20-sim 4.6 Reference Manual
794
9. Library
To connect 2D ports, only other models with 2D ports can be used. A double line
indicates this vector connection.
Small Rotations
C onsider the body below:
Given a force Fx in x-direction acting upon the body at an offset y1 from the center, the
resulting force at the center of the body is:
F1x = Fx * cos(q)
F1y = Fx * sin(q)
F1q = Fx * -y1
For small angles this can be simplified to:
F1x = Fx
F1y = 0
F1q = Fx * -y1
A force acting upon a body at a certain offset is rewritten to a force at the center of the
body. This is common in multibody dynamics and called a transformation. A force acting
at a certain point can be transformed to see its effect at another point.
C onsider two frames which have an arbitrary offset as shown in the picture below. We
want to know how a force in frame 0 is transformed to a force in frame 1. We assume
that frame 1 has an offset of x1 and y1 with respect to frame 0 and a rotation q1 with
respect to frame 0. In order to make clear that the offsets are given with respect to
frame 0 we will write the with extra indices (x1,0 , y1,0 and 1,0 ).
20-sim 4.6 Reference Manual
795
9. Library
Given an arbitrary force F1,0 at frame 0 the resulting force F1,1 at frame 1 is equal to:
For small angles this can be simplified to:
The accuracy of this simplification depends on the angle . For an angle of 0.5 degrees
(0.009 rad) this results in an almost 1% error in the calculation of F1,1. C onsidering the
cumulative effects of this error when multiple models are used, an angle of maximum
0.05 degrees (<1 mrad) is an upper bound for the models of the 2DSmallRotation
library.
The simplification of the equations has two advantages. First because of the small
rotations there is no frame rotation any more. Therefore all frames have the same
direction (there is only an offset in x-direction and y-direction). Interpreting results is
therefore much easier. But the biggest advantage is the simplification of equations which
allows us to linearize models symbolically and thus perform tasks in the frequency like
parameter sweeps!
Connections
Degrees of Freedom
As described in the previous topic, the models in 2DSmallRotation library have two types
of connection ports: 1D and 2D. The 1D port can represent movement in the x-direction,
the y-direction or an angular displacement .
20-sim 4.6 Reference Manual
796
9. Library
The 2D port is a vector that contains all three degrees of freedom. The vector notation
that is used in 20-sim is:
d.o.f.
identity
forces
velocities
x
position
P.F[1] [N]
P.v[1] [m/s]
y
position
P.F[2] [N]
P.v[2] [m/s]
angle
P.F[3] [Nm] P.v[3] [rad/s]
The vector element number (1, 2 or 3) denotes the identity of the degree of freedom (x,
y and ). To create meaningful models, we have to define the positive direction of each
degree of freedom:
d.o.f.
positive direction
x
from left to right
y
from bottom to top
counter clockwise
This definition is arbitrary. We could as well define it any other way. In the
2DSmallRotation library we have chosen the definition above. It will help us define new
models and interpret simulation results.
Orientation Independent
The connections between models only indicate how variables (forces and velocities) are
transferred from one model to the other and vice versa. The orientation of the models in
the Graph Editor (how they are drawn) is therefore not important. Flipping, rotating or
moving a model does not change the model! All four representations in the figure
below are the same although their individual models are oriented differently.
The figure above shows a point model in x-direction connected to a 2D body. The point
indicates a force in x-direction that is applied to the body. Since we defined that the
positive x-direction is from the left to the right, intuitively figure b leads to the correct
interpretation.
20-sim 4.6 Reference Manual
797
9. Library
This indicates a problem. Although all models describe the same behavior, we would
intuitively interpret them differently. It is therefore useful to impose some rules to
prevent misinterpretation of a model by other users.
Drawing Rules
1.
Preferably leave the orientation of the models of the 2DSmallRotation library as they
pop up on the screen.
2.
If necessary, only flip or rotate models in a direction that does not lead to
misinterpretations.
3.
If possible, draw 1D connections in the following direction:
d.o.f.
positive direction
x
from left to right
y
from bottom to top
from left bottom to right top
An example is shown in the figure below:
TwoDBody
Library
Iconic Diagrams\Mechanical\Translation\2DSmallAngles
Use
Domains: C ontinuous. Size: 2-D. Kind: Iconic Diagrams (2D Planar).
20-sim 4.6 Reference Manual
798
9. Library
Description
The central model in the 2DSmallRotation library is the TwoDBody model. It describes a
body with three degrees of freedom: x, y and . The TwoDBody is a point mass with
rotational inertia. The constitutive equations are therefore very simple:
P.v = I .* int(P.F);
With
I = [1/M; 1/M; 1/J];
Any number of connections can be made to the TwoDBody model. All forces acting upon
the body are added.
Because any number of connections can be made, successive ports are named P1, P2,
P3 etc. 20-sim will automatically create equations such that the resulting force P.F is
equal to the sum of the forces of all connected ports P1 . Pn. The velocities of all
connected ports are equal to P.v. The model has a preferred velocity out causality. The
corresponding constitutive equations then contain an integration. The model can also
have the non-preferred force out causality. The constitutive equations then contain a
differentiation.
P.F = sum(P1.F, P2.F, ....)
P.v = P1.v = P2.v = ....
velocity out causality (preferred):
I = [1/M;1/M;1/J]
P.v = I*int(P.F);
force out causality:
I = [1/M;1/M;1/J]
P.F = I-1*ddt(P.v);
Interface
Ports
Description
20-sim 4.6 Reference Manual
799
9. Library
P[3]
Port with three degrees of freedom (x, y,
). Any number of
connections can be made.
Causality
preferred velocity
out
Parameters
M
Mass [kg].
J
Moment of inertia [kgm2/rad]
Note
A TwoDBody model can be connected to any other element of the 2D-library except
other 2D-bodies. Two bodies can always be simplified to one TwoDBody model with
the combined mass and inertia of both single bodies.
TwoDBody models can be connected to 1D models using the TwoDPoint models as
intermediate. If a TwoDPoint is connected to a body, it constrains the movement of
the body in one direct
TwoDPoint Models
TwoDPoint models are used to connect 1D models to TwoDBodies. They indicate a 1D
force or torque that is applied in a certain direction, onto a body.
A point model forms the connection between the single degree of freedom part of a
system and the center of mass of a body. C onsider the example below, where force F in
x-direction (single degree of freedom) is pushing upon a body (three degrees of
freedom) at an offset YP from the body center of mass.
To create such a construct, the TwoDPoint-X model is used:
20-sim 4.6 Reference Manual
800
9. Library
The TwoDPoint-X model describes the translation of a 1D force (x-direction) to a 2Dforce (x-, y- and -direction) and vice versa the translation of a 2D-velocity (x-, y- and
-direction) to a 1D velocity (x-direction).
There are four point models. Three point models transform from x-direction, y-direction
and -direction to 2D. One point models transforms from direction with arbitrary
orientation to 2D.
Fixation of bodies
If a TwoDBody model is used in combination with TwoDPoint models, at least three noncoinciding, unequal (i.e. not having the same offsets) TwoDPoints must be connected to
prevent the body from free motion. This is obvious when we interpret the point models
physically. Point models can be interpreted as constraints on motion in one direction.
The motion in the other two directions is free.
To show that two points are not sufficient to constrain all motions look at the figure
below.
20-sim 4.6 Reference Manual
801
9. Library
TwoDPoint
Library
Iconic Diagrams\Mechanical\Translation\2DSmallAngles
Implementations
X
Y
theta
XY
Use
Domains: C ontinuous. Size: 1-D/2-D. Kind: Iconic Diagrams (1D Translation, 2D
Planar).
Description - X
TwoDPoint models are used to connect 1D models to TwoDBodies. They indicate a 1D
force or torque that is applied in a certain direction, onto a body. The TwoDPoint-X
model forms the connection between the single degree of freedom in x-direction and the
center of mass of a body. C onsider the example below, where force F in x-direction
(single degree of freedom) is pushing upon a body (three degrees of freedom) at an
offset YP from the body center of mass.
To create such a construct the TwoDPoint-X model is used:
The TwoDPoint-X model describes the transformation of force in x-direction to a force in
three degrees of freedom. The single degree of freedom port p_in describes the
connection in x-direction and the three three degree of freedom port P_out describes
connection with the 2D-body (x, y and ).
P_out.F[1] = p_in.F;
// x-direction
P_out.F[2] = 0;
// y-direction
P_out.F[3] = -p_in.F * YP;
// rotation
p_in.v = P_out.v[1] - YP *
// x-direction
P_out.v[3];
20-sim 4.6 Reference Manual
802
9. Library
Interface - X
Ports
Description
p_in
1D Translation port (x).
P_out[3]
2D Port with three degrees of freedom (x, y, ).
Causality
fixed
force
out
P_out
fixed velocity out
p_in
Parameters
YP
Distance (y-direction) between connection and center of mass [m].
Description - Y
TwoDPoint models are used to connect 1D models to TwoDBodies. They indicate a 1D
force or torque that is applied in a certain direction, onto a body. The TwoDPoint-Y
model forms the connection between the single degree of freedom in y-direction and the
center of mass of a body. C onsider the example below, where force F in y-direction
(single degree of freedom) is pushing upon a body (three degrees of freedom) at an
offset XP from the body center of mass.
To create such a construct the 2D-point-Y model is used:
20-sim 4.6 Reference Manual
803
9. Library
The 2D-point-Y model describes the transformation of force in y-direction to a force in
three degrees of freedom. The single degree of freedom port p_in describes the
connection in y-direction and the three three degree of freedom port P_out describes
connection with the 2D-body (x, y and ).
P_out.F[1] = 0;
// x-direction
P_out.F[2] = p_in.F;
// y-direction
P_out.F[3] = p_in.F * XP;
// rotation
p_in.v = P_out.v[2] + XP *
// y-direction
P_out.v[3];
Interface - Y
Ports
Description
p_in
1D Translation port (y).
P_out[3]
2D Port with three degrees of freedom (x, y, ).
Causality
fixed
force
out
P_out
fixed velocity out
p_in
Parameters
XP
Distance (x-direction) between connection and center of mass [m].
20-sim 4.6 Reference Manual
804
9. Library
Description - theta
TwoDPoint models are used to connect 1D models to TwoDBodies. They indicate a 1D
force or torque that is applied in a certain direction, onto a body. The TwoDPoint-Theta
model forms the connection between the single degree of freedom rotation and the
center of mass of a body. C onsider the example below, where torque (single degree of
freedom) is acting on a body (three degrees of freedom).
To create such a construct the TwoDPoint-Theta model is used:
The TwoDPoint-Theta model describes the transformation of a single rotation to a
rotation of the 2D-body. The single degree of freedom port p_in describes the
connection to the single degree rotation the three three degree of freedom port P_out
describes connection with the 2D-body (x, y and ).
P_out.F[1] = 0;
// x-direction
P_out.F[2] = 0;
// y-direction
P_out.F[3] = p_in.T;
// rotation
p_in.omega = P_out.v[3];
// rotation
Interface - theta
Ports
Description
p_in
1D Rotation port ( ).
P_out[3]
2D Port with three degrees of freedom (x, y, ).
Causality
fixed
force
out
P_out
fixed velocity out
p_in
20-sim 4.6 Reference Manual
805
9. Library
Description - XY
TwoDPoint models are used to connect 1D models to TwoDBodies. They indicate a 1D
force or torque that is applied in a certain direction, onto a body. The TwoDPoint-XY
model forms the connection between a single degree of freedom in arbitrary direction
and the center of mass of a body. C onsider the example below, where force F (single
degree of freedom) is pushing upon a body (three degrees of freedom) with an arbitrary
angle theta at an offset XP and YP from the body center of mass.
To create such a construct the TwoDPoint-XY model is used:
The TwoDPoint-XY model describes the transformation of a one degree of freedom force
in an arbitrary direction to a force in three degrees of freedom. The single degree of
freedom port p_in describes the connection in the arbitrary direction and the three three
degree of freedom port P_out describes connection with the 2D-body (x, y and ).
Fx = cos(theta)*p_in.F;
// arbitrary-direction
Fy = sin(theta)*p_in.F;
// arbitrary-direction
P_out.F[1] = Fx;
// x-direction
P_out.F[2] = Fy;
// y-direction
P_out.F[3] = Fy * XP - Fx * YP;
// rotation
20-sim 4.6 Reference Manual
806
9. Library
p_in.v = cos(theta)*P_out.v[1] +
// arbitrary-direction
sin(theta)*P_out.v[2] +
XP * sin(theta)* P_out.v[3] -
YP * cos(theta) * P_out.v[3];
Interface - XY
Ports
Description
p_in
1D Translation port in arbitrary direction.
P_out[3]
2D Port with three degrees of freedom (x, y, ).
Causality
fixed
force
out
P_out
fixed velocity out
p_in
Parameters
YP
Distance (y-direction) between connection and center of mass [m].
XP
Distance (x-direction) between connection and center of mass [m].
theta
Angle of impact of the single degree of freedom port [rad].
Note
A TwoDBody has to be connected to at least three unequal TwoDPoint models to
prevent it from free motion (rotation & translation).
Flipping or rotating the model does not change the direction of applied forces or
measured directions. Preferably leave the orientation as it pops up on the screen.
TwoDFixedWorld
Library
Iconic Diagrams\Mechanical\Translation\2DSmallAngles
Use
Domains: C ontinuous. Size: 2-D. Kind: Iconic Diagrams (2D Planar).
Description
The TwoDFixedWorld represents the fixed world in 3 degrees of freedom. It can be
connected to other 2D models to freeze their motion. Models that can be connected to
the fixed world are:
1.
TwoDSprings
2.
TwoDLinearSlides
20-sim 4.6 Reference Manual
807
9. Library
3.
TwoDLinearActuators
Although other models like the TwoDBody can also be connected to the TwoDFixedWorld
model, it makes no sense because it completely fixates all equations of motion.
Interface
Ports
Description
P
Port with three degrees of freedom (x, y, ).
Causality
fixed velocity out
P
TwoDZeroForce
Library
Iconic Diagrams\Mechanical\Translation\2DSmallAngles
Use
Domains: C ontinuous. Size: 2-D. Kind: Iconic Diagrams (2D Planar).
Description
This model can be used to connect any open end of another 2D model that is not
connected to the fixed world. It generates a three degree of freedom zero force while
the velocity is free.
Interface
Ports
Description
P
Port with three degrees of freedom (x, y, ).
Causality
fixed force out P
Sensors
To inspect the model behavior you can plot variables. Sometimes not all variables are
available. Then sensor model can be used.
1D
To use the 1D sensor models from the standard library, connect them to the 2D models
using the TwoDPoint models.
20-sim 4.6 Reference Manual
808
9. Library
2D
To measure variables directly from the 2D models, three absolute sensors are available
showing the absolute position, velocity and acceleration. Also two relative sensors are
available showing the force and powerflow between two elements.
TwoDPositionSensor
Library
Iconic Diagrams\Mechanical\Translation\2DSmallAngles
Use
Domains: C ontinuous. Size: 1-D/2-D. Kind: Iconic Diagrams (1D Translation,1D
Rotation, 2D Planar).
Description
This model is used to find the absolute position of a TwoDBody model. It has a port P
which can be connected to the body and it has three output signals that denotes the xand y-position and the angle of the body. The model has a force out causality. The
equations are:
P.F = 0;
x = int (P.v[1]);
y = int (P.v[2]);
theta = int (P.v[3]);
Interface
Ports
Description
P[3]
Port with three degrees of freedom (x, y, ).
Causality
fixed force out P
Output
x
Absolute position [m].
y
Absolute position [m].
theta
Absolute angle [rad].
Initial Values
x_initial
Initial position [m]
y_initial
Initial position [m]
theta_initial
Initial angle [m]
20-sim 4.6 Reference Manual
809
9. Library
TwoDVelocitySensor
Library
Iconic Diagrams\Mechanical\Translation\2DSmallAngles
Use
Domains: C ontinuous. Size: 1-D/2-D. Kind: Iconic Diagrams (1D Translation,1D
Rotation, 2D Planar).
Description
This model is used to find the absolute velocity of a TwoDBody model. It has a port P
which can be connected to the body and it has three output signals that denotes the xand y-velocity and the angular velocity of the body. The model has a force out causality.
The equations are:
P.F = 0;
vx = P.v[1];
vy = P.v[2];
omega = P.v[3];
Interface
Ports
Description
P[3]
Port with three degrees of freedom (x, y, ).
Causality
fixed force out P
Output
vx
Absolute velocity [m].
vy
Absolute velocity [m].
omega
Absolute angular velocity [rad].
TwoDAccelerationSensor
Library
Iconic Diagrams\Mechanical\Translation\2DSmallAngles
Use
Domains: C ontinuous. Size: 1-D/2-D. Kind: Iconic Diagrams (1D Translation, 1D
Rotation, 2D Planar).
Description
This model is used to find the absolute acceleration of a TwoDBody model. It has a port
P which can be connected to the body and it has three output signals that denotes the xand y-acceleration and the angular acceleration of the body.
The acceleration output is calculated out of the velocity by differentiation. Differentiation
is performed by a state variable filter:
20-sim 4.6 Reference Manual
810
9. Library
The S-domain function of this filter is equal to:
where f is the cut-off frequency. For very high values of f, the output becomes the pure
derivative of the input. High values of f, however, increase simulations times. A good
trade-off is a starting value of 1e5.
The equations of this model are:
P.F = 0;
ax = 2*pi*f*( P.v[1] - int(ax, 0));
ay = 2*pi*f*( P.v[2] - int(ay, 0));
alpha = 2*pi*f*( P.v[3] - int(alpha, 0));
Interface
Ports
Description
P[3]
Port with three degrees of freedom (x, y, ).
Causality
fixed force out P
Outputs
ax
Absolute acceleration [m].
ay
Absolute acceleration [m].
alpha
Absolute acceleration [rad].
Initial Values
ax_initial
Initial acceleration [m]
ay_initial
Initial acceleration [m]
alpha_initial
Initial angular acceleration [m]
20-sim 4.6 Reference Manual
811
9. Library
TwoDForceSensor
Library
Iconic Diagrams\Mechanical\Translation\2DSmallAngles
Use
Domains: C ontinuous. Size: 1-D/2-D. Kind: Iconic Diagrams (1D Translation, 1D
Rotation, 2D Planar).
Description
This model can be used to measure the forces and torque between two components. It
has a high and a low terminal to connect to both components. The equations are:
P.F = P_high.F = P_low.F;
P.v = P_high.v - P_low.v;
P.v = 0;
Fx = P.F[1];
Fy = P.F[2];
T = P.F[3];
Interface
Ports
Description
P[3]
Port with three degrees of freedom (x, y, ).
Causality
fixed velocity out
P
Outputs
Fx
Force [N].
Fy
Force [N].
T
Torque [Nm].
TwoDPowerSensor
Library
Iconic Diagrams\Mechanical\Translation\2DSmallAngles
Use
Domains: C ontinuous. Size: 1-D/2-D. Kind: Iconic Diagrams (1D Translation, 1D
Rotation, 2D Planar).
Description
This model can be used to measure the powerflow between two models. It has two ports
to to both models. The equations are:
20-sim 4.6 Reference Manual
812
9. Library
P.F = P_high.F = P_low.F;
P_high.F = P_low.F;
P_high.v = P_low.v;
P = P_high.v .* P_high.F;
Px = P[1];
Py = P[2];
Ptheta = P[3];
Interface
Ports
Description
P[3]
Port with three degrees of freedom (x, y, ).
Causality
fixed velocity out
P
Outputs
Px
Power [W].
Py
Power [W].
Ptheta
Power [W].
Springs and other Flexible Components
2D Springs
A TwoDSpring model represents a flexible spring between two bodies. The center of
stiffness is located relative to the two bodies. The offsets from the bodies to the center
of stiffness are indicated by x1, y1, x2 and y2 as shown in the picture below (left).
A 2-D spring in rest (left) and stretched (right).
20-sim 4.6 Reference Manual
813
9. Library
Note that x1, y1, x2 and y2 are defined with respect to the spring coordinate frame
which is at the center of the spring. This means in the picture above x1 and y1 have a
negative value and x2 and y2 have a positive value.
When the spring is stretched the offsets will change by the spring elongations x, y and
as indicated in the picture (right). The center of stiffness is always located precisely in
the middle of the spring elongations. Because all spring equations will be calculated from
the center of stiffness this means that the offsets for a stretched spring are (x1 - x/2),
(y1 - y/2), (x2 + x/2) and (y2 + y/2).
For a realistic representation of vibration behavior, every 2D spring has a damper in
parallel. If you want to turn off the effects of this damper, choose the damping
parameters equal to zero. If you want to damp out unwanted vibrations, choose the
damping parameters equal to 0.1% to 10% of the spring parameters.
Linear Slides
Take a look at the TwoDSpring model in the picture below. If we replace the spring in xdirection by a zero force we have created a linear slide.
Linear slide: x = free, y = stiff,
= stiff.
C onsider a carriage that is clamped with four wheels to a slide. In the x-direction the
carriage is free to move, which is equal to a zero force. The limited stiffness of the
wheels is represented by springs. If there is a force with equal sign on both wheels, the
carriage will slightly move in the y-direction. If there is a force with opposite sign on
both wheels, the carriage will only rotate. This can be represented by two independent
springs: one in the y-direction and -direction.
If we repeat the same experiment and replace the spring in x-direction by a zero force
and the spring in -direction by a zero torque, we have created a linear slide with
rotational freedom. In practice this can be found with carriages that are clamped with a
limited set of wheels as shown below.
20-sim 4.6 Reference Manual
814
9. Library
Linear slide: x = free, y = stiff,
= free.
The TwoDLibrary contains four Linear Slide models:
1
TwoDLinearSlide-X
x = free, y = stiff,
= stiff
2
TwoDLinearSlide-Y
x = stiff, y = free,
= stiff
3
TwoDLinearSlide-XTheta
x = free, y = stiff,
= free
4
TwoDLinearSlide-YTheta
x = free, y = stiff,
= free
Linear Actuators
Instead of replacing the spring in x-direction with a zero force as with the linear slides,
we can replace it by a 1D power port to allow all kind of connections with the models
from the standard library. In this way we have created a linear actuator, that allows
every kind of actuation.
Like the linear slides, for the linear actuators we can also replace the spring in direction by a zero torque, which makes the total number of linear actuator models
equal to four:
20-sim 4.6 Reference Manual
815
9. Library
1
TwoDLinearActuator-X
Fx and vx connected to a port
2
TwoDLinearActuator-Y
Fy and vy connected to a port
3
TwoDLinearActuator-
Fx and vx connected to a port, T = 0,
=0
Fy and vy connected to a port, T = 0,
=0
XTheta
4
TwoDLinearActuatorYTheta
With the port connection ever possible form of actuation can be created. Two examples
are shown below.
TwoDSpring
Library
Iconic Diagrams\Mechanical\Translation\2DSmallAngles
Use
Domains: C ontinuous. Size: 2-D. Kind: Iconic Diagrams (2D Planar).
Description
A TwoDSpring model represents a flexible connection between two bodies. The bodies
are located relative to the center of stiffness. The offsets from the bodies to the center
of stiffness are indicated by x1, y1, x2 and y2 as shown in the picture below (left).
20-sim 4.6 Reference Manual
816
9. Library
A 2-D spring in rest (left) and stretched (right).
Note that x1, y1, x2 and y2 are defined with respect to the spring coordinate frame
which is at the center of the spring. This means in the picture above x1 and y1 have a
negative value and x2 and y2 have a positive value.
When the spring is stretched the offsets will change by the spring elongations x, y and
as indicated in the picture (right). The center of stiffness is always located precisely in
the middle of the spring elongations. Because all spring equations will be calculated from
the center of stiffness this means that the offsets for a stretched spring are (x1 - x/2),
(y1 - y/2), (x2 + x/2) and (y2 + y/2).
For a realistic representation of vibration behavior, every 2D spring has a damper in
parallel. If you want to turn off the effects of this damper, choose the damping
parameters equal to zero. If you want to damp out unwanted vibrations, choose the
damping parameters equal to 0.1% to 10% of the spring parameters.
Interface
Ports
Description
P[3]
Port with three degrees of freedom (x, y, ).
Causality
fixed force out P
Parameters
x1
distance in x-direction from center of stiffness to port 1 [m]
y1
distance in y-direction from center of stiffness to port 1 [m]
x2
distance in x-direction from center of stiffness to port 2 [m]
y2
distance in y-direction from center of stiffness to port 2 [m]
kx
stiffness in x-direction [N/m]
ky
stiffness in y-direction [N/m]
kth
rotational stiffness [N.m/rad]
dx
damping in x-direction [N.s/m]
20-sim 4.6 Reference Manual
817
9. Library
dy
damping in y-direction [N.s/m]
dth
rotational damping [N.m.s/rad]
Initial Values
x_initial
The initial extension of the spring [m].
y_initial
The initial extension of the spring [m].
theta_initial
The initial rotation of the spring [rad].
TwoDLinearSlide
Library
Iconic Diagrams\Mechanical\Translation\2DSmallAngles
Implementations
X
Y
XTheta
YTheta
Use
Domains: C ontinuous. Size: 2-D. Kind: Iconic Diagrams (2D Planar).
Description - X
The TwoDLinearSlide-X model represents a flexible connection between two bodies in yand -direction. The bodies are located relative to the center of stiffness. The offsets
from the bodies to the center of stiffness are indicated by the parameters x1, y1, x2 and
y2 as shown in the picture below.
The TwoDLinearSLide-X model is based on the TwoDSpring model by replacing the
spring and damper in x-direction by a zero force. C onsider a carriage that is clamped
with four wheels to a slide. In the x-direction the carriage is free to move, which is equal
to a zero force. The limited stiffness of the wheels is represented by springs. If there is a
force with equal sign on both wheels, the carriage will slightly move in the y-direction. If
there is a force with opposite sign on both wheels, the carriage will only rotate. This can
be represented by two independent springs: one in the y-direction and -direction.
20-sim 4.6 Reference Manual
818
9. Library
Linear slide: x = free, y = stiff,
= stiff.
For a realistic representation of vibration behavior, every spring has a damper in
parallel. If you want to turn off the effects of this damper, choose the damping
parameters equal to zero. If you want to damp out unwanted vibrations, choose the
damping parameters equal to 0.1% to 10% of the spring parameters.
Interface - X
Ports
Description
P[3]
Port with three degrees of freedom (x, y, ).
Causality
fixed force out P
Parameters
x1
distance in x-direction from center of stiffness to port 1 [m]
y1
distance in y-direction from center of stiffness to port 1 [m]
x2
distance in x-direction from center of stiffness to port 2 [m]
y2
distance in y-direction from center of stiffness to port 2 [m]
ky
stiffness in y-direction [N/m]
kth
rotational stiffness [N.m/rad]
dy
damping in y-direction [N.s/m]
dth
rotational damping [N.m.s/rad]
Initial Values
y_initial
The initial extension of the spring [m].
theta_initial
The initial rotation of the spring [rad].
Description - Y
The TwoDLinearSlide-Y model is equal to the TwoDLinearSlide-X model except that here
the movement is free in the y-direction.
20-sim 4.6 Reference Manual
819
9. Library
Interface - Y
Ports
Description
P[3]
Port with three degrees of freedom (x, y, ).
Causality
fixed force out P
Parameters
x1
distance in x-direction from center of stiffness to port 1 [m]
y1
distance in y-direction from center of stiffness to port 1 [m]
x2
distance in x-direction from center of stiffness to port 2 [m]
y2
distance in y-direction from center of stiffness to port 2 [m]
kx
stiffness in x-direction [N/m]
kth
rotational stiffness [N.m/rad]
dx
damping in x-direction [N.s/m]
dth
rotational damping [N.m.s/rad]
Initial Values
x_initial
The initial extension of the spring [m].
theta_initial
The initial rotation of the spring [rad].
Description - XTheta
The TwoDLinearSlide-XTheta model represents a flexible connection between two bodies
in y-direction. The bodies are located relative to the center of stiffness. The offsets from
the bodies to the center of stiffness are indicated by the parameters x1, y1, x2 and y2
as shown in the picture below.
The TwoDLinearSLide-X model is based on the TwoDSpring model by replacing the
spring and damper in x- and -direction by a zero force. C onsider a carriage that is
clamped with two wheels to a slide. In the x-direction the carriage is free to move, which
is equal to a zero force. The carriage is also free to rotate, which is equal to a zero
torque. The limited stiffness of the wheels is represented by springs. If there is a force
on the wheels, the carriage will slightly move in the y-direction.
20-sim 4.6 Reference Manual
820
9. Library
Linear slide: x = free, y = stiff,
= stiff.
For a realistic representation of vibration behavior, every spring has a damper in
parallel. If you want to turn off the effects of this damper, choose the damping
parameters equal to zero. If you want to damp out unwanted vibrations, choose the
damping parameters equal to 0.1% to 10% of the spring parameters.
Interface - XTheta
Ports
Description
P[3]
Port with three degrees of freedom (x, y, ).
Causality
fixed force out P
Parameters
x1
distance in x-direction from center of stiffness to port 1 [m]
y1
distance in y-direction from center of stiffness to port 1 [m]
x2
distance in x-direction from center of stiffness to port 2 [m]
y2
distance in y-direction from center of stiffness to port 2 [m]
ky
stiffness in y-direction [N/m]
dy
damping in y-direction [N.s/m]
Initial Values
y_initial
The initial extension of the spring [m].
Description - YTheta
The TwoDLinearSlide-YTheta model is equal to the TwoDLinearSlide-XTheta model
except that here the movement is free in the y and -direction.
Interface - YTheta
Ports
Description
20-sim 4.6 Reference Manual
821
9. Library
P[3]
Port with three degrees of freedom (x, y, ).
Causality
fixed force out P
Parameters
x1
distance in x-direction from center of stiffness to port 1 [m]
y1
distance in y-direction from center of stiffness to port 1 [m]
x2
distance in x-direction from center of stiffness to port 2 [m]
y2
distance in y-direction from center of stiffness to port 2 [m]
kx
stiffness in x-direction [N/m]
dx
damping in x-direction [N.s/m]
Initial Values
x_initial
The initial extension of the spring [m].
TwoDLinearActuator
Library
Iconic Diagrams\Mechanical\Translation\2DSmallAngles
Implementations
X
Y
XTheta
YTheta
Use
Domains: C ontinuous. Size: 1-D / 2-D. Kind: Iconic Diagrams (1D Translation, 2D
Planar).
Description - X
The TwoDLinearActuator-X model represents a flexible connection between two bodies
in y- and -direction. The TwoDLinearActuator-X model is based on the TwoDLinearSlideX model. Instead of using a zero force in the x-direction, there is a coupling with a 1D
translation port for the actuator force.
20-sim 4.6 Reference Manual
822
9. Library
C onsider a carriage that is clamped with four wheels to a slide. In the x-direction the
carriage can be moved by a certain force. The limited stiffness of the wheels is
represented by springs. If there is a force with equal sign on both wheels, the carriage
will slightly move in the y-direction. If there is a force with opposite sign on both wheels,
the carriage will only rotate. This can be represented by two independent springs: one in
the y-direction and -direction.
Linear slide: x = free, y = stiff,
= stiff.
For a realistic representation of vibration behavior, every spring has a damper in
parallel. If you want to turn off the effects of this damper, choose the damping
parameters equal to zero. If you want to damp out unwanted vibrations, choose the
damping parameters equal to 0.1% to 10% of the spring parameters.
With the 1D port connection every possible form of actuation can be created using the
models from the standard library. Two examples are shown below.
Interface - X
Ports
Description
P[3]
Port with three degrees of freedom (x, y, ).
20-sim 4.6 Reference Manual
823
9. Library
p
1D translation port
Causality
fixed force out P
Parameters
x1
distance in x-direction from center of stiffness to port 1 [m]
y1
distance in y-direction from center of stiffness to port 1 [m]
x2
distance in x-direction from center of stiffness to port 2 [m]
y2
distance in y-direction from center of stiffness to port 2 [m]
ky
stiffness in y-direction [N/m]
kth
rotational stiffness [N.m/rad]
dy
damping in y-direction [N.s/m]
dth
rotational damping [N.m.s/rad]
Initial Values
y_initial
The initial extension of the spring [m].
theta_initial
The initial rotation of the spring [rad].
Description - Y
The TwoDLinearActuator-Y model is equal to the TwoDLinearActuator-X model except
that here the force acts in the y-direction.
Interface - Y
Ports
Description
P[3]
Port with three degrees of freedom (x, y, ).
p
1D translation port
Causality
fixed force out P
Parameters
x1
distance in x-direction from center of stiffness to port 1 [m]
y1
distance in y-direction from center of stiffness to port 1 [m]
x2
distance in x-direction from center of stiffness to port 2 [m]
y2
distance in y-direction from center of stiffness to port 2 [m]
kx
stiffness in x-direction [N/m]
kth
rotational stiffness [N.m/rad]
dx
damping in x-direction [N.s/m]
dth
rotational damping [N.m.s/rad]
Initial Values
x_initial
The initial extension of the spring [m].
theta_initial
The initial rotation of the spring [rad].
20-sim 4.6 Reference Manual
824
9. Library
Description - XTheta
The TwoDLinearActuator-XTheta model represents a flexible connection between two
bodies in y-direction. The TwoDLinearActuator-XTheta model is based on the
TwoDLinearSlide-XTheta model. Instead of using a zero force in the x-direction, there is
a coupling with a 1D translation port for the actuator force.
C onsider a carriage that is clamped with two wheels to a slide. In the x-direction the
carriage can be moved by a certain force. The carriage is free to rotate, which is equal
to a zero torque. The limited stiffness of the wheels is represented by springs. If there is
a force acting on both wheels, the carriage will slightly move in the y-direction. If there
is a force acting on the wheels, the carriage will slightly move in the y-direction.
Linear slide: x = free, y = stiff,
= stiff.
For a realistic representation of vibration behavior, the spring has a damper in parallel.
If you want to turn off the effects of this damper, choose the damping parameters equal
to zero. If you want to damp out unwanted vibrations, choose the damping parameter
equal to 0.1% to 10% of the spring parameter.
With the 1D port connection every possible form of actuation can be created using the
models from the standard library. For example see the TwoDLinearActuator-X model.
Interface - XTheta
Ports
Description
P[3]
Port with three degrees of freedom (x, y, ).
p
1D translation port
Causality
fixed force out P
Parameters
x1
distance in x-direction from center of stiffness to port 1 [m]
y1
distance in y-direction from center of stiffness to port 1 [m]
x2
distance in x-direction from center of stiffness to port 2 [m]
y2
distance in y-direction from center of stiffness to port 2 [m]
20-sim 4.6 Reference Manual
825
9. Library
ky
stiffness in y-direction [N/m]
dy
damping in y-direction [N.s/m]
Initial Values
y_initial
The initial extension of the spring [m].
Description - YTheta
The TwoDLinearActuator-YTheta model is equal to the TwoDLinearActuator-XTheta
model except that here the force acts in the y-direction.
Interface - YTheta
Ports
Description
P[3]
Port with three degrees of freedom (x, y, ).
p
1D translation port
Causality
fixed force out P
Parameters
x1
distance in x-direction from center of stiffness to port 1 [m]
y1
distance in y-direction from center of stiffness to port 1 [m]
x2
distance in x-direction from center of stiffness to port 2 [m]
y2
distance in y-direction from center of stiffness to port 2 [m]
kx
stiffness in x-direction [N/m]
kth
rotational stiffness [N.m/rad]
dx
damping in x-direction [N.s/m]
dth
rotational damping [N.m.s/rad]
Initial Values
x_initial
The initial extension of the spring [m].
theta_initial
The initial rotation of the spring [rad].
20-sim 4.6 Reference Manual
826
9. Library
Tips
When you are working with the 2D-Library for small angles, it is good to keep the
following tips in mind:
The 2DSmallRotations library is very well suited for frequency domain analysis
through linearization.
The 2DSmallRotations library is not suited for large rotations. C onsider a rotation of
0.05 degrees or 1 mrad as an upper bound for every model part.
It is not possible in 20-sim to use vector elements with mixed units. Therefore
element number 3 will be displayed with units [m/s] and [N] although it really is [rad/
s] and [Nm]!
The vector element number (1, 2 or 3) denotes the degree of freedom. Flipping or
rotating of a model does not change this degree (e.g. a rotation does not change
from x into y). Preferably leave the orientation of the models as they pop up on the
screen.
To create intuitive models, the positive direction of each degree of freedom is defined
as: x from left to right, y from bottom to top, ? counter clockwise.
To prevent misinterpretation of a model by other users, stick to the drawing rules
that are given.
A TwoDBody model can be connected to any other element of the 2D-library except
other 2D-bodies.
A TwoDBody model can be connected to 1D models using the TwoDPoint models as
intermediate.
TwoDPoint models can only be connected to TwoDBody models.
If a TwoDBody model is connected to TwoDPoint models only, it has to be connected
to at least three non-coinciding, unequal (i.e. not having the same offsets)
TwoDPoints to prevent it from free motion.
3DSmallRotation
ThreeDLibrary
Library
The 3DSmallRotation library contains 3D models that are only suited for small rotations.
The library is comparable to the 2DSmallRotation library and suited for modeling
systems that, due to limited stiffness, experience rotation that should be accounted for.
Degrees of Freedom
All models in 3DSmallRotation library contain one or more ports with 6 degrees of
freedom The first three degrees of freedom denote the x-, y- and z-position and the last
three degrees of freedom denote the rotation around the x-, y- and z-axes. A vector
notation is used to denote the forces and velocities for these degrees of freedom. For a
model with a port P the notation is:
degree
identity
forces
velocities
x
position
P.F[1] [N]
P.v[1] [m/s]
20-sim 4.6 Reference Manual
827
9. Library
y
position
P.F[2] [N]
P.v[2] [m/s]
z
position
P.F[3] [N]
P.v[3] [m/s]
x
angle
P.F[4] [Nm] P.v[4] [rad/s]
y
angle
P.F[5] [Nm] P.v[5] [rad/s]
z
angle
P.F[6] [Nm] P.v[6] [rad/s]
Note
It is not possible in 20-sim to use vector elements with mixed units. Therefore
element number 4 to 6 will be displayed with units [m/s] and [N] although it really is
[rad/s] and [Nm]!
The vector element number (1 to 6) denotes the identity of the degree of freedom.
Flipping or rotating of a model does not change the this identity (e.g. a rotation does
not change x into y). Preferably leave the orientation of the models as they pop up
on the screen.
3D-body
The central model in the 3DSmallRotation library is the 3D-body model which describes a
body with 6 degrees of freedom.
3D-mass
The 3D-mass model is a body with only mass and zero rotational inertia.
Points
The 3D-body model is nothing more than a center of mass. To connect a 3D-body with
the outside (single degree of freedom) world, 3D-points are used. A 3D-point describes
the offset between the center of mass and the connection point.
A 3D-body has to be connected to 3D-points with at least three orthogonal nonzero
offsets to prevent it from free rotation.
A 3D-body has to be connected to at least three orthogonal 3D-point models to
prevent it from free motion.
Sensors
The velocities of bodies can be inspected directly in the body models. To find positions
sensor models are available.
20-sim 4.6 Reference Manual
828
9. Library
ThreeDBody
Library
Iconic Diagrams\Mechanical\Translation\3DSmallAngles
Use
Domains: C ontinuous. Size: 6D. Kind: Iconic Diagrams (Translation,Rotation).
Description
This is a model of a 6 degree of freedom body. It is the equivalent of the 2D-body
model. The first three degrees of freedom in this model are represented by a single
mass and the last three degrees of freedom by a rotational inertia. The 3D-body has to
be connected to at least three orthogonal 3D-points, which define the reaction forces.
The model has a preferred velocity out causality. The corresponding constitutive
equations then contain an integration. The model can also have the non-preferred force
out causality. The constitutive equations then contain a differentiation. Because any
number of connections can be made, successive ports are named P1, P2, P3 etc. 20-sim
will automatically create equations such that the resulting force P.F is equal to the sum of
the forces of all connected ports P1 .. Pn. The velocities of all connected ports are equal
to P.v
P.F = sum(P1.F, P2.F, ....)
P.v = P1.v = P2.v = ....
velocity out causality (preferred):
I = [1/M;1/M;1/M;1/J[1];1/J[2];1/J[3]];
P.v = I.*int(P.F);
force out causality:
I = [1/M;1/M;1/M;1/J[1];1/J[2];1/J[3]];
P.F = I-1.*ddt(P.v);
Interface
Ports
Description
P[6]
Port with 6 degrees of freedom. Any number of connections can be
made.
Causality
preferred velocity
out
Parameters
M
Mass [kg].
J[3]
Moment of inertia for three axes [kgm2]
20-sim 4.6 Reference Manual
829
9. Library
Note
A body has to be connected to 3D-points with at least three orthogonal nonzero
offsets to prevent it from free rotation.
A 3D-body has to be connected to at least three orthogonal 3D-point models to
prevent it from free motion.
Flipping or rotating the model does not change the direction of applied forces or
measured directions. Preferably leave the orientation as it pops up on the screen.
It is not possible in 20-sim to use vector elements with mixed units. Therefore
element number 4 to 6 will be displayed with units [m/s] and [N] although it really is
[rad/s] and [Nm]!
ThreeDFixedWorld
Library
Iconic Diagrams\Mechanical\Translation\3DSmallAngles
Use
Domains: C ontinuous. Size: 6-D. Kind: Iconic Diagrams (Translation,Rotation).
Description
This model represents the fixed world in 6 degrees of freedom It can be connected to a
3D-body model to freeze its motion.
Interface
Ports
Description
P
Port with 6 degrees of freedom.
Causality
fixed velocity out
P
ThreeDForceActuator-Relative
Library
Iconic Diagrams\Mechanical\Translation\3DSmallAngles
Use
Domains: C ontinuous. Size: 1-D/6-D. Kind: Iconic Diagrams (Translation,Rotation).
Description
This model represents an ideal actuator. The actuator applies a force between its two
terminals. This force can be set to a (fluctuating) value given by the input signal F, the
velocity is indifferent.
20-sim 4.6 Reference Manual
830
9. Library
This model is the equivalent of the 1 degree of fredom model ForceActuatorRelative.emx. It model represents an ideal actuator. The actuator applies a force
between its two terminals. The force can be set to a (fluctuating) value given by a vector
K multiplied by a signal F, the velocity is indifferent. By setting the elements of the
vector K equal to zero or one, specific elements of the 6 degrees of freedom output
force can set equal to the input signal F.
P_high.F[1:6] = P_low.F[1:6] = K*F;
Interface
Ports
Description
P_high[6],
Both terminals of the port with 6 degrees of freedom.
P_low[6]
Causality
fixed force out P
Parameters
K[6]
Vector with 6 elements to set the 6 force elements on or off.
ThreeDForceActuator
Library
Iconic Diagrams\Mechanical\Translation\3DSmallAngles
Use
Domains: C ontinuous. Size: 1-D/6-D. Kind: Iconic Diagrams (Translation,Rotation).
Description
This model is the equivalent of the 1 degree of fredom model ForceActuator.emx. It
model represents an ideal actuator. The actuator is mounted to the fixed world and
applies a force. The force can be set to a (fluctuating) value given by a vector K
multiplied by a signal F, the velocity is indifferent. By setting the elements of the vector
K equal to zero or one, specific elements of the 6 degrees of freedom output force can
set equal to the input signal F.
P.F[1:6] = K*F;
Interface
Ports
Description
P
Port with 6 degrees of freedom.
Causality
fixed force out P
Parameters
K[6]
Vector with 6 elements to set the 6 force elements on or off.
20-sim 4.6 Reference Manual
831
9. Library
ThreeDMass
Library
Iconic Diagrams\Mechanical\Translation\3DSmallAngles
Use
Domains: C ontinuous. Size: 6D. Kind: Iconic Diagrams (Translation,Rotation).
Description
This is a model of a 6 degree of freedom body without rotational inertia. The 3D-mass
has to be connected to at least three orthogonal 3D-points, which define the reaction
forces.
The model has a fised velocity out causality. Because any number of connections can be
made, successive ports are named P1, P2, P3 etc. 20-sim will automatically create
equations such that the resulting force P.F is equal to the sum of the forces of all
connected ports P1 .. Pn. The velocities of all connected ports are equal to P.v
P.F = sum(P1.F, P2.F, ....)
P.v = P1.v = P2.v = ....
I = [1/M;1/M;1/M];
P.v[1..3] = I.*int(P.F);
P.v[4..6] = 0;
Interface
Ports
Description
P[6]
Port with 6 degrees of freedom. Any number of connections can be
made.
Causality
fixed velocity out
Parameters
M
Mass [kg].
Note
A 3D-body has to be connected to 3D-points with at least three orthogonal nonzero
offsets to prevent it from free rotation.
A 3D-body has to be connected to at least three orthogonal 3D-point models to
prevent it from free motion.
Flipping or rotating the model does not change the direction of applied forces or
measured directions. Preferably leave the orientation as it pops up on the screen.
It is not possible in 20-sim to use vector elements with mixed units. Therefore
element number 4 to 6 will be displayed with units [m/s] and [N] although it really is
[rad/s] and [Nm]!
20-sim 4.6 Reference Manual
832
9. Library
ThreeDPoint
Library
Iconic Diagrams\Mechanical\Translation\3DSmallAngles
Implementations
X
Y
Z
XYZ
Use
Domains: C ontinuous. Size: 1-D/6-D. Kind: Iconic Diagrams (Translation,Rotation).
Description - X
A point model forms the connection between the single degree of freedom part of a
system and the center of mass of a 3D-body.
The 3D-point-X model is the equivalent of the 2D-point-X model. It describes the
translation of force in x-direction to a force in 6 degrees of freedom. Because there are
three rotational degrees of freedom, the 3D-point-X model has two offsets, YP and ZP.
The single degree of freedom port p_in describes the connection in x-direction and the 6
degree of freedom port P_out describes connection with the 3D-body.
P_out.F[1] = p_in.F;
// x-direction
P_out.F[2] = 0;
// y-direction
P_out.F[3] = 0;
// z-direction
P_out.F[4] = 0;
// x-rotation
P_out.F[5] = ZP*p_in.F;
// y-rotation
P_out.F[6] = -YP*p_in.F;
// z-rotation
p_in.v = P_out.v[1] - YP*P_out.v[6]
// x-direction
+ ZP *P_out.v[5];
As can bee seen from the equations, a nonzero offset YP or ZP (distance from center of
mass) in a 3D-point will result in a momentum. Therefore a 3D-body has to be
connected to 3D-points with at least three orthogonal nonzero offsets to prevent it from
free rotation.
The equations also show that the y-direction and z-direction are not affected by the 3Dpoint-X model. Therefore each 3D-body has to be connected to at least three orthogonal
3D-point models to prevent it from free motion.
Interface - X
Ports
Description
20-sim 4.6 Reference Manual
833
9. Library
p_in
Translation port with one degree of freedom (x [m]).
P_out[3]
Port with 6 degrees of freedom.
Causality
fixed
force
out
P_out
fixed velocity out
p_in
Parameters
YP
Distance (y-direction) between connection and center of mass [m].
ZP
Distance (z-direction) between connection and center of mass [m].
Description - Y
A point model forms the connection between the single degree of freedom part of a
system and the center of mass of a 3D-body.
The 3D-point-Y model is the equivalent of the 2D-point-Y model. It describes the
translation of force in x-direction to a force in 6 degrees of freedom. Because there are
three rotational degrees of freedom, the 3D-point-Y model has two offsets, XP and ZP.
The single degree of freedom port p_in describes the connection in x-direction and the 6
degree of freedom port P_out describes connection with the 3D-body.
P_out.F[1] = 0;
// x-direction
P_out.F[2] = p_in.F;
// y-direction
P_out.F[3] = 0;
// z-direction
P_out.F[4] = -ZP*p_in.F;
// x-rotation
P_out.F[5] = 0;
// y-rotation
P_out.F[6] = XP*p_in.F;
// z-rotation
p_in.v = P_out.v[2] + XP*P_out.v[6]
// y-direction
- ZP *P_out.v[4];
As can bee seen from the equations, a nonzero offset XP or ZP (distance from center of
mass) in a 3D-point will result in a momentum. Therefore a 3D-body has to be
connected to 3D-points with at least three orthogonal nonzero offsets to prevent it from
free rotation.
The equations also show that the x-direction and z-direction are not affected by the 3Dpoint-Y model. Therefore each 3D-body has to be connected to at least three orthogonal
3D-point models to prevent it from free motion.
Interface - Y
Ports
Description
20-sim 4.6 Reference Manual
834
9. Library
p_in
Translation port with one degree of freedom (x [m]).
P_out[3]
Port with 6 degrees of freedom.
Causality
fixed
force
out
P_out
fixed velocity out
p_in
Parameters
XP
Distance (x-direction) between connection and center of mass [m].
ZP
Distance (z-direction) between connection and center of mass [m].
Description - Z
A point model forms the connection between the single degree of freedom part of a
system and the center of mass of a 3D-body.
The 3D-point-Z model is the equivalent of the 2D-point-X model. It describes the
translation of force in z-direction to a force in 6 degrees of freedom. Because there are
three rotational degrees of freedom, the 3D-point-Y model has two offsets, XP and YP.
The single degree of freedom port p_in describes the connection in x-direction and the 6
degree of freedom port P_out describes connection with the 3D-body.
P_out.F[1] = 0;
// x-direction
P_out.F[2] = 0;
// y-direction
P_out.F[3] = p_in.F;
// z-direction
P_out.F[4] = YP*p_in.F;
// x-rotation
P_out.F[5] = -XP*p_in.F;
// y-rotation
P_out.F[6] = 0;
// z-rotation
p_in.v = P_out.v[3] - XP*P_out.v[5]
// y-direction
+ YP *P_out.v[4];
As can bee seen from the equations, a nonzero offset XP or YP (distance from center of
mass) in a 3D-point will result in a momentum. Therefore a 3D-body has to be
connected to 3D-points with at least three orthogonal nonzero offsets to prevent it from
free rotation.
The equations also show that the x-direction and y-direction are not affected by the 3Dpoint-Z model. Therefore each 3D-body has to be connected to at least three orthogonal
3D-point models to prevent it from free motion.
Interface - Z
Ports
Description
p_in
Translation port with one degree of freedom (x [m]).
20-sim 4.6 Reference Manual
835
9. Library
P_out[3]
Port with 6 degrees of freedom.
Causality
fixed force out
P_out
fixed velocity out
p_in
Parameters
XP
YP
Distance (x-direction) between connection and center of mass [m].
Distance (y-direction) between connection and center of mass [m].
Description - XYZ
A point model forms the connection between the single degree of freedom part of a
system and the center of mass of a 3D-body.
The 3D-point-XYZ model is a combination of the 3D-point-X model, the 3D-point-Y model
and the 3D-point-Z model. It describes the translation of force in x-direction, y-direction
and z-ditrection to a force in 6 degrees of freedom. Because there are three rotational
degrees of freedom, the model has three offsets, XP, YP and ZP.
The single degree of freedom ports p_inx, p_iny and p_inz describes the connection in xdirection, y-direction and z-direction and the 6 degree of freedom port P_out describes
connection with the 3D-body.
P_out.F[1] = p_inx.F;
// x-direction
P_out.F[2] = p_iny.F;
// y-direction
P_out.F[3] = p_inz.F;
// z-direction
P_out.F[4] = YP*p_inz.F - ZP*p_iny.F;
// x-rotation
P_out.F[5] = -XP*p_inz.F + ZP*p_inx.F;
// y-rotation
P_out.F[6] = XP*p_iny.F - YP*p_inx.F;
// z-rotation
p_inx.v = P_out.v[1] - YP*P_out.v[6] + ZP // x-direction
*P_out.v[5];
// y-direction
p_iny.v = P_out.v[2] + XP*P_out.v[6] - ZP // z-direction
*P_out.v[4];
p_inz.v = P_out.v[3] - XP*P_out.v[5]
+ YP *P_out.v[4];
As can bee seen from the equations, a nonzero offset XP, YP or ZP (distance from center
of mass) in a 3D-point will result in a momentum. Therefore a 3D-body has to be
connected to 3D-points with at least three orthogonal nonzero offsets to
prevent it from free rotation.
20-sim 4.6 Reference Manual
836
9. Library
Interface - XYZ
Ports
Description
p_inx
Translation port with one degree of freedom [m].
p_iny
Translation port with one degree of freedom [m].
p_inz
Translation port with one degree of freedom [m].
P_out[3]
Port with 6 degrees of freedom.
Causality
fixed
force
out
P_out
fixed velocity out
p_in
Parameters
YP
Distance (y-direction) between connection and center of mass [m].
XP
Distance (x-direction) between connection and center of mass [m].
theta
Angle of impact of the single degree of freedom port [rad].
Note
A body has to be connected to 3D-points with at least three orthogonal nonzero
offsets to prevent it from free rotation.
A 3D-body has to be connected to at least three orthogonal 3D-point models to
prevent it from free motion.
Flipping or rotating the model does not change the direction of applied forces or
measured directions. Preferably leave the orientation as it pops up on the screen.
It is not possible in 20-sim to use vector elements with mixed units. Therefore
element number 4 to 6 will be displayed with units [m/s] and [N] although it really is
[rad/s] and [Nm]!
ThreeDPositionSensor
Library
Iconic Diagrams\Mechanical\Translation\3DSmallAngles
Use
Domains: C ontinuous. Size: 1-D/6D. Kind: Iconic Diagrams (Translation,Rotation).
Description
This model is used to find the positions of a 3D-body model. It has a port P which can be
connected to the body and an output signal pos that denotes the positions
(x,y,z, x y z) of the body.
20-sim 4.6 Reference Manual
837
9. Library
Interface
Ports
Description
P[3]
Port with 6 degrees of freedom.
Causality
fixed force out P
Output
Pos(6)
Absolute positions [m].
Initial Values
Pos_initial[6]
Initial positions [m]
Note
The sensor model yields an absolute position starting at 0. Set the initial values to
yield a position starting at other values.
It is not possible in 20-sim to use vector elements with mixed units. Therefore
element number 4 to 6 will be displayed with units [m] although it really is [rad]!
ThreeDSpringDamper
Library
Iconic Diagrams\Mechanical\Translation\3DSmallAngles
Use
Domains: C ontinuous. Size: 1-D/6-D. Kind: Iconic Diagrams (Translation,Rotation).
Description
This model is the equivalent of the 1 degree of freedom model SpringDamper.emx. It
model represents an ideal spring-damper. The model has a preferred force out
causality. The corresponding constitutive equations then contain integrations. The
element can also have the non-preferred velocity out causality. The constitutive
equations then contain derivatives. The spring-damper model has separate high and low
ports. The equations are
P.F = P_high.F = P_low.F
P.v = P_high.v - P_low.v
Force out causality (preferred):
X = int(P.v);
P.F = S*X + D*P.v;
Velocity out causality:
20-sim 4.6 Reference Manual
838
9. Library
P.v = ddt(X);
X = S-1*(P.F - D*P.v);
Interface
Ports
Description
P_high[6],
Both terminals of a port with 6 degrees of freedom.
P_low[6]
Causality
preferred
force
out P
Variables
X
Vector with 6 spring extension values [m].
Parameters
S[6]
Stiffness vector [N/m]
D[6]
Damping vector [N.s/m]
Initial Values
X_initial[6]
Vector with 6 initial extension values of the spring [m].
Note
It is not possible in 20-sim to use vector elements with mixed units. Therefore element
number 4 to 6 will be displayed with units [m/s] and [N] although it really is [rad/s] and
[Nm] etc.!
ThreeDZeroForce
Library
Iconic Diagrams\Mechanical\Translation\3DSmallAngles
Use
Domains: C ontinuous. Size: 6-D. Kind: Iconic Diagrams (Translation,Rotation).
Description
This model can be used to connect any open end of another 3D model that is not
connected to the fixed world. It generates a three degree of freedom zero force while
the velocity is free.
Interface
Ports
Description
P
Port with 6 degrees of freedom.
Causality
fixed force out P
20-sim 4.6 Reference Manual
839
9. Library
Note
It is not possible in 20-sim to use vector elements with mixed units. Therefore element
number 4 to 6 will be displayed with units [m/s] and [N] although it really is [rad/s] and
[Nm] etc.!
Actuators
AccelerationActuator-Relative
Library
Iconic Diagrams\Mechanical\Translation\Actuators
Use
Domains:
Diagrams.
C ontinuous. Size:
1-D.
Kind:
Iconic
Diagrams
(Translation),
Block
Description
This model represents an ideal actuator. An acceleration input signal is integrated to a
velocity difference between its two terminals:
p_high.v = p_low.v + int(a,v_initial);
p_low.F = p_high.F = indifferent;
Interface
Ports
Description
p_high, p_low
Both terminals of the Translation port p.
Causality
fixed velocity out
Input
a
Acceleration [m/s2].
Parameters
v_initial
Initial velocity output of the integration [m/s].
AccelerationActuator
Library
Iconic Diagrams\Mechanical\Translation\Actuators
Use
Domains:
Diagrams.
C ontinuous. Size:
1-D.
Kind:
Iconic
Diagrams
(Translation),
Block
Description
This model represents an ideal actuator. An acceleration input signal is integrated to a
velocity at the translation port. The actuator is mounted to the fixed world:
20-sim 4.6 Reference Manual
840
9. Library
p.v = int(a,v_initial);
p.F = indifferent;
Interface
Ports
Description
p
Translation port.
Causality
fixed velocity out
Input
a
Acceleration [m/s2].
Parameters
v_initial
Initial velocity at the port [m/s].
CMABender
Library
Iconic Diagrams\Electric\Actuators
Iconic Diagrams\Mechanical\Translation\Actuators
Use
Domains:
Diagrams.
C ontinuous. Size:
1-D.
Kind:
Iconic
Diagrams
(Translation),
Block
Description
This model represents a piezo actuator. The actuator translates a voltage difference at
port p1 to a mechanical position difference between the base at port p2 and the end
effector at port p3.
Although the underlying equations of this model are equal to the equations of the
CMAStrecher.emx model, the default parameter values are typical for bending.
Interface
Ports
Description
p
Translation port.
Causality
fixed force out
Input
C
KF
m
k
B
C apacitance [F]
Voltage to force conversion factor [N/V]
Equivalent mass [kg]
Stiffness [N/m]
Relative damping ratio []
20-sim 4.6 Reference Manual
841
9. Library
KB
Force to voltage conversion factor [V/N]
CMAStretcher
Library
Iconic Diagrams\Electric\Actuators
Iconic Diagrams\Mechanical\Translation\Actuators
Use
Domains:
Diagrams.
C ontinuous. Size:
1-D.
Kind:
Iconic
Diagrams
(Translation),
Block
Description
This model represents a piezo actuator. The actuator translates a voltage difference at
port p1 to a mechanical position difference between the base at port p2 and the end
effector at port p3.
Although the underlying equations of this model are equal to the equations of the
C MABender.emx model, the default parameter values are typical for stretching.
Interface
Ports
Description
p
Translation port.
Causality
fixed force out
Input
C
KF
m
k
B
KB
C apacitance [F]
Voltage to force conversion factor [N/V]
Equivalent mass [kg]
Stiffness [N/m]
Relative damping ratio []
Force to voltage conversion factor [V/N]
20-sim 4.6 Reference Manual
842
9. Library
Force-Relative
Library
Iconic Diagrams\Mechanical\Translation\Actuators
Use
Domains:
Diagrams.
C ontinuous. Size:
1-D.
Kind:
Iconic
Diagrams
(Translation),
Block
Description
This model represents an ideal actuator. The actuator applies a force between its two
terminals. This force can be set to a constant value F, the velocity is indifferent.
p_high.F = p_low.F = F
Interface
Ports
Description
p_high, p_low
Both terminals of the Translation port p.
Causality
fixed force out
Parameters
F
Force [N]
Force
Library
Iconic Diagrams\Mechanical\Translation\Actuators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description
This model represents an ideal actuator. The actuator is mounted to the fixed world and
applies a force. The force can be set to a certain constant value, the velocity is
indifferent.
p.F = F;
Interface
Ports
Description
p
Translation port.
Causality
fixed force out
Parameters
20-sim 4.6 Reference Manual
843
9. Library
F
Force [N].
ForceActuator-Relative
Library
Iconic Diagrams\Mechanical\Translation\Actuators
Use
Domains:
Diagrams.
C ontinuous. Size:
1-D.
Kind:
Iconic
Diagrams
(Translation),
Block
Description
This model represents an ideal actuator. The actuator applies a force between its two
terminals. This force can be set to a (fluctuating) value given by the input signal F, the
velocity is indifferent.
p_high.F = p_low.F = F
Interface
Ports
Description
p_high, p_low
Both terminals of the Translation port p.
Causality
fixed force out
Input
F
Force [N]
ForceActuator
Library
Iconic Diagrams\Mechanical\Translation\Actuators
Use
Domains:
Diagrams.
C ontinuous. Size:
1-D.
Kind:
Iconic
Diagrams
(Translation),
Block
Description
This model represents an ideal actuator. The actuator is mounted to the fixed world and
applies a force. The force can be set to a (fluctuating) value given by the input signal F,
the velocity is indifferent.
20-sim 4.6 Reference Manual
844
9. Library
p.F = F;
Interface
Ports
Description
p
Translation port.
Causality
fixed force out
Input
F
Force [N].
PositionActuator-Relative
Library
Iconic Diagrams\Mechanical\Translation\Actuators
Use
Domains:
Diagrams.
C ontinuous. Size:
1-D.
Kind:
Iconic
Diagrams
(Translation),
Block
Description
This model represents an ideal actuator. A position input signal is differentiated by a
state variable filter to a velocity difference between its two terminals:
p_high.v = p_low.v + dx/dt;
p_low.F = p_high.F = indifferent;
Differentiation is performed by a state variable filter:
The S-domain function of this filter is equal to:
where f is the cut-off frequency. For very high values of f, the output becomes the pure
derivative of the input. High values of f, however, increase simulations times. A good
trade-off is a starting value of 1e5.
20-sim 4.6 Reference Manual
845
9. Library
Interface
Ports
Description
p_high, p_low
Both terminals of the Translation port p.
Causality
fixed velocity out
Input
x
Position [m].
Parameters
f
C ut-off frequency of the differentiation [Hz].
v_initial
Initial velocity output of the differentiation [m/s].
PositionActuator
Library
Iconic Diagrams\Mechanical\Translation\Actuators
Use
Domains:
Diagrams.
C ontinuous. Size:
1-D.
Kind:
Iconic
Diagrams
(Translation),
Block
Description
This model represents an ideal actuator. A position input signal is differentiated by a
state variable filter to a velocity at the translation port. The actuator is mounted to the
fixed world:
p.v = dx/dt;
p.F = indifferent;
Differentiation is performed by a state variable filter:
The S-domain function of this filter is equal to:
20-sim 4.6 Reference Manual
846
9. Library
where f is the cut-off frequency. For very high values of f, the output becomes the pure
derivative of the input. High values of f, however, increase simulations times. A good
trade-off is a starting value of 1e5.
Interface
Ports
Description
p
Translation port.
Causality
fixed velocity out
Input
x
Position [m].
Parameters
f
v_initial
C ut-off frequency of the differentiation [Hz].
Initial velocity at the port [m/s].
ServoMotor
Library
Iconic Diagrams\Mechanical\Rotation\Actuators
Iconic Diagrams\Mechanical\Translation\Actuators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Electric).
Description
This is a masked model which opens the Servo Motor Editor when edited. The servo
Motor Editor is a tool that can shows the torque speed plots numerous permanent
magnet motors and can generate a dynamic model from any motor that you select. The
following motor types are supported:
1.
Brush DC
2.
Brushless DC (trapezoidal EMC and square wave currents)
3.
AC synchronous (sinusoidal EMC and sinusoidal currents)
4.
AC synchronous linear (sinusoidal EMC and sinusoidal currents)
20-sim 4.6 Reference Manual
847
9. Library
Interface
Depending on the type of motor that you have selected, the interface can vary:
DC Brush
Ports
Description
p
Rotation port.
Causality
fixed
rotational
velocity out
Input
i
The input current [A]
DC Brushless
Ports
Description
p
Rotation port.
Causality
fixed
rotational
velocity out
Input
i
The maximum input current [A]
AC Synchronous
Ports
Description
p
Rotation port.
Causality
fixed
rotational
velocity out
Input
i_rms
The rms phase current [A]
AC Synchronous Linear
Ports
Description
p
Translation port.
Causality
fixed velocity out
Input
20-sim 4.6 Reference Manual
848
9. Library
i_rms
The rms phase current [A]
For more information on the parameters an variables of this model is referred to the
Mechatronic Toolbox.
Velocity-Relative
Library
Iconic Diagrams\Mechanical\Translation\Actuators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description
This model represents an ideal actuator. The actuator applies a velocity difference
between its two terminals. This velocity can be set to a constant value v, the force is
indifferent.
p_low.v = p_high.v + v
Interface
Ports
Description
p_high, p_low
Both terminals of the Translation port p.
Causality
fixed velocity out
Parameter
v
Velocity [m/s].
Velocity
Library
Iconic Diagrams\Mechanical\Translation\Actuators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description
This model represents an ideal actuator. The actuator is mounted to the fixed world and
applies a velocity. This velocity can be set to a certain constant value, the force is
indifferent.
20-sim 4.6 Reference Manual
849
9. Library
p.v = v;
Interface
Ports
Description
p
Translation port
Causality
fixed velocity out
Parameters
v
velocity [m/s]
VelocityActuator-Relative
Library
Iconic Diagrams\Mechanical\Translation\Actuators
Use
Domains:
Diagrams.
C ontinuous. Size:
1-D.
Kind:
Iconic
Diagrams
(Translation),
Block
Description
This model represents an ideal actuator. The actuator applies a velocity difference
between its two terminals. This velocity can be set to a (fluctuating) value given by the
input signal v, the force is indifferent.
p_high.v = p_low.v + v
Interface
Ports
Description
p_high, p_low
Both terminals of the Translation port p.
Causality
fixed velocity out
Input
v
Velocity [m/s].
20-sim 4.6 Reference Manual
850
9. Library
VelocityActuator
Library
Iconic Diagrams\Mechanical\Translation\Actuators
Use
Domains:
Diagrams.
C ontinuous. Size:
1-D.
Kind:
Iconic
Diagrams
(Translation),
Block
Description
This model represents an ideal actuator. The actuator is mounted to the fixed world and
applies a velocity. This velocity can be set to a (fluctuating) value given by the input
signal v, the force is indifferent.
p.v = v;
Interface
Ports
Description
p
Translation port.
Causality
fixed velocity out
Input
v
Velocity [m/s].
Components
Backlash
Library
Iconic Diagrams\Mechanical\Translation\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description
This model represents backlash by a spring damper system. Inside an outside the play,
spring and damping can be set separately. Discontinuities are avoided by adding a round
off. The model can has a force out causality. The port p of this model has separate high
and low terminals. The equations are:
20-sim 4.6 Reference Manual
851
9. Library
p.F = p_high.F = p_low.F
p.v = p_high.v - p_low.v
with x the position within the play. Real backlash behavior is obtained by choosing low
stiffness and damping values inside the play and choosing high stiffness and damping
values outside the play.
The parameter ep determines the smoothness of the force curve that is obtained. A
larger value (> 0.01) makes the force change gradually when the position reaches the
play boundaries. A smaller value (< 0.001 ) makes the force change abruptly. This is
shown in the figure below. A good starting value for ep is 1e-4.
Interface
Ports
Description
p_high, p_low
Both terminals of port p (Translation).
Causality
fixed force out
Parameters
s
Interval of the play [m]
c1
Stiffness in the play [N/m]
c2
Stiffness outside the play [N/m]
20-sim 4.6 Reference Manual
852
9. Library
d1
Damping inside the play [Ns/m]
d2
Damping outside the play [Ns/m]
ep
Relative round off (1e-6 -> sharp edges, 1e-2 -> smoother)
Initial Values
x_initial
Initial position in the play [m], -s/2 < x_initial < s/2
Collision-Relative
Library
Iconic Diagrams\Mechanical\Translation\C omponents
Implementations
Right
Left
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description - Right
This model represents an collision of an object with another object. It can be used to
indicate a possible collision to the right of an object.
The collision force is modeled by a spring and damper:
p.F = if x > x0 then k*(x-x0) + d*limit(p.v,0,1e20) else 0 end;
with a stiffness k and damping d. The limit function is used to prevent the damper force
to become negative. The initial position of the spring is indicated by x0 (see the figure
above). Note that the positive direction is to the right. If x is larger that x0, the two sides
have collided and are in contact. The collision model has separate high and low ports.
The equations are
p.F = p_high.F = p_low.F
p.v = p_high.v - p_low.v
Interface - Right
Ports
Description
p_high
Two ports of the collision model.
20-sim 4.6 Reference Manual
853
9. Library
p_low
Causality
fixed force out
Variables
x
extension of the spring [m]
Parameters
x0
unstretched spring position
k
stiffness [N/m]
d
damping [N.s/m]
Initial Values
x_initial
The initial extension of the spring [m].
Description - Left
This model represents an collision of an object with another object. It can be used to
indicate a possible collision to the left of an object.
The collision force is modeled by a spring and damper. Note that the positive direction is
to the right, so the initial position of the spring x0 has a negative value in the figure
above. If x is smaller that x0, the two sides have collided and are in contact.
Interface - Left
Ports
Description
p_high
Two ports of the collision model.
p_low
Causality
fixed force out
Variables
x
extension of the spring [m]
Parameters
x0
unstretched spring position
20-sim 4.6 Reference Manual
854
9. Library
k
stiffness [N/m]
d
damping [N.s/m]
Initial Values
x_initial
The initial extension of the spring [m].
Collision
Library
Iconic Diagrams\Mechanical\Translation\C omponents
Implementations
Right
Left
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description - Right
This model represents an collision of an object with the ground.
The collision force is modeled by a spring and damper:
p.F = if x > x0 then k*(x-x0) + d*limit(p.v,0,1e20) else 0 end;
with a stiffness k and damping d. The limit function is used to prevent the damper force
to become negative. The initial position of the spring is indicated by x0 (see the figure
above). Note that the positive direction is to the right. If x is larger that x0, the two sides
have collided and are in contact. The collision model has separate high and low ports.
The equations are
p.F = p_high.F = p_low.F
p.v = p_high.v - p_low.v
Interface - Right
Ports
Description
p_high
Two ports of the collision model.
p_low
20-sim 4.6 Reference Manual
855
9. Library
Causality
fixed force out
Variables
x
extension of the spring [m]
Parameters
x0
unstretched spring position
k
stiffness [N/m]
d
damping [N.s/m]
Initial Values
x_initial
The initial extension of the spring [m].
Description - Left
This model represents an collision of an object with the ground.
The collision force is modeled by a spring and damper. Note that the positive direction is
to the right, so the initial position of the spring x0 has a negative value in the figure
above. If x is smaller that x0, the two sides have collided and are in contact.
Interface - Left
Ports
Description
p_high
Two ports of the collision model.
p_low
Causality
fixed force out
Variables
x
extension of the spring [m]
Parameters
x0
unstretched spring position
k
stiffness [N/m]
d
damping [N.s/m]
20-sim 4.6 Reference Manual
856
9. Library
Initial Values
x_initial
The initial extension of the spring [m].
Damper
Library
Iconic Diagrams\Mechanical\Translation\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description
This model represents a linear damper. It can have an force out as well as an velocity
out causality. In the last case the constitutive equation, as shown below, is simply
inverted. The port p of the damper model has separate high and low terminals. The
equations are:
p.F = p_high.F = p_low.F
p.v = p_high.v - p_low.v
Force out causality:
p.F = d * p.v;
Velocity velocity out causality:
p.v = p.F / d;
Interface
Ports
Description
p_high, p_low
Both terminals of the Translation port p.
Causality
indifferent
Parameters
d
damping [Ns/m]
20-sim 4.6 Reference Manual
857
9. Library
FixedWorld
Library
Iconic Diagrams\Mechanical\Translation\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description
This model represents the fixed world (velocity = 0). The model has only one initial port
p defined. Because any number of connections can be made, successive ports are
named p1, p2, p3 etc. which gives the constitutive equations:
p1.v = p2.v = .. = pn.v = 0;
p1.F = free; p2.F = free; ..; pn.F = free;
Interface
Ports
Description
p [any]
Any number of connections can be made (Translation).
Causality
Fixed
angular All ports have a fixed velocity out causality.
velocity out
Friction
Library
Iconic Diagrams\Mechanical\Translation\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Implementations
C
V
CV
SC VS
LuGre
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Introduction
These models represents friction with the fixed world. The amount of friction depends on
the normal force that is applied and the friction function that is used. The normal force is
given by the input signal Fn.
20-sim 4.6 Reference Manual
858
9. Library
The models have only one initial port p defined. Because any number of connections can
be made, successive ports are named p1, p2, p3 etc. 20-sim will automatically create
equations such that the resulting force p.F is equal to the sum of the forces of all
connected ports p1 .. pn. The velocities of all connected ports are equal to p.v.
p.F = sum(p1.F, p2.F, ....)
p.v = p1.v = p2.v = ....
Due to the use of normal force, the friction models all have a fixed force out causality.
The constitutive equations are therefore described as:
p.F = Fn * f(p.v);
with f the friction function.
Description - C
This model represents friction with the fixed world described as coulomb friction:
p.F = Fn*mu_c*tanh(slope*p.v);
Fn: normal force (given by the input signal Fn)
mu_c: the coulomb friction coefficient
slope: the steepness of the coulomb friction curve.
Interface - C
Ports
Description
p[any]
Any number of connections can be made (Translation).
Causality
Fixed force out
Input
20-sim 4.6 Reference Manual
859
9. Library
Fn
Normal force [N]
Parameters
mu_c
C oulomb friction coefficient []
slope
Steepness of C oulomb friction curve [s/m]
Description - V
This model represents friction with the fixed world described as viscous friction:
p.F = Fn*mu_v*p.v;
Fn: normal force (given by the input signal Fn)
mu_v: the viscous friction coefficient
Interface - V
Ports
Description
p[any]
Any number of connections can be made (Translation).
Causality
Fixed force out
Input
Fn
Normal force [N]
Parameters
mu_v
Viscous friction coefficient [s/m]
Description - CV
This model represents friction with the fixed world described as coulomb plus viscous
friction:
20-sim 4.6 Reference Manual
860
9. Library
p.F = Fn*(mu_c*tanh(slope*p.v) + mu_v*p.v);
Fn: normal force (given by the input signal Fn)
mu_v: the viscous friction coefficient
mu_c: the coulomb friction coefficient
slope: the steepness of the coulomb friction curve.
Interface - CV
Ports
Description
p[any]
Any number of connections can be made (Translation)
Causality
Fixed force out
Input
Fn
Normal force [N]
Parameters
mu_v
Viscous friction coefficient [s/m]
mu_c
C oulomb friction coefficient []
slope
Steepness of C oulomb friction curve [s/m]
Description - SCVS
This model represents friction with the fixed world described as static plus coulomb plus
viscous plus Stribeck friction:
p.F = Fn *
(( mu_c + (mu_st*abs(tanh( slope*p.v )) - mu_c)
* exp( -((p.v / v_st)^2 )) ) * sign(p.v)
+ mu_v * p.v);
Fn: normal force (given by the input signal Fn)
mu_s: the static friction coefficient
mu_v: the viscous friction coefficient
mu_c: the coulomb friction coefficient
20-sim 4.6 Reference Manual
861
9. Library
slope: the steepness of the coulomb and static friction curve.
v_st: the characteristic Stribeck velocity.
Interface - SCVS
Ports
Description
p[any]
Any number of connections can be made (Translation).
Causality
Fixed force out
Input
Fn
Normal force [N]
Parameters
mu_s
Static friction coefficient []
mu_v
Viscous friction coefficient [s/m]
mu_c
C oulomb friction coefficient []
slope
Steepness of C oulomb friction curve [s/m]
v_st
C haracteristic Stribeck velocity [m/s]
Description - LuGre
This model represents friction with the fixed world described by the LuGre friction model:
p.F = FN*f_lg(p.v);
Fn: normal force (given by the input signal Fn)
f_lg: the LuGre friction model
Interface - LuGre
Ports
Description
p[any]
Any number of connections can be made (Translation).
Causality
20-sim 4.6 Reference Manual
862
9. Library
Fixed force out
Input
Fn
Normal force [N]
Parameters
mu_c
C oulomb friction coefficient []
mu_s
Static friction coefficient []
mu_v
Viscous friction coefficient [s/m]
v_st
C haracteristic Stribeck velocity [m/s]
mu_k
Stiffness coefficient at zero speed []
Friction-Relative
Library
Iconic Diagrams\Mechanical\Translation\C omponents
Implementations
C
V
CV
SC VS
LuGre
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Introduction
These models represents friction relative to other objects. The amount of friction
depends on the normal force that is applied and the friction function that is used. The
normal force is given by the input signal Fn.
The port p of the friction models have separate high and low terminals. The equations
are:
p.F = p_high.F = p_low.F
p.v = p_high.v - p_low.v
Due to the use of normal force, the friction models all have a fixed torque out causality.
The constitutive equations are therefore described as:
p.F = Fn * f(p.v);
with f the friction function.
Description -C
This model represents friction between two terminals described as coulomb friction:
20-sim 4.6 Reference Manual
863
9. Library
p.F = Fn*mu_c*tanh(slope*p.v);
Fn: normal force (given by the input signal Fn)
mu_c: the coulomb friction coefficient
slope: the steepness of the coulomb friction curve.
Interface - C
Ports
Description
p_high, p_low
Both terminals of port p (Translation).
Causality
Fixed force out
Input
Fn
Normal force [N]
Parameters
mu_c
C oulomb friction coefficient []
slope
Steepness of C oulomb friction curve [s/m]
Description - V
This model represents friction between two terminals described as viscous friction:
p.F = Fn*mu_v*p.v;
Fn: normal force (given by the input signal Fn)
mu_v: the viscous friction coefficient
20-sim 4.6 Reference Manual
864
9. Library
Interface -V
Ports
Description
p_high, p_low
Both terminals of port p (Translation).
Causality
Fixed force out
Input
Fn
Normal force [N]
Parameters
mu_v
Viscous friction coefficient [s/m]
Description - CV
This model represents friction between two terminals described as coulomb plus viscous
friction:
p.F = Fn*(mu_c*tanh(slope*p.v) + mu_v*p.v);
Fn: normal force (given by the input signal Fn)
mu_v: the viscous friction coefficient
mu_c: the coulomb friction coefficient
slope: the steepness of the coulomb friction curve.
20-sim 4.6 Reference Manual
865
9. Library
Interface - CV
Ports
Description
p_high, p_low
Both terminals of port p (Translation).
Causality
Fixed force out
Input
Fn
Normal force [N]
Parameters
mu_v
Viscous friction coefficient [s/m]
mu_c
C oulomb friction coefficient []
slope
Steepness of C oulomb friction curve [s/m]
Description - SCVS
This model represents friction between two terminals described as static plus coulomb
plus viscous plus Stribeck friction:
p.F = Fn *
(( mu_c + (mu_st*abs(tanh( slope*p.v )) - mu_c)
* exp( -((p.v / v_st)^2 )) ) * sign(p.v)
+ mu_v * p.v);
Fn: normal force (given by the input signal Fn)
mu_s: the static friction coefficient
mu_v: the viscous friction coefficient
mu_c: the coulomb friction coefficient
slope: the steepness of the coulomb and static friction curve.
v_st: the characteristic Stribeck velocity.
20-sim 4.6 Reference Manual
866
9. Library
Interface - SCVS
Ports
Description
p_high, p_low
Both terminals of port p (Translation).
Causality
Fixed force out
Input
Fn
Normal force [N]
Parameters
mu_s
Static friction coefficient []
mu_v
Viscous friction coefficient [s/m]
mu_c
C oulomb friction coefficient []
slope
Steepness of C oulomb friction curve [s/m]
v_st
C haracteristic Stribeck velocity [m/s]
Description - LuGre
This model represents friction between two terminals described by the LuGre friction
model:
p.F = FN*f_lg(p.v);
Fn: normal force (given by the input signal Fn)
f_lg: the LuGre friction model
Interface - LuGre
Ports
Description
p_high, p_low
Both terminals of port p (Translation).
Causality
20-sim 4.6 Reference Manual
867
9. Library
Fixed force out
Input
Fn
Normal force [N]
Parameters
mu_c
C oulomb friction coefficient []
mu_s
Static friction coefficient []
mu_v
Viscous friction coefficient [s/m]
v_st
C haracteristic Stribeck velocity [m/s]
mu_k
Stiffness coefficient at zero speed []
FrictionSimple
Library
Iconic Diagrams\Mechanical\Translation\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Implementations
C
V
CV
SC VS
LuGre
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Introduction
These models represents friction with the fixed world. The amount of friction does not
depend on the normal force but determined by parameters directly. The models have
only one initial port p defined. Because any number of connections can be made,
successive ports are named p1, p2, p3 etc. 20-sim will automatically create equations
such that the resulting force p.F is equal to the sum of the forces of all connected ports
p1 .. pn. The velocities of all connected ports are equal to p.v.
p.F = sum(p1.F, p2.F, ....)
p.v = p1.v = p2.v = ....
Description - C
This model represents friction with the fixed world described as coulomb friction:
p.F = Fc*tanh(slope*p.v);
Fc: the coulomb friction
slope: the steepness of the coulomb and static friction curve.
20-sim 4.6 Reference Manual
868
9. Library
Interface - C
Ports
Description
p[any]
Any number of connections can be made (Translation).
Causality
Fixed force out
Parameters
Fc
C oulomb friction [N]
slope
Steepness of C oulomb friction curve [s/m]
Description - V
This model represents friction with the fixed world described as viscous friction:
p.F = d*p.v;
d: the viscous friction or damping
20-sim 4.6 Reference Manual
869
9. Library
Interface - V
Ports
Description
p[any]
Any number of connections can be made (Translation).
Causality
Fixed force out
Parameters
d
Viscous friction or damping [N.s/m]
Description - CV
This model represents friction with the fixed world described as coulomb plus viscous
friction:
p.F = Fc*tanh( slope*p.v ) + d*p.v;
d: the viscous friction or damping
Fc: the coulomb friction
slope: the steepness of the coulomb and static friction curve.
Interface - CV
Ports
Description
p[any]
Any number of connections can be made (Translation)
Causality
Fixed force out
Parameters
Fc
C oulomb friction [N]
d
Viscous friction or damping [N.s/m]
slope
Steepness of C oulomb friction curve [s/m]
20-sim 4.6 Reference Manual
870
9. Library
Description - SCVS
This model represents friction with the fixed world described as static plus coulomb plus
viscous plus Stribeck friction:
p.F = (( Fc + (Fst*abs(tanh( slope*p.v )) - Fc) * exp( -((p.v / v_st)^2 )) ) *
sign(p.v) + d * p.v);
Fst: the static friction
d: the viscous friction or damping
Fc: the coulomb friction
slope: the steepness of the coulomb and static friction curve.
v_st: the characteristic Stribeck velocity.
Interface - SCVS
Ports
Description
p[any]
Any number of connections can be made (Translation).
Causality
Fixed force out
Parameters
Fc
C oulomb friction [N]
Fst
Static friction [N]
d
Viscous friction or damping [N.s/m]
v_st
C haracteristic Stribeck velocity [m/s]
slope
Steepness of C oulomb friction curve [s/m]
Description - LuGre
This model represents friction with the fixed world described by the LuGre friction model:
p.F = f_lg(p.v);
f_lg: the LuGre friction model
20-sim 4.6 Reference Manual
871
9. Library
Interface - LuGre
Ports
Description
p[any]
Any number of connections can be made (Translation).
Causality
Fixed force out
Parameters
Fc
C oulomb friction [N]
Fst
Static friction [N]
d
Viscous friction or damping [N.s/m]
v_st
C haracteristic Stribeck velocity [m/s]
k
Stiffness at zero speed [N/m]
FrictionSimple-Relative
Library
Iconic Diagrams\Mechanical\Translation\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Implementations
C
V
CV
SC VS
LuGre
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Introduction
These models represents friction with the fixed world. The amount of friction does not
depend on the normal force but determined by parameters directly. The models have
only one initial port p defined. The port p of the friction models have separate high and
low terminals. The equations are:
p.F = p_high.F = p_low.F
p.v = p_high.v - p_low.v
Description - C
This model represents friction with the fixed world described as coulomb friction:
p.F = Fc*tanh(slope*p.v);
Fc: the coulomb friction
slope: the steepness of the coulomb and static friction curve.
20-sim 4.6 Reference Manual
872
9. Library
Interface - C
Ports
Description
p[any]
Any number of connections can be made (Translation).
Causality
Fixed force out
Parameters
Fc
C oulomb friction [N]
slope
Steepness of C oulomb friction curve [s/m]
Description - V
This model represents friction with the fixed world described as viscous friction:
p.F = d*p.v;
d: the viscous friction or damping
20-sim 4.6 Reference Manual
873
9. Library
Interface - V
Ports
Description
p[any]
Any number of connections can be made (Translation).
Causality
Fixed force out
Parameters
d
Viscous friction or damping [N.s/m]
Description - CV
This model represents friction with the fixed world described as coulomb plus viscous
friction:
p.F = Fc*tanh( slope*p.v ) + d*p.v;
d: the viscous friction or damping
Fc: the coulomb friction
slope: the steepness of the coulomb and static friction curve.
Interface - CV
Ports
Description
p[any]
Any number of connections can be made (Translation)
Causality
Fixed force out
Parameters
Fc
C oulomb friction [N]
d
Viscous friction or damping [N.s/m]
slope
Steepness of C oulomb friction curve [s/m]
20-sim 4.6 Reference Manual
874
9. Library
Description - SCVS
This model represents friction with the fixed world described as static plus coulomb plus
viscous plus Stribeck friction:
p.F = (( Fc + (Fst*abs(tanh( slope*p.v )) - Fc) * exp( -((p.v / v_st)^2 )) ) *
sign(p.v) + d * p.v);
Fst: the static friction
d: the viscous friction or damping
Fc: the coulomb friction
slope: the steepness of the coulomb and static friction curve.
v_st: the characteristic Stribeck velocity.
Interface - SCVS
Ports
Description
p[any]
Any number of connections can be made (Translation).
Causality
Fixed force out
Parameters
Fc
C oulomb friction [N]
Fst
Static friction [N]
d
Viscous friction or damping [N.s/m]
v_st
C haracteristic Stribeck velocity [m/s]
slope
Steepness of C oulomb friction curve [s/m]
Description - LuGre
This model represents friction with the fixed world described by the LuGre friction model:
p.F = f_lg(p.v);
f_lg: the LuGre friction model
20-sim 4.6 Reference Manual
875
9. Library
Interface - LuGre
Ports
Description
p[any]
Any number of connections can be made (Translation).
Causality
Fixed force out
Parameters
Fc
C oulomb friction [N]
Fst
Static friction [N]
d
Viscous friction or damping [N.s/m]
v_st
C haracteristic Stribeck velocity [m/s]
k
Stiffness at zero speed [N/m]
Mass
Library
Iconic Diagrams\Mechanical\Translation\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description-Default
This model represents an ideal mass (no gravity). The element has a preferred velocity
out causality. The corresponding constitutive equations then contain an integration. The
element can also have the non-preferred force out causality. The constitutive equations
then contain a derivation. Because any number of connections can be made, successive
ports are named p1, p2, p3 etc. 20-sim will automatically create equations such that the
resulting force p.F is equal to the sum of the forces of all connected ports p1 .. pn. The
velocities of all connected ports are equal to p.v.
p.F = sum(p1.F, p2.F, ....)
p.v = p1.v = p2.v = ....
velocity out causality (preferred):
a = p.F/m;
p.v = int(a);
x = int(p.omega);
force out causality:
20-sim 4.6 Reference Manual
876
9. Library
a = ddt(p.v);
p.T = m*a;
x = int(p.v);
Description-Gravity
This model represents an ideal mass with gravity. It is equal to the default model with a
gravitational acceleration g added:
a = p.F/m - g;
p.v = int(a);
x = int(p.omega);
The gravitational acceleration g acts in the negative direction. E.g. a free fall will give the
model a negative acceleration, negative velocity and negative position.
Interface
Ports
Description
p[any]
Any
number
of
connections
can
be
made
(Translation).
Causality
preferred velocity out
An torque out causality results in a derivative
constitutive equation.
Variables
x
position [m]
a
acceleration [m/s^2]
p
impulse [Ns]
Parameters
m
mass [kg]
g
acceleration of gravity [m/s^2]
Initial Values
p.v_initial
The initial velocity of the mass.
x_initial
The initial position of the mass.
20-sim 4.6 Reference Manual
877
9. Library
Modal
Library
Iconic Diagrams\Mechanical\Translation\C omponents
Implementations
Stiffness
Frequency
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description - Stiffness
This model represents a spring-damper-mass system that can be used for modal
analysis. The springdamper is equivalent tot the SpringDamper-Stiffness.emx model.
The mass is equivalent to the Mass.emx model. The model has one output that can be
connected to the modal-summer.emx model.
Interface - Stiffness
Ports
Description
p
Translation port.
Causality
preferred velocity out
Parameters
k
Stiffness [N/m]
b
Relative damping []
m
Equivalent mass [kg]
Description - Frequency
This model represents a spring-damper-mass system that can be used for modal
analysis. The springdamper is equivalent tot the SpringDamper-Frequency model. The
mass is equivalent to the Mass model. The model has one output that can be connected
to the Modal-Summer model.
Interface - Frequency
Ports
Description
p
Translation port.
Causality
preferred velocity out
Parameters
b
Relative damping []
f
Resonance frequency [Hz]
20-sim 4.6 Reference Manual
878
9. Library
m
Equivalent mass [kg]
ModalSummer
Library
Iconic Diagrams\Mechanical\Translation\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description
This model combines the results from all modal.emx models to one resulting output. The
model has 8 input ports and one output port that shows the combined result. If more or
less input ports are needed, you have to adapt the model (C hoose Go Down and alter
the internal description).
Interface
Ports
Description
p1 .. p8
Input ports for modal.emx models (Translation).
p_out
Port with the modal result (Translation)
Causality
preferred force out p1..p8
preferred velocity out p_out
Parameters
A1 .. A8
Gains for each input port.
Node
Library
Iconic Diagrams\Mechanical\Translation\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description
This node model represents a structural connection between two or more parts, where
the velocity of all connected parts is equal. The model has only one initial port p defined.
Because any number of connections can be made, successive ports are named p1, p2,
p3 etc.
20-sim 4.6 Reference Manual
879
9. Library
Interface
Ports
Description
p [any]
Any number of connections can be made (Translation).
ShockAbsorber
Library
Iconic Diagrams\Mechanical\Translation\C omponents
Implementations
Right
Left
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Introduction
This model represents a shock absorber with an open end. This type of shock absorbers
is used to protect equipment from large impacts when reaching the end of a line.
The damper has an internal piston which can travel a certain length (i.e. the stroke l)
until it collides with the end cap. The shock absorber is modeled by a damper for the
active damping part and a spring damper to model the impact with the end cap. The
position of the damper is indicated by the parameter x0. Two implementations are
available: one with the impact at the right and one with the impact at the left.
The damper is modeled by viscous damping, where the damping force is proportional
with the velocity:
p.F = d * v;
After a stroke of length l, the end caps are reached which a are modeled by a spring
damper:
p.F = k * x;
20-sim 4.6 Reference Manual
880
9. Library
To get the damper back in its original position a return force is added.
Description - Right
The ShockAbsorber-Right models a shock absorber with impact at the right of the
system.
Shock absorber model with impact at the right.
Description - Right
The ShockAbsorber-Left models a shock absorber with impact at the left of the system.
Shock absorber model with impact at the left.
Interface
Ports
Description
p_high
Two ports of the shock absorber model.
p_low
Causality
fixed force out
Parameters
k
stiffness at the end cap [N/m]
d
damping [N.s/m]
l
shock absorber stroke [m]
x0
position of the damper [m]
20-sim 4.6 Reference Manual
881
9. Library
Fr
return force [N]
SkyHookDamper
Library
Iconic Diagrams\Mechanical\Translation\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description
This model represents a skyhook damper. It can have an force out as well as an velocity
out causality. In the last case the constitutive equation, as shown below, is simply
inverted. The model has a fixed force out causality. The equations are:
Force out causality:
p_high.F = d * p_high.v;
p_low.F = p_high.F
As the equations point out, the force of the skyhook damper only depends on the
velocity at the port p_high. The position of p_high is indicated by an arrow, as shown in
the figure below.
In this figure two models are shown. In the top model, the damping force of the skyhook
damper is zero because the velocity at p_high is zero. C onsequently the mass is free to
move.
In the lower model, the damping force is proportional to the velocity of the mass. Here
the skyhook damper acts as a normal damper.
Interface
Ports
Description
p_high, p_low
Both Translation ports of the skyhook damper.
20-sim 4.6 Reference Manual
882
9. Library
Causality
fixed force out
Parameters
d
damping [Ns/m]
Spring
Library
Iconic Diagrams\Mechanical\Translation\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description
This model represents an ideal translational spring. The element has a preferred force
out causality. The corresponding constitutive equations then contain an integration. The
element can also have the non-preferred velocity out causality. The constitutive
equations then contain a derivation. The spring model has separate high and low ports.
The equations are
p.F = p_high.F = p_low.F
p.v = p_high.v - p_low.v
Force out causality (preferred):
x = int(p.v);
p.F = k * x;
Velocity out causality:
p.v = ddt(x);
x = p.F/k;
Interface
Ports
Description
p_high
Two ports of the spring (Translation).
p_low
Causality
preferred force out
An velocity out causality results in a derivative
constitutive equation.
Variables
x
extension of the spring [m]
Parameters
20-sim 4.6 Reference Manual
883
9. Library
k
Stiffness [N/m]
Initial Values
x_initial
The initial extension of the spring [m].
SpringDamper
Library
Iconic Diagrams\Mechanical\Translation\C omponents
Implementations
Default
Stiffness
Frequency
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description - Default
This model represents an ideal translational spring with damper. The element has a
preferred force out causality. The corresponding constitutive equations then contain an
integration. The element can also have the non-preferred velocity out causality. The
constitutive equations then contain a derivation. The spring-damper model has separate
high and low ports. The equations are
p.F = p_high.F = p_low.F
p.v = p_high.v - p_low.v
Force out causality (preferred):
x = int(p.v);
p.F = k*x + d*p.v;
Velocity out causality:
p.v = ddt(x);
x = (p.F - d*p.v)/k;
Interface - Default
Ports
Description
p_high
Two ports of the spring (Translation).
p_low
Causality
preferred force out
20-sim 4.6 Reference Manual
884
9. Library
Variables
x
extension of the spring [m]
Parameters
k
Stiffness [N/m]
d
damping [N.s/m]
Initial Values
x_initial
The initial extension of the spring [m].
Description - Stiffness
This model represents another implementation of the ideal translational spring with
damper. The damping value (d) is calculated on the basis of a known stiffness (k),
relative damping (b) and mass reference (m). The mass is only used to compute the
damping (no actual mass is used in this component).
The element has a preferred force out causality. The corresponding constitutive
equations then contain an integration. The element can also have the non-preferred
velocity out causality. The constitutive equations then contain a derivation. The springdamper model has separate high and low ports. The equations are
p.F = p_high.F = p_low.F
p.v = p_high.v - p_low.v
Force out causality (preferred):
x = int(p.v);
p.F = k * x + d*p.v;
d = 2*b*sqrt(k*m);
Velocity out causality:
p.v = ddt(x);
x = (p.F - d*p.v)/k;
d = 2*b*sqrt(k*m);
Interface - Stiffness
Ports
Description
p_high
Two ports of the spring (Translation).
p_low
Causality
preferred force out
Variables
x
extension of the spring [m]
d
damping [N.s/m]
20-sim 4.6 Reference Manual
885
9. Library
Parameters
k
Stiffness [N/m]
b
Relative damping []
m
Reference mass [kg]
Initial Values
x_initial
The initial extension of the spring [m].
Description - Frequency
This model represents another implementation of the ideal translational spring with
damper. The stiffness (k) is calculated on basis of a known resonance frequency. The
damping value (d) is calculated on the basis of the calculated stiffness (k), relative
damping (b) and mass reference (m). The mass is only used to compute the damping
(no actual mass is used in this component).
The element has a preferred force out causality. The corresponding constitutive
equations then contain an integration. The element can also have the non-preferred
velocity out causality. The constitutive equations then contain a derivation. The springdamper model has separate high and low ports. The equations are
p.F = p_high.F = p_low.F
p.v = p_high.v - p_low.v
Force out causality (preferred):
x = int(p.v);
p.F = k * x + d*p.v;
k = m*(2*pi*F)^2;
d = 2*b*sqrt(k*m);
Velocity out causality:
p.v = ddt(x);
x = (p.F - d*p.v)/k;
k = m*(2*pi*f)^2;
d = 2*b*sqrt(k*m);
Interface - Frequency
Ports
Description
p_high
Two ports of the spring (Translation).
p_low
Causality
preferred force out
Variables
x
extension of the spring [m]
20-sim 4.6 Reference Manual
886
9. Library
k
stiffness [N/m]
d
damping [N.s/m]
Parameters
b
Relative damping []
f
Resonance frequency [Hz]
m
Reference mass [kg]
Initial Values
x_initial
The initial extension of the spring [m].
ZeroForce
Library
Iconic Diagrams\Mechanical\Translation\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description
This model can be used to connect any open end of another model that is not connected
to the fixed world. It generates a fixed force of 0 N while the velocity is free:
p.v = indifferent;
p.F = 0;
Interface
Ports
Description
p
Translation port
Causality
Fixed force out
Sensors
AccelerationSensor-Absolute
Library
Iconic Diagrams\Mechanical\Translation\Sensors
Use
Domains:
Diagrams.
C ontinuous. Size:
1-D.
Kind:
Iconic
Diagrams
20-sim 4.6 Reference Manual
(Translation),
Block
887
9. Library
Description
This model describes an acceleration sensor which derives an acceleration output out of
a port velocity by differentiation. Differentiation is performed by a state variable filter:
The S-domain function of this filter is equal to:
where f is the cut-off frequency. For very high values of f, the output becomes the pure
derivative of the input. High values of f, however, increase simulations times. A good
trade-off is a starting value of 1e5.
The equations of this model are:
a = d( p.v)/dt;
p.F = indifferent;
Interface
Ports
Description
p
Translation port p.
Causality
fixed force out
Output
alpha
Acceleration [m/s2]
Parameters
f
C ut-off frequency of the differentiation [Hz].
a_initial
Initial acceleration [m/s].
20-sim 4.6 Reference Manual
888
9. Library
AccelerationSensor-Relative
Library
Iconic Diagrams\Mechanical\Translation\Sensors
Use
Domains:
Diagrams.
C ontinuous. Size:
1-D.
Kind:
Iconic
Diagrams
(Translation),
Block
Description
This model describes an acceleration sensor which derives an acceleration output out of
a velocity difference (between high and low terminals) by differentiation. Differentiation
is performed by a state variable filter:
The S-domain function of this filter is equal to:
where f is the cut-off frequency. For very high values of f, the output becomes the pure
derivative of the input. High values of f, however, increase simulations times. A good
trade-off is a starting value of 1e5.
The equations of this model are:
a = d( p_high.v - p_low.v)/dt;
p_low.F = p_high.F = indifferent;
Interface
Ports
Description
p_high, p_low
Both terminals of the Translational port p.
Causality
fixed force out
Output
a
Acceleration (measured as the difference between both terminals)
[m/s2]
20-sim 4.6 Reference Manual
889
9. Library
Parameters
f
C ut-off frequency of the differentiation [Hz].
a_initial
Initial acceleration [m/s].
ForceSensor
Library
Iconic Diagrams\Mechanical\Translation\Sensors
Use
Domains:
Diagrams.
C ontinuous. Size:
1-D.
Kind:
Iconic
Diagrams
(Translation),
Block
Description
This model translates an applied force to an output signal. It has a velocity out causality.
The port p of the model has separate high and low terminals. The equations are:
p.F = p_high.F = p_low.F;
p.v = p_high.v - p_low.v;
F = p.F;
p.v = 0;
Interface
Ports
Description
p_high, p_low
Both terminals of the Translation port p.
Causality
fixed velocity out
Output
F
Applied force [N].
PositionSensor-Absolute
Library
Iconic Diagrams\Mechanical\Translation\Sensors
Use
Domains:
Diagrams.
C ontinuous. Size:
1-D.
Kind:
Iconic
Diagrams
20-sim 4.6 Reference Manual
(Translation),
Block
890
9. Library
Description
This model translates a position to an output signal. It has a force out causality. The
equations are:
p.F = 0;
x = int(p.v);
Interface
Ports
Description
p_high, p_low
Translation port p.
Causality
fixed force out
Output
x
Absolute position [m].
Initial Values
x_initial
Initial position [m]
PositionSensor-Relative
Library
Iconic Diagrams\Mechanical\Translation\Sensors
Use
Domains:
Diagrams.
C ontinuous. Size:
1-D.
Kind:
Iconic
Diagrams
(Translation),
Block
Description
This model translates a position difference to an output signal. It has a force out
causality. The port p of the model has separate high and low terminals. The equations
are:
p.F = p_high.F = p_low.F;
p.v = p_high.v - p_low.v;
p.F = 0;
x = int(p.v);
Interface
Ports
Description
p_high, p_low
Both terminals of the Translation port p.
Causality
fixed force out
20-sim 4.6 Reference Manual
891
9. Library
Output
x
Relative position [m].
Initial Values
x_initial
Initial position [m].
PowerSensor
Library
Iconic Diagrams\Mechanical\Translation\Sensors
Use
Domains:
Diagrams.
C ontinuous. Size:
1-D.
Kind:
Iconic
Diagrams
(Translation),
Block
Description
This is an ideal sensor (no dissipation or other effects) that yields the power that flows
through the model as output signal. The equations are:
p_high.F = p_low.F
p_high.v = p_low.v
P = p_high.F * p_high.v;
Interface
Ports
Description
p_high, p_low
Both translation ports.
Causality
p_high not equal
p_low
Output
P
Power [w].
VelocitySensor-Absolute
Library
Iconic Diagrams\Mechanical\Translation\Sensors
Use
Domains:
Diagrams.
C ontinuous. Size:
1-D.
Kind:
Iconic
Diagrams
(Translation),
Block
Description
This model translates a velocity to an output signal. It has a force out causality. The
equations are:
20-sim 4.6 Reference Manual
892
9. Library
p.F = 0;
v = p.v;
Interface
Ports
Description
p
Translation port p.
Causality
fixed force out
Output
v
Absolute velocity [m/s].
VelocitySensor-Relative
Library
Iconic Diagrams\Mechanical\Translation\Sensors
Use
Domains:
Diagrams.
C ontinuous. Size:
1-D.
Kind:
Iconic
Diagrams
(Translation),
Block
Description
This model translates a velocity difference to an output signal. It has a force out
causality. The port p of the model has separate high and low terminals. The equations
are:
p.F = p_high.F = p_low.F;
p.v = p_high.v - p_low.v;
p.F = 0;
v = p.v;
Interface
Ports
Description
p_high, p_low
Both terminals of the Translation port p.
Causality
fixed force out
Output
v
Relative velocity [m/s].
20-sim 4.6 Reference Manual
893
9. Library
Transmission
BeltPulley
Library
Iconic Diagrams\Mechanical\Rotation\Gears
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation/Translation).
Description
This models represents a belt and pulley. The connection to the pulley is through the
rotation port p_rot. The connection to the belt is through the translation port p_trans.
The model is ideal, i.e. there are no compliances or inertias. The causality of this model
is always mixed: torque out & velocity out or angular velocity out & force out:
p_rot.T = radius * p_trans.F
p_trans.v = radius * p_rot.omega
or:
p_trans.F = 1/radius * p_rot.T
p_rot.omega = 1/radius * p_trans.v
Interface
Ports
Description
p_rot
Rotation port.
p_trans
Translation port.
Causality
p_rot
notequal
p_trans
Parameters
radius
pulley radius [m]
20-sim 4.6 Reference Manual
894
9. Library
Cam-Wizard
Library
Iconic Diagrams\Mechanical\Rotation\Gears
Iconic Diagrams\Mechanical\Translation\Transmission
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation/Translation).
Description
This is a masked model which opens the C am Wizard when edited. Depending on the
selections entered, various cam motion profiles can be generated.
Interface
Ports
Description
p_in
Driving axis (Rotation)
p_out
Output port with resulting motion (Rotation or Translation)
Parameters
stroke
amplitude of resulting motion
start_angle
start angle motion
stop_angle
angle when the maximum is reached
return_angle
start angle of the return motion
end_angle
finish angle of the return motion
CamRod
Library
Iconic Diagrams\Mechanical\Rotation\Gears
Iconic Diagrams\Mechanical\Translation\Transmission
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description
This models represents a cam and rod mechanism. If the input shaft is rotating with a
constant speed, the output motion is a pure sinusoidal.
20-sim 4.6 Reference Manual
895
9. Library
The mechanism is ideal, i.e., it does not have inertia, friction or geometrical limitations.
It has one rotation port (p_in) and one translation port (p_out). The causality of this
model is always mixed: one port has a force out causality while the other has a velocity
out causality:
p_in.T = i * p_out.F
p_out.v = i * p_in.omega
The transmission ratio (i) is the ratio of the velocities of both ports (in fact a sinusoidal
function of the shaft angle).
Interface
Ports
Description
p_in
Driving axis (Rotation)
p_out
Output port with resulting motion (Translation)
Causality
fixed torque
out
p_in
fixed velocity out
p_out
Parameters
stroke
Stroke of the translation port (is equal to half the length of the rod).
20-sim 4.6 Reference Manual
896
9. Library
CrankRod
Library
Iconic Diagrams\Mechanical\Rotation\Gears
Iconic Diagrams\Mechanical\Translation\Transmission
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description
This models represents a crank and rod mechanism. The mechanism is ideal, i.e., it
does not have inertia, friction or geometrical limitations. It has one rotation port (p_in)
and one translation port (p_out). The causality of this model is always mixed: one port
has a force out causality while the other has a velocity out causality:
p_in.T = i * p_out.F
p_out.v = i * p_in.omega
The transmission ratio (i) is the ratio of the velocities of both ports. It is a function of the
shaft angle, the crank length and the rod length.
Interface
Ports
Description
p_in
Driving axis (Rotation)
p_out
Output port with resulting motion (Translation)
Causality
fixed torque
out
p_in
fixed velocity out
p_out
Parameters
crank_length
C rank length [m]
rod_length
Rod length [m]
20-sim 4.6 Reference Manual
897
9. Library
Fork
Library
Iconic Diagrams\Mechanical\Translation\Transmission
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description
This model is equivalent to the differential model of the Rotation library. It represents a
special type of node where the forces are equal and the velocities are added:
p3.v = p1.v + p2.v;
p1.F = p2.F = p3.F;
This model can for example be used for actuators that generate a force difference. With
the fork model an equivalent model can be found with the actuator attached to the fixed
world:
Interface
Ports
Description
p1,p2,p3
Translation ports.
20-sim 4.6 Reference Manual
898
9. Library
Lever
Library
Iconic Diagrams\Mechanical\Translation\Transmission
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description
This models represents any type of lever with two counter-moving ports. The lever is
ideal, i.e., it does not have inertia, friction or geometrical limitations. The lever has one
fast moving port and one slow moving port. The lever ratio is the (absolute) ratio of the
velocities of both ports. The causality of this model is always mixed: one port has a
force out causality while the other has an velocity out causality:
p_fast.F = -i * p_slow.F
p_slow.v = -i * p_fast.v
or:
p_slow.F = -1/i * p_fast.F
p_fast.v = -1/i * p_slow.v
Interface
Ports
Description
p_fast
Fast moving translation port.
p_slow
Slow moving translation port.
Causality
p_slow
notequal
p_fast
Parameters
i
lever ratio p_slow.v / p_fast.v [], 0 < i < 1
Note
Keep the lever ratio i between 0 and 1. C onfusion might otherwise exist:
i > 1: the fast moving port is slower than the slow moving port (you better
interchange the connections of the lever model).
i < 0: the ports are not counter-moving (use the transmission model instead).
20-sim 4.6 Reference Manual
899
9. Library
RackPinionGear
Library
Iconic Diagrams\Mechanical\Rotation\Gears
Iconic Diagrams\Mechanical\Translation\Transmission
Implementations
FixedPinion
FixedRack
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation/Translation).
Description - FixedPionion
This models represents a rack and pinion gear. The connection to the pinion gear is
through the rotation port p_rot. The connection to the rack is through the translation
port p_trans. The model is ideal, i.e. there is no compliance nor inertia nor backlash.
In this model the pinion bearing is connected to the fixed world and the rack is free to
move. This in contrary to the model FixedRackPinionGear where the pinion bearing is
free to move and the rack is connected to the fixed world.
The causality of this model is always mixed: torque out & velocity out or angular velocity
out & force out:
p_rot.T = radius * p_trans.F
p_trans.v = radius * p_rot.omega
or:
p_trans.F = 1/radius * p_rot.T
p_rot.omega = 1/radius * p_trans.v
The rack position is determined by the internal variable x. For x = 0, the pinion gear is
at the middle of the rack. When the pinion crosses the end of the rack, i.e.
abs(x) > rack_length/2
20-sim 4.6 Reference Manual
900
9. Library
a warning is given, "WARNING: rack length has been exceeded at the rack and pinion
gear!", and the simulation is stopped.
Interface - FixedPionion
Ports
Description
p_rot
Rotation port.
p_trans
Translation port.
Causality
p_rot
notequal
p_trans
Parameters
radius
pinion gear pitch radius [m]
rack_length
rack length [m]
Variables
x
Internal
variable
which
denotes
the
rack
position,
abs(x)
<
rack_length/2 else simulation halted.
Initial values
x_initial
Initial rack position, abs(x_initial) < rack_length/2
Description - FixedRack
This models represents a fixed rack and pinion gear. The connection to the pinion gear is
through the rotation port p_rot. The connection to the rack is through the translation
port p_trans. The model is ideal, i.e. there is no compliance nor inertia nor backlash.
In this model the pinion bearing is free to move and the rack is connected to the fixed
world. This in contrary to the model RackPinionGear where the pinion bearing is
connected to the fixed world and the rack is free to move.
The causality of this model is always mixed: torque out & velocity out or angular velocity
out & force out:
20-sim 4.6 Reference Manual
901
9. Library
p_rot.T = radius * p_trans.F
p_trans.v = radius * p_rot.omega
or:
p_trans.F = 1/radius * p_rot.T
p_rot.omega = 1/radius * p_trans.v
The rack position is determined by the internal variable x. For x = 0 the pinion gear is at
the middle of the rack. When the pinion crosses the end of the rack, i.e.
abs(x) > rack_length/2
a warning is given, "WARNING: rack length has been exceeded at the rack and pinion
gear!", and the simulation is stopped.
Interface - FixedRack
Ports
Description
p_rot
Rotation port.
p_trans
Translation port.
Causality
p_rot
notequal
p_trans
Parameters
radius
pinion gear pitch radius [m]
rack_length
rack length [m]
Variables
x
Internal
variable
which
denotes
the
rack
position,
abs(x)
<
rack_length/2 else simulation halted.
Initial values
x_initial
Initial rack position, abs(x_initial) < rack_length/2
20-sim 4.6 Reference Manual
902
9. Library
Spindle
Library
Iconic Diagrams\Mechanical\Rotation\Gears
Iconic Diagrams\Mechanical\Translation\Transmission
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation).
Introduction
This models represents a spindle and nut. It transfers an angular motion of the spindle
into a translational motion of the nut. The model is ideal, i.e., it does not have inertia or
friction. The causality of this model is always mixed: one port has a torque out causality
while the other has an angular velocity out causality:
p_spindle.T = i * p_nut.F
p_nut.v = i * p_spindle.omega
or:
p_nut.F = 1/i * p_spindle.T
p_spindle.omega = 1/i * p_nut.v
The model has two implementations which calculate the transform ratio i out of different
parameters.
Description - Pitch
In this implementation the transform ratio is calculated using the pitch (the advance of
the nut during one revolution of the spindle):
i = pitch / (2 * pi);
Interface - Pitch
Ports
Description
p_spindle
Port at the spindle shaft (Rotation).
p_nut
Port at the wheel (Translation).
Causality
p_spindle
notequal p_nut
Parameters
pitch
translation of the nut during one revolution of the spindle [m]
Description - LeadAngle
This implementation calculates the transform ratio out of the lead angle alpha and the
radius r_spindle of the spindle:
i = tan(alpha)*r_spindle;
20-sim 4.6 Reference Manual
903
9. Library
The pitch angle is shown in the figure below. r_spindle is the effective radius of the
spindle, i.e. the radius from the center of the spindle to the pitch point p.
Interface -LeadAngle
Ports
Description
p_spindle
Port at the spindle shaft (Rotation).
p_nut
Port at the wheel (Translation).
Causality
p_spindle
notequal p_nut
Parameters
r_spindle
alpha
effective radius of the spindle [m]
lead angle of the spindle [rad]
TimingBelt
Library
Iconic Diagrams\Mechanical\Rotation\Gears
Iconic Diagrams\Mechanical\Translation\Transmission
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Rotation/Translation).
Introduction
This models represents a timing belt, used for linear positioning.
20-sim 4.6 Reference Manual
904
9. Library
It has a rotating pulley which drives the the belt and clamp. The timing belt is modeled
by a series of spring damper elements that convey the rotation of the pulley to a clamp
translation. Because the output position is moving, stiffness and damping values are not
constant.
The stiffness for a piece of belt can be expressed as:
k = E*A / l
with
E = Modulus of elasticity {N/m2}
A = Belt area {m2}
l = belt length {m}
If the belt is sufficiently pre-tensioned, the stiffness experienced at the clamp can be
expressed as the combination of three individual belt parts:
k = E*A/(0.5*l+x) + 1/( 1 / E*A/(0.5*l - x) + 1 / E*A / l )
which can be rewritten to:
k = E*A*( 1/(0.5*l+x) + 1/(1.5*l - x) )
The stiffness approaches infinity as the clamp moves to the driven pulley (x = -l/2) and
has a minimum value when the clamp moves to the other pulley (x = 0.5*l). The
minimum stiffness is equal to:
k = 2*E*A / l
The belt position is determined by the internal variable x. For x = 0 the clamp is in the
middle. When the position crosses the driven pulley, i.e.
20-sim 4.6 Reference Manual
905
9. Library
x < - belt_length/2
the simulation is stopped: "Error: clamp position larger than belt end!". When the
position crosses the other pulley, i.e.
x > belt_length/2
the simulation is also stopped, "Error: clamp position smaller than belt start!".
Description - Default
In this model the minimum stiffness is used, based on an output position at a length L of
the driven pulley.
k = 2*E*A / l
Description - VariableStiffness
In this model a variable stiffness is used equal to:
k = E*A*( 1/(0.5*l+x) + 1/(1.5*l - x) )
Take care not to let the clamp get too close to the driven pulley, because the stiffness
will then grow to infinity!
Interface
Ports
Description
p_rot
Rotation port.
p_trans
Translation port.
Causality
p_rot
notequal
p_trans
Parameters
radius
pinion gear pitch radius [m]
d
damping N.s/m]
E
Modulus of elasticity [N/m2]
A
A = Belt area [m2]
l
belt length [m]
Variables
x
clamp position, abs(x) < belt length/2
Initial values
x_initial
Initial clamp position, abs(x_initial) < belt length/2
20-sim 4.6 Reference Manual
906
9. Library
Transmission
Library
Iconic Diagrams\Mechanical\Translation\Transmission
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description
This models represents any type of lever with ports moving in the same direction. The
lever is ideal, i.e., it does not have inertia, friction or geometrical limitations. The lever
has one fast moving port and one slow moving port. The transmission ratio is the ratio of
the velocities of both ports. The causality of this model is always mixed: one port has a
force out causality while the other has an velocity out causality:
p_fast.F = i * p_slow.F
p_slow.v = i * p_fast.v
or:
p_slow.F = 1/i * p_fast.F
p_fast.v = 1/i * p_slow.v
Interface
Ports
Description
p_fast
Fast moving rotation port.
p_slow
Slow moving rotation port.
Causality
p_slow
notequal
p_fast
Parameters
i
transmission ratio p_slow.v / p_fast.v [], 0 < i < 1
Note
Keep the transmission ratio i between 0 and 1. C onfusion might otherwise exist:
i > 1: the fast moving port is slower than the slow moving port (you better
interchange the connections of the transmission model).
i < 0: the ports are counter-moving (use the lever model instead).
20-sim 4.6 Reference Manual
907
9. Library
UniversalLever
Library
Iconic Diagrams\Mechanical\Translation\Transmission
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Translation).
Description
This model represents an ideal transmission with a free pivot point. The relations are:
p3.v = (i/(1+i))*p1.v + (1/(1+i))*p2.v;
p2.F = (1/(1+i)*p3.F;
p1.F = (i/(1+i)*p3.F;
Ground
Although each of the three ports may be connected to the ground, it is more efficient to
use other models. When p1 or p2 is connected to the ground, this model is equal to the
Transmission.emx model. When p3 is connected to the ground, this model is equal to
the Lever.emx model.
Transmission-Universal
Transmission
Lever
Interface
Ports
Description
p1,p2,p3
Translation ports.
20-sim 4.6 Reference Manual
908
9. Library
Parameters
i
Transmission ratio []
9.2.5
Thermal
Thermal
The Thermal library contains components which are very useful for modeling thermal
systems. The following libraries are available.
C omponents
Generators
Sensors
Note
For domains that have port variables that do no multiply to power the name
pseudo is used. This model has pseudothermal ports. The port variables of a
pseudothermal port are the heat flow, p.dQ [W], and the temperature, p.T
[K], which do not multiply to power.
The base unit of temperature is degrees Kelvin. You can select degrees C elsius in
the Parameters Editor or Variables C hooser desired. 20-sim will take care that
internally always SI units (Kelvin) are used for calculations.
Components
Convection
Library
Iconic Diagrams\Mechanical\Thermal\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Pseudothermal).
Description
This model describes linear heat convection between a material surface and gas or fluid
flow. The basic equation is:
p.dQ = (p1.T - p2.T)*Gc;
where p1.T is the temperature of at the surface and p2.T the gas or fluid temperature.
Gr is the thermal conductance which is function of the surface area A and the convection
coefficient h:
Gr = A*h;
20-sim 4.6 Reference Manual
909
9. Library
In most cases h is not contant but a non-analytical function of the gas or fluid speed and
other poperties. In most cases Gr is experimentally defined. Therefore G is given as an
input signal.
Interface
Ports
Description
p1
Material port
p2
Fluid port
Causality
indifferent
Input
G
thermal conductance [W/K]
Ground
Library
Iconic Diagrams\Mechanical\Thermal\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Pseudothermal).
Description
This is a general model for the heat storage that is so large that is can be considered
constant (e.g. the environment). It is comparable to the ground in the electrical domain.
T0 = 25 {degC};
p.T = T0;
Interface
Ports
Description
p[any]
Any number of
(pseudothermal).
connections
can
be
made
Causality
fixed temperature out
An torque out causality results in a derivative
constitutive equation.
Parameters
T0
temperature [K]
20-sim 4.6 Reference Manual
910
9. Library
HeatCapacity
Library
Iconic Diagrams\Mechanical\Thermal\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Pseudothermal).
Description
This is a general model for the heat storage in a specific material. A constant
temperature distribution in the material is assumed and a constant heat capacity:
E = int(p.dQ) + C*T0;
p.T = E/C;
T0 is the initial temperature of the material, E the internal energy {J} and C the thermal
capacity {J/K}. Because any number of connections can be made, successive ports are
named p1, p2, p3 etc. 20-sim will automatically create equations such that the resulting
heat flow p.dQ is equal to the sum of the heatflows of all connected ports p1 .. pn. The
temperatures of all connected ports are equal to element temperature p.T.
p.dQ = sum(p1.dQ, p2.dQ, ....)
p.T = p1.T = p2.T = ....
The thermal capacity can be calculated with the specific heat capacity cp and material
mass m:
C = cp*m;
Typical values for cp are:
water
4186
granite
790
glass
840
aluminium
900
concrete
840?
copper
387
silver
235
iron / steel
452
wood
1674
air (50 °C )
1046
Interface
Ports
Description
20-sim 4.6 Reference Manual
911
9. Library
p[any]
Any
number
of
connections
can
be
made
(pseudothermal).
Causality
preferred temperature out
An torque out causality results in a derivative
constitutive equation.
Variables
E
internal energy [J]
Parameters
C
thermal capacity [J/K]
T0
initial temperature [K]
Radiation
Library
Iconic Diagrams\Mechanical\Thermal\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Pseudothermal).
Description
This model describes the heat transfer between to bodies through radiation:
p.dQ =Gr*sigma*(p1.T^4 - p2.T^4);
where p1.T and p2.T are the temperatures of the body surfaces and sigma is the StefanBoltzmann constant. For simple cases, Gr may be analytically computed. The analytical
equations use epsilon, the surface emissitivy of a body which is in the range 0..1.
Epsilon=1, if the body absorbs all radiation (= black body). Epsilon=0, if the body
reflects all radiation and does not absorb any.
Typical values for epsilon are:
aluminium, polished
0.04
copper, polished
0.04
gold, polished
0.02
paper
0.09
rubber
0.95
wood
0.85..0.9
20-sim 4.6 Reference Manual
912
9. Library
Analytical Equations for Gr
Small convex object in large enclosure (e.g., a hot machine in a room):
Gr = e*A;
where
e: Emission value of object (0..1)
A: Surface area of object where radiation heat transfer takes place
Two parallel plates:
Gr = A/(1/e1 + 1/e2 - 1);
where
e1: Emission value of plate1 (0..1)
e2: Emission value of plate2 (0..1)
A : Area of plate1 (= area of plate2)
Interface
Ports
Description
p1
Material port
p2
Fluid port
Causality
indifferent
Input
G
thermal conductance [W/K]
ThermalConductance
Library
Iconic Diagrams\Mechanical\Thermal\C omponents
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Pseudothermal).
Description
When a temperature difference exists in a material, heat will flow from the high
temperature part to the low temperature part. This model describes the transport of heat
through a block of material with a temperature difference on both sides of the block. The
heat conducting capacity of the material is indicated by the parameter G (thermal
conductance):
p.dQ = p.T*G;
This model is the dual form of the thermal resistor where the insulation capacity of the
block is indicated by the parameter R (thermal resistance):
20-sim 4.6 Reference Manual
913
9. Library
p.dQ = p.T/R;
The heat flow through the material is ideal. I.e. there is no heat storage modeled. The
thermal resistance model has separate high and low ports. The equations are
p.dQ = p_high.dQ = p_low.dQ
p.T = p_high.T - p_low.T
Block
The thermal conductance of a block can be calculated with the specific thermal
conductivity k, the length L of the block, and the area A of both sides of the block:
G = k*A/L
Typical values of the thermal conductivity [W.m-1.K-1] are:
water
0.6
granite
2,1
glass
1.0
aluminium
210
concrete
1.28
copper
390
silver
430
iron / steel
40-70
wood
0.13
air
0.026
Interface
Ports
Description
p_high, p_low
Both terminals of the pseudothermal port p
Causality
indifferent
Parameters
G
thermal conductance [W/K]
ThermalResistor
Library
Iconic Diagrams\Mechanical\Thermal\C omponents
20-sim 4.6 Reference Manual
914
9. Library
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Pseudothermal).
Description
When a temperature difference exists in a material, heat will flow from the high
temperature part to the low temperature part. This model describes the transport of heat
through a block of material with a temperature difference on both sides of the block. The
insulation capacity of the block is indicated by the parameter R (thermal resistance):
p.dQ = p.T/R;
This model is the dual form of the thermal conductor where the heat conducting capacity
of the material is indicated by the parameter G (thermal conductance):
p.dQ = p.T*G;
The heat flow through the material is ideal. I.e. there is no heat storage modeled. The
thermal resistance model has separate high and low ports. The equations are
p.dQ = p_high.dQ = p_low.dQ
p.T = p_high.T - p_low.T
Block
The thermal resistance of a block can be calculated with the specific thermal
conductivity k, the length L of the block, and the area A of both sides of the block:
R = L/(k*A)
Typical values of the thermal conductivity [W.m-1.K-1] are:
water
0.6
granite
2,1
glass
1.0
aluminium
210
concrete
1.28
copper
390
silver
430
iron / steel
40-70
wood
0.13
air
0.026
Interface
Ports
Description
p_high, p_low
Both terminals of the pseudothermal port p
Causality
20-sim 4.6 Reference Manual
915
9. Library
indifferent
Parameters
R
thermal resistance [K/W]
Generators
HeatFlow
Library
Iconic Diagrams\Mechanical\Thermal\Generators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Pseudothermal).
Description
This model yields a heat flow that is set to a constant value. The temperature is
indifferent. The model can represent any heat generating object with a constant heat
flow.
Interface
Ports
Description
p
Causality
fixed heat flow out
Parameters
dQ
Heat flow [J/s]
ModulatedHeatFlow
Library
Iconic Diagrams\Mechanical\Thermal\Generators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Pseudothermal).
Description
This model yields a heat flow that is equal to a (fluctuating) value given by the input
signal dQ. The temperature is indifferent. The model can represent any heat generating
object with a fluctuating heat flow.
Interface
Ports
Description
20-sim 4.6 Reference Manual
916
9. Library
p
Causality
fixed heat flow out
Parameters
dQ
Heat flow [J/s]
ModulatedTemperatureSource
Library
Iconic Diagrams\Mechanical\Thermal\Generators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Pseudothermal).
Description
This model has a temperature that is equal to a (fluctuating) value given by the input
signal T. The heat flow is indifferent. This model can represent an object that has a heat
capacity which is so much larger than the rest of the system, that its temperature can be
seen as an independant variable.
Interface
Ports
Description
p
Causality
fixed temperature out
Input
T
Variable temperature signal [K]
Resistor
Library
Iconic Diagrams\Thermal\Generators\Generators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Pseudothermal, Electric).
Description
This is a model of a resistor with a temperature coefficient. The resistance and voltage
equation can be written as:
R = R_ref*(1 + alpha*(p_th.T - T_ref));
p_el.u = p_el.i * R;
20-sim 4.6 Reference Manual
917
9. Library
where R_ref is the reference resistance at reference temperature T_ref and alpha the
temperature coefficient of resistance. The actual temperature of the resistor is given by
the pseudothermal port of the model , p_el.T. The heat generated by the resistor is
equal to
p_th.dQ = p_el.u * p_el.i;
The electrical port p of the resistor model has separate high and low terminals. The
equations are:
p_el.i = p_high_el.i = p_low_el.i;
p_el.u = p_el_high.u - p_el_low.u;
Interface
Ports
Description
p_el_high
Both terminals of the Electric port.
p_el_low
p_th
The pseudothermal port
Causality
indifferent p_el
fixed
heat
flow
out p_th
Parameters
R_ref
Reference resistance [Ohm].
T_ref
Reference temperature [K].
alpha
Temperature coefficient of the resistance []
TemperatureSource
Library
Iconic Diagrams\Mechanical\Thermal\Generators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Pseudothermal).
Description
This model has a temperature that is set to a certain constant value. The heat flow is
indifferent. The model can represent a piece of material which is so large that its
temperature variation is neglectable (e.g. the environment) and thus can be seen as an
ideal temperature source
20-sim 4.6 Reference Manual
918
9. Library
Interface
Ports
Description
p
Causality
fixed temperature out
Parameters
T
Fixed temperature [K]
Thermistor
Library
Iconic Diagrams\Thermal\Generators
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Pseudothermal, Electric).
Description
This is a model of a linear thermistor. Thermistors are thermally sensitive resistors and
have, according to type, a negative (NTC ), or positive (PTC ) resistance/temperature
coefficient. For linear thermistors the resistance and voltage equation can be written as:
R = R_ref*(1 + alpha*(p_th.T - T_ref));
p_el.u = p_el.i * R;
where R_ref is the reference resistance at reference temperature T_ref and alpha the
temperature coefficient of resistance. The actual temperature of the themistor is given
by the pseudothermal port of the model , p_el.T. The heat generated by the thermistor
is equal to
p_th.dQ = p_el.u * p_el.i;
The electrical port p of the thermistor model has separate high and low terminals. The
equations are:
p_el.i = p_high_el.i = p_low_el.i;
p_el.u = p_el_high.u - p_el_low.u;
Interface
Ports
Description
p_el_high
Both terminals of the Electric port.
p_el_low
p_th
The pseudothermal port
Causality
20-sim 4.6 Reference Manual
919
9. Library
indifferent p_el
fixed
heat
flow
out p_th
Parameters
R_ref
Reference resistance [Ohm].
T_ref
Reference temperature [K].
alpha
Temperature coefficient of the resistance []
Sensors
HeatFlowSensor
Library
Iconic Diagrams\Mechanical\Thermal
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Pseudothermal).
Description
This is a model of an ideal heat flow sensor with an output signal dQ that is equal to the
measured heat flow. The sensor is ideal which means that is does not store, loses or
adds heat.
Interface
Ports
Description
p_high, p_low
Both ports of the sensor
Causality
p_high not equal p_low
Parameters
dQ
Measured heat flow [J/s]
TemperatureSensor
Library
Iconic Diagrams\Mechanical\Thermal
20-sim 4.6 Reference Manual
920
9. Library
Use
Domains: C ontinuous. Size: 1-D. Kind: Iconic Diagrams (Pseudothermal).
Description
This is a model of an ideal temperature sensor with an output signal T that is equal to
the measured temperature. The heat flow into the model is zero to assure zero power
loss.
Interface
Ports
Description
p
Causality
fixed heat flow out
Parameters
T
9.3
Measured temperature [K]
Signal
9.3.1
Block Diagram
Attenuate
Library
Signal\Block Diagram
Use
Domains: C ontinuous, Discrete. Size: 1-D. Allowed in: Block Diagrams.
Description
This model divides an input signal by a constant value.
output = input/K
Interface
Inputs
input
Outputs
output
Parameters
K
Description
Division parameter
20-sim 4.6 Reference Manual
921
9. Library
Delay-Pade
Library
Signal\Block Diagram
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams.
Description
This model delays the input signal by "T" seconds using a 4th order Pade approximation.
The model is linear which means that it can be used in models that should be linearized.
Interface
Inputs
input
Outputs
output
Parameters
T
Description
Delay time.
Delay-Step
Library
Signal\Block Diagram
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams.
Description
This model delays its input signal one simulation step.
output = initial; (time = 0)
output = inp(time - hk); (time > 0)
where hk = simulation step size.
Note
To correctly use models with constant delays, simulation runs must be performed using
integration algorithms with a constant time-step. Otherwise the model Delay-Time.emx
should be used!
Interface
Inputs
input
Outputs
Description
20-sim 4.6 Reference Manual
922
9. Library
output
Parameters
initial
The initial output value.
Note
To correctly use models with constant delays, simulation runs must be performed
using integration algorithms with a constant time-step. Otherwise the model DelayTime.emx should be used!
The delay-step.emx submodel is non-linear: i.e. models which include the delaystep.emx submodel cannot be linearized. Use the linear time delay Delay-Pade.emx
if you want to perform linearization.
Delay-Time
Library
Signal\Block Diagram
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams.
Description
This model stores the input signal and corresponding time in a buffer. After "delay"
seconds the stored values are retrieved. When the simulation time step does not
coincide with the delay time "delay", the output is calculated by first order interpolation.
output = initial; (time < delay)
output = inp(time - delay); (time >= delay)
Interface
Inputs
input
Outputs
output
Parameters
initial
delay
Description
The initial output value.
Delay time.
Delay-VariableTime
Library
Signal\Block Diagram
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams.
20-sim 4.6 Reference Manual
923
9. Library
Description
This model stores the input signal and corresponding time in a buffer. After "delay"
seconds the stored values are retrieved. This delay is a variable input signal. When the
simulation time step does not coincide with the delay time "delay", the output is
calculated by first order interpolation.
output = initial; (time < delay)
output = input(time - delay); (time >= delay)
output = input(time); (delay < 0)
Interface
Inputs
input
Outputs
output
Parameters
initial
delay
Description
The initial output value.
Delay time.
Note
The maximum storage capacity of the buffer is 58254 input values. When many input
values are stored the simulation speed may slow down considerably!
The delay-variabletime.emx submodel is non-linear: i.e. models which include the
delay-variabletime.emx submodel cannot be linearized. Use the linear time delay
Delay-Pade.emx if you want to perform linearization.
Demux
Library
Signal\Block Diagram
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams.
Description
You can use the Mux model to combine multiple input signals into one multi-dimensional
signal.
This model can be used to spit the multi-dimensional signal again into single signals.
20-sim 4.6 Reference Manual
924
9. Library
Interface
Inputs
inputs
Outputs
output[any]
Description
Default 2 signals can be connected. Use the right
mouse menu and choose Edit Implementation to
change the number of signals.
The output signal size is equal to the number of
inputs.
Differentiate-Calculus
Library
Signal\Block Diagram
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams.
Description
This model approximates the differentiation of an input signal by the equation:
where hk = simulation step size. The initial value of the output is equal to the parameter
"initial". When the simulation step size is zero (time event, state event) the output value
will be equal to the previous output value (the simulation step size part is not calculated
to prevent a division by zero).
Interface
Inputs
input
Outputs
output
Parameters
initial
Description
The initial value of the output.
20-sim 4.6 Reference Manual
925
9. Library
Differentiate-FO
Library
Signal\Block Diagram
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams.
Description
This model is a first order approximation of a differentiation. The transfer function is:
As shown in the figure below, the model behaves as a differentiator for frequencies
below fl.
Interface
Inputs
input
Outputs
output
Parameters
kd
fl
Initial Values
output_initial
Description
Differentiation gain []
Differentiation limit [Hz]
The initial value of the integral.
20-sim 4.6 Reference Manual
926
9. Library
Differentiate-SVF
Library
Signal\Block Diagram
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams.
Description
This model approximates the differentiation of an input with a state variable filter:
As can be seen, no differentiation is used in this model and consequently all integration
algorithms can be used. In the S-domain the output of this model is equal to:
For very high values of N, the output becomes the pure derivative of the input. High
values of N, however, increase simulations times. A good trade-off is a starting value of
10. If more accuracy is needed, this value can be increased.
Interface
Inputs
input
Outputs
output
Parameters
N
initial
Description
Derivative Gain Limitation.
The initial value of the output.
20-sim 4.6 Reference Manual
927
9. Library
Differentiate
Library
Signal\Block Diagram
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams.
Description
This model differentiates an input signal. The initial value of the output is equal to the
parameter "initial".
output = ddt(input,initial);
Interface
Inputs
input
Outputs
output
Parameters
initial
Description
The initial value of the output.
Filter
Library
Signal\Block Diagram
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams.
Description
When you select this model and click Go Down a special editor opens (Filter Editor),
allowing you to choose a filter:
20-sim 4.6 Reference Manual
928
9. Library
Interface
Inputs
input
Outputs
output
Initial Values
Description
The model has internal states that are not
accessible.
Parameters
Parameters are entered by the Filter Editor.
Gain
Library
Signal\Block Diagram
Use
Domains: C ontinuous, Discrete. Size: 1-D. Allowed in: Block Diagrams.
Description
This model multiplies an input signal with a constant value.
output = K * input
Interface
Inputs
Description
20-sim 4.6 Reference Manual
929
9. Library
input
Outputs
output
Parameters
K
Gain
Integrate-ExpWindow
Library
Signal\Block Diagram
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams.
Description
This model integrates an input signal over an exponential window with time constant T0
[s].
The model behaves as a signal averager, with an effective window of T0 [s].
Interface
Inputs
input
Outputs
output
Initial Values
state(0)
Parameters
T0
Description
The initial value of the integral.
Window constant [s].
20-sim 4.6 Reference Manual
930
9. Library
Integrate-FO
Library
Signal\Block Diagram
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams.
Description
This model is a first order approximation of an integration. The transfer function is:
As shown in the figure below, the model behaves as an integrator for frequencies above
the fl
Interface
Inputs
input
Outputs
output
Parameters
ki
fl
output_initial
Description
Integration gain []
Integration limit [Hz]
Initial value.
20-sim 4.6 Reference Manual
931
9. Library
Integrate-FOLimited
Library
Signal\Block Diagram
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams.
Description
This model is a first order approximation of an integration with an output value limited to
a minimum and maximum value. The model checks the output value to see if the
maximum of minimum values have been crossed. If so the input value is set to zero to
prevent the integral from winding-up. Between the bounds the transfer function is:
As shown in the figure below, the model behaves as an integrator for frequencies above
the fl
Interface
Inputs
input
Description
20-sim 4.6 Reference Manual
932
9. Library
Outputs
output
Parameters
ki
fl
output_initial
maximum
minimum
Integration gain []
Integration limit [Hz]
Initial value.
Maximum output value
Minimum output value
Integrate-Limited
Library
Signal\Block Diagram
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams.
Description
This model integrates an input signal. The output of this integral is limited between a
maximum and minimum bound. If the integral is in saturated condition and the input
changes sign, the output wanders away from the bounds immediately.
output = int(inp) + state(0); (minimum <= output <= maximum)
Interface
Inputs
input
Outputs
output
Initial Values
state(0)
Parameters
minimum
maximum
Description
The initial value of the integral.
Minimum output value.
Maximum output value.
20-sim 4.6 Reference Manual
933
9. Library
Integrate-RectWindow
Library
Signal\Block Diagram
Use
Domains: Continuous. Size: 1-D. Kind: Block Diagrams.
Description
This model integrates an input signal over a limited time interval which is T0 [s] wide.
The model behaves as a signal averager, with a rectangular window of T0 [s].
Interface
Inputs
input
Outputs
output
Initial Values
state(0)
Parameters
T0
Description
The initial value of the integral.
Integration interval.
Integrate-Reset
Library
Signal\Block Diagram
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams.
Description-Default
This model integrates an input signal. The output of this integral may be reset to any
desired value each time the reset signal is unequal to zero.
output = int(inp) + state(0); (reset = 0)
output = reset to newoutput; (reset <> 0)
20-sim 4.6 Reference Manual
934
9. Library
This implementation uses a normal integrator. That is why the model will also work when
c-code is generated.
Interface-Default
Inputs
input
reset
newoutput
Outputs
output
Initial Values
state(0)
Description
Input signal
When reset <> 0, the output changes to newoutput.
New output.
The initial value of the integral.
Description-Pure
This model integrates an input signal. The output of this integral may be reset to any
desired value each time the reset signal is unequal to zero.
output = int(inp) + state(0); (reset = 0)
output = reset to newoutput; (reset <> 0)
This implementation uses the function resint. This function forces the integration method
with a state event to search for the exact time where the integral is reset. The result is
more accurate than the Default implementation, but this implementation will not work
when c-code is generated.
Interface-Pure
Inputs
input
reset
newoutput
Outputs
output
Initial Values
state(0)
Description
Input signal
When reset <> 0, the output changes to newoutput.
New output.
The initial value of the integral.
Integrate
Library
Signal\Block Diagram
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams.
Description
This model integrates an input signal:
20-sim 4.6 Reference Manual
935
9. Library
output = int(input) + state(0)
Interface
Inputs
input
Outputs
output
Initial Values
state(0)
Description
The initial value of the integral.
Inverse
Library
Signal\Block Diagram
Use
Domains: C ontinuous, Discrete. Size: 1-D. Allowed in: Block Diagrams.
Description
This model yields the inverse of the input signal.
output = 1 / input
Interface
Inputs
input
Outputs
output
Description
Linear System
Library
Signal\Block Diagram
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams.
Description
When you select this model and click Go Down a special editor opens (Linear System
Editor), allowing you to enter a linear system in State Space form, as a Transfer
Function or by adding poles and zeros:
20-sim 4.6 Reference Manual
936
9. Library
Interface
Inputs
input
Outputs
output
Initial Values
Description
The model has internal states that are not
accessible.
Parameters
Parameters are entered by the Linear System
Editor.
20-sim 4.6 Reference Manual
937
9. Library
MultiplyDivide
Library
Signal\Block Diagram , System
Use
Domains: C ontinuous, Discrete. Size: [n,m]. Kind: Block Diagrams.
Description
This model yields a multiplication and/or division of one or more input signals. While
connecting input signals, 20-sim will ask whether the signals should be multiplied or
divided. The signals may have either size, but the size of all connected signals should be
equal.
For example the MultiplyDivide model can have 2 signals connected that are multiplied
and 2 signals that must be divided. 20-sim treats them as an array multiply and an array
divide with:
multiply = [multiply1;multiply2];
and
divide = [divide1;divide2];
The output will then be equal to:
output = (multiply1 * multiply2) / (divide1 * divide2);
Interface
Inputs
multiply[any]
divide[any]
Description
Any number of input signals (each of the same
size) may be connected to be multiplied (multiply)
or divided (divide).
Outputs
output
Limitations
The signals connected to this model should all have the same size.
20-sim 4.6 Reference Manual
938
9. Library
Mux
Library
Signal\Block Diagram
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams.
Description
You can use this model to combine multiple input signals into one multi-dimensional
signal.
The Demux model can be used to spit the multi-dimensional signal again into single
signals.
Interface
Inputs
inputs
Outputs
output[any]
Description
Default 2 signals can be connected. Use the right
mouse menu and choose Edit Implementation to
change the number of signals.
The output signal size is equal to the number of
inputs.
Negate
Library
Signal\Block Diagram
Use
Domains: C ontinuous, Discrete. Size: 1-D. Allowed in: Block Diagrams.
Description
This model yields the negative of the input signal.
20-sim 4.6 Reference Manual
939
9. Library
output = -input
Interface
Inputs
input
Outputs
output
Description
PlusMinus
Library
Signal\Block Diagram , System
Use
Domains: C ontinuous, Discrete. Size: [n,m]. Kind: Block Diagrams.
Description
This model yields a subtraction and/or summation of one or more input signals. While
connecting input signals, 20-sim will ask whether the signals should be added or
subtracted. The signals may have either size, but the size of all connected signals should
be equal.
For example the PlusMinus model can have 2 signals connected that are added and 2
signals that must be subtracted. 20-sim treats them as an array plus and an array minus
with:
plus = [plus1;plus2];
and
minus = [minus1;minus2];
The output will then be equal to:
20-sim 4.6 Reference Manual
940
9. Library
output = plus1 + plus2 - minus1 - minus2;
Interface
Inputs
plus[any]
minus[any]
Description
Any number of input signals (each of the same size)
may be connected to be added (plus) or subtracted
(minus).
Outputs
output
Limitations
The signals connected to this model should all have the same size.
SignalMonitor
Library
Signal\Block Diagram , Signal\Sources
Use
Domains: C ontinuous, Discrete. Size: 1-D. Allowed in: Block Diagrams.
Description
This model shows the value of its input in the Simulator. When you open the Simulator
(select Properties and Plot) the input of this model is automatically selected as
plotvariable. As label for this variable the local name of the SignalMonitor model is
chosen. It is therefore advised to give each SignalMonitor model a useful name (select
the model, click the right mouse button and select Attributes from the right mouse
menu).
Interface
Inputs
Description
input
The value of the input is shown in the Simulator
using the local name of the model as label.
Splitter
Library
Signal\Block Diagram , System
Use
Domains: C ontinuous, Discrete. Size: [n,m]. Kind: Block Diagrams.
Description
This model can split one output signal into two or more output signals. The signals may
have either size, but the size of all connected signals should be equal.
20-sim 4.6 Reference Manual
941
9. Library
Interface
Inputs
input
Outputs
output[any]
Description
One input signal must be connected
Any number of input signals (each of the same
size) may be connected.
Limitations
The signals connected to this model should all have the same size.
9.3.2
Block Diagram Non-Linear
DeadZone
Library
Signal\Block Diagram Non-Linear
Use
Domains: Discrete, C ontinuous. Size: 1-D. Allowed in: Block Diagrams.
Description
This model generates zero output when the input is within a specified region, called the
dead zone. Otherwise the output equals the input plus or minus half the zone.
20-sim 4.6 Reference Manual
942
9. Library
output = input + zone/2; (input < -zone/2)
output = 0; (-zone/2 <= input <= zone/2)
output = input - zone/2; (input > zone/2)
Interface
Inputs
Description
input
Outputs
output
Parameters
zone
Magnitude of the dead zone.
Limitations
Only single signals (i.e. signals of size 1) can be connected to this model.
Function-2DTable
Library
Signal\Block Diagram Non-Linear
Use
Domains: C ontinuous. Size: 1-D. Kind: Block Diagrams.
Description
This model uses a two-dimensional table with data points to calculate the output z =
f(x,y) as a function of the input x and y. The output z is calculated using linear
interpolation between the table data points.
20-sim 4.6 Reference Manual
943
9. Library
The first row denotes the x-values and the first column denotes the y-values.
The input data of the first column and first row needs to be monotonically increasing.
Discontinuities are allowed, by providing the same input point twice in first row or
first column of the table.
Values outside of the table range, are computed by linear extrapolation of the last
two points.
A table must be stored as an ASC II (text) file and should consist rows and columns of
data. The first row consists of the x-values first column consist of the y-values. The rowcolumn pairs are the corresponding z-values. Values must be separated by a space or a
tab. No comment or other text may be part of the table-file. The filename of the input
file can be specified using the complete path (e.g. c:\data\data.tbl ). When no path is
given, the file is assumed to be in the experiment directory.
Example
Suppose we want to use the well known Matlab peaks function:
This function can be put in a matrix form as:
20-sim 4.6 Reference Manual
944
9. Library
The first row and column denote the x-values and y-values and the other row-column
pairs the corresponding peaks function values. This matrix can be entered in a text file:
The model 2DTableLookup.emx (Examples\Signal Processing) shows how to use this text
file as a 2-D table.
Interface
Inputs
input1
input2
Outputs
output
Parameters
filename
Description
x-value
y-value
z-value
The filename of the table file.
20-sim 4.6 Reference Manual
945
9. Library
Function-Absolute
Library
Signal\Block Diagram Non-Linear
Use
Domains: Discrete, C ontinuous. Size: 1-D. Allowed in: Block Diagrams.
Description
This model yields the absolute value of an input signal.
outp = abs(inp);
Interface
Inputs
Description
input
Outputs
output
Function-Cosine
Library
Signal\Block Diagram Non-Linear
Use
Domains: Discrete, C ontinuous. Size: 1-D. Allowed in: Block Diagrams.
Description
This model yields the cosine of an input signal.
output = cos(input);
Interface
Inputs
Description
input
Outputs
output
20-sim 4.6 Reference Manual
946
9. Library
Function-DB
Library
Signal\Block Diagram Non-Linear
Use
Domains: Discrete, C ontinuous. Size: 1-D. Allowed in: Block Diagrams.
Description
This model returns an output signal in decibel (dB):
output = 20*log10(input);
Interface
Inputs
input
Outputs
output
Description
Function-Log
Library
Signal\Block Diagram Non-Linear
Use
Domains: Discrete, C ontinuous. Size: 1-D. Allowed in: Block Diagrams.
Description
This model returns the natural logarithm of the input.
output = log(input);
Interface
Inputs
input
Outputs
output
Description
20-sim 4.6 Reference Manual
947
9. Library
Function-Power
Library
Signal\Block Diagram Non-Linear
Use
Domains: Discrete, C ontinuous. Size: 1-D. Allowed in: Block Diagrams.
Description
This model raises the values of an input signal to the power p.
output = input^p;
Interface
Inputs
Description
input
Outputs
output
Parameters
p
Function-Sign
Library
Signal\Block Diagram Non-Linear
Use
Domains: Discrete, C ontinuous. Size: 1-D. Allowed in: Block Diagrams.
Description
This model returns the sign of the input. A zero input results in a zero output.
output = -1; (input < 0)
output = 0; (input = 0)
output = 1; (input > 0)
Interface
Inputs
Description
input
Outputs
output
20-sim 4.6 Reference Manual
948
9. Library
Function-Sine
Library
Signal\Block Diagram Non-Linear
Use
Domains: Discrete, C ontinuous. Size: 1-D. Allowed in: Block Diagrams.
Description
This model yields the sine of an input signal.
output = sin(input);
Interface
Inputs
Description
input
Outputs
output
Function-Square
Library
Signal\Block Diagram Non-Linear
Use
Domains: Discrete, C ontinuous. Size: 1-D. Allowed in: Block Diagrams.
Description
This model returns the square of the input signal.
output = input^2;
Interface
Inputs
input
Outputs
output
Description
20-sim 4.6 Reference Manual
949
9. Library
Function-SquareRoot
Library
Signal\Block Diagram Non-Linear
Use
Domains: Discrete, C ontinuous. Size: 1-D. Allowed in: Block Diagrams.
Description
This model yields the square root of an input signal.
outp = sqrt(inp);
Interface
Inputs
Description
input
Outputs
output
Function-SquareRootSign
Library
Signal\Block Diagram Non-Linear
Use
Domains: Discrete, C ontinuous. Size: 1-D. Allowed in: Block Diagrams.
Description
This model yields the square root of an input signal with sign and multiplied by a
parameter p.
output = sign(input)*sqrt(inp)/p;
Interface
Inputs
Description
input
Outputs
output
Parameters
p
20-sim 4.6 Reference Manual
950
9. Library
Function-SquareSign
Library
Signal\Block Diagram Non-Linear
Use
Domains: Discrete, C ontinuous. Size: 1-D. Allo