User Manual

User Manual
by
Copyright ESI ITI GmbH, 2016
Der Inhalt dieses Handbuches sowie die Rechte an der zugehrigen SimulationX-Software
sind Eigentum der ESI ITI GmbH Dresden und urheberrechtlich geschtzt. Die Vervielfl-
tigung, Verarbeitung auf elektronischen Systemen und Verbreitung des Handbuches oder
der Software beziehungsweise von Teilen davon bedrfen der Zustimmung der ESI ITI
GmbH.
Fr die Nutzung von ESI-ITI-Software gelten ausschlielich die Vertragsbedingungen der

ESI ITI GmbH fr die berlassung von Software (AGB Software). Beachten Sie die dort
genannten Hinweise zur beschrnkten Haftung. ESI ITI und SimulationX sind eingetragene
Marken der ESI ITI GmbH. Alle anderen im Handbuch genannten Marken und Produktna-
men sind Eigentum des jeweiligen Unternehmens.
The contents of this manual and the rights to the SimulationX software described therein
are the property of ESI ITI GmbH Dresden, Germany, and are protected by copyright. Any
reproduction, transmission, or electronic processing of the manual or the software or
parts thereof in any manner whatsoever is prohibited.
Use of ESI ITI software is governed exclusively by the terms of contract for software
licensing (GTC Software) of the ESI ITI GmbH. Attention is called to the stipulations
on limited liability contained therein. ESI ITI and SimulationX are a registered trademarks
of ESI ITI GmbH. Any other trademark and product names given in the manual are the
property of their respective owners.
ESI ITI GmbH

Schweriner Strae 1
01067 Dresden Germany
T + 49 (0) 351.260 50 - 0
F + 49 (0) 351.260 50 - 155
support.iti@esi-group.com
www.simulationx.com
Table of Contents
About the Manuals

The manuals are your companions when working with the simulation software
SimulationX. They were written for coworkers in research and development,
which with the simulation and analysis of technical systems are concerned.
Using the manuals and the context-sensitive online help you will quickly
understand the comprehensive software package. To facilitate your search for
information as efficiently as possible, the manuals are structured into these parts:
Part I: User Manual

First of all, you will be introduced to the concept of SimulationX. Secondly, all
necessary operations, tools and interfaces for creating models, running simulations
and evaluating results are explained in detail.
Finally, you will become familiar with the TypeDesigner an excellent and
powerful tool for creating your own element types. Based on the Modelica
language, you can describe completely new types by yourself, extend an existing
element type or create a Compound type by grouping an existing model structure
together.
Part II: Library Manual

Here you will find a complete description of all element types, which belong to the
model libraries of SimulationX. Model features, options, input parameters and
result variables are discussed in detail as well as the relevant calculation formulas.
Furthermore, the domain-specific connection and port types are explained also.
SimulationX 3 I
User Manual About the Manuals
Legend:
Option, not included in the Basic Module of

SimulationX
Warning
Hint or Tip
Example or Action
italic Instruction
Serif Variable, mathematical expression
II SimulationX 3
Table of Contents
Table of Contents
About the Manuals I
Table of Contents III
1 Introduction 1-1
1.1 Fields of Application 1-1
1.2 Solution Concept 1-1
1.3 Scope of Computation 1-2
1.4 Modelica 1-3
1.5 Software Development 1-3
2 Installation 2-1
2.1 Installation - Overview and Basics 2-1
2.1.1 Hard and Software Conditions for SimulationX 2-1
2.1.2 Requirements of Code Export and external Solver 2-1
2.2 SimulationX - Editions 2-3
2.2.1 All editions Overview 2-3
2.2.2 Evaluation version 2-3
2.2.3 The Student Edition 2-4
2.2.4 The Viewer Edition 2-4
2.2.5 The Analyzer Edition 2-4
2.2.6 The Professional Edition 2-4
2.2.7 Change edition 2-4
2.3 Installing SimulationX 2-5
2.3.1 Installation 2-6
2.3.2 Reinstall or Update 2-9
2.4 First start of the program 2-10
2.4.1 SimulationX - Evaluation-version 2-11
2.4.2 Student or Viewer Edition 2-14
2.4.3 Analyzer or Professional Edition 2-14
2.4.4 Migrate Settings from previous Versions 2-14
2.5 Hints for Administrators 2-15
2.5.1 Installation in the Batch Processing (without user Interaction) 2-15
2.5.2 Installations for Program Protection 2-16
2.5.2.1 Hardware Protection (Key / Dongle) 2-16
2.5.2.2 Software protection with license file 2-19
SimulationX 3 III
2.6 SimulationX the Licensing 2-20

2.6.1 Single Station License 2-21
2.6.2 Network License 2-21
2.6.3 Several different licenses in the network 2-22
2.7 Selection of a Hardware key / Dongle 2-23
2.7.1 Update a license 2-25
2.8 Selection a license file 2-26
2.9 Specialties for network licenses 2-29
2.9.1 Network licenses with Hard Key 2-29
2.9.2 Network License with License File 2-30
2.9.2.1 License renewal interval 2-30
2.9.2.2 Empty entries within the license file 2-31
2.10 Licensing modules 2-34
2.10.1 Module Selection Dialog 2-34
2.11 Managing license configurations 2-35
2.12 Working with Codemeter Licenses 2-36
2.12.1 Licenses with CmDongle (Cm USB Stick) 2-37
2.12.2 Licenses with License file (CmActLicense) 2-38
2.12.3 The CodeMeter Control Center 2-39
2.12.3.1 CodeMeter License Request and Update 2-40
2.12.4 Using of CodeMeter Licenses in SimulationX 2-42
2.13 Working with FlexLM licenses 2-43
2.14 License Configuration (for Administrators) 2-45
2.14.1.1 Configuration Sources 2-45
2.14.1.2 Write-protection 2-46
2.14.1.3 Configuration examples 2-47
2.14.1.4 Creating license configuration files 2-47
3 Getting Started 3-1

3.1 Working with Sample Models 3-1
3.1.1 Opening a Model File 3-2
3.1.2 Changing Parameters 3-2
3.1.3 Running a Simulation 3-3
3.1.4 Opening a Result Window 3-3
3.2 Creating your own Model 3-4
3.2.1 Selecting Elements 3-4
3.2.2 Connecting Elements 3-5
IV SimulationX 3
Table of Contents
3.2.3 Entering Parameters 3-6

3.2.4 Transient Simulation in the Time Domain 3-7
3.2.5 Displaying Results 3-8
3.2.6 Steady State Simulation in the Frequency Domain 3-10
3.2.6.1 Steady State Simulation of a Powertrain 3-10
3.3 ITI SimulationX for Complete System Modeling and Analysis 3-15
4 Graphical User Interface (GUI) 4-1

4.1 Overview 4-1
4.1.1 Tool Window 4-1
4.1.2 Document Window 4-2
4.2 Operating 4-2
4.2.1 Menu Bars and Toolbars 4-2
4.2.2 Library Bar 4-3
4.2.2.1 General Information about the Library Bar 4-6
4.2.3 Managing Different Versions of Packages and Types with
Apache Subversion 4-10
4.2.4 Diagram View, 3D View, Text View and Documentation
View 4-12
4.2.5 Model Explorer 4-14
4.2.5.1 How to Edit Component Properties 4-15
4.2.5.2 How to Add Parameters and Result Variables 4-16
4.2.5.3 How to Remove Parameters and Result Variables 4-16
4.2.6 Output Area 4-17
4.2.7 Result Window Manager 4-17
4.2.8 Search and Replace 4-17
5 Modeling Fundamentals 5-1

5.1 Modeling in SimulationX 5-1
5.1.1 Physical Object-Oriented Modeling 5-1
5.1.2 Signal-Oriented Modeling 5-2
5.1.3 Modeling with Equations and Algorithms 5-3
5.2 Creating Models 5-3
5.2.1 The SimulationX User Interface 5-3
5.2.2 Element Types and Libraries 5-6
5.2.2.1 SimulationX Libraries 5-6
5.2.2.2 Modelica Standard Libraries 5-7
5.2.2.3 User-Defined Element Types 5-9
SimulationX 3 V
5.2.3 Model Creation and Modification 5-9

5.2.3.1 Building a Model Structure 5-9
5.2.3.2 Editing of models 5-13
5.2.3.3 Labeling of Elements and Connections 5-15
5.3 Parameters and Results 5-16
5.3.1 Property Window 5-16
5.3.2 Parameters 5-21
5.3.2.1 Control for Parameters 5-21
5.3.2.2 Physical Measurement Units 5-24
5.3.2.3 Constants: 5-24
5.3.3 Initial Values 5-24
5.3.4 Result variables 5-25
5.3.5 Global Parameters 5-25
5.3.6 Special Tools for Parameter Input 5-26
5.3.6.1 Multidimensional Parameters 5-26
5.3.6.2 Files, Folders and Colors 5-30
5.3.7 Export and Import of Parameters 5-30
5.3.7.1 Export of Parameters 5-30
5.3.7.2 Import of Parameters 5-31
5.3.7.3 Editing Parameters in Excel 5-32
5.4 Special Topics 5-32
5.4.1 Describing Nonlinear Properties with Force Characteristics 5-32
5.4.1.1 Description using Formulas 5-32
5.4.1.2 Description using Characteristics 5-33
5.4.2 Variable Element Parameters 5-35
5.4.2.1 Parameter Input of the Elements Using Variable
Parameters - Parameters are Effective Quantities 5-35
5.4.2.2 Integration over Variable Parameters - Parameters are
Given as Derivatives 5-36
5.4.3 Working with Characteristic Curves and Maps 5-40
5.4.3.1 Characteristic Curve Dialog 5-41
5.4.3.2 Characteristic set 5-53
5.4.3.3 Family of characteristic curves 5-53
5.4.3.4 2D-Characteristic map 5-53
5.4.3.5 3D Characteristic map 5-58
5.4.4 3D View 5-60
5.4.4.1 Elements in the 3D-View 5-60
5.4.4.2 Camera Manipulation 5-61
VI SimulationX 3
Table of Contents
5.4.4.3 Settings 5-62

5.4.4.4 Working in the 3D-View 5-70
5.4.4.5 Performance 5-75
5.4.5 Special Model Components 5-76
5.4.5.1 How to Insert Special Model Components 5-76
5.4.6 Resolve External References 5-80
5.4.7 Compare Models 5-81
6 Analysis 6-1
6.1 Transient Simulation in the Time Domain 6-1
6.1.1 Simulation Settings 6-3
6.1.1.1 General settings 6-3
6.1.1.2 Reset Points 6-7
6.1.1.3 Save Model Initialization 6-8
6.1.1.4 Tracing 6-11
6.1.1.5 Solver Settings 6-13
6.1.1.6 Settings for Symbolical Analysis 6-14
6.1.2 Workflow of the Calculation over Time 6-15
6.1.2.1 Global Symbolic Analysis 6-16
6.1.2.2 Calculation of Consistent Initial Values 6-17
6.1.2.3 Homotopy 6-20
6.1.2.4 Time Steps 6-30
6.1.2.5 Events 6-30
6.1.3 Available Solvers 6-32
6.1.3.1 BDF and MEBDF Solver 6-33
6.1.3.2 Fixed Step Solver 6-36
6.1.3.3 CVODE 6-38
6.1.4 Performance Analyzer 6-41
6.1.4.1 Output 6-41
6.1.4.2 Result Interpretation 6-42
6.1.4.3 Handling 6-42
6.2 Animation of Results 6-42
6.2.1 Record a Animation 6-45
6.2.2 Play back the Animation 6-45
6.2.3 Saving of 3D Animations for external Presentation 6-45
6.3 Periodic Steady-State Simulation 6-46
6.3.1 Basics of the Steady State Simulation 6-48
6.3.1.1 Periodic Steady State of a System 6-48
SimulationX 3 VII
6.3.1.2 Period Vector, Period Variable and Period Computation 6-49

6.3.1.3 Harmonic Balance, Parametric Analysis, Reference
Quantity and Compensation Parameter 6-50
6.3.2 The Steady State Simulation Dialog 6-51
6.3.2.1 Dialog Pages System and Method 6-52
6.3.2.2 Start of the Steady State Simulation 6-53
6.3.3 System Page of the Properties Dialog 6-53
6.3.3.1 Choosing the Reference Quantity 6-53
6.3.3.2 Selection of the Period Variable and the Period 6-55
6.3.3.3 Setting the Orders 6-55
6.3.3.4 Setting the Compensation Parameter 6-56
6.3.4 Page Method of the Properties Dialog 6-56
6.3.4.1 Relative Quantities 6-56
6.3.4.2 Stepsize parameter 6-56
6.3.4.3 Relative Tolerance 6-57
6.3.4.4 Oversampling 6-58
6.3.4.5 Algorithm 6-58
6.3.5 Result Window for the Steady State Simulation 6-62
6.3.5.1 Activation of the Protocol Attribute of Result Quantities 6-63
6.3.5.2 Opening Result Windows 6-63
6.3.5.3 Representation of the Spectra 6-64
6.3.5.4 Representation of the Signal 6-67
6.4 Equilibrium (Static / Steady-State) 6-69
6.5 Linear System Analysis 6-70
6.5.1 Natural Frequencies and Mode Shapes 6-72
6.5.1.1 Eigenvalues 6-73
6.5.1.2 Eigenvectors 6-75
6.5.1.3 Deviation 6-75
6.5.1.4 Distribution of Energy 6-77
6.5.1.5 Campbell Diagram 6-79
6.5.1.6 Animation 6-80
6.5.2 Input-Output Analysis 6-81
6.5.2.1 Settings 6-82
6.5.2.2 Frequencies Analysis 6-82
6.5.2.3 Poles and Zeros 6-84
6.5.2.4 Export 6-85
6.6 Variant Analysis 6-87
VIII SimulationX 3
Table of Contents
6.6.1 Range of Application 6-87

6.6.2 Preparation 6-87
6.6.3 The Variants Wizard 6-88
6.6.3.1 Welcome Page 6-88
6.6.3.2 Parameters 6-89
6.6.3.3 Variants 6-90
6.6.3.4 Results 6-90
6.6.4 Observing the Computation Results during the Variant
Computation 6-94
6.6.5 Calling External Tools for Post-Processing 6-95
6.7 Order Analysis 6-95
6.7.2 Functionality 6-96
6.7.2.1 Basis Signal over Frequency (Computation over the Time) 6-97
6.7.2.2 Basis Signal over Order (Computation over the Integral of
Base Signal) 6-98
6.7.2.3 Order over Time 6-99
6.7.3 Operation 6-100
6.7.3.1 Import of source Data 6-100
6.7.3.2 Setting of Analysis Options 6-104
6.7.3.3 Setting Display Options 6-109
6.7.3.4 Saving, Printing and Result Export 6-111
6.8 Power Balance 6-111
6.8.1 General Functionality 6-111
6.8.2 Generating a Power Balance in SimulationX 6-113
6.8.2.1 General Procedure 6-113
6.8.2.2 Procedure in models with compounds 6-115
6.8.3 Power Sensors 6-115
6.9 Troubleshooting: What should I do if... 6-116
6.9.1 Frequent Modeling Problems 6-117
6.9.2 Calculation of consistent initial values failed 6-119
6.9.3 Singularity problem 6-120
6.9.4 Slow simulation speed 6-120
6.9.5 General Hints 6-123
7 Result Analysis, Documentation and Settings 7-1

7.1 Overview 7-1
7.2 Visualizer 7-1
SimulationX 3 IX
7.2.1 To Open the Visualizer 7-2

7.2.2 Linkage with Result Variables 7-2
7.2.3 Other Settings 7-3
7.2.4 Extended Visualizers 7-5
7.2.4.1 Chart 7-5
7.2.4.2 Sankey Diagram 7-7
7.2.5 Comment 7-7
7.3 Result window 7-8
7.3.1 Basics 7-8
7.3.2 Opening result windows 7-9
7.3.2.1 Empty result windows 7-9
7.3.2.2 Context menu (structure view) 7-9
7.3.2.3 Model Explorer 7-10
7.3.2.4 Properties window (model elements and connections) 7-11
7.3.2.5 Result Bar (Result window) 7-11
7.3.2.6 Result Window Manager 7-12
7.3.2.7 COM Interface 7-13
7.3.3 Structure of result windows 7-13
7.3.3.1 Definitions 7-13
7.3.3.2 Window layout 7-13
7.3.4 Move and copy 7-18
7.3.4.1 Moving and copying results 7-18
7.3.4.2 Moving and copying panels 7-18
7.3.4.3 Moving and copying pages 7-21
7.3.5 Customizing view 7-21
7.3.5.1 Adjusting the axes 7-21
7.3.5.2 Auxiliary lines 7-23
7.3.5.3 Display of Orders at the Steady State Simulation 7-24
7.3.5.4 Editing labels 7-24
7.3.6 Post-processing 7-27
7.3.6.1 Transformations 7-27
7.3.6.2 Operations (Links) 7-28
7.3.6.3 Data model and internal structure 7-28
7.3.6.4 Composition of Transformations and Operations 7-30
7.3.6.5 Description of operations with Modelica expressions 7-31
7.3.6.6 Measuring result curves 7-33
7.3.7 Freezing and importing result curves 7-36
7.3.8 Exporting and Printing 7-37
X SimulationX 3
Table of Contents
7.3.9 Settings 7-37

7.3.9.1 Property Bar 7-37
7.3.9.2 Loading and saving settings 7-50
7.3.9.3 Setting default settings 7-51
7.3.10 Managing result windows 7-51
7.3.10.1 Merging result windows 7-51
7.3.10.2 Result window manager 7-51
7.3.10.3 Fast Fourier Transformation (FFT) 7-52
7.3.10.4 Complex frequency response function 7-53
7.4 Printing (PrintEngine) 7-54
7.4.1 Print Preview 7-54
7.4.1.1 Selection bar 7-55
7.4.1.2 Toolbar 7-55
7.4.1.3 Page Settings 7-55
7.4.2 User defined Print 7-57
7.5 TVA Report Generator 7-60
7.5.1 General Procedure 7-61
7.5.2 Configuration File 7-63
7.5.3 Computation Basics 7-64
7.5.3.1 Natural Frequencies, Mode Shapes and Energy
Distribution 7-64
7.5.3.2 Engine-excited Resonance Speeds 7-64
7.6 General Settings 7-65
7.6.1 General 7-65
7.6.2 Directories 7-67
7.6.3 Libraries 7-67
7.6.4 Storing 7-68
7.6.5 Modelica 7-70
7.6.6 Editor 7-70
7.6.7 General Settings 3D View 7-71
7.6.8 Fluids 7-71
7.6.9 Miscellaneous 7-72
7.6.10 Connections 7-72
7.6.11 Languages 7-72
7.6.12 Licensing 7-73
7.6.13 Maintenance 7-73
7.6.14 Customizing of the Program 7-75
SimulationX 3 XI
8 Customizing and Extension 8-1

8.1 Administration of user-defined Types in SimulationX 8-1
8.1.1 Import of ExternalTypes Packages 8-7
8.1.2 Interactive Type Correction for Loading Models 8-8
8.1.2.1 The Type Correction Dialog 8-9
8.1.2.2 Corrections outside the Current Model 8-10
8.1.2.3 Example for the Interactive Type Correction 8-11
8.2 TypeDesigner 8-11
8.2.1 Starting and Dialog 8-12
8.2.2 Features of the TypeDesigner 8-13
8.2.2.1 General 8-13
8.2.2.2 Connectors 8-14
8.2.2.3 Base Types 8-15
8.2.2.4 Components 8-15
8.2.2.5 Local Types 8-20
8.2.2.6 Imports 8-21
8.2.2.7 Activity Groups 8-23
8.2.2.8 Behavior 8-26
8.2.2.9 Modelica Code 8-27
8.2.2.10 Documentation 8-29
8.2.2.11 Security 8-30
8.2.3 Extension of Types (Inheritance) 8-31
8.2.4 Compounding Submodels 8-32
8.2.4.1 Inner Connectors 8-33
8.2.4.2 Inner Components 8-34
8.2.5 Creating Packages (Libraries) 8-37
8.2.6 Functions 8-37
8.2.6.1 Internal/External Functions 8-37
8.2.6.2 Partial Derivations 8-37
8.2.6.3 Example External Function 8-37
8.2.7 Simulation Specific Functions 8-44
8.3 FluidDesigner 8-49
8.3.1 FluidDesigner Hydraulics 8-49
8.3.1.1 General 8-50
8.3.1.2 Viscosity 8-52
8.3.1.3 Density 8-53
8.3.1.4 Compressibility 8-53
XII SimulationX 3
Table of Contents
8.3.1.5 Heat Expansion 8-54

8.3.1.6 Specific Heat 8-54
8.3.1.7 Thermal Conductivity 8-54
8.3.1.8 Aeration 8-54
8.3.1.9 Vapor Pressure 8-54
8.3.1.10 Limits 8-54
8.3.2 FluidDesigner Pneumatics Gases 8-55
8.3.2.1 General 8-55
8.3.2.2 Viscosity 8-55
8.3.2.3 Caloric Properties 8-55
8.3.2.4 Thermal Conductivity 8-55
8.3.2.5 Specific Enthalpy 8-56
8.3.2.6 Real Gas 8-56
8.3.2.7 Limits 8-56
8.3.3 FluidDesigner Mixtures 8-56
8.4 Statechart Designer 8-56
8.4.1 Introduction 8-56
8.4.2 Graphical Notation of State Machines 8-57
8.4.2.1 States 8-57
8.4.2.2 Transitions 8-58
8.4.2.3 Pseudostates 8-59
8.4.2.4 Trigger 8-60
8.4.2.5 Guards 8-62
8.4.2.6 Priorities 8-62
8.4.2.7 Self-Transitions und internal Transitions 8-63
8.4.2.8 Composite States 8-64
8.4.3 Statechart Designer of SimulationX 8-67
8.4.3.1 Start and Interface 8-68
8.4.3.2 Modeling 8-68
8.4.3.3 Animated view of the statechart in SimulationX 8-75
8.4.4 Semantics of Notational Elements in Modelica-Code 8-76
8.4.4.1 States 8-76
8.4.4.2 Transitions 8-78
8.4.4.3 Signal-Trigger 8-79
8.4.4.4 Change-Trigger 8-81
8.4.4.5 Time-Trigger 8-82
8.4.4.6 Guards 8-83
8.4.4.7 Priorities 8-86
SimulationX 3 XIII
8.4.4.8 Transition Activities 8-87

8.4.4.9 Composite States 8-88
8.4.4.10 Overall structure of Modelica coding 8-95
9 Interfaces 9-1
9.1 Data formats 9-1
9.1.1 Text Format 9-1
9.1.1.1 Save File 9-1
9.1.1.2 Load File 9-2
9.1.2 IEEE-Binary Format 9-4
9.1.2.1 Save File 9-4
9.1.2.2 Load File 9-5
9.1.3 ITI-Binary Format (*.rfb) and ITI-ASCII Format (*.rfu) 9-7
9.1.4 XML-Format 9-7
9.1.5 DIAdem-Headerformat 9-7
9.2 Interfaces to MS Office, Data Exchange 9-7
9.3 COM Interface 9-7
9.3.1 Classes 9-9
9.3.1.1 Application 9-9
9.3.1.2 Documents (Document) 9-9
9.3.1.3 SimObjects (SimObject) 9-10
9.3.1.4 Connections (Connection) 9-11
9.3.1.5 Parameters (Parameter) 9-11
9.3.1.6 Curves (Curve) 9-11
9.3.1.7 Results (Result) 9-12
9.3.1.8 Selection 9-13
9.3.1.9 ResultWindows (ResultWindow) 9-14
9.3.1.10 NaturalFrequencies 9-15
9.3.1.11 InputOutputAnalysys 9-17
9.3.2 Examples 9-18
9.3.2.1 VBScript Example 9-18
9.3.2.2 Jscript Example 9-19
9.3.2.3 ITI-Script Example 9-20
9.3.3 Code Export via COM Interface 9-21
9.4 Co-Simulation Interface 9-27
9.4.1 Co-Simulation with SimulationX Coupling Element 9-27
9.4.1.1 Description of Communication Protocol 9-27
9.4.1.2 Using Coupling Element in SimulationX 9-29
XIV SimulationX 3
Table of Contents
9.4.2 Co-Simulation with Simulink 9-30

9.4.3 Co-Simulation with CarSim, BikeSim, TruckSim 9-32
9.4.3.1 Introduction 9-32
9.4.3.2 Workflow 9-32
9.4.3.3 The Sample Model 9-33
9.4.3.4 Preparation of the CarSim Model 9-33
9.4.3.5 Preparation of the SimulationX Model 9-36
9.4.3.6 Co-Simulation 9-39
9.4.3.7 Post processing in CarSim and SimulationX 9-42
9.5 Code Export 9-42
9.5.2 Code Export Wizard 9-45
9.5.2.1 Dialog page Project 9-45
9.5.2.2 Selection of signal inputs 9-47
9.5.2.3 Selection of outputs 9-48
9.5.2.4 Parameter selection 9-49
9.5.2.5 Selection of characteristic curves (only NI VeriStand) 9-50
9.5.2.6 (Additional) Libraries 9-50
9.5.2.7 Code Generation 9-51
9.5.2.8 Post-Processing 9-52
9.5.3 Project Types 9-53
9.5.3.1 C-Code (without Solver) 9-53
9.5.3.2 Executable Model 9-53
9.5.3.3 Simulink S-Function 9-59
9.5.3.4 NI VeriStand 9-63
9.5.3.5 NI LabVIEW Control Design and Simulation Module 9-64
9.5.3.6 FMI 9-66
9.5.3.6.1 FMI for Model Exchange (1.0 and 2.0) 9-66
9.5.3.6.2 FMI for Co-Simulation (1.0 and 2.0) 9-68
9.5.3.6.3 External Resources 9-71
9.5.3.7 CarSim, BikeSim, TruckSim component (VehicleSim) 9-72
9.5.3.8 ETAS LABCAR 9-76
9.5.3.9 B&R Automation Studio 9-77
9.6 Code Import 9-79
9.6.1 FMU Import 9-79
9.6.2 Code Import from Simulink 9-83
9.6.2.1 Code Import by FMU 9-83
SimulationX 3 XV
9.6.2.2 Code Import using RTW Import Element 9-86

9.7 Interfaces to other Tools 9-88
9.7.1 Optimization with OptiY 9-88
9.7.2 Optimization with Isight 9-88
9.7.2.1 Component Editor 9-88
9.7.2.2 Mapping of Parameters and Result Variables 9-89
9.7.3 Optimization with optiSLang 9-90
9.7.4 FEM-Import 9-90
9.8 SafetyDesigner 9-91
9.8.2 Global Workflow of Model based Safety Design 9-91
9.8.2.1 Conventional Safety Analysis 9-91
9.8.2.2 Model based Safety Design 9-91
9.8.3 Model based Safety Optimization 9-92
9.8.3.1 Semiautomatic Structural Optimization of Models 9-92
9.8.3.1.1 Requirements 9-92
9.8.3.1.2 Changing the Model Structure 9-93
9.8.3.2 Handling of Design Choices in Models Modeling
Concept 9-93
9.8.3.3 Description of Design Choices for Optimization -
Implementations 9-94
9.8.4 Extension of SimulationX 9-94
9.8.4.1 Software Structure 9-94
9.8.4.2 Extension of GUI SafetyDesigner 9-95
9.8.4.2.1 Page General 9-96
9.8.4.2.2 Page Basic Events 9-98
9.8.4.2.3 Page Potential Common Cause Failures (PCCF) 9-101
9.8.4.2.4 Page Output Deviations 9-102
9.8.4.2.5 Dialog for Definition of Failure Classes 9-104
9.8.4.2.6 Page Connected Ports 9-106
9.8.4.3 Fault Tree Generation Wizard 9-108
9.8.4.3.1 Page Tools and Options 9-109
9.8.4.3.2 Page Actual Common Cause Failures 9-111
9.8.4.3.3 Page Potential Common Cause Failures 9-112
9.8.4.3.4 Page System Output 9-113
9.8.4.3.5 Page Analysis 9-113
9.8.4.4 Integration in the Modeling Environment 9-114
9.8.4.5 Printing Capabilities 9-115
XVI SimulationX 3
Table of Contents
9.8.4.6 COM-Interface 9-117

9.9 Polygon Editor 9-117
9.9.1 Preparation 9-117
9.9.2 Overview 9-117
9.9.3 3D View 9-118
9.9.4 Contact Data 9-118
9.9.5 Toolbar 9-119
9.9.6 Generating Polygons 9-120
9.9.7 Edit Polygons 9-120
9.10 Database Link 9-121
9.10.1 Creation of Database Link 9-122
9.10.2 Automatic creation of a data source 9-123
9.10.3 Connect to existing database 9-125
9.10.3.1 Database Selection 9-125
9.10.3.2 Table Selection 9-128
9.10.3.3 Linkage of Parameters 9-130
9.10.4 Data Selection 9-131
9.10.5 Removal of a Database Link 9-133
9.10.6 Linkage of curves and maps 9-133
9.10.6.1 Curves 9-133
9.10.6.2 Maps 9-135
9.10.7 Hierarchical database links 9-136
10 Modelica in SimulationX 10-1

10.1 General Hints 10-1
10.2 Modeling with the Modelica-Standard-Library 10-2
10.3 Combining the SimulationX Libraries with the Modelica Standard
Library 10-4
10.4 Differences in SimulationX 10-4
10.4.1 Lexical Structure and Syntax 10-5
10.4.2 Operators and Expressions 10-6
10.4.2.1 Arithmetic Operators 10-6
10.4.2.2 Equality, Relation, and logical Operators 10-7
10.4.2.3 Numeric Functions 10-7
10.4.3 Classes, Types and Declarations 10-8
10.4.3.1 Component Declaration 10-8
10.4.3.2 Attributes of pre-defined Types 10-8
SimulationX 3 XVII
10.4.4 Name Spaces and Identifiers 10-10

10.4.4.1 References on local parameters 10-10
10.4.5 Inheritance, Modification und Redeclaration 10-11
10.4.6 Equations 10-11
10.4.6.1 The for Statement 10-12
10.4.6.2 If Statement 10-13
10.4.6.3 The when Statement 10-13
10.4.7 Connectors and connect Equations 10-14
10.4.8 Arrays 10-14
10.4.9 Assignments and Algorithm sections 10-15
10.4.9.1 Algorithm and Assignments 10-15
10.4.9.2 The for Statement 10-16
10.4.9.3 If Statement 10-16
10.4.9.4 The when Statement 10-16
10.4.9.5 The while Statement 10-17
10.4.10 Functions 10-17
10.4.11 Libraries (Packages) 10-17
10.4.12 Annotations 10-17
10.5 Conversion of models for use in SimulationX (since version 3.7) 10-18
10.5.2 New warnings and error messages 10-18
10.5.3 Event Handling 10-26
10.5.3.1 Terms 10-26
10.5.3.2 Multiple executions of instructions in when blocks 10-29
10.5.3.3 Avoiding algebraic loops with discrete variables 10-30
10.5.4 Initialization 10-32
10.5.5 Variability 10-33
10.5.5.1 Observing variability 10-33
10.5.5.2 Discrete and continuous variables and expressions with
noEvent 10-34
10.5.6 Algorithms 10-35
10.5.6.1 Initialization of variables in algorithms 10-35
10.5.6.2 Outputs of algorithms 10-37
10.5.7 The stateSelect attribute 10-37
10.5.8 Bus systems 10-38
10.5.9 Miscellaneous 10-40
10.5.9.1 Assigning a variable in when blocks in the equation section10-40
10.5.9.2 The operator last(v) at the starting time 10-41
XVIII SimulationX 3
Table of Contents
10.5.9.3 Global parameters and variables in the model 10-41

10.5.9.4 References to variables of other types 10-41
10.5.9.5 Input variables 10-42
10.5.9.6 Model variable time 10-42
10.5.9.7 Settings in the simulation control dialog 10-42
10.5.9.8 Propagation of parameter activity 10-43
11 FAQ Frequently asked questions 11-1

11.1 General 11-1
11.2 Installation/Licensing 11-2
11.3 Simulation/Computation 11-5
11.3.1 BDF and MEBDF Solver 11-5
11.3.2 Fixed Step Solver and CVODE 11-27
11.3.2.1 Warnings in the context of non-solvable blocks 11-27
12 Definitions 12-1
13 Bibliography 13-1
14 Index 14-1
SimulationX 3 XIX
XX SimulationX 3
by
Introduction
Fields of Application
1 Introduction
1.1 Fields of Application
SimulationX is a program package for the modeling, computation, simulation,

optimization and reliability analysis of components and systems in many areas of
technological development. The computation bases of all the important physical
domains, as for instance mechanics, fluid, control, electrical technology and
magnetics, are provided in extensive libraries.
The software offers sophisticated modeling tools, which permit to image all the
physical-technological relationships in the form of compounded elements. It makes
the software versatile and suitable for new fields of application, and this reflects
the objective of the ESI ITI team to provide you with all the prerequisites and tools
to implement your special know-how in customized models which suit your tasks
best. But there are also general fields of application, which incorporate more than
fifteen years of experience in modeling and simulation, i.e. libraries, sample
models, reference applications and the ESI ITI support team and our partners.
Engineering such as automotive, power transmission and fluid dynamics belongs
to the classical fields of application of the ESI ITI simulation software. The
program is typically used in machine and plant construction, in shipbuilding and
tracked vehicle manufacture and in the aerospace industry. Other applications are
microsystem engineering, planning of off-shore plants, optimization of magnetic
drives, thermal and energy management, fuel cells etc.
1.2 Solution Concept
The program package supports the overall design process both horizontally and
vertically. By having integrated the modeling and computation of submodels of
various kinds in a common environment, the comprehensive system simulation of
complex components, machines, vehicles and plants becomes possible. Universal
data interfaces, COM programming and cosimulation modules ensure the optimal
further use of calculated data, the CAD connection and connection to CAE tools.
With data bases for parameters, models and variants and optimized interfaces the
step is made from system research to the design with data of real components.
SimulationX unites modeling concepts on different levels. On the one hand,

models can be designed fast and efficiently with validated standard elements from
the supplied libraries. And on the other hand, experienced model developers have
at their disposal a sophisticated development environment with the comfortable
TypeDesigner tool to create user-defined elements. The object-oriented modeling
language Modelica enhances efficiency and safety in the development. The
SimulationX 3 1-1
User Manual 1. Introduction
Modelica language provides the modeler with a high degree of freedom for the
description of his systems and processes.
The complexity of model descriptions sets high standards for the computational
tasks during simulation. SimulationX implements a number of analytical and
numerical methods, which lead to a high performance also for sophisticated
models. In several compilation runs the system of differential algebraic equations
(DAE) is subject to a global symbolic analysis, reduction, and simplification. The
resulting compact equation system is handed over to a powerful solver. By default,
the BDF method is used, which ensures a good performance also for stiff systems,
as they often arise from heterogeneous models. The applications to be examined in
industrial practice virtually always contain nonlinearities and in particular
discontinuities. SimulationX considers discontinuities with adjustable precision.
From Version 3 an implementation of CVODE is available in addition. You can

save computing time with this explicit solver in particular with models which lead
to common differential equations. When you choose this procedure for your
simulations you also benefit from the fact that model and solver are compiled
separately prior to runtime. This yields another performance increase which is
independent of the model.
1.3 Scope of Computation

This program is used to study systems, which are described as a network of (space)
compounded elements. The domain-specific valid revolution and intersection laws
for difference and flow variables are part of the system. In addition the modeling is
supported on the basis of signal flow charts. The notation of the SimulationX
models has sequential algorithms, (algebraic) equations, (common) differential
equations, analytical or empirical (characteristic curve) functions and logical
conditions for state transitions. It can (also) be used to image linear systems and
simple controls of course. The advantages of the program become obvious mainly
when you study the dynamics of non-linear systems, discontinuities, interaction
with controls and in the integration of external measuring data and characteristic
maps.
Despite of the sophisticated modeling tools, model development is still a

demanding work which requires creativity and concentration. The more important
is that a model of a system which you develop can also be used for various and
diverse analyses and computations. What computation tasks can be solved with
SimulationX?
With computation in the time domain (transient simulation) the entire behavior of a
system within a time interval can be examined. Inputs by the system and initial
values defined by the user will be taken into account.
1-2 SimulationX 3
Modelica
Frequently, an equilibrium of the system must be determined which will be the

starting point for other examinations. This is called the static or stationary state.
At every point of operation SimulationX can perform a structure analysis of the

linearized system and calculate eigenfrequencies, eigenvectors, frequency
responses and transfer functions.
For the Steady-State Simulation, for instance, of torsion vibration applications the
tool ITI-STAT has already been offered by ESI ITI. An even more powerful and
more universal analysis procedure has been developed which is now offered as an
option in SimulationX.
On the basis of the functional structure of the model and additional local error
probabilities, SimulationX can generate a model for reliability analysis.
Due to the common model basis the analysis types can be combined in a suitable
way. In addition extensive parameter studies can be made more efficiently with the
Variants Wizard.
1.4 Modelica
Since the language Modelica has already been used for model description in the
SimulationX libraries, SimulationX supports the full language scope of Modelica.
As a SimulationX user you can now benefit from the Modelica standard libraries in
addition to the scope of performances available so far. As a modeling expert you
can draw on extensive language constructs like arrays and records for complex
models to be developed anew.
1.5 Software Development

The program package was developed with modern software methods. An
extensive internal class library, mainly on the basis of C++, permits the developer
engineers to respond flexibly to the user requirements. Quality assurance has been
and is an integral part of the SimulationX development.
The models of the standard libraries were tested individually and with regard to
their interaction in complex applications. In the test the solver methods were
subjected to partially extreme requirements. Since the tasks of the user become
more and more demanding, perfecting our software is our daily challenge. Your
experiences, criticism and proposals are welcome. Call our service, we gladly help
you in finding solutions to your issues. Information about our workshops and
trainings is offered in Internet.
SimulationX 3 1-3
User Manual 1. Introduction
ESI ITI wishes you success for your work with SimulationX and a lot of fun with
the simulation.
Dresden, 2016
1-4 SimulationX 3
by
Installation
Installation - Overview and Basics
2 Installation
2.1 Installation - Overview and Basics
The program was developed for Windows operating systems.
For the installation of SimulationX you need the rights of access of an

administrator. If you do not have the necessary rights of access, let your system
administrator carry out the installation. If you experience any problems during the
installation with an existing virus scanner, deactivate it for the time of the
installation.
2.1.1 Hard and Software Conditions for SimulationX

To ensure that SimulationX is executable on your system, certain minimum
requirements must be ensured, cf. Table 2.1.
Component Minimum requirements Recommended Configuration

Operating Systems Windows Vista* Windows 7 x64 and newer*
Main memory 1 GB depending on the application **
(RAM) (2 GB for x64 Systems) min. 4GB
Hard Disk Minimum 2 GB depending on the application **
Graphics 3D-capable graphics card depending on the application **
Drives DVD-ROM drive for installation
* The installation of the latest service packs is recommended
** The effectively required memory (RAM, Graphic RAM and HDD) is
dependent on model size and complexity
Table 2.1: Hard and Software Requirements
If you intend to purchase a new system, ESI ITI recommends a system with
performance parameters that are suitable for tasks in the CAE area. Processor
speed and main memory configuration are the decisive components for this (as a
rule, the more GHz and MB the better).
2.1.2 Requirements of Code Export and external Solver

For the creation of executable code during the code export (Executable Models
etc.) and for the simulation with external solvers (CVODE, FixedStep) a compiler
is needed. For information about development environments supported by
SimulationX, refer to the following table.
SimulationX 3 2-1
User Manual 2. Installation
Development Environment SimulationX 32bit SimulationX 64bit
Ext. CE CE Ext. CE CE
Solver for for Solver for for
x86 x64 x86 x64
Microsoft Visual C/C++ 6.0 x x x
Microsoft Visual C/C++ .Net x x x
Microsoft Visual C/C++ .Net x x x
2003
Microsoft Visual C/C++ 2005 x x x x x x
Microsoft Visual C/C++ x x x
Toolkit 20031
Microsoft Visual C/C++ 2008 x x x
Express Edition1
Microsoft Visual C/C++ 2010 x x x3 x3 x x3
Express Edition2
Microsoft Visual Studio x x x x x x
Express 2012 for Windows
Desktop2
Express 2013 for Windows
Desktop2
Community 2013
Microsoft Visual Studio 2015 x x x x x x
Visual C++ 2015 Build Tools x x x x x x
1
free but not more available
2
free, available on www.microsoft.com
Please note the license conditions of Microsoft.
Table 2.2: Requirements for external Solvers and code generation during Code Export
2-2 SimulationX 3
We recommend to install the Microsoft Visual Studio 2015 due to the integrated
C/C + + compiler that can be used in SimulationX 64bit without any effort for
additional installation steps.
2.2 SimulationX - Editions
2.2.1 All editions Overview
There is a SimulationX product DVD available for all editions. The respective
edition is activated by selection during the first start of SimulationX.
Edition
Program Function Student Viewer Analyzer Professional
File new x x
File open x x x
File open (encrypted) x x x x
File save x x x
File save (encrypted) x x x
Side preview x x x
Print x x x x
Load user-defined x x x x
Types
Create/Edit user- x x
defned Types
Edit Models x x
(Structure)
Edit Parameters x x x
Control Elements / x x
Momentary Displays
Database Connection x License License
Computation x x License License
3D view x x License License
Script editor x x
Table 2.3: Available (x) Functions in the Editions
2.2.2 Evaluation version

SimulationX is available as a fully functional Professional Edition for testing
the Evaluation version. This version comprises ALL LIBRARIES AND
SimulationX 3 2-3
OPTIONS which can be tested with COMPLETE FUNCTIONALITY for a limited

period of time.
It needs only a time limited license file generated for your computer, which you get
from ESI ITI by using the request form (see also 2.4.1).
2.2.3 The Student Edition

The student edition allows the execution of student tasks (for educational purpose).
The table shows that only certain model elements and reduced functions can be
used in a limited number of times in a model (cf. Table 2.3). In the Options
dialog on the page Licensing, you see which elements can be used how often
(cf. Figure 2.1).
Figure 2.1: Available model elements in the Student Edition (extract).
2.2.4 The Viewer Edition

With the Viewer Edition user can pass his models as coded version to others. The
models can be opened with the Viewer Edition and computed if necessary. The
results can be printed (cf. Table 2.3).
2.2.5 The Analyzer Edition

The Analyzer Edition is suitable for parameter studies of the prepared models. For
this version a license is needed.
2.2.6 The Professional Edition

The Professional Edition is a full functional powerful tool for model creation,
simulation and analysis. You can use all acquired program functions, libraries and
options without restrictions (cf. Table 2.3). For this version a license is needed.
2.2.7 Change edition

The edition can be changed at any time. You can do it by opening the dialog
Licensing in the menu Extras Options of SimulationX program (s. Figure
2.2).
2-4 SimulationX 3
Installing SimulationX
Click on Edition change to and select an edition for the next program start.
Please mind that Analyzer and Professional Editions need appropriate license code
or key. Table 2.3 gives an overview of the program functions available in the
individual editions.
Figure 2.2: Switch the Edition in SimulationX
2.3 Installing SimulationX

After inserting the DVD the initialization program leads you through all necessary
installation steps. If the autorun function of the DVD drive is turned off, please
start the program Autorun.exe in the DVD root directory. With the start of the
installation wizard a language selection dialog is shown. Select the language of the
user interface. First select Install software.
Figure 2.3: Start screen
SimulationX 3 2-5
By clicking the other buttons, you can view the documents from the DVD, perform
the identification of your computer or read the ESI ITI software contract. The
identification of your computer in order to request a license file is described in
section 2.5.2.2.
Additional you can install options and plugins by this site.
2.3.1 Installation
After the language selection dialog the Installation Wizard starts and looks for
prerequisites that need to be installed in order to run SimulationX correctly.
Figure 2.4: Welcome screen
Figure 2.5: Start of install wizard
One of these prerequisites is the installation of DirectX to enable the best

performance of the SimulationX 3D view. If you already have DirectX 9.0c
installed (the exact version is important) or if you do not want to use the 3D model
view at all, you can skip the DirectX configuration by checking the box.
2-6 SimulationX 3
Uninstalling an older version of SimulationX is not necessary. Different versions

of SimulationX can be installed and run on one computer independently. This does
not include different releases of the same version however. If the installer finds an
older release of the same SimulationX version on the computer, it will remove the
older release and will also install components required by the application before
the actual installation begins.
Figure 2.6: License agreement
In order to continue with the installation, accept the license agreement by clicking
on Next.
The following dialog gives you different options for installing SimulationX:
Complete All features and modules that are available are installed.
The documentation and samples are copied to your hard
drive. To install special modules with prerequisites like the
Isight interface you need to choose the Customized
installation.
When you are installing to a 64bit system SimulationX
will be installed in a 64bit version. When you want to use
the 32 bit version on 64 bit systems please select
Customized here and choose the 32 bit version in the
following dialog.
SimulationX 3 2-7
Customized The user can choose the features he wants to be installed.

Every single module or function can be separately
(de-)selected. The target directories for 32 and 64 bit
components of SimulationX can be set only in this mode
or by using the command line options (see section 2.5).
Figure 2.7: Possible setup types
Figure 2.8: Custom setup
Figure 2.9: Selection of modules and options at the custom installation
2-8 SimulationX 3
For all modules and features, which are needed, the option Install on a local hard
drive is to choose. When you chose a custom setup, you will be able to select the
target folders for 32 and 64 bit components of SimulationX. The other setup types
will use the default location in Program Files and/or Program Files (x86)
under ESI Group\SimulationX X.Y where X and Y represent the major and
minor product version.
After the selection of the shortcut folder and if you want to install desktop and start
menu shortcuts for all users or the current user only, the installation wizard is
ready to go.
Figure 2.10: Completing the wizard
Thus the installation of SimulationX is finished.
If you have purchased a Professional or Analyzer license with a license file you
have to identify your computer first. The identification is described in section
2.5.2.2.
2.3.2 Reinstall or Update

If SimulationX has already been installed and you started the setup, two reactions
may occur depending on the release that has already been installed.
1. You want to install a newer release.
The installed version of SimulationX is going to be removed during the
setup of the requirements for SimulationX software.
2. You want to install the same release for the second time; the maintenance
mode of the setup wizard will be started.
The maintenance mode can also be started with the ITI Software setup start
menu entry or via the Windows Add and remove programs control panel
application.
You can repair the existing release, add or remove features, remove the application
or install the software for the use of SimulationX with hardware dongles or
SimulationX 3 2-9
CodeMeter licenses. Software protection (drivers, services) is only to be installed

on computers which manage licenses (not needed for Test version).
Figure 2.11: Maintenance dialog
These are, for instance:

Workstations with a local Professional or Analyzer Edition as a single
workplace configuration protected by a dongle key.
Computers (servers or workstations) which provide licenses in the network (see
also 2.5.2.1).
The installation of the program protection software is described in the section
2.5.2.
The options Reset License Settings and Reset User Settings can be used to
reset SimulationX e.g. after setting wrong license options. Reset License
Settings removes only the License key from the settings. Reset User Settings
resets SimulationX to the default state and removes most of your custom settings.
You can use the "Fix SimXLauncher" option to repair the file associations of
SimulationX models (.ism) and SimulationX Projects (.isx) with the
SimXLauncher. The SimXLauncher allows the user to set the SimulationX version
(if multiple versions are installed) that should be used to open SimulationX files.
2.4 First start of the program
When SimulationX is started on your computer for the first time, the program
displays the dialog for edition selection (see Figure 2.12).
2-10 SimulationX 3
First start of the program
Figure 2.12: Edition selection dialog
Select the desired edition here and click Start. See also Section 2.2.2 to 2.2.6.
2.4.1 SimulationX - Evaluation-version

For running the program as Evaluation-version a license file is needed.
For submission, please click on the button Request (cf. Figure 2.12).
After the information that devices with a non-permanent MAC address (e.g. PDAs)
are to be disconnected from the computer, the request dialog (see Figure 2.13)
appears.
Please add your desired test period, planned application fields and personal data.
If an email client has been installed on your system, you can transmit the data
directly. By clicking the Generate button an email is created which you only
need to send (s. Figure 2.14).
SimulationX 3 2-11
Figure 2.13: Dialog for requesting a license file
If your request is received and agreed by ESI ITI, they will email the license file to
you.
The license file can be used after a click on the button Search (cf. Figure 2.12).
Consider please that the license file assigned by ESI ITI works only with the
computer, by which it were requested!
No other installations (drivers, services, etc.) will be required.
Upon each further program start the dialog in Figure 2.15 is displayed with the
end of the test period. During the test period you can change your license file to a
newer one (e.g. with other or more libraries, modules ...). In order to do that, click
the Update... button and select the newer license file. This will update the
existing license file to the newer one.
2-12 SimulationX 3
First start of the program
Figure 2.14: E-mail for requesting a license file
When the test period has elapsed, a corresponding note appears and the start dialog
is displayed as shown in Figure 2.12. Although the license is expired, you can
request another testing period or still use the program as a Student or Viewer
Edition.
Figure 2.15: Start-Dialog of the trial edition
Please note that the license file which ESI ITI provides will only work with the
computer which has requested it!
SimulationX 3 2-13
When you purchased a license with hardware key/dongle in the meantime, install
the SimulationX copy protection software first from the product DVD please.
These can be found in the Dongle directory on the DVD. For this purpose the
"SentinelProtectionInstaller.exe" has to be started (for 64-bit systems you use
"SDD_USB_x64_Installer.exe"). The installation is described in detail in
section 2.7.
2.4.2 Student or Viewer Edition

For using the program as Student or Viewer Edition no further input is needed.
The dialog at program start indicates the Student Edition (cf. Figure 2.16) is
released.
Figure 2.16: Program Start of Student Edition
2.4.3 Analyzer or Professional Edition

If the program is to be used as an Analyzer or Professional edition a license has to
be purchased first (see also 2.6). This license has to be selected at the start of the
program.
After you have selected the program version with the license according to Figure
2.12 the dialog for selection of a key/dongle (see section 2.7), for selection of a
license file (see section 2.8) or for selection of a CM Container (see 2.12) is
opened. The program can be started after a valid license has been selected.
2.4.4 Migrate Settings from previous Versions

When a new version of SimulationX is started for the first time, the following
dialog is shown, allowing you to import your settings from a previous installed
version of SimulationX:
2-14 SimulationX 3
Hints for Administrators
Figure 2.17: Dialog to import settings of a previous version of SimulationX
You may import the following settings from SimulationX 3.7:

Resultwindow settings (see 7.3.9.3)
3D settings (see 5.4.4.3)
SimulationX Macros
2.5 Hints for Administrators

2.5.1 Installation in the Batch Processing (without user
Interaction)
This installation process is particularly suitable for networks for the software
distribution. The installation of SimulationX can be accomplished in the batch
processing mode without interaction of the user.
The installation in batch mode is executed without any options, standard

installation (see 2.3.1) and is initiated by the command line switch "/ s".
In batch mode, the following parameters are accepted:

ADDLOCAL=ALL This installs all features of SimulationX to be
installed by a complete installation (see also
2.3.1).
TARGET=Path This option specifies the target directory of the
32 bit components.
TARGET64=Path This option specifies the target directory of the
64 bit components.
SimulationX 3 2-15
CHECKPRE=[TRUE|FALSE] This option disables the installation

requirenments check.
NOTE: If there are some uncompliant
requirements, the stable operation of the
software cannot be guaranteed.
Example:
The automatic installation can be started by the command line dialog (click on
Start/Run):
Figure 2.18: Command line dialog
D:\Setup\Setup.exe /s ADDLOCAL=ALL TARGET=C:\temp\SimX

Similar terms can be used in batch files, too.
2.5.2 Installations for Program Protection

In the contrary to the editions STUDENT and VIEWER available for free,
the ANALYSER and "PROFESSIONAL" editions are provided with software
protection. For using SimulationX as Analyzer or Professional edition, software
protection is to be installed.
Program protection can be ensured either by means of hardware key/dongle (see

section 2.5.2.1) or by means of license file (see section 2.5.2.2). For further
information about licensing refer to section 2.6.
The special features and requirements for working with the CodeMeter software
protection are listed in section 2.12.
This can be done after the successful installation of SimulationX. To do this there
are administrative privileges required.
2.5.2.1 Hardware Protection (Key / Dongle)

The installation is to be carried out only at the computers where a key (dongle) is
plugged on. This software installs both components (driver and server). The driver
ensures that SimulationX can communicate with the key. And the server
administrates the License(s) both for the single station and in the network.
After the successful installation of SimualtionX you can start it by:
starting the setup again
2-16 SimulationX 3
choosing the ITI Software Setup entry in the SimulationX startmenu entry
choosing the SimulationX V.V entry of the desired SimulationX version in
the Programs dialog of the Control Panel
Figure 2.19: SimulationX maintenance dialog
At each item of the bullet list the SimulationX maintenance dialog appears. Now
choose the Install Dongle Software radio button (see Figure 2.19) and press
Next.
Make sure that USB keys are NOT PLUGGED IN while the driver is installed.
AFTER the installation, the key is to be plugged in.
Figure 2.20: Key Driver Installation Setup Type
Now the installation of the driver starts. After the Welcome, License
acceptations and Destination selection, select Complete as setup type (cf.
Figure 2.20).
To save disk space, the installation can also be customized. Select the option
"Custom" for this. Next the components which can be installed are to be selected.
SimulationX 3 2-17
Figure 2.21: Key Driver Installation Components Selection
Please, deactivate the components which are not necessary for your key:
a key for parallel interface does not need a USB-System-Driver
a USB-key does not need a Parallel-System-Driver
Click on the hard-disk icon and select the menu entry This feature will not be
available (cf. Figure 2.21).
The installation of the hardware protection component is to be implemented only

once on your system. Further start of the installer calls the program maintenance
dialog of the respective installation on. Continue with section 2.7.
The network communication between client (SimulationX) and server (plugged

key) uses port 6001 as default. In a heterogeneous network therefore is to be
ensured that all connecting and/or branching out components (router, gateway,
bridges, etc.) allow port 6001 for the UPD and TCP communication. Port 6002
communication should be allowed too as it is used monitoring purposes.
Figure 2.22: Monitoring view
2-18 SimulationX 3
When you enter http://servername:6002 in the location bar of your browser

window (server name stands for the name or the IP-address of the computer, with
the key attached) supplies the table for the examination of the key (cf. Figure
2.22).
If you have to change the standard ports use the following procedure:
Server (computer with attached key)
Change the following options in the file sntlconfigsrvr.xml (default path is
C:\Program files (x86)\Common files\SafeNet Sentinel\Sentinel Protection
server\WinNT)
<ConfigurePort>: new port number for communication
<ConfigureLicenseMonitorPort>: new port number for monitoring
Client (user computer with SimulationX) Change the following options in the
file sntlconfig.xml (default path is the SimulationX program directory)
<ServerPort>: new port number for communication
Make sure that the given ports are unused and that client and server have identical
numbers assigned.
2.5.2.2 Software protection with license file

No installations are required for this type of license. Since the license file must be
bound to a concrete hardware the identification of the computer is required on
which the license file is to be stored later.
For this purpose the program for identification has to be executed on this computer
(cf. Figure 2.23).
After you transmitted the data to ESI ITI the ITI team will provide the license file
for your computer after your authorization has been verified.
Save the license file on the computer to a directory where all users have write
permission (the license file will consistently be updated).
By default the license file should be saved to the directory "C:\Documents and
Settings\All Users\User Data\ESI Group\SimulationX 3.8".
Furthermore it is possible to place the license file in a network directory on a
server. To do this, start the program CIPro.exe provided on the installation DVD.
Provided by a UNC target path for the license file (e.g. \\server\share\path) it
identifies the respective server and transmits this information to ESI ITI.
After receiving the license file from ESI ITI make sure, it is stored in the exact
location specified earlier and not renamed. The file path is part of the license.
Continue with section 2.8.
SimulationX 3 2-19
Figure 2.23: Computer identification
2.6 SimulationX the Licensing

The Analyzers and Professional Edition licenses are not free
but with costs. The license is protected by either hardware key
or a software license file.
The licensing of CodeMeter Lizenzen is explained in section

2.12.
SimulationX is a modular structured software program. ESI

ITI GmbH as the software provider and supplier generates the
license according to the modules acquired.
2-20 SimulationX 3
SimulationX the Licensing
2.6.1 Single Station License

The license is usable only at a defined local computer.
Plug in the key onto the interface port (parallel or USB).
Figure 2.24: Selection of a single station license
Install all components of the software package according to 2.2.6, 2.2.7 and 2.5.2.
With the first start of SimulationX-Professional Edition or SimulationX-Analyzer
Edition select the connection to your local key (cf. 2.7). Switch off the opening of
the connection dialog with each program start (cf. 2.7).
2.6.2 Network License

This license is usable in the entire network.
Select a computer in the network, which is to administrate the license(s). Windows

NT operating system (2000, XP Prof. or newer) is required for running the
program. Connect the key to the corresponding interface of the computer. Please
follow the procedure described in 2.5.2 for installing the program protection.
Figure 2.25: Selection of a network license
Install the program SimulationX according to 2.3 on all work stations in which
SimulationX is to run. For this purpose you can use the installation in the batch
processing (cf. 2.5.1).
SimulationX 3 2-21
The user selects the connection to the network key with the first start of
SimulationX (cf. 2.7). If only one key is available in the network, it is
recommended to switch off the connecting dialog with each program start (cf. 2.7).
2.6.3 Several different licenses in the network

SimulationX does not take the first best license available in the network, but
demanding the dedicated connection with a certain license. Therefore it is possible
to have several available SimulationX licenses with different range of functions
in a network.
Example:
For modeling within the following configuration:
Planar Mechanics and Power Transmission (2D),
Power Transmission (1D),
System Analysis
You require three professional licenses (full licenses) of SimulationX. In addition

to the tasks you have to accomplish frequently variant calculations with these
models in the batch processing, as such you will need two more license, i.e.
Analyzer Edition which shall have the same functionality as mentioned above.
Additionally in the neighboring room SimulationX is to be used for
investigations of hydraulic components.
2 Keys on
a computer
Figure 2.26: Different Licenses in the Network
For this task you need one other Professional Edition license which includes
Planar Mechanics and Power Transmission (2D),
MBS Mechanist (3D),
Power Transmission (1D),
Electronic (analog) and Magnetics
2-22 SimulationX 3
Selection of a Hardware key / Dongle
Hydraulics and
System Analysis
Because in one key always exactly the same module combination (a function
range) can be saved, ESI ITI supplies two keys for this application.
You install the software in the network according to 2.6.2. Thereby it is irrelevant
whether both keys are plugged in on a computer or on different computers. It is
only important that they are visible in the network.
The user selects the connection to the desired network key when starting
SimulationX (cf. 2.7). With the option "Show this dialog with program start" the
user can decide whether the program is to ask with each start or whether a
preferred setting should be applied up to cancellation (checkmarks to be removed).
The connection can be changed at any time over the menu "Extras/Options" on the
page Licensing through clicks on the control New Connection.
The connection to a license is user-referred. I.e., on a machine different users can

use different licenses without further inquiry (checkmark for connecting dialog
removed).
2.7 Selection of a Hardware key / Dongle
You can specify which key is to be used when starting SimulationX. In particular
after a first installation the connection is not yet defined. So the dialog for the
connecting selection has to be opened (cf. Figure 2.27). You can open this dialog
also by the menu Extras Options on page Licensing by clicking on the
button New key connection. You may decide first for canceling the action
(Cancel), or where (locally or in the network) licenses are to be searched for (cf.
Figure 2.28).
Searching for available keys can be repeated at any time. Click on the appropriate
control in the field Searching available keys. Searching can be done by means
of using host names or by means of IP addresses. Select the appropriate variant
with the radio buttons Hostname based... and IP addresses based...
If you are not sure, which selection is applicable for your system, select the
standard setting Hostname based selection.
Figure 2.27: Start of searching available licenses
SimulationX 3 2-23
In the field In the network available keys all available keys are indicated in a tree
structure. The local computer is marked by a red circle.
If you click in the tree structure on a SimulationX key (characterized by the key
Ident of the form <letter><number>- > X ###), important contents of this key are
indicated in the field Selected key. If required license (Analyser and/or
Professional) is currently available, the button Activate this key is enabled.
Figure 2.28: Dialog for Connecting Selection to SimulationX-License
If you click on this button, the key just selected in the tree is declared as the
Current connection. I.e., when starting SimulationX will use a license of the
current connection (concrete computer, concrete key).
Searching for keys in the network is done over so-called broadcast calls realized
under the slogan: Hello Sentinel ' Im calling - who will answer me. It could
happen that in the network available keys do not indicate all actually existing
keys. A most frequent cause for it is a prohibition of broadcasts in your network. In
this case you cannot select the desired key in the tree structure, as described above.
You have to do the connection manually. For it you click the Button in the
2-24 SimulationX 3
Selection of a Hardware key / Dongle
field current connection. Thereupon the dialog boxes Host and Key are
released for editing. Register the name of the computer and the identity of the key
into the appropriate fields. The selection in the tree structure and clicking the
switching surface this key activate are void.
If the connecting selection dialog is not to be opened with each start by

SimulationX (e.g. with a single station license) the checkmark Show this dialog at
startup must be removed.
Should the connecting selection dialog is not to be opened with each start by
SimulationX (e.g. with a single station license), remove the checkmark Show this
dialog at startup.
If SimulationX is used in the batch processing (e.g. over COM) the checkmark
should generally be removed, since always a defined license is to be worked with.
If you click on OK button SimulationX will start. You can also continue to work
in the dialog Options.
2.7.1 Update a license

It happens that the key must be reprogrammed for example because
the license period (the rental period) has finished and you want to extend the
using period,
the function range changed by additional purchase of modules,
the number of licenses increased by additional purchase, or
you want to replace your local license by a network license.
You can execute this operation locally by yourself fast and comfortably. You
may order and acquire an update version, ESI ITI will send the update code (a text
file, e.g. by email). After receiving the update code from ESI ITI, please proceed
the following:
1. Store the update code on your hard disk.
2. Start SimulationX (e.g. as a student edition if the validity time of the key has
terminated).
3. Open the dialog Options in the menu Extras Options.
4. Activate the page Licensing.
5. Check in the left upper corner that the correct key used for the update
(cf. Figure 2.29).
If this is not the case (e.g. because you started the Student Edition), select
"Professional (with Dongle)" with Edition Change to first.
Select the key to be updated with New key connection now (the display in
the left upper corner will appear only after a program restart). Open the file
dialog by clicking on the button Update key.
6. Select the stored file (see 1.) and acknowledge the dialog with Open.
SimulationX 3 2-25
The key update is accomplished. Before the key update the consistency of the
codes is checked in order to detect data loss with code transfer. In addition it is
examined whether the code is intended for the selected key. The update procedure
is terminated with a message (success or error).
Figure 2.29: Update of SimulationX key
Only one key can be plugged in for updating otherwise an error occurs.
2.8 Selection a license file

The license file(s) which you purchased must be made "known" to the program. In
addition the license files shall also be managed easily. For this purpose the dialog
Selection of a license file (see Figure 2.30) is used.
The license file must be added to the management once in particular during the
first start of SimulationX with a license file.
The dialog consists mainly of three parts:

current license file,
administrated licenses and
content of the selected license.
In the section Current license file important information such as

file name,
available licenses,
period of validity,
2-26 SimulationX 3
Selection a license file
network use authorized,

current users,
information on validity (see Table 2.4) and
license renewal interval
is displayed regarding the currently used license file.
Figure 2.30: Dialog for selection of a license file
Validity information Meaning

License file is valid Everything ok. The license file can be used.
License file expired The validity period of the license file has expired.
You cannot use this license file anymore.
License file invalid The license file is stored on a computer for which it
(wrong INST code). has not been generated. It cannot be used.
No free license All licenses of this file are being used. The users are
available. displayed as follows (for single-user license - the
computer name, for network license -
user+++computer name). Select another license file.
Table 2.4: Validity information of license files
SimulationX 3 2-27
In the section Administrated licenses all license files are listed which you want
to use with SimulationX. For a better transparency every license file can be given a
self-explanatory name.
The license file management must contain one entry at least - you got at least
one license file from ESI ITI which has to be added here.
License files can be added to and removed from the management.

Click the button Add new license. A dialog (see Figure 2.31) is opened. Click
Search to select the license file which you want to add. Assign an expressive
name and tick use as current license file. After that you can start SimulationX
(provided that you selected a valid license file).
Figure 2.31: Adding new license file to management
When you selected a line in the list of managed licenses with a mouse click you
can delete this selected license from the management by clicking the button
Delete selected license. The license file itself will not be deleted by this action.
Editing of the managed license files (e.g. change of the name) is not possible. For
such a purpose delete the file from the management and add it anew.
Highlight a line in the list of the managed license files with a mouse click. In the
dialog area Content of the selected license the most important information -
total number of licenses, available licenses, period of validity, current users,
network ability and validity details (see Table 2.4) - of the highlighted license file
is displayed.
Click Open License Viewer to open the License Viewer dialog of the selected
license file. You get comprehensive information about the license file here.
The button Use this license file is enabled if the highlighted license file is a
valid license file. Clicking this button sets the license file to be the current one and
it will be used at the start of SimulationX.
Several license files may be available in a network in particular. With the

management you can quickly choose among several licenses.
2-28 SimulationX 3
Specialties for network licenses
If it is not desired that the selection dialog is opened upon every start of
SimulationX (e.g. in the case of a single-user license) remove the tick at "Show
this dialog upon program start". If the dialog is to be shown again open the options
dialog via the menu Extras Options. Go to Licensing. Here you can tick
"Show startup dialog for license selection" again.
Any information in this dialog is user-related. This means that every user of this
computer manages his license files himself.
2.9 Specialties for network licenses
2.9.1 Network licenses with Hard Key
If you have ESI ITI SimulationX network licenses it may happen, that all licenses
are used by other colleagues and you want to know who is currently using the
licenses.
If you have a hard key for license protection, there is the following possibility:
On the computer, where the key is connected to, a license monitor is running (in
addition to the license server). You can connect to the license monitor (see Figure
2.32) using your web browser and entering the address
http://ComputerWithKey:6002
where ComputerWithKey is the name or the IP address of the machine where the
key is connected to.
Figure 2.32: Sentinel license monitor
By clicking on a key number you can retrieve further information about this key (s.
Figure 2.33). It is an unsigned Java applet of the Safenet Inc. (safety set acc).
SimulationX 3 2-29
Figure 2.33: Key information
2.9.2 Network License with License File

2.9.2.1 License renewal interval
For licenses that are be used in a network a license renewal interval has to be set.
This is done automatically during program startup using a default value.
The license renewal interval ensures, that lost licenses can be reused after a certain
timeout (for instance after the program has crashed).
If a license is used in a LAN or WLAN network normally no modifications of the
defaults are necessary.
If a license should be used in a WAN (Wide Area Network), a resource problem
may appear, caused by a too narrow small bandwidth (slow network speed). As a
result, during the program start process, when SimulationX checks the license for
all modules, the license renewal interval times out and the licenses for all modules
will be rechecked. The problem manifests itself when SimulationX starts very,
very slow or when it does not start without an error message.
In order to fix the problem you can set up the license renewal interval manually.
Figure 2.34: Setup of the license renewal interval
2-30 SimulationX 3
The edit box will be enabled when you have clicked the edit button and
confirmed warning message.
Attention! Please choose the license renewal interval only as large as necessary
for proper program operation.
Please preconceive that lost licenses can be reused only after a timeout. This
timeout is 150% of the renewal interval.
Entering a license renewal interval = 0 means that default value shall be used.
The default values for the license renewal interval are as follows:
1 Lic. = 4 sec
5 Lic. = 20 sec
10 Lic. = 41 sec
20 Lic. = 84 sec
50 Lic. = 214 sec
100 Lic. = 440 sec
500 Lic. = ca. 40 min
1000 Lic. = ca. 87 min
2000 Lic. = ca. 190 min
How can a suitable license renewal interval be estimated? Assume that the
message traveling time between the license server and a remote computer is p
seconds. The license will have q modules (the number of modules can be counted
in the license viewer), for each a license request will be sent by the remote
computer. All license requests must be processed within the license renewal
interval, i.e.
license renewal interval > p*q seconds.
If more than one license is administrated by the license server, the renewal interval
should be multiplied by the number of licenses.
2.9.2.2 Empty entries within the license file

The following statement only applies to license files with more than one license.
Network licenses with license file can become inactive temporarily, but are
reactivated by a heartbeat function. (cf. 2.9.2.1). When the program starts, a free
license for the Professional or the Analyzer module is only provided, if the
maximum number of users minus the currently active and inactive users is greater
than zero. In this case, that the program crashes during an inactive license phase,
the license will not be returned to the pool of available (free) licenses. These
licenses can be regained using the Cleanup dialog, if NO user is active.
Long term studies revealed the following possible incorrect behavior:
SimulationX 3 2-31
License entries for libraries and options of active users still remain after an
(abnormal) end of the program.
License entries of inactive users remain the Professional, respectively the
Analyzer module.
Both situations can be cleared up.
License entries of active users that are inactive can be deactivated using the
License Viewer.
To realize this, open the License Viewer either from the license selection
dialog of the respective license (cf. 2.8) or for the current license file using
the menu Extras Options Licensing.
Select the entry you want to deactivate and click Deactivate. The entry is
shown within brackets and can now be used again.
Please pay attention that only entries are deactivated which are really not
in use!
License entries of inactive users within the Professional, resp. the

Analyzer module can be removed using the Cleanup dialog within the
startup license selection dialog.
2-32 SimulationX 3
Figure 2.35: Startup dialog with the Cleanup button
This procedure is only possible if no other user is active. The cleanup button
is enabled; if there are only inactive users (entries in brackets in
Figure 2.35). Click the button to open the license files Cleanup dialog
(see Figure 2.36).
Figure 2.36: The license files cleanup dialog
As the number of active and inactive users changes from time to time the
button "Refresh" can be used to get the current number. The "License
Viewer" button opens the license viewer for the current license file.
When you are sure that all inactive users that are shown in the dialog can be
removed, use the Delete all inactive users from license file button. After
that the licenses can be used again.
SimulationX 3 2-33
2.10 Licensing modules

This is only possible with network licenses with more than one license for the
edition module (Professional or Analyzer).
This license files not only can manage multiple users at once, but can also release
unused modules and libraries.
When using such a file SimulationX lets the user decide which modules are to be
used before starting. That way it is possible, that they are still available to
subsequent users.
2.10.1 Module Selection Dialog

Some libraries depend on others; please note that, when deselecting modules.
Below the table missing libraries are listed, which are required when using the
selected libraries. To aid with solving issues with missing modules there are two
buttons, which are able to solve this automatically.
Figure 2.37: List of missing libraries in the module selection dialog
Add missing modules adds as few missing modules as possible until there are no
conflicts left. In many cases this solution is not unique. Is not satisfactory your
selection, you can still change the selection as required.
2-34 SimulationX 3
Managing license configurations
Remove conflicting modules removes the modules, which require other modules,
which are currently not checked or unavailable.
To speed up finding the modules you need, you can enter parts of the module
name, its description or the type ID of a component it contains in the search text
field to filter the list by these criteria.
After you are done with the configuration, SimulationX starts in the usual manner.
Additionally the user can decide if he wants to decide on which modules to use on
every launch or if the dialog is to be skipped in the future.
2.11 Managing license configurations
All relevant settings made by the user regarding the license can be exported to a
file and be imported in several ways. That is information on:
the edition (see 2.2)
the dongle in use
the license file in use
skipping the license file/dongle/module selection dialogs at program start
license usage log
the selected modules
To create such a file open the settings dialog via the menu Extras/Options. On the
page License click the button Save as XML .... After confirming the message box
summarizing the settings to be exported, the file location is chosen.
Now the file can be reused in several ways:

1. The value ConfigFile in the key
HKEY_LOCAL_MACHINE\SOFTWARE\ESI Group\SimulationX
3.8\License in the Windows registry contains the string value with the path to
the configuration file. Then the settings apply to all users on this computer and
the user cannot change anything on the license settings page in SimulationX.
Please note, that on a 64 bit Windows the relevant key for the 32 bit version of
SimulationX is
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ESI
Group\SimulationX 3.8\License.
2. The parameter /config:X:\path\config.xml containing the path to the
configuration file is passed to SimulationX through the command line in a batch
file, the Windows command line dialog or the link target string of a program
link. If the user changes anything on the license settings page, he is prompted to
confirm saving the changes to the file, so they come into effect after restarting
SimulationX with the same parameters. Only write-protecting the file will keep
it from being overwritten.
SimulationX 3 2-35
3. The license configuration file is placed under

C:\Users\Username\Documents\SimulationX 3.8\Settings\licenseConfig.xml
and applies only to this user. Changes made on the license settings page are
stored without prompting.
4. The license configuration file is placed under
C:\Users\Public\Documents\SimulationX 3.8\Settings\licenseConfig.xml and
applies to all users on this computer. Changes made on the license settings page
are again stored without prompting an effect all users.
On every start of SimulationX this sequence is checked exactly in this order to

determine which settings to use for the license. If there exists no registry key in
HKEY_LOCAL_MACHINE, the /config:-parameter is missing and there is no
licenseConfig.xml found neither in the current users documents and the public
documents SimulationX is started in the same configuration as before.
Figure 2.38: Summary of license relevant settings
2.12 Working with Codemeter Licenses

CodeMeter is a technology for software protection by WIBU SYSTEMS. It is
available both as hardware protection (CmDongle) and as license file
(CmActLicense). In terms of functionality, they are both identical. The CodeMeter
control center is used for license management purposes on the user/client machine.
Local licenses on the client computer are managed through the CodeMeter control
center. The licenses there are labeled CmContainer.
If the CodeMeter Runtime is missing on the computer, it can installed by the

maintenance dialog (cf. 2.3.2) of SimulationX. After the Setup is completed, you
will then see a new Icon among the notifications in your taskbar. This is the
CodeMeter Control Center, which is used to configure the CodeMeter License
Server locally and to connect to CodeMeter licenses, called CmContainers, locally
2-36 SimulationX 3
Working with Codemeter Licenses
or in the network. CodeMeter Runtime installation programs are available for both
32-bit and 64-bit Windows.
Alternatively, the CodeMeter Runtime also can be downloaded from our Customer
Center (https://www.simulationx.com/customer-center.html), for example, for an
installation on a server.
The CodeMeter network server runs in the background and must be started
manually upon the installation. To do that, go to
http://localhost:22350/ConfigServer.html and tick the checkbox Run network
server.
Figure 2.39: Codemeter Netzwerk Server aktivieren
2.12.1 Licenses with CmDongle (Cm USB Stick)
Vendor ITI GmbH

FSB File Security Box
(Master Key)
Customer User
WibuCmRaC License
Request File
WibuCmRaU License
Update File
Source: WIBU-SYSTEMS AG CodeMeter Developers

Manual, Version 5.30, Figure 13, page 28
SimulationX 3 2-37
Figure 2.40: Generation of license for CmDongle
The user receives a CmDongle from ESI ITI. This can be used immediately.
If the CmDongle be updated (extension of the use period or adding modules), so a

license request by CodeMeter Control Center is necessary. The request contains all
necessary data about the client machine for the license update. Based on the
provided information, ESI ITI generates a license file and sends it over to the user.
The user then imports the license information from the file and transfers it onto the
CmDongle through the CodeMeter Control Center.
For using CmDongles in SimulationX, please refer to section 2.7.
2.12.2 Licenses with License file (CmActLicense)

The user receives an empty container file (LIF License Information File). The
license is requested through the CodeMeter Control Center. The request contains
all necessary data about the client machine for the license update.
Based on the provided information, ESI ITI generates a license file and sends it
over to the user.
The user then imports the license information from the file and transfers it into the
container file through the CodeMeter Control Center.
Vendor ITI GmbH

FSB File Security Box
(Master Key)
Customer User
WibuCmRaC- License
Request File
WibuCmRaU License
Update File
Source: WIBU Systems AG
Source: WIBU-SYSTEMS AG CodeMeter Developers

Manual, Version 5.30, Figure 6, page 30
Figure 2.41: Generation of a license file (CmActLicense)
For using CmActLicense in SimulationX, please refer to section 2.8.
2-38 SimulationX 3
2.12.3 The CodeMeter Control Center
By clicking on the icon on the taskbar, you can open

the CodeMeter control center.
Figure 2.42: CodeMeter Control Center
Overview of the status display in the control center and the taskbar:
Color State
Grey No CmContainer is connected, or CodeMeter License Server
is not started.
Green An activated CmContainer is connected.
SimulationX 3 2-39
Blue double Several CmContainer are connected and activated until

disconnected.
Yellow A CmDongle is connected and activated until it is
disconnected.
Red A deactivated CmContainer is connected.
By Clicking of the button WebAdmin or right-click on this Icon pops up a

context menu and the entry WebAdmin takes you to a configuration page. By this
page you can administrate the licenses (CmDongle or CmActLicense).
By navigating to the Home page and clicking on the computer name, you can also
visit configuration pages of other computers in your network.
For more information see the Help page of the CodeMeter WebAdmin.
Figure 2.43: CodeMeter WebAdmin user interface
2.12.3.1 CodeMeter License Request and Update

The CodeMeter control center helps managing license requests, updates and
confirmations, which requires you to open the CodeMeter control center.
2-40 SimulationX 3
Clicking on opens the CodeMeter Field Activation Service (CmFAS).
Figure 2.44: CodeMeter FAS
The CmFAS Assistant helps you request, update and verify licenses.
When you request a license, a WibuCmRaC file is generated which you then need
to send to support@itisim.com.
Figure 2.45: CmFAS Wizard
Base on this file, ESI ITI will generate a WibuCmRaU update file and sends it
back to you via email. Through the Import function, you can then transfer the file
into the CmContainer.
Upon the successful update, a confirmation is sent to ESI ITI inlcuding the file
support@itisim.com.
SimulationX 3 2-41
Figure 2.46: CodeMeter WebAdmin Lizenzverwaltung
The WebAdmin GUI helps you manage your licenses. The tab Content shows all
existing containers and the content of each license.
2.12.4 Using of CodeMeter Licenses in SimulationX
Figure 2.47: Selection of the desired Edition
2-42 SimulationX 3
Working with FlexLM licenses
When starting SimulationX for the first time you have to choose the edition and
license medium. Whether you are planning to use a Professional or Analyzer
Edition, select the appropriate entry with CmContainer.
The licenses are addressed in the CodeMeter Control Center as container. In the
following dialog (cf. Figure 2.47) select an available container and activate it for
SimulationX to use it.
By default only the local machine is searched for any CodeMeter containers. To
search for containers on a different machine, simply enter its name and click Start
searching now. For an overview over all containers in the entire network simply
leave the text field empty.
For troubleshooting when using CodeMeter licenses please refer to the section
11.2.
Figure 2.48: Dialog for selection of a Container
2.13 Working with FlexLM licenses

No additional software installation is required for the use of FlexLM licenses on an
arbitrary client machine.
To setup a license server you will find the necessary binaries and documentation
either on the installation DVD in the folder FLEXlm or in the customer center
https://www.simulationx.com/customer-center.html.
SimulationX 3 2-43
When starting SimulationX for the first time you have to choose the edition and
license medium you wish to use.
Figure 2.49: Both Professional and Analyzer Edition of SimulationX are available for
being licensed with FlexLM.
The next dialog determines the location of the license within the network. Choose
the option Specify the License Server System and enter the name of the license
server.
Figure 2.50: The FlexNet License Finder helps locating a SimulationX license in the
network.
2-44 SimulationX 3
To prevent entering this information on every start of SimulationX create a file
containing the following information:
SERVER licenseserver 0 27000

USE_SERVER
Replace licenseserver by the correct name of your license server. In some

cases switching to another port different from 27000 can be necessary.
The above file can act as a placeholder for a local machine-bound license file and
forwards all license queries to the server license. There are three locations of
licenses SimulationX checks upon startup:
1. Place the license at C:\flexlm\pam_lmd.lic.
2. Place the path to the license file in the environment variable
PAM_LMD_LICENSE_FILE. This path is checked for a license by all
ESI products.
3. Place the path to the license file in the environment variable
LM_LICENSE_FILE. This path is checked by any software using the
FlexLM license protection.
2.14 License Configuration (for Administrators)
This section deals with the license configuration for each individual user. It should
only be modified by admins or users familiar with registering modules.
2.14.1.1 Configuration Sources

The users settings on which edition and licensing medium to use, and whether to
show license and module selection dialogs at startup, can be stored in the system
registry or in configuration XML files alternatively.
There are 5 different sources, that come along with different rights for the user and
administration options and they are checked in the following order:
1. Check the registry key HKEY_LOCAL_MACHINE\SOFTWARE\ESI

group\SimulationX 3.8\License
(HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ESI
Group\SimulationX 3.8\License for the 32 bit version of SimulationX on a
64 bit Windows), if the string value ConfigFile exists, then use the given
path there to load the configuration file.
Writing to these keys requires admin rights, so this source is convenient for
administrators to set up everything for a certain user.
If the above key does not exist, or the string value is empty, then
2. Check the command line parameters, which were passed along to
SimulationX when it was started. If the parameter /config:"Path\Filename"
was given, use this path to load the configuration file.
This option enables users to place shortcuts on their Desktop or Start Menu
SimulationX 3 2-45
that start a certain edition of SimulationX directly by referencing an

appropriate configuration file.
If no such parameter was given, then

3. Check the folder C:\Users\username\Documents\SimulationX 3.8\Settings.
If there is a licenseConfig.xml file, use it to configure SimulationX.
This option enables different users on the same machine to use different
license settings. Therefore it is equivalent to storing the settings in the
registry, which was the only available configuration option in previous
versions of SimulationX.
If no such file exists, then

4. Check the folder C:\Users\Public\Documents\SimulationX 3.8\Settings. If
there is a licenseConfig.xml file, use it to configure SimulationX.
Placing a configuration file there enables different users on the same
machine to share their license configurations.
If no such file exists, then

5. Read all relevant settings from the registry key
HKEY_CURRENT_USER\Software\ESI Group\SimulationX 3.8\License.
The configuration settings are loaded as well as stored in these locations.

In case a multi-user license file or CodeMeter container from the network is used,
the set of modules to be available to SimulationX can be configured as well. But
this information is stored in configuration XML files only, so if the user started
SimulationX with license settings from the HKEY_CURRENT_USER registry
the current configuration and the currently selected set of modules is written to
C:\Users\Public\Documents\SimulationX 3.8\Settings\licenseConfig.xml and this
file is used for storing the license settings from then on.
In any other case, the license configuration source is not changed during the
runtime of SimulationX.
2.14.1.2 Write-protection
Depending on the source of the configuration there come along user rights for
changing the settings:
Source Changes allowed Inquire the user before

overwriting
HKEY_LOCAL_MACHINE No unnecessary
Command line Yes (except file is Yes
write-protected)
2-46 SimulationX 3
License Configuration (for Administrators)
User Documents No
Public Documents No
HKEY_CURRENT_USER Yes No
So if the user is allowed to change the licensing settings, he or she can change the
edition and the license medium or add modules. Conversely using a write-
protected configuration file referenced under the HKEY_LOCAL_MACHINE key
is the only way to keep the user from changing these settings.
The user is notified about the inability to store modified settings in write-protected
files just before trying to write them to the file system. The modified settings are
still kept in the memory of SimulationX and the user is allowed to change these
settings further. They are just not stored but reset after a restart of SimulationX.
This is relevant when the configuration dialogs are suppressed at startup, but there
are problems obtaining a valid license from the configured medium or when trying
to load corrupt configuration files.
2.14.1.3 Configuration examples

If the configuration file given in the HKEY_LOCAL_MACHINE key was
not found or is corrupt SimulationX is stopped after giving detailed
informations on the occurred problems. In this context the user has no rights
to do anything about this.
If the configuration file passed along via command line parameters is not
found, SimulationX is started with a default configuration. It is then stored
under the given path, once the user changes any license related setting.
If there are problems accessing the configured license medium, but the
respective selection dialog is suppressed, SimulationX is stopped after giving
detailed informations on the specific problems. But in the case, where user is
allowed to modify license settings and the medium selection dialog is not
suppressed at startup, the medium can be changed in the dialog.
Modifications to the settings in a write-protected configuration file apply as
long as the instance of SimulationX remains open. They are discarded once
SimulationX is closed. This is the same behavior as if the user denies the
inquiry to overwrite a configuration file passed along via command line
parameters.
2.14.1.4 Creating license configuration files

Files, which can be referenced for configuration, can be created in the SimulationX
Settings dialog. Navigate to the Licensing tab in the menu Extras->Options
and click Save as XML. The generated file will contain a snapshot of the
current licensing settings, which can be used to restore the current state.
Advanced users can also edit the generated XML files safely as they prefer.
Configuration files are always validated before use during startup and any
problems are reported to the user.
SimulationX 3 2-47
2-48 SimulationX 3
by
Getting Started
Working with Sample Models
3 Getting Started
In this chapter, we want to make it easy for you to begin working with
SimulationX. The focus will be on using the provided example models, although
the instructions still apply generally. The structure of a model will be explained
step-by-step using the example Two-Mass-Oscillator.
For many actions there are several different ways to carry them out. In this
introduction only one method will be demonstrated and used. In chapter 5
Modeling you can read in detail about the modeling process. The terms used in
the following chapter can be found in chapter 12 Definitions.
3.1 Working with Sample Models

With the installation of SimulationX, you also received a collection of example
models. It is possible to open these models, change parameters and run
simulations. You will find the example models in the directory
(C:\Users\Public\Public Documents\SimulationX 3.7\ Samples).
The welcome page when starting SimulationX enables direct access to the
examples.
You are able to see examples which contain elements not included in your licensed
libraries using the Viewer Edition. Switching into the Viewer edition is described
in section 2.2.8.
SimulationX 3 3-1
User Manual 3. Getting Started
3.1.1 Opening a Model File
To open an example file, click on the button or select File Open...".
To open an existing model:

1. In the menu, select File > Open.
2. Navigate to the model directory, select the desired model and click Open.
After opening, the model structure and a model description will appear on the
screen, as well as some result window with previously calculated curves.
Additionally, data sheets, basic data and explaining illustrations are contained
within the examples.
3.1.2 Changing Parameters

If the model has already been simulated, you should first reset the simulation by
clicking on the button or selecting Simulation Reset to Start.
Now you can double-click on the symbol of any element in order to open the
corresponding parameter dialog. For each parameter in SimulationX, you can
enter constant numerical values, mathematical expressions and/or logical
conditions.
Figure 3.1: Parameter dialog
To change parameters of an element:

1. Double-click on an element. The properties dialog opens.
2. Select the tab Parameters.
3. Change the value or the unit of a parameter.
4. Clicking outside of the input field assigns the value to the parameter.
3-2 SimulationX 3
Working with Sample Models
For detailed information about the elements (parameters, result variables,

assumptions and calculation) you can press the Help button. The online help
system will appear which provides the required information. For entering numbers
into the parameter fields, select the desired unit first and then enter the numerical
value. The parameter value will be automatically updated if you change the unit
afterwards.
In order to save simulation results for later display, you should activate the
protocol attribute for the desired result variables.
Figure 3.2: Result Variables Dialog
To activate a protocol attribute:

1. Double click on an element. The properties dialog opens.
2. Select the tab Results.
3. Click on the symbol of the protocol attributes to switch it on /off .
Close the parameter dialog with OK.
3.1.3 Running a Simulation

Start the simulation by clicking on the button or selecting Simulation>Start.
The simulation will now run up to the specified stop time. You can observe the
current simulation time in the lower right corner ( ).
To change the preset value of the stop time, open the simulation control panel by
selecting Simulation>Options... on the menu bar. Now you can edit the
simulation parameters (e.g. tStop).
3.1.4 Opening a Result Window

If you have activated the protocol attribute ( ) for result quantities before
running the simulation, you can now plot these result as y = f(t) diagrams.
SimulationX 3 3-3
To open a result window:

1. Click with the right mouse button on an element.
2. Select under Results (transient) the desired variable.
If no result variables are available for a model element, likely no protocol

attributes have been activated ( ).
The work with result windows is described in detail in section 7.3 "Result
Windows".
You can display several result curves in one window using Drag-and-Drop. A y(x)
plot is possible by clicking on the button within the result window.
3.2 Creating your own Model
In the following sections, the simple model Two-Mass Oscillator will be
developed. The individual steps are explained, and references are provided to more
detailed explanations in following chapters.
When creating your own model, you should always start with a new
file (button or menu File New). Then proceed as follows:
3.2.1 Selecting Elements
Figure 3.3: Library Bar and the Model
On the left side of the screen you will see the library bar (Figure 3.3). Sub-libraries
can be opened by clicking on the arrow. Using Drag-and-Drop, the elements can
be placed in the diagram view (more information in section 5.2.3).
The elements of the model are still movable, i.e. they can be shifted, turned and
tilted. Select an element by clicking on it. It can be shifted by dragging it across the
work space with the mouse, or using the arrow keys. Using the tools you
can rotate the element, and using the element can be horizontally or
vertically tilted. In this way you can move the element to the desired position and
orientation for the following connections.
3-4 SimulationX 3
Creating your own Model
Figure 3.4: Property Dialog
Within the General tab of the property dialog, it is possible to enter comments
for the element, or change the position and orientation of the label (s. Figure 3.4).
Task:
From the library Linear Mechanics, select two masses (mass1, mass2) and a
spring-damper element (springDamper1) and place these in the diagram view.
element connectors
Figure 3.5: Model
3.2.2 Connecting Elements

The next step is to connect the elements in order to obtain the desired model
structure.
Task:
Connect the two masses with the spring damper element according to the following
structure.
Figure 3.6: Model Structure
SimulationX 3 3-5
The procedure of connecting elements is described in detail in section 5.2.3 and

will be explained here only briefly:
Select the port (pin) of the element that you would like to connect by hovering
with the mouse pointer over it (red pin signals - connector found).
Create the connection by pressing the left mouse button and drawing towards
the other element.
Once the port of the next element has been reached (visible as a black point),
release the mouse button and the connection will be created.
Please note the fact that only elements within the same physical domain can be
connected (e.g. mechanical spring not compatible with hydraulic throttle). In this
case, no connection structure at the other element occurs.
3.2.3 Entering Parameters

In order to be able to work with our model, the input of the desired parameters for
the elements is necessary.
Task:
Enter the following parameters:
mass1 Mass m 250 g

Initial displacement x0 5 mm
mass2 Mass m 2 kg
springDamper1 Kind Spring-Damper
Stiffness of Contact k 0.25 N/mm
Damping of Contact b 2 Ns/m
Table 3.1: Parameters of the Elements
You can do this by using the property dialog of an element (double click on it) or
by using the Model Explorer. After clicking on an element, its parameters appear
in the Model Explorer.
tree
view
Figure 3.7: Parameters of mass1 in Model Explorer
3-6 SimulationX 3
After clicking on an element, all parameters are available to be edited in the top
part of the Model Explorer (s. Figure 3.7), and in the lower part the result
variables are available.
Please note that a dot is always used as the decimal separator (no comma!).
Protocol attributes ( ) for the result variables can also be activated via the
Model Explorer, so that they can be plotted during or after the simulation.
Activate protocol attributes for the following result variables:
mass1 Displacement.x
mass2 Displacement.x
springDamper1 Internal Force.Fi
springDamper1 Displacement Difference.dx
3.2.4 Transient Simulation in the Time Domain

With the prepared sample model you can do all computations implemented in
SimulationX (see Chapter 7):
Simulation in the time domain
Computation of the equilibrium
Linear model analysis (natural frequencies and mode shapes)
Figure 3.8: Property Window "Simulation"
SimulationX 3 3-7
We will limit the following analysis to simulation in the time domain. Figure 3.8
shows the dialog for the simulation control.
The simulation can be started using the menu Simulation Start or with the
button in the tool bar. The computation takes place up to the given stop time.
The preset value is 1 second.
Using the button you can end the simulations run. The button resets the
model to the start.
In order to modify the value for the stop time, open the dialog for the simulation
control (menu Simulation Properties).
3.2.5 Displaying Results

We will now describe plotting simulation results.
Task:
Plot the result variable Mass1.x in a y=f(t) diagram.
In order to display the appropriate result window, we use the Drag-and-Drop

function as described in section 7.3.3.
Select the element mass1 in the diagram view by clicking with the mouse. In the
Model Explorer the available result variables will be indicated. Click the protocol
attribute for the displacement of mass1 with the left mouse button and pull it via
Drag-and-Drop into the diagram view. After releasing the mouse button, the result
window becomes visible.
Figure 3.9: Result Window of Mass1.x
Plotting multiple result variables within the same result window is also possible.
3-8 SimulationX 3
Task:
Plot the result variable mass2.x in the existing result window as well.
Figure 3.10: Result Window with Multiple Curves
Select the element mass2 in the diagram view and drag the protocol attribute
for the displacement using Drag-and-Drop into the existing result window. It will
be displayed as a second curve.
Two result variables can also be plotted in a y(x) diagram. In the following, the
displacement different should be plotted as a function of the internal force.
First the simulation should be reset, and subsequently the protocol attributes for the
result variables displacement difference (dx) and internal power (Fi)
activated. Create a result window in which both of the selected result variables are
plotted. After a new simulation run, switch into the y(x) representation using the
button in the result window tool bar.
Figure 3.11: Result Window with a y(x)-Representation
SimulationX 3 3-9
At this point you can reset the simulation with the button , make parameter or
structural changes in the model, and start the simulation again. When resetting the
simulation, all result curves will be removed.
Note: If you freeze the result curve with the button before resetting, then the
original curve remains visible in the window. The effect of parameter changes can
be seen by direct comparison after running the simulation again.
3.2.6 Steady State Simulation in the Frequency Domain

The following two sections guide you through running steady state simulations by
means of a simple example.
3.2.6.1 Steady State Simulation of a Powertrain

First create the powertrain model from Figure 3.12. Have a look in sections 3.2.1
to 3.2.3 if you need help with the basic steps for model construction.
Figure 3.12: SimulationX model of a simple powertrain for the steady state simulation
The model parameters you need to modify are collected in Table 3.2.
springDamper1 Properties kind Spring-Damper

Stiffness of Contact k 20000 Nm/rad
Damping of Contact b 10 Nms/rad
source1 Torque T see below N
Table 3.2: Powertrain Parameters to be Changed
The following value of the excitation torque is input in the properties dialog
of source1:
source1.T = 1000*exp(-10*(cos(0.5* in1)+1))
The corresponding torque waveform is shown in Figure 3.13. It is periodic with

two turns of the shaft as is the case for a 4-cycle engine.
3-10 SimulationX 3
The torque source source2 serves for the compensation of the average drive torque
of source1. This makes sure that the mean angular velocity of the drive train keeps
constant and a steady state solution is possible. You do not need to modify the
parameter Torque of source2. The employed harmonic balance algorithm
calculates the necessary compensation torque by itself.
Figure 3.13: Excitation Torque of the Simple Powertrain
Before running the steady state simulation you should activate the protocol
attributes of the result variables of interest. The procedure to activate protocol
variables is briefly described in section 3.1.2. For the current application example
the following result variables are needed:
the acceleration torque Ta of inertia1,
the angular velocity om of inertia1.
Set the multiple-choice box in the toolbar to Steady State and open the
Property Dialog for the steady state simulation by clicking on the symbol in
the toolbar or by clicking on Steady State Settings in the Simulation menu.
In this example you only need to set some parameters on the System page of the
property dialog for the Steady State Simulation. This page is shown in Figure
3.14.
Please choose the angular velocity of inertia1.om from the multiple-choice

box for the Reference Quantity and input 100rad/s and 300rad/s as Start and Stop
values, respectively, for this reference variable. These values determine the range
of mean angular velocities of intertia1 for which the steady states should be
computed.
SimulationX 3 3-11
Figure 3.14: Property Dialog for Steady State Simulation
When choosing the angular velocity inertia1.om as the reference quantity, the
angle inertia1.phi is automatically selected by default as Period Variable.
You can retain the default value 4 for the Period of the period variable since the
excitation torque is 4 -periodic in inertia1.phi. You can also keep the values for
the Fundamental Order and the Maximal Order.
The fundamental order 0.5 is assigned to the oscillation with the given period
length 4 the oscillation of first order then has the period length 2 and so on.
Choose Source2.T as the compensation parameter. As already stated, the

harmonic balance adjusts the compensation parameter such that the angular
velocity averaged over one period stays constant.
After entering all required Simulation parameters you may start the steady state
simulation by pressing the button or by clicking on Start in the Simulation
menu.
You can already watch the evolving results during the simulation. Open the
context menu of intertia1 with a right mouse click on intertia1 and select in the
3-12 SimulationX 3
submenu Results (Steady State) the item Angular Speed om (see Figure 3.15). This
opens the steady state result window intertia1.om (see Figure 3.16).
Figure 3.15: Selection of a recorded result variable for the steady state simulation
When the result window opens, the Spectra representation of the signal is shown.
With the checkboxes , individual curves of the result window may be switched
on or off. For the angular speed of rotational masses the Fluctuation Coefficient is
shown by default. Alternatively, you may select the Amplitude, Excitation, Phase,
Real Part, or Imaginary Part representation.
Figure 3.16: Result Window for inertia1.om
SimulationX 3 3-13
The tabs Spectra Signal at the lower right corner switch the result window
from Spectra view to Signal view and back.
The signal view of the result window is shown in Figure 3.17.
The multiple choice box in the upper right corner offers the representation of the
Deflection, Deflection+Mean Value, and Fluctuation. The default representation
for the angular speed of rotational masses is the fluctuation.
With the slider, the reference value for which the signal is plotted over the period
variable can be changed. Alternatively, you may input the desired value into the
text field and then click the button Apply or press the Return button.
Figure 3.17: Representation of inertia1.om over the Period Variable (intertia1.phi)
3-14 SimulationX 3
ITI SimulationX for Complete System Modeling and Analysis
3.3 ITI SimulationX for Complete System Modeling and

Analysis
Use the many possibilities of SimulationX for a fast and efficient modeling
solution, as well as for the evaluation and optimization of technical systems:
Transient or steady state simulation (cf. 6.1 and 6.3)

Automated Parameter Studies (button or menu Analysis Variants
Assistant ... , cf. 6.6)
Linear system analysis: Analyze Natural Frequencies and Mode Shapes of your
system (button or menu Analysis Natural Frequencies ..., cf. 6.5.1)
Linear system analysis: Input-Output Analysis (button or menu Analysis
Input-Output Analysis, cf. 6.5.2)
Analyze the flow of power and energy in a SimulationX model Power
Balance , cf. 6.8
Extend existing elements (button or menu Elements Extension, cf.
8.2.3)
Create compounds (button or menu Elements Compound, cf. 8.2.4)
Use the TypeDesigner/FluidDesigner for creating your own element types and
fluids (cf. section 8.3)
Implement your own user-specific algorithms (cf. 8.2.6)
Co-simulation...(see 9.3)
Code Export (button or menu Export) for accelerated simulation
(executable model) or model integration (see section 9.4)
SimulationX 3 3-15
3-16 SimulationX 3
by
Graphical User Interface

Overview
4 Graphical User Interface (GUI)

4.1 Overview
The working area of ITI SimulationX can be subdivided into different windows
and areas.
2 3 4
7
Figure 4.1: SimulationX working area:

(1) Menu and Tool bar, (2) Library bar, (3) Diagram view
(4) 3D view, (5) Model explorer, (6) Output area,
(7) Result window manager, (8) Find and Replace
The SimulationX program interface contains two main window types:

Tool window
Document window
These two window types show slight differences in their behavior.
4.1.1 Tool Window

The tool windows are listed in the menu View and can be displayed in several
ways:
Automatically displayed or hidden
Docked to the edges of the SimulationX program interface
Non-docked (floating)
SimulationX 3 4-1
User Manual 4. Graphical User Interface (GUI)
4.1.2 Document Window

Document windows are created dynamically when you open or create models. The
list of the opened document windows is displayed in the Windows menu. Tab
groups allow using the restricted workspace better when you work with two or
more opened model views. You can combine several document windows into
vertical or horizontal tab groups and also shift views from one tab group into
another one easily.
Further customizations can be made via the menu View. Here you can change to
full-screen mode which uses the whole screen for the display of the document
window.
4.2 Operating
4.2.1 Menu Bars and Toolbars
The menu bars and toolbars (1) permit access to all tools and commands of
SimulationX. You can change the layout, the position and the contents of toolbars.
You can add buttons to the toolbars and change the assigned icon for any button.
How to add a new toolbar
1. In the menu Extras click Customize.
2. In the dialog field Customize select the tab Toolbars.
3. Select New.
4. In the dialog field New toolbar enter a name for Toolbar.
5. Click OK.
How to add a button to the toolbar
3. Select the toolbar you wish to adapt and activate it.
4. Select the tab Commands.
5. In Categories go to the category which contains the command that you
want to add to the toolbar.
6. In Commands select an element.
7. Under Commands drag the element from the dialog field Customize to
the desired toolbar.
8. When the mouse shows a plus sign (+) drops the element on the toolbar.
How to change icons for toolbar buttons
4-2 SimulationX 3
Operating
3. Select the toolbar with the icon you want to change and activate it.
4. With the dialog field Customize open click the button you want to
change. A black square or rectangle indicates that the button has been
marked for editing.
6. Select Change selection.
7. Select "Change icon" and subsequently select the desired icon in the
submenu. If the available icons do not suit your preferences you can
customize a selected icon of the system.
How to edit icons
3. Select the toolbar with the icon you want to change and activate it.
4. With the dialog field Customize open click the button you want to
change. A black square or rectangle indicates that the button has been
marked for editing.
6. Select Change selection.
7. Select Change icon.
8. In the dialog field Icon editor customize the icon for the selected button.
In the dialog field Customize you can also customize menus.
4.2.2 Library Bar

The library bar (2) serves for selection, management and editing of element types.
Logically related element types are combined in groups which are structured
hierarchically and displayed in a tree view similar to the folder view in Windows
Explorer. The folders contained in the library bar can be subdivided into the
following groups:
Favorites
The favorites bar can extend the library bar or even replace it if configured
accordingly. The folder Favorites which used to be part of the library bar in
SimulationX up to version 3.7 has been moved to the new favorites bar. Favorites
can be set as usual by dragging and dropping individual types or entire packages.
The favorites bar can be enabled or disabled from the View menu.
SimulationX 3 4-3
You can store links to frequently used element

types or libraries under Favorites by
Drag-and-Drop. Creating new groups permits
the creation of a customized folder structure
independently of the actual name hierarchy of
the contained element types. The contents of
the Favorites folder are stored individually for
every user in the file usersettings.mo in the
directory for the user data of the user (e.g.
C:\Users\<user>\ AppData\Roaming\ITI
GmbH\ SimulationX 3.8).
SimulationX Libraries
All libraries and element types licensed and

contained in the SimulationX scope of delivery
are shown in these folders. The element types
contained here can neither be changed nor
deleted. You can transfer the properties of an
element type to a new element type though by
creating a derivative of the existing type (see
8.2.3). The new element which has been
created in this way can be edited in
TypeDesigner. If a certain SimulationX library
is not required it can be excluded from
automatic loading at the program start.
How to exclude a library from the automatic loading at the program start:
1. In the menu Extras click Options.
2. In the dialog field Options select the tab Libraries & Add-ons.
3. Remove the selection mark for the library which you want to exclude from the
automatic loading at the program start.
4-4 SimulationX 3
Operating
Modelica Standard Library
You will find the contents of the Modelica

Standard Library in this folder. The Modelica
types contained there can be opened in
TypeDesigner and here you can check the
contained components and the Modelica
source code. However you cannot change or
delete the element types.
For installation hints refer to section 10.2.1.
Other Modelica libraries
In this folder you will find the contents of other

libraries installed under the Modelica search
path. The ITI External Libraries (e.g.
Combustion Engines, synchronizer) belongs
also to this category.
The groups and element types contained in this

folder can be renamed, moved by Drag-and-
Drop or copied, edited in TypeDesigner or
even deleted. You can expand the libraries by
new types. You create a new Modelica library
by highlighting the root entry "ITI
SimulationX" in the tree view of the library bar
and add "Package" as a new Modelica class via
the selection box in the toolbar or the context
menu. The TypeDesigner is opened
automatically for further editing of the
package. The created package can be extended
by new Modelica classes in the same way.
User-defined types
New groups, element types or other Modelica classes are created by first selecting
in the tree view of the library bar the group which is to contain the newly to be
created type. The desired type can be added via the context menu then. For further
SimulationX 3 4-5
editing the TypeDesigner is opened (see section 8.2) or, in the case of a newly
created group, a corresponding dialog field is displayed.
4.2.2.1 General Information about the Library Bar

By default the comment is displayed as the label of the individual entries in the
tree view. This comment is displayed for the SimulationX libraries in the selected
language (German or English).
For the elements of the Modelica Standard Library in contrast the name of the type
is displayed instead of the comment.
By the button you can change the display of the symbols and the behavior
when double-clicking on them.
Figure 4.2: Settings of the Library Bar
In the toolbar of the library bar there is an input field for the search for element
types. After the button Search has been pushed the program starts searching the
tree view for the input character string starting with the currently selected element
type. In the search both the name and the comment of the types are included. When
the search has been successful the found entry is selected. By pushing the Search
button again the search can continue.
By the button the view of the library bar can be adjusted by sorting or
filtering.
The icons of the element types in the tree view can be highlighted specifically by
an additional marking:
4-6 SimulationX 3
Operating
Storing the element type as a file

The element type is stored as a file. Further types contained in this type are
also stored in this file. The corresponding file name is found in the preview
window at the bottom of the library bar.
Storing of a group or package as a directory

The package or the group is stored as a package.mo file in a separate
directory. The types declared within this package can be stored in separate
files or within the actual package.mo file. Packages which are contained
within this package can also be stored as a directory.
Coded element type or group

The element type is coded and can only be edited after the correct password
has been entered. Different Modelica tools use different coding methods in
general.
Blocked element type or Modelica class

The element type or Modelica class is opened in TypeDesigner or the
diagram view. Further editing is only possible after TypeDesigner or the
respective diagram view has been closed.
The following commands are available via a context menu for the selected entry of
the tree view. The icons given at the edge inform to which element types the
respective command can be applied on principle. The applicability of a command
can depend on further conditions which will be mentioned specifically in the text.
New...
Use this command to create a new type of the specified Modelica class. The
commands Model, Connector, Block, Function and Package are
available to create user-defined types. The newly created type is opened for editing
in TypeDesigner. Name and comment and, if required, the respective target
directory have to be input in a dialog field for a newly created group. This can be
edited like a Modelica package in TypeDesigner later.
Delete
Use this command to delete the selected type including the types contained in it.
Note that the file or the directory where the respective type is stored will also be
deleted then. A corresponding warning has to be confirmed prior to the deletion. If
the type is to be removed from the tree view only temporarily, the command
Unload can be used.
Duplicate.
SimulationX 3 4-7
This function creates a copy of the selected type. In the following dialog is type-
name and target package of the copy can be specified. If the destination is the same
package is assigned to another name.
Open
Select this command to edit the model of the selected type in the TypeDesigner,
diagram view, text view, 3D view or to open the documentation view. As long as
the diagram view is open the respective type remains blocked for further editing.
Modelica Standard Library types can be opened but not stored.
Not all features are available for any type.
Note the reference in section 7.6.5.
New Version...
Use this command to create a new version of the selected type. The newly created
version substitutes the basic type in the library view. The basic version remains
available though. Models which use a type for which several versions are available
use the respective current version by default. However use of a certain version can
also be demanded. The consistent use of versions can help in ensuring the
reproducibility of computation results because models can be developed in this
way which remains unaffected from later changes to the basic types.
New Derivative...
With this command you can create a derivative of the selected type. Derivatives
permit the extension of existing element types by, for instance, an additional
connector or parameter. However you cannot change the behavior of the element
fundamentally with a derivation.
Reload
Use this command to load anew a group of element types starting with the selected
type. This can be necessary if you have modified a mo-file outside SimulationX
and want to apply these changes in SimulationX. Note that all opened models must
4-8 SimulationX 3
Operating
be closed before you execute this command. Model changes can be stored in this
process.
Unload
To save storage space or to reduce the size of the library bar you can unload
individual types or groups of types. In contrast to deletion files or directories will
not be deleted in this process. The respective types will be available again upon
restart or execution of the command Reload. Note that all opened models must
be closed before you execute this command. Model changes can be stored in this
process.
SVN Update
Use this command to update your local copy of a particular package or type (see
section 4.2.3).
SVN Commit
Use this command to submit all changes made to the package or type to the
repository (see section 4.2.3).
TortoiseSVN
This context menu holds additional options for version management. See section
4.2.3 for more details.
Expand/Collapse
Use this command to expand or collapse the tree view for the selected entry.
Samples
This command initiates a search for examples in the Sample Browser containing
the selected type.
Help
Use this command to open the Help for the selected type. Alternatively, press F1.
Drag-and-Drop
Element types can be copied or shifted within the library bar and in the tree view
of the model explorer by Drag-and-Drop. Types of the Modelica Standard Library
cannot be shifted. Protected types are excluded from Drag-and- Drop operations as
a matter of principle. To copy or shift such a type you have to remove the
password protection in TypeDesigner first.
Caution:
The Shifting of element types can cause models which use these types to be no
longer loadable. Therefore you should use this option only in rare cases.
SimulationX 3 4-9
At the bottom of the library bar a preview picture and some useful information
regarding the entry which you selected in the tree view are displayed in a small
separate window area. Via a hyperlink the directory which contains the file
belonging to the respective type can be opened in Windows Explorer.
4.2.3 Managing Different Versions of Packages and Types with

Apache Subversion
Version management with Subversion (SVN) provides full control over all changes
made to libraries and their many packages and types. Changes can be undone or
merged with other users modifications. SimulationX relies on a well proven open
source solution. Apache Subversion (SVN) is free software for organizing different
versions of files and directories. TortoiseSVN, a convenient client for Windows,
adds to the functionality of SVN by providing a graphical user interface.
Requirements
- Microsoft Windows OS (Windows Vista or later), 32 or 64 bit
- TortoiseSVN must be installed
During the installation of TortoiseSVN, the

Subversion command line option must be selected.
After the installation is complete, it may be
necessary to restart the computer in order for
SimulationX to recognize all system changes.
Settings
Version management with Subversion SVN can be enabled on the Storing page in
the Options dialog (under Extras in the menu bar). The context menu in the
SimulationX library bar provides the following commands for the work with SVN:
SVN Update
Use this command to update your local copy of a particular package or type. Files
from the repository that are newer than your local copies are downloaded to your
computer. Changes you may have made already in your local copy will not get
lost. The program tries to merge your changes with the version from the repository.
Occurring conflicts are flagged up. Once the update process is complete,
SimulationX reloads the affected types.
SVN Commit
Use this command to submit all changes made to the package or type to the
repository. All modified files are listed in a window. You can add comments to the
revised version (log entry) in order to track the version history later.
4-10 SimulationX 3
Operating
Difference
This command looks for changes in your local copy compared to the latest version
in the repository. Differences between both files are shown and highlighted in a
separate window.
Show Log
Use this command to view the version history. A separate window shows all
exchanges for a particular package or type including all comments.
Add
Use this command to add a type or package to the repository. That requires the
superordinate type or package to be part of the repository already. If that is not the
case, new types and packages can be included in the version management by
clicking Add to Existing Repository or Add to Existing Repository.
Remove
This command removes the selected type or package from the repository. All
associated files remain on your local drive. Deleting a type removes all associated
files from your local drive and the repository.
Revert
This command undoes all local changes and updates your local copy with a version
from the repository, the basis for your changes. All changes in the selected file that
were not submitted to the repository get lost.
Resolve conflict
During the update process, merging various changes may cause conflicts. These
conflicts must first be resolved. This can be done manually or through the
corresponding tool in TortoiseSVN. Once all necessary changes are applied, you
can update the files status with this command.
Add to Existing Repository

This command allows you to add an entire package to an already existing
repository. The repository may exist on a local drive or on a server. This command
is only available for top-level packages that were saved as directories.
Add to New Local Repository

This command allows you to add an entire package to a new local repository. You
have to specify the path to the repository first. This command is only available for
top-level packages that were saved as directories.
Repository Browser
Choose this command to browse the repository.
SimulationX 3 4-11
Show Version Information in the Library Bar

The current status of packages and types is indicated by small icons in the library
bar.
The package/type is not managed by SVN.
The package/type is managed by SVN. There are no changes.
The package/type is managed by SVN. There are changes that have

not yet been submitted to the repository. This status is also shown if a
type was not modified, but one of the types they contain.
The package/type was added to the repository. The repository has not
yet been updated.
The package/type was removed from the repository. The repository
has not yet been updated.
Merging different package/type versions caused a conflict.
4.2.4 Diagram View, 3D View, Text View and Documentation View

SimulationX supports four types of document windows. The Diagram view (3)
serves for visualization and editing of the logical structure of a model. The 3D
view (4) is used to display elements of the MBS Mechanics library three-
dimensionally and to edit their spatial position interactively. For more information
about 3D view see section 5.4.4.
The Text View can be used for displaying and editing the Modelica code.
The Documentation View shows the content of the model Online Help. This view
serves for model documentation.
4-12 SimulationX 3
Operating
Several views with different settings can simultaneously be opened for a model.
More views are created via the menu Windows.
Right mouse click on a tab opens a popup menu with the following commands:
Create vertical or horizontal

configuration
Go to the previous view
For the splitting in Figure 4.3 a new vertical tab group was added.
Other views are created via the menu Windows.
All settings made are stored together with the model. The views have equal priority
(e.g. only 3D view). This means that animations are also possible without 3D view.
In the properties dialog of the model in the register 3D Settings (dx9) settings to
the representation (colors, grid and other things) can be specified. The button
Save As Default can be used to fix the settings.
SimulationX 3 4-13
Figure 4.3: Vertically split diagram view
4.2.5 Model Explorer

The tree view of the model explorer (cf. Figure 4.4) represents all in the model
used components (1) and types (4). By the button you can filter the entries of
the model explorer.
Settings are stored and are available after a restart of SimulationX again.
For a selected element (e.g. Mass1) or a connection the parameters and result
variables are listed in tabular form, see (2) and (3).
If no model elements have been marked the general parameters and result variables
of the model will be displayed.
1 2
4 3
Figure 4.4: Model Explorer: (1) Components, (2) Parameters Table,

(3) Results Table, (4) Types
The Model Explorer windows can be arranged freely within the SimulationX
workspace. You can also hide views that are not needed.
The tree views, just like the library bars, come with options for sorting and
filtering. Use this feature to hide entries that you do not need.
4-14 SimulationX 3
Operating
4.2.5.1 How to Edit Component Properties

Select the component (element or connection) which you want to edit, either in the
diagram view or in the tree view of the model explorer. A component, selected in
the diagram view, is selected also in the tree view of the model explorer and vice
versa.
For the selected component the related parameters and result variables are shown
in two tables. To edit an entry you click on the desired table field. Now you can
edit the contents of the field or choose an entry from the corresponding selection
list.
As long as the field is edited, the corresponding parameter is not updated. The
transfer of the new value to the parameter takes place only after completion and
validation of the input. For the completion of the input there are the following
possibilities:
Change to another row using the cursor keys and res. a mouse click on the
new field
Press the Return key
Change the focus to another window, e.g. by a click to the diagram view.
Modifications can be undone using the command Undo in the menu
Edit.
By clicking on the header of the parameter or result variable table with the right
mouse button, you can select the columns to be displayed by ticking them
accordingly.
These are the following for parameter tables and result variable tables:
SimulationX 3 4-15
All columns can be shown with ascending/descending sorting order. To this end
click on the corresponding column header and the sorting will proceed. ( -
ascending; - descending).
To toggle the protocol attribute of a result variable click on the corresponding

symbol in the protocol column.
Drag-and-Drop can move activated protocol symbols into the diagram view or an
already opened result window. For this click on the protocol symbol and move it to
the desired place, while keeping the button pressed. When releasing the button, the
result protocol is shown either in a new or in an existing result window.
The current value of a result variable cannot be changed. However, the unit of
measurement, in which the variable should be shown, can be changed.
4.2.5.2 How to Add Parameters and Result Variables

A parameter or a result variable can be added to the current model or to a user-
defined element type as follows:
1. Select the model or an element type defined in the model in the tree view of the
model explorer.
2. Open the context menu in the corresponding table of the model explorer, using
the right mouse button.
3. Choose the item New. The new variable or parameter will be shown in the
table.
4. Name and comment of the new variable or parameter can be edited directly in
the table.
4.2.5.3 How to Remove Parameters and Result Variables

A parameter or a result variable can be removed from the current model or from a
user-defined element type as follows:
1. Select the model or an element type defined in the model in the tree view of the
model explorer.
2. Select the desired parameter or variable in the corresponding table.
3. Perform the command Delete from the context menu. The parameter or the
variable will be removed from the table and the model. You can only remove
parameters or variables, which you have added beforehand.
Hint:
You can also use the TypeDesigner to add or to remove parameters or variables.
4-16 SimulationX 3
Operating
4.2.6 Output Area

In the output area (6) messages, tracing outputs, warnings and error messages are
logged. These messages are allocated to different categories (e.g. simulation, file).
The content of the output area can be stored, exported in text format and printed.
For more information about tracing see section 6.1.1.4.
Figure 4.5: Output area
4.2.7 Result Window Manager

The Result window manager (8) facilitates the
central management of the result windows of all -
opened models. Result windows can be hidden or
displayed with a click on the respective icon or
closed by actuation of the respective button on the
icon bar.
The buttons are described under section 7.3.10.2.
By ticking/unticking in the list of the result windows you can display/hide

individual result windows.
4.2.8 Search and Replace

This function is with large models very helpfully for finding types or one of certain
text passages in the text view. By means of Replacing model elements can be
found and renamed.
SimulationX 3 4-17
4-18 SimulationX 3
by
Modeling
Modeling in SimulationX
5 Modeling Fundamentals
5.1 Modeling in SimulationX
SimulationX offers various ways to create models:
Physical object-oriented models
Signal-oriented models
Equation- and algorithm-based models
Thus, users can apply the best suiting modeling approach to their component and
system models and can combine the different approaches within the same
simulation model, so that every component is modeled in the way suiting it best.
The benefits and application areas of each modeling approach are explained in the
sequel.
5.1.1 Physical Object-Oriented Modeling

Physical object-oriented modeling is the natural way to describe any kind of
physical behavior in simulation models. It is also known as network modeling.
SimulationX uses such modeling approaches for all of its physical domains and
libraries.
F F F = 0
x, x&, ...
element
F F F F
element element
Node
Element connector Connection
Figure 5.1: Physical Network Modeling
The concept of network modeling is illustrated in Figure 5.1. Physical network

models are formed of elements, which are interconnected to each other by
connections, also called nodes. In SimulationX, elements are objects found in the
libraries, whereas connections are created when connecting elements to each other.
Physical relationships in network models are formulated in terms of potential and

flow quantities.
In a connection resides a set of potential quantities, which are identical for all
element connectors connected to it. Such potential quantities are, e.g.,
SimulationX 3 5-1
User Manual 5. Modeling Fundamentals
displacements, speeds, and accelerations in mechanics, pressures in fluid libraries,

voltages in electronics, or temperatures in thermal models.
The flow quantities are quantities, for which certain balance equations must be
fulfilled. For instance, forces or torques at connections in mechanics must balance
to zero. The same must hold for currents in electronics and flow quantities in other
physics.
The potential quantities as well as the balance equations for flow quantities, which
belong to a physical domain, are defined in the connections.
Figure 5.2: Physical Network Model from Translatory Mechanics
Elements, .i.e., objects found in the SimulationX libraries or developed by users,

define relationships between the potential quantities at their connectors and their
internal flow quantities. A spring in mechanics for instance relates the internal
force F and the displacement difference dx between its connectors via the
stiffness parameter k by an equation F=k*dx.
5.1.2 Signal-Oriented Modeling

The modeling of signal structures follows a concept different from physical
network models. Signal structures, such as control systems, are information
processing structures. This means, that elements of such structures generate output
data from input data provided to them. Within the models there exists a clearly
defined information flow and causality.
Figure 5.3: Signal-Oriented Model
5-2 SimulationX 3
Creating Models
Signal-oriented models are the appropriate way to model control systems and can
be used as auxiliary structures for computing dependencies in physical libraries.
Figure 5.3 shows a sample for signal-oriented structures.
For connecting physical models to signal-oriented models the SimulationX

libraries for the different physical domains provide sensors, which translate
physical quantities into signals and actuators, which use signals and translate them
into appropriate physical actions (such as, e.g., applied forces or displacements).
Signal-oriented modeling could also be used for the modeling of physical

structures, but this will result in cumbersome modeling and very incomprehensible
models! In fact, Figure 5.2 and Figure 5.3 show the same model, clearly
demonstrating the advantages of physical modeling.
5.1.3 Modeling with Equations and Algorithms

Equations and algorithms in SimulationX use the capabilities of the Modelica
modeling language, which is an integral part of SimulationX (see chapters 8 and
11).
Equations permit the direct text-based notation of physical relationships in terms of

differential or algebraic sets of equations, which is in particular useful for
customizing SimulationX and developing customer-specific elements with
capabilities beyond the SimulationX standard libraries.
Algorithms provide methods for implementing programmed functionality for

instance in controllers.
The working with algorithms and equations is not covered in this chapter of the
manual. Please refer to chapter 8 for an in-depth introduction into this matter.
5.2 Creating Models

5.2.1 The SimulationX User Interface
The graphical user interface (GUI) is the main interface for building models in
SimulationX. The GUI is parted into several windows, which control the
interaction with SimulationX and which are described in detail in chapter 4.
SimulationX models are assembled by drag-and-drop in the Diagram View, which

is normally found in the center of the SimulationX window. The Library Bar,
typically found on the left of the SimulationX window provides the collection of
element types, which can be used in SimulationX models.
SimulationX 3 5-3
Following functions in the "File" menu are for the handling of SimulationX
models available:
creates a new document
opens an existing SimulationX model
Close closes the current document window (model)
saves the current model
Save as displays a dialog box for the Save options
generates a print preview
opens the Windows Print dialog box
Send Message generates a message with the model as an attachment
Alternatively in Windows Explorer by double-click on a file name (*. isx, *.ism or

*. mo) the file to be opened.
Please note the instructions in section 10.5, "Conversion of models for use in
SimulationX 3.7".
A dialog opens for selecting the appropriate SimulationX version, if the

SimXLauncher was activated, as described in section 2.3.2.
Figure 5.4: SimXLauncher
Models can be saved as

SimulationX Model (*.ism),
SimulationX Project (*.isx) or
Modelica file (*.mo).
5-4 SimulationX 3
Creating Models
When storing models you can select the additionally following options:
The file format SimulationX Project permits accelerated saving and loading of
models containing large amounts of binary data, such as recorded results,
animation and CAD data, or graphics in the diagram view. The SimulationX
project is structured as a ZIP archive. Both, the text-formatted model as well as the
embedded data, can be accessed directly. For instance, the recorded simulation
results can now be extracted, evaluated, or processed in other programs without
involving SimulationX. Additionally SimulationX Project data contain a preview
picture of the model, which can be displayed in the Windows Explorer and in the
dialogs for opening and storing files. To make possible the search for models in the
Windows Explorer additional information like idents of the used element types in
the model will be stored in the data file.
It is possible to prevent imported CAD data from being saved. In this case the
triangular meshes, which define the body shape, are replaced by simple cuboids.
The imported mass and inertia data is not removed and remains intact within the
model.
When saving as a Modelica file you receives the following notice:
SimulationX 3 5-5
5.2.2 Element Types and Libraries

Elements, which are used in SimulationX, can come from three different sources:
SimulationX libraries
Modelica standard libraries
Libraries of user-defined element types
All of those elements can become part of one and the same simulation model.
5.2.2.1 SimulationX Libraries

SimulationX comes with a collection of libraries for different physical domains
and application fields. The availability of a library depends on the license which
was purchased for the respective SimulationX installation.
These SimulationX libraries are developed and maintained by ITI, and are based
on know-how from numerous engineering projects and applications. They are well
validated and tested and the handling of the elements from these libraries is set up
such, that they provide a maximum in comfort and easiness of use. For all
SimulationX libraries the customer can obtain full technical and modeling support.
Figure 5.5: Snapshot showing some of the SimulationX libraries
5-6 SimulationX 3
Creating Models
The SimulationX libraries are all based on the modeling approaches introduced in
section 5.1.
The SimulationX libraries cannot be modified by the user, but they can be used as
starting point for custom model object development either by forming compound
models or by extending the functionality of the library elements (see section 8.2.3).
5.2.2.2 Modelica Standard Libraries

SimulationX implements the Modelica language as a model development and
programming interface for user-defined types. Modelica is a vendor-independent
language standard and there exist publically available model libraries written in
Modelica. These libraries can be used in SimulationX too.
Figure 5.6: Snapshot showing some of the Modelica libraries
The use of Modelica libraries within SimulationX is explained in detail in

chapter 10.
Modelica libraries are neither developed nor supported by ITI. Compared to

SimulationX libraries there are some limitations in Modelica:
There are no connection objects in Modelica, which makes model object
development more complex. The coupling to SimulationX libraries requires
special interface elements.
Modelica does not allow variable values or expressions to be assigned to
parameters, which are a major factor for the SimulationX modeling
flexibility.
Change of the size of Modelica objects:

In order to change the size of an element the mouse pointer has to be positioned at
specially marked vertices of the marker frame and has to be dragged (at
simultaneously pressed left mouse button) till the desired size has been gained.
Using the red arrow a rotation of the element is available.
SimulationX 3 5-7
The size of an element can only be adjusted if the following conditions are met:
Vector graphics are used for the symbol of the element type instead of
bitmaps.
Instead of proprietary SimulationX ports Modelica compatible Connectors
are used exclusively.
Those mentioned preconditions are fulfilled by the elements of the Modelica

Standard Library as well as by all Modelica compliant types.
For restoring the standard size chose Reset Transformation in the context menu
of the element.
These elements can also rotate. Click on the element. Then touch with the cursor
on the red arrow and rotate it.
5-8 SimulationX 3
Creating Models
5.2.2.3 User-Defined Element Types

SimulationX provides the user with various capabilities to develop custom libraries
and model elements.
New element types are either
Compounds of existing types
Extensions of existing types
Newly developed types based on equations and algorithms, or a combination
of these.
For the development of customer-defined element types all SimulationX and

Modelica capabilities can be exploited and can jointly be used.
For details on developing customer-defined element types please refer to

chapter 8.
5.2.3 Model Creation and Modification

This section explains the assembly of simulation models in SimulationX. It gives
the necessary startup information. More specialized issues such as the handling of
characteristic curves, the modeling using the Multi-Body library and additional
elements to be placed in models (visualizers, text boxes, graphics, and controls) are
treated separately in section 5.4.5.1.
5.2.3.1 Building a Model Structure

Elements and connections are the components (cf. Figure 5.7) of a simulation
model. Elements have connectors that can link together via a connection.
Connections can be branched arbitrarily; i.e., they can link more than two
connectors.
Element
Element connector
Element connection
Figure 5.7: Components
There are different types of connectors, such as mechanical (linear and rotary),
hydraulic, and electrical connectors, as well as signal inputs and outputs. Only
SimulationX 3 5-9
connectors of the same type can be connected to each other. Each connector
possesses an unambiguous name with respect to the corresponding element. These
names can be made visible via the menu View Pin Labels or by using the
button .
To place a new element using drag-and-drop into the diagram view, proceed as
follows:
1. Find the corresponding element type in the tree view of the library bar.
2. Click with the left mouse button on the entry in the tree and keep the mouse
button pressed.
3. With the left button pressed move the mouse pointer to the position where the
new element is to be inserted.
4. When releasing the mouse button the element is created at the desired place in
the model.
You can modify the positioning of elements by using the following options and
commands:
Snap to grid
Rotate left
5-10 SimulationX 3
Creating Models
Rotate right
Mirrored horizontal
Mirrored vertical
Dragging them with the mouse can change the position of the elements.
To place several elements of one type into the diagram view, you can repeat step
1-4 several times or use the drag-and-drop copy.
To create a connection between two connectors you can do the following:

1. Place the mouse pointer over the connector, from which you want to draw the
new connection. The changed mouse pointer as well as the changed color of the
connector indicates that you have met the connector.
2. Press the left mouse button and move the mouse pointer to the target connector
of the new connection, while pressing the left mouse button.
3. When you release the mouse button the connection is created.
You can abort the creation of a new connection at any time by releasing the mouse
button over an empty region in the diagram view or by using the Escape key.
SimulationX supports 2 basic kinds of connections:

In Modelica connections are only defined between two connectors. The
Modelica connection does not have a unique name, nether parameters nor
result variables. The connection can be labeled optional with a comment.
SimulationX connections can be branched to an arbitrary number of
connectors. So it is possible to connect more than 2 elements together. An
element can be added to an existing connection line by drawing a connection
line between the empty connector of the element and the existing connection
line. The drawing can be started at the empty connector as well as at the
SimulationX 3 5-11
existing connection. Each SimulationX connection has a unique name and

mostly they possess parameters and result variables.
The path of a connection will be determined automatically (Auto routing), but a

change of the path is possible at any time. To do this, click with the mouse on a
connection. After that the existing nodes are visible.
These nodes can be replaced in an arbitrary way with the mouse. This results in a
changed connection routing. Via the context menu of the selected node it is
possible to add or delete nodes of the connection. Also the Auto Routing can be
deactivated.
By clicking on a connection line, the mouse pointer shows you in which direction
you can move the selected connection line.
To improve the clarity of the model, you can branch connections. So, you can
create connections between free connectors and existing connections in both
directions.
Connections can be also separated, shifted or deleted.

For disengaging a connection at a connector keep the Shift key pressed and drag
the mouse pointer to the connector, where the connection is to be separated.
The connection is separated with a click on the left mouse button.
5-12 SimulationX 3
Creating Models
For shifting a connection: mouse click on a), keep it pressed and drag to
somewhere for disengaging (see b). Then move with the mouse pointer to a
connector of the target element (c) and release mouse button.
a) b) c)
Alternatively you can select the connection, and use the Del key for disengaging.
The connection will be deleted completely.
By using the option "Separate" in the properties dialog of an element you can also
disengage the element.
The dynamic visualization for connection lines gives you an improved model
overview. The settings for the visualization are done by the properties dialog of a
connection (see section 6.2). The current state or the exceeding of
minimum/maximum of certain variables like pressure or temperature can be color-
marked. Even video recording is possible.
5.2.3.2 Editing of models

How to Select an Element
An element is selected by a mouse click. Once selected, it will be optically
accentuated by a frame. Single elements can be selected also by selection of the
corresponding entry in the model explorer.
How to Select Several Elements

To select several elements there are two possibilities:
1. Draw a frame around the respective elements.
SimulationX 3 5-13
2. An element can be added to the current selection by pressing the Shift key and
clicking with the mouse on the element. The removal of an element from the
selection is performed in the same way.
How to Select a Connection

By clicking one of the lines belonging to a connection, the connection is selected.
A selected connection will be optically accentuated by small rectangles. A
connection can be selected also by the selection of the corresponding entry in the
model explorer.
A selection of several connections is supported.
How to Move Elements

Selected elements can be moved by drag-and-drop as follows:
1. Click with the left mouse button on an element belonging to the current
selection and keep the button pressed. The selected elements will be shown
with frames.
2. By moving the mouse you can drag the elements to the desired position.
3. Release the mouse button at the desired element position.
5-14 SimulationX 3
Creating Models
How to Copy Elements

Beside the copy and paste of parts of the model using the clipboard, the copy of
elements via drag-and-drop is also supported as follows:
1. Click with the left mouse button on an element belonging to the current
selection and keep the button pressed. The selected elements will be shown as
frames.
2. At the same time keep the Ctrl key pressed. A copy of all selected elements is
created and you can place them at the desired place by moving the mouse.
3. When the mouse button is released the copying is finished.
You can abort a started drag-and-drop operation at any time by pressing the
Escape key before releasing the mouse button.
5.2.3.3 Labeling of Elements and Connections

On the General page in the parameter dialog of
elements you can change the name and comment of the
component as well as its orientation and the alignment of
its label.
Take care when you change the name of a component.

References to it from other components (e.g., in function
expressions) may become invalid. The mode of labeling
of all elements is globally adjustable.
On the property page Labels within the dialog Options (menu Extras
Options Labels) you can choose between four different display modes for
Elements. Per default the name of the element is displayed.
The following entries can be entered in the format field when using a free label:
&name Name of the element

&comment Comment of the element
SimulationX 3 5-15
&mainparamvalue Value of the main parameter

&mainparamunit Current unit of the main parameter
The different labeling options can be selected as follows:

The name of the
element is used.
The comment of
the element is
used.
The main
parameter is used.
The text entered in

the format field is
used.
Table 5.1: Element labeling
5.3 Parameters and Results

5.3.1 Property Window
The Property window is used to display and to edit properties of components
(elements, connections) in a simulation model.
Property windows are opened as follows:

Double click on the desired component in the diagram view or the model
explorer.
Select the element, then select the item View Properties from the menu
or press Alt+Return
Select Properties from the context menu of the element
If the current selection in the diagram view is changed, the property window is
automatically closed.
5-16 SimulationX 3
Parameters and Results
Figure 5.8: Property window of an element
There is a toolbar on the bottom of the property window, which offers the
following functions:
By a click on the button Open a dialogue is shown for opening a file with
parameters.
A click on the button Save as - opens the dialogue for storing files.
By a click on the button Excel the appropriate support for exporting data
to Microsoft Excel opens
Through a click on the button Help the online help for the component is
displayed.
A click on the button Keep opened prevents the automatic closing of the
dialog window when another component is selected. The property window
now remains open even if the current selection is changed. The properties
of the currently selected components are shown. This display mode is valid
until the window is closed or the button is pressed again.
Clicking the Backward button opens the property window of the previously
edited component.
For returning to the component, which was edited before clicking the
Backward button, the button Forward can be used.
SimulationX 3 5-17
The location of the toolbar can be changed by clicking with the right mouse button
on it. It can be either placed on bottom (default) or on top of the property window.
Properties belonging together are shown on the same page in the dialog. A
particular page is displayed by clicking on the corresponding tab. With the key
combinations Ctrl+Tab and Ctrl+Tab+Shift you can move to the next or previous
page respectively.
The size of the property window can be adjusted. There is a minimum size, which
depends on the maximum number of entries on the pages. Position and size are
saved, so the window is shown at the same place and with the same size, when you
open it again.
Changes to the properties of the component are taken over immediately. To revoke
a change use the command Undo in the menu Edit, the undo button in the
tool bar, or the corresponding key combination (Ctrl+Z).
The Property Window can be closed manually:

by using the keys RETURN, ESCAPE or Alt+F4
by using the button in the title bar of the window
by clicking on a different element in the model view (i.e. Property Window
becomes inactive)
If the window is not unpinned, the keys RETURN and ESCAPE cannot be used to
close it, but instead have the following functions:
RETURN Apply most recent change
ESCAPE Undo most recent change
If an error message pops up, it can be closed by hitting ESCAPE. To undo the most
recent change, hit ESCAPE again. The window cannot be closed until the error has
been corrected.
Default entries for parameters and units in the property window are shown in blue.
A reset to default values is possible by the context menu entry Reset to Default
on the respective input box.
The property window supports the selection of several components. In this case
only those properties are displayed, which are present in all selected components.
A change of such a property has an effect on all selected components. The

following figure shows the simultaneous changing of the stiffness of three springs.
5-18 SimulationX 3
The buttons in the properties dialog let you access parameters and result variables.
You can also use the Model Explorer and right-click on a line where you can select
Edit attributes.
The attributes dialog gives the possibility to enter additional information for the
control of the GSA (global symbolic analysis) as well as the solver.
The button to open the properties dialog for individual parameters and variables
shows an icon for a variables file type and variability. A small arrow on the right
side of the button opens additional options for parameter editing.
The variables properties are visualized in line with the symbols used in the
TypeDesigner and other GUI elements.
Real Integer Boolean String Un- Un-

known defined
Variable
Parameter
Constant
Parameter
Constant
Initial Value
This setup should be executed by advanced users only.
SimulationX 3 5-19
Figure 5.9: Attributes of a Parameter
Attribute Meaning
min, max extreme values of the parameter / the variable (result
quantity)
start start value (initial value );
if fixed == true , the computation starts with this value
fixed true: the solver must use the start value
false: the solver can use the start value, but it can also be
changed
notFixed the state can be changed while an initial value computation
after an event iteration, although in contrast of physical
reasons (e.g., displacement or velocity branches);
(only of interest in state variable)
nominal scaling factor for the solver, if the parameter or variable is a
state
(nominal value, e.g., in Hydraulics: nominal value of the
pressure = 1 bar; the values depends on the specific task and
usually the user can ignore it)
stateSelect specification whether a variable (preferably) should become
a state or not (never, avoid, default, prefer, always)
5-20 SimulationX 3
minNotReached, true: the value of the min-attribute must not be reached

(e.g., T.min = 0 K (temperature) must never be reached)
maxNotReached true: the value of the max-attribute must never be reached
absTol, relTol, tolerances of states for the solver
(if nothing is entered, the values will be taken from the
simulation control parameters)
discontChange state may jump change during the integration even without
discontinuity
quantity class of the physical quantity
(can be changed by the user in model elements from user-
defined Types, else in model components from Internal
Types only, if Basics.Unitless is the default setting)
comment comment of the parameter / variable
(can always be changed by the user)
5.3.2 Parameters
For the parameterization of model components special controls are used, whose
functionality is described in the sequel. The label of the controls consists of a
name, unique within the component, and a comment. The name can be referenced
in expressions and algorithms. While the comment is language dependent, the
name remains the same in each language version of SimulationX. This enables the
exchange of models between different language versions, whereby the comments
are shown in the current language.
Comment and physical quantity can be changed using the attributes dialog (see
section 5.3.1).
5.3.2.1 Control for Parameters
Name Unit selection
Description (comment) Editbox for functional expression
If a parameter was modified, but the changes have not yet been applied, this state
will be shown through an asterisk (*) in the title bar.
Entering parameters now triggers an immediate warning when a defined range of

values is exceeded.
SimulationX 3 5-21
Parameters in SimulationX may contain not only simple numerical values. The
"Editbox for functional expressions" allow you to enter:
Mathematical expressions
With few exceptions, each parameter input can be a mathematical function.
The range of possible notations is shown in section 10.4.2 and 8.2.7.
Examples for the use of mathematical functions
- sum, difference 5.23*mass1.x-50+function1.y
- product, quotient 0.01*gravity*CarMass.m/2
- relative deviation 2*(ctr1.x-ctr2.x)/(ctr1.x+
ctr2.x)
- weighted mean (a*x1+b*x2)/(a+b)
- logarithmic function a*ln(x+b) or a*log(x+b)
- power function 0.31*CarMass.v^2/2
- trigonometric function 230*cos(2*pi*50*time)
- exponential function 1-exp(-time/10ms)
- characteristic curve curve1.curve(ctr1.x)
- square root 0.01*sqrt(k)
- absolute value abs(x)
Logical terms
Each parameter entry can be linked to logical conditions. The logical
condition is written in brackets. If the condition is fulfilled (true) the
expression in brackets receives the value 1, and otherwise 0.
See also section 10.4.2, 10.4.6 and 10.4.9. Complex relationships can be
built up through the linkage of logical expressions in mathematical formulas
or parameter entries, as following examples show.
Examples for the use of logical operators

- switch function if(time<0.2) then 0 else 1
5-22 SimulationX 3
- limiter if x>b then b elseif x<a

then a else x
- case limit if(time>a)then X else Y
- range selection if(X2>a)and(X2<b)then X

else 0
- different stiffnesses for tension and pressure

if (ctr1.x>ctr2.x) then k1 else k2
Variables
All variables known in the model can be used for the parameter input, also
result variables.
If you enter the name of an element

followed by a dot, the autosensing
shows the available items.
More information about namespaces, identifiers and usable functions can be found
in section 10.4.
When using expressions, the selection box is disabled (the background becomes
gray). The result of an expression will always be interpreted as a value in the
corresponding SI base unit, as long as the expression itself does not contain the
desired unit explicitly. For more information about units see section 5.3.2.1.
Hint:
An expression, which is not shown completely due to its length, can also be
completely shown as a tool tip. For this move the mouse pointer over the input
field.
If the input field contains a simple number and another unit of measurement is
chosen, the number is converted to the new unit. Thus, the value used during
simulation does not change.
SimulationX 3 5-23
Figure 5.10: Unit switching with conversion
You can suppress this conversion by pressing the Shift key during the selection of a
new unit. The value of the parameter changes according to the selected unit.
Figure 5.11: Unit switching without conversion
5.3.2.2 Physical Measurement Units

Each expression can be extended with a character string (enclosed in single
quotation marks) describing a physical unit of measurement.
There are two forms:
1. e.g. 1 'km' : The value is interpreted as given in this unit and is converted into
the SI unit, i.e. 1 'km' == 1000
2. e.g. 1 '->km' : The value is interpreted to be in the SI unit and is converted into
the specific unit, i.e. 1 '->km' == 0.001.
Both forms can be used together, e.g. 1 'km^2->ha' == 100.

The existence of the given unit is approved using a database. Alternative notations
are allowed, e.g. 1 'km' == 1 'km^2' == 1 'km2'; 1 'N/m2' == 1 'Nm-2'
Values of the Anglo-American measurement system can be entered directly, e.g. 6
'ft' 6 'in' == 1.9812 'm'.
5.3.2.3 Constants:
pi 2*arccos(0) == 3.14159265358979...
e exp(1) == 2.71828182845905...
5.3.3 Initial Values
If a parameter is an initial value, the parameter control appears slightly different.

It contains a pin. If the pin is loose (like above) then the value is used as a hint for
the solver to start the search for consistent initial values with that value. The finally
used value might be different.
If the pin is stuck the value is obligatory. The solver will not modify it.
If there is no value given (the input field is empty) the value is interpreted as free
and the solver will choose it appropriately.
The initial value input field accepts only constant expressions.
5-24 SimulationX 3
5.3.4 Result variables

Each model element calculates a number of result variables depending on its
functionality and complexity. At every output time step all active result variables
of all elements of the model are provided.
Control for Result Variables
Name Unit selection
Description (comment) Protocol attribute on/off
The protocol attribute of a result variable can be switched on or off by clicking on

the corresponding button.
The protocol of a result variable can be shown in result windows (cf. section 7.3)
or can be saved to a file. The chosen unit of measurement is used as preset for the
display. It has no effect on the simulation.
5.3.5 Global Parameters

These parameters are defined globally in the model and provided with standard
values.
Name Comment Default
gravity
gravitation 9.80665 m/s
gravity3D
gravity vector (3D) {0.0,0.0,gravity}
m/s
pAtm
atmosphere pressure 1.01325 bar
TAtm
atmosphere temperature 20 C
iSim
counter of simulation run 0
(increased by every
simulations run)
nSim
name of simulation empty
(used by the variant wizard)
SimulationX 3 5-25
5.3.6 Special Tools for Parameter Input

5.3.6.1 Multidimensional Parameters
When editing multidimensional parameters a special editor is available providing a
table like view. You can access it through the respective button in the input textbox
of the parameter.
For multi-dimensional parameters, there is a dedicated table editor for array
components. Parameters must be a one-, two, or at max three-dimensional
Boolean, integer, real or string matrix. This enables a button in the parameter input
for both the parameter dialog and the parameter table to open the editor directly.
Figure 5.12: Table Editor of a 3 by n matrix
It is important to know that any expression, be it matrix entries with formulas,

array constructors or other matrix-related function calls, are processed in the editor.
The existing parameter expression will be overwritten with the correct value when
the window is closed through the OK button in the dialog. If this is behavior is
not desired, the confirmation can be declined by clicking on Cancel to close the
dialog. If the number of columns and rows for a parameter can be changed, the
buttons
and text fields can be used to add or remove cells. This option
is only available if transposing the matrix does not violate the dimension
conditions. The tabulator key can speed up the process of entering an entire matrix:
The cursor then jumps from one cell to the next one or to the beginning of a new
row. If there is no row, a new one is created and the cursor moves to its beginning.
5-26 SimulationX 3
Copying the marked table area to the clipboard allows other programs to use it as
well. If necessary, table dimensions are extended automatically when a table with a
variable number of columns and rows is pasted. Copy and paste functionality is
available from both the tool bar and the context menu which can be opened with
the right mouse click on the highlighted area.
Figure 5.1: Context menu of a table row
Clicking on the row or column header selects the entire row or column. The
context menu also indicates whether the values in a row or column are strictly
increasing or decreasing. It also lets you sort the matrix in ascending or descending
order.
For numerical parameters (integer and real), values are shown in a diagram on the
right. Except for one-dimensional matrices (vectors), there are several diagram
types available:
Bar diagram
Open, closed or filled curve
Point cloud
3D surface
SimulationX 3 5-27
It is possible to specify through comma separated y values which columns should

be shown as data point series with different colors. In order to use a different
column for the x arguments, it is possible to enter the column index accordingly.
The two-dimensional representations allow for zooming in and out;
double-clicking on the diagram reset the view. Clicking on the axes synchronizes
the scaling of the horizontal and vertical axes to avoid distorted representations.
If data points are moved through drag and drop, the values in the table are updated
accordingly.
For the import, there is an assistant that can read different file types. Before that, it
is vital to make sure that the correct unit is set in the table editor. Depending on the
file type, the import assistant requires information about several aspects of the
process.
When importing XML serialized tables you have to specify the exact cell
range. To select a different cell range than the one proposed, drag the mouse
over the desired rectangular range. By clicking while pressing the Ctrl key
you can create disconnected selections. The selection then is always
completed automatically to form a full matrix.
Figure 5.13: Assistant to import XML files
When importing CSV files or TXT files consisting of similarly separated

data, the data separator and decimal separator can be chosen and a certain
number of header lines can be skipped.
5-28 SimulationX 3
Figure 5.14: Assistant to import character separated files
After this setup is done, the file is initially parsed. On the next page you can
specify the exact range of cells just like on the XML import page.
When you import MATLAB files, you must select the variables containing
the desired data. It is only possible such matrices whose dimensions and
type match the edited parameter. Not only are dimensions of the actual
variables checked, but also the transposed. Though you can exclude those
variables that do not meet these criteria from the import.
Figure 5.15: Assistant to import MATLAB files
When importing from Excel files, again the desired cell range has to be
selected along with the correct spread sheet and table.
SimulationX 3 5-29
Figure 5.16: Assistant to import Excel files
If multiple tables are to be imported for 3-dimensional arrays, you can choose a
manual table by table setup or let the assistant do it the automated way.
The parameter data can also be visualized in a diagram. In addition, data points can
conveniently be changed by drag and drop.
5.3.6.2 Files, Folders and Colors

When inputting files, folders or colors, there is also a set of special tools accessible
through the respective button in the input textbox of the parameter. Of course,
textual input by hand is possible as well, but the correct format for character
strings and arrays has to be taken into account.
5.3.7 Export and Import of Parameters

5.3.7.1 Export of Parameters
Parameters can be exported directly from the properties dialog. Parameter tables
can be saved as text file (*.csv, *.txt) or as Excel worksheet (*.xlsx). That allows
parameter sets to be organized independently from the simulation model, and
individual parameters can be transferred from one component to another one of the
same kind. The parameters that are to be included in the export can be defined in
the corresponding dialog. In general, it is possible to save any parameter type,
though it is advisable to pay special attention to enumerations as they may switch
active and inactive parameters around when altered.
The example of a spring-dampers backlash illustrates this correlation. If the

settings for the parameter export are set to kind=spring-damper, all inactive (i.e.
invisible) parameters for the backlash are only transferred when the option Inactive
Parameters is selected for export.
5-30 SimulationX 3
In order to export all parameters of a model or a compound, open the properties

dialog of the corresponding model or compound and activate the option Export
parameters of all included components.
5.3.7.2 Import of Parameters

Parameters can also be imported, of course. The same file formats are supported as
for export. Column delimiter in *.txt and *.csv files is the tabulator. Decimal mark
is the full stop as it used to be in SimulationX. A text file must have the following
structure:
SimulationX 3 5-31
Attention must be paid to the headers of each column in the text file. They must
have exactly the same names for all imported files.
5.3.7.3 Editing Parameters in Excel

Parameters can also be edited directly in Excel. This does not require the data to be
exported in a separate file however. SimulationX generates a temporary file in the
background instead. Once you have finished editing in Excel, all changes are
applied in SimulationX automatically and the temporary file will be deleted.
5.4 Special Topics

5.4.1 Describing Nonlinear Properties with Force Characteristics
The nonlinear properties of parts or components are often described with force or
torque characteristics. Examples of this are torque-deformation characteristics of
couplings with nonlinear stiffness properties or slip characteristics in the case of
contact problems.
Variable forces/torques can be modeled best with the elements External Force or
External Torque from the library Mechanics, respectively.
5.4.1.1 Description using Formulas

Relations described with formulas can be entered directly in the parameter dialog
box. For example, if the torque of a coupling is given with the formula
M iKupplung = k0 ( + a 3 ) (5.1)
the following entry will be found in the parameter dialog box for the External
Torque:
k0 * ((self.ctr1.phi - self.ctr2.phi) + a * (self.ctr1.phi - self.ctr2.phi)^3) (5.2)
or alternatively:
k0 * (self.dphi + a * self.dphi^3) (5.3)
Figure 5.17: External Torque with parameter input for the torque characteristics given as
a formula
The variables k0 and a here are user-defined variables, created beforehand in the
parameters dialog of the model. The deformation of the connected inertias can be
accessed from the element via the parameters self.ctr1.phi and
5-32 SimulationX 3
Special Topics
self.ctr2.phi in the Mechanics Library. Since stands for the relative or

differential torsion of the two coupling halves, ctr1.phi-ctr2.phi has to be
written for this in the parameter dialog box.
Alternatively, a reference to the result variable dphi can be written.
The External Torque element with this parameter input is connected between two
rotary inertias (cf. Figure 5.18).
Figure 5.18: Model structure of a coupling with nonlinear torque characteristics

described by formula
The parameters given for each of the rotating inertias are the inertia of one
coupling half. Furthermore, the deformations (angle, angular velocity, angular
acceleration) of the coupling halves are also calculated at the rotating inertias
Please refer also to the sample file Mechanics/NonlinearCoupling.ism.
5.4.1.2 Description using Characteristics

For example, let's assume the following characteristics of a multistage clutch:
Figure 5.19: Point-by-point described characteristics
In SimulationX you can best describe relations given point-by-point with the
element Curve (from the library Signal Sources). Select the Input X option in the
list box and enter the points or load them from the medium (cf. Figure 5.20)
SimulationX 3 5-33
Figure 5.20: Plotting point-by-point relations with the Curve element
The torque is described as a function of the deformation or differential angle of the

clutch halves . Accordingly, must be the reference variable (x-axis) for the
Curve1. Therefore, not the simulation time, but rather the input variable is selected
as the reference variable in the dialog box (see Figure 5.20). Furthermore is
fed to the input of the signal block (cf. Figure 5.21). has to be made available
beforehand. For this you have to tap the angles of both clutch halves through
sensors. The angular difference can be calculated at a summing junction.
Figure 5.21: Structure of a coupling model with point-by-point characteristics

(multistage clutch)
5-34 SimulationX 3
Special Topics
The output variable of the Curve (Curve1 at Figure 5.20) is the coupling torque. It
is put between the coupling halves with the External Torque (Coupling). The
parameters for the External Torque are given with the signal input in1, which
refers to the quantity applied at the signal input Curve1.x.
The coupling halves are modeled with rotating inertias (J1 and J2). The inertia
parameters are defined with the moment of inertia. The motion quantities of the
coupling are also calculated at the inertias.
The initial rotational speed of inertia J1 is set to 2 rpm.
If you perform a simulation run and represent the torque over the differential angle,
you will obtain the characteristics entered for the range that is covered during the
calculation (cf. Figure 5.22).
Figure 5.22: Simulation results of coupling characteristics
5.4.2 Variable Element Parameters

5.4.2.1 Parameter Input of the Elements Using Variable Parameters -
Parameters are Effective Quantities
In general, when the elements are not specially tailored to variable parameters, the
solution algorithm in SimulationX assumes that the parameters used are constant.
Spring elements are one example of this. The force F is calculated as follows in the
spring element:
F = k ( x1 x 2 ) = k x , (5.4)
or the torque T for a rotary spring:

T = k (1 2 ) = k . (5.5)
SimulationX 3 5-35
If we transpose (5.5) with respect to the stiffness k, we get

T
k= , (5.6)

which is precisely true for constant stiffnesses.
Therefore, if you want to work with variable stiffnesses in the spring element, you
have to use the so-called effective stiffness keff, since it is likewise defined as the
quotient of torque (or force) and deformation ( or x):
T ( )
keff ( ) = . (5.7)

The effective stiffness thus corresponds to the slope of a straight line passing
through the working point and the zero point of the T--characteristic curve (cf.
Figure 5.23). By all means, keff can be a function here. It does not have to be
constant. For example, the following effective stiffness would be obtained for the
torque in the coupling with the relation given in (5.1):
keff =
TiKupplung
=
(
k0 + a 3 )
. (5.8)
(
keff = k0 a 1 + a 2
)
If the expression k 0 a (1 + a 2 ) is given as the parameter input for the stiffness of a
spring element, the nonlinear relation will be precisely described. No integration
over the parameter is required. Initial values for the simulation start (integration
constants such as (5.10) do not have to be known.
The following section discusses how to proceed if the stiffness is given as a

derivative.
5.4.2.2 Integration over Variable Parameters - Parameters are Given as

Derivatives
If variable parameters are given as derivatives, an integration over these
parameters is required. We will illustrate this again using a nonlinear spring as an
example.
In general the spring stiffness k is defined with the following relation:
dT
k= , (5.9)
d
where k is the derivative of the torque T with respect to the angle . Thus, the
stiffness corresponds to the slope of the tangent at the working point of the T--
characteristic curve (Figure 5.23).
5-36 SimulationX 3
Special Topics
Figure 5.23: Stiffness k and effective stiffness keff for nonlinear torque-deformation
characteristic curves T()
Transposing from (5.9) yields the relation for the torque:
T = k d + T0 . (5.10)
T0 here is the integration constant.
Thus, the torque is calculated in the model by integration. Corresponding signal

blocks are available for this.
If you want to directly transpose the above integration formula, you have to
integrate over the differential angle . section 5.4.1.2 already tells you how this
angle is obtained. This is also shown in Figure 5.24. The integration takes place in
the signal block Integral y over x of the Special Signal Blocks library. The torque
applied at the output is once more put between the inertias of the coupling halves
(J1 and J2) by means of the External Torque (coupling).
Figure 5.24: Model structure of a coupling with nonlinear stiffness integration of the
stiffness over the angle
SimulationX 3 5-37
In general, however, the integration during the simulation is made over time. You
can also put down the integral for the torque for this. The torque is obtained from
(5.10) as the integral over time (5.13), by inserting (5.12).
T = (k )dt + T0 , with (5.11)
d = dt , (5.12)
where is the velocity. The simulation model then looks like the one shown in
Figure 5.25.
Figure 5.25: Model structure of a coupling with nonlinear stiffness integration of the
stiffness over time
The Integrator of the Linear Signal Blocks library is required for the integration
over time.
Remarks:
In the integration the internal torque of the spring for the starting point of the
simulation must be known and entered (not necessary if the effective stiffness is
used; cf. (5.7)). However, the simulation often begins in the undeformed state,
for which reason the internal torque at the beginning of the simulation, and thus
the integration constant, are zero.
The External Torque (coupling in Figure 5.24 and Figure 5.25) is assigned as
in1 for the signal applied at the input.
If the relation given as a derivative can be completely integrated, then the
stiffness k can be converted to an effective stiffness keff, for example according
to (5.13).
5-38 SimulationX 3
Special Topics
k eff =
k d bzw.

(5.13)
k eff =
k dx
x
Three modeling possibilities for the given nonlinear relation TiCoupling = k 0 ( + a 3 )

are compiled in the samples model Mechanics/NonlinearCoupling.ism.
Known: Ti = k0 * (phi + a * phi^3)
Solution 1: The torque depends on the difference of the turning angles

-> use of an external torque element (source) with formula.
Solution 2: The effective coupling stiffness is known. It can be entered in a

Spring element.
Solution 3: Is the internal torque on the angle phi derived, we get the actual
stiffness. In this case, it must be integrated and provide solutions
according to Figure 5.24 or Figure 5.25.
SimulationX 3 5-39
Both the result curves (cf. Figure 5.26) and the dynamic behavior of all three
modeling possibilities are identical. Thus, all of these types of modeling are
equivalent in terms of their results. You can choose any model, depending entirely
on what you prefer or need to use.
Figure 5.26: Identical results of different modeling variants of nonlinear relations in the
element
The solutions presented here are exemplary. Of course, other solutions arise using
the TypeDesigner or use of the functionality of Modelica.
5.4.3 Working with Characteristic Curves and Maps

Several elements of the different domains (e.g. signal sources, proportional control
valves ) possess the possibility of entering parameters by means of
characteristics, curve sets, and maps. All of these follow a common handling
concept, which is explained in the following subsections.
5-40 SimulationX 3
Special Topics
5.4.3.1 Characteristic Curve Dialog

Characteristic curves permit the generation of signals from point-wise data. In the
signal block curve these are generated either as function of the simulation time or
as function of the signal provided at the signal input x, in other model objects
mostly as function of some variable of the element.
Characteristic curves offer extensive possibilities for parameterization, which are
described in detail in the sequel.
With the button Edit you open a characteristic curve dialog, which permits the
detailed description of the generated signal. Different interpolation and
approximation methods for the generated curve can be selected. Some of them may
produce discontinuities of the output signal, so generally a treatment of these
points of discontinuity is necessary in the simulation (especially for further
processing of the derivative signal ydot on the Curve element in the simulation
model). If discontinuity handling is not necessary, it can be switched by setting the
selection box No Handling of Discontinuities to yes.
Figure 5.27: Characteristic curves dialog
The characteristic curves dialog offers a comfortable adjusting and editing of:
Sampling points (as table or graphically interactively)
Interpolation/Approximation
Kinds of continuation
Units
If there is more than one characteristic (such as in curve families, curve sets or
hysteresis curves), the dialog contains a table, where each column represents a
curve (1st column represents x-values, 2nd to n-th column represents values of the
function).
SimulationX 3 5-41
Tool bar:
The tool bar on top of the characteristic curve dialog offers access to the following
functions:
Load characteristic sets
Save entered characteristic set
Print characteristic set
Insert row (after selected one)
Delete row (selected one)
Properties dialog of characteristic set
Reset characteristic curve to standard values
Toggle Markers for sampling points
Show all axes (for curve sets only; separately axis for each row)
Characteristic input, data import and export:

For the input of characteristics and curve sets several possibilities exists to enter
and/or edit data points:
Insert/Edit value pairs in the table
Double click into the diagram for the generation/deletion of points and moving
of points by dragging them with the mouse
Load characteristics from a file (supported formats: Text (*.txt, *.csv), ITI-
SimulationX format (*.rsf), IEEE binary format (*.bin), ITI binary format
(*.rfb), ITI ASCII format (*.rfu))
Characteristics and curve sets can be stored in the mentioned formats and can be
also printed (see also section 7.1). For editing the characteristic in the table, the
following keyboard commands are available:
Tab Moves cursor to the next cell
Shift+Tab Moves cursor to the previous cell
ESC Cancels the current editing procedure and closes the
curve dialog
Enter Terminates the current editing procedure
Cursor up/down Moves the cursor upward and downward within a
column
Cursor left/right Moves the cursor to the left and to the right within a line
You can add or delete rows of the table using the buttons for 'Inserting' and
'Deletion' in the tool bar. A row is marked by a mouse click on the first column of
this row (row gets a frame). If you move the cursor by using the Tab-key behind
5-42 SimulationX 3
Special Topics
the last column of the table, a new column is added automatically. The current
characteristic curve is plotted in the preview, where the point marked in the table is
also marked in the diagram.
Shift Mouse can be moved only in y direction, the x value
remains constant
Ctrl Mouse can be moved only in x direction, the y value
remains constant
The point worked on in the preview is marked in the table too.
Interpolation and/or Approximation between the Sampling Points:

The interpolation or approximation can be adjusted separately for each of the
curves in the dialog. For the adjustment one of the entries in the respective column
or the column head is selected by a mouse click and then the desired
interpolation/approximation is selected by pressing the respective button in the
toolbar. For the curve family there is also an interpolation along the curve
parameters, which is always linear.
The respective mode is selected by clicking the appropriate button in the tool bar.
The interpolation/approximation modes work as follows:
Stair function:
The function value remains constant from the current data point to the next. The
curve is discontinuous if there are different function values for different sampling
points. The derivative of the curve is a constant zero, thus it is a continuous time
derivative.
Figure 5.28: Characteristic curve with stairs
SimulationX 3 5-43
Linear interpolation:
The given sampling points are connected with straight lines.
Figure 5.29: Characteristic curve with linear interpolation
Spline interpolation:
The sampling points are connected by splines (polynomials). This results in a
smooth curve with continuous first and second time derivative. The third time
derivative of the curve is discontinuous at the sampling points. The first derivative
of the curve (e.g. the preset velocity if the curve is used as preset displacement) is
piecewise quadratic. The second derivative (e.g. the preset acceleration if the curve
is used as preset displacement) is piecewise linear.
Figure 5.30: Characteristic curve with spline interpolation
5-44 SimulationX 3
Special Topics
Hyperbolic approximation:
The curve is approximated by hyperbolas. The transitions between adjacent
hyperbola sections are continuously differentiable. The transition uses the same
distance from the sampling point for left- and right-sided approximation. This
distance value is half the minimum of the interval lengths of the two adjacent
intervals. Such for the greater interval the hyperbola is continued by a straight line
till the next hyperbola section is hit. If the curve is non-periodically continued
these straight lines are also applied for the boundary intervals from the boundary
point to at least the interval center point.
The permissible deviation of the function values from the hyperbola vertices is
determined by the parameter Approximation Tolerance. In the example a value of
1000 is chosen. In simple words, the greater the value of the approximation
tolerance is the greater the deviation distance gets. There is a maximum possible
deviation to still meet the above requirements for the hyperbola sections. Thus an
extremely large value of the approximation tolerance will not change the resulting
curve any longer.
Figure 5.31: Characteristic curve with hyperbolic approximation
If straight lines are used the first derivative (e.g. the preset velocity if the curve is
used as preset displacement) is constant. The second derivative (e.g. the preset
acceleration if the curve is used as preset displacement) of the straight line sections
is zero. The time derivatives for the hyperbola sections are not zero and
continuous. The transition of the first derivative is continuous at the sampling
points. The transition of the second derivative between adjacent hyperbola sections
or a hyperbola section and its adjacent straight line is discontinuous.
If the sum of the adjacent slopes at a sampling point vanishes the principal axis of
the corresponding hyperbola are parallel to the x- and y-axis of the curve with the
vertex of this hyperbola being vertically aligned with this sampling point.
SimulationX 3 5-45
Approximation by circular arcs:

The curve is approximated by a set of circular arcs. The transitions between
adjacent circular arcs are continuously differentiable. The transition uses the same
distance from the sampling point for left- and right-sided approximation. This
distance value is calculated by the approximation tolerance and bounded by half
the minimum of the interval lengths of the two adjacent intervals. Such for the
greater interval the circular arc is continued by a straight line till the next circular
arc is hit. If the curve is non-periodically continued these straight lines are also
applied for the boundary intervals from the boundary point to at least the interval
center point.
The permissible deviation from the sampling points is determined by the parameter
Approximation Tolerance. In the example a value of 1000 is chosen. The distance
between the data value and the center point of the corresponding circle is equal to
the radius of the circle and the approximation tolerance. There is a maximum
possible distance to meet the requirements for adjacent circular arcs. Thus an
extremely large value of the approximation tolerance will not change the resulting
curve any longer.
Figure 5.32: Characteristic curve with approximation by circular arcs
is zero. The time derivatives for the circular arcs are not zero and continuous. The
transition of the first derivative is continuous at the sampling points. The transition
of the second derivative between adjacent circular arcs or a circular arc and its
adjacent straight line is discontinuous.
5-46 SimulationX 3
Special Topics
If the sum of the adjacent slopes at a sampling point vanishes the center of the
corresponding circle is vertically aligned with the sampling point. Then the
transition points have the same distance from the sampling point along the x-axis.
Quadratic Approximation:
The curve is approximated by a sequence of quadratic splines. The transitions
between adjacent parabola sections are continuously differentiable. The transition
uses the same distance from the sampling point for left- and right-sided
approximation. This distance value is bound by half the minimum of the interval
lengths of the two adjacent intervals. Such for the greater interval the parabola is
continued by a straight line till the next parabola section is hit. If the curve is non-
periodically continued these straight lines are also applied for the boundary
intervals from the boundary point to at least the interval center point.
Figure 5.33: Characteristic curve with quadratic approximation
The permissible deviation from the sampling points is determined by the parameter
Approximation Tolerance. In the example a value of 1000 is chosen. There is a
maximum possible distance to meet the requirements for adjacent parabola
sections. Thus an extremely large value of the approximation tolerance will not
change the resulting curve any longer.
is zero. The first time derivative of the parabola sections is linear. The second time
derivative of the parabola sections is constant. The transition of the first derivative
is continuous at the sampling points. The transition of the second derivative
between adjacent parabola sections or a parabola section and its adjacent straight
line is discontinuous.
SimulationX 3 5-47
If the sum of the adjacent slopes at a sampling point vanishes the vertex and the
focal point of the parabola are vertically aligned with the sampling point.
Continuation of the curve outside of the specified interval:

The characteristic offers a set of possibilities for the continuation of the described
curve beyond the indicated range.
Linear extrapolation: This button affects the behavior of representation

"No special handling for values outside of the specified range" and "Mirror ".
If "Linear extrapolation" is switched on, then the curve is linearly continued
beyond the indicated range with the slope in the respective boundary point.
The following figure illustrates the linear extrapolation:
Figure 5.34: Linear Extrapolation
If the linear extrapolation is turned off and the domain of the curve is exceeded
during simulation, an error message is produced and the simulation stops. The
setting is ineffective if "Periodic Continuation" is selected for the curve.
No special handling for values outside of the specified range: If "Linear

extrapolation" is selected the curve is continued as a straight line beyond the
limits of the specified range using the slopes in the boundary points.
Mirror Curves: The curve is mirrored at the left boundary point (in both
coordinate directions). Outside of the defined range the curve behaves as
specified in the "Linear extrapolation". A continuation by mirroring is
demonstrated in the following illustration with linear extrapolation turned on:
5-48 SimulationX 3
Special Topics
Figure 5.35: Continuation of a curve by mirroring
Periodic Continuation: Outside of the specified range the curve is

periodically continued. In order to ensure a continuous extension the right
boundary point is set to the value of the left boundary point. In the periodic
mode no selection for the "Linear extrapolation" can be made.
The result is shown exemplarily in the following figure:
Figure 5.36: Periodic Continuation of a Curve
Properties of characteristic curves :

A click on the corresponding button in the toolbar of the curve dialog (found in
Curves, Curve Sets, Curve Families, and Hysteresis Curves) opens the properties
dialog for characteristic curves.
In the dialog a table of all available curve axes appears. It contains the x axis of the
curve on top, which then is followed by one or more y axes depending on the
functionality of the respective curve.
SimulationX 3 5-49
Figure 5.37: Property window of characteristic curves
The properties window has the following capabilities:

Curve Hysteresis
Function: Curve Curve Set
Family Curve
Changing the comments
for the particular axes: Yes Yes Yes Yes
Inserting a curve before

the currently selected
No Yes Yes No
row ( ):
Inserting a curve at the

end of the table ( ): No Yes Yes No
Removing the currently

selected curve from the No Yes Yes No
list ( ):
Selecting physical Yes, Yes, Yes, Yes,
quantities: for x and y for x and for for curve for x and
axes all y axes parameters, jointly for all
for x and y axes
jointly for all
y axes
5-50 SimulationX 3
Special Topics
Setting curve
parameters: No No Yes No
Setting approximation Yes, Yes, Yes, Yes,

tolerances: if approxi- if approxi- if approxi- if approxi-
mation is mation is mation is mation is
selected selected selected selected
Changing the comments for the particular axes

A comment can be edited after double clicking in the respective field in the table.
The usual Windows editing functionality is available. By default the curves are
named 'y[i]', where i stands for the consecutive number of the y axes (i.e., all
curves belonging to this particular curve object). Left at the default setting, the y
axes are automatically renumbered according to their order of appearance.
Inserting a curve before the currently selected row ( )
In order to insert a curve before a specific row, the row must be selected by a
mouse click on one of its fields first. Afterwards pressing the button in the
toolbar creates a new entry in the table, which is named 'y[i]'. i is the number of the
function in consecutive order. This functionality is available for curve sets and
curve families only.
Inserting a curve at the end of the table ( )
Pressing this button a new curve is inserted at the end of the curve list. The new
curve is named 'y[i]', where i is the number of the function in consecutive order.
This functionality is available for curve sets and curve families only.
Deleting the currently selected curve ( )
In order to delete a curve from the list, the respective row is selected by a mouse
click, followed by a click on in the toolbar. All but the last remaining curve
can be deleted. Curves, which bear the default comment 'y[i]', where i is the
number of the curve in consecutive order, are renumbered accordingly. This
function is available for curve sets and curve families only.
Selecting physical quantities
A click on an entry in the Quantity column opens a selection menu from which the
appropriate physical quantity for the respective curve and axis can be chosen. After
setting the physical quantity, units of measurement can be selected for the data
entered in the table and/or graph of the Curve Dialog. Note, that for curve families
and hysteresis curves the physical quantity can only be selected jointly for all y-
axes.
Setting curve parameters
Curve parameters define the value, according to which a curve is selected in a
curve family. This value is provided as a second input beside the curve argument x.
According to the provided value a curve is selected. If no matching parameter is
found, a linear interpolation is performed between the neighboring curves.
SimulationX 3 5-51
Hint: It has to be made certain, that the curve parameters increase strictly
monotonously according to the order of the curves. Otherwise the dialog cannot be
closed and an error message is generated.
Setting approximation tolerances

The approximation tolerance provides a measure for how close the approximated
curve passes the entered data points. A small value means small deviation, a large
value large deviation respectively.
An approximation tolerance can be entered, if an approximation method is selected

for the respective curve. Newly generated curves take over the approximation
setting from the first curve in the list.
Reset the characteristic curve to standard values :
This button resets the complete contents of the curve dialog to its default values.
This button should be applied with care, since it deletes all previous data.
Selection of Physical Units:

Units for the x and y-axis can be specified in accordance with the physical quantity
selected in the Properties of characteristic curves dialog. After unit selection the
corresponding values are converted automatically. Units are selected in the
characteristic curve dialog by clicking with the left mouse button on the header of
the respective column of the data table. This opens a menu with the available units
(see illustration).
In order to prevent the automatic conversion of the numerical values you can press
the Shift-key during the unit selection. The selected unit defines only the
conversion of values in the table and in the diagram. The input signal must be
provided in the appropriate SI base unit (if the signal has a unit of measurement
this is ensured automatically). The selected unit for the output quantity is used in
the result display too. The output signal itself is provided in the respective SI base
unit.
5-52 SimulationX 3
Special Topics
5.4.3.2 Characteristic set

The characteristic set generates a vector of output signals from a given input signal
(simulation time or signal input), where everyone is individually parameterizable.
The input of parameters is the same as described in 5.4.3.1, with the following
peculiarities:
By the properties dialog you can add or delete curves.

The selection of physical dimensions and units is adjusted to using more than
one curve.
Interpolation and approximation are adjusted to using more than one curve.
Characteristic sets dialog

If there is more than one characteristic, the dialog offers a table (1. Column
represents x-values, 2. to n. column represents values of the function), where each
column represents a curve. They can be edited as described in section 5.4.3.1.
5.4.3.3 Family of characteristic curves

With a family of characteristic curves you can generate a map by processing a
range of curves z=f(x), which selection is controlled by an input signal y. A
comparable functionality is usable also over 2D-maps.
The parameterization is the same as described in 5.4.3.1, with the following
peculiarities:
A family of curves is always calculated as function of the input signal, whereby
one input signal gives the selection parameter of the curve.
With the properties dialog you can add and delete curves.
The selection of physical dimensions and units is adapted to the use of several
curves.
Interpolation and Approximation are adapted of the use of several curves.
Along the y-axis always a linear interpolation between the individual
curves takes place.
Hint: It is to be always made certain that the curve parameters increase strictly
monotonously with the sequence of the curves is the list.
5.4.3.4 2D-Characteristic map

By means of the 2D-maps, two-dimensional curves (arrays) can be used for
parameterization. With the button Edit you open a map dialog, which permits the
detailed description of the generated signal.
Characteristic maps dialog
The characteristic maps dialog offers a comfortable adjusting and editing of:
SimulationX 3 5-53
Interpolation and/or approximation

Units
Figure 5.38: Characteristic maps dialog
Toolbar:
The toolbar in the top of the characteristic map dialog differs from the toolbar of
the characteristic curve dialogs in some aspects. It offers access to the following
functions:
Load characteristic maps data

Save characteristic maps data
Print characteristic maps
Copy of current selection
Insert to current selection
Delete current Column
Delete current Row
Insert new Column to current position
Insert new Row to current position
Properties dialog
Zoom of diagram
Rotation of diagram
Two-dimensional diagram of the curve (plane view, outline diagram)
Three-dimensional diagram of the curve (perspective view)
Point-wise representation of sampling points
5-54 SimulationX 3
Special Topics
Representation of contour
Representation of zone ranges
Representation of grid structure
Reset all contents of the dialog to default values
Characteristic maps input, Data import and export:

For the input of characteristic maps several possibilities exists to enter and/or edit
data points:
Insert/Edit value pairs in the table
Load characteristic maps from a file (supported formats: Text (*.txt),
Microsoft Excel-spread sheet (*.xls).
Characteristic maps can be stored in the mentioned formats ( ) and can be also
printed ( ). Characteristic maps are displayed in a diagram and in a table. In the
table the entries of the first row (red) describe the data points of the x-axis, the
entries of the first column (green) the position of the data points concerning to the
y-axis, respectively. In the other cells the function values are entered, which are
defined by the x- and y-coordinates of the current row and column.
In the diagram the x- and y-values belonging to the respective mouse position are
visible.
For editing the characteristic map in the table, the following keyboard commands
are available:
Tab Moves cursor to the next cell
Shift+Tab Moves cursor to the previous cell
Cursor keys up/down Moves the cursor upward and downward within a
column
Cursor keys left/right Moves the cursor to the left and to the right within a line
For marking individual fields of the table the usual Windows marking functions
can be used, after marking a table field by a mouse click:
Left mouse button+Shift Mark the rectangular table range between the table field
selected last and the clicked field
Left mouse button+Ctrl Add the clicked field to the current selection
Cursor keys+Shift Mark the rectangular table range covered during the
cursor movement
Hint: If you have changed the number of columns in an exported xls-file, it is

necessary to check the name references using the Microsoft Excel Name Manager
before importing the data into SimulationX.
SimulationX 3 5-55
Figure 5.39: MS Excel Name Manger with wrong name reference
Copy and paste of table cells:

By using the button marked table cells can be copied to the clipboard. After
marking a new position in the table, a press on the button inserts the values
from the clipboard into the marked position. The selected field obtains the left
upper value of the range inserted from the clipboard.
Adapt the table size:

The size of the table and thus the number of the points in the curve can be reduced
by using the buttons (delete current column) and (delete current row).
Thereby the row and/or column of the current cell of the table are deleted.
In the same way by the button (insert column) and (insert row) an
extension of the table is possible. The new columns and/or rows are inserted on the
left and/or above of the currently marked cell of table. The new x- and/or y-values
are selected in such a way that the new value lies exactly between its two
neighboring values. When inserting rows above the first row or columns on the left
of the first column the value is adjusted in such a way that the marked row/column
has a value located in the middle between the new row/column and its other
neighbor row/column.
Adapt the diagram display:

For the adaptation of the diagram a set of buttons is available in the toolbar:
Zoom function: This button zooms into the curve plot. For this the button is
pressed and then a rectangular section of the diagram is selected with the
mouse. Pressing the button again or a click with the right mouse button on the
diagram cancels the zoom operation. A double click on the diagram re-
establishes the original view before all zoom or rotation steps.
Rotation of the diagram: With this button the curve representation can be
rotated freely in all directions. After pressing the button a click and hold on the
left mouse button (over the diagram) together with mouse movement changes
the viewing angle. Pressing the button again or a click with the right mouse
5-56 SimulationX 3
Special Topics
button on the diagram cancels the zoom operation. A double click on the
diagram re-establishes the original view before all zoom or rotation steps..
Two-dimensional diagram: This type of representation shows the curve in
top view (contour plot). Depending on selection, data points and/or contours,
zone ranges, and/or a grid are displayed.
Three-dimensional diagram: This type of representation shows the curve
in perspective projection. Depending on selection, data points and/or contours,
zone ranges, and/or a grid are displayed.
Point-wise representation of sawpling points: In this representation only
the sampling points given in the table are shown in the curve display. Contours,
zone ranges, and grid cannot be displayed.
Representation of contours: This button activates/deactivates the display
of contours in the diagram. During the point-wise representation of sampling
points this function is not available.
Representation of zone ranges: This button activates/deactivates the
colored representation of contours in the diagram. A zone (altitude range)
corresponds to the range between two contours. During the point-wise
representation of sampling points this function is not available.
Representation of grid structure: This representation activates/deactivates
the connection of the sampling points by a grid structure. During the point-wise
representation of sampling points this function is not available.
Properties of 2D-maps
Clicking the corresponding button in the tool bar of the map dialog opens the
properties dialog for the characteristic map, which permits the setting of
comment string,
physical dimension,
unit and
Interpolation and/or Approximation (the latter with approximation tolerance)
for both, the inputs in the characteristic diagram and for the output value. In the
map dialog a separate tab is available for each of the values.
Comment string:
The comment defines the inscription on the individual axes in the diagram of the
characteristic map. It can contain, e.g., symbols or short describing texts.
Selection of physical dimensions and units:

Physical dimensions can be assigned to the input values and the output value via a
selection menu on the associated tab. As a result the respective values are provided
SimulationX 3 5-57
with a unit, which can be suitably adjusted by the user. The units affect the
numerical values in the table of the sampling points as well as in the diagram of the
characteristic map. A change of the unit causes a conversion in the table and the
diagram. The selected physical dimension for the curve output does also apply to
the signal output of the component.
Note that the input signals must always be provided in the respective SI base unit.
The current selection of a unit for one of the map inputs does only affect the
representation of the values in the table and the diagram. All internal computations
take place in the SI base unit. This does also hold for the output values of the map.
Interpolation and/or Approximation between the Sampling Points:

For the interpolation and/or approximation between the sampling points different
options are available. They can be set independently for each of the inputs. The
options are similar to the interpolation/approximation options for the characteristic
curves, but with some restrictions (in brackets)
Linear interpolation (all input values)
Stair function (all input values)
Spline interpolation (only x axis)
Hyperbolic approximation (only x axis)
Approximation by circular arcs (only x axis)
Quadratic approximation (only x axis).
All approximations allow the setting of an approximation tolerance, which defines
the permissible deviation of the approximation from the sampling points.
5.4.3.5 3D Characteristic map
Figure 5.40: Characteristic maps dialog
5-58 SimulationX 3
Special Topics
By means of the 3D map parameterizations with 3D-arrays (three-dimensional

curves) are possible. The 3D map is specified as a collection of 2D maps, which in
turn are given by sampling points as described in section 5.4.3.4.
3D characteristic maps dialog:

The characteristic maps dialog offers a comfortable adjusting and editing of:
Interpolation and/or Approximation
Units
Toolbar:
The Toolbar on the top of the characteristic maps dialog offers access to all
functions of 2D-maps and is extended by the following:
Delete current table

Insert a new table at current position
Characteristic map input, data import and export:

The capabilities and handling of the 3D map corresponds essentially to that of the
2D map. In addition, it allows the assignment of different sampling points of the
input signal z to different tables. The tables are selected via a tab on the bottom.
The corresponding z value can be seen and edited in the upper left cell of the
respective table.
Copy and Paste of table cells:
This function corresponds to the 2D maps.
Adapt the table size:
There are two additional buttons available compared the editing functions of the
2D-maps. These buttons affect the number of the sampling points along the z-axis
of the diagram. deletes the currently displayed table and thus all sampling
points for the corresponding z-value. By pressing a new table is inserted at the
current position. When new tables are inserted, the same rules for the selection of z
values apply, as during the insertion of rows or columns in the 2D maps.
Adjust the diagram display:

The adjustment of the diagram (zoom, rotation, 2D/3D-view, sampling points,
contours, zone ranges, grid structure) takes place as with the 2D maps.
Properties of the 3D-maps:

Similarly to the 2D maps the properties dialog permits the definition of
annotations, physical dimension and units, as well as the interpolation and/or
approximation of the computed output values.
SimulationX 3 5-59
5.4.4 3D View
SimulationX provides a 3D viewer to visualize, examine and assemble multi body
simulation models. You can use multiple 3D views to display the elements of such
models, their position and orientation while building the model, and see the
animated simulation result. To open a new 3D view use the menu option Window-
>New 3D View.
5.4.4.1 Elements in the 3D-View

Within a 3D view you can see the objects of your model as well as several other
elements to display additional information. Some of them can be used to interact
with the model (cf. Figure 5.41).
The origin of the world (that is, your model) is displayed by a grey coordinate
system (1). It will always stay at this point, its position on the screen depends on
the camera position and/or orientation. In the bottom left corner there is another,
colored coordinate system (2). This one will always stay at that position on your
screen, regardless of the camera position. It can be used to quickly determine from
which side you are looking at your model.
An MBS connector is displayed by a coordinate system, to show its position, as

well as a symbol close to its position. The symbol shows whether this connector is
a MBS input (3), or output (4) connector. Connectors are only visible when the
element they belong to is selected.
3
4
Figure 5.41: 3D-View of a model
Hint: Connector symbols are used for interactive modeling tasks. Therefore they
are only visible during modeling.
5-60 SimulationX 3
Special Topics
5.4.4.2 Camera Manipulation

The current view of the model is defined by a virtual camera, which looks from its
position to a target point. To change the view you can control the camera in the
following ways: move it towards the target point (zoom), move target point and
position perpendicular to the line of sight (pan), rotate the cameras position around
the target point (rotate).
Camera controls are available through the mouse, the toolbar, keyboard shortcuts
as well as supported 3D input devices. It is possible to add model cameras from
MechanicsMBS/Tools. You can change the active camera using the drop down box
in the toolbar.
Mouse camera controls:
Middle mouse Rotate around the target point.

button
Shift + middle Pan camera.
mouse button
Ctrl + middle Zoom camera.
mouse button
Button C Camera target is set to the current selected object.
Or When this button is pushed again, the camera will move to fit
the selected object(s) into the screen.
Front view.
Back view.
Left view.
Right view.
Top view.
Bottom view.
Iso view.
Hint: By pressing one of the predefined view angles the camera will be rotated
around the target point. It is recommended to set the target to the object(s) of
interest before using this feature.
There are further controls available in the toolbar:
SimulationX 3 5-61
Activate the camera pan tool.

Activate the camera rotate tool.
Activate the camera rotate tool to rotate around:
X axis,
Y axis,
Z axis.
Fit model into the screen.

Activate the camera zoom tool.
Hint: Most camera controls are not available when a model camera is used to view
the scene. Position and orientation of a model camera are defined by its
parameters. To modify position/orientation of a model camera you have to
transform the object itself, using a second 3D-view.
5.4.4.3 Settings
You can customize the way your model is displayed on the screen using various
settings that can be applied to elements and views.
View settings are applied only to that particular view, while object settings effect
the object and possibly its children in every view they are displayed.
To change settings of an object go to the tab 3D settings in the property pages of
that object, view settings are available in the property pages of the current model.
At least one 3D-view has to be opened for a model to see and change these
settings.
Hint: Since every view has its own settings, a tab is added for each of them in the
property pages of the current model.
View Settings
A 3D-view in SimulationX has its own set of settings, which makes it possible to
display one model in different ways at the same time.
To make it easier to switch between certain sets of settings they can be saved and
restored using view modes. There are four predefined view modes available, which
can be activated using the dropdown list in the toolbar.
The settings for each view mode can be examined in the views property page,
where they can be changed and saved. It is also possible to create a new view mode
5-62 SimulationX 3
Special Topics
with customized settings. Saved view modes are available in all views of
SimulationX.
Values contained in the section general settings are not included in view modes.
Hint: The predefined view modes are protected. If you modify them and try to
save them, they wont be changed. Instead, a new view mode is created holding the
new settings.
View Modes
The viewing modes and their settings can be opened from the tool bar at any time.
There are four presets available which cannot be altered. Any changes of
individual settings are saved with the model, though the presets themselves remain
untouched. It is possible, however, to create your own view by simply copying the
current settings.
Custom view modes are saved locally on your hard drive and can thus be used for
all 3D views. View modes can be created, copied and deleted through the
properties dialog of the 3D view. Custom view modes can also be renamed in that
section. Settings from the General Settings are not accounted for in the view
modes, pre-defined view modes cannot be edited or deleted.
Figure 5.42: Modified settings are highlighted in bold (on the left); copying and
renaming creates a custom view mode (on the right).
SimulationX 3 5-63
View Mode
Predefined view modes
Standard view Wireframe
Technical view Realistic
Visibility
Edges
Mode Edge visibility mode
Off No edges visible
Wireframe All edges visible
Silhouettes Silhouette and hard edges only
Hidden Lines Visibility of hidden edges
Only available when edge mode is not off.
To save performance these settings cannot be used with
shadow planes/reflection/shadow maps.
Blend out Occluded edges are not visible
Blend over Occluded edges are visible.
5-64 SimulationX 3
Special Topics
Color Edge color

Ignore local Controls whether local edge colors should be ignored
colors
True Local element colors are ignored
False The global edge color is applied to only those
objects, which have no local color defined
Lighting Activates lighting calculation for edges (true/false).
Faces
Visible Face visibility (true/false).
Farbe Face color
Ignore local See edges/ignore local colors
colors
Shading Face shading mode
Gouraud Standard (colorinterpolation)
Phong Better but slower than gouraud shading (normal
interpolation)
Flat No interpolation between edges/points
Aus No lighting calculation
General
Anti Alias Activates anti-aliasing on directX displays. (true/false).
Shadow plane Activates a shadow plane. Inactive when the hidden line
algorithm is used. (true/false).
Reflection Activates a reflection plane. Inactive when the hidden line
algorithm is used. (true/false).
Shadow maps Activates shadow maps which make it possible for scene
elements to emit and receive shadows. Restricted to DirectX
and not active when the hidden line algorithm is used
(true/false).
Quality
Shadow plane Quality of the shadows on the shadow plane.
(low/medium/high)
SimulationX 3 5-65
Transparency Quality of transparency effects.

(off/low/medium/high)
Shadowmaps Quality of the shadows on elements.
(low/medium/high)
Hidden Line Quality of the hidden line algorithm.
General Settings
Colors
Background Defines top and bottom color of the background
Grid
Display Grid visibility (off/lines/points).
Line Pattern Line pattern if visibility = lines.
Line weight Line weight if visibility = lines.
Grid width Total width of the grid in both directions.
Step size Distance between two grid lines.
Color Color of the grid.
Type Defines the orientation of the grid.
Shadow
Type Toggles between dynamic and fixed shadow plane.
Color Shadow color.
Shadow plane Fixed shadow plane: position and orientation.
Light position Fixed shadow plane: light position.
Global Coordinate System
Mode Visibility mode: off/cross/axis triad.
Color Color of the coordinate system.
Draw always in If true, the coordinate system wont be obscured by any other
front geometry.
Scale Scale size of the coordinate system.
5-66 SimulationX 3
Special Topics
Visibility
Level of detail Different modes to control when to switch between LOD
levels.
Points
Symbol Defines a symbol to be used as point visualization.
Size Size of the points.
Table 5.2: View Settings
Object settings
Every element in the scene has its own settings, which are applied to that element
in every view where this element is visible.
If an object contains child objects (i.e. submodels) its settings take effect on these
objects, too, allowing to use compounds as a single object. However, it is still
possible to override settings coming from the parent object.
Visibility
Visualization Contains a couple of different visibility modes, which
override the global settings of the visibility of edges and
faces.
Use global setting (Standard)
Faces & Edges
Invisible
SimulationX 3 5-67
Solid
Wireframe
Edges
Points
Local Coordinate Choose at which element state the local coordinate system
System (CS) should be visible
when selected CS is visible when the element is
selected
never CS is never visible
always CS is always visible
Material
Use model values Decide whether the color coming from model parameters
should be used (true/false)
Color Local color setting for this element
Table 5.3: Object Settings of the View
5-68 SimulationX 3
Special Topics
Geometry settings
Geometry settings are part of the object settings but depend on the contents of an
object. Some geometry has specific settings, which are added to their elements
object settings. This is the same for models: geometry settings of their contents are
added to their own object settings. Geometry settings are empty per default. That is
the object doesnt define its own value but uses its parents value. This is signaled
by a blue italic value. If a value is defined on a certain element it is used for every
child which doesnt define its own value.
The model itself cannot derive values from a parent. Therefore its values are
always defined. When creating a new model it is initialized using default values,
which affect every element added to the model.
Geometry settings
[All geometries]
Always in front If true, this object will be drawn in front regardless of what lies
between it and the camera. This may lead to unexpected results
if defined for more than one object.
Trajectories Trajectories Enables/Disables motion paths for the selected
element.
Length Defines the length of trajectory in seconds. '-1'
for no length restriction.
Resolution Smallest time interval between adjacent positions
Always Shows the complete trajectory ignoring the given
visible simulation time. The length of the trajectory must
not be restricted in this case.
[All geometries except coordinate systems]
Shadow Deactivate shadow for this object (if activated in the view).
Reflection Deactivate reflection for this object (if activated in the view).
[Curved geometries ]
Geometry Different levels of geometry approximation.
approximation
SimulationX 3 5-69
[Imported geometries]
Smooth Deactivate smooth shading at object level.
shading
LOD Activate the use of LODs for this object.
Backface Deactivate backface culling to remove visualization artifacts of
culling geometries with inconsistent face handedness.
[Arrows]
Arrow Defines in which direction the arrowhead should point.
direction
[3D curve]
upVector Defines the up vector used to generate the curve: the geometry
shows defects when the difference between two supporting
points is close to the direction of the up vector. In that case it is
recommended to choose another one.
[Coordinate system]
Fixed size Deactivates the fixed size behavior of coordinate systems.
[Free cross section] (Prism, Rotoid, )
Smooth Separate shading option for objects using free cross sections.
geometry
[Quadratic cross section]
X alignment Defines cross section alignment in x direction (center/max/min)
Y alignment Defines cross section alignment in y direction (center/max/min)
5.4.4.4 Working in the 3D-View

Selection
To select an element in the 3D view, move the mouse cursor over the desired
element and press the left mouse button. You can see which element will be
selected when moving the mouse over the elements.
Selected elements are displayed with yellow edges and a coordinate system (if not
disabled, see object Settings).
5-70 SimulationX 3
Special Topics
Highlighted element Selected element

Figure 5.43: Selecting an Element
If an element contains MBS connectors, they will become visible when the
element is selected.
To add or remove an element from the selection, hold Shift and click it. It is also
possible to select more than one element. To do so, hold the left mouse button to
draw a selection frame. Every element inside of this frame will be selected when
the left mouse button is released.
If you click inside the 3D View, the system keeps track of every element which is
behind the cursor, not only the one which is in front and therefore visible. As long
as the selection is not changed via the left mouse button, you can switch between
these elements using the Tab key.
To deselect everything, simply select nothing by clicking in an empty place of the
screen.
Hint: Use the Tab key to select elements obscured by other objects.
Construction
To create an element, choose the desired element in the library and place it
anywhere inside the 3D view using drag-and-drop.
If you are creating an ITI MBS element it is also possible to start a construction
process, to change the standard values for the geometry dimensions. To do so, hold
STRG while dropping the element into the 3D view. After that, each dimension of
the element can be defined successively using the mouse, and confirmed by
pressing the left mouse button. It is possible to switch between continuous and
discrete input by pressing D on the keyboard. To finish construction, either define
and confirm every dimension parameter, or press Esc to abort the process and
restore the standard dimension values.
SimulationX 3 5-71
Positioning
Translation and rotation of an element in the 3D View is an interactive task done
by moving the mouse while keeping the left mouse button pressed. To make these
tasks easier, a couple of helpful features are available through the following keys:
D Switch between discrete/continuous input.

X, Y or Z Enable/disable input constraints.
Spacebar Switch to another pivot point, if available.
ESC Abort transformation process.
Hint: These keys are supposed to be pressed once, not held down. It is never
necessary to press more than one key at the same time.
To confirm the new position, release the left mouse button. If an element is
transformed, the transformation will be propagated to all its successors.
To rotate selected elements press R once. You may now click anywhere in the 3D-
view to start the rotation, keep the left button down while moving the mouse.
Without a defined constraint, the element will be rotated around the line of sight.
To rotate around a special axis only, press the corresponding key on the keyboard
(X, Y, Z).The center of rotation is the coordinate system (CS) of the rotated
element. You can switch between different centers of rotation using the Space. It is
possible to choose the CS of the elements input connector, the CS of its
predecessor and the CS of the output connector of its predecessor, if available.
Figure 5.44: Move an element along the X- axis
5-72 SimulationX 3
Special Topics
To translate an object you can move it using one of its connectors. It is possible to
constrain a translation along different axes or planes of the reference coordinate
system. To choose a plane, combine the axis constraints (for example: combining
X and Z moves the object along the y-plane). The reference CS is the elements CS,
it is also possible to switch to the global CS using the Space key.
Connect
To connect element A with element B inside the 3D view, simply grab A on one of
its connectors, and move that connector to a free one of element B. If there is no
connector visible at B during the translation of A, it
a) has no connectors at all,
b) has no corresponding connector (input connectors can only be connected
to an output connector), or
c) has no free connector (an input connector may have only one connected
output connector).
When the connectors are aligned on the screen and the mouse button is released, A
and B are connected where A is transformed that way that the CS of both
connectors are aligned in position and orientation. By pressing STRG while
connecting A and B, only the position of the connectors are aligned, the orientation
of the elements will stay as they were before.
Disconnecting Elements
To disconnect Element A from element B, simply move element A away from B
by moving one of its connectors.
Figure 5.45: Separate from elements: separated by pulling the element away at its input
connector will cut the connection to the predecessor
If you move A using its output connector, it will be disconnected from every other
element. The positions of the other elements, successors and predecessors, will
stay as they were.
If you move A using its input connector, it will be disconnected from its
predecessor, but stays connected to its successors, which will move as well.
SimulationX 3 5-73
To move objects without disconnecting press Shift when selecting the connector
(you can release Shift during the translation).
A rotation operation does not cut any connection, but will be applied to the rotated
elements as well as all of its successors, like any other transformation.
Trajectories
During animations, it is possible to show motion paths for any 3D object.
This option can be enabled or disabled in the 3D settings for one or more elements
at any time. The data for the trajectories are not based on the recorded result curves
of the model. They are saved and managed separately in the 3D view. Besides the
setting for the resolution of the trajectories, also the resolution of the animation has
an impact on a smooth motion path.
It may be advisable to reduce the animations speed. Trajectories with a small

resolution are fine-tuned with each further animation if possible.
Recorded motion paths are deleted when the model is reset or if the option is
disabled in the 3D settings.
Figure 5.46: Example model 'Centrifugal Governor' with trajectories
5-74 SimulationX 3
Special Topics
5.4.4.5 Performance
Low 3D performance may increase simulation time and reduce the quality of
animations. When facing performance problems check these points:
a) Hardware
Update the driver of your graphics card
Be sure your system supports DirectX 9.0c
Decrease the size of the 3D-view
b) Geometries
Reduce the count of visible 3D objects
Reduce the count of facets used in your 3D objects
- Internal objects: reduce geometry precision, see 5.4.4.3
- Imported objects: reimport geometries with lower precision
- Imported objects: activate LOD
c) Settings
Use the predefined view mode wireframe to increase performance
Deactivate advanced effects like anti-alias, shadows, reflection,
hidden line rendering
Create your own view modes to quickly change between settings
optimized for performance/visual quality
Hardware and System

The 3D visualization runs on multiple hardware configurations. If the underlying
hardware doesnt support certain implementations, the graphics system has to
switch to slower algorithms, which reduces overall performance. We recommend a
graphics cards supporting DirectX 9.0c, but 3D visualization also works with
OpenGL and, if none of them is available, a generic software driver. Regardless of
your graphics card, drivers should always be up to date.
Powerful hardware allows more geometries to be drawn and better effects to be
applied to them. However, even the best hardware has its limitations, especially
when geometries are too complex.
To reduce the impact on simulation time (for example when using virtual
machines) use minimal settings or close the 3d view.
Geometries
Imported geometries of high precision may have a severe impact on 3D
performance, if combined with advanced visualization techniques. When importing
or creating these geometries through third party applications, it is recommended to
use low/middle precision settings, especially when these geometries are used for
visualization only.
Built-in geometries support different precision settings if applicable, see geometry
settings.
SimulationX 3 5-75
Hint: Since SimulationX 3.6, imported geometries of every source, even

SimulationX files created in previous versions, are preprocessed to optimize
visualization, making them appear smooth. That makes it unnecessary to use high
precision geometries to increase visualization quality.
When activating LOD, SimulationX automatically creates geometries of reduced

precision. These will be used when an object is far away from the observer, in
which case less precision is needed to visualize the object. When LODs are used
the following points have to be considered:
Objects far away may have dark spots inside of the geometry. To remove
this effect deactivate smooth shading, or use transparency (performance
impact of transparent objects is reduced when using LODs)
Generated objects might not exactly match the shape of the original
geometry.
High precision geometries benefit the most from using LODs, performance
wise. However, negative effects also increase. It is always recommended to
use geometries of low precision.
LOD geometries are not saved to the model. They are regenerated each time
the model is opened.
5.4.5 Special Model Components

5.4.5.1 How to Insert Special Model Components
There are a couple of components in ITI SimulationX, which are used to complete
an existing simulation model. These components can be chosen via the menu
Insert. The components are shown as blocks in the model. They can be
selected, moved, and resized using the mouse. A corresponding property dialog
can be opened using the context menu.
Text Blocks and Pictures
A model can be illustrated using text blocks and
pictures. With a double click on a text block, its edit
mode is switched on. Within the toolbar Text
extensive formatting possibilities are available.
Using the clipboard, texts from common text

processors can be imported.
Visualizers
Using a visualizer the value of a result variable can be shown during the
simulation.
5-76 SimulationX 3
Special Topics
To assign a result variable to the visualizer, open the property dialog via the
context menu. On the page Visualizer there is a combination field where you
can choose the desired variable.
Visualizers are usable for animation of results (see section 7.2).
Controls
Using controls you can change parameters during the simulation.
To assign a parameter to a control open the property dialog (context menu). On the
page Control there is a combination field where you can choose the desired
parameter.
The Push Button control can be used to trigger a specific action from the
Diagram view of a model.
SimulationX 3 5-77
The push button control element, there are now two modes:
1. Script execution
When the button is pushed, a script specified in the properties dialog is
executed.
2. Stimulation of a parameter
As long as the button is pushed, the parameter selected in the properties
dialog uses the specified maximum value instead of the defined minimum.
Script VB script for describing the action to be performed. All

commands of COM interfaces of SimulationX available.
Text Sets the color of the button label. If the color is set to
transparent (default), system settings for buttons are used.
Label Specifies the text of the button label.
Figure 5.47: Button for Starting the Simulation
5-78 SimulationX 3
Special Topics
The control "Grid" can only be used with arrays, for example, with a function (see
Figure 5.47). Then the values can be edited comfortably in the table and are
available for the simulation immediately.
The axis label can be inserted on the label of the table. In the example, "| a | b" is
used.
Figure 5.48: Control Grid
Forms
Forms allow making the diagram view even more readable. For creating forms all
graphical primitives are available. The primitives are selected via the menu Insert
Forms or the control bar Drawing. Different properties of the forms can be
adjusted via the control bar too.
A polygon is drawn as follows:

1. Click on Polygon in the Drawing control bar.
2. Click on the desired location of the first polygon point in the diagram view.
3. Next click in the location, where the second polygon point shall be placed.
Repeat the procedure for all polygon points.
4. Finish the polygon by a double click.
5. The curve points can be moved with the mouse later on. Via the context
menu new points can be added to the polygon or existing points can be
removed.
SimulationX 3 5-79
An ellipse is drawn within the diagram view as follows:

1. Click on Ellipse in the Drawing control bar.
2. With the left mouse button pressed in the diagram view, drag the ellipse to
the desired size. The newly drawn form remains selected after that.
3. Adjust the line thickness, style and color, as well as the fill color and pattern
according to your needs.
Forms are compatible to the Modelica language standard.
5.4.6 Resolve External References

If you would like to give a model to another user, its important to also send the
components used in the system model. This can be done by including the
appropriate library with the model.
With the function Resolve External References (menu Edit), copies of all the
components used within the model can be generated. The previously external
references can then be found in the view Types in the Model Explorer under
Imported Types. Since they are now included in the system model, the components
will be automatically given to the next user with the model.
5-80 SimulationX 3
Special Topics
5.4.7 Compare Models

You can compare two open models via the menu Edit -> Compare Models.
The differences between the two models are listed in the output area.
SimulationX 3 5-81
5-82 SimulationX 3
by
Analysis
Transient Simulation in the Time Domain
6 Analysis
The following sections give a description of the analysis available in SimulationX.
These are:
Transient Simulation in the time domain,
Animation of Results,
Steady State simulation in the frequency domain,
Calculation of the equilibrium state,
Linear system analysis.
Furthermore, the variant analysis is described. The third part will make you
familiar with the order analysis which is a tool used in the torsional vibration
analysis. Power and energy flows within a SimulationX model can be analyzed
with the Power Balance feature.
6.1 Transient Simulation in the Time Domain
The controlling of the simulation in the time domain is done using the buttons of
the toolbar Simulation Control. Check that Transient is set in the selection box
for the kind of analysis before beginning the computation.
Open Simulation settings
Equilibrium
Reset to last reset point
Reset to Start
Break / Single Step
Start Simulation
Terminate Simulation
Record Animation
The simulation in the time domain is performed from the start time tStart to
the stop time tStop.
SimulationX 3 6-1
User Manual 6. Analysis
The results are the time functions of the variables whose protocol attributes you
enabled. During the simulation the result windows are continually updated.
- Due to this ongoing update of the result windows (plot windows) one can
immediately observe the actual results and their progression.
In the mode Single Step just one step will be calculated. At t=tStart no time
step will be carried, but the calculation of initial values. The results of the initial
value calculation will be displayed in the model explorer. If the soft button Break
Single Step is kept pressed then the calculation of the single step will be
continued till button release.
If the Stop button is pressed, the simulation finishes the current time step in order
to ensure valid result data. If the Stop button is pressed a second time, the
simulation stops immediately and the time is set back to the last valid time step.
For large scale models the execution of this time step may be time consuming and
hence the simulation seems not to stop. In this case, pressing the Stop button a
second time the simulation stops immediately and the time is set back to the last
valid time step and the following dialog is shown.
Figure 6.1: Aborting calculation of equations
If a simulation is finished or is interrupted by pressing the Stop button or by the

occurrence of an error, the output window displays the current simulation time in
addition to the computation time.
The command Reset puts the model in the non-initialized state. This means,
simulation time is reset to tStart,
all result protocols and variables are deleted and,
if the result of a previous simulation has been saved as "Initial State" (see
6.1.1.3), the model is initialized with that state. The initial values (in the
elements and connections) of the model become disabled in that case, since
they will be ignored when starting a new simulation.
6-2 SimulationX 3
With the menu option Simulation Transient Settings or by the button the
parameters of the numerical solution algorithm can be changed. This applies to the
setting of numerical parameters (tabs General and Solver) and the display of
certain events during simulation (Tracing).
Your simulation model is transferred internally into a system of algebro-

differential equations. It is solved by the solver during simulation.
6.1.1 Simulation Settings

In the following all simulation settings are summarized and explained briefly.
Through the menu Simulation Transient Settings you open the dialog for the
Simulation Control.
Here you can change all settings for the computation of the model, e.g. simulation
time, step size, accuracy or solver.
6.1.1.1 General settings
Figure 6.2: General Settings
The section General of the dialog Simulation Settings contains the

following parameters (see Figure 6.2):
SimulationX 3 6-3
The simulation interval is defined by Start Time tStart and Stop Time
tStop. The stop time must be at least the same as the start time. If the stop
time is identical with the start time, the program only runs the event iteration
for the starting point.
The Scalable Real-Time Synchronization makes it possible, to bring the
simulation time in line with the real-time. Thus a model with a start time of 0 s
and a stop time if 60 s will be calculated in one minute, under the premise, that
the complexity of the model and its numerical features allows this calculation
time. With that interactive simulation, this means that parameters are changed
with control components, like sliders or switches, during the simulation, are
possible within real-time requirements. The definition of a Scale Factor makes
sense, when the designated simulation interval differs strongly from the defined
or reasonable time for an interactive simulation. Thus a simulation of the year-
round behavior of a building can be done in several minutes. For the
synchronization different modes are available:
No Synchronization (Standard Setting)
There is no synchronization. The calculation will be done as fast as possible.
Synchronization related to total time
SimulationX tries to meet the defined total calculation time. If there are
hesitations at some points during the calculation, later SimulationX will try to
regain this lost time.
Synchronization related to protocol interval
SimulationX tries to achieve a constant calculation speed. Hesitations can
sum up and led to a significantly longer total calculation time.
Synchronization of time events
This type of synchronization is suitable for example for models, which work
together with external components operating in real-time. In SimulationX
models this communication is triggered in most cases with time events.
These time events are created with the Modelica when sample(..) construct,
which is for example used in the SimulationX library
SignalBlocks.TimeDiscrete. If this type of synchronization is activated, the
execution of time events is stopped until the real-time reached the simulation
time.
If the synchronization is activated, the stop time of the model can be deactivated by
choosing Infinite in the corresponding combo box. Furthermore the recording of
results is set to equidistant automatically. During a infinite simulation the curves in
the result windows are displayed in a sliding time interval. The size of that interval
can be specified via Display Buffer Length.
6-4 SimulationX 3
Figure 6.3: General Settings Infinite Simulation
The Minimum Calculation Step Size dtMin is observed by BDF and

MEBDF solver (see. 6.1.3.1 BDF and MEBDF methods) except for the
detection of discontinuities. For CVODE, this can be specified through the
parameter bLimitdtMin (see also section 6.1.3.3. CVODE).
The Maximum Calculation Step Size dtMax defines the upper limit of the
step size used by the solver.
The default value is: (tStop-tStart)/100
This permits to perform at least 100 simulation steps. Limitation of the
maximum step size is important especially for models without any state
variables and events. Otherwise, the step size would grow up to the stop time
with such models. For models without state variables, the step size is increased
to dtMax after one successful step unless the step size is limited by an event.
For models with state variables that can be calculated without any problems as
they may have a linear time dependence, the step size grows gradually until the
stop time is reached unless it is limited by an event or dtMax. Please note that
dtMax can have a significant impact on the data logs under these
circumstances (see below).
SimulationX 3 6-5
The computation accuracy can be influenced with the parameters Absolute

Tolerance absTol and Relative Tolerance relTol. With these parameters
the program computes the maximum tolerance which may occur during a
simulation step:
relTol * absolute value of the state variable +
absTol * Nominal value
The Minimum Output Step Size dtProtMin defines how dense variables
are logged. The distance between two logged values is at least the minimum
output step size. Irrespective of this, events are always logged, if a suitable
setting is chosen for Recording of Results. If you want to log all computed
points, the minimum output step size selected must be less than or equal to the
Minimum Step Size. If equidistant logging is not used, dtMax>dtProtMin
applies and the maximum distance between two logging points is the maximum
step size dtMax if permitted by the solvers convergence.
The Minimum Step Size dtDetect is the smallest step size possible for
the solver during the detection of discontinuities, and has therefore a direct
impact on the accuracy of events and their detection. Moreover, dtDetect is
also the time interval for BDF and MEBDF solvers (see 6.1.3.1). The
distance of all time points from the start time and also the time steps are
integer multiples of dtDetect.
Via Recording of Results it is defined at which times and events results will be
recorded. The following options are possible:
Equidistant with dtProtMin
At least after dtProtMin
At least after dtProtMin and after Events
At least after dtProtMin, before and after Events
At least after dtProtMin and Eventsteps
Last Value
The values of the system variables described here tStart, tStop and
protKind (for logging events) can also be changed in the model explorer or
within the property window of the model. In both property dialogs, see the
additional variables, such as pre-defined variables of the simulation model that
have an influence on the simulation and the output:
termCond: Terminate the simulation when the condition is met before
tStop has been reached
traceOn: Activate the output (find more details in sections 6.1.1.4
and 8.2.7.)
protOn allows the conditional logging of results
(standard is true on), e. g. t >= 0.6 and t <= 0.7
loggs only values in the defined time range.
6-6 SimulationX 3
There is the possibility to save the custom user settings.

The current settings are stored in the registry as user-defined
default values. New models get assigned to these settings.
The model is set to the values stored in the registry.
The user-defined settings are deleted from the registry and set
the model to the built-in defaults.
6.1.1.2 Reset Points

A Reset Point allows you to reset a model after a simulation up to a certain time
tRP (with tStart < tRP < t). Reset points may be created manually or
automatically (dialog Simulation Control , page Reset Points), however you
must specify the creation of reset points before starting the simulation. In order to
reset a model to a certain reset point, you must open the Simulation Control
dialog, page Reset Points.
Figure 6.4: Dialog Reset Points
Select the desired reset point and click the Reset button on the right side of the
selection box. This function carries out the following actions:
The current simulation time t is set to the time of the reset point tRP.
All entries with t>tRP are deleted from the result protocols of variables.
All existing reset points after the selected reset point are deleted.
The model is reinitialized with the state of the selected reset point.
SimulationX 3 6-7
Figure 6.4 shows an automatic generation of 10 reset points after the starting point
over the simulation time. After a simulation run you can reset the model to one of
the generated points by using the dialog Reset Points again and start the
simulation from there.
6.1.1.3 Save Model Initialization

There are two possibilities to save the model initialization in SimulationX:
Save the initialization internally at a current Reset Point
Save the initialization externally in a file
Both methods should not be used simultaneously.
Saving the initialization internally enables you to define the state of a model at the
current Reset Point (or the current state, respectively) as the initial state for further
simulations. This might be useful for example, if the steady-state solution of a
model (calculated either by the transient or the steady-state solver) is to be used for
further transient simulations (variant analyses, optimization runs etc.). If such an
initial state has been defined (dialog Simulation Control, page Reset Points,
Save Initial State), the following actions are carried out:
The parameter "Start Time" tStart is set to the time of the current Reset
Point tRP. (Otherwise the calculation became inconsistent if the absolute time
t is referred somewhere in the model.)
The status line "Initial state is active" is shown in the dialog.
After Reset, the model is initialized automatically with the saved initial state.
The initial values in the elements and connections of the model are disabled, since
they will be ignored at the next simulation start.
However, the saved initialization state can be removed (dialog Simulation
Control Reset Points, Remove Initial State). In that case, the following
actions are carried out:
The parameter Start time tStart is reset to its original value.
6-8 SimulationX 3
The status line Initial State is not active is shown in the dialog.
After Reset, the model is not initialized.
With a restart of the simulation now again the initial values are used in the
elements and connections of the model.
Alternatively a user changeable initialization file can be generated in SimulationX.
It allows the user to change the values of parameters and variables in order to adapt
an existing model to the current needs without changing the model itself. It can be
also used to adjust starting conditions close to the real solution, to help the solver
to initialize the model properly, even if the underlying equation system is strongly
nonlinear. Another use case is to store the current state of a model at a certain point
in time in an initialization file and to restart a simulation from this state by reading
this file.
You can generate this initialization file (*.isi) by using the menu
Export/Initialization Data. It can be generated from in any status of the model
(e.g. non-simulated as well as simulated). The content is model specific.
If generated from a non-simulated model the file contains only the current values
of parameters. Variables are left out in this case. If it is generated from a simulated
model, it also contains the current values of variables.
The content of this file is plain text and can be modified with any text editor. The
syntax is aligned to Modelica equations. It consists of lines of the form:
<Identifier>=<Value>;
where <Identifier> denotes a parameter or variable instance inside the model.
In case the <Identifier> references a non-scalar variable, values can be given

for each component separately, e.g. sphere1.Fa[1]=3.5;. Non-scalar parameters
can be assigned using an array expression with literals, e.g.
rigidLink1.x0={1,0,0};.
Please note:
The initialization file does not contain the complete state of the model. For
example the state of buffers of Modelica delay operators or the internal state of
external objects is not contained.
The initialization files (*.isi) can be loaded with the parameter userInitFile
in the model. You can access this parameter by double-clicking into the diagram
view of the model on the tab General Parameters of the model properties:
SimulationX 3 6-9
Figure 6.5: General Parameters userInitFile
The parameter userInitFile is of type string and empty by default. The

storage path of the initialization file (*.isi) can be specified here. Backslashes in
the path have to be masked by an additional backslash, e.g.
C:\InitializationFiles\Test.isi must be entered as "C:\\InitializationFiles\\Test.isi".
Alternatively you can choose the initialization file in dialog by clicking the -
button.
If a path is specified, every time the simulation is started, the file is read in.
Also the parameter consistentInitialConditions with the default value

true is now accessible. It defines whether a calculation of consistent initial values
should be done after initialization or not.
If consistentInitialConditions is set to false, no computation of

consistent initial values is carried out and the simulation over time starts
immediately. This may result in unexpected simulation results if the values in the
file where changed manually.
If consistentInitialConditions is set to true, consistent initial values
are computed. During this computation the values of variables which are set in the
file can be overwritten again.
6-10 SimulationX 3
The value of consistentInitialConditions is also stored in the

initialization file (*.isi) and overrules the value with is specified in SimulationX!
So make sure to define the right value also in the initialization file (*.isi).
6.1.1.4 Tracing
A multitude of debug information can be displayed in the output area during the
simulation, in order to ensure fast and efficient trouble shooting. By using the tree
view, the display of various trace messages (menu option Simulation
Settings dialog, page Tracing) can be switched on or off.
Figure 6.6: Dialog Tracing
For the solver these messages mainly concern:

Summary (statistics of the arithmetical steps performed, time needed...),
current action (logs actions at the beginning of the BDF method, for the
calculation of the initial value and for equilibrium calculations)
information about valid and invalid steps,
display of the computed state variables, derivatives, Newton updates, residuals
and Jacobian matrices,
indices of the state variables,
state variables tending to exceed their limits
variance of the residuals after solution of the linear system (non-solvable linear
systems or rounding errors).
- Errors in residuals from solving the linear system (deriving from unsolvable
linear equation systems or rounding errors).
- Outputs for embedding (see 6.1.2.3) for BDF and MEBDF solvers (see 6.1.3.1)
SimulationX 3 6-11
Other tracing information refers to:

Modelica (outputs of trace and terminate instructions),
variables (discrete variables, exceeding of limits after changing between ranges
of different behavior),
events (time instant and sources of events),
timers (sources and values of time-dependent events).
Some of the information is only available for particular solvers. The BDF and
MEBDF methods generate the most extensive tracing information.
The trace information is displayed as a tree. There are the following types of
outputs:
Values
Information
Warnings
Errors
When you expand entries, you will get further information. The displayed variable
names must be interpreted according to the following rules:
_der_ denotes a derivative. In a mechanical connection
_der_connection1.v, for example, is the derivative of the speed
connection1.v. Thus, it is a synonym for the acceleration connection1.a.
An underscore _ in the name of a connection indicates, that this connection
connects to a compound, e.g., connection1_.p0
Expressions of the form compound1.connection1.p show model hierarchies,
meaning p of connection1 in compound1.
Variables, which really exist in the model (i.e., which do not contain _der_
or _), can be found using the search function. In order to apply this
function, mark the full variable name, click the right mouse button, and select
Find in Model from the context menu.
Values are displayed only if the traceOn parameter of the model is set to true
or the analysis of logical condition that is defined there returns the value true.
That way, the output can be limited to a certain time making an analysis much
easier.
With double-click on the diagram view you open the properties dialog of the
model where you have access to this parameter through the tab card General
Parameter.
6-12 SimulationX 3
For example, in order to restrict tracing to a time interval, you must enter the
following relation: t>0.5 and t<0.7 or use the relation displayed in the
following figure.
Figure 6.7: Tracing settings traceOn
The tracing settings are not saved with the model. They are stored in the Windows
Registry and apply thus to all models even after a restart of SimulationX.
6.1.1.5 Solver Settings

On the page General, one of the available solvers can be selected:
BDF-Method
MEBDF-Method
Fixed Step Solver
CVODE-Method
Solvers with the addition compiled C-code generate C-code of the model
algorithm which is automatically compiled and linked. This leads to an
acceleration of the computation. For these solvers one of the supported compilers
needs to be installed (see section 6.1.3).
Additional settings depend on the selection and are described in the respecting
sections.
SimulationX 3 6-13
By pushing the button on the page More you get access to

further solver parameters. When making changes, please be sure, that you know
what you are doing! Contact the ITI-Support in cases of doubt.
6.1.1.6 Settings for Symbolical Analysis

On the page Symbolic Analysis some properties of the global symbolic analyses
can be changed. The settings have following meaning:
No symbolic integration
The symbolic analysis does not try to integrate some equations symbolically
to reduce the number of states.
Numerical calculation of Jacobian matrix
Normally, the Jacobian matrix is calculated symbolically. Switching off that
feature, lets SimulationX calculate the Jacobian matrix (see (6.10))
numerically by difference quotients. The computation time needed for the
symbolic analysis before the simulation calculation decreases. Please
consider: the calculation of numerical Jacobians mostly needs more
computation time during the simulation calculation. Such matrices are
mostly less accurate than symbolically calculated ones.
Sometimes this switch helps if the Jacobian is singular at the beginning of
simulation, because of unfortunate start values.
Use alternative numerical differentiation of functions
Instead of the time derivative of the function with disturbance of input
values, a partial derivative with a difference quotient is used.
Resolve linear equation systems
It will determine the part of linear equations in an equation block and
resolved as far as possible.
Reduce large expressions (for C-code generation)
Problems of C-compilers with very large expressions are solved by the
introduction helper variables replacing big sub-expressions.
min/max functions create events
Due to changes in SimulationX and the Modelica standard, events can no
longer be created for min/max functions by default. If equations depend from
them, it might be necessary to have that, if the solution does not converge at
maximum/minimum points. That option can be enabled here.
Evaluation of initial parameters
Parameters with the attribute fixed=false are calculated using initial
equations during start of simulations. If these equations can be solved
explicitly and do not depend on other parameters, they are evaluated at
compile time. This can reduce the initialization time significantly.
Alternative selection of iteration variables
Sometimes, nonlinear equation systems are sensitive to the selection of
iteration variables. Selecting this check box, a different algorithm is used for
that, so that different iteration variables may be selected. This may help, if
6-14 SimulationX 3
solvers are not able to solve the system, especially in case of CVode and the
Fixed Step solver, if a nonlinear block cannot be solved.
Solve one-line blocks explicitly
To solve equation systems explicitly, it is sometimes necessary to divide by
the potential iteration variable, even if it can be zero. Usually this is avoided.
Using this switch, this will be done in case the local equation system contains
only one iteration variable and one equation. The assumption is, if it would
be a division by zero in the resolved case, that equation would be also
singular in the non-resolved case and therefore also not solvable.
No index reduction (Only for Steady State Simulation and Input-Output
Analysis):
If the equation system forms a DAE with a higher differential index,
normally some equations are differentiated symbolically to reduce the index.
This may lead to rectangular systems, which cannot be solved by Steady
State Simulation or Input-Output Analysis. In this case, use the switch to
avoid this.
6.1.2 Workflow of the Calculation over Time

After pressing the Start button, the Global Symbolic Analysis (6.1.2.1 ) starts.
The simulation in the time domain proceeds in the following steps:
Start Global Symbolic Analysis
Index calculation
same
Calculation of consistent initial values no
state?
yes
Time step
Prepare new time Success? no Message

step yes
yes Finished? yes Message

Event? no
no
Stop
Figure 6.8: Workflow of the simulation in the time domain
This step transforms the SimulationX model represented in the modeling language
Modelica into a computable form. The model is now in a solver-internal
representation. Consistent initial values are determined then. Time domain
SimulationX 3 6-15
simulation will start after that. After every successful time step the solver checks
whether an event (e.g. discontinuity) has occurred. In this case, the exact time of
this event is determined as precisely as possible, continuous integration is stopped
and the model is reinitialized.
The following section describes the steps in detail.
6.1.2.1 Global Symbolic Analysis

The global symbolic analysis transforms the model into a computable
representation and simplifies it. The following analyses steps are done:
Conversion of the hierarchical model into a flat one. To this end, compounds
and derived types are resolved.
Resolution of references
Substitution of simple equations
Determination of index range of loop variables
Determination of the dimension of variables
Conversion of multidimensional equations into one-dimensional Equations
Resolution of language constructs
Creation of discontinuities (Zerofunctions / root functions)
Introduction of variables for special functions
Assignment of variables to equations
Rearrangement of equations with respect to variables
Determination of the calculation order of the equations
Determination of states and equations
Index reduction
Symbolic calculation of Jacobian matrix
Depending on the selected solver the model is represented now either as an implicit
system of differential algebraic equations:
0 = f ( x, x&, p, t ) , (6.1)
or as a system of ordinary differential equations:

x&= f ( x, p, t ) , (6.2)
with:
x ..... State variables
x& .... Time derivatives of state variables
p ..... Parameters
t ...... Time
6-16 SimulationX 3
In the latter case, implicit parts of the model are solved by small linear or nonlinear
systems of equation during the evaluation of the right hand side (RHS) of the
equation.
6.1.2.2 Calculation of Consistent Initial Values

The initial values characterize the state of the model at the beginning of
calculation. You can define them in the connections and/or in certain elements (e.g.
Mechanics). In SimulationX the initial values are special parameters of the model.
They have the following properties:
They must be constant. The values are evaluated only at the start. You can also
input expressions and functions.
Initial values may be selected to be fixed or free . To this end, click on the
symbol at the right of the input field.
Figure 6.9: A fixed and a free initial value
For most libraries, all initial values in model objects and connections are set and
fixed to the value zero (e.g. the Mechanics libraries). For most models, this
represents the lowest energy level possible in a system.
Initial values can be entered and fixed in the elements property window or
the Model Explorer (see Figure 6.7). There are also variables with initial
values that are not linked to a separate start parameter, which is often the
case for Modelica libraries. In that case, the initial value of a variable can
be specified through the attributes dialog and fixed if needs be (see section
5.3)
Figure 6.10: Model of a one-mass oscillator with initial values
Initial values are consistent only when the values of the state variables and their
derivatives fulfill the differential-algebraic equation systems at the starting point.
The initial values of Ordinary Differential Equations (ODE) are always consistent;
meaning that for each set of the state variables initial values there is a solution to
SimulationX 3 6-17
the system (6.2). The computation algorithm must only compute the highest
derivatives of the state variables in that case. This is demonstrated using the
example of a mechanical one-mass oscillator:
Speed and displacement of the mass are given as initial values. As the initial value
for acceleration
m
a( t = 0 ) = 1100 (6.3)
s2
is computed automatically.
The situation is slightly more complicated if also algebraic parts occur in the
algebro-differential equation. Examples of this are:
Mechanical models with constraints (joints, transmissions),
Electric circuits with parallel capacitors (C-loops) or inductors in series
(L-nodes),
Hydraulic or pneumatic models with connections without volume.
This is called a system of Differential-Algebraic Equations (DAE). Here, the initial
values are no more automatically consistent as the following example shows:
Figure 6.11: Mechanical model with a constraint (transmission)
Transmission is obtained by the ideal (rigid) modeling of a gear.

You now could define initial values for angle and speed at both inertias. However,
not all combinations allow the solver to create a consistent initial state.
The following table gives some combinations:
1 Inconsistent and fixed
2 Inconsistent and free
3 Consistent and fixed
Table 6.1: Various combinations of defined initial values
6-18 SimulationX 3
In the first variant, initial values are defined and fixed at both sides of the gear.
However, they are not consistent. The algorithm cannot produce consistency as
free variables are not available. This faulty parameterization is frequently found
when initial values are defined only for one side (branch 1) of the constraint. The
initial values of J2 are still the default values and must be changed by the user.
Consistent initial values can be produced for the other two options: In variant 2
J2.om0 can be determined by the algorithm so that the constraint will not be
impaired. In the third parameterization the initial values are already consistent.
The following information shall help you in dealing with initial values:
Define as many initial values as possible and fix them. This will ensure that the
initial state which you desire will be obtained.
When using constraints, you should carefully decide where you want to define
initial values. Note that with constraints there are some initial values which you
cannot select freely but which must fit the constraints. Set such initial values to
free or fix them with a valid value.
Avoid free initial values with models which represent ordinary differential
equations. The algorithm will then select the consistent initial state arbitrarily
which might not be the one you want though.
The message Calculation of consistent initial values failed! could also point to an
error in the model. Refer to chapter 11 FAQs.
If the calculation of consistent initial values fails (at time t=tStart) try to define
a suitable homotopy, see section 6.1.2.3.
A consistent state must also be recreated after events (reinitialization of the model).
Then the same algorithm will be used. The information what state variables are
fixed or free will then be derived from the algebro-differential equation though.
The following variables will mainly be considered to be free:
purely algebraic state variables,
state variables with a derivative which, however, is not used at any point in the
model,
the highest derivatives of the state variables,
the 1st derivative if the 2nd derivative exists but is not used anywhere in the
model.
All other state variables are fixed and keep their values prior to the event. So they
cannot show any jump.
A frequent modeling mistake is that at certain events jumps are required for state
variables which are not capable of such discontinuous behavior, i.e. whose values
are recognized by the algorithm as fixed during reinitialization. Examples of this
are jumps of the voltage over capacitors which can be realized only with infinite
currents. Other examples are jumps of the transmission ratio of rigid transmissions
SimulationX 3 6-19
which cause jumps of the angle or angular velocity which are physically
impossible!
Note: An exception is found with the elements end stop and rigid
friction(rotatory or linear mechanics).
6.1.2.3 Homotopy
It may be that the calculation of consistent initial values or a steady state fails
although a solution exists. Then homotopy could help. Another application consists
in finding a particular solution when several solutions exist. This last case can
particularly appear for strongly nonlinear models from Thermal Fluid, MBS
Mechanics or Electronics.
Homotopy techniques
SimulationX supports three homotopy techniques:
1. Natural Parameter Homotopy with Modelica homotopy operator (see (6.6))
2. Automatic embedding with fixed-point homotopy (see (6.8))
3. Automatic embedding with Newton homotopy (see (6.9))
The Modelica homotopy operator is also accounted for when used for
automatic embedding in the model (see (6.6)).
They run after the following scheme:
1. The system of equations f (x ) = 0 (x denotes the independent variables, i.e.
state and their derivatives, during the Initial Value or Steady State
Calculation) is suitably augmented by the homotopy parameter
(in SimulationX models lambdaHomotopy) (6.4)
in such a way that a solution of the modified system
h ( x, ) = 0 (6.5)
can be easily computed for = 0 . The proceeding of this modification are

described in the following sections Natural Embedding, Examples of
equilibrium state calculations through natural embedding and Automatic
embedding.
2. After the solution of (6.5) for = 0 , curve tracing is used to focus again on
the original task at hand with h(x,1) = f (x ) . Curve tracing begins with = 0
and stops once = 1 has been reached.
Simplified description of the continuation method

The rough workflow of the continuation method can be described as follows:
6-20 SimulationX 3
Points of the result curve {z = (x, ) : h(x, ) = 0 } are determined consecutively starting
with (x(0 ) , (0 ) = 0) = z (0 ) = z (0,) = (x(0,) , (0,) = 0) (see Figure 6.12). The marker (0 ) refers to the
starting point for curve tracing, and in (0,) the modifier (,) marks the accepted
value (after the corrector iteration, see 2). That applies also to all other points
during curve tracing.
Figure 6.12: Example of curve tracing
Starting from a calculated point (x (i 1) , (i 1) ) = z (i 1) = z (i 1,) = (x (i 1,) , (i 1,) ) on the curve, the
calculation of the next point (x (i ) , (i ) ) = z (i ) = z (i ,) = (x (i ,) , (i ,) ) looks as follows (see
Figure 6.12):
1. Step size si > 0 and a tangent t (i 1,) in point z (i 1,) = (x (i 1,) , (i 1,) ) on the curve
h(x, ) = 0 define a new predictor point
z (i , 0 ) = (x (i , 0 ) , (i , 0 ) ) = z (i 1, ) + si t (i 1, ) = (x (i 1, ) , (i 1, ) ) + si t (i 1, ) (predictor step).
Tangent t (i 1,) is orthogonal to the derivative of all components of h to z ,
that is dh(z (i 1,) ) dz t (i 1,) = 0 .
2. The predictor point is iteratively improved by a Newton-like method
(corrector step): z (i ,0 ) z (i ,1) L z (i ,*) .
SimulationX 3 6-21
Figure 6.13: Example of one step during curve tracing
Natural Parameter Homotopy

If SimulationX does not compute the favored or cannot compute any solution, the
user can here apply his knowledge by a suitable change of the model.
Sometimes the user knows an approximate solution of the system for modified
parameter values which can be easily computed by SimulationX. Based on the
approximated results, SimulationX can find a numerically correct result for the
modified system (i.e. for = 0 ).
Known approximation values are provided as start values for the calculation of
initial values, i.e. values after initialization. They do not need to be fixed in order
to be changed for the calculation of initial values including embedding. In the same
way, values from before the equilibrium calculation are used as start values for
embedding during the equilibrium calculation. The way from the modified system
to the original system can be determined by use of the Modelica homotopy
operator. The change of the modified parameter then depends on the corresponding
homotopy parameter (see (6.6)).
In some applications the user knows different initial states for a modified value of
a model parameter. The choice of different initial values then determines different
solutions of the modified system. The Modelica homotopy operator and the
associated continuation method allow a description of the special path which
connects the known initial state for the modified system with the desired initial
state of the original model.
Initial values or parameter values have to be replaced during the modeling by an

expression
homotopy(actual, simplified) (6.6)
6-22 SimulationX 3
actual corresponds to the declaration equation or the value for which the model
shall be computed. simplified describes an expression for which an initial or
steady state is known and a salutation can be easily computed.
The operator homotopy(actual, simplified) is substituted by
actual + (1 ) simplified (6.7)
and the continuation method starts with = 0 .
Examples of equilibrium state calculations through natural embedding

The following MBS model (cf. Figure 6.14) possesses different steady states for
the parameter springDamper3D1.k=10.
For the value springDamper3D1.k=0 the stable and instable steady state are
known: revoluteJoint1.phiRel=pi/2 (cf. Figure 6.16)and
phiRel=-pi/2(cf. Figure 6.15).
One of this values can be chosen as initial values for springDamper3D1.k=0.
Figure 6.14: Diagram view
Figure 6.15: Instable steady state for k=0, phiRel0=-pi/2
SimulationX 3 6-23
Figure 6.16: Stable steady state for k=0, phiRel0=pi/2
Now we insert the expression homotopy(10,0) as new value for

springDamper3D1.k. Dependent on revoluteJoint1.phiRel0 the stable or instable
steady state will then be computed for springDamper3D1.k=10 (cf. Figure 6.17
and Figure 6.18).
Figure 6.17: Stable steady state for k=10, phiRel0=pi/2
Figure 6.18: Instable steady state for k=10, phiRel0=-pi/2
Thus the computed steady state can be determined by use of homotopy.
6-24 SimulationX 3
Figure 6.19: Homotopy path of the stable steady state: revoluteJoint1.phiRel as a

function of the homotopy parameter lambdaHomotopy ( in (6.4))
Figure 6.20: Homotopy path of the instable steady state: revoluteJoint1.phiRel as a

function of the homotopy parameter lambdaHomotopy ( in (6.4))
Artificial Parameter Homotopy

When the application of the Modelica homotopy operator is not immediately
obvious or has been failed then artificial parameter homotopy can be an alternative
(see (6.6)). It can be enabled by the parameter iHomotopyType at the dialog
Simulation Control Solver MoreFurther Parameters (only visible if
SimulationX 3 6-25
the BDF Method or the MEBDF Method is set in the dialog Simulation
Control/Solver/General. For the default value iHomotopyType = 1, natural
embedding is used exclusively if the Modelica homotopy operator is in use
somewhere in the model (6.6).
For values 2 and 3, the following applies:
a. Fixed Point Homotopy (iHomotopyType=2)
g (x, ) = h(x, ) + (1 ) ( x x0 ) (6.8)
b. Newton Homotopy (iHomotopyType=3)
g ( x, ) = h( x, ) + (1 ) (h(x, ) h(x0 ,0)) (6.9)
(If the Modelica homotopy operator is not in use throughout the model (see (6.6)),
(6.8) and (6.9) only have f (x ) instead of h(x, ) . x0 is the vector of the state
variables and their derivatives (where applicable) before the calculation of initial
values and the equilibrium calculation. If the dimensions of h und x do not match
during fixed-point homotopy (6.8), all components of h are multiplied by , but
the summand (1 ) (x x0 ) is only added for the dimensional minimum of h and
x . That allows for automatic embeddings to be used with and without the
Modelica homotopy operator. Even without the Modelica homotopy operator, the
homotopy parameter is part of the equation system, and one for = 0 is
apparently x = x0 .)
Tracing/Result windows
The results can be analyzed via the Output (see section 6.1.1.4) or Result
Windows (see section 7.3). Since the values are not recorded as a function of the
time t, examine result variables as a function of the homotopy parameter
lambdaHomotopy (Model Explorer or in the property dialog under
Properties/General Results) or use the Result Window transformation Index
(Result Window Menu: Insert/Transformation / Index). Then result variables can
be viewed solely.
The recording of results during the calculation of initial values via homotopy has
to be enabled. Set the value of bProtocolValuesForHomotopy (dialog
Simulation Control SolverMore Further Parameters) to true. The
result window transformation Index shows all values over the corresponding
sampling point (index number) during curve tracing.
The tracing allows a complete overview (with BDF method or MEBDF method)
about all computations and helps to find reasons when the simulation fails. The
values of states, newton updates, jacobians, or the Errors in the Residuals at an
actual iteration step (Actual Action) during the continuation method as well as the
6-26 SimulationX 3
current step size (Solver Homotopy Step size for homotopy) and the
computed tangent space can be traced (Solver Homotopy Computed
Tangent Space).
The tangent space consists of all vectors whose product with the Jacobian yields
the zero vector. In the case of one-dimensional solution curves it corresponds with
the tangent at the currently calculated point. It is also possible, however, that the
solution set and thus the tangent space are of higher dimensions.
The magnitudes of the calculated states during the continuation method can spread
widely. Thus the continuation method works with scaled values. The scaling can
be viewed after activating the tracing Solver Homotopy Step size for
homotopy (only with BDF method or MEBDF method).
Special Parameters of the continuation method

Changing special method parameters can help when the continuation method fails.
The following parameters can be found in the dialog Simulation Control
Solver More Further Parameters (only visible if BDF or MEBDF method
is selected in the dialog Simulation Control/Solver/General).
iHomotopyType (Standard value: 1)
Used Homotopy technique:
1 only Modelica-Homotopie operator (see (6.6) and (6.7) and the
equation system (6.5));
2 Fixed Point Homotopy (with or without Modelica homotopy operator)
3 Newton Homotopy (with or without Modelica homotopy operator)
bUseBorderForHomotopy (Standard value: false)
true: If a solution cannot be found for over-determined systems, additional
variables are introduced.
dblMaxPredictorDistanceForHomotopy(Standard value:
1e10)
Maximum length of the first Newton update in a single continuation step
- should be decreased for a more exact calculation of the solution curve.
Then more steps of the continuation method are computed.
dblMaxConvergenceRateForHomotopy (Standard value: 0.1)
Upper bound for the calculated convergence rate.
- should be increased (until a values less than 1) when many steps are
discarded due to poor convergence
SimulationX 3 6-27
iMaxIterForHomotopy (Standard value: 10)

Maximum number of corrector iterations in a single continuation step
- should be increased when the iteration does not converge after this number
dblStepMinForHomotopy (Standard value: 1e-8)
Minimum step size
dblStepMaxForHomotopy (Standard value: 10)
Maximum step size
dblStepSizeAtBeginOfHomotopy (Standard value: 0.2)
(Scaled) step size at the beginning of the continuation and after changing the
discrete state during curve tracing: this ist he starting step size; should be
between minimum and maximum step size;
- can be increased when the continuation path is almost linear
- when set too high, returns many invalid steps at the beginning of the curve
tracing or after changing the discrete state
blStepSizeReductionForHomotopy (Standard value: 0.5)
Reduction factor of the step size at discarded steps
dblAngleMaxForHomotopy (Standard value: 0.3)
Maximum angle (unit: Radian, less than 2 1.57) between tangent spaces
of successive continuation steps
- the step will be discarded for angle values greater than this value
- should be increased when too many steps are discarded due to exceedance
of this limit
- it can happen that the solution path goes back (the homotopy parameters
return to zero) when this value has chosen too high
iMaxPointsForHomotopy (Standard value: 1000)
Maximum number of continuation steps
- should be increased when the continuation aborts before
lambdaHomotopy=1 had been reached
dblBoundWrongDirForHomotopy (Standard value: -0.5)
Lower bound for the homotopy parameter lambdaHomotopy (value<0)
- if lambdaHomotopy deceeds this value, the direction of the continuation
path will be reversed and the lambdaHomotopy is reset to zero
bAlwaysGlobalNewtonForHomotopy (Standard value: true)
Use a global Newton method during the corrector iteration
- can ameliorate the convergence behaviour, but the number of Jacobian
computations increases
6-28 SimulationX 3
bScaleRHSForHomotopy (Standard value: true)

Scale lines in the Jacobian matrix and the residus for the homotopy method:
Scaling lines may improve results of the linear equation system
dblMinScaleRHSForHomotopy (Standard value: 1e-100)
Only scales lines of Jacobian matrix with this minimal norm:
If values per line are large enough, the line is multiplied by a factor for
bScaleRHSForHomotopy = true. Lines with small values remain
unchanged and are treated as if they contain plenty of zeros.
The boundary can be adjusted if values in the Jacobian matrix are larger or
smaller.
bUseHomotopyFirst (Standard value: false)
Only scales lines of Jacobian matrix with this minimal norm:
If values per line are large enough, the line is multiplied by a factor for
bScaleRHSForHomotopy = true. Lines with small values remain
unchanged and are treated as if they contain plenty of zeros.
- The boundary can be adjusted if values in the Jacobian matrix are larger or
smaller.
bProtocolValuesForHomotopy (Standard value: false)
Set to true to record the results of the homotopy for the result windows
iMaxRetryForHomotopy (Standard value: 10)
Maximum event iterations after a valid step during curve tracing:
If a discontinuity is detected for embeddings, the discrete state applies
((ME)BDF method only). Afterwards, the system tries to find consistent
values for the new discrete state. If it fails to do so, the system starts over
closer to the discontinuity.
If accurate values for the discontinuity are hard to find and there is only a
consistent state directly at the discontinuity, it is possible to increase the
value. This will not help, however, for massively non-linear models with
surges at such discontinuities.
iMaxRepeatForHomotopy (Standard value: 1000)
Maximum number of event steps per event iteration for curve tracing:
This number should be larger than the maximum number of event steps
required, before a cycle occurs in the event iteration.
If the cycles are shorter, the number can be decreased and the event
iteration is discarded earlier.
SimulationX 3 6-29
6.1.2.4 Time Steps

For computation of the time steps several solvers are available. The solver is
selected in the dialog Simulation Settings, register General. More
information about the solvers can be found in section 6.1.3.
6.1.2.5 Events
An event is a time instant during the simulation run at which:
state variables or their derivatives change in leaps and bounds (discontinuities)
and/or
the structure of the equations changes.
Discontinuities can depend on the time:

time-discrete signal blocks,
expressions sample() or delay().
However they can also be influenced by the state of the model:

at the sampling points of characteristic curves for linear or staircase
interpolation,
changes between contact and backlash with spring damper backlash elements,
conditional instructions as if x>10 then 0 else 5.
When the structure changes, other equations apply from one moment to the other
or their number changes. Examples of structure changes are:
change between sticking and sliding friction in mechanics,
ideal mechanical end stops,
opening and closing of ideal electric switches.
Time-dependent events are passed on internally to the event queue of SimulationX.
The step size control of the solver ensures that computation proceeds up to these
time instants and event processing will start then.
State-dependent discontinuities are detected by means of so-called zero-functions.

They change their algebraic sign at the event instant. When a sign change is
expected, the step size is selected so that the event is met as precisely as possible.
When such a sign change occurred within a time step, the system attempts to meet
the event even better. The system will then interpolate zero-functions for state-
dependent discontinuities. If dtDetect remains behind the interpolated
estimation for the event point by the minimal step size at most, the continuous
integration is stopped and the event iteration is started. So you can use dtDetect
to set the accuracy with which you hit the events. The value should not be higher
than the minimum step size. The minimum step size should be an integer multiple
of dtDetect.
6-30 SimulationX 3
The values of elementary relations remain constant during integration, i.e. a short
time before the event iteration the old values are used, although the relation may
have changed already. At the event time the integration is stopped and an event
iteration is started. During the iteration the model time remains constant.
During the iteration the values of the relation adjust to the real situation and new
consistent initial conditions are calculated at the same time instant. Thus at the
discontinuity you get two points in the protocol of a variable at the same time, one
before the iteration and one after.
For the event iteration the discrete variables play an important role. They can
change their values only at event times. If a discrete variable changes its value
because of the new consistent state, the iteration is repeated. Only when each
discrete variable keeps its value the event iteration terminates and the integration
continues. It may happen for some model that its discrete variables dont stop
changing in the process of event iteration. In most cases this indicates a modeling
error. Then the simulation stops with the error message "Cycle found in the event
iteration".
The operator noEvent can be used to prevent that certain relations trigger
unintentional events.
Example:
y:=noEvent(if u>uMax then uMax else if u<uMin then uMin else u);
The expressions in the if instructions are evaluated directly without keeping the
values of the relations constant and without producing events.
You can use this to protect the domain of a function:
y:= if noEvent(x>=0) then sqrt(x) else 0;
Without noEvent an error would take place, because a short time before the event
iteration x is already negative, but x>=0 is still true.
The operator noEvent should be used only after careful consideration as it can
mask events which are required for exact computation.
noEvent is absolutely applicable and its use is even to be recommended, for
instance, in the following cases:
The event has no influence on any state variable. This is often the case when
model parts are merely used for evaluation. The continuous integration can then
proceed with the computation over this time instant without any problem.
However, a certain error must be expected in the relation as it cannot be
ensured that the change-over instant is hit exactly.
To intercept values out of the domain of operations and functions (e.g. division
by zero, tan, arcsin ...).
SimulationX 3 6-31
The result changes the slope of a function only to a small extent (e.g. linear
continuation of the exponential function).
You use a relation to produce a continuous run of the highest relevant
derivative of a state variable.
We want to explain this last point with an example:

Parts of sin functions are frequently used as nominal functions for positioning
processes.
You can generate such a signal with the expression:
if t<=0.5 then sin(pi*t)^2 else 1
An event is generated automatically at 0.5 sec for the relation even though there is
no discontinuity there at all. The noEvent operator:
if noEvent(t<=0.5) then sin(pi*t)^2 else 1
results in the suppression of the event and therefore to an acceleration of the

computation without any loss of accuracy here.
Figure 6.21: sin part as value for a positioning process
The noEvent-property has effect on all relations inside the noEvent function.
All statements within a when-statement are implicitly handled as if they would be
contained in a noEvent function. This is not a restriction, because the body of the
when-statement is not evaluated during normal integration.
6.1.3 Available Solvers

SimulationX provides different solvers for the transient simulation:
BDF method (Backward Differential Formulas). This solver corresponds to an
extension of DASSL [1].
MEBDF method (Modified Enhanced BDF). This is a solver which has been
developed by Jeff Cash [2]).
6-32 SimulationX 3
Fixed Step Solver

CVODE method. Solver from the SUNDIALS Suite [5]
(see: www.llnl.gov/casc/sundials/)
The solver is selected in the dialog Simulation Control, tab General.
Solvers with the addition compiled C-code use a compiled representation of the
model algorithm to increase the computation speed. SimulationX supports the C-
Compilers of the Microsoft Developer Studios (version 6 and above, also the free
Express Editions). One of these compilers must be installed on the SimulationX
computer and can be selected in the dialog Simulation Transient Settings,
tab More, group Compiled Simulation.
6.1.3.1 BDF and MEBDF Solver

Both solvers are well suited for following models:
- Non stiff or stiff models (systems having eigenfrequencies and/or time
constants in a wide range).
- Models with discontinuities. Event handling is done as shown in section
6.1.2.5 Events.
- The MEBDF-solver is especially designed for models with higher index (e.g.
MBS-models with closed loops). The results for such models are more accurate
and the simulation speed is often faster.
The solvers use either a SimulationX internal representation of the model for
the RHS calculation according to (6.1) or a compiled form. Without C-code the
preparation of the calculation goes faster, but the RHS calculation is slightly
slower.
Figure 6.22: Predictor-corrector method
SimulationX 3 6-33
Both algorithms are predictor-corrector methods with automatic control of step

size and order (k). With this kind of implicit multistep method the current value is
extrapolated from (k + 1) already computed values for every state variable
(predictor). This value is improved iteratively until the desired accuracy is obtained
and certain convergence criteria are fulfilled (corrector).
If the corrector value is accepted, the next time step can be dealt with. To this end,
a new step size and/or order is computed from the iteration curve.
If after a certain number of iterations no corrector value is obtained which fulfils

the accuracy requirements, step size and/or order are decreased and the complete
time step is repeated.
The Maximum Order can be changed in the dialog Simulation Control, tab
More. It indicates how many of the time steps which have been computed
already may be included in the computation. During a simulation the system
performs an automatic control of the order. When the maximum order selected is 1,
the method corresponds to the implicit Euler method.
When the minimum step size is reached and convergence has still not been
obtained, we get a hint. You should always reduce the minimum step size first
then. Only if this does not help, the error bounds may be relaxed. A reduction of
the maximum order is only required with strongly non-linear models where the
methods with the default settings compute slowly or do not find any solution at all.
The automatic control usually ensures that always the optimum order is used for
computation.
During each corrector iteration a linear equation system must be solved:
res = J ( xi 1 xi ) (6.10)
where:
res .. Residuals
x ..... State variables
i ...... Number of iteration
J ..... Jacobian matrix
The following methods are available for this:

Sparse Matrix Solver,
Gauss method,
Scaled Gauss method.
Select one of the methods by means of the dialog Simulation

Transient Settings, tab card More. By default the Sparse Matrix solver
6-34 SimulationX 3
is selected. This solver takes advantage of the fact that mostly only local
dependencies exist with the equation system to be solved. For example, with a
drive line the state variables at the engine depend only indirectly via other state
variables on those at the wheel. This causes many zero entries in the Jacobian
matrix which need not be considered in the solution. This leads to a considerable
faster computation as compared with the Gauss solver.
The Gauss Method is recommended for extremely strongly meshed models
where no sparse Jacobian matrices are found. However, this case is very rare.
Models with strongly differing time constants or high changes of the magnitude of
the state variables can feature badly conditioned Jacobian matrices. The above
mentioned methods will no longer be suitable then to compute an exact solution.
This can lead to a bad convergence in the corrector steps (many corrector
iterations, small step sizes) or even to the cancellation of the simulation. The
Scaled Gauss Method attempts to improve the condition number and thus to
yield a better solution.
Every model contains the variable Solver Debug Info solverInfo which is filled
by the solver. The BDF or MEBDF solver writes the following nine components to
this vector:
1. Order.
2. No. of corrector steps for predictor-corrector iterations.
3. No. of discarded steps (invalid or discarded because of an event) between the
last successful and the current step.
4. No. of steps with too big error estimation between the last successful and the
current step.
5. No. of discarded steps because of lack of convergence between the last
successful and the actual step.
6. Recommended change of the step size (interesting in the context of event steps
and discarded steps).
7. No. of RHS calculations in invalid and valid steps (not during event iterations)
8. No. of discontinuities (Event iterations)
9. No. of Jacobian matrix computations.
10.No. of event-steps, including internal event iterations, at the equilibrium
calculation and embedding
11.Number of substitute event steps in event iterations: for example, for collisions
with end-stops, a numeric integration of (motion) equations (to maintain the
conservation law of momentum) is required; in this case the substitute event
steps during the event iteration are checked for changes in the discrete state of
the system; if changes are found, the next step is suppressed and the equation
system is re-calculated.
SimulationX 3 6-35
6.1.3.2 Fixed Step Solver

This solver was integrated in SimulationX to be able to test models for real-time
capability. It includes five explicit methods for the solution of explicit ordinary
differential equations (ODE) according to (6.2) which are also available for the
Code Export project types Executable model, Matlab/Simulink S-Function,
CarSim, BikeSim, TruckSim component and the targets for real-time
simulation SCALE-RT, dSPACE DS1006, NI VeriStand,
B&R Automation Studio or ETAS Labcar.
In SimulationX you can find out what step size must be presumably chosen for a
stable calculation of such models which are intended for the export to real-time
platforms.
For this solver, the same restrictions as for C-code export are to be considered.
The Min. Calculation Step Size dtMin is the only quantity (beside tStart/
tStop) in the dialog Simulation Control, tab card General on which the
calculation of state variables depend. The step size remains constant throughout the
simulation.
As a result events can consequently not be detected exactly. Inaccurate results can
follow when chosen a too big dtMin. It will be checked once at each time step
(after the calculation of the states) whether a zerofunction has changed its sign.
The potential event iteration will then be carried out subsequently.
In the dialog Simulation Control, tab card Solver you have the choice
between five Integration methods. Their difference consists in their order and the
number of RHS computions (RHS: Right Hand Side or model evaluations) per
time step.
0 : Euler Forward (1 RHS computation, order 1),
1 : ITI Standard (1 RHS computation, order 2),
2 : Heuns Method (2 RHS computations, order 2),
3 : RKF23 (3 RHS computations, order 3),
4 : DOPRI5 (6 RHS computations, order 5).
Responsible for the differing number of RHS computations is the method order
which represents a degree of accuracy of the numerical approximations. As models
are usually not linear and contain discontinuities, eigenvalues often depend on the
corresponding working point in such cases. It is thus advisable to experiment with
various methods and several step sizes dtMin between 1.E-003 and 1.E-006.
6-36 SimulationX 3
Figure 6.23: Stability domains (except ITI Standard whose stability domain is located
inside of those of Euler Forward)
Remark: Stability requires: dtMin has to be chosen such that the product
dtMin lies inside the stability domain for all eigenvalues with negative real
part. Hence a larger stability domain promises theoretically calculations with a
bigger step size.
However our present experience often shows that being able to choose a larger
model step size due to more stability does not compensate the longer computation
time due to multiple calculations of the model.
The total number of RHS calculations can be calculated as follows

RHS calculations = FE * (tStop/dtMin + Event steps).
Hence the computation time grows with
an increase of the method order,
a decrease of dtMin or
many discontinuities and time events.
SimulationX 3 6-37
We recommend to try different methods and different step sizes in the range
between 1.E-003 and 1.E-006 until you obtain the desired results, beginning
with iMode = 1 or 0 and dtMin = 1.E-005.
Under Further Parameters... in the register Morethe following settings can

be changed furthermore:
A change of the parameters blockTol or blockLinSolv should be
proved when the solution of block equations has been failed (see 11.3.2).
The Simulation usually fails/terminates when the values of state variables are
below a given minimum or above a given maximum. Setting
bStateMinMax=true prevents this limit violations (by holding the state
variable on its limit) and thus improves real-time capability. (The
minima/maxima have to be constant.) The value of bIgnoreMinMax is
ignored in this case.
If bIgnoreMinMax is set to true given minima/maxima for state
variables are ignored.
By activating the option bOptimization it is possible to increase the
calculating speed. Then the compiler will use the compiler option /O2. Be
aware that this can result in a significant longer compile time.
16
An object file can hold up to 65,536 (2 ) addressable sections. Setting
bBigobj=true increases the address capacity to 4,294,967,296 (232).
Note: An .obj file produced with /bigobj can only be consumed by a
linker that shipped in Visual C++ 2005 (or later).
6.1.3.3 CVODE
This solver can be applied to following models:
- Stiff or non-stiff models (systems having eigenfrequencies and/or time
constants in a wide range).
- Large models are computed mostly faster compared to the (ME)BDF-solver.
This is caused by the compilation of the model algorithm.
Due to the compilation process, the preparation of the calculation takes a bit longer
than using the (ME)BDF-solvers without compiled C-code. Therefore we
recommend the usage of this solver for models, with fixed structure and varying
parameters (e.g. in variant calculations).
For this solver, the same restrictions as for C-code export are to be considered.
Please refer to the latest release notes of your SimulationX version for details.
The solver is part of the SUNDIALS Suite (see: www.llnl.gov/casc/sundials/).

Please consider the license note of the original code:
Copyright (c) 2002, The Regents of the University of California.

Produced at the Lawrence Livermore National Laboratory.
6-38 SimulationX 3
Written by:
S.D. Cohen, A.C. Hindmarsh, R. Serban, D. Shumaker, and
A.G. Taylor.
UCRL-CODE-155951 (CVODE)
UCRL-CODE-155950 (CVODES)
UCRL-CODE-155952 (IDA)
UCRL-CODE-155953 (KINSOL)
All rights reserved.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND

CONTRIBUTORS"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE REGENTS OF THE UNIVERSITY OF
CALIFORNIA, THE U.S. DEPARTMENT OF ENERGY OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
OF SUCH DAMAGE.
It was slightly changed and integrated into SimulationX by ITI.
CVODE is a solver for explicit ordinary diffential equations (ODE) according to

(6.2). It uses either BDF or Adams formulas for integration. After pushing the
button Further Parameters in the dialog Simulation Control, tab card
More you can choose one of these methods (bStiff). The Adams method
may be more efficient for non-stiff models.
As with (ME)BDF solver the maximum order of the BDF variant can be reduced.
An increase often leads to a higher simulation speed when the solver works
primarily with a low order. Latter can be found out easily with the Solver Debug
Info vector [1]. The default value is 5.
The maximum order of the Adams variant is 12. When you choose bStiff=false
this value will be set automatically by the solver and cannot be changed.
Considerably less RHS calculations, particularly for models with a sparse Jacobian
matrix, and consequently an obvious decrease of computation time can be achieved
by a more efficient computation of the Jacobian matrix. By default, it is enabled in
the dialog Simulation Control, tab card More in combination with a Sparse
Matrix solver for the solution of the linear system. It can also be combined with a
Gauss Method or disabled in certain circumstances (Without Efficient Jacobian
computation).
SimulationX 3 6-39
Under Further Parameters... the following settings can be changed

furthermore:
A change of the parameters blockTol or blockLinSolv should be
proved when the solution of block equations has been failed (see 11.3.2).
Events are treated as described in section 6.1.2.5. You can switch off the
exact localization of roots of zerofunctions setting bZeros=false. This leads
sometimes to higher simulation speed but to a loss of accuracy. State events
are located later in this case.
The algorithms for exact localization of events can consider a hysteresis. This
feature is avtivated by the parameter bHysterese. In this case events are
located when the corresponding zero functions are different from zero by a
certain value (parameter Epsilon). Events are located a little bit later in
this case. For certain models cycles during event iteration and disconuitiy
sticking can be avoided. Epsilon should not be larger than 10-8..
By default, the minimum stepsize for CVODE is not limited from below. A
lower limit can be set via the parameter bLimitdtMin.
The parameter bParJac controls if the Jacobians are computed in parallel.
Parallelization reduces the computing time for models with costly model
calculations and many state variables. However, the overhead caused by
thread management and copying data can lead to longer computing times for
smaller models.
By activating the option bOptimization it is possible to increase the
calculating speed. Then the compiler will use the compiler option /O2. Be
aware that this can result in a significant longer compile time.
16
An object file can hold up to 65,536 (2 ) addressable sections. Setting
bBigobj=true increases the address capacity to 4,294,967,296 (232).
Note: An .obj file produced with /bigobj can only be consumed by a
linker that shipped in Visual C++ 2005 (or later).
If bIgnoreMinMax is set to true given minima/maxima for state
variables are ignored.
For details about the algorithms inside CVODE please refer to [5] and referenced
papers.
Comparable to the BDF solver CVODE writes the following nine components to
the vector solverInfo:
1. Order (at time t<=tStop)
2. Changing factor of the step size
3. No. of RHS calculations (until time t)
4. No. of iteration steps within one event iteration (enable Recording of Results
At least after dtProtMin (before) and after Events necessary)
5. No. of Jacobian matrix computations (until time t)
6-40 SimulationX 3
6. No. of code generations (until time t) (only for Sparse Matrix solver)
7. No. of decompositions (until time t)
8. No. of solving the linear system (until time t)
9. No. of discarded steps (at time t)
6.1.4 Performance Analyzer

The performance analysis (menu Simulation/ Performance Analyzer) can help
you to identify critical i.e. stiff or nonlinear model parts. Furthermore, it allows
you to keep track of the number of events that occur during calculation and the
amount of event iterations necessary to keep the model stable.
a) View of the influence of state variables b) View of the number of changes of

on the calculation performance discrete variables in event iterations
Figure 6.24: Diagram view of Performance Analyzer
6.1.4.1 Output
For each state variable the solver computes an error estimate. These values are then
weighted and their sum over all time steps is displayed in the column Influence.
At each time step the Fixed Step Solver computes for each state variable (column
States) two numerical approximations whose difference is scaled and summed up
during the simulation. This sum is displayed in the column Influence.
The solver increases counters denoting the changes of discrete variables which
may occur during event iterations. Furthermore, the solver also counts zero
crossings of zero functions that induce events. The results are listed in the column
number of changes and number of zero crossings respectively.
SimulationX 3 6-41
6.1.4.2 Result Interpretation

By the Performance Analysis we can specify those states that mostly inhibit step
size increase and model parts which have to be changed. A model which doesnt
run in real-time yet can be reduced more easily with this information.
The number of events and the iterations necessary to reach a stable state after an
event occurred can have a great impact on the overall performance of the
simulation.
6.1.4.3 Handling
(1) The Performance Analyzer must be enabled before its use (Checkbox
Activate Performance Analyzer). If we are solely interested in a certain
time interval [t1 , t 2 ], t1 > 0, the (de-)activation can also happen during the
simulation.
(2) Setting Record values during simulation time all summed up values at
the corresponding simulation time will be recorded. After stopped or
finished the simulation they can be pursued over time with the help of the
scroll bar.
(3) Otherwise only the values at the actual simulation time are displayed
(press Update or Update list automatically).
(4) Clicking on the head of the list columns affects a sorting after number
(No.) or name (States, discrete variables or zero functions) of the states or
the computed values (Influence, number of Changes or number of zero
crossings).
(5) The tab control element at the top of the list allows switching the view
between the estimated influence of state variables, the changes of discrete
variables during event iterations and the zero crossings of zero functions
on events.
(6) By clicking on an entry, the corresponding component within Structure
View and Model explorer can be directly reached enabling intuitive
assigning of the state variables or corresponding model parts to the
monitored entry.
6.2 Animation of Results
The results of a transient simulation can be recorded and replayed in real-time as
an animation. During running animations motion sequences can be checked within
the 3D-View.
The animation can be controlled and adjusted with the following commands:
6-42 SimulationX 3
Animation of Results
Record Video
Animation Time Change
Open Animation Control
Animation in a Loop
Forward to End
Step Back
Step Forward
Back to Start
Start Animation
Terminate Animation
In the result windows (see Figure 6.25) with Y(t) or Y(x)-diagrams respectively a
cross wire is discernible that follows the progress of the result curve during the
animation.
Figure 6.25: Animated hair cross in a result window with Y(t)-chart
SimulationX 3 6-43
In the result window with a Bar chart (see Figure 6.26) the bars size will be
changed dynamically in accordance to the value of the associated result variable.
Figure 6.26: Animated Bar chart in a result window
Within the diagram view visualizer as well as element symbols and forms with
dynamic properties of appearance allow the additional visualization of results.
Figure 6.27: Animated Modelica graphics
Connections can be animated with different colors depending on values of result

variables. So it is possible to observe result variables of connections, e.g.
temperatures, during simulation without using a result window.
Figure 6.28: Animated Connection (5)
On the tab Visualization within the connection properties dialog you can select a
result variable which should be animated. This result variable will be animated at
connection line according to the specified limits with different colors.
6-44 SimulationX 3
Animation of Results
The following modes for coloration are available:

Color gradient between minimum and maximum
Discrete colors for permissible and impermissible areas
Figure 6.29: Settings for the visualization
The animation of a 3D-View can be saved as video file that can be played back
with an external player (e.g. Windows Media Player). It can also be given to a third
party and can be included in presentations or web sites.
6.2.1 Record a Animation

In order to animate the calculation results in real time it is necessary to record the
transient results of a simulation. For this the soft button Record in the tool bar
Simulation Control has to be pressed prior to the simulation run.
At the end of the calculation at time tStop the edit box for the mode of Analysis
will be set to Animation automatically. If this behavior is not the wanted you
can open the dialog Options in the menu Extras. Here choose the tab
General and deactivate the option Switch to Animation after Recording.
6.2.2 Play back the Animation

At first you have to make sure that in the tool bar the Simulation Control is set to
Animation. If the soft buttons for the control of the animation are not enabled
no recorded calculation results are available for the play back of an animation. In
this case results of a transient simulation have to be recorded.
6.2.3 Saving of 3D Animations for external Presentation

You can save the animation in AVI-, WMV-format for a replay in an external
player. With the button in the toolbar you start the rendering of the animation
to the video.
Before saving the file name, type and location as well as further video settings can
be specified (see Figure 6.30).
SimulationX 3 6-45
Figure 6.30: Video settings
Via a selection field (see Figure 6.31) you can choose afterwards a video
compression (which exists on your computer), in order to save storage capacity.
Figure 6.31: Selection of video-compression
6.3 Periodic Steady-State Simulation

The Periodic Steady-State Simulation serves for the computation of periodic limit
cycles of nonlinear and linear systems in dependence of a reference quantity (as,
for example the mean angular velocity of a rotational mass).
Some important fields of application are:
oscillation analysis of powertrains with combustion engines
computation of the describing function of nonlinear dynamical blocks in control
systems
Computation of harmonic distortions of electronic amplifiers and filters in
dependence of the amplitude of excitation
hydraulic and pneumatic test benches for oscillatory long-term stress analysis
The applied periodical ansatz is supplemented by a linearly time dependent term to
take the steadily growing angles of rotating masses in the oscillation analysis of
freely rotating powertrains into account.
6-46 SimulationX 3
Periodic Steady-State Simulation
The following frequency-domain quantities can be displayed for the computed re-
sults:
amplitudes
fluctuation coefficients
excitations
phases
real parts and imaginary parts
In each of these cases the sum curve, the mean value, and the spectral compo-
nents (orders) are shown. Furthermore, for the periodical part of the ansatz the
signal wave form over one period and the fluctuation are available as typical
time-domain results.
The steady state simulation allows the consideration of internal behavioral

descriptions in the frequency domain, in particular for those effects, which do not
have a time-domain representation.
This permits the implementation of frequency-dependent damping models in

spring-damper-backlashes instead of the Reid damping models used so far.
Frequency-dependent damping was added to the following elements:

ElasticFriction (Mechanics.Rotation)
Coupling (PowerTransmission.Couplings)
DiscClutch (PowerTransmission.Couplings)
Gear (PowerTransmission.Transmission)
BeltDrive (PowerTransmission.Transmission)
Each of these elements now features a separate parameter page for steady state
simulation, where the damping model can be selected and the spectral power can
be recorded as a result quantity (the real part of the spectral power is the dissipated
power loss).
The Delay Time with constant delay was implemented in the frequency domain too
and will generate correct results in steady state simulation with continuous-time
input signals.
The user may operate the Steady-State Simulation with the help of the buttons in
the Simulation Control toolbar. Before starting the simulation make sure that
the combo box for the kind of simulation is set to Steady State.
For the handling of the simulation the Simulation Control toolbar offers the
following commands:
SimulationX 3 6-47
Open Settings Dialoge
Reset to Start
Start Simulation
Terminate Simulation
6.3.1 Basics of the Steady State Simulation

6.3.1.1 Periodic Steady State of a System
A dynamical system, such as a powertrain, is described by Differential-Algebraic
system of Equations (DAE)
0 = f (x(t ), x&(t )) (6.11)
with the time-dependent vector x (t ) of the state variables, and the corresponding
vector x&(t ) of time-derivatives and an equation
y = g(x (t ), x&(t )) (6.12)
for the computation of the user-selected result quantities y(t ) . In a valid model the
number of state variables n matches the number of equations in (6.11). Conse-
quently, for valid models x (t ) and f have the same number of components.
For an example, in most powertrain applications the vector x of the state variables
is composed of the angles and the angular velocities of the rotational masses and
system (6.11) constitutes Newton's law of motion together with the equations re-
presenting the angular velocities as time-derivatives of the angles of the rotational
masses.
During the steady-state simulation such solutions x (t ) of the system are computed
which can be represented as the composition
t ~ (t )
x (t ) = x P + x [0] + x (6.13)
T
t
of a uniform (linear) motion x P , a constant component x[0] and an unbiased pe-
T
riodical component x~ (t ) . Thereby, the periodical motion is approximated by a
finite harmonic sum
6-48 SimulationX 3
N
~ (t ) :=
x x R [k ] cos(kt ) x I [k ] sin (kt ) .
k =1
(6.14)
Here, the indexes R and I refer to the real part and imaginary part of the complex
amplitudes x [k ] = x R [k ] + j x I [k ] in the equivalent representation
N
~ (t ) = Re(x [k ] exp(jkt ) ) .
x k =1
(6.15)
The quantities in these equations are defined as follows:

xP a constant period vector with the dimension of the state variables (discussed
in section 6.3.1.2)
T the period duration of the oscillation
2
the phase velocity = of the oscillation
T
x [k ] the complex amplitude of the k -th spectral component
x[0] the constant signal component, in the following also denoted as mean
value (we call x[0] `mean value even if x P 0 )
x R [k ], x I [k ] Real part and Imaginary part of the complex amplitude of the k -th
spectral component of the state vector
N number of spectral components for the representation of x~ (t )
The result quantities y are likewise decomposed into mean value y[0] and the
complex spectral components y [k ] with k = 1,..., N and afterwards transformed into
the diverse representations. Section 6.3.5 describes the computational basis for the
representation of the result quantities in greater detail.
6.3.1.2 Period Vector, Period Variable and Period Computation

The meaning of the period vector x P shall be described by means of the periodical
steady state of a freely rotating powertrain with combustion engine.
The engine produces an angle dependent torque which excites oscillations in the
whole powertrain. Those oscillations are usually investigated for nonzero mean
engine speed. Therefore, within one oscillation period the angle of a rotational
mass of the powertrain will grow by the mean angular velocity times the period
duration.
This motion is taken into account by the period vector x P in the ansatz. The com-
ponents of the period vector corresponding to angular positions of rotational
masses amount to the angle covered within one period of oscillation. If, e.g., two
rotational masses are connected by a gear drive the ratio of the period vector com-
ponents for the angular positions of these masses is equal to the transmission ratio
of the gear drive. The period vector component of state variables with purely perio-
SimulationX 3 6-49
dically oscillating wave form equals zero. In the case of a powertrain this applies
for an instance to the angular velocities of the rotational masses.
When setting-up the steady state simulation the user is required to select one of the
state variables as period variable and to input the period vector component for
that variable by himself. This is in general not a difficult task. E.g., for a power-
train the excitation wave form repeats after two turns of the crank shaft. Therefore,
one may choose the crank shaft angle as period variable and two turns (i.e. 4
radian) as the value for the period variable.
The values of the other period vector components are determined in a separate step
called period computation at the beginning of the steady state simulation.
1. The quasi-static method used for the period computation requires that con-
straints are formulated in terms of states and not in terms of time derivatives.
For powertrains this implies that transmission constraints must be formu-
lated in terms of angles and positions and not in terms of velocities.
2. The model equations should be continuous. This especially applies to points
where
the period variable equals zero or the user-given period and
all velocities are zero.
6.3.1.3 Harmonic Balance, Parametric Analysis, Reference Quantity and

Compensation Parameter
After the period computation (described in the previous section) there follows the
main computational task of the steady state simulation: The computation of the
mean value x[0] , the spectral components x [1],K , x [ N ] , and the phase velocity in
the ansatz (6.13), (6.14) such that the system of equations (6.11) is satisfied at least
for the mean value f[0] and the first N spectral components f[1], K , f[ N ] on the right
hand side.
The algorithm for this computation is denoted as harmonic balance.
In SimulationX the harmonic balance algorithm is designed as a parametric analy-
sis. That means that the periodical steady state is determined in dependence of a
Reference Quantity x Ref which is swept through a user-defined range of values.
The user may choose any parameter or state variable as the reference quantity. If
he selects a state variable the mean value of this variable will be swept.
Because of the unknown phase velocity the harmonic balance system has one
more unknowns than equations. Therefore, to determine the periodic steady state
solution uniquely the mean value of the period variable is always set to zero.
Apart from this there result two different constellations for the system of equations
depending on whether the user chooses a parameter or a variable as reference
quantity:
Case 1: Parameter as reference quantity

If the user chooses a parameter as reference quantity the differential-algebraic
system (6.11) is just the parametric system
6-50 SimulationX 3
0 = f (x, x&; x Ref ) (6.16)
where for each parameter value of x Ref the number of equations equals the number
of variables.
Case 2: Variable as reference quantity

The user also has the possibility to choose the mean value x r [0] of a state variable
as reference quantity x Ref . E.g., in freely rotating powertrains often the mean rota-
tional speed of one of the rotational masses is selected as the reference quantity.
In this case the relation x r [0] = x Ref can be interpreted as additional equation for the
harmonic balance. To keep the numbers of variables and equations consistent one
of the system parameters must be set free as a variable. This parameter is denoted
as Compensation Parameter xComp . The modified differential algebraic
system (6.11) then reads
0 = f (x, x&, xComp ), x r [0] = x Ref . (6.17)
The role of the compensation variable shall be explained by means of an example:
Figure 6.32: Powertrain with additional element loadTorque for the compensation of the
mean engine torque
A powertrain without load will continuously accelerate and therefore does not keep
in a periodical steady-state (with constant rotational speed) if it is driven by an en-
gine under full injection.
Only with a load torque compensating the motor torque the mean engine speed can
be kept at the reference level (see Figure 6.32). Thus, for a powertrain application
it is a good idea to add a torque source as load torque and choose its torque param-
eter as the reference parameter.
6.3.2 The Steady State Simulation Dialog

Before running the first steady state simulation for a SimulationX model some
system specific parameter settings are necessary. The according input fields can be
found on the System page of the Steady State Simulation dialog (see Figure 6.33).
SimulationX 3 6-51
Figure 6.33: Steady State Simulation Dialog
You can open this dialog by the menu item Steady

State Settings in the Simulation menu.
The Steady State Simulation dialog also opens

after an error message if you try to start the steady
state simulation with missing or wrong parameter
settings.
6.3.2.1 Dialog Pages System and Method

In the Steady State Simulation dialog you can switch between the pages System
and Method by the tabs in the Solver menu at the left border.
6-52 SimulationX 3
A comprehensive help for these dialog pages is given in sections 6.3.3 (page
System) and 6.3.4 (page Method).
6.3.2.2 Start of the Steady State Simulation

After setting all required simulation parameters you can start the periodic steady
state simulation.
First, select the computation mode Steady State in the submenu Mode of the
Simulation menu and then click the start button or press the button F5.
The simulation mode can also be selected from the dropdown box
in the toolbar.
6.3.3 System Page of the Properties Dialog

The following settings on the System Page of the properties dialog are required for
the steady state simulation:
1. the Reference Quantity (parameter or variable)
2. the Period Variable and its Period
3. the Orders
4. the Compensation Parameter
6.3.3.1 Choosing the Reference Quantity

The periodic steady state simulation is designed as parametric analysis. This allows
the convenient investigation of the periodic solution of a system in dependence of
a user-defined reference quantity. Thereby, the reference quantity is in a user-
defined range.
SimulationX 3 6-53
You can select the reference quantity from the tree-view in the section "Setting
Reference Quantity" on the system page (see also Figure 6.34). It may be a
system variable or a system parameter.
With the input fields Start and Stop the user determines the boundaries of the
interval within which the reference quantity varies during the steady state
simulation. The values for Start and Stop are not restricted. Stop may be
larger, equal, or smaller than Start. If you choose the same value for both
settings then the steady state simulation is only executed for this parameter value.
Figure 6.34: Selecting the reference quantity
As indicated by the mouse pointer in the lower red circle of the example from
Figure 6.34 the angular velocity of the rotational mass jClutchAndGear is
selected by a mouse click.
If you choose a variable as reference quantity, as in the above example from
Figure 6.34, the mean value of that variable is swept from Start to Stop during
the steady state simulation. With a variable as reference quantity you are also
required to select a Compensation Parameter (see section 6.3.3.4). The harmonic
balance adapts the value of compensation parameter in order to adjust the mean
6-54 SimulationX 3
value of the reference quantity to the appropriate value inside the user-defined
range.
If you choose a parameter as reference quantity no compensation parameter is
required and the input field for the compensation parameter is disabled.
6.3.3.2 Selection of the Period Variable and the Period

As described in the theory section 6.3.1 the wave form of the states is composed of
a periodical signal (with possible constant offset) and a linear time-dependent sig-
nal. Through the time-linear component the values of some variables at the
beginning of a period differ from their values at the end of the period. E.g., for a
powertrain with 1-cylinder 4-cycle engine the crankshaft angle changes by the
value 4 over one excitation period.
Figure 6.35: Settings for the period, the fundamental order, and the highest order for a
4-cycle engine
In field Settings Period you select one of the state variables as Period Variable.
For this variable you have to specify the period length. E.g. for a powertrain you
may select the cardan shaft angle as the period variable and input in the case of a 4-
cycle engine the value 4 as period. The period duration of the oscillation is com-
puted from this data and the values for the reference variable automatically by the
steady state simulation.
Further details about the period variable and the period length can be found in sec-
tion 6.3.1.
6.3.3.3 Setting the Orders

The period duration of the lowest spectral component (apart from the mean value)
is determined by the user-defined period length for the period variable. This spec-
tral component is assigned to the fundamental order the second spectral component
is assigned to twice the fundamental order and so on up to the user-defined maxi-
mal order. The number of the spectral components used for the harmonic balance
solver equals the quotient of the maximal order divided by the fundamental order.
In stationary operation the oscillations in a 4-cycle engine are periodical with two
turns of the crank shaft. But it is common practice to assign the first oscillation
order to the spectral component which is periodical with one turn of the crank
shaft. Therefore, one designates the fundamental order with 0.5, as it is the case for
the default settings of SimulationX.
SimulationX 3 6-55
6.3.3.4 Setting the Compensation Parameter

If you choose a variable as reference quantity, you also need to select a Compensa-
tion Parameter (see also section 6.3.3.1) from the accordingly labeled parameter
tree view. The compensation parameter should directly or indirectly influence the
mean value of the reference quantity, such that the harmonic balance algorithm is
able to adjust the mean value of the reference quantity by adaption of the compen-
sation parameter value. For the example of the power train in Figure 6.32 the
torque value Model1.loadTorque.T has been chosen as compensation
parameter.
6.3.4 Page Method of the Properties Dialog

On the page Method of the properties dialog for the steady state simulation the
most important algorithm related parameters for the period computation and the
harmonic balance are available. The default settings on this page are appropriate
for many applications. So, it should only rarely be necessary to modify these
parameters.
6.3.4.1 Relative Quantities

Resonance maxima of higher spectral components are usually much smaller than
that ones of lower order but nevertheless they are often of interest for the steady
state analysis of the system. To ensure that small resonance peaks in the higher
orders are traced with the same high resolution as large ones in the lower orders
only relative measures are employed to determine the error tolerance and the point
density along the solution curve. That means, for the computation of the numerical
error and the step size, all components, for which the difference between maximum
and minimum of the values computed so far exceeds the value one, are previously
multiplied with the scaling factor 1/(maximum-minimum). The reference quan-
tity is scaled by the factor 1/|Stop-Start| for the step size control if Start and
Stop do not coincide.
6.3.4.2 Stepsize parameter

For the computation of the solution curve a curve tracing algorithm is applied. This
algorithm makes the fine tracking of resonance peaks as well as the computation of
nonlinear frequency responses with turning points possible. Thereby, the relative
step size for tracing the solution curve is not measured strictly in direction of the
reference quantity but tangent to the solution curve in the space composed of the
reference quantity and all spectral components for state variables (see Figure
6.36). This is indispensable for tracing solution curves with turning points (see
Figure 6.37).
The relative limits for the step size of the curve tracing algorithm determine mainly
the resolution of the solution curve. The default relative minimal and maximal step
sizes 0.01 and 0.1, respectively, should be optimal for many applications.
Choosing the minimal step size too small may lead to apparent stopping of the
6-56 SimulationX 3
curve tracing or even unwanted reversal of the tracing direction. A too large
maximal step size may lead to skipping of resonance peaks along the solution
curve.
Figure 6.36: Step size tangential to the solution curve
Figure 6.37: Frequency responses of nonlinear systems may have turning points in
which the tangent direction of the curve is perpendicular to the direction of
the reference quantity. In such points the step size in direction of the
reference quantity is zero.
The step size is also controlled by the curvature of the solution curve and the con-
vergence of the Newton-algorithm. These aspects of the step size control can be in-
fluenced by the options on the dialog page More Parameters.
6.3.4.3 Relative Tolerance

The relative tolerance is a measure for the precision of the computed spectra.
Thereby, the numerical error is estimated for the scaled spectral components of the
state variables (see section 6.3.4.1).
SimulationX 3 6-57
Notes:
Since the exact solution is unknown also the numerical error cannot be determined
exactly. As a measure for the remaining numerical error the length of the current
Newton step is used.
Beside the remaining error of the Newton iteration, which is controlled by the
relative tolerance, also the sampling error of the Fast Fourier Transformation
contributes to the overall error in the spectral results. This error can only be re-
duced by oversampling (see section 6.3.4.4).
If the linear method is chosen the relative tolerance is only relevant for the
calculation of the mean values. The oscillation amplitudes of the states are
computed with exactly one Harmonic Newton step starting from zero initial guess
regardless whether the numerical error reaches the relative tolerance or not (see
section 6.3.4.5).
6.3.4.4 Oversampling
In the course of the harmonic balance nonlinear functions must be evaluated in the
time-domain. For the balance of the frequency-domain residuals the function
values are transformed with the help of the Fast Fourier Transformation (FFT) into
the frequency domain. The Oversampling determines how many samples in the
time-domain are used for this discrete Fourier transformation. If N is the number
of spectral components for the harmonic balance then at least
Oversampling 2 N
points are used in the time-domain. Internally, the number of samples is enlarged
to the next power of two since the FFT works best for this case.
6.3.4.5 Algorithm
With the multiple choices box Algorithm you can select one of the following al-
gorithms for the harmonic balance:
1. Nonlinear Method (Newton, GMRES, Jacobi-Precond.)
With this method the harmonic Newton algorithm is applied to the system
equations. As many Newton iterations are executed as it takes for the rela-
tive approximation error to get smaller than the user-given tolerance.
Thereby, the approximation error is estimated by the length of the current
Newton step. It has to be taken into account that the sampling error of the
Fast Fourier Transformation gives a contribution to the overall error which is
not controlled by the error estimator of the Newton algorithm. Therefore, the
Oversampling must be chosen high enough to keep the sampling error small.
The harmonic Newton-Algorithm requires the solution of a large linear
system of equations in each iteration step. The supplement GMRES in the
name refers to the iterative algorithm for the solution of this linear system.
The GMRES algorithm can be speed-up by a pre-conditioner. This is an
approximation for the Jacobian of the harmonic balance equations.
6-58 SimulationX 3
For the case of the Jacobi-Preconditioner the Jacobian of (6.11) is averaged

over one oscillation period and then used for each frequency component
separately. Therefore, no frequency mixing effects are taken into account
through the preconditioner. Nevertheless, GMRES exactly solves the linear
system. But it might take more GMRES iterations to find the right solution.
2. Linear Method
With this method only one step of the harmonic Newton algorithm is exe-
cuted in each point of the solution curve. Therefore, the linear method is
often faster than the nonlinear one. But the approximation error of the
harmonic Newton algorithm cannot be controlled with this method (for this
end at least two Newton steps would be necessary).
3. Nonlinear Method (Newton, GMRES, approxim. Jacobian)
This method differs only in the Preconditioner from the nonlinear method
with Jacobi-Preconditioner (see above). All entries from the Jacobian-Pre-
conditioner are also used for the approximate harmonic Jacobian.
Additionally, strongly mixing terms are regarded in this preconditioner. This
can help the convergence of the GMRES algorithm. On the other hand the
harmonic Jacobian becomes larger and structurally more complicated which
may cause longer calculation times.
Thus this method can be seen as a fall-back if the nonlinear method with
Jacobian-Preconditioner fails.
4. Linear Method with Interpolation
This method is a speed-up version of the linear method. For most mildly
nonlinear models it allows a ten times faster calculation than the linear
method without interpolation. The main computational acceleration of the
interpolating method is due to the better exploitation of the step size control
for the reference quantity. In powertrain applications usually the engine
speed is selected as reference quantity. Often the oscillation orders have
resonances at different speeds. Therefore, the amplitudes of the orders vary
rapidly in separate regions of the reference quantity. In those regions the
reference step size is reduced to capture the fast amplitude changes.
Without interpolation there is only one common reference grid. The mean
value and all orders are calculated in each point of this grid. This causes high
computational costs without interpolation.
With interpolation the mean value component and the oscillation orders are
calculated separately each with its own step size control and its own
reference grid. This allows coarser grids and therefore less numerical effort
without loss of precision. Only the results are interpolated on a combined
common reference grid.
SimulationX 3 6-59
The linear methods are suited for systems where the constant component and the
time-linear component dominate the nonlinear system behavior in comparison to
the oscillating signal component.
The linear methods are exact for linear systems which are excited by a generator
whose frequency is chosen as reference quantity and whose phase is chosen as
period variable.
a) Model
b) Result of the linear method c) Result of the nonlinear method

Figure 6.38: Comparison of the results obtained with the linear and the nonlinear method
for a powertrain with 6-cylinder 4-cycle engine. The amplitudes for the
listed orders of jClutchAndGear.om are shown.
Important examples for systems where the constant and time-linear components
dominate the nonlinear system behavior are powertrains with combustion engine
whose conrod is rigidly modeled. For such a powertrain the simulation results once
obtained by the linear method and once by the nonlinear method are depicted in
Figure 6.38. For this example the results of the linear method match very well
those of the nonlinear method. In general it can be stated that for powertrain
applications with rigid conrod and linear drivetrain the precision of the linear
method is sufficient.
For systems with dominating nonlinear system behavior the results of the linear
method may be erroneous. An example for such a system is a spring mass oscilla-
tor with nonlinear spring characteristic as it is exhibited in Figure 6.39.
6-60 SimulationX 3
The linear and nonlinear methods differ mainly in the determination of the state
evolution in dependence of the phase angle. The results are calculated from the
states. With the nonlinear methods and with the linear method without inter-
polation the assigning equations for the results are evaluated in the time-domain. In
this way result quantities are correctly calculated even if they depend strongly
nonlinearly on states.
The linear method with interpolation is designed for high calculation speed. With
this method the results are calculated in the time domain only for the large affine-
linear motion of the states. The changes of the results caused by the small state
oscillations are linearly superposed in the results afterwards (as transmission
matrix the Jacobian of the results with respect to the states is averaged over one
oscillation period).
a) Model (stiffness c of the spring dependent on the deviation dx)
b) Realistic result obtained by the c) Erroneous result obtained with the

nonlinear method linear method
Figure 6.39: Comparison of the results of the nonlinear method and the linear method
applied to a spring mass oscillator with nonlinear spring characteristic
This may lead to imprecise results if a result quantity is strongly nonlinearly

dependent on states. An extreme example for this case is represented in Figure
6.40. There, the angular velocities of the inertias J1 and J2 are states and the result
quantity f2.y depends quadratically on the difference angular velocity.
The result quantities required for powertrain applications (such as angles, angular
velocities, and excitation torques) are most often linearly or mildly nonlinearly
SimulationX 3 6-61
dependent on the oscillation of the states. Furthermore, the spectral power of

elements is calculated in the frequency domain. Therefore, the negative effect of
result interpolation should not play a role for such applications.
If in special applications its influence becomes too large it is possible to switch off
result interpolation through the extended parameter bResultInterpol (press
the button More Parameters... on the Steady State Dialog page Method). If
many result protocols are activated this may slow down the calculation.
a) Model (result f2.y strongly nonlinearly dependent on sd1.dom)
b) Realistic result for f2.y without c) Erroneous result obtained with result
result interpolation interpolation
Figure 6.40: Comparison of the results with and without result interpolation
6.3.5 Result Window for the Steady State Simulation

The periodic steady state results can be visualized by the following steps:
1. Activate the protocol attribute of the desired result variables
2. Open the result window
3. Select the spectral representation (frequency domain results) or
4. Select the signal representation over the period variable (time domain
results)
6-62 SimulationX 3
6.3.5.1 Activation of the Protocol Attribute of Result Quantities

Before the simulation run activate the protocol attributes of the result variables for
which you want to display steady state results. Thereby, proceed as for the
visualization of transient simulation results.
Click on the icons of the protocol attributes of the wanted result quantities (
) on the Results page of the Properties dialog of the corresponding
model elements.
Figure 6.41: Activation of the protocol attribute of a result variable in the Properties
dialog of a model element (here jClutchAndGear)
6.3.5.2 Opening Result Windows
Figure 6.42: Opening a result window for the periodic steady state simulation
For display of a result variable with activated protocol flag chose the variable from
Results (Steady State) in the context menu of the corresponding model element (cf.
Figure 6.42). Thereby the corresponding steady state result window for that
variable opens (see Figure 6.43).
SimulationX 3 6-63
With the tabs Spectra and Signal in the right lower corner of the result
window you can switch between the representations of
the spectra over the reference quantity (as, e.g., the mean angular velocity of a
rotational mass) and
the time-domain waveform over the affine signal-component of the period
variable (as, e.g., the fluctuation of the angular velocity of a rotational mass
over the uniform advancing angle without angle oscillation)
When opening the steady state result window the Spectra are shown by default.
Figure 6.43: Steady state result window
Drag-and-Drop is not available for these result windows!
6.3.5.3 Representation of the Spectra

In the spectra representation the harmonic components, the mean value, and the
sum curve are shown.
Sum Mean Spectral Remarks/Examples

Quantity Value Components
(Orders)
E.g., for the angle of a
rotational mass the maxi-
mal deviation from the
Amplitude max | ~
y (t ) | y[0] y[k ] = y R [k ] + y I [k ] uniform motion is shown.
2 2
t[ 0 ,T ]
Please, regard also the text
about the sum curve
below the table.
6-64 SimulationX 3
~
ymax ~
ymin The fluctuation coefficient
y[0] is a usual measure for the
2 y[k ]
For y[0] deviation of the angular
Fluctuation y[0] = 0 speed of a rotational mass
0 For y[0] = 0 this
Coefficient this from its mean value. It is
quantity is set to the default representation
quantity is
zero. for the angular speed of
set to
zero. rotational masses.
For the computation of the excitation For rotational masses
of a result quantity y only the directly connected to a
approach massless and rigid crank
t shaft the excitation of the
x(t ) := x P + x[0]
T acceleration torque is the
is used. excitation torque
commonly used for order
That means that the unbiased
Exitation ~ analysis in powertrain
periodically oscillating signal x (t ) is engineering.
set to zero for this computation.
For excitations, those results y which
are linearly dependent on the states the
y[k ]
excitation frequency components
(k = 1,..., N ) equal zero and are not
shown.
The phase is relative to the
Phase 0 0 arctan( y I [k ], y R [k ]) null phase of the period
variable.
The real part is the co-
Real Part 0 y[0] y R [k ] efficient of the base func-
tion cos(kt ) in the ansatz.
The imaginary part is the
Imaginary coefficient of the base
0 0 y I [k ]
Part function sin (kt ) in the
ansatz.
Table 6.2: Multiple choices for the spectra representation
The multiple-choice box at the right upper corner (see Figure 6.44) offers the
following possibilities how the displayed quantities are derived from the harmonic
balance results.
At a given reference value the value of the sum curve is the maximum absolute
value of the deflection taken over the Signal in time-domain (Signal representation
in the Steady-State result window).
SimulationX 3 6-65
Figure 6.44: Multiple-choice box for the representation of the spectral components
In the example of Figure 6.45 the Fundamental Order and the Maximal Order both
are set to 1 such that the waveforms of the states are approximated only by their
fundamental components. The output of the nonlinear block xPower5 is distorted
in such a way that its maximum exceeds the amplitude of the fundamental
component. Therefore, the sum curve is located notably above the curve for the
amplitude of the fundamental component.
a) Model b) Distortion of the sinusoidal signal x

by the nonlinear signal block xPower3
and the corresponding output signal y
c) Waveform of the output y of d) The sum curve (red) is larger than

xPower3 at excitation frequency the amplitude of the fundamental
of 100 Hz component (blue)
Figure 6.45: Fundamental Order and Maximal Order each are set to 1 in this example.
Even so the sum curve of the nonlinear block is located notably above the
amplitude of the fundamental component
6-66 SimulationX 3
On the diagram presentation at the panel Spectra the sum curve, the mean value,
and the spectral components are listed (see Figure 6.46). The columns in this panel
have the following meaning:
1. With the checkbox in the first column you can switch on and off every single
signal component (sum signal/mean value/individual orders). To select a
range of orders select the start order with the mouse and afterwards the end
order with the shift-button pressed. If you check or uncheck one of the orders
within the selected range all of selected orders will be checked or unchecked,
respectively.
2. In the second column the orders of the spectral columns are listed. These are
the integral multiples of the fundamental order given in the System-dialog of
the steady state properties page.
3. In the third column the maximal amplitudes over the reference quantity for
each of the spectral components is listed.
4. The fourth column lists for each spectral component at which reference value
the maximal amplitude is taken on inside the user-defined range for the
reference quantity (see Figure 6.46).
Figure 6.46: The Panel in the spectra representaion of the steady state results. For the
sixth order (light-blue) it is shown where the corresponding curve takes on
its maximum (blue line) and how large this maximum is (red line)
6.3.5.4 Representation of the Signal

In Figure 6.47 the result window is shown after switching to Signal view mode. In
this case the results are plotted over one period of the period variable.
SimulationX 3 6-67
Figure 6.47: Result window for the signal representation of the steady state results.
The way how the displayed quantity is calculated from the harmonic balance re-
sults can be selected from the multiple-choice box in the right upper corner of the
result window.
Figure 6.48: Multiple-choice box for the computation of the displayed quantities from
the harmonic balance results
There are following choices:

Computation Remarks/Examples
Often the oscillating part of the result quantity is
much smaller than its mean value. In those cases it
~
y (t )
is best to represent the oscillating part separately.
Deflection
E.g. for the angle of a rotational mass directly the
deviation of the instantaneous angle from the
uniform motion is shown.
Deflection+ ~
y (t ) + y[0] For quantities, with zero period vector components
Mean Value this is the complete signal.
The fluctuation indicates how large the relative
~ deviation of a quantity from its mean value is.
y (t )
Fluctuation y[0] In powertrain engineering it is custom to plot the
fluctuation for the angular velocity of rotational
masses. This is the default setting of SimulationX.
The reference value for which the signal wave form is displayed can be adjusted by
the slider or input in the text field and accepted with the enter button or a mouse
click on the button Apply.
6-68 SimulationX 3
Equilibrium (Static / Steady-State)
6.4 Equilibrium (Static / Steady-State)

For many applications it is very useful to start the simulation from the (steady-state
or static) equilibrium state instead of a certain user-defined initial state.
Examples for such equilibrium states are:

Electronics:
DC-operating point of a circuit
Hydraulics:
Steady state analysis of hydraulic circuits
Mechanics:
Spring-suspended, elastically supported system, vehicles drives at constant
speed and then starts maneuvering
A system is in a static equilibrium when its state variables no longer change, i.e.
when their derivatives are zero. However, in mechanics states of equilibrium are
interesting too where the system moves at a constant speed. In that case, only
acceleration (i.e. the highest derivative) is zero.
Systems may have:
exactly one,
several (pendulums have one stable, and one unstable state of equilibrium),
possibly infinitely many (e.g. ball on plain ground),
or even no state of equilibrium at all.
With the menu option Simulation Equilibrium or the button you start the
equilibrium calculation.
For this the computation algorithm maintains the highest derivatives of the state
variables at zero and tries to generate a consistent state under these conditions. The
resulting non-linear equation system is solved with an iterative method. The input
initial values are used as start values for the iteration. If no state of equilibrium is
found, you can try to vary the initial values manually and restart the equilibrium
calculation again. However, keep in mind that there are models which do not have
a state of equilibrium as shown in Figure 6.49.
The numerical method cannot differentiate if a model does not have an equilibrium
or if it cannot be found because, for instance, the selected start values are
unsuitable. For helping the algorithm to find equilibrium, it is possible to carry out
a transient simulation which brings the model near to a possible equilibrium and
start the equilibrium calculation afterwards.
SimulationX 3 6-69
Figure 6.49: Simple models which do not have an equilibrium state
The results from the equilibrium computation are displayed in the model explorer
(for all variables), in result windows (first value of the result curve) or by means of
immediate displays.
You can start a simulation in the time domain or a linear model analysis from the
calculated equilibrium state.
6.5 Linear System Analysis

In addition to dynamic simulation, periodic steady state simulation and equilibrium
calculation, further analysis functions are available:
Natural frequencies and mode shapes,
Input-Output Analysis.
All these functions are based upon linear model analysis, i.e. the model equations
are linearized at the current operating point. For strongly non-linear models, the
result of this analysis applies therefore only to a small neighborhood of this
operating point. Examples for such non-linear models can be found easily in every
engineering domain:
Nonlinear stiffness and damping of mechanical elements,
Physical end stops,
Friction (stick-slip),
Hydraulic/pneumatic control valves,
Electronic devices (diodes, transistors,...),
Pressure- and temperature-dependent fluid properties of hydraulic oil
(compressibility, viscosity, aeration and cavitation).
The linear model analysis can be performed at any time instant. For example, you
can stop a transient simulation at a certain point and perform a linear analysis.
6-70 SimulationX 3
Linear System Analysis
The linear system analysis calculates the eigenvalues for the small signal system
equations which are derived from the simulation model by the linearization of the
model equations in the current operating point.
As seen in section 6.1.2.1 the Symbolic Analysis provides the system equations in
one of two forms. Here we use the more general form
, (), () = (6.18)
where is the simulation time, and () is the vector of state variables

depending on time, are the corresponding derivatives. In the smooth real vector-
valued function the residuals of the model equations are collected.
For the linear system analysis a small disturbance () of the solution () is

considered. Note that such a disturbance can be caused by a small variation of the
start values (0) for the states. The linear system analysis calculates measures
that characterize the time-evolution of all possible disturbations. Next, we derive
the governing equations for the perturbations .
Substituting the states () and their time derivatives () by the corresponding
disturbed quantities () + () and () + (), respectively, in the model
equations (6.18) we get
, () + (), () + () = . (6.19)
Since the disturbance () shall be small we may approximate the left-hand side
of this equation by its first order Taylor series
, (), () + , (), () () + , (), () () = (6.20)
for the disturbance () where and denote the partial derivatives of

w.r.t. and , respectively. Note, that these derivatives are -matrices also
called as Jacobian with respect to , and , respectively.
The state evolution () represents a solution of the system equations (6.18).

Therefore, the first summand in the linearized equation (6.20) balances to zero
which leaves us with the rest
, (), () () + , (), () () = . (6.21)
To simplify the system for the linear system analysis the time-dependency of the
Jacobians is neglected and rather the Jacobians -
Stop , Stop , Stop and Stop , Stop , Stop
at the stop time Stop of the time-simulation are used. Therewith, we finally arrive
at the equations
SimulationX 3 6-71
() = () (6.22)
employed in the linear system analysis.

It should be noted, that the replacement of the Jacobians from (6.21) by constant
matrices in (6.22) does not change the system if does not explicitly depend on
time and the base solution () is at equilibrium, i.e. constant. Otherwise, the
solution of (6.22) gives only an approximation for the disturbance from (6.21).
This approximation is good if the time-dependent changes of and are much
slower than the eigenmotions of the linearized system (6.22).
In most cases all solutions of (6.22) are representable by the approach

()
() = () (6.23)

with real amplitude vectors

and , a real decay time constant , a real
eigenfrequency .
The solution of equation (6.22) simplifies a bit if one replaces the disturbation
() by the complex signal () with the vector of complex
1
amplitudes = and the characteristic exponent = + i ,
+ i

where i 1 is the imaginary unit. The wanted real disturbation () from
(6.23) can then be recovered from () by extracting its real part: () =
Re ().
into (6.22) gives
Substituting and its time derivative () =

= . (6.24)
Since exp never gets zero we can divide by this term and get the eigenvalue
equation

= . (6.25)
which can then be solved for the eigenvalues and the corresponding eigenvectors
by the appropriate numerical algorithms. From these eigenvalues and
eigenvectors all quantities represented in the dialog window `Natural Frequencies
And Mode Shapes of SimulationX are derived (see 6.5.1). Furthermore, these
eigenvalues are the poles shown in the dialog window for the `Input Output
Analysis (see 6.5.2).
6.5.1 Natural Frequencies and Mode Shapes

The natural frequencies and mode shapes of the system are computed from the
Jacobian matrices of the model. All state variables are taken into account.
Therefore, the computed values apply to the whole model regardless of the
physical domain.
6-72 SimulationX 3
You open the dialog window for the natural frequency analysis with Analysis
Natural Frequencies and Mode Shapesor by the button . After pressing the
Update button the computation is performed and the eigenvalues are given in a
table.
The window size can be varied. You may leave it open during other operations.
This allows you to comfortably observe the influence of certain parameters on
certain eigenvalues. Simply change the parameter and re-compute the eigenvalues
(button Update).
The following buttons are available in the window:

Push this button to print or export as a file the results of the natural
frequency analysis. In the print preview results can be hidden
which are not of interest and various format settings can be made.
This button starts a new natural frequency computation. Updates
are required when parameters have been changed and the influence
of these parameters on certain eigenvalues is to be studied.
Actuate this button to close the window for the computation of the
natural frequencies and modes.
With this button you go to help for how to use this window.
Filtering
In addition to the existing possibility to hide frequencies with values zero or
infinity, lower and upper limits for frequencies as well as time constants can be
defined. The filter settings are stored with the model.
The natural frequencies and mode shapes are displayed on five tab cards:
6.5.1.1 Eigenvalues
Display of the complex eigenvalues, damped and undamped natural frequencies,
damping factors D and of the time constants of the current model. Clicking on a
column header sorts the table rows according to the clicked column. Clicking on
the same header alters the sorting order from ascending to descending and vice
versa.
For a given eigenvalue the entries of the corresponding row are determined by
the following rules:
1. The row is marked as time constant T in the first column if is real and as
frequency f if is complex.
SimulationX 3 6-73
2. The imaginary unit is employed for displaying the values of complex

eigenvalues. Complex conjugated pairs of eigenvalues are represented
combined in one row indicated by the sign in front of the imaginary part.
3. The undamped frequency

(6.26)
2
With the absolute value || of . It is only shown if is complex.

4. The damped frequency is
|()|
(6.27)

With the imaginary part Im() of . It is only shown if is complex.

5. The damping factor D is
()
(6.28)
||
It is shown only if is complex.

6. The time constant is
1
(6.29)

It is only shown if is real and nonzero.
Figure 6.50: Eigenvalues, eigenfrequencies and time constants
6-74 SimulationX 3
With default settings only eigenvalues different from zero and infinity are shown.
If you click on Show All zero and infinite eigenvalues are also represented and
each complex conjugated pair of eigenvalues takes two rows of the table (cf.
Figure 6.51).
Figure 6.51: Representation of eigenvalues with Show all enabled
You can copy the content of the table to the clipboard by pressing Ctrl-C.
Alternatively, click with the left mouse button into the data area. From the opening
popup menu chose Copy table.
6.5.1.2 Eigenvectors
Display of all eigenvectors and of the names of the respective state variable. By
clicking on a line the corresponding element or the corresponding connection is
selected in the diagram view and in the Model Explorer.
To copy the contents of a table in text format to the clipboard, select the command
Copy table in the context menu of the table.
6.5.1.3 Deviation
An eigenvector is displayed as a value and also in the form of a bar chart. The
length of the red bar is indicating the amplitude of the deviation. The direction
(positive or negative) is selected depending on the phase angle. Complex values in
the right half plane, corresponding to phase angles between -90 and +90 are
shown as positive (to the right), whereas values in the left half plane (-180 to -90,
and 90 to 180) are shown negative. Such vibration mode plots are very common
in natural frequency analysis, showing amplitude and positive (in-phase) or
negative (counter-phase) sign. This comes from the natural frequency analysis
SimulationX 3 6-75
based on mass and stiffness only (undamped systems), where all phase angles are
either 0 or 180. In damped systems any phase angle is possible. Therefore we
also provide amplitude and phase in addition to the bar chart.
By clicking on a line, the corresponding element or the corresponding connection
is selected in the diagram view and in the Model Explorer.
To copy the contents of a table in text format to the clipboard, select the command
Copy table in the context menu of the table.
Natural mode
Select here the eigenvector to be displayed. The order of the entries in the
combobox corresponds to the sorting on the dialog page Eigenvalues.
Figure 6.52: View of Deviation
Filter
Actuate this button to hide any state variables which are not of interest by means of
a selection dialog.
Figure 6.53: Filter for the display of the modes
6-76 SimulationX 3
The deviations shown in the bar chart are normalized according to the rule:
max( y ) = 1 (6.30)
In the normalization only the currently displayed state variables are regarded.
6.5.1.4 Distribution of Energy

This dialog page shows the distribution of energy of a natural mode. Thus the
influence of certain elements on the respective natural frequency can be seen. If
you select one of the rows with an element name then this element will also be
selected in the diagram view and in the model explorer. To take the energy
contribution of an element into account the evaluation of special variables is
required in its behavioral description (this is regarded in several internal libraries
such as the mechanics libraries).
You can copy the content of a table as text by clicking on Copy in the context
menu.
You get a print preview of the energy distribution by pressing Print Preview.
There you may choose modes for which the energy distribution should be
represented.
Figure 6.54: Distribution of energy view
Natural mode
Select the natural mode here, whose energy distribution is to be shown. The order
of the entries in the combobox corresponds to the sorting of the eigenvalues on the
dialog page Eigenvalues (see 6.5.1.1).
SimulationX 3 6-77
Kinetic energy
This table shows the normalized distribution of the kinetic energy Ekin for the
currently selected natural mode. The table contains all elements which can
accumulate kinetic energy (e.g. element Mass, library Mechanics).
Potential energy
This table shows the standardized distribution of the potential energy Epot for the
currently selected natural mode. The table contains all elements which can
accumulate potential energy (e.g. element Spring, library Mechanics).
Power loss
This table shows the standardized distribution of the power loss Ploss for the
currently selected natural mode. The table contains all elements which are linked
with power loss (e.g. element Damper, library Mechanics).
The displayed energy forms are normalized by the following rules:
E kin = E pot (6.31)
max(Ekin , E pot ) = 1 (6.32)
max(Ploss ) = 1 (6.33)
Filter
Click this button to open a selection dialog to hide the not interesting variables and
change other settings.
Figure 6.55: Filter for the distribution of energy view
6-78 SimulationX 3
6.5.1.5 Campbell Diagram

This dialog page shows the Campbell Diagram. It is mainly used to identify critical
speeds of rotational systems (powertrains). Possible resonance points are found at
the crossing points of the eigenfrequencies (horizontal lines) with the orders
(transversal lines).
The presence of the certain resonances depends mainly on the kind of excitation,
degree of damping etc. They can be determined by the actual simulation (time-
domain simulation or a periodic steady state simulation).
Figure 6.56: Campbell Diagram
Description of buttons at this page:
Copies the Campbell Diagram to the clipboard

Prints the Campbell Diagram
Zoom function to define the speed range
Shows the complete Campbell Diagram
SimulationX 3 6-79
The crossing points can be exactly measured by clicking with the mouse
on the point of interest. A certain speed range can be marked by 2 vertical
lines. The location of the vertical lines and the represented region of the
diagram can be adjusted by using the mouse or with defined values n by
clicking on the button shown on the left side.
6.5.1.6 Animation
The animation of the natural modes permits three-dimensional allocation of the
natural frequencies and localization of the corresponding components in the 3D
view.
Natural mode
Select the natural mode here which is to be animated. The order of the entries in
the combobox corresponds to the sorting of the eigenvalues on the dialog page
Eigenvalues. The natural mode can also be selected while the animation is
running.
Amplification
With the slider control you can set an amplification factor for the deviation of the
animated natural mode. The deviation can be changed while the animation is
running.
Animation frequency
With the slider control you can vary the animation speed. With an animation
frequency of 1 an oscillation period per second is shown. The animation frequency
can be changed while the animation is running.
Start
Actuate this button to start the animation. During the animation you can set the
amplification and animation frequency and change the active natural mode.
6-80 SimulationX 3
Stop
Actuate this button to terminate the running animation.
Save
Actuate this button to save the animation for the active natural mode as a video in
the AVI format. If more than one 3D view is displayed, you have to select the
desired view from a list first.
6.5.2 Input-Output Analysis

For the analysis of the transmission behavior, the model is interpreted as a system
with inputs and outputs. After the definition of the inputs and outputs by the
user, the model equations
0 = , (), (), ()
() = , (), ()
are linearized in the current operating point () without input (() = 0). The
first order equations for small deviations , are:
0 = + +
= +
The potentially time-variant Jacobians , , , and are
approximated by constant system matrices:
, ,
,
Therewith, the linearized system can be written in the standard descriptor form
= + ,
= + .
If the matrix is non-singular it can be transformed into an identity matrix by
multiplying the first equation of the above system with the inverse 1 . With new
system matrices , one obtains the state-space representation
= + ,
= + .
The dialog window for the Input-Output Analysis opens if you select the menu
item Analysis Input-Output Analysis.
To display all values the window size can be adjusted. The window may stay
opened for further operations. This allows you to easily study the influence of
single parameters.
SimulationX 3 6-81
Actuate this button to perform the linear system analysis once

again. Updates are required when parameters have been changed
and the influence of these parameters on the computation results is
to be studied.
Actuate this button to close the transmission behavior window.
6.5.2.1 Settings
The dialog page Settings permits the selection of inputs and outputs for
performing a linear system analysis. Free signal inputs can be defined as an input.
As output both signal outputs and result variables can be selected.
Edit
Actuate the respective button to add or delete inputs or outputs. A dialog will be
opened to select admissible inputs or outputs of the active model. The variables
can be copied from the tree view of the model by Drag-and-Drop or double click.
Signal inputs of the model suit as admissible inputs and result quantities as
admissible outputs for the input-output analysis.
6.5.2.2 Frequencies Analysis

The frequency analysis allows the illustration of the model behavior at the
frequency range.
A harmonic input signal () = Re() exp(2) with the possibly
frequency varying amplitude () is applied to the linearized system.The periodic
steady state response amplitude () is calculated from the system of following
equations in dependency of the excitation frequency :
2 () = () + (),
() = () + ()
To be able to perform a frequency analysis, the following steps are required:
1. Selection of the inputs and outputs on the dialog page Settings
2. Description of the excitation for every input
3. Defining the frequency range as well as number and distribution of
the samples to perform the analysis
4. Execution of the analysis by actuation of the button Update
Excitations
An excitation must be specified for every defined input. For this purpose the
respective input must be marked in the table. There are several options for the
description of the excitation:
6-82 SimulationX 3
Amplitude and phase as constants (default setting with amplitude 1 and

phase 0)
Real and imaginary parts as constants
Amplitude and phase as characteristic curves over the frequency
Real and imaginary parts as characteristic curves over the frequency
Periodic time signal
Analysis
Before an analysis will be performed the frequency range to be studied must be
specified by means of the following parameters:
Minimum frequency in Hz
Maximum frequency in Hz
Number of samples
Division of the frequency axis (linear or logarithmic)
Results
The table Results contains for every defined output the system response in three
different types of representation:
Real and imaginary part
Amplitude and phase
Nyquist plot
Figure 6.57: Result display as a Nyquist plot
SimulationX 3 6-83
The symbols can be dragged from the result table as a result window into the
SimulationX workspace with Drag-and-Drop or double click. The result windows
opened in this way are stored together with the model and updated automatically
when another frequency analysis is performed.
Actuate this button to update the computation results after
parameter changes in the model or after changes of the settings for
the frequency analysis. Result windows with frequency curves
which are already open will be updated automatically in this
process.
6.5.2.3 Poles and Zeros

The poles of the system are the complex values in the non-trivial solutions
() = Re exp of the linear system with zero input () = 0, i.e., the
solutions of the system
() = ().
Substituting the solution ansatz () = Re exp into that system provides
the generalized eigenequation
=
where the poles can be determined numerically as eigenvalues.
The zeros of the system are the values for which the system output is zero even
with a non-trivial input signal = Re exp and/or a non-trivial state
evolution = Re exp .
One obtains for zero output the following linear system of equations:
= +
0 = +
With the given ansatz = Re exp , = Re exp results the
condition
0
= .
0
This equation also describes a generalized eigenvalue problem with the zeros as
eigenvalues which can be determined numerically.
The Poles and Zeros dialog page shows the poles and zeros of the transmission
system as a table and in graphical form as a pole / zero setting chart (beforehand
the inputs and outputs of the system must be determined on the dialog page
Settings).
The pole and zero settings can be highlighted with a mouse click both in the table
and in the graphics. Multiple selections are possible with the Ctrl button kept
pressed. Marked poles or zeros are highlighted with different color in the graphics.
6-84 SimulationX 3
Figure 6.58: Pole-Zero Plot
The symbol bar of the dialog page contains the following buttons:
Copies the table in text format and the graphics to the clipboard.
These displays can be copied to other programs with the command
Paste contents.
Opens the print preview. The table and the graphics can be printed
or exported with it.
Shows a magnifying lens. By marking a rectangular area in the pole
/ zero plot you can zoom into a section of the graphics.
Resets the zoom. All poles and zeros which can be pictured are
displayed.
parameter changes of the model.
Actuate this button to close the Input Output Analysis window.
Get help on the usage of this window.
6.5.2.4 Export
This dialog page permits the export of the active model at the current operating
point in the state-space representation (if available):
SimulationX 3 6-85
x&= A x + B u
(6.34)
y = C x + D u
or in descriptor form:
E x&= A x + B u
(6.35)
y = C x + D u
with:
x ... state variables
u ... input variables
y ... output variables
As a first step the input variables and output variables of the system must be
determined on the dialog page Settings.
Figure 6.59: Export of system matrixes
Data format
Determine here the format in which the system matrixes are to be exported. The
following formats are supported
Matlab m-File
Modelica-Syntax
Number format
Under Format string the accuracy and format of the numbers in the exported
data are determined. The syntax used here complies with the rules defined for the
printf function in the programming language C.
6-86 SimulationX 3
Variant Analysis
Designations
Customize the names of the exported matrixes here. Note that the validity of the
designations depends on the selected data format.
Actuate this button to copy the system matrixes in the selected
format to the clipboard.
Actuate this button to save the system matrixes in the selected
format as a file. A file dialog is opened to select the file name and
target directory.
parameter changes of the model.
Actuate this button to close the transmission behavior window.
6.6 Variant Analysis

6.6.1 Range of Application
Variant analysis and parameter studies are useful to investigate a model with
different sets of parameters. The Variants Wizard helps you to define such
parameter studies. It allows selection of the parameters to be varied and their value
assignment. It also offers different output formats where the results of the variant
computation can be saved for further analyses. A variant analysis described in this
way can be saved for later use.
6.6.2 Preparation
Firstly, load the model, which you want to use for a parameter study. In order to be
able to assess how long a simulation will take roughly, it is advisable to execute a
single computation prior to the actual variant computation.
Start the Variants Wizard now. The command you need is given in the menu
"Analysis" or in the tool bar .
Figure 6.60: Menu option
Note, that the model is reset during the variant computation. Any existing
computation results will be lost. Therefore, save your model before you start the
SimulationX 3 6-87
Variants Wizard. Open the result window of the variables whose curve you want to
observe during the computation. Activate in the result window the option for an
automatic freezing of result curves, if required (see 6.6.4).
If all result variables, which are selected on page Results within the Variants
Wizard should be observed, the option Show Result Windows (see Figure 6.65)
on page Save can be selected. This will automatically open the selected result
windows and activate the automatic freezing option.
If there is an existing variation description (*.var) available for the active model
with the same name as the model file (*.isx, *.ism), that description is loaded
automatically when the Variants Wizard is started.
6.6.3 The Variants Wizard

6.6.3.1 Welcome Page
Figure 6.61: Welcome dialog
Select on the dialog page Welcome whether you want to define a new variant
calculation or use an existing one. You also define the computation task here.
6-88 SimulationX 3
Variant Analysis
You may choose between

transient simulation (set by default)
steady state simulation and
Equilibrium calculation.
6.6.3.2 Parameters
The dialog page Parameters is used to select the parameters to be varied. For
this a tree view is available, similar to that of the model explorer.
Figure 6.62: Dialog Parameters
You can copy the respective entries to the list of parameters to be varied by Drag-
and-Drop or double-clicking.
Parameter Variations can now be defined through Modelica Array construction
expressions. This admits a far more flexible description of variants. Thereby, the
former specification of start value, step size, and end value can be input as follows:
start:step:stop
You can list several values which may be vectors or matrices. For instance, use the
following expression to list the values value1, value2, and value3:
{value1, value2, value3}
Variation calculations can now also include parameters based on strings, Boolean
values and enumerations. The parameter variation must be described in such a way
that the expression delivers a vector of the same type as the parameter itself for the
result. The simplest form is an array constructor:
{<val1>, <val2, , <valn>}
Example:
{true, false}
{SpringDamper.Kind.Spring,
SpringDamper.Kind.Damper}
SimulationX 3 6-89
{c:\temp\file1.dat, c:\temp\file2.dat,
c:\temp\file3.dat}
You can delete list entries by selecting the respective lines and then actuating the
button .
6.6.3.3 Variants
The dialog page Variants lists the parameter assignment for any calculations to
be performed as a table. You can add parameter sets here or delete selected entries.
Figure 6.63: Dialog Variants
6.6.3.4 Results
Select on the dialog page Results the result variables which you want to save for
the analysis of the variant calculation.
Figure 6.64: Dialog Results
At the top of the view you see again the tree of the current model where you can
copy the respective entries to the list below by Drag-and-Drop or double-clicking
with the mouse. The protocol attribute for the selected result variables is enabled
automatically if required.
6-90 SimulationX 3
Variant Analysis
Figure 6.65: Dialog Save
If a result file format is chosen which produces a single file only then it is possible
to let SimulationX automatically open the registered application for the file in
question (e.g. MS Excel for a XML-spread sheet).
There are four output formats available for saving the simulation results:
Text file for any result variable (default setting)
A text file is created for any result variable, which has been entered in the list.
The directory where these files are created can be selected by using the button .
In the following, an example of such a file is given.
In order to make the comparability of the individual variants easier, the results are
saved in an equidistant protocol step size which can be adjusted in the respective
input field.
Force F[N]
Current Frequency f=5 Hz Frequency f=10 Hz Frequency f=15 Hz
simulation
time [s]
0 0 0 0
0.01 0.0610679658897106 0.115427960730342 0.165126435123372
0.02 0.351107779866563 0.648306137116845 0.857805463509306
0.03 0.84043513728217 1.40536310612747 1.52968568804314
SimulationX 3 6-91
0.04 1.26635999100135 1.67116295096669 1.01977814907407

0.05 1.39485305276926 0.909691505499602 -0.899841642475671
XML file
This output format permits saving of any results of the variant computation in a
single file. Standardization of this format permits to analyze and further process the
data saved in this way through an increasing number of other programs such as
Excel.
The name and location of this file can be adjusted by using the button .
input field.
In the following, some part of such a file is given:
input field.
6-92 SimulationX 3
Variant Analysis
SimulationX model for each variant
Expression Meaning
[...] The brackets represent a list of varied parameters in the form of
p1, p2, ..., pn
<comment> Comment of the parameter pi
<name> Name of the parameter pi
<value> Current value of the parameter pi
<unit> Unit of measure of the parameter pi
<ident> Identification of the parameter pi
<iVar> Number of the variant i
<numVar> Number of variants n
Table 6.3: Format definitions
Using this format, the results are not saved separately from the model. Instead the
complete SimulationX model including any logged results is saved for any
computed parameter set. This format should be used if the individual computations
shall be analyzed with SimulationX.
In the field Variant Title Format you can adjust the title of the computed
variant. Table 6.3 gives an overview of the entries which are possible here.
Examples:
If you use varied parameters, such as
And a format string, e.g.:
Than you can observe the following output:
Another format:
SimulationX 3 6-93
Output:
SimulationX project for each variant
Using this format, the complete SimulationX model including any logged results is
saved for any computed parameter set in a new project.
6.6.4 Observing the Computation Results during the Variant

Computation
During the variant analysis the simulation results can be observed by means of the
result windows which must be opened before the Variants Wizard is started. It is
advisable to use the automatic freezing option for result curves for this. To this
end, proceed as follows:
1. Open a Result Window for the variable to be observed.

2. Open the property dialog in the result window and select the dialog page
Representation.
3. Define the settings of the X- and Y-axis manually for the expected results
(minimum, maximum, division).
4. Enable the option AutoFreeze.
The curve labels in the legend are to be given in the format which is specified on
the dialog page Results of the Variants Wizard.
Alternatively to the described preparation and observation of single result
variables, all result variables, which are selected on page Results within the
Variants Wizard (see 6.6.3.4) can be observed using the option Show Result
Windows (see Figure 6.65) on page Save. This will automatically open the
selected result windows and activate the automatic freezing option.
Figure 6.66: Labeled result curves
6-94 SimulationX 3
Order Analysis
6.6.5 Calling External Tools for Post-Processing

To evaluate the variant calculation external tools can be used. This can be called
after the simulation of a variant and can use the COM interface to access the
calculated results. To configure a program to be called from a variant calculation,
press the Post-Processing button.
Under "Program" you fill in the full path to the program to be executed. The
command line parameters required to be given under "Arguments". If required, a
working directory for the external tool can additionally be determined.
Figure 6.67: Dialog for setting the call parameters for external tools
In order to ensure the uninterrupted flow of a variant calculation, the called

program should not allow interactions with the user.
Figure 6.67 shows the settings for calling the TVA Report Generator. The paths
may need to be adjusted accordingly.
6.7 Order Analysis
Order analysis is a method of frequency analysis for drive systems. It allows easily
detecting and displaying resonances. So order analysis is applied, e.g., in the
investigation of combustion engine drive trains and drives with nonuniform
transmission ratios.
Order Analysis provides a tool for this kind of frequency domain calculations. The
close interaction with the simulation software SimulationX of ITI simplifies the
import of the simulation data to be analyzed. A multitude of customization options
and the automatic selection of reasonable default values for parameters ensure a
flexible, easy, and fast exploitation of the program. Result diagrams can be printed
or exported via the Windows clipboard. All data, settings, and results can be saved
to a file for later reuse.
SimulationX 3 6-95
6.7.1 Installation
The order analysis is not part of SimulationX setup. When required it must be
installed therefore.
When you call the Order Analysis for the first time, a corresponding selection
dialog (see Figure 6.68) appears. There you can choose the installation media
between product DVD and download from the Internet. After successful
installation the Order Analysis can immediately be called without SimulationX
must be vacated.
Figure 6.68: Subsequent installation of the order analysis
Alternatively, the installation can also be done from the start screen of the
SimulationX installation DVD.
Choose the corresponding option and click on Installation.

Alternatively, you can download the setup for the Order Analysis from the
Helpdesk. Simply run the OrderAnalysis.exe. To use the Order Analysis, you are
required to have a valid license for it.
6.7.2 Functionality
An order analysis is performed using simulated or measured run-up or run-down
data for a drive.
The input data sets are the signal to be analyzed A(t ) (e.g., the torque of a shaft or
the acceleration at some location in the drivetrain) and the base signal (t ) (e.g.
the rotary speed) over a common time base.
6-96 SimulationX 3
Order Analysis
6.7.2.1 Basis Signal over Frequency (Computation over the Time)

The signal to be analyzed is partitioned into time segments of the length , which
are assigned to certain sampling points of the base signal. The segments are
transferred to the frequency domain by means of a fast Fourier transform (FFT).
The result of the fast Fourier transform can be further used to calculate the
coefficients of a Fourier series, which approximates the analyzed signal as a
function over time:
N 1
2
A(t ) a0 + ak cos k t + k (6.36)
k =1 T
N / 2 1
The maximum frequency f max = depends on the number of samples and
T
the sample time that were used for the FFT.
The coefficients a k are displayed as sonogram or as waterfall diagram alternatively
k
(see Figure 6.69). The frequencies f k = are assigned to the x-coordinate the
T
values of the basis signal are plotted on the y-axis.
Figure 6.69: Sonogram and waterfall diagram
Eigenfrequencies can be spotted as vertical lines in the sonogram (cf.

Figure 6.69) on left with approx 14 periods per second). If an eigenfrequency is
excited, the corresponding area in the plot appears in a different color.
The kind of result representation induces a requirement on the input data: The basis
signals floating average has to be strictly monotonic (see 6.7.3.2).
SimulationX 3 6-97
6.7.2.2 Basis Signal over Order (Computation over the Integral of Base
Signal)
As opposed to the computation over frequency the analysis signal is not divided
into time intervals T . Therefore, in a first step the time axis is replaced with the
t
basis signals integral over time (t ) = (t )dt :
0
A(t ) = A( (t )) . (6.37)
For the mentioned possible application example (run-up or run-down of

powertrain), where the base signal is usually given by engine speed, the base
signals integral corresponds to the engines rotation angle .
After substituting time by the integral of the base signal, it is possible to cut the
analysis signal A into parts with equal width P over and relate them to a value
of the base signal .
The results of the FFT (with equidistant sample points over the base signals
integral ) can be assigned to the coefficients of a Fourier series, which
approximates the analysis signal as a function over :
N 1
2
A( ) a0 + ak cos k + k . (6.38)
k =1 P
Knowing the period p of the analysis signals first harmonic over , (which is one
revolution of the engine, leading to = 2 in the above mentioned application
example) the coefficients of the Fourier series can be related to the harmonic
orders:
kp
nk = . (6.39)
P
kp
(Figure 6.70). The orders nk = are assigned to the x-coordinate the values of
P
the base signal are plotted on the y-axis.
The kind of result representation induces a requirement on the input data: The base
signals moving average has to be strictly monotonic (see 6.7.3.2). Furthermore the
computation algorithm requires that the base signals integral is strictly monotonic
in the interval of interest.
6-98 SimulationX 3
Order Analysis
Figure 6.70: Sonogram and waterfall diagram (Basis signal over Order)
6.7.2.3 Order over Time

The calculation is similar to the one in section 6.7.2.2, that means time is
substituted by the integral of the base signal. However the intervals of length P are
no longer assigned to a value of the base signal but time. This is especially useful
if the experiment, that ought to be analyzed, is not a run-up or run-down. For
example if the data originates from measurements which were recorded with
constant engine speed.
(see Figure 6.71). The time t is assigned to the x-axis whereas harmonic orders
correspond to the y-axis.
The computation of orders over the base signals integral requires its strict
monotony in the interval to be analyzed (see 6.7.3.2).
Figure 6.71: Sonogram and waterfall diagram (Order over time)
SimulationX 3 6-99
6.7.3 Operation
ITI-ORD is started either via the menu Analysis/Order Analysis within
SimulationX or via the Windows Start menu.
Both sections of the window (see Figure 6.72 ) are arbitrarily resizable.
An analysis run is performed in four steps:
1. Source data import
2. Specification of the analysis settings
3. Specification of the display settings
4. Saving, printing, result export.
Properties Window Diagram Window
Figure 6.72: Program window
6.7.3.1 Import of source Data

Selection of application
At first the application has to be selected, which supplies the source data. The
selection field contains only the actual installed applications.
6-100 SimulationX 3
Order Analysis
Figure 6.73: Source Data Import
Selection of result variables

An order analysis requires a signal to be analyzed A(t) as well as the corresponding
base signal (t) (e.g. rotation speed), both are imported from the Application. The
protocol attributes for the corresponding result variables have to be set. The model
itself must have been completely simulated and saved at least once.
It is highly recommended that analysis and base signal are generated from the same
simulation model. In the interval that ought to be analyzed the base signal should
monotonically increase (run-up) or decrease (run-down), for further detail please
refer to section 6.7.3.2. Using the result representation (view), there is no
restriction regarding the monotony of the base signal.
Using the views Order over time or Base signal over order a source for the
Integral of the base signal (over time) can be defined optionally. If no signal for
the Integral is supplied, it is calculated numerically.
Figure 6.74: Numerical Integration of the basis signals
Next, in ITI-ORD the button beside the corresponding identifier (Figure 6.74)
is pressed. A window opens, which shows a tree view of all currently opened and
already saved models. Select the corresponding result quantities and press the OK.
This creates the link to the corresponding result quantities. The input box next to
the button now shows a text with the following syntax:
COM@AppID@Model@ModelObject@ResultQuantity
SimulationX 3 6-101
The '@' symbol is a separator for the individual identifiers. The identifier COM
indicates, that the connecting to the Application is achieved via the COM interface.
The AppID indicates the selected application. These entries are subject to further
extensions and should be left unaltered. There follows an entry for the file name
(including the complete path) of the model. The two entries at the end specify the
model object and the result quantity. The last three entries can be set manually too.
This allows, e.g., a quick and easy change of the model file name and path.
When linking the input fields Analysis signal and Base signal are assigned with the
name of the model and the corresponding result quantity. The texts are used to
label the plot axes and can be overwritten with a text of users choice.
To be able to select a source for the time integral of the base signal from the tree
view the corresponding option button has to be selected (see Figure 6.75).
Figure 6.75: Selection of the integral of basis signal
Please note, that it is currently not possible to analyse vector or array sized signals.
If you want to analyse such signals, you have to tranform them into multiple scalar
ignals during the simulation. For the angular velocity of a rigid body with name
body1 from the multi-body library is a vector of length 3. Its x-value can be
referenced with body1.om[1] in a function signal block, whose output is then
used for analysis.
The source data import itself takes place once the analysis and base signals are
assigned to result variables in a model.
Data import is restarted by pressing the Update button (necessary, e.g., if there
was a new simulation providing modified data). If the selected application is not
running at this time, the program is started and the corresponding model is loaded.
For the case that the application, the model, the model object, or the result quantity
is not found, an error message appears. All links to result quantities can be
6-102 SimulationX 3
Order Analysis
modified or newly created at any time. Using the button Info a window is opened,
which displays information about the imported signals.
Period of the base signal

The selection of the base signal includes the definition of the period length
(Figure 6.76).
If the selected result quantity is a rotary speed (e.g., the speed of a rotary node),
then is the period length (2 [rad]). If the base signal is another quantity, then you
have to enter the period in SI. Example: When base signal is delivered in m/s, then
the period has to be specified in meters.
Figure 6.76: Definition of period length
The length of period is important for the correct display of the order lines. The
period length will also be used for the creation of equidistant courses (see section
6.7.3.1).
It is possible to change the period length later and to redo the order analysis.
Creation of equidistant courses

If the courses of the source data are not already equidistant, then equidistant
courses will be created. The sampling time (dt) is calculated from the maximal
step size in the base signal (Base1..n) :
Basemax
f max =
2
(6.40)
1
dt =
2 f max
The values of the base- and the analysis signal are linear interpolated.
SimulationX 3 6-103
6.7.3.2 Setting of Analysis Options

The analysis settings are modified in the middle section of the properties window
(Figure 6.77).
Analysis Options with Computation over the Time

The parameter Number of FFTs defines the number of signal segments, i.e., the
number of FFTs to be performed during the analysis.
There are two possibilities to form the segments.
Figure 6.77: Modification of analysis settings
Continuous Segment Distribution

The time segments are constructed with the help of the following algorithm:
1) The range of the base signal from min to max is divided into equally
spaced intervalls. The base signal reference points 1 , , are the
midpoints of these intervals.
2) To each of the reference points the sample time point [] is assigned
where the reference signal exceeds for the first time. Thereby, for a
runup the reference signal is searched for this sample point with growing
time and for a rundown with falling time.
3) For the inner grid values with = 2, , 1 the FFT time segments
1 1
start at [1] + [] and end at [] + [+1] .
2 2
The left boundary of the first time segment is chosen as max min , [1]
1
2
[1] + [2] and the right boundary of the last time segment is chosen
1
as min max , [] + [1] + [] .
2
6-104 SimulationX 3
Order Analysis
Consequently, the signal segments may be of different lengths. Figure 6.78

demonstrates this at hand of an example with = 3.
()

3
2
1

1st FFT 2nd 3rd
Figure 6.78: Base signal reference points and time segments for the FFTs
With this approach the complete data set for the reference signal range from min
to max is covered with FFTs. There are no disregarded signal parts as well as no
overlapping segments within this range.
Please consider that using this method there is no way of directly influencing the
length of the individual signal segments. For long signals and sparsely distributed
base signal observation points fairly long segments are created. Inside such a
segment the frequency can vary considerably, which may corrupt the FFT results.
For short segments and dense base signal observation points the segments become
very short, which results in a decrease of frequency resolution.
Fixed Number of Segments

In this method you can specify the number of sampling points n belonging to a
n n
signal segment. A segment then consists of samples before and samples after
2 2
the respective basis signal observation point.
Consider, that (especially for long signals, sparse base signal observation points,
and small numbers of FFT samples) some parts of the signal might be disregarded
in the calculation of the FFT spectra. So there arises a risk of missing existing
resonances. In the opposite case there might be an overlap of segments which
results in an assignment of one signal part to several frequency observation points.
This may lead to a blurring of the results. Therefore, a variation of the selected
analysis parameters in conjunction with a critical analysis of the obtained results is
always recommended.
The Minimum and Maximum settings define the signal section to be analyzed and
specify the target frequency range.
SimulationX 3 6-105
By pressing the Automatic button reasonable parameter values are selected for all
settings. In particular these are:
Continuous distribution of the base signal observation points
50 FFTs
Minimum and Maximum values of the base signal
1
Minimum frequency = 0, max. Frequency = (dt is the time step size of the
2dt
signals)
If consistent parameters are selected, the button Calculate can be pressed in
order to perform the order analysis and to show the current result.
Analysis Options with Computations over the Angle
Figure 6.79: Dialog for setting the analysis options by computation over the angle
For the views Base signal over order and Base signal over time the following
computational parameters can be changed (cf. Figure 6.79):
Parameter Comment
Sampling points per FFT Number of sampling points that are used
for FFT (this value must be even numbered
but not necessarily has to be a power-of-
two)
Number of periods The width of a interval P is given by the
product of the number of periods and the
period length.
Number of FFTs This parameter defines the number of
windows (intervals) distributed over the
whole data
6-106 SimulationX 3
Order Analysis
Max. Order Maximum order to be displayed

Time - Minimum Lower limit of the time interval that ought
to be analyzed
Time - Maximum Upper limit of the time interval that ought
to be analyzed
Table 6.4: Changeable parameters for computation over angle (time integral of base
signal)
Sampling Points per FFT

For the computation of discrete Fourier transform on an interval P according to
equation
N 1 2
i k j
X [ j] = x[k ]e N (6.41)
k =1
N samples of the analyzed signal x[k] are used.

It has to be considered that the number of sample points must be even numbered
and that maximum order that can be displayed is related to this number as follows:
N / 2 1
nmax = (6.42)
M
where M is the number of periods (see Figure 6.80).
Number of Periods
This parameter defines the width P of the intervals used for FFT as an even numbered
multiple of the basic period length p.
Figure 6.80: Number of periods M
SimulationX 3 6-107
The number of periods constitutes the resolution of harmonic orders:

1
n =
M (6.43).
This is why M has to be even numbered; otherwise the solution would not contain
the 0.5th sub harmonic.
Number of FFTs
This parameter defines, how many FFT-windows are placed over the interval that
ought to be analyzed (between Minimum and Maximum). Therefore this number
also affects how much the FFT windows do overlap each other. In an extreme case
two neighboring windows are closer to each other than the source datas samples.
In this case an error message appears after computation has started via Calculate
button. That means the value for the Number of FFTs has to be reduced
considerably.
Maximum Order
The parameter Max. Order ( nmax ) defines the maximum order displayed in any
diagram.
The number of sampling points N (see 6.7.3.2 ) affects the maximum order that can
be displayed:
N / 2 1
nmax = . (6.44)
M
Thus the value of nmax may be automatically decreased. In this case the number of
sampling points per FFT N has to be increased to guarantee the desired maximum
order nmax .
Definition of the Analysis Interval
Figure 6.81: Definition of analysis interval
6-108 SimulationX 3
Order Analysis
With the parameter Minimum and Maximum the boundaries of the interval that
ought to be analyzed are defined. The values correspond to the beginning (the end)
of the first (the last) FFT window. See Figure 6.81 for a graphical explanation.
A modification of the boundaries is strongly recommended if the source data

violates the above mentioned requirements concerning the monotony of base signal
or its time integral. (see also section 6.7.3).
If the view option Base signal over order is selected, the corresponding boundaries
of the base signal are shown below the time limits (see Figure 6.81). These values
are not editable, but one can change the unit of the base signal that is used for
result representation.
6.7.3.3 Setting Display Options

The most important display options can be set in the bottom section of the
Properties Window.
Figure 6.82: Display Options
After marking the checkbox Signal the minimum and maximum of the FFT
values in the display can be specified. This makes sense, if there are significant
differences in the dimension of the individual FFT values.
Further, the display can be toggled between a sonogram and a waterfall diagram
and orders can be highlighted.
The viewing angle of the waterfall diagram can be changed by clicking on the
display and moving the mouse with the button pressed. The perspective is reset to
the defaults again via the diagram windows context menu entry Reset. The
Properties entry in the context menu opens a dialog for the adjustment of the
display options, which allows modifying the remaining display parameters.
Display of Order Lines

The button Order lines shows the dialog order lines (Figure 6.83).
Each order line can be visible or hidden and has its own comment. Rational orders
are also shown.
SimulationX 3 6-109
Figure 6.83: Setting of order lines
The button Order lines shows the dialog order lines (Figure 6.83).
Each order line can be visible or hidden and has its own comment. Rational orders
are also shown.
2D Display
The 2D View shows the amplitudes of the base signal pursuant the selected orders
(Figure 6.83). You achieve the view by clicking the button 2D View.
The 2D display represents the amplitudes in accordance with in Figure 6.82

selected orders depending upon selected type of representation over the basis
signal (basis signal over frequency) or over the order (basis signal over order).
The sum level is the maximum of the analysis signal in the time-domain (at the
analyzed base signal). The visibility of the sum level can be set in the dialog of
order lines
Figure 6.84: Illustration of the amplitudes of the speed of the selected orders
6-110 SimulationX 3
Power Balance
6.7.3.4 Saving, Printing and Result Export

Via the menu entry Save all data can be saved to a file at any time.
If analysis data signals were already imported, they are saved too. Thus a use of the
program is also independently of the simulation software possible. Data is stored in
XML. Thus the data files can be manually edited and can be imported into other
programs.
The default Windows print interface is used for printing.
Result graphics are sent to the clipboard via the Diagram Window context menu.
The export can be carried out in terms of bitmaps or vector graphics (Enhanced
Metafile).
CSV-Export of the 2D Display

In the window of the 2D display the curves can be exported over the menu File
save... in the ASCII format. There the values are saved in columns separated by
commas. Thus a simple import into result windows of SimulationX is possible.
There e.g. the comparison of the results of different source data can take place.
6.8 Power Balance

6.8.1 General Functionality
The Power Balance can be used to analyze the flow of power and energy in a
SimulationX model. Often it is not sufficient only to measure the power flowing
into or out of a technical system. Only based on that, answers cannot be given to
the question whether e.g. the applied power of a power source is stored or lost in
the system. With the help of the Power Balance in a SimulationX model you are
able to investigate these questions systematically.
In SimulationX the Power Balance is currently available for the libraries Linear
Mechanics, Rotary Mechanics, Electronics and Hydraulics. All elements of these
libraries calculate their characteristically powers. They are defined by the product
of the flow quantity (e.g. mechanical force) and the potential quantity (e.g.
mechanical velocity). Elements can apply power to the system (e.g. mechanical,
external torque), store power in the system (e.g. mechanical inertia or spring) or
generate power losses in the system (e.g. mechanical damper).
Due to that 4 types of power are defined in the system

Input Power (applied power)
Stored Power Type A
Stored Power Type B
Power Loss
The following table (cf. Table 6.5) gives an overview of these 4 types of power
and example elements in the libraries where they occur.
SimulationX 3 6-111
There are no general standardized names for both kinds of stored power in
different physical domains (cf. Electronic vs. Mechanics). Because of that the
generic terms Stored Power Type A and B are used.
So elements, e.g. the mechanical spring-damper-element, calculate according to

their functionality several power componets.
The Power Balance in SimulationX collects all power components of the elements
in the actual model and assigns them to the 4 types of power. In the model 4 new
result variables are generated, where the assigned power components are summed.
The following table(cf. Table 6.6) shows these 4 Power Balance variables and
defines, which power components of different libraries are assigned.
Library Input Power Stored Power Stored Power Power Loss
Type A Type B
Linear External Power Change of Change of Power Loss
Mechanics Kinetic Energy Potential Energy
e.g. External e.g. Mass e.g. Spring e.g. Damper

Force
Rotary External Power Change of Change of Power Loss

Mechanics Kinetic Energy Potential Energy
e.g. External e.g. Inertia e.g. Spring e.g. Damper

Torque
Electronics External Power Change of Change of Power Loss

Electric Field Magnetic Field
Energy Energy
e.g. Voltage e.g. Capacitor e.g. Inductance e.g. Resistor
Source
Hydraulics External Power Change of Change of Power Loss

Kinetic Energy Potential Energy
e.g. Pressure e.g. Line (with- e.g. Volume e.g. Nozzle

Source out losses)
Table 6.5: Types of Powers in the libraries and example elements
6-112 SimulationX 3
Power Balance
Input Stored Power Stored Power Power

Power (Type A) (Type B) Loss
PSrc PStoreA PStoreB PLoss

Linear Pe Pk Pp Pl
Mechanics
Rotary Pe Pk Pp Pl
Mechanics
Electronics Pe Pelek Pmag Pl
Hydraulics Pe Pk Pp Pdiss, Pfr
Table 6.6: Power Balance variables and the assigned powers
On demand you can calculated the related energies by integration of these 4 power
variables.
Furthermore the sum of all powers PSum can be calculated.

PSim is calculated out of the 4 Power Balance variables:
PSum = PSrc ( PStoreA + PStoreB + PLoss ) (6.45)
This variable is a control variable which shows that all components of power are
used in the balance. In that case PSum is 0.
6.8.2 Generating a Power Balance in SimulationX

6.8.2.1 General Procedure
To insert a Power Balance you have to select at first the structural view of your
model.
Figure 6.85: Insert a Power Balance
SimulationX 3 6-113
Now click on the option Power Balance in the menu Insert.

In the following window you can choose the power and energy variables you want
to add. Enter the selection with the button OK.
Figure 6.86: Choose the power and energy variables
After that, the result variables are generated in the model. They are visible in the
model explorer and their protocol attributes can be activated here.
After opening the model in the TypeDesigner (click on Types in the model
explorer- then double click on model name), you can find these variables on the
page Components. The corresponding balance equations (summation of the single
power variables) are defined on the page Behavior on a separate tab Equations
which starts with the comment //Powerbalance: Do not change
manually! (cf. Figure 6.88).
Figure 6.87: Model Explorer power and energy balance variables
Manual editing of these equations is not prohibited, but then there is no guaranty
that the complete power balance is correct. Therefor these equations should not be
changed manually.
6-114 SimulationX 3
Power Balance
Figure 6.88: TypeDesigner balance equations
After changes of the structure of the model or names of model elements the Power
Balance must be updated manually. Simply click again on Power Balance (cf.
Figure 6.85)!
6.8.2.2 Procedure in models with compounds

A Power Balance can also be added in models with substructures (Compounds). In
that case the Power Balance has to be inserted in the compounds first, before a
balance in the whole model can be applied.
So first insert the Power Balance on the lowest substructure level (e.g. compound
in a compound). After that, add the balances on the next higher level and proceed
up to the top level of the model. This procedure ensures that power components of
all model substructure levels are considered in the total balance of all powers.
To Insert a Power Balance in a compound you have to open the diagram view of
respective external or inner compound (right-click on the element type-Open-
Diagram View). After that the Power Balance can be added as in section 6.8.2.1
specified.
The completeness of the Power Balance can be checked with the sum of all powers
PSum (cf. section 6.8.1). When all components of power on all substructure levels
are collected successfully, then in the comprehensive modell PSum = 0.
6.8.3 Power Sensors

In the element libraries Linear Mechanics, Rotary Mechanics, Electronics and
Hydraulics you can find corresponding power sensor elements.
SimulationX 3 6-115
The following table lists these elements.
Sensor Result Variable

Linear Mechanics Power Sensor Mechanical Power Pmech
Rotary Mechanics Power Sensor Mechanical Power Pmech
Electronics Power Sensor Electric Power Pel
Hydraulics Power Sensor Hydraulic Power Phydr
Table 6.7: Power Sensors
The Power Sensors can be connected in series between two elements of the
respective library. They measure the power flow in the connection between these
two elements.
Figure 6.89: Insertion of a Power Sensor in Linear Mechanics
6.9 Troubleshooting: What should I do if...

This chapter and chapter 11 give answers to the most frequently asked questions
and tells you what you can do in the case of warnings and error messages. You
also find information about how you can optimize solver settings with regard to
accuracy and computation speed. For understanding the definitions about the
solver please refer to chapter 12.
There can be different classes of problems when running a simulation. Solutions

for these problems can be found in the following sections and section 11.3.
In section 11.3 you find solutions to the following items:

For BDF and MEBDF method (section 11.3.1)
There are empty parameters!
System is singular!
Calculation of consistent initial values failed!
The calculated initial state does not fulfil my expectations...
6-116 SimulationX 3
Troubleshooting: What should I do if...
Calculation of consistent initial values failed after a discontinuity.

Cycle found in the event iteration.
The required accuracy cannot be reached...
The solution failed to converge!
Linear system of equations is not solvable and order and the step size not
reducible
Exceeding of the Minimum/ Maximum of state
Exception during the calculation
Error during the calculation of the damping factor for the Newton update
Steady State (Equilibrium) not found!
Calculation of equilibrium stopped
At least one absolute tolerance is less or equal zero!
At least one relative tolerance is less or equal zero!
The number of states and the number of equations are not equal!
The time domain simulation takes very long!
Can I be sure that the simulation results are correct?
For solver with constant stepsize and CVODE (section 11.3.2)

"Error: System of equations with the DAE state(s) cannot be solved! " or
"Error: Equation with the DAE state(s) cannot be solved! ")
"Residual is not in the image of Jacobian ... with the DAE state(s) ..."
"the value is below the minimum () of the DAE state ",
"the value exceeds the maximum () of the DAE state "
"Reducing the damping factor to because of the DAE state ",
"DAE state exceeds a border"
6.9.1 Frequent Modeling Problems

Now have a look at some frequent modeling problems:
Problem 1: Missing capacity (mass inertia, volume etc.) between elements

Please think about, whether you can do it without the capacity in similar models.
Unexpected model behavior or numeric problems in solution are often the
consequences of such models.
SimulationX 3 6-117
Problem 2: Missing Damping

Missing or too small damping results in vibrations which stop often for a long time
or even develop. Unexpected model behavior and slowed simulation calculation
respectively are the consequence. Too little damping is often used for elastic stops.
6-118 SimulationX 3
Problem 3: Large curves (data tables) with linear interpolation

Slow simulation
due to
discontinuity
handling at each
sample point of
the curve!
Use of spline interpolation, hyperbolic interpolation, arc interpolation or

quadratic approximation is recommended!
6.9.2 Calculation of consistent initial values failed

For solving problems use the Tracing function (see also 6.1.1.4). Some important
solution strategies will be given in the following text.
Solution 1: Initial value problem

Step (1): Understand the problem
The set of equations cannot be fulfilled at t=0 with the
specified set of initial values ('fixed' or 'not fixed' )
Step (2): Find the reason for the problem

Examine the error message in the output window. Find the
residual(s), which are above the tolerance level (normally
absTol, if not scaled internally). Find the state variable(s),
which have influence on this residual(s).
SimulationX 3 6-119
No state has any

influence on the
residual!
Modeling
problem!
Step (3): Try to solve the problem by...

... Changing the corresponding initial values ( / )
... Changing the model
... An equilibrium calculation ( ) before the transient simulation
(if initial values are not so important for the application)
6.9.3 Singularity problem

Step (1): Understand the problem!
There is (at least) one state variable, which does not influence any
of the equations, and/or there is (at least) one equation, which is
not influenced by any state variable (or derivation). A singularity is
normally caused by a modeling error (e.g. missing capacity, mass,
volume etc.).
Step (2): Find the reason for the problem!
Examine the error message in the output window. Find the state
variable and/or equation, which is singular.
To narrow down the error it may be useful to turn on the tracing

flag "Equations at end of symbolical analysis" on the page Tracing
in the Simulation Control dialog.
Step (3): Try to change the model accordingly!
6.9.4 Slow simulation speed

Step (1): Understand the problem:
6-120 SimulationX 3
There are mainly 3 reasons for a slow simulation speed:

a) an oscillation with a high frequency and low damping
b) too many discontinuities
c) too many invalid steps
Step (2): Find the reason

a) Examine the natural frequencies
b) Examine the occurrence of discontinuities

Some possible reasons for too many discontinuities are
- Friction (stick/slip)
- Curves with linear interpolation
- Unstable valve operating (open/close)
- Toggling of limitation functions
SimulationX 3 6-121
c) Examine the occurrence of invalid steps!

Possible reasons for too many invalid steps are
- highly non-linear behavior
- poor Jacobian matrix
- hidden discontinuities ('noEvent(...)')
Decrease the tolerance and the step size!
6-122 SimulationX 3
Step (3): Reducing the tolerance and the step size!
6.9.5 General Hints

The absolute and relative tolerance (absTol and relTol) should only be
increased as a last resort if no other means are left to reach convergence.
Sometimes it helps to choose smaller values for absTol and relTol.
The minimum step size (dtMin) often needs to be reduced for models
containing hydraulic, electronic, and/or magnetic elements with small time
constants (e.g. caused by small volumes, capacitors, or inductivities). The
typical numerical range of values for dtMin in these domains of
applications reaches from 1e-16 to 1e-12.
The minimum output step size (dtProtMin) prevents the creation of a large
amount of data. The default setting (0.001) produces at least 100 output
samples for a simulation time of 1s. If you wish to investigate high-frequency
SimulationX 3 6-123
oscillations, you should decrease the value of dtProtMin. To see all data
generated by the solver you may enter dtDetect as value for
dtProtMin.
The value of dtDetect should not be changed. This step size only affects the
accuracy of the detection of discontinuities. The value should not be higher than
the minimum step size. The minimum step size dtMin should be an integer
multiple of dtDetect.
6-124 SimulationX 3
by
Results and Documentation

Overview
7 Result Analysis, Documentation and Settings

7.1 Overview
Each model element calculates a number of result variables depending on its
functionality and complexity. At every output time step all active result variables
of all elements of the model are provided.
This means that during the simulation a large set (of data) is created.
The following chapter shall show you the possibilities to handle simulation results.
Depending on the respective analysis requirements, you may use
visualizers or
result windows.
A result printing is also available (cf. 7.3.8).

In order to be able to reuse the developed models, parameters and results, they can
be saved.
The following options are supported by the program:

A calculated model is saved together with its results. This is done whether a
result window is open or not at the time of saving.
Open result windows can be saved together with the model and retrieved.
Individual results can be saved as a file on a data medium. File format, name
and directory can be selected by the user (see section 7.3.7). This is done with
the File /Save menu option.
7.2 Visualizer
To evaluate the quality of a model, e.g. in the phase of model development or
troubleshooting, it is often sufficient to evaluate selected result variables at the
respective time step. Such evaluations are for instance:
Does any result variable exceed a certain limit?
Does a result variable lie within a certain range?
Does any result variable change at all?
To continually observe as many result variables as possible is not easy, particularly

with large models. The visualizers in SimulationX are a valuable help for these
tasks.
SimulationX 3 7-1
User Manual 7. Result Analysis, Documentation and Settings
7.2.1 To Open the Visualizer

Visualizers are opened with the menu Insert Visualizer (see
Figure 7.1). Any result variable can be linked with any visualizer. Visualizers can
be freely placed just like elements on the worksheet.
Please note the settings in section 7.6.1.
Figure 7.1: Visualizers
7.2.2 Linkage with Result Variables

Double-click on a visualizer to open its property window. On the page Display all
elements and result variables are displayed in a selection box where they can be
selected by clicking on them (see Figure 7.2).
The unit of measure is preset according to the properties dialog of the element and
cannot be changed.
Figure 7.2: The tab Momentary display
Further a minimum and a maximum value can be defined (see Figure 7.3).
Depending on the selected display options additional setting are available.
7-2 SimulationX 3
Visualizer
Figure 7.3: Range which can be set
In the case of the bar graphs and the speedometer this corresponds to the range
which can be displayed. The signal lamp is lit when the linked variable is within
the range.
7.2.3 Other Settings

The following settings can be made:
Variable Reference to a scalar parameter or a scalar variable
Minimum Minimum scale value
Maximum Maximum scale value
Start Angle Position of the minimum scale value in degrees
(see Figure 7.4)
End Angle Position of the maximum scale value in degrees
(see Figure 7.4). If the end angle is smaller than the
start angle, the direction of the scale is reversed.
Show Major Ticks Determines whether the main subdivision of the
scale is displayed.
Show Minor Ticks Determines whether the secondary partition of the
scale will be displayed.
Major Ticks Number of intervals for the division of the entire
scale
Minor Ticks Number of intervals for the division of each
principal interval
Decimal Digits Number of decimal digits to display
Fractinal Digits Number of decimal places
Text Color of the label
Pointer Color of the pointer
Background Background color
Frame Frame color (also for the lines of the scale
subdivision)
SimulationX 3 7-3
Label Labeling of the display. The following macros can

be used:
<comment> Comment of the variable
<name> Name of the variable
<ident> Ident of the variable
<unit> Unit of the variable
Figure 7.4: Configuration dialog for the circular gauge
Display as described in Figure 7.4 Dual display
Figure 7.5: Display of the circular gauge
Note: If the background color is set to Transparent, multiple display elements can
be layered on top of each other (see right image of Figure 7.5.
7-4 SimulationX 3
Visualizer
Size and Position

With this tab the size and position can be selected. This is also possible by
dragging or pulling the window of the momentary display open.
7.2.4 Extended Visualizers

7.2.4.1 Chart
Charts can be used to visualize the current state of scalar and multi-dimensional
variables (parameters and result variables). They include a variety of available
options:
Line chart
Polar curve
Area chart
Bar chart
Pie chart
Surface diagram (2D, 3D)
SimulationX 3 7-5
Some diagrams offer additional parameters for a more customized representation.
Figure 7.6: Parameter settings for visualizers
For the data assignment, it is possible to specify whether the data series should be
given in columns or rows and whether the first row or column should contain the
corresponding arguments (if they cannot be derived from the values index in the
respective column or row).
7-6 SimulationX 3
Visualizer
Labeling, minimum and maximum for each axis of the diagram can also be set. If
the minimum and maximum have the same value, the axis is scaled automatically.
Scalar variables can only be represented as lines as a function of time. The axes are
labled automatically without the option of modification in the table.
Additional options are available to customize colors and labeling.
7.2.4.2 Sankey Diagram
Figure 7.7: Sankey diagram
Sankey diagrams are used to visualize flows within a process or system.
7.2.5 Comment
Visualizers can be used for visualizing results anywhere in the model where the
current value is more important than the entire progress over time. Refreshing the
overlay display requires more computation time. If visualizers are only used for
SimulationX 3 7-7
visualization purposes during a recorded animation, they can be disabled for the
actual simulation (Extras/Options => General).
7.3 Result window
Result windows are used for graphical presentation of simulation results and their
interpretation. They are being updated during the simulation process and allow
continuous monitoring of the running computation.
Figure 7.8: Result window with result curve
7.3.1 Basics
In order to show a result curve of a model variable, several conditions must be met:
1. The variable must be defined as a result quantity in the model. Result
quantities are all those variables that were not explicitly declared
parameters.
2. The variables protocol attribute must be enabled. This can be done in
the Properties window of each component or in the Model Explorer. The
Result Bar (see 7.3.2.5) in the result window provides another way to
activate the protocol attribute (see section 7.3.3.2).
Values recorded during the computation are stored in temporary files by default.
The performance can be improved by increasing the reserved buffer size for each
result value or by keeping the data itself in the memory (RAM). This setting,
however, requires significantly more memory and should therefore only be used on
suitably equipped computers.
Memory requirements for storing results of transient simulations can be estimated

as follows:
= (1 + + ) 8
s Memory requirements in byte
7-8 SimulationX 3
Result window
nprot Number of logged variables

ntimeSteps Number of valid time steps*
neventSteps Number of event steps*
* These values depend on the value of dtProtMin and the settings for
logging results in the Property Bar of the transient simulation.
7.3.2 Opening result windows

Result windows can be opened in different ways. Once opened, the result window
is saved with the model and can be used again immediately after reloading the
model.
7.3.2.1 Empty result windows

An empty result window, i.e. a result window with no
result curve, can be created from the menu Insert or
by clicking the corresponding button in the Result
Window Manager. Empty result windows can be
populated through drag-and-drop (see 7.3.2.3) or by
pasting previously copied curves. When creating an
empty result window, the Result Bar is activated
automatically permitting a quick selection of result
quantities to be displayed in the newly created result
window.
7.3.2.2 Context menu (structure view)

The context menu of elements and connections in the structure view provides
various options to create immediate result windows for individual variables or
groups of variables.
If several result curves are shown in one result window, following options are
available:
arrange curves within one panel
arrange curves in different panels on one page
arrange curves on different pages (one result curve per page)
For multiple selections all related variables of the same name are shown together in
one panel.
SimulationX 3 7-9
7.3.2.3 Model Explorer

Result windows can also be created from the Model Explorer via drag-and-drop
following the instructions below:
1. Move the cursor over an activated result variable icon.
2. Click and hold the left mouse button.
3. Drag the selection in any model view window of the active model. This may
be the Structure View, 3D View or Text View.
4. Release the mouse button. SimulationX will then create a new result window
with the corresponding result curve.
You can also drop the selection in an open result window. In this case, the result
curve will be added to the existing curves in the window. Depending on where it is
dropped, the result curve will be integrated into an existing panel or added to the
result window as the first result curve of a new panel or of a new page. For details,
see section 7.3.4.
In order to allow for new result windows to be positioned more precisely when
dragging and dropping results from the parameter dialogs of elements and
connections, the parameter dialog becomes transparent during such operations.
7-10 SimulationX 3
Result window
7.3.2.4 Properties window (model elements and connections)

The Properties window of elements and connections summarizes the result
quantities of the selected component on one or more pages.
By clicking the icon of a protocol attribute, logging the corresponding variable can
be enabled or disabled. You can also drag the icon and drop it in a model view
window to create a new result window, or drop it in an existing result window to
add a new curve.
7.3.2.5 Result Bar (Result window)

The result window shows a tree of all result
variables for those models currently open. In order
to display the result curve of a result variable, drag
and drop its icon in the graphical output area of the
result window.
To switch the protocol of a variable on or off, right-
click on the variable and select the command from
the context menu.
For comparison with previous simulations, saved curves can be loaded in an

existing result window. The following file formats are supported:
Result View Configuration (*.rsx)
ITI SimX format (*.rfs)
Text format (*.txt, *.csv)
SimulationX projekt file (*.isx)
These result variables become available in the

result tree and can be used in the same way as
existing model variables.
SimulationX 3 7-11
Please note that unlike other file formats, a SimulationX result configuration file
includes only references to variables, not the actual values. The available result
variables are accessible through the Result Bar.
7.3.2.6 Result Window Manager

New, empty result windows can be created,
and saved result windows can be loaded
through the Result Window Manager.
For creating result windows, the following file formats are supported:
SimulationX result configuration (*.rsx)
ITI SimX format (*.rfs)
Text format (*.txt, *.csv)
IEEE-binary format (*.bin)
Section 7.3.2.5 applies to SimulationX result configurations.
In order to avoid new result windows to be created each time a result curve is
opened from the context menu of an element or connection, it is now possible to
add new result curves to a new page of an existing result.
There are two options to specify whether this action should be the default behavior
or whether it is restricted to only one open result window at a time. If there are
multiple result windows, the active one is used, i.e. the window which was opened
7-12 SimulationX 3
Result window
last or which is selected in the result window manager. This option is available
from the properties dialog of the result window manager.
7.3.2.7 COM Interface

Result windows can also be created via the COM interface. For this purpose, the
attribute ResultWindows is assigned to the classes Application and
Document.
The following code fragments demonstrate the use of these classes and methods
for script-driven creation of result windows.
ResultWindows.AddYt "model1.mass1.x"
ActiveDocument.ResultWindows.AddYt "mass1.x"
7.3.3 Structure of result windows

7.3.3.1 Definitions
Page Basic component of a result window. Includes panels.
Panel Used to represent result diagrams. Multiple instances can be
placed anywhere on a page.
Series
Transformation Subsequent modification of result curves
Line used for evaluation and assessment of result curves (e.g. mean
value)
7.3.3.2 Window layout

A result window consists of the following parts:
Menu bar (1)
Toolbar (2)
Panel for graphical output (3)
Page marker (tab) (4)
Property Bar (5)
Result Bar (6)
Crosshair (7)
Legend for steady-state simulation
SimulationX 3 7-13
1
2
3 5
6
4
Figure 7.9: Result window
To change the layout of the result window, go to View in the menu bar.
Individual components, e.g. Property Bar or Result Bar, can be undocked.
You can adjust the representation of the results under Options Presentation
For graphical output, the result window offers the following options:
Line graph
This is the default setting when you open a result window as shown in Figure 7.8
and can also be selected by clicking .
Bar chart
Figure 7.10: Result window with bar chart
7-14 SimulationX 3
Result window
Result variables can also be displayed as bar charts (see Figure 7.10). Click on
.
As a result of changing values for each bar during the simulation, you will see a
simple progress animation.
Polar coordinate system
Figure 7.11: Polar diagram
Certain result variables are more accessible through a polar diagram which can be
selected by clicking . X is shown on the angle and y on the radius.
Bar chart (vertical)
Figure 7.12: Bar chart with vertical alignment
SimulationX 3 7-15
Results are shown in vertical alignment illustrating the share of the total.
Pie chart
Figure 7.13: Pie chart
In certain cases it makes sense to choose a pie chart over other forms of
representation.
Sankey diagram
Figure 7.14: Sankey diagram
The Sankey diagram can help visualize flow quantities (e.g. energy balances).
Quantities are represented by arrows of proportional dimensions.
7-16 SimulationX 3
Result window
y(t)-chart
By clicking , results are shown along the time line.
Figure 7.15: Representation of two result variables
If in one window two or more result variables with different physical content or
different units are shown, a new y-axis is generated automatically for each result
variable. The same applies to the x-axis.
y(x)-chart
Figure 7.16: y(x)-chart
If there is an even number of result variables in one window, y(x) representation

is possible by clicking . Figure 7.16 shows Figure 7.15 as a y(x)-chart. To
swap axes, click .
SimulationX 3 7-17
Result curve displayed as a line

This is the default setting for result curves. It can be enabled or disabled with the
button . Use this function to temporarily hide the active curve in a result
window (e.g. if multiple result curves lie on top of each other).
Displaying computed points
Figure 7.17: Displaying computed points
Instead of a continuous line, computed points can be displayed by clicking (see

Figure 7.17). Display Line must be disabled.
7.3.4 Move and copy

7.3.4.1 Moving and copying results
Result variables support drag-and-drop. Simply hover with the mouse cursor over
the result variable identifier and left-click to grab it. Hold the mouse key and drag
the result across the screen to drop it in another or a new panel, for instance. When
you drop a curve or a panel outside of a result window, a new result window will
be created. In order to copy a curve, press the Ctrl-key and hold it before dropping
it (cursor shows a plus sign ). These functions are also available from the menu.
7.3.4.2 Moving and copying panels

Drag-and-drop offers three options for pasting result curves in an open result
window:
above the existing panel
in the existing panel
below the existing panel.
7-18 SimulationX 3
Result window
Pasting above of the existing panel
Figure 7.18: Drop zone marked by rectangle - top
Drag the result curve over the top area of the existing panel (Figure 7.18). A
rectangle marks the drop zone. The new curve will be placed above the existing
one as shown in Figure 7.28.
Pasting in the existing panel
Figure 7.19: Drop zone marked by rectangle - full
Drag the result curve over the center of the existing panel (Figure 7.19). A
rectangle marks the drop zone. The new curve will be displayed together with the
existing one in the very same diagram as shown in Figure 7.15.
SimulationX 3 7-19
Pasting below the existing panel
Figure 7.20: Drop zone marked by rectangle - bottom
Drag the result curve over the bottom area of the existing panel (Figure 7.20). A
rectangle marks the drop zone. The new curve will be placed below the existing
one.
In the same manner, you can also swap curves around within one window. The
same procedure can be used to arrange panels horizontally.
Please note that panels can only be re-arranged through the context menu or the
page properties (cf. 7.3.9.1) once two curves have been aligned via drag-and-drop.
Figure 7.21: Horizontal alignment via drag-and-drop
7-20 SimulationX 3
Result window
7.3.4.3 Moving and copying pages

Use drag-and-drop to move or copy pages within a result window or over to a
different one. Left-click and hold the page marker at the bottom of the window.
After half a second you can move the page around. If you drop it on a panel, a new
result window opens up.
In order to copy a page, press the Ctrl-key and hold it before dropping it.
7.3.5 Customizing view

7.3.5.1 Adjusting the axes
Using the middle mouse button:
Middle mouse button Press and hold the middle mouse button to move the
curve around.
before after
Ctrl+middle mouse Zooming along the axes (scale range)
button Position the cursor over either of the axes and press
Ctrl+middle mouse button. Moving the mouse along the
respective axis will then zoom in or out accordingly.
Shift+middle mouse Synchronizes the x-axes of all panels on the active page
button while moving (vertical alignment only).
Ctrl+Shift+middle Synchronizes the x-axes of all panels on the active page
mouse button while zooming along the axes (vertical alignment only).
SimulationX 3 7-21
Zoom
In addition to setting a range (min-max) for the shown segment through the
Property Bar, you can also use the magnifier function from the toolbar to
zoom in to a certain area. Simply mark the area you want to zoom into with a
rectangle as shown in Figure 7.22.
If you need to move the graph around, there is always the option to use the cursor
keys . Each curves view in one window can be customized
separately.
Ctrl Holding the Ctrl-key after selecting the magnifier keeps this
function enabled until released.
X-button Holding X after selecting the magnifier zooms only along
the x-axis.
Y-button Holding Y after selecting the magnifier zooms only along
the y-axis.
Figure 7.22: Zooming in using the magnifier function
7-22 SimulationX 3
Result window
For zooming with the mouse wheel in several panels there are following additional
options:
Ctrl+mouse Smooth zooming within a panel.
wheel
Ctrl+Shift+ Synchronizes the x-axes of all panels while zooming.

mouse wheel
If you want to reset the view after zooming, use the undo-function from the
toolbar. Please note that this will re-enable auto-scale for the axes.
Tip:
For the documentation of a segments exact values it is strongly recommended to
set a minimum-maximum range in the Property Bar.
7.3.5.2 Auxiliary lines

Evaluating results in relation to other values can be vital (e.g. minimum,
maximum, mean value etc.). In order to insert auxiliary lines for certain values, go
to Insert Horizontal Line or Vertical Line. SimulationX offers some
common presets, but you can also use User Defined values.
Custom auxiliary lines can now be moved interactively by drag and drop.
Color, style and width of auxiliary lines can be changed in the Property Bar on the
right-hand side.
In order to delete an auxiliary line, right-click on it in the Property Bar and then
click Delete.
SimulationX 3 7-23
Figure 7.23: Result window with mean value (auxiliary line)
7.3.5.3 Display of Orders at the Steady State Simulation

With the button the orders can be selected at the Steady State Simulation .
Figure 7.24: Display of orders at Steady State Simulation
7.3.5.4 Editing labels

SimulationX generates labels automatically. The legend entry (identifier )
of a curve is derived from the element and its result variable, but can be edited if
need be.
The attribute "Title Format" can be used to customize legend entries. Relabeling
an entry will not change the variables name, but is only intended for a more
accessible representation.
7-24 SimulationX 3
Result window
Macros, with respect to the respective axis

<identX> <identY> Complete identifier of the result variable
relative to the model
<nameX> <nameY> Name of the result variable
<commentX> <commentY> Comment on the result variable
<unitX> <unitY> Unit of measurement for the shown
variable
<quantityX> <quantityY> Physical quantity for the shown variable
<quantityXTitle> <quantityYTitle> Name of the physical quantity for the
shown variable
<nameEnvX> <nameEnvY> Name of the element containing the result
variable
<commentEnvX> <commentEnvY> Comment on the element containing the
result variable
<nameRootX> <nameRootY> Name of the corresponding model
<commentRootX> <commentRootY> Comment on the corresponding model
<numX> <numY> Index for multidimensional result

variables
Macros for the Steady State Simulation
<ssName> Type of spectrum or curve displayed
(amplitude, degree of uniformity etc.)
<ssOrdName> Type of order (sum, mean value or
order)
<ssOrdNum> Order identifier or empty character string
for sum or mean value
<ssMaxY> Maximum y value of a spectrum
<ssMaxX> X value corresponding with the
maximum y value of a spectrum
<ssRef> Character string showing value and unit
of the reference variable in the following
fashion:
(Ref=1000 rpm)
SimulationX 3 7-25
General Macros
<simRun> Name or number of the simulation curve.
If the name (value of the global string
variable nSim) is empty, the value of the
global integer variable iSim will be
displayed. This applies only to frozen
curves. Active results have an empty
character string.
<tab> Tabulator: enables individual tokens to be
grouped in columns within a legend
The parameter "Number Format" can be used to change the appearance of

numbers (e.g., axes labels, file output etc.).
The format string has the following syntax:
%[flags][width][.precision]ltype
Parameters in brackets are optional.
The parameters have the following meaning:
flag Meaning Default
- Align results to the left within the given Right alignment.
field width.
+ Always show numbers with algebraic sign. Sign only shown for
negative values.
Space Insert a space in front of positive numbers No space.
(ignored if + flag included).
0 Show leading zeros (within defined digit No leading zeros.
range)
# Always show decimal point for type=e, Decimal point only
type=E or type=f. shown when digits
following after the
decimal point.
# Always show trailing zeros for type=g or No trailing zeros.
type=G.
The width argument is a non-negative decimal integer defining the minimum

number of characters to be shown.
The dot separates the width parameter from the precision parameter. Precision is a
non-negative decimal integer.
7-26 SimulationX 3
Result window
Options Meaning of precision value Default

for type
f Precision defines the number of digits after the 6
decimal point. When the decimal point is shown,
there is always at least one digit preceding.
Numbers are rounded within the defined range of
digits.
e, E Precision defines the number of digits after the 6
decimal point. The last digit is rounded.
g, G Maximum number of significant digits to be 6
displayed.
The l-sign (prefix for type specifier) is required, as numbers used are of type
"double".
type Meaning Default
f float: floating decimal shown in the format [-
]mmm.ddd. While the number of digits in front of
the decimal point depends on the integer part of
the number, the number of digits after the decimal
point depends on the defined precision.
e, E float: floating decimal shown in the format [-
]m.ddddddexxx or
[-]m.ddddddExxx,
Precision specifies the number of digits.
g, G float: %e or %E is used only when the exponent is
smaller than -4 or greater than/equal to the
precision argument. Otherwise, %f is used.
Decimal point (if nothing else follows) and trailing
zeros are dropped.
The default setting for numbers is %6lg.
7.3.6 Post-processing
7.3.6.1 Transformations
A transformation is the subsequent modification of the computed results within the
result window, independent of the simulation process. To conduct a transformation
of the active curve within a results window, proceed as follows:
1. Select the corresponding curve from the legend, the combo box in the
toolbar or the Property Bar.
2. Go to Insert Transformation and select an operation.
SimulationX 3 7-27
3. If necessary, edit the parameters of the added transformation in the Property

Bar.
7.3.6.2 Operations (Links)

Operations are special transformations of a result curve linking its initial variable
to other variables. In order to link two curves to each other, proceed as follows:
1. Drag the curve you want to link up over the target panel.
2. Hold the mouse button while hovering over an operation icon and then drop
the curve. The added transformation refers to the existing curve shown in the
panel.
3. If necessary, edit the parameters of the transformation in the Property Bar.
The original curve will be removed upon completion of the transformation. To
prevent this, hold the Ctrl-key while dropping the curve.
The following operations are available (1-4) and can be extended (5):
1. Sum of two or more curves
2. Difference of two or more curves
3. Product of two or more curves
4. Mean value of two or more curves
5. Adding another argument to an existing operation
The type of operation as well as the arguments applied can still be edited through
the Property Bar later.
7.3.6.3 Data model and internal structure

Curves shown in result windows are based on values recorded during a simulation.
These values are copied as pairs of value (x; y) into the display buffer before being
sent to the graphical output. Managing the caching of these values is done by the
series objects storing both the references to the corresponding variables and the
representation properties.
Before being copied into the display buffer, data can be modified by one or more
transformations or can be linked to recorded values of other variables.
7-28 SimulationX 3
Result window
Additional references can be stored in the series object as potential arguments for
transformations and operations with other variables. If linked variables have a
common basis (e.g. simulation time t of the same model), only the Y-references to
the additional variables are stored making the computation process much simpler.
The difference of two variables, for instance, requires a subtraction of only the Y-
values of both pairs of values.
SimulationX 3 7-29
If the variables to be linked originate from different models or simulation runs (e.g.
by importing or freezing computation results), both the X- and the Y-references are
stored.
Before the actual transformation, pairs of values need to be adapted internally by

determining the function values for the added curve through linear interpolation of
the original curves x-coordinates. Hence, the number and location of sampling
points of the target function are always derived from the original curve.
As a series object is capable of managing several additional variable references, it

is mandatory to specify which argument variable to use with the selected operation.
The variable of the original curve is always set as the first operand.
7.3.6.4 Composition of Transformations and Operations

In order to execute a sequence of operations, arbitrary compositions of
transformations can be formed (see Figure 7.24).
7-30 SimulationX 3
Result window
When forming compositions of operations which have more than one argument it
has to be noted that only the first argument of an operation can be a result of a
preceding transformation or operation. The remaining arguments refer directly to
the respective variables.
Figure 7.25: A composition of transformations
7.3.6.5 Description of operations with Modelica expressions

Links can also be described with simple Modelica expressions for which basic
mathematical operators and functions are available. These expressions can be
edited directly in the property bar. For a more convenient approach, there is a
dedicated dialog which can be opened as follows:
1. Result window menu Insert/Transformation/Multiple Operation. This
shows all curves in the active panel as formal parameters of the link. This
list can be expanded or collapsed.
2. Double-click on a transformation symbol in the tree view of the property
bar. This shows the current settings of a link compared to the default values.
For the description, the variables to be linked are not directly referenced, but
through formal parameters. Result variables can be moved via drag and drop from
the tree view to the list of formal parameters. The formal parameters are named
automatically which depends on the chosen operation and the number of
parameters. The selected operation can be described for each point or for the entire
SimulationX 3 7-31
result curve as an array expression. The first case uses a scalar for the result
expression. The following result dimensions are permitted for the array
description:
Vector[n]: n number of x values
Array[2,m]: m random number of nodes
Array[m,2]: m random number of nodes
Example 1:
Five result curves are to be linked as follows:
= (1. [1]2 + 1. [2]2 + 1. [3]2 ) (1. 2. )
The link can be created as follows:

1. Open a result window for any of the relevant variables or add a new panel to
one of the existing windows.
2. Click on Insert/Transformation/Multiple Operation to open the relevant
dialog.
3. Add the missing variables to the list of the formal parameters from the result
tree via drag and drop (preferably in the order they occur in the formula).
4. Under Operation, choose the option Expression.
5. Enter under Expression the following string:
sqrt(y1^2+y2^2+y3^2)-(y3-y5)
Example 2:
Three result curves are to be added together and then multiplied by 1000.
The link can be created as follows:

1. Open a result window for any of the relevant variables or add a new panel to
one of the existing windows.
2. Click on Insert/Transformation/Multiple Operation to open the relevant
dialog.
3. Add the missing variables to the list of the formal parameters from the result
tree via drag and drop (preferably in the order they occur in the formula).
4. Under Operation, choose the option Expression(Vector).
5. Enter under Expression the following string:
(Y1+Y2+Y3)*1000
For vectorial descriptions of expressions, you can also use Modelica array
structures. This allows even for creation of curves that no longer have any
reference to the original data (e.g. ideal curve, slope line etc.).
Further examples for array expressions:
7-32 SimulationX 3
Result window
{{0.5, -1},{0.5,1}} vertical line
{{0,0.5},{1,0.5}} horizontal line
{{0,0.5},{1,1.25}} line
{{0,0.5},{1,1.25},{2,0.5}} polyline
{{0,0.5},{1,1.25},{2,0.5},{0,0.5}} triangle
{{i, sin(i/180*pi)} for i in 0:360 } sinus function
{if i==1 then j else sin(j/180*pi) for i in 1:2, j in 0:360 } sinus function
7.3.6.6 Measuring result curves

Displaying values
When showing results in the fashion of y(t) or y(x), function
values can be pinpointed anywhere along the active curve.
Figure 7.26: Result window with values displayed
How to:
1. Move the cursor over the coordinate system, press and hold the left mouse
button. The cursor turns into a crosshair at the current position of the curve.
A small status window shows the active curves values for x and y.
2. If you change the crosshairs position along the curve while holding the left
mouse button the values are updated accordingly. Please note that only
computed points can be displayed. If there is only a small amount of values,
SimulationX 3 7-33
the crosshair jumps from point to point. When the mouse button is released,
the crosshair disappears.
When you open the Measure Bar by clicking , you get additional options
while the crosshair remains visible after releasing the mouse button. You can
grab and move the crosshair again to get other values. The values shown in the
small status window are also displayed in the Measure Bar on the right-hand
side..
Figure 7.27: Result curve with Measure Bar
If you click on the curve again, a second crosshair will appear.
Figure 7.28: Result curve with two measured values
7-34 SimulationX 3
Result window
Beside the values of the measured points (X1, X2, Y1, Y2), data about the path
difference (X, Y) and the slope (X/Y) between the two points are provided in
the same window.
Measuring multiple result curves
Figure 7.29: Measuring two result curves
In result windows with multiple panels, movement of the active crosshairs in each
is synchronized along the x-axis while the small status window is only available for
the selected curve. Values for the other graph(s) are accessible through the
Measure Bar (see Figure 7.30).
Figure 7.30: Two result diagrams with Measure Bar
SimulationX 3 7-35
7.3.7 Freezing and importing result curves

Freeze Use this function to save the selected curve for comparison with
following simulations. SimulationX generates a copy of the current result
curve (light colored curve) which remains visible after resetting the
corresponding simulation. Frozen result curves are saved together with the
model.
Figure 7.31: Result window with frozen curve Mass1.v (History)
Load Open a saved curve in the current result window.

Save - Save all curves displayed in a result window in one of following file
formats (cf. section 9.1):
Text (*.txt)
IEEE binary (*.bin)
ITI SimulationX (*.rfs)
CSV (comma separated) (*.csv)
DIAdem-Header (*.dat)
XML (*.xml)
Image (*.bmp, *.jpeg, *.gif, *.tiff, *.png, *.emf)
Import of result curves from external files:

During the drag and drop operation for the import of result curves from external
files through the result bar of the result window, it is possible to specify whether
the data should be copied to the target model or only referenced through a link to
the external data.
7-36 SimulationX 3
Result window
Simple drag operations for a variable from the result bar into the
result area of a result window create a shortcut.
Dragging a variable from the result bar into the result area while
holding the Shift key copies the data to the target model.
7.3.8 Exporting and Printing

If you want to export the computation results, select Export from the menu. All
results of the current model are stored in the following formats:
Text (*.txt)
CSV(separators separated) (*.csv)
XML (*.xml)
Figure 7.32: Printout of a result curve
It is also possible to print out the selected page with all curves displayed.
7.3.9 Settings
7.3.9.1 Property Bar
Via the menu View Property Bar you get access to the properties of the
result window.
This window provides access to all result attributes you may want to edit. Click on
a category to see its available settings in the lower section of the Property Bar. You
can find the most common settings explained below.
Menu bar, toolbars and status bar can be turned on or off under the menu View.
These options may come in handy to save space when having multiple result
windows open at a time.
SimulationX 3 7-37
Figure 7.33: Property Bar Selection of categories
Window properties
In the properties dialogue you can adjust the settings of the window and the
representation of the curves.
Window
Name/Explanation Value
Keep axis settings when frozen True/False
Current settings for minimum and maximum are preserved.
Auto-scale is disabled.
Independent curves for frozen results True/False
When freezing results, an independent curve is created which
can be moved to a different panel, page or window and, hence,
is available for transformations. If this option is deactivated,
frozen results are tied to the original curve.
High rendering quality True/False
Improves image quality for output on a screen at the cost of
rendering performance. For export, high quality settings are
applied by default.
Keep cached values when unselected True/False
With this setting you can increase the rendering speed when
switching between pages of a result window at the expense of
available memory.
7-38 SimulationX 3
Result window
Show info tips True/False

Activate this setting to have SimulationX show you additional
information about available options during certain actions (e.g.
zoom).
Remove invalid curves True/False
Disable this setting to prevent automatic deletion of curves
whose corresponding variables were removed from the model.
Those residue curves remain in the result window and are
marked accordingly in the legend. Once a variable with the
same identifier reoccurs, the relevant curve will be restored.
Show with model True/False
Turn this setting on to have the result window pop up
automatically whenever you select a model.
Font
Name Value
Name Font selection
Font size Numerical value (integer)
Text color Color selection
Position
X X
Y Y
Size
Width Numerical value (integer)
Height Numerical value (integer)
The selected font applies to all labels in the result window.
Page properties
Page
Name String
Shows the current page title. Editing the page title disables
automatic labeling.
Automatic labeling True/False
Turns on/off automatic labeling for pages. When enabled,
labels are derived from the first result variable on a page.
SimulationX 3 7-39
Back color Color selection

Sets the background color for the page.
Rows Numerical value
Shows/sets the number of panels aligned horizontally.
Columns Numerical value
Shows/sets the number of panels aligned vertically.
Automatic resizing True/False
Enables automatic resizing to fit existing panels to the
result window.
For printing or image export, you may want to disable this
option to be able to define a fixed size.
Frame Size Numerical value
This attribute determines the spacing between the panels
and also between panels and page borders.
Individual Panel Layout True/False
Customized panel layouts (cf. Figure 7.35).
Page format ISO/DIN A4
Defines the page size (only available when automatic ISO/DIN B4
resizing is turned off). ISO/DIN C4
ISO/DIN D4
Legal
Letter
User
Orientation Landscape
Defines the page orientation (only available when Portrait
automatic resizing is turned off).
User-defined width Numerical value
User-defined page width in millimeters (only available (real)
when automatic resizing is turned on, and page format is
set to User).
User-defined height Numerical value
User-defined height in millimeters (only available for (real)
automatic resizing and the page format set to User).
7-40 SimulationX 3
Result window
Page borders in millimeters

Left Numerical value
Left margin in millimeters (only available when automatic (real)
resizing is turned on).
Right Numerical value
Right margin in millimeters (only available when (real)
automatic resizing is turned on).
Top Numerical value
Top margin in millimeters (only available when automatic (real)
resizing is turned on).
Bottom Numerical value
Bottom margin in millimeters (only available when (real)
automatic resizing is turned on).
You can define the number and position of panels on one page through the page
properties as illustrated in the example below (two panels in one row).
See the effect of these setting in Figure 7.34.
SimulationX 3 7-41
Figure 7.34: Result window with one page and two panels horizontally aligned
Figure 7.35: Ergebnisfenster ohne (links) und mit (rechts) individuellem Seitenlayout
Panel properties
Panel
Name String
Enter an optional title for the panel.
Visible True/False
Select this option to display the name of the panel in
the top left corner above the coordinate system.
Chart style Cartesian coordinate
Common settings for characteristics are the Cartesian system
coordinate system and the polar coordinate system. Polar coordinate system
Further options are intended for instantaneous values. Bars
For more information, please refer to the following
pages.
7-42 SimulationX 3
Result window
Back color Color selection

Sets the background color of the coordinate system.
Axes color Color selection
Sets the axes color.
Legend No legend
Defines the position of the legend. Top
Right
Grid
Line color Color selection
Sets the grid color.
Line width Numerical value (integer)
Sets the line width of the grid.
Line style solid
Defines the line style of the grid. dash
dot
dash dot
dash dot dot
x-axis/y-axis
Grid True/False
Sets the visibility of the grid.
Show axes True/False
Sets the visibility of the axes labels.
Common axis True/False
Determines whether to use a common axis for multiple
curves in a panel.
Auto-scale True/False
Switches automatic zoom along the axes on/off.
SimulationX 3 7-43
Additional marks True/False

Provides a finer scale on the main axis.
False True
Integer marks True/False

Provides integer scales on the axes. Minimum and
maximum coincide with the main axis interval
boundaries.
False True
Unit labels in accordance with DIN 416 True/False

Places the unit in the middle of the main axis last
interval.
False True
7-44 SimulationX 3
Result window
Show numbers True/False

Shows numerical values of the main interval boundaries.
Axes properties
For individual changes, select the panel you want to customize.
X- and y-axes have the same properties. Properties can be set for each axis
separately.
If the result window holds multiple curves, a common axis (true) can be shown for
each coordinate (x; y).
If auto-scale is enabled (true/false), minimum and maximum are derived from all
curves (common axis) or the selected curve while the axes are optimized to fit the
window showing all visible values. Minimum, maximum and marks, however,
cannot be selected anymore.
"Show axes" (labels) can be enabled and disabled (true/false) referring to marks
and units.
The parameter "additional marks" permits finer scales on the axes (grid). The grid
can be enabled or disabled.
The axes can also be displayed with a logarithmic division.
Depending on the general properties, the parameters "Minimum", "Maximum" (to
generate a section, for example), "Unit" (of measure) and "Marks" can be set under
Options.
The orientation for the x-axis can be set through "Negative orientation
(true/false).
Curve properties
Each curves properties can be customized individually, such as color, line style,
line width and markers.
These settings can be changed by selecting a result variable in the Property Bar
(see Figure 7.33) as outlined below:
1. Select the curve to be customized in the Property Bar.
2. Make changes as desired for the properties below.
SimulationX 3 7-45
Series
Label String
Sets the result curve label. You can use different macros for
automatically generated names (see 7.3.5.4).
Visible True/False
Use this option to hide a curve (temporarily).
Auto freeze True/False
If this option is turned on, the selected curve will be frozen
automatically when resetting the model.
Show transformation in title True/False
Includes the transformation in the title. For example, an FFT
of the result mass1.om is displayed as FFT (mass1.om).
Representation
Color Color selection
Sets the line color of a curve.
Line width Numerical value (integer)
Sets the line width of a curve. For fast
rendering, chose 1. For printing or exporting,
broader lines may improve readability.
Line style solid
Sets the line style of a curve. For fast rendering, dash
chose a solid line. dot
dash dot
dash dot dot
Marker No marker
Use markers to improve differentiation of Rectangle
multiple curves. Filled rectangle
Ellipse
Filled ellipse
Triangle
Filled triangle
Alternative triangle
Alternative filled Triangle
Cross
Alternative cross
7-46 SimulationX 3
Result window
Show line True/False

Shows results as a line. Sampling points are connected
through linear interpolation.
Show points True/False
Shows each computed sampling point as an x.
Show upper envelope True/False
Shows the upper envelope as combined local maxima.
Show lower envelope True/False
Shows the lower envelope as combined local minima.
x-axis/y-axis
Unit Selection box
Option to change the curves unit displayed. This
setting has no effect on the corresponding model.
Position
Defines the position of the x axis in the diagram. Top/Bottom
Defines the position of the y axis in the diagram. Left/Right
Minimum Numerical value (real)
Sets the minimum for each axis.
Maximum Numerical value (real)
Sets the maximum for each axis.
Scale origin Numerical value (real)
Sets the starting point of the scale.
Scale interval Numerical value (real)
Sets the size of intervals.
Negative orientation True/False
When activated, the direction of the axis is reversed.
Log10 True/False
Switches the logarithmic scale on/off.
Origin Numerical value (real)
(in degrees)
Title String
Sets the optional axes label. As for curve labels,
macros can be used (see 7.3.5.3).
Show label True/False
Show optional axes labels.
SimulationX 3 7-47
Number format see 7.3.5.4

Defines the number format for labeling axis
intervals.
Variable
Ident String
Refers to the x-variable or y-variable of the
corresponding curve. Usually, the ID is
specified relative to the model (see model
properties).
Index Numerical value
Refers to the corresponding component of a (integer)
multidimensional variable. The entry can only
be edited if it is not a scalar variable.
Argument(s)
Number
Shows the number of additional arguments for
links and other operations.
Variable
Ident String
Refers to a variable. Usually, the ID is
specified relative to the model (see model
properties).
Index Numerical value
Refers to the corresponding component of (integer)
a multidimensional variable. The entry
can only be edited if it is not a scalar
variable.
Zoom factor for the shown range in percent Numerical value
Defines the percentage of magnification for the (integer)
range to be shown with respect to the difference
between maximum and minimum.
Model String
Shows the name of the corresponding model.
Number of pairs of values Numerical value
Shows the number of pairs of values of a curve. This is (integer)
for information purposes only and cannot be changed.
7-48 SimulationX 3
Result window
Precision Single or double

Specifies which floating point format is used to store
values for representation. Simulation results are always
recorded with double precision regardless of the above
setting.
Line
Line style Minimum
Shows the line type, but cannot be changed. To change Maximum
the line type, delete the line and replace it with the Mean value
desired type.
RMS value
User defined,
horizontal or vertical
Name String
Shows/Sets the name of a line.
Visible True/False
Determines whether a line should be displayed.
Show name True/False
Determines whether to show the name in the line label.
Show value True/False
Determines whether to include the value in the line
label.
Current value Numerical value (real)
Shows the lines value at the current position within the
coordinate system. The value can only be changed for
user defined lines.
Display
Same color as result curve True/False
Sets the same color for line and active result curve.
Line color Color selection
Line width Numerical value
(integer)
Line style solid
dash
dot
dash dot
dash dot dot
SimulationX 3 7-49
Transformation
Type String
Specifies the type of a transformation.
Parameter 1
Further parameters depend on the selected
transformation.
7.3.9.2 Loading and saving settings

Layout settings for result windows can be saved in the menu (Options Save
Settings). These settings can be restored through Options => Load Settings
and are applied to the active window immediately.
Switching between different layouts can be useful for printing (colored or

monochrome), for example. To create a template, follow the below instructions:
1. Create a new simulation model.
2. Place a function block f(x) in the Structure View and enter the following
values for x:
time*{1, 2, 3, 4, 5, 6, 7, 8, 9}
The number of vector components should equal the maximum number of
curves required within a panel.
3. Simulate the model with the default settings.
4. Open a result window for the result variable y.
5. Define all properties of the result window as needed,(line color, line width,
line style etc.).
6. Save the template under a descriptive name (e.g. template printing B/W).
7-50 SimulationX 3
Result window
7.3.9.3 Setting default settings

In the menu under Options Save as Default Settings you can save the
current settings as default for new result windows.
The default settings are stored as a default.rsx file in the directory specified in
the program settings. If you want to apply the default settings to an open window,
go to Options Load Settings in order to load the template from file.
7.3.10 Managing result windows

7.3.10.1 Merging result windows
Combine all open result windows of one model into a single
window by clicking Window Collect. Previous
windows will be shown as pages in the combined view.
7.3.10.2 Result window manager

The Result Window Manager provides easy
access to all open result windows.
Tick a checkbox to show a particular
window. Please note that checkboxes for
models have different functions from those
for results.
Checking the checkbox of a result window

The result window will be visible.
Unchecking the checkbox of a result window

The result window is minimized and - depending on the settings - shown as an icon
in the taskbar. The unchecked result window is disabled and will not be shown
when activating a model (indicated by a gray icon).
Checking the checkbox of a model

All active result windows of the corresponding model will be displayed.
Deactivated result windows are not included. To display all result windows of one
model, use the context menu on this model in the result window manager.
Unchecking the checkbox of a model

All result windows of the corresponding model are minimized. The activation
status of the result windows will not change.
Opens an empty result window (only when the model level is active)
Opens a result window from file (only when model level is active)
SimulationX 3 7-51
Displays all result windows regardless of their activation status or their

parent model.
Disables and hides all result windows.
Closes all result windows.
Opens the Properties window of the Result Window Manager.
The following settings can be selected:
Show minimized result windows in windows taskbar
This function makes use of the preview function in Windows 7. It is
recommended to disable this function for Windows Vista and XP in
absence of the preview function in those OSs.
Show result windows at model activation
When activating a model, all active result windows of this model are
displayed while all non-related result windows are minimized.
Merge result windows from models created with SimulationX 3.4
or earlier
If enabled, this function combines all result windows into one window
when loading a model that was created with a previous version (3.4 or
earlier).
Show preview image
Move the mouse over an entry in the result window manager to get a
preview of the result curve..
7.3.10.3 Fast Fourier Transformation (FFT)

The Fast Fourier Transformation provides a way to determine an amplitude
response over the frequency for a given time signal (y(t)-chart assumed).
Figure 7.36: Fast Fourier Transformation of a simple oscillation
7-52 SimulationX 3
Result window
Click the button or select Options Fast Fourier Transformations

(FFT) from the menu to show the computed amplitude spectrum for all result
curves of one result window in a new window.
All result windows with Fast Fourier Transformation are closed when the model is
reset.
7.3.10.4 Complex frequency response function

The calculation of the complex frequency response function (FRF) is often the
basis for the evaluation of a structure and its dynamic behavior within a defined
frequency range. For signal analysis, frequency response functions can be helpful
when comparing calculated and measured results. The complex frequency response
function of a system represents the complex relation between two signals (result
curves from a time range).
It is defined as the Fourier transform of one signal divided by the Fourier transform
of the other signal:
Y(j )
H ( j ) =
X(j )
X ... signal2 (input) (7.1)
Y ... signal1 (output)
H ... response function
If the complex frequency response function is described by an output signal

(response) and an input signal (excitation), it means in terms of Physics that an
input signal with the frequency f causes an output motion with the same frequency.
The output amplitude is the input amplitude multiplied by H ( f ) , and the output
phase is displaced by ( f ) relative to the input.
Figure 7.37: Complex frequency response function
SimulationX 3 7-53
Complex frequency response functions can be derived from the ratio of various
output and input signals. Here are some examples:
dynamic flexibility (displacement to force),
mobility (velocity to force),
accelerability (acceleration to force)
dynamic stiffness (force to displacement)
impedance (force to velocity)
resonant mass (force to acceleration).
7.4 Printing (PrintEngine)
This chapter explains how models and results are documented. Any Windows
printing operations are assumed to be known. By the menu File Print
Preview you get to the printing preview.
7.4.1 Print Preview

The adjustment for the printout is also available in the menu File Print
Preview (see Figure 7.38). All inputs and results are prepared for printing. The
print layout (always visible in the print preview) can be adapted to the individually
layout requirements.
All printable parts of the actually model are listed in a hierarchical tree view, such
as
Diagram view
Global Parameters and results
Components and
Result charts.
Toolbar
Selection bar Print preview
Page preview
Figure 7.38: SimulationX print preview
7-54 SimulationX 3
Printing (PrintEngine)
7.4.1.1 Selection bar

Via View or Document structure you can select those elements to be printed.
By ticking the respective boxes, the elements are either shown or hidden in the
print preview.
Each change is indicated immediately in the print view.
In the Document structure the printable components are sorted out according to
structural criteria. Each selection refers to the selected components and the
underlying components.
In the View the printable components are sorted out according to textual criteria.
7.4.1.2 Toolbar
The existing toolbar permits further settings for the document and various output
options.
Initializes the printing process
Setting up the printer
Setting up the page layout (s. a. paper size, source and
direction, border)
Exporting the document in 3 formats
PDF-File (*.pdf)
Rich Text Format (*.rtf)
HTML-page
Sending the document as an email
Bar for navigation in the document
Displaying/hiding edge marks
Adjusting font size (5 sizes).
Selection of print view layout
Closing the print preview
7.4.1.3 Page Settings

By the corresponding button you get to the dialog of the page settings.
The following properties of the page layout are adjustable (see Figure 7.39):
Page format (paper size, paper direction, border)
Header (label and font size)
SimulationX 3 7-55
Footer (label and font size)

Design (classic, modern, simple, color).
Figure 7.39: Dialog Page Settings
Figure 7.40 shows a generated document.
Figure 7.40: Documentation of a model
7-56 SimulationX 3
For labeling of header and footer a selection of predefined field types are available.
The following fields can be inserted:

Field name Comment
Page Number number of current page
Odd Page Number number of current odd page
Even Page Number number of current even page
Number of Pages number of total pages
File Name file name of the model
Author author of the model
Current Date current date
Current Time as before however with indication of the current
time
Company
Copyright
Program Version SimulationX version number
Release Number SimulationX Release Number
Release Number with Date as before however with date
Image File opens a dialog for the selection of an image
7.4.2 User defined Print

The available PrintEngine controlled via the COM-interface can be utilized for
user defined print outputs. By using of scripts you can generate user defined print
forms. The structuring of the documents can be done by frame sets and diagrams.
Tables can also be included. The following script generates a model and a
multipage document, which are represented in the print preview. You can find this
example in the directory
\ITI SimulationX 3.8\Samples\Scripting\Print_simple_model.vbs.

' constants
simStopped = 16
filepath= "C:\Programme\ITI-Software\ITI SimulationX
3.8\Samples\Scripting\"
' Start of ITI-SimulationX with a new document
Set sim = CreateObject("iti.simx38")

Set doc = sim.Documents.Add()
sim.visible=true
SimulationX 3 7-57
' Creation of a simple model
Set simobj=doc.SimObjects.Add
("Mechanics.Translation.Mass", "Mass1", 90, 90)
Set simobj2=doc.SimObjects.Add
("Mechanics.Translation.Spring", "Spring1", 180, 90)
Set simobj3=doc.SimObjects.Add
("Mechanics.Translation.Damper", "Damper1", 180, 150)
doc.Connections.Add "Mass1.ctr2", "Spring1.ctr1",
"Connection1"
doc.Connections("Connection1").AddLine "Damper1.ctr1", 145,
105
' Parameterization
doc.SimObjects("Mass1").Parameters("m").Value = 0.5
doc.SimObjects("Spring1").Parameters("k").Value = 1000
doc.Connections("Connection1").Parameters("x0").Value =
0.01
doc.Connections("Connection1").Results("x").Protocol = true
doc.Connections("Connection1").Results("v").Protocol = true
' Open a result window
Set wnd = sim.ResultWindows.Add("Connection1.x")
wnd.SetMinMax 0.0, 1.0, -0.01, +0.01
' Computation (damping b = 2)
doc.Parameters("Damper1.b").Value = 2
doc.Reset
doc.Start
While (doc.SolutionState <> simStopped)

wscript.Sleep(100)
Wend
' Print of the model
Set pe = doc.PrintEngine
If pe Is Nothing Then
MsgBox "Error getting printengine"
Else
' Arrangement of printing objects

pe.Objects.AddSimObject simobj
pe.Objects.AddSimObject simobj2
pe.Objects.AddSimobject simobj3
pe.Objects.AddModelView
7-58 SimulationX 3
'Generating a second page

set p=pe.Pages.Add
' Insertion of picture blocks
set imgblock=p.Objects.AddBlock
("ImageBlock","Parameters of mass1")
imgblock.LoadImage filepath & "pic1.gif"
' imgblock.PrintName=false
set imgblock1=p.Objects.AddBlock
("Imageblock",Chr(13) & "Paramter of Spring1")
imgblock1.LoadImage filepath & "pic2.gif"
set imgblock2=p.Objects.AddBlock
("Imageblock",chr(13) & "Parameter of Damper1")
imgblock2.LoadImage filepath & "pic3.gif"
' Insertion of a result window
p.Objects.AddResultWindow wnd
' Open printing preview
pe.PrintPreview
End If
Figure 7.41 shows the result of the script controlled print. The inserted pictures on
page 3 are made via a capture program. The structure of the page corresponds to
the sequence of the notation in the script.
Figure 7.41: User defined print layout
SimulationX 3 7-59
Parameters can be imported and results output via the existing COM interface (see
Chapter 9). This is helpful for the automation of simulation runs.
7.5 TVA Report Generator
The TVA Report Generator generates analysis reports as DOCX files, i.e.
Microsoft Word. These reports are based on model parameters and computation
results from SimulationX models. These SimulationX models are 1D mechanical
powertrain structures including inertia and spring-damper elements as well as
engine and machine elements.
In contrast to the print module of SimulationX, the TVA Report Generator is

intended for classification societies to create reports of torsional vibration analyses
(TVA) of marine powertrains with standardized formatting.
Figure 7.42: GUI of the TVA Report Generator
The report can contain the following components:

Diagram views of the complete model structure and the sub-model structure of
engine elements
Table of system parameters including the parameter values of rotational
inertias, stiffness, damping, and transmission ratios
Table of engine data
Two tables for the analysis of natural vibration modes:
Mapping the kinetic energy distribution and the deviation to the
corresponding inertia elements for each frequency
7-60 SimulationX 3
TVA Report Generator
Mapping the potential energy distribution to the corresponding stiffness

elements for each frequency
Table of resonance speeds and angle sums, which are excited by the engine;
listed for each frequency and all orders
Result plots taken from the result windows in SimulationX
The generated report can be extended by the user, i.e. in Microsoft Word, with
application specific descriptions, annotations and further formatting options.
The data is transferred between the TVA Report Generator and SimulationX via
the COM interface. In order to utilize the TVA Report Generator, the following
requirement must be met:
SimulationX 3.7 with a valid license must be installed to use this tool
7.5.1 General Procedure

Connecting the TVA Report Generator with SimulationX
upon loading SimulationX, the TVA Report Generator is connected
automatically. Otherwise, the TVA Report Generator initiates the start of
SimulationX and connects with it.
Loading data from an active model

The TVA Report Generator reads data from the model that is currently active in
SimulationX. If the active model was changed, data can be reloaded by clicking
on the button in the group Settings.
Elements
A list shows the components generated for the report. It is possible to unselect
report components that are not required.
Templates
Word Document:
Specify the directory of your DOCX template file (file extension *.docx).
Configuration file:
Specify the directory of your configuration file. This file must be an ASCII
text file with file extension *.ini (DefaultSetting.ini). For more information
about this configuration file, see chapter Configuration File below.
Settings
Project, Customer, ProjectNo, Mode:
Enter the name of your project and your customer as well as your project
number and your simulation or analysis mode. This information will be
printed on the cover and shown in the header of each page of the report or at
SimulationX 3 7-61
any place in your DOCX template, where corresponding placeholders exist

(see section DOCX Template below).
Min. Frequency and Max. Frequency:
Use these parameters for specifying the range of natural frequencies, to be
included in the report. The minimum frequency defines the lower limit and
the maximum frequency the upper limit.
Max. Order:
This parameter defines the maximum excitation order in the table of engine
excited resonance speeds.
The button reloads data from the active SimulationX model. The
TVA Report Generator the refreshes all elements of the report.
Note: All selected file paths and customized settings will be saved, when the
program is closed. So they are available for the next session of the TVA Report
Generator.
Report Generation
If this option is selected, the TVA Report Generator
opens the file in your default DOCX application upon the report generation.
By clicking this button, the TVA Report Generator creates the

DOCX-file that contains the report. Before the report is generated, you need
to specify the storage location of the DOCX-file.
DOCX Template
The TVA Report Generator comes with a default template with an ITI-specific
layout (Template.docx). This file is Users\PUBLIC\Documents\SimulationX
3.7\TVA Report Generator.
To create your own template, it is recommended to copy the ITI template.

Customize this template according to your needs.
Note:
Within this template, there are several strings: #CUSTOMER#,
#PROJECT_NAME#, #PROJECT_NO#, #MODE#.
These strings are fixed placeholders which are filled by the TVA Report
Generator:
#CUSTOMER# customer or client
#PROJECT_NAME# project name
#PROJECT_NO# project number
#MODE# analysis or simulation mode
7-62 SimulationX 3
TVA Report Generator
7.5.2 Configuration File

The TVA Report Generator comes with a default configuration file Default.ini.
This file defines how element parameters are mapped to report parameters. This is
an ASCII text file, Users\PUBLIC\Documents\SimulationX 3.7\TVA Report
Generator.
If you want to modify this configuration file, it is recommended to copy the ITI
template. The file can be opened in any text editor.
The file contains several groups of model types which are to be included by the
TVA Report Generator and hold required parameters.
Following groups are available: [Inertias], [Stiffness], [Damping],

[AbsoluteDamping], [SpeedRatio], [LEngine], [VEngine], [EngineCylinder].
Note:
Do not change these group headers. Only change the list under the header if
required.
The groups contain lists of model type idents, as you can see them in the
library bar of SimulationX. At the end of each ident, there is the name of the
corresponding parameter which holds an inertia or stiffness value, for
instance.
Example 1: Mechanics.Rotation.Inertia.J
The TVA Report Generator searches the simulation model for elements of
type Mechanics.Rotation.Inertia. For each element of this type,
the TVA Report Generator reads the value of the parameter J. According to
the Default.ini file, J is an inertia parameter (-> group [Inertias]) and thus
the value is written to the table of the system parameters in column Inertia.
In the case of engine models, the model type ident is followed by a list of
parameters in brackets. The engine elements in a simulation model hold more
than one parameter for the report. Thus this list assigns model parameters to
report parameters.
Example 2: TVA.Engines.LEngines.L4 (NoCyl=NoCyl:4,
CylBore=bore, Stroke=stroke, NoStrokes=kindCyl,
RecMass=mOsc, RodRatio=ratio)
The TVA Report Generator searches the simulation model for elements of
type TVA.Engines.LEngines.L4. If one is found, the TVA Report
Generator reads the value of the parameter bore, for instance. According to
the Default.ini file, bore is assigned to the report parameter CylBore and
thus the TVA Report Generator understands the value as cylinder bore
parameter and writes it to the engine data table.
SimulationX 3 7-63
7.5.3 Computation Basics

7.5.3.1 Natural Frequencies, Mode Shapes and Energy Distribution
For information about the computation of natural frequencies and corresponding
mode shapes (deviation of inertia elements) as well as corresponding energy
distributions (potential energy of stiffness elements, kinetic energy of inertia
elements), please refer to the SimulationX User Manual.
Furthermore, the table containing the potential energy distribution lists the
normalized relative angle (~ deformation; Rel. Angle -> , ) and the normalized
maximum torque (Torque -> , ) for each frequency and each stiffness element.
These values are also (internal) results of the SimulationX Natural Frequencies
and Mode Shapes analysis.
The mode shape of a natural frequency provides the deformation of each
stiffness element i. The TVA Report Generator selects the maximum value
and normalizes each deformation to this maximum value:

, =
max

Using the normalized deformation , and stiffness of each stiffness

element i, the corresponding normalized maximum torque , can be
computed as follows:
, = ,
7.5.3.2 Engine-excited Resonance Speeds

The table Engine excited Resonance Speeds lists the resonance speeds (OMRES ->
) and the corresponding angle sum (SUM -> ) for each frequency f [Hz]
and for each order O. They are calculated with the following equations:
Engine excited resonance speeds in [rpm] (revolutions per minute):
= 60

in [rpm];
with O = {0.5 ; 1 ; 1.5; ; Omax} and Omax, which is the setup parameter
Max. Order (see above in section 7.5.1)
The vector sum angle is computed based on the complex firing angles
and complex eigenmodes of each cylinder c for each order O:
o Complex firing angles for each cylinder c using the given firing
angle of the cylinder c:
7-64 SimulationX 3
General Settings
( ) = cos( )
( ) = sin( )
o SimulationX provides magnitude RN,c and phase , for each
eigenmode Nc for each cylinder c:
( ) = , cos,
( ) = , sin,
o Summation of the complex firing angles and the complex
eigenmodes for each cylinder c:
, = ( ) ( )
, = ( ) ( )
o Summation of the real and imaginary parts:
= ,

= ,

Vector sum for each excitation order:
= 2 + 2
7.6 General Settings
Further settings for SimulationX can be made with the

menu Extras Options. During the installation of
SimulationX they are set to default values but they can be
changed at any time.
7.6.1 General
If you want to make during the simulation, a visualization of Visualizers, Modelica
graphic primitives or state charts, the control Enable Diagram View Animation
during Simulation must be set in the register General. This can increase the
computation time.
SimulationX 3 7-65
The option Synchronize Animation during the Simulation ensures that a

specified framerate is maintained. For fast computing models, this is helpful as
otherwise the animation is not visible.
You can choose a default action to be performed every time SimulationX is started:
Create New Model
Open Recently Used Model
No Model at Startup
Figure 7.43: General Settings.
In the section Warnings and Errors, you can specify how SimulationX should
deal with warnings and errors. Pre-defined checks can be changed to customized
analyses.
Figure 7.44: Settings for displaying warnings and errors
7-66 SimulationX 3
General Settings
7.6.2 Directories
With the menu Extras Options Directories you can change the paths which
were generated by SimulationX during installation (see Figure 7.43).
Figure 7.45: Directory settings
You can use this buttons for

add a new directory entry
delete a selected entry
move entries and
import of External Types (possibility of the import of libraries,
which were provided with an earlier version of SimulationX and
stored under External Types)
7.6.3 Libraries
The section Libraries gives an overview of all available model libraries. You can
specify which libraries are loaded when SimulationX is started and whether
excluded libraries should be loaded automatically when a model requires them.
The table shows the version and directory as well as the current status of the
libraries (Load at start, existing license, currently loaded). An overview of all
shown states is available by clicking on the Legend button.
By excluding individual libraries from being loaded when SimulationX is started,

storage space is saved and the program starts up faster. When you open a model
with a missing reference at a later point, the corresponding library is loaded
automatically provided that the related file and a valid license exist.
For external libraries, this requires the option Load external libraries
automatically to be enabled. If only certain packages are to be included, disable
the option Load external libraries completely. This may need more time to
compute for missing references if within the affected model functions or constants
SimulationX 3 7-67
from other packages are used in equations or algorithms. These references are
currently not supported when libraries are loaded automatically.
Figure 7.46: Selection of libraries
7.6.4 Storing
So far, all data, which was recorded during a simulation run, has been stored in
memory.
This data can optionally be stored in the file system too. Current hard disk
technology and intelligent buffering permit almost equivalent access performance
compared to storage in memory. The option can be turned on and off via the menu
Extras Options Storing.
You can also select the standard file format for storing (*.ism or *.isx).
When the option 'Store Modelica Conform' is selected, models are stored as *. mo
files without results and without inclusion of the SimulationX calculation
environment.
Storing calculated models with results may occasionally lead to large files on the
hard disk. This can be avoided selecting the option Store without Results by
default'.
7-68 SimulationX 3
General Settings
Figure 7.47: Setting of protocol storing location
The AutoRecover allows protecting your work against power failures or other
unwanted program terminations. If the feature is activated, temporary copies of
modified models are stored in the specified regular intervals of 5 min (default
setting) or longer.
With the AutoRecover feature turned on, on the next SimulationX launch after an
abnormal termination the models affected are displayed in a recovery dialog. From
there they can be restored and saved (cf. Figure 7.46).
Figure 7.48: Dialog for Recovery of Files
The information in the files reflects the state at the last auto-save.
AutoRecover does not replace the manual saving or backing up of your files!
SimulationX 3 7-69
If when using SVN the storage of backup copies of modified types is not desirable,
the creation of backup files can be deactivated by the option "Store backup for
models and types".
7.6.5 Modelica
Figure 7.49: Modelica Settings in this Register the appearance of the text editor is
specified.
7.6.6 Editor
Figure 7.50: Settings of the Text Editor
Also a special text editor (e.g. Notepad++) for working on the text view can be
adjusted by setting a file path.
7-70 SimulationX 3
General Settings
7.6.7 General Settings 3D View
Figure 7.1: Settings for the 3D view
Preferred driver:
Here the preferred 3D driver can be selected. The default setting 'Auto'
should only be changed when problems occur with the 3D graphics. ->
Changes are only applied when a new 3 D view is opened.
Camera controls:
Specifies the mouse button controlling the camera.
Allow animation during the simulation:
Disables the refresh rate of the 3D view during a simulation in order to
reduce computation time.
Copy to clipboard:
Resolution: Virtual resolution of the created image. The value 96
corresponds with the original size of the 3D view on the screen.
White background
If enabled, settings for the 3D views background are ignored showing a
white background instead.
7.6.8 Fluids
Figure 7.51: Dialog Fluids
Figure 7.49 shows the available settings for the Fluid selection. For more
information see section 8.3.
SimulationX 3 7-71
7.6.9 Miscellaneous
In this tab the label of the elements is set, as they are shown in the model.
Customizing of element labels and connection labels are described in section
5.2.3.3.
The auto routing for connections can be deactivated/activated.

Further settings of the Model Explorer are present.
7.6.10 Connections
Connections can graphically represent their state during the simulation. The default
behavior for individual connection types, e.g. Mechanical connection (linear), you
can specify on this dialog page.
Figure 7.52: Settings of the connections
These settings are stored globally and thus apply to all models, as long as no local
settings for individual connections were made in the model.
7.6.11 Languages
With this menu option you can select the dialog language of SimulationX. You
will get a list of the languages that are available. As you click with the mouse on a
language it becomes the dialog language for SimulationX.
Figure 7.53: Setting of the language
7-72 SimulationX 3
General Settings
7.6.12 Licensing
Using the menu Extras Options Licensing allows you to switch to another
license. It can be done by a click on the button below SimulationX start as:
followed by selecting the desired edition. See chapter 2.
Figure 7.54: License Settings
7.6.13 Maintenance
This dialog allows you to check for update and specify the interval when
SimulationX is supposed to check for updates automatically. This requires a
working internet connection. Before you install any update, we recommend you
read the Release Notes first.
SimulationX 3 7-73
Figure 7.55: Maintenance settings
Office Add-ins can be installed from the Options section (see section 9.2). You
can also customize the installation of SimulationX (e.g. add new libraries). Please
note that the Office Add-ins are bound to a specific user. When other users log on
to Windows, they must reinstall the Office Add-ins under their account in order to
use them.
Figure 7.56: Display in the missing of a license
You can also reset all settings you made for non-licensed or not installed features.
(Disable this function permanently, see Figure 7.54).
7-74 SimulationX 3
General Settings
7.6.14 Customizing of the Program

By the menu Extras Customizing you can adjust the graphical user interface
of SimulationX (Commands, toolbars, menus, and others).
Figure 7.57: Adjustment of the graphical user interface of SimulationX
If icons in the toolbar are not displayed properly after an update from SimulationX
in the tab Options a Reset my usage data can be helpful.
SimulationX 3 7-75
7-76 SimulationX 3
by
Customization and Extensions

Administration of user-defined Types in SimulationX
8 Customizing and Extension

In this chapter you will learn about creating your own Element Types and defining
your own Fluid Types.
8.1 Administration of user-defined Types in SimulationX

The term user-defined types indicates types, which are created with the open
model description language Modelica and therefor e.g. can be edited with the
TypeDesigner in SimulationX. If necessary an encryption protects the type from
unauthorized access (e.g. against editing).
Working with Modelica classes will be described in a separate chapter. Here

some general definitions, which are helpful for the administration of user-defined
types, follow:
A type is the definition of all properties, which an element represents in a model,

e.g. symbol, parameters, result variables and behavior (equations ). The type
consists of components of types. Components of types could be a parameter of
type Real for instance as well as an element of (element) type
Mechanics.Translation.Mass in a sub structure.
In general, the user defines new types via the TypeDesigner, which is integrated in
SimulationX. The format and location for saving the definition can be configured
during the definition process. Furthermore, between different security levels can be
chosen to define permissions for using and changing this type.
A distinction between global types and local types is defined. Here and in the
following of chapter 8 this is done from the perspective of an opened simulation
model in SimulationX:
Global types can be found within the library bar of SimulationX. These types are
globally defined in the program environment and useable for all models or other
types. Global types are saved as individual file separately or in the package.mo file
of a corresponding library package. Those packages can also be saved as a
directory folder. The path is determined with respect to the directories in Extras
Options Directories Modelica Search Path.
Local types are saved inside of a simulation model and can be found in the model
explorer on page Types. Thus the usage of local types is limited to the model itself.
SimulationX 3 8-1
User Manual 8. Customizing and Extension
Move and Copy inside SimulationX

The location for saving types is changeable within SimulationX. With moving and
copying operations of types, often changes of the physical storage respectively file
name are associated.
This feature is used to change local types into global types (and vice versa) or to
change its position inside the tree structure. The handling procedures are described
in chapter 4).
It is possible that the copy and move functionalities are limited by the encryption
of types.
Moving a type from the library bar into the tree structure (page Types) of the
model explorer (and vice versa) changes the reference within the element (model
component). That is essential, because while moving the element its storage
location is also changing. Hence the old reference is not valid anymore.
Example:
The global type Type_move in a user defined library package UserDefinedTypes:
is used in a model. The reference can be determined in the element property dialog
on page "General" or in Modelica code of the model. The current type reference
is UserDefinedTypes.Type_move.
By moving the type via Drag-and-Drop into the model, the reference of the type to
the element will be changed to Model1.Type_move (compare Figure 8.1).
However inside the Modelica code, the name of the model is not included in the
reference.
Figure 8.1: Type Model1.Type_move
The type is no longer available within the library bar and cannot be used for
modeling in other models than Model1. Already existing models, that are not open
during the moving process (including model components of the type Type_move),
still contain the type reference UserDefinedTypes.Type_move. These models
8-2 SimulationX 3
cannot be opened anymore correctly. An error message will be generated, that the
corresponding type is unknown.
It is also possible to move types from the model (model explorer, page Types) to
the library bar. There the reference in the element (model component) is changed
as well.
By copying types via Drag-and-Drop (press Ctrl-key while Drag-and-Drop ) the

reference of the model element will not be changed. The model element still uses
the original type as template.
Please note: Copies of types are independent from their origin. These copies can
contain different contents even though the type names are identical.
Overwriting already existing types

Existing types in the library bar or in the model explorer cannot be overwritten by
copy or move operations within SimulationX. An existing type, which has to be
replaced, has to be deleted before. Afterwards the new type has to be saved at the
same position.
Models with user-defined types

If models are created with global types and the models should be computed on
another computer, it is necessary that the types can be accessed from this
computer. This can be ensured with three different methods:
1. The *.mo files of the user-defined type are saved on a network drive in a
way, that SimulationX is loading and using the same files on both
computers.
2. The files for the user-defined types are present at both computers, while
name and content should be identical and
the tree structure of the library containing the user-defined types has to be
identical on every computer.
When changes on types have been conducted, the *.mo files have to be
changed. The exchange of *.mo files is also possible during a SimulationX
session, but the function Reload has to be executed before a new
simulation run is started.
3. The types are saved as local types inside the model and are passed on within
the model file.
For saving types as local types within the model, the function for resolving
external references (Menu Edit Resolve External References) can be used. It
SimulationX 3 8-3
copies the global types into the model (creation of a local type) and resolves the
type references from global to local. The global type still remains in the library bar.
The feature creates a special entry Imported Types in the model explorer. This
entry contains the imported local types. Moreover, external fluid definitions will be
imported in the same way.
Loading user-defined types into the library bar

After starting SimulationX, the global types will be loaded from the specified
directories into the main memory.
The replacement of a *.mo file for an existing user-defined type in the

corresponding directory does not affect the type in the SimulationX library bar
initially. Only if the Reload function or a restart of SimulationX are executed, the
global type element definition are updated.
Modifications of types in SimulationX are updated after finishing the

TypeDesigner or by file saving after changing the internal structure.
If user-defined type elements are used by more than one user, it is recommended
that one user is responsible for data administration and management.
Administration outside of SimulationX

Global types are saved with the *.mo-file extension.
The file name consists of the type name, the hash mark # (optional) and a version
counter. In general a text file format is used for saving. By using encryption
methods for file protection, a binary file format will be used instead.
After editing and saving an existing global type, a backup file is generated by
SimulationX automatically.
The backup file gets the file extension .mo1. Further changes result in increasing
the counter step by step with increment 1. The file with the highest index is the
latest back up file.
The creation of a new package in the library bar usually results in the generation of
a new directory. The name of the new package is identical to the name of the new
directory. During entering the name, SimulationX pays attention to a correct
syntax and already existing names in the same level of hierarchy. It is not allowed
to use identical names for packages or types in the same level.
A file package.mo will be generated within the new file directory. This is
necessary to ensure compatibility with Modelica definitions.
The relation between the type structure in the user-defined package

UserDefinedTypes and the file structure in the corresponding type directory is
explained in the following with the help of an example (compare Figure 8.2):
8-4 SimulationX 3
Library hierarchy UserDefinedTypes File system structure
Figure 8.2: Type and file system structure of global user-defined types
The directory UserDefinedTypes is stored in a directory which is given in Extras

Options Directories Modelica Search Path. It has been created with a
right mouse click on the root of the library bar and selecting the entry New
Package ... in the context menu. The directory for storage has been selected in
TypeDesigner from the Modelica Search Path.
The directory NewGroup1was created via right mouse click on

New Package .... of the UserDefinedTypes library bar entry. In both
directories (UserDefinedTypes and NewGroup1) a file package.mo was generated,
when the packages were created in SimulationX.
The type NewElemType3 was created with the attribute Save Within Environment
(No Own File). Its source code is contained in the file package.mo, which
corresponds to the package NewGroup1. The types NewElemType1,
NewElemType2 and NewElemType4 were saved as individual files. I.e. for each of
them an individual *.mo-file is existing.
Files ending on mo1, mo2, etc. are backup files which are created by SimulationX
whenever a type is modified (this behavior can be deactivated with the
corresponding setting at Extras Options Storing). Files containing # are
generated when new versions of types are created.
SimulationX 3 8-5
By default Packages are saved as directory. It is possible to transform a package

into a file at any time, whereas all belonging packages and types will be
implemented into the new environment, i.e. the new file.
It is possible to create the library tree structure for a user-defined library outside of
SimulationX. To avoid problems during the load process it is necessary to pay
attention about the used syntax.
Versions of global types

SimulationX supports the creation and usage of different versions of global types.
This refers to the SimulationX libraries as well as to user-defined types. By
creating a new version of the type name#1_0.mo, a new file name#2_0.mo will be
saved in a separate file. Within SimulationX, only the newest version is available
for editing. Deleting this or an older version can only be performed at file level in
the respective directory. For copying or sending a type, which exists in different
versions, it is required that all files name#i_j.mo are considered. If one file is
missing, it might occur that a model, which requires that particular version, cannot
be opened.
Special user defined types
Fluid types
Fluid types are defined with the FluidDesigner. These fluid types are separately
saved in a Name.mo file. The path is taken with respect to the directories in
Extras Options.
SimulationX model
Per definition a SimulationX model is a type, similar a type. In addition to the type
there are additional information, parameters , which are necessary for a
simulation computation. Hence a SimulationX model is also editable via the
TypeDesigner. To access the TypeDesigner, double-click on the model on Model
Explorer tab Types. Alternatively you can perform a right-click on the model Open
TypeDesigner. (For more information please refer to section 4.2.4).
The name of the model is automatically assigned (Model1, Model2 ) by

SimulationX. During a SimulationX session the index for each opened model is
increased automatically. The model name will be saved within the model file. The
index can change after opening a model in the case that an already opened model is
using the same name. For this reason the model name should not be used in
references of variable names.
8-6 SimulationX 3
8.1.1 Import of ExternalTypes Packages

From SimulationX 3.6 onwards there is no ExternalTypes package available
anymore. Modeling user-defined types can be done using Modelica packages. This
change aligns the handling of user-defined types more closely with the Modelica
standard. Types from former ExternalTypes directories can be still used by
importing them.
The import for ExternalTypes directories takes the types which were created within
the ExternalTypes package and converts them into a Modelica package. It can be
used like ordinary Modelica packages by integrating them, using the Modelica
search path.
The import dialog for ExternalTypes packages (Figure 8.3) can be accessed
through the options dialog (menu Extras/ Options) under Directories /
Modelica Search Path by clicking the button External Types.
Figure 8.3: Import Dialog for ExternalTypes Packages
The text field External Types Folder has to contain a path to a directory that
corresponds to an ExternalTypes folder which was created with SimulationX 3.5 or
earlier. That means, the path should be identical to a valid entry for a
ExternalTypes directory in the earlier version of SimulationX. Instead of the
manual input, the path can also be selected using the Search button.
At Package name a new identifier must be entered for the Modelica package,
which is created be the import of the ExternalTypes directory.
SimulationX 3 8-7
To declare a path in the Directory for MODELICAPATH, there are the following
possibilities:
Selection of an existing entry in the Modelica search path by using the

combo box
Selection of an existing directory using the Search button
Creation of a new directory using the Search button
This (new) directory will be automatically added to the Modelica search path.
By clicking the OK button, a new directory with the specified new package name is
created in the chosen directory for the Modelica search path. All files and
subdirectories from the ExternalTypes folder will be copied to the newly created
directory. Additionally, a package.mo file is created to fulfill the requirements for
Modelica packages. The package.mo file also contains the special Modelica
annotation __iti_ExternalTypes=true, which labels the package as a former
ExternalTypes package. The original ExternalTypes directory is not modified by
the import.
SimulationX creates internal links for the types from the imported ExternalTypes
package. These links are used to resolve references which still contain
ExternalTypes as part of their identifiers. This may occur, when models are loaded,
that have been created with an earlier version of SimulationX. In special cases, e.g.
when relative identifiers were used in the former external types, the internal links
may not be sufficient. Such relative references can be corrected using the
interactive type correction.
8.1.2 Interactive Type Correction for Loading Models

SimulationX offers an interactive type correction if references cannot be resolved
during the instantiation of a type, i.e. if no matching type is found for a Modelica
identifier. The user can select an alternative type, for the type which was not found
and which should be used for the remaining instantiation.
The interactive type correction handles references on base classes, component

types, base classes for type redeclarations, types for component redeclarations as
well as references in import statements.
It is not only possible to correct references, which occur in the type which is about
to be loaded, but also for references within types outside the current type, which
are needed for its instantiation. Corrections are possible in individual models
(ism/isx files) but also for types defined in Modelica libraries.
Typical use cases for the type correction are the conversion of models to a new
version of a library or the adjustment to changes during the library development.
8-8 SimulationX 3
8.1.2.1 The Type Correction Dialog

The dialog for the interactive type correction (Figure 8.4) is shown if a
reference to a type which is used in a model or another type from a library
cannot be resolved while loading the file.
The text fields Environment and Modelica Code give information about the
position in the opened type, where the reference cannot be resolved. Reference
shows the identifier of the type which could not be found.
Figure 8.4: Dialog for interactive type correction
After a type has been selected in the combo box New Element Type as a
replacement for the type which was not found, the reference can be corrected by
clicking the Replace button.
References with the same name and environment are automatically handled in the
same way as the first occurrence of the unresolved reference was treated.
If the reference shall not be corrected, there are three additional possibilities:
Ignore the behavior for the reference is identical to SimulationX 3.5, i.e.
components with an unknown type are removed and the instantiation is
interrupted with an error in case a base class cannot be found.
Ignore All like Ignore, but additionally all the remaining unresolved
references are ignored.
Cancel the instantiation is cancelled and the type is not loaded; the type is
not modified.
SimulationX 3 8-9
For import statements an additional Remove button is provided. Sometimes types

contain import statements which are not necessary to resolve type references
within the type. Such import statements can be safely removed. To keep such an
import statements in the type, the Ignore button should be used.
References in expressions, algorithms and equations cannot be corrected using the

interactive type correction.
Type correction is not possible for encrypted types.

Using the interactive type correction is not possible as long as other types are
opened at the same time. In this case the type correction is interrupted with a
warning.
8.1.2.2 Corrections outside the Current Model

During the interactive type correction it is possible that changes outside the actual
opened type (e.g. in other types) are necessary.
Figure 8.5: Dialog for changes in the Library Tree
After the interactive type correction was finished i.e. either after the corrected
type has been instantiated successfully or after the type correction was interrupted
the Dialog for Changes in the Library Tree (Figure 8.5) is opened. It contains
a list of types outside the current type, which were modified during the type
correction. The files, in which these types are implemented, are shown at the same
place. By clicking the Save-button, the modifications are stored permanently in the
file system. Discard can be used to reverse these modifications.
8-10 SimulationX 3
TypeDesigner
8.1.2.3 Example for the Interactive Type Correction

The following example illustrates the usage of the interactive type correction. Two
simple models Test and MissingBaseClass are given:
model MissingBaseClass
extends UnknownBaseClass;
end MissingBaseClass;
model Test
MissingBaseClass m;
end Test;
It is assumed that the base class UnknownBaseClass of MissingBaseClass

cannot be found. The model Test, which contains an instance of the type
MissingBaseClass, is opened:
When attempting to open the model Test in the diagram view, the dialog
for the type correction (Figure 8.4) is shown, because the base class
UnknownBaseClass of MissingBaseClass cannot be found during
instantiation of the component m.
Now a new type can be chosen as the base class for MissingBaseClass at
New Element Type, e.g. Modelica.Icons.Example. Replace resumes the
instantiation using the new type.
Since a type outside the model, which is about to be opened, has been
modified by the interactive type correction, the dialog for changes in the
Library Tree (Figure 8.5) is shown. The user is informed that the type
MissingBaseClass, which is defined in the file MissingBaseClass.mo,
has been modified (UnknownBaseClass was replaced by
Modelica.Icons.Example). Save confirms the changes and saves the
modifications in the file. Subsequently, the model Test is shown in diagram
view.
8.2 TypeDesigner
The TypeDesigner is the in SimulationX integrated editor for the definition of user
defined library elements. The TypeDesigner offers access to the complete range of
possibilities for modeling and programming in SimulationX and the object-
orientated modeling language Modelica.
The TypeDesigner assists the user during the creation and the development for all
kinds of standardized Modelica classes:
Model (type)
Connector
Record
SimulationX 3 8-11
Block
Function
Package
The following steps explain how to start the TypeDesigner. After that an example
describes the definition of a type.
New types can be created in different ways:
1. Creation of new types (see section 8.2.1)
2. Extension of existing types (see section 8.2.3)
3. Creation of composed types (see section 8.2.4)
8.2.1 Starting and Dialog

The TypeDesigner can be started within SimulationX wherever a new type can be
created or an existing type can be modified (Please also refer to chapter 3).
Library bar: In the tree view use the right mouse button and click SimulationX
or a lower-level package. Select New Model in the context menu to
create a global type.
Model Explorer: In the tree view on page Types use the right mouse button to
click on the root entry. Select New Model ... in the context menu to create a
local type
Menu bar: Elements Compound or Elements Extension, therefore
one or more model components have to be highlighted. Extensions are only
allowed of single highlighted components.
Library bar: In the tree view use the right mouse button and click to an
existing type (SimulationX library or other global types). Select Extension
in the context menu to create a global type.
Model Explorer: In the tree view on page Types use the right mouse button to
click on an existing type. Select Extension in the context menu to create a
local type.
Library bar or Model Explorer: Use the right mouse button to click on an
existing type and select Edit" in the context menu. Double clicks on a type
also open the TypeDesigner.
The assignment of the new type (global or local) can be changed at any time.
The TypeDesigner is intended to edit the content of the type. To change the
structure it is necessary to open the type via Open in the context menu.
8-12 SimulationX 3
TypeDesigner
Figure 8.6: View TypeDesigner
8.2.2 Features of the TypeDesigner

The following chapters describe the property pages of the TypeDesigner.
section 8.2.3 explains the page "Base Types" for types of kind "Extension". section
8.2.4 describes the additional property pages for creating compounds of
components.
8.2.2.1 General
Type Definition
If the TypeDesigner has been started in the library bar or in the Model Explorer via
the context menu New/Model the storage position is fixed at that point.
The kind of storage (within environment / as file) depends on the environment of
the new type. A type could be saved as file only within an already existing
directory (package).
If the TypeDesigner has been started via the SimulationX menu (Elements
Compound, or Elements Extension) or via the context menu of an internal
SimulationX library type (Extension), the storage position has to be defined by the
user themselves too:
local (within the model) or global (within the library bar) storage
the environment: package or existing type (selection via tree structure)
SimulationX libraries cannot be selected as the environment, because they are not
changeable by the user.
Name and Comment

Enter a unique identifier for the new type in the field Name. Follow the rules for
the name formats (see chapter 10).
SimulationX 3 8-13
The type can be described with a comment. The type name will be used for file
name generation as well as for an automatic generation of component names in the
model.
Graphical Representation
The symbol defines the graphical representation of the components within the
types-/library tree and the elements of this type in the diagram view. If no symbol
is defined, then a default frame with the symbol dimensions is created.
The button creates a new symbol. The symbol can be edited directly in the right
hand side window. It is possible to generate graphical objects via the integrated
toolbar. Bitmaps can also be used in the symbol. Pixels with the color magenta
(red=255, green=0, blue=255) are interpreted as being transparent.
By the button a predefined symbol can be imported.
Hint:
When you draft the symbol take the later position of the connectors into
consideration already. Optimum results are yielded when the connectors are in the
15-pixel grid at the edges of the symbols.
8.2.2.2 Connectors
By the definition of connectors (also called "ports") you define the interface for
elements of the new type. Perform the following steps for each connector to be
created:
1. Select the desired type of connector (see Figure 8.7).
2. Insert it with the button next to it. The new connector is displayed in the
preview window.
3. Properties such as name and comment can be edited.
4. With Drag-and-Drop you can move it to the desired position in the window.
Figure 8.7: Connectors selection box
8-14 SimulationX 3
TypeDesigner
The number of connectors is only limited by the size of the frame. By enlarging the
element (width and/or height) you can extend the number of connectors. If a
bitmap already exists it is necessary to delete the bitmap before changing the
symbol dimensions.
With the buttons the order of the connectors can be changed and using
deletes a connector.
Figure 8.8: Dialog Connectors
8.2.2.3 Base Types

Explanations about this page you will find in section 8.2.3.
8.2.2.4 Components
Add different types of components and edit them. To this end, perform the
following steps:
1. Select the desired component type (see Figure 8.10). Table 8.1 gives an
overview to major properties of available component types.
2. Insert it with the button next to it.
3. Properties such as name and comment can be edited.

4. Depending on the selected component you can enter other properties (e.g.
physical variable or default values)
SimulationX 3 8-15
Figure 8.9: Dialog Components
Figure 8.10: Components selection box
Type: The available settings depend on the type of component.
Physical Quantity: The type attributes quantity and displayUnit can be defined to
select a default unit for components of type Real, Integer, Boolean. These
attributes define the available units and the displayed (default) unit in the property
dialog.
Dimension: Scalar or multidimensional value (vector )
8-16 SimulationX 3
TypeDesigner
Further settings: Possible settings in the lower table depend on the selected
component type. A Parameter, for instance, can serve as Start Value. By choosing
the option Disabled, a component can be set to visible but not changeable. This is
helpful e.g. for fixed directories or for results delivered by other programs. Using
the Protected option, e.g. for a variable, makes the variable invisible in the
parameter dialog of the type. This can be used for hiding variables, which are used
for the calculation of intermediate results in the algorithm or equation section. If
the option Discrete is selected, then the component is only changeable within event
iterations.
Declaration equation (for Variables): Using the declaration equations is not
recommended at this point. In general the result is similar to an equation in the
equation section of the TypeDesigner on page Behavior.
If there is another equation in the equation section for this variable, then there is
one equation too much. The user will get a message about this problem in the
Output window. The analysis of the problem will be more complicated because
possible reasons are located at two different points.
Start Value (for Variables): If a variable is designed to be a state variable then the
start value, also called initial value, should be editable by the user. Therefore a
value can be entered or an existing parameter with the start value attribute can be
selected in the enumeration. To get a parameter with start value attribute the user
has to create a component of type Parameter.
After that the option Start Value in the lower table has to be activated. The symbol
of the parameter component switches from blue to red. The parameter should have
the same quantity as the variable. Within the parameter dialog in SimulationX this
parameter contains the special symbol of a pin, which allows fixing or unfixing the
entered start value.
Attributes: The adjustment of the attributes of pre-defined is done here. A

description is given in Chapter 11.4.3.2 of MLS. During the parameterization of
components they can be changed (chapter 5.3.4).
The same control elements apply as with connectors.
SimulationX 3 8-17
The following component types are available:
Component Application
Parameter Input of numerical values and mathematical expressions of
the Real type, Integer type, Boolean type or String
type (see also Table 8.2). Parameters of Real type can be
used as initial values of states.
Enumeration Selection of an option from an enumeration, requires the
selection or generation of an Enumeration type (see
TypeDesigner on page Local Types/Enumeration)
Boolean Selection of an option
Variable Result variable (see Table 8.2)
Characteristic curve Input of a characteristic curve f(x)
Set of characteristic Input of a group of characteristic curves fi(x)
curves
Family of curves Input of a family of curves
2D-look-up table Input of a 2D-look-up table
3D-look-up table Input of a 3D-look-up table
Database link Linking of parameters of the type with a database
Block Use of a Block type as reusable input-/output blocks (see
Local Types/Block)
Record Set of associated data with different types - selection of a
Record type is necessary (see Local Types/Record)
Model Extension of a compound (see section 8.2.4)
Dialog group Group of components in a page of the properties dialog,
allows the arrangement of properties in groups
Dialog page User defined dialog page of components in the properties
dialog, allows the creation of user defined tabs in the
property dialogs
Table 8.1: Component types
The property of variability defines the using of a component as parameter or as

variable.
8-18 SimulationX 3
TypeDesigner
The following table shows alternatives and consequences.
Variability Property dialog Allowed expressions

representation
Variable result variable none
(recordable) (only start value definition)
Variable Parameter variable expression during calculation
Parameter
Constant Parameter constant expression during calculation
Parameter
Constant Parameter constant expression during calculation, not
(disabled) changeable by the user via property dialog
Table 8.2: Variability
Parameters will be displayed on page Parameters and allow the input of

expressions. Variables can be recorded and displayed as results.
Dialog pages and groups

Using dialog pages allows you to arrange components at different pages in the
properties dialog. Dialog groups allow arranging the components at a dialog page.
Definition in the TypeDesigner Properties dialog
First create the dialog page or group. At the right side you can give a name.
SimulationX 3 8-19
Move the new item up and down by using the arrow buttons. The components
below will be displayed with the corresponding indent. This shows that the
component is subordinated to page (or group). If a component should not be
subordinated, then move the component above the first page of the type. These
components are displayed on the standard pages for parameters and results.
Empty dialog pages and groups are not stored in the type and they are deleted also
if the components site is left.
Hint:
Dialog pages and groups influence only the display in the property dialog. Name
and identifier of components are not changed by the relation to a group.
8.2.2.5 Local Types

Local types are stored in the current type. The following kinds of types are
available:
Enumeration
Function (external or internal function, partial derivation)
Record
Block
Model
Connector
Type definition
Package
The definition of local types under types is possible. A type in type construct
will be generated which was already described at the beginning of this chapter. For
a well arranged modeling such structures should be avoided and only be used in
exceptional cases. One of these cases is the usage of enumerations which are
usually bound to a certain type and must be defined within the type.
To add a new local type, select first the kind of type and add the type using the add
button . At the left side you can edit name and comment of the new type.
For editing of structured types (Function, Block, Record, Models, Connections, and
Packages) opens a special TypeDesigner via the Edit button.
Enumeration
The type of an enumeration defines a set of alternatives and a default value. When
you create a component of the enumeration type, you can define the visibility of
the alternatives and a different default value.
Function (Definition of a stateless calculation)
Functions are reusable calculation modules. The arguments (input- and output
parameter) are the interface.
8-20 SimulationX 3
TypeDesigner
External functions calculate the output parameters using an external function

call in a DLL.
Internal functions use an algorithm for calculation of the output parameters.
They can have components and local enumeration- and function types. (see
also chapter 10).
Record
Records are a set of associated data of different types. Using records, for instance,
simplifies the syntax of assignments.
Block (Definition of a stateful calculation)
Blocks are reusable input-/output blocks with own algorithm and/or equations. The
arguments (input- and output parameters) are the interface. A Block can have own
components and local types.
Model
Model types are templates for elements within a simulation model. They define a
stateful behavior description. The interface is realized via connectors.
Connector
Connector types allow the definition of user defined types for connectors.
Type Definition
Type Definitions allow the definition of extended types in a shortened syntax for
the case, that the structure of the Extension is unchanged. However the properties
of the inherited components of the base class are changeable. This modification
can be done after selecting the base class.
Package
A package unites the definitions of types and constants, e.g. for such which belong
to one topic. This results in a better readable source code. Additional the using of
packages avoids name conflicts, e.g. Pneumatic.Valves vs. Hydraulic.Valves.
8.2.2.6 Imports
Imports provide public definitions of a package to a local type and allow therefore
a shortened syntax. Furthermore the import statement defines explicit the
dependency between type and imported package.
Via the button additional import statements can be added. Then available
definitions can be chosen in a selection box.
The import of package contents is possible in three different ways. The differences
are shown in Table 8.3.
SimulationX 3 8-21
Figure 8.11: Selection Box of the Import
Import Notation for Re-nameable?

Mechanics.Translation.Spring
Mechanics.Translation Translation.Spring yes
Mechanics.Translation.Spring Spring yes
Mechanics.Translation.* Spring no
(Import all definitions)
Table 8.3: Imports
The first two possibilities allow renaming the imported definition within the
current type. Then the definition can be used with the new name within the type,
e.g. to avoid name conflicts with already existing definitions.
By activating the option Import all definitions, all package definitions will be
imported. This is indicated with the * sign at the end of the expression in the
import column (see Figure 8.12).
All names of the imported definition will be converted to shortened syntax within
the source code. After deleting an import, the complete identifier will be used
again.
8-22 SimulationX 3
TypeDesigner
Figure 8.12: Select Import
8.2.2.7 Activity Groups

Activity Groups serve to create dynamic property dialogs. Dynamic dialog means
that their content depends on the current parameter assignment.
Activity Groups permit to define conditions when certain parameters are visible or
invisible.
To make the Activity Groups function available, enable the checkbox Support
Activity Groups first.
With the button you create a new group which you can edit.
A list of tuples {name, condition, list of corresponding parameters} is maintained.
Each tuple is one ActivityGroup. The parameter list gives the names of the
parameters which are influenced by this Activity Group.
If a condition returns the value false, the corresponding parameters are invisible in
the properties dialog and they return the value 0. If a parameter exists in several
Activity Groups, the individual conditions are linked with OR, i.e. if a condition is
true this parameter is visible then.
To delete an Activity Group, mark it and use the button Delete .
Example:
You want to create a type which uses a cross section and a flow as selection
criterion for various approaches.
Enumeration Option
Cross section A = {a, b } Rectangle
A={ d } Circle
Flow Q = { p1 } Approach1
Q = { p21, p22 } Approach2
Q = { p31,p32,p33 } Approach3
Table 8.4: List of parameters
SimulationX 3 8-23
There are two enumerations which select the type of the respective option.
The type contains one parameter of the ActivityGroups type then and its value
consists of the following entries:
Name Condition List of parameters

Rectangle A==1 a,b
Circle A==2 D
Approach1 Q==1 p1
Approach2 Q==2 p21,p22
Approach3 Q==3 p31,p32,p33
Table 8.5: Conditions for A and Q
Application in the TypeDesigner:
1. Create one component each for the cross section and the flow and the
corresponding parameters.
To do this, select one component of the type Enumeration and add it.
Assign the respective name then (A in the present example) and the comment
(Cross section). Add the values now (in the present case Rectangle and
Circle). Define any other parameters then.
Figure 8.13: Dialog Components
8-24 SimulationX 3
TypeDesigner
The order of the entries corresponds to the representation in the properties dialog
of the new type and should be used for the example as shown in Figure 8.13.
2. To create an ActivityGroup
Activate the Activity Groups with the checkbox Support Activity Groups (top
left). Use the button , define the conditions for the enumerations and enter
the parameters.
Note:
Inactive parameters return 0.
Enumerations are inquired via an integer value.
Figure 8.14: Activity Groups
3. To test the conditions of the ActivityGroup
Create an element of the new type in the diagram view and open the properties
dialog. Under Parameter1 you find the previously defined selection criteria and
you can test them.
Figure 8.15: Parameter dialogs
SimulationX 3 8-25
The test results are given as an example in Figure 8.15 for:

rectangle and Approach1
circle and Approach2
A new dialog is used if there are more than 10 parameters. In the present case the
parameter p33 in the dialog Parameter2 is displayed for Approach3.
8.2.2.8 Behavior
The behavior of the Type can be described with algorithms and equations.
The left side shows the names of the available components and local function types
for information. An enumeration shows also the available alternatives. At the right
side you can edit the currently selected section.
Figure 8.16: Algorithms and equations
It is possible to define more than one equation or algorithm section. During the
simulation the sections are evaluated in the order in which they appear. The order
can be changed by using the arrow buttons and by doing Drag-and-Drop of the
tabs at the bottom of the view.
Every type needs at least one equation or algorithm section. When possible you
should describe the behavior by using equations. This increases the chance of
optimization by the symbolic analysis.
Hint: Internal functions contain only one algorithm section. Adding sections is not
possible.
8-26 SimulationX 3
TypeDesigner
Enter a sequence of instructions which describes the behavior of the new type. In
addition to instructions for numeral values and arithmetic operators, the control
constructors which are common in programming languages are also available. You
have access to the connectors, parameters and result variables via their names.
Equation section:
Enter the equations which describe the new type. Any equation has a left and a
right side which are connected with a "=". The equation must be terminated with a
";". The equations are analyzed automatically prior to the simulation and the order
of processing inside the section is determined internally.
Algorithm section:
Enter a sequence of instructions which describes the behavior of the new type. In
addition to instructions for numeral values and arithmetic operators, the control
constructors which are common in programming languages are also available. You
have access to the connectors, parameters and result variables via their names. The
algorithm determines the processing order of the statements.
To ease the work with the notation of algorithms and equations are the following
buttons available:
Find Variables, Parameters, (text retrieval)
Find and Replace (text retrieval)
Check Syntax
Chapter 10 gives a detailed description of the application of variables in an

algorithm and in equations.
In addition to the description of the type behavior within the simulation one can
include special sections concerning the initial value calculation. Both options of
the behaviors description, i.e. Initial Algorithm and Initial Equation, are
available. The Initial-sections will be utilized only during the calculation of the
initial values of the model. The usage of systems of equations or algorithms for the
initialization is only necessary in case the initial values cannot be calculated
explicitly. A further possibility the behavior of an element to describe is the use of
state chard diagrams (see section 8.4).
8.2.2.9 Modelica Code

On this page the Modelica source code can be inspected and edited.
To protect the source code from accidental changes the view mode is the default.
In this mode the text can be inspected, but is not editable. You have to press the
edit button to enter the edit mode. When finished with editing press the edit button
again. You are asked whether you want to accept the changes. If you deny, all
changes are lost. If you accept, the source code is validated. Syntax errors - if there
SimulationX 3 8-27
are any - are shown in the message area below the text input field and you are
asked to correct them. If the source code is correct then it is accepted and the
Modelica page changes from editing mode to view mode and all other pages in
the TypeDesigner are updated too.
Enables editing of the Modelica source code. Click to switch to editing
mode (the background color of the button changes from gray to blue).
Click again to switch back to view mode (the background color changes
from blue to gray).
Undoes the last user input (e.g. typing, copy-paste, or query-replace
operations).
Redoes undone user actions.
Starts a text search.
Starts query and replace.
Performs a Modelica syntax check on the source code.
Enlarges the font size.
Reduces the font size.
For clarity of the source code you can collapse Modelica code fragments by
clicking the framed minus signs at the left border of the text window. The
collapsed code fragments are indicated as three dots "..." (see Figure 8.17). To
expand the code fragment click on the framed plus sign.
Figure 8.17: Collapsing a code segment by clicking a framed minus sign.
This feature is especially useful for hiding annotations which in general do not
influence the behavior of the model but determine the graphical representation of
the type in the user interface.
8-28 SimulationX 3
TypeDesigner
8.2.2.10 Documentation
In order to simplify utilization and re-application of a new type, you should
document your work. Documentation is done in form of HTML file.
If no such file exists yet, the TypeDesigner generates a frame (see Figure 8.19)
with all essential components required to document the new type. Your task is to
complete the generated frame with any information which permits proper use.
For this extensive input and editing options are available.
Create new template
Select font
Select font attributes
Select font colors
Insert picture
Insert table
Insert Hyperlink
Insert bookmark
Figure 8.18: Toolbar for the design of the documentation
Figure 8.19: View Documentation
SimulationX 3 8-29
8.2.2.11 Security
SimulationX offers a two-level safety concept (see Figure 8.20) to protect global
types against unauthorized access or changes.
Usually global types are stored in the model language Modelica and they are
freely accessibly by any user.
By encrypted storage access to these files can be prevented. However, these
models and types can still be loaded without any restriction. To prevent this, you
can use encryption optionally with a password in addition (Password for Usage).
Figure 8.20: Dialog Security
To use global types, which are protected in this way, in SimulationX, you must
input the correct password when you load the file. Passwords which are entered
like this are stored on your computer in a computer-specific and also encrypted file
to avoid that the password is inquired any time you start SimulationX. This file
cannot be transferred to another computer and it is created anew by SimulationX
after hardware components, like hard disk or network interface card, have been
replaced in which case the passwords must be re-entered.
Frequently, global types shall be made available to other users. In this case it can
be desirable to prevent insight into the functions and to prevent any changes to the
behavior of the type. This can be done by entering a second password (Password
for Editing), see Figure 8.21. For the execution of any actions which disclose the
behavior of the type (converting into local types) or permit changes to the type
(starting the TypeDesigner), it is obligatory to input this password. This password
is not stored.
8-30 SimulationX 3
TypeDesigner
Figure 8.21: Dialog Password
The option for encryption and the two-level password protection can be lifted only
by fully authorized users.
Hint:
Make sure that your password is kept in a safe place. Without a valid password you
will not be able anymore to open and edit a global type which is protected in this
way.
8.2.3 Extension of Types (Inheritance)

With the help of the TypeDesigner you can derive a new type from an existing
type. Both types, i.e. those supplied with SimulationX and own types, are
admissible as a basis for this.
To derive a new type within a model from an element which exists already in the
model, proceed as follows:
1. Highlight the element whose type is to be used as a pattern for the newly to be
developed type.
2. Open the TypeDesigner (Elements Extension or button on the
toolbar).
You can decide whether the derived type is created as a global type (global) or
only in this model (local). The base type is also shown.
Working with the TypeDesigner is analogous to the procedure when you create a
new type, as described under 8.2.1. The properties of the basic type (connectors,
parameters, result variables, behavior) are extended to the newly created type. You
can extend it by new connectors, parameters, result variables now and extend the
behavior by adding new algorithms or expressions.
On the page 'Base type components' some properties of inherited components can
be modified for use in the current type.
If a property of an inherited component is not modified, then the corresponding
value of the component in the base type will be used. This means that changes of
the component properties in the base type will also affect the unmodified
properties of the corresponding components in all derived types. Modified
SimulationX 3 8-31
properties of components remain unchanged when the property is changed in the

base type.
Figure 8.22: Extended dialog of the derived type
Unmodified properties are indicated by blue text color and modified properties are
shown as black text. Modifications can be removed by deleting the text in the edit
box.
How to select a component of a base class:

1. Select in the drop down window the base type.
2. Select the component in the list.
3. Modify the available properties.
ActivityGroups and parameter groups are inherited from the base type. They are
not editable, but it is possible to add ActivityGroups and parameter groups.
The behavior of the basic type is not displayed. During the simulation the behavior
of the basic type is always executed prior to the behavior of the derivative. This
means that you can use results of the basic type or change them.
8.2.4 Compounding Submodels

Complete simulation models or a submodel can be compounded in a new type for
use in other models.
To do this, perform the following steps:
1. Select the model part which you want to combine in a new type (see section
5.2.3.2 - How to Select Several Elements).
8-32 SimulationX 3
TypeDesigner
Figure 8.23: Selected elements
2. Open the TypeDesigner (Elements Compound... or ).
The pages of the TypeDesigner are the same as those described in section 8.2.1 -
extended by the pages Inner Connectors and Inner Components.
Example:
Develop a model structure according to Figure 8.23. Select the elements and
compound them in a new type. You will complete the compound in the following
chapters.
When a compound is created, a graphic is automatically generated that contains a

preview of the summarized model structure (see Figure 8.24).
8.2.4.1 Inner Connectors

You can lead any connectors of the compounded elements outside for the new
type. Perform the following steps for each connector to be taken over in this way:
1. Click on the connector to be led out in the tree view.
2. With the button Add the new connector is created and shown in the
preview.
3. With Drag-and-Drop you can move it to the desired position in the preview
window.
Figure 8.24: Selection of connectors
Select the connector ctr1.Mass1 for the present example.
SimulationX 3 8-33
The selected inner connectors will then be available under Connectors for the
compounded type (see Figure 8.25).
Figure 8.25: Connectors of the new type
Hint:
You can use Drag-and-Drop for moving connectors directly from the tree view to
the preview window and for placing them at the desired position.
To delete a connector which was led out, select it with a mouse click and press
Remove .
8.2.4.2 Inner Components

Any components of the compounded type can be displayed and edited in the
properties window of this page.
Figure 8.26: Inner Components
To select a parameter, proceed as follows:
1. Click on the respective component in the tree view.

2. Take the component over into the preview list with the button Add .
8-34 SimulationX 3
TypeDesigner
Example:
Take over the following components:

Parameter mass1.m
Parameter spring1.k
Parameter damper1.b
The result is shown in Figure 8.26.
Hint:
Use Drag-and-Drop to drag components from the tree view into the preview list.
The inner components which have been taken over are given on the dialog page
Components, where certain properties (e.g. the comment) can be changed (see
Figure 8.27).
Figure 8.27: Components
To delete a component which was taken over, select it in the preview list and
actuate the button Remove .
When you use the compound you can use the components for parameter input (see
Figure 8.29).
Example:
Use the created compound (NewCompound1) and extend it by a mass (Mass1)
which is defined with the parameter Mass1.m = 2 kg.
SimulationX 3 8-35
Figure 8.28: Compound with mass
Figure 8.29: Parameters for the mass1 and the compound1
Start the simulation and display the resulting way of the mass (mass1.x) in a
result window.
Figure 8.30: Result window for compound application
Compare the result diagram with the results of chapter 3.
Any operations as described in the chapters 4 and 5 can be applied to the generated
types (i.e. moving, reflecting, and rotating...).
With the button on the toolbar the inner structure can be displayed for a
combined type in the diagram view. This view is closed with .
However, to change the type you must use the TypeDesigner!
8-36 SimulationX 3
TypeDesigner
8.2.5 Creating Packages (Libraries)

See chapter 8.1 and chapter 10.
8.2.6 Functions
8.2.6.1 Internal/External Functions
Functions are used to define reusable stateless calculation modules. The arguments
(input- and output parameter) are the interface of the function. Their order must be
considered when the function is called. The behavior of internal functions will be
described by an algorithm. The behavior of external functions is described by
functions from DLL libraries.
The Derivation button allows the definition of a function to calculate a

designated order derivation. For more information, please refer to the Modelica
Specification [5].
The SimulationX tracing can be accessed from external functions too. How the
tracing for an external function has to be implemented as described in section
12.9.6 of the Modelica Specification [5].
8.2.6.2 Partial Derivations

Partial derivations define a derivation of a function regarding one or more than
one input arguments of the referenced function.
For more information, please refer to the Modelica Specification [5].
8.2.6.3 Example External Function

The behavior of a type can be fully or partially described by external functions
from DLL libraries.
The basic steps for adding external functions to a type are explained in the
following. A simple example shows these steps and important details for specific
applications are described thereafter.
Example: Linking the external function times_two_c from the following

source code to a model.
/*
Simple example of an external function.
Compilation with the Microsoft C++ Compiler:

cl.exe times_two.cpp -o times_two_lib.dll -link -dll
Compilation with gcc in the cygwin environment:

g++.exe times_two.cpp -o times_two_lib.dll \
-mno-cygwin -shared
SimulationX 3 8-37
*/
// Compiler dependent settings:

#ifdef _MSC_VER
#define DLL_EXPORT __declspec(dllexport)
#else
#define DLL_EXPORT
#endif
/************* External function *************/

extern "C" DLL_EXPORT double times_two_c(double x)
{
return 2.0*x;
}
The example collection of SimulationX provides the following files:

times_two.cpp - source code
times_two_lib.dll - compiled library
times_two_model.ism - model containing the local type
times_two using times_two_c
Step 1:
The local type Function serves as an interfaces between SimulationX and external
functions. Add a Function f(x) to the Local Types of the type where you want to
use the external function and give it an appropriate name (see also section 8.2.2.3).
In Figure 8.31, you see the function times_two_fct among the components of
the type times_two. It is the interface to the external function times_two_c.
Figure 8.31: Adding the function times_two_fct
8-38 SimulationX 3
TypeDesigner
Step 2:
Declare the external function call in the function dialog window. You can open this
window by clicking on the Edit button (on the right side in Figure 8.31).
Figure 8.32: Arguments dialog of the function times_two_fct
The inputs and outputs of the function are defined on the Arguments page (see
Figure 8.32). The usage of this page corresponds to that one of the Parameter page
in section 8.2.2.3.
The external C-function times_two_c from the example has an argument of

type double and a return value of type double. This corresponds to type Real
for both input and output in SimulationX.
In addition to the argument window there is a calling convention window (Figure

8.33).
In the External Library field enter the name of the DLL library exporting the
external function.
The switch Calling Convention determines how the arguments of the external
function are put onto the program stack and how the stack is cleaned up after the
function call. You can choose between C/C++ and PASCAL/WIN32-API calling
SimulationX 3 8-39
conventions. Since times_two_c is compiled as an external C-function this

switch is set to C/C++ in the example.
At Function Call you declare the external function. Especially the name of the
external function, the order of its arguments and its return value are fixed here.
In the example the string y=times_two_c(x) corresponds to the definition of
times_two_c in the C-source code. The external function times_two_c takes
the real input x as an argument of type double and returns a value of type
double to the real output y.
Figure 8.33: Calling convention of the function times_two_fct
Step 3:
After adding a function to the local types of a type according to steps 1 and 2 you
are ready to use the function in the behavioral description of the type.
In Figure 8.34 this is demonstrated for the function times_two_fct from the
example. The so defined type times_two is applied in the demonstration model
times_two_model.ism to multiply the input signal by two (you find this
model in the example collection of SimulationX).
8-40 SimulationX 3
TypeDesigner
Figure 8.34: Application of the function times_two_fct in the behavioral description of

the type times_two
Important Details:
Remarks about the Arguments page in the Function dialog:
This page is similar to the page Components in the TypeDesigner. An
important difference is that there are only input parameters and output
parameters available on this page. You can use the input parameters as
arguments and output parameters as results for the external function.
Name: As already mentioned, you can refer to the input or output, resp., by
this name in the input field Function Call. In the behavioral description of the
type this is the identifier you use to specify the arguments of the function by
name (see the explanations below).
Type: Modelica-Type of the input or output, resp. In section Functions of
the chapter 10 and in 8.2.7 is listed how the data types of the arguments and
return values of the exported C-function correspond to Modelica types.
In the running example the function times_two has an argument of type double
and a return value of type double. That corresponds to an input of type Real
and an output of type Real.
Dimension: It is possible to transfer real-valued, integer-valued, or boolean-
valued vectors or matrices as inputs or outputs to external functions. Available
settings for the dimensions are:
Scalar: inputs and the return value of the function are passed by
value. For example, a scalar of Modelica type Real is passed as
value of C-type double to the external function.
On the other hand, if an output is used in the argument list
SimulationX passes a pointer to the memory where to store the result.
E.g., for a Real output parameter in the argument list a pointer with C-
type (double*) is passed.
SimulationX 3 8-41
Vector: For Modelica vectors always a pointer to the data field is

passed to the C function. For example, SimulationX supplies a pointer
of type (double*) for a Real-vector. If the user chooses Vector as
dimension type he has also to specify the size of the vector as an
integer. Please note the remarks to the dimension type free.
Matrix2D: The statements for vectors also apply to this dimension
type. The Modelica matrix is stored row-wise in the C-data field.
Matrix3D: The statements for vectors apply also to this dimension
type. The Element M[i,j,k] of a Modelica-Matrix corresponds to the
element size(M,1)*(size(M,2)*i + j) + k - 1 in the C-data field.
free: In many applications the size of a vector or matrix is unknown at
the time of the definition of the external function. For example, it may
be that the size of a vector results from the parameterization of an
object of the newly created type or by the signal connections in the
overall model.
In this case one chooses the dimension type free instead of Vector,
Matrix2D, or Matrix3D. An input field becomes visible where to
input the free dimension definition. The free dimension definition is a
comma separated list of dimension entries for the multi-dimensional
data field (vector or matrix). All Modelica terms for dimension
specification can be used as dimension entries. For an example the
free dimension definition ":,:" stands for a two-dimensional matrix
where the size is unknown at the time of definition. Furthermore one
can refer to the dimension sizes of other input parameters by the size
operator.
Other fields of the Function dialog:

You can specifiy a relative or the absolute path of the DLL file at External Library.
A relative path refers to the directories in Extras Options
External Functions and the standard search paths of WINDOWS.
Those are:
the directories listed in the environment variable PATH
the directory where SimulationX resides (simx.exe)
(usually: c:\Programme\ESI Group\SimulationX 3.*)
Alternatively to direct entering the path you can click on the folder symbol and
search the directory tree of your computer for the DLL file.
DLL-libraries made from Fortran sources in general follow C/C++ calling
conventions. Note, nevertheless that scalars are normally passed by reference to
Fortran routines. Use data fields of size one in these cases. Also, note that contrary
to C/C++, Fortran stores data fields in column major mode. That means, that if you
call a Fortran function via the C-interface all data fields are transposed in the
Fortran routine.
8-42 SimulationX 3
TypeDesigner
At Function Call you give the name of the external function followed by the coma
separated argument list in parenthesis. Additionally you can use the size
operator.
size(Array, n)returns the size of the n-th dimension of Array
Please, regard also the hints in the next section.
Attention: A wrong argument list can cause an abnormal termination of

SimulationX.
Data formats of the external function arguments

A scalar output can be specified as the return value of the external function.
Example in C: double times_two(double x)
Put the corresponding output variable separated by an equality sign in front of the
function name in the Function Call field of the Function Property dialog.
Example: y = times_two(x)
Alternatively, you can use output variables in the argument list of the external
function. In this case SimulationX passes pointers to data fields (in C: double*
or int*) where the external function saves its results.
Example: In the following header of a C-function a field is assigned to the

output y.
void mat_mul(int n, int m, double *y, double* A,
double* x)
In the Function Call field you insert the output at the corresponding position of the
argument list:
Example: mat_mul(size(A,1),size(A,2),y,A,x)
Scalar input variables are passed as scalars to the external function (e.g. in C:
double and int for the data types Real and Integer, resp.). For input
variables having a data field as value a pointer of this field is passed to the external
function (in C: double* or int*).
Usage of functions in the behavioral descriptions of types

In the algorithm section you use a function at the right hand side of an assignment.
The left and the right hand side of assignments are separated by the symbol ":=".
In the equation section you use a function at the right hand side of an equation
where left and right hand side are separated by "=".
SimulationX 3 8-43
If the function has just a single output value, then the output variable stands at the
left side.
Example: y = f(a1,a2);
For a function with more than one output at the left hand side the outputs are listed
in a coma separated list in parenthesis.
Example: (y1,y2) = f(a1,a2);
The function name followed by a coma separated list of inputs enclosed in
parenthesis stands on the right hand side.
There are two ways to specify the function arguments: per name and per order.
Each argument by name is given as a sequence of the name of the function input,
an equality sign "=" and the value to be assigned to the input.
Example: f(a1=x1, a2=1.0)
If you write the arguments in exactly the same order as in the component table of
the function then you can leave out the input names and the equality signs. This is
meant by passing arguments by order.
Example: y = f(x1,1.0)
You can also combine arguments by order with arguments by name. In this case
you must first specify the arguments per order and then the arguments by name.
Example: y = f(x1, a2 = 1.0)
8.2.7 Simulation Specific Functions

Following functions can be used for the behavior description. Some functions are
only in SimulationX available (marked with *) and not part of Modelica language.
abs(x) Is replaced by (if x>=0 then x else x). Outside of
noEvent (...) or the when-statement state events are
triggered.
analysisType()* Returns a string with a description of the context, in

which the model is evaluated.
available values are:
dynamic transient simulation
linear linear system analysis
static computation of the equilibrium state
stationary Steady State simulation (in the
frequency domain)
8-44 SimulationX 3
TypeDesigner
analysisTypeDetail()* Returns a string, describing the context in further

details, in which the model is evaluated.
Available vales are:
residuals computation of the residuals at the
current point of time
residualsChangeStates computation of
the residuals using slightly
changed values of states and/or
current simulation time
residualsIntegral computation of the
residuals with changed values of
the states for integral equations
jacobian computation of the Jacobian matrix
event an event step (discrete variables can
change their value )
animation during animation
acceptStates during the execution of the
accept algorithm
others otherwise
analysisTypeDepend()* Permits to introduce additional dependencies into
an equation, in order to enable the solver to leave
an otherwise singular range.
assert(condition, Assertion that the condition is true. If not, the string

string) is given as error message and the simulation is
terminated (error). It can be avoided using the trace
flags.
cardinality( A ) Returns the number of connectors which are

connected with connector A. Returns 0 if A is not
connected.
change(x) Is replaced by (x <> pre(x)). Returns true, if the

value of the variable changes. The argument needs
to be a discrete variable.
ceil(x) Returns the smallest integer not less than x.

The argument needs to be a discrete expression.
der(x) Returns the time derivative of variable x. (= dx/dt)
der(y,x)* Returns the x derivative of variable y. (= dy/dx)
SimulationX 3 8-45
delay(expr, dt Returns the value of expr delayed by dt. As long as

[,dtmax]) time < dt it returns the start value.
dtmax must be a constant and 0 <= dt <= dtmax.
If dtmax is not given dt must be constant.
div(x,y) Returns the algebraic quotient x/y with any

fractional part discarded (also known as truncation
to zero).The arguments need to be discrete
expressions.
dontSolveFor(expr)* Prevents a rearrangement of an equation towards a

variable contained in expr.
edge(b) Is replaced by (b and not pre(b)) for the Boolean

variable b. Returns true, if the value of the
variable changes from false to true. The
argument needs to be a discrete variable.
floor(x) Returns the largest integer not greater than x as a

real value.
forCodeGen()* Yields true, if a symbolic analysis for the

generation of code is running
*
impact(state) Returns a value 0, if the state state had an
impulse. The sign indicates the direction of the
impulse. Can be used only in a special algorithm
section (accept algorithm)
inAnimation()* Supplies true during animation.
integer(x), int(x) Returns the largest integer not greater than x as an

integer value.
integral(x,z0)* Returns the integral of variable x ( = xdt + z ). z0 is

0
the initial value of the integral. It is used only once.
integral(y,x,z0)* Returns the time integral of the variable y over x

= ydx + z . z0 is the initial value of the integral. It
0
is used only once.
8-46 SimulationX 3
TypeDesigner
initial() Returns true at the beginning of the simulation.
isConstant(expr)* Supplies true, if the passed expression is constant.
message()* See the description of terminate

noEvent(expr) The expression is evaluated literally. Relations
within it do not trigger state events (no
discontinuities).
language(lang, Returns a string, if lang corresponds to the

string)* appointed language, otherwise an empty string.
Possible values for lang are:
'de' for German or 'en' for English.
Thus language dependent messages can be
produced.
last(x)* Returns the value of the variable x from the last
valid integration step. During event iteration last(x)
remains constant.
objectIdent()* Supplies the designator of the object, to which the

equation belongs (for messages).
pre(x) During the event iteration at discontinuities the
operator returns the value of the discrete variable x
from the last iteration step. Outside of the event
iteration x = = pre(x) holds. The argument needs to
be a discrete variable.
reinit(x, expr) Reinitializes the state variable x with expr at event

instants. The der(x) operator needs to be applied to
x.
rem(x,y) Returns the integer remainder of x/y, such that:

x = div (x,y)*y + rem (x,y).
The arguments need to be discrete expressions.
sample(Start, Produces time events at time instants

Interval) Start + Intervali . At these time instants the
i
function returns true, else false. The value

Start is only evaluated once. Start >= 0 and Interval
> 0 is required.
SimulationX 3 8-47
sign(x) Is replaced by (if x > 0 then 1 else if x < 0 then 1

else 0).
Outside of noEvent(...) or the when-statement state
events are triggered.
smooth(n, expr) If n >= 0 returns the expression and states that it is

n times continuously differentiable. If expression
triggers event iterations, the necessary effort can be
reduced.
setImpact(state)* Release an impulse on the State state, e.g. by end

stop.
terminate The string is written to the output area and the
(string) simulation is finished successfully.
trace( )* see below

warning()* see below
Trace Function
The trace function generates messages in the output-area for supporting the error
search.
The representation in the output-area consists of a short (always present) and a
long character string (only present if you have clicked on the '+' before the
message).
The trace function can be called with a variable number of parameters.
Function call Output (short) Output (long) Comment
trace("test") test test simple string
trace("test",t) test 0.23 additional
argument
trace("time:%1,dt: time:0.23,dt:0.01 time:0.23,dt:0.01 format
%2",t,dt) specification in
the first argument
trace("time:%1\ndt time:0.23 dt:0.01 long and short
:%2",t,dt) output different
trace("time+dt=%1" time+dt=0.24 time+dt=0.24 expression as
,t+dt) argument
The first argument is a format specification. It can contain place holder of the form
'%n', where n refers to the n-th further argument.
8-48 SimulationX 3
FluidDesigner
The separation between short and long character string takes place via first '\n' in
the format specification.
The further arguments can be arbitrary expressions, whose current value is filled
into the indicated place holder.
The return value of the function is always 1. Thus it can be called also in
parameters.
To get the output in the output area, the trace-flag (menu Simulation/Settings, page
Tracing, Modelica/trace-function) has to be turned on and the global parameter
traceOn has to yield true.
The functions 'message' and 'warning' work similarly. They also show messages
and/or warnings in the output area. However, the global settings to release the
trace-function have no influence on them.
8.3 FluidDesigner
The FluidDesigner can be used to create user-defined Fluid Types for the libraries
Hydraulics and Pneumatics.
The toolbar below the FluidDesigner is available for all pages and has following
functions:
go to the next site
go to the previous site
create the fluid and finish the FluidDesigner
cancel the work
switch on the Online-Help
8.3.1 FluidDesigner Hydraulics

A Fluid Type describes all physical properties of a hydraulic fluid (e.g. viscosity,
density, compressibility etc.), which are relevant for the simulation, depending on
the hydraulic state variables pressure, temperature, and gas fraction.
In addition to the internally predefined Fluid Types in the library 'Hydraulics' you
can create your own Fluid Types. The new Fluid Types are displayed in the dialog
of the hydraulic connection and can be used for the simulation.
The FluidDesigner is started via:

the menu Extras Options Fluids by pushing the Add button :
SimulationX 3 8-49
Figure 8.35: Menu Extras/Options fluid selection
or by the properties dialog of the hydraulic connection:
Figure 8.36: Connections properties dialog
With selecting New Fluid (see Figure 8.36) the FluidDesigner starts.
If you wish to edit or modify a user-defined Fluid Type select this type in the menu
Options Fluids and proceed with the Edit button.
8.3.1.1 General
At this page you can define the name of the new Fluid Type, add a comment, select
a classification (see Figure 8.37) and change the security settings.
The classification provides suitable default values for the fluid properties on the
following pages. For fire-resistant fluids and environmentally-safe fluids, a
sub-classification should be selected as well.
8-50 SimulationX 3
FluidDesigner
When activating the security settings, the Fluid Type will be encrypted. That
means, for reading the fluid properties SimulationX and the FluidDesigner are
needed. With giving passwords for usage and editing, misuse of the user-defined
fluid data can be prevented. For further information please note the security
settings of the TypeDesigner in section 8.2.2.11.
The new Fluid Type will be saved by default in the directory 'My Fluids/
Hydraulics'. The user can change the directory by the menu Extras Options
in the register card Directories. All Fluid Types, which are located in this
directory, will be loaded automatically upon program start. After editing an
existing Fluid Type, a backup copy of the previous Fluid Type is stored in the
directory. The copy gets a counter behind the Filename Extension '.mo'.
Figure 8.37: General settings
On the following dialog pages, the physical properties of the fluid must be defined.
It should be noticed, that
- For defining the pressure dependency of any physical property, the absolute
pressure should be used, which is calculated in each hydraulic connection. The
variable p in the FluidDesigner does always refer to the absolute pressure (of
the hydraulic connection).
- By means of the FluidDesigner, only the physical properties of pure liquid
should be defined, i.e. without considering cavitation or any gas fraction. The
SimulationX 3 8-51
effect of cavitation and gas fraction (air release) is still considered in each
hydraulic connection, by assuming the fluid as a mixture of liquid, vapor and
gas (air). For that purpose, the user defines such properties as vapor pressure or
Bunsen coefficient in the FluidDesigner (pages Aeration and Vapor
Pressure).
- By setting the fluid properties with user-defined functions and curves, please
regard, that some properties depend on each other, that are the bulk modulus,
the compression coefficient, the density, the heat expansion and the specific
heat. Furthermore cavitation and gas fraction influence the compressibility and
every depending property. By giving imprecise functions or curves for density
and compressibility, the mass balance cannot be fulfilled.
8.3.1.2 Viscosity
By this page you specify the kinematic viscosity of the pure liquid (without
aeration and cavitation). You can select between 4 options for the definition of the
viscosity:
ISO 3448 Viscosity Class
Default setup function with coefficients
Arbitrary setup function
Viscosity-temperature/viscosity-pressure data table (Figure 8.38).
Figure 8.38: Site Viscosity with Viscosity-Temperature Characteristic
Editing and/or creating of characteristics is possible by pushing the button

.
The work with characteristics (data tables) is described in section 5.4.3.
8-52 SimulationX 3
FluidDesigner
The two data tables T (T ) and p ( p ) define the viscosity-temperature behavior (at
the pressure pRef ) and the viscosity-pressure behavior (at the temperature TRef ),
respectively. From these two data tables, a 2D data array ( p, T ) is built-up
internally, by using the following formula:
1
( p, T ) = (T ) p ( p ) (8.1)
T (TRef ) T
The above formula is based on the assumption, that both data tables give the same
value for the viscosity at the reference point ( pRef , TRef ) :
T (TRef ) = p ( pRef ) (8.2)
If this condition is violated, a warning message appears upon closing the

FluidDesigner:
8.3.1.3 Density
This page specifies the density of the pure liquid (without aeration and cavitation).
Following approaches are available:
default setup function
arbitrary setup function
density-temperature/density-pressure data table
By setting the fluid properties with user-defined functions and curves, please
regard that the compressibility and density depend on each other. By giving
imprecise functions or curves, the mass balance cannot be fulfilled.
When giving a function or curve for the compressibility, it is recommended to
define the density with the default setup function. The resulting density (which
shows then the influences of aeration and cavitation) can be compared with the
given values and eventually be adjusted.
8.3.1.4 Compressibility
This page defines the compressibility of the pure liquid (without aeration and
cavitation). You can select between the following approaches:
constant compressibility
SimulationX 3 8-53

compressibility-pressure/compressibility-temperature data table
8.3.1.5 Heat Expansion

This page specifies the heat expansion of the pure liquid (without aeration and
cavitation). The following approaches are available:
constant heat expansion
setup function
heat expansion-pressure/heat expansion-temperature data table
8.3.1.6 Specific Heat

This page defines the specific heat of the pure liquid (without aeration and
cavitation) with the following approaches:
constant specific heat
setup function
specific heat-pressure/specific heat-temperature data table
8.3.1.7 Thermal Conductivity

This page specifies the thermal conductivity of the pure liquid (without aeration
and cavitation). Following approaches are available:
constant thermal conductivity
setup function
thermal conductivity-pressure/thermal conductivity-temperature data table
8.3.1.8 Aeration
By this page you can specify the aeration behavior of the pure liquid as well as the
gas properties. You can use default settings or input individual values.
8.3.1.9 Vapor Pressure

This page specifies the vapor pressure of the pure liquid. You can select between
following approaches:
vapor pressure data table
8.3.1.10 Limits
By this page you can specify the maximum and minimum values for pressure and
temperature. You can select between default and arbitrary values.
8-54 SimulationX 3
FluidDesigner
8.3.2 FluidDesigner Pneumatics Gases

The start of the FluidDesigner is analog to 8.3.1.
8.3.2.1 General
By this page you name the created gas and add a comment (see also 8.3.1.1).
By default, the created Fluid Type will be saved in the directory 'My
Fluids/Pneumatics'.
The user can change the directory by the menu Extras Options in the register
card Directories.
Figure 8.39: FluidDesigner for Gases
8.3.2.2 Viscosity
This page specifies the dynamic viscosity of the gas. Following approaches are
available:
constant viscosity
Sutherland's Law
viscosity-pressure/viscosity-temperature data table.
8.3.2.3 Caloric Properties

This page specifies the caloric property of the gas. Considerations of the specific
gas constant or the molecular weight and different approaches for the specific heat
capacity are done.
8.3.2.4 Thermal Conductivity

This page defines the thermal conductivity of the gas. You can select between
following approaches:
constant thermal conductivity
SimulationX 3 8-55

data table over T.
8.3.2.5 Specific Enthalpy

By this page you can specify the specific enthalpy of the gas with following
approaches:
data table over T.
8.3.2.6 Real Gas

This page specifies the properties, which are required for the real-gas models.
8.3.2.7 Limits
This page defines the upper and the lower bound of the pressure and the
temperature.
8.3.3 FluidDesigner Mixtures

You can create and use mixtures of all available gases. The general settings of the
mixture are analog to 8.3.2.1. By the page 'Mixture composition' you can define the
default mass fraction of the individual components. See also Library manuals/
Pneumatics for more information.
8.4 Statechart Designer

8.4.1 Introduction
Control units in automation equipment are the link between operators and plant
(e.g. printing machine, automatic gearbox in cars, home automation). The operator
in the control center is giving commands which are transferred into control signals
by the control unit. The plant in turn sends data which characterize dedicated
sequences of actions. The control unit is organizing these sequences in a state
machine which is analyzing operator commands as well as plant data (sensor data).
Furthermore the control unit is providing status information for the operator.
Operator commands are given in irregular (sporadic) intervals. The plant sends
data cyclic and/or acyclic to the control unit. In respect of information technology
the user commands can be interpreted as messages with various arguments. Plant
data are usually scalars. In the state machine introduced in this document the
information transfer will be differentiated into signal events and change events.
Time events will be used for organizing chronological sequences which are
generated by the state machine itself.
8-56 SimulationX 3
Statechart Designer
Control centre Control unit Plant
Run /
commands Stop control signals
Halt / Halt /
x < LimitLeft /
GoLeft GoRight
status x > LimitRight / sensor data
State machine
Figure 8.40: Function of a state machine in automation engineering
8.4.2 Graphical Notation of State Machines

The graphical representation of the state machine and its semantic interpretation
follow definitions given in the UML 2.0 Superstructure Specification [6].
Basic components of state diagrams are states and transitions between these states.
A sequence of transitions starts at an initial state with an initial transition to the
target state. Figure 8.41 shows the basic components and their relations.
Initial State
Initial Transition
Transition
State
Transition
State
Figure 8.41: Components of the graphical notation of state machines
8.4.2.1 States
A state represents a situation in which an invariant condition is valid. This
invariance can be either static (e.g. waiting for an event) or dynamic (e.g.
executing an activity).
SimulationX 3 8-57
The following types of states are differentiated:

simple state,
composite state,
submachine state.
Simple states are not subdivided in terms of hierarchy, i.e. they do not contain
further states. Composite states contain one or more regions. These regions consist
of states and transitions and represent parallel control operations. Submachine
states include complete substate machines in the state machine. Submachine states
are semantically identical to composite states.
However, submachine states will not be examined in this document furthermore.

The subdivision of composite states will be limited to a single region.
States can be either active or inactive. All composite states that contain an active
state in a direct or indirect manner are also active.
The graphical representation of a state will be subdivided by horizontal lines into

the following compartments:
name compartment with the states name
internal activities compartment with internal activities
internal transitions compartment with internal transitions.
State Name
entry / Activity
exit / Activity
Figure 8.42: State with name and internal activities
In case a state is active then the internal activities will be executed. Their behavior
is specified by the keywords entry and exit.
An entry activity is executed once after the state was entered and became active
respectively. The exit activity is executed when the state becomes inactive and has
been exited.
8.4.2.2 Transitions
A transition is a passage from one state to another which is associated with these
conditions:
the transitions source state is active
a trigger initiates the state change
a logical condition called guard is true.
8-58 SimulationX 3
Statechart Designer
An optional activity can be associated with the transition. This activity is without
duration and not interruptible and will be executed when the transition is taken.
Passing a transition does not consume time, i.e. is transient and without duration.
An implicit completion-trigger will be associated with the transition as long as
there is no explicit trigger associated with it.
Figure 8.43: Different kinds of transitions
The following triggers will be explained:

signal-trigger
change-trigger
time-trigger
completion-trigger.
Signal-triggers are activated when a predefined signal is received.
Change-triggers are activated when the corresponding Boolean relation of system

variables is evaluated to TRUE.
Time-triggers are activated after a predefined time has elapsed.
Completion-triggers are implicit triggers. They are activated when states have
completed their activities.
8.4.2.3 Pseudostates
Pseudostates are transient states with no duration. They are used to define an initial
state as well as more complex transitions. Figure 8.44 shows pseudostates used in
respect of industrial controls.
The initial pseudostate is used in two different ways:

As entry point to the state machine:
From the initial pseudostate the initial transition goes to the starting state of
the state machine. Initial transitions have no trigger or guard but can perform
an activity.
As default entry to a composite state.
See section 8.4.2.8. for more information
Junction pseudostates are junctures splitting one incoming transition into multiple
outgoing transitions (split)
or merging multiple incoming transitions into one outgoing transition (merge).
SimulationX 3 8-59
Initial State
/ Activity
Junction
Split
Trigger
[ Guard ] / Activity
[ else ] / Activity
Merge

Trigger
Figure 8.44: Pseudostates
8.4.2.4 Trigger
Signal-Trigger
A signal-trigger initiates a transition in case an expected signal event occurs. This

signal event is an asynchronous event such as the reception of a message. The term
"asynchronous" implies that the subsystem which generates the signal event
continues working immediately after sending the signal without waiting for the
receivers response.
Along with the signal event goes the assignment of arguments to corresponding
attributes or variables of the state machine. These arguments can be transmitted
optionally.
Signal-triggers are noted with the name of the causing event and an enumeration of
arguments:
signal-trigger ::= event-name [ ( attribute-list ) ]

attribute-list ::= attribute-name : type-name [ , attribute-name : type-name ]*
8-60 SimulationX 3
Statechart Designer
The assignment of arguments to attributes or variables of the state machine is

carried out only if the corresponding transition really fires (see 8.4.2.5).
In the Statechart-Designer the above mentioned attribute-list is currently restricted

to a logic (Boolean) expression which describes the condition of the occurring
event and can only evaluate to true or false. This means a signal-trigger has
the form
event-name (Boolean expression) for example: signal1 (in1>0.5)
A transition which is parameterized with a signal-trigger is firing, if and only if its

predecessor state is active, its successor state is inactive, the guard-condition is
true and the Boolean expression for the signal is changing from false to true, i.e.
it has a positive edge.
Change-Trigger
A change-trigger initiates a transition as result of a change event. This event is

generated in case a corresponding Boolean expression is evaluated to TRUE. The
expression might include input variables, internal variables, parameters and
constants.
Notation:
change-trigger ::= boolean-expression
In reference to industrial controls the following definitions are valid:

the Boolean expression is evaluated continually
the change event is set up as soon as the Boolean expression is TRUE for the
first time and exists as long as the expression continues to be TRUE.
Time-Trigger
A time-trigger initiates a transition as result of a time event. This event is

generated after a defined period of time has elapsed. The length of this period is
specified with the time-trigger.
Notation:
time-trigger ::= after ( time-expression )
The time expression is a period of time which starts when the transitions source
state has been entered. After this period has elapsed a time event will be generated
as long as the source state is still active.
SimulationX 3 8-61
The essential difference to the signal-trigger is that no event-name is defined. The

Boolean expression is directly denoted in the transition.
A transition with the change-trigger fires if and only if the predecessor state is
active, the successor state is inactive, the guard condition is fulfilled and the
Boolean condition of the change-trigger evaluates to true. In opposite to the
signal-trigger no positive edge is necessary.
Completion-Trigger
An implicit completion-trigger is assigned to transitions without trigger. This

trigger is firing when a completion event is detected.
The completion event is generated after all entry activities of the source state are
finished. In case the source has no entry activity, the completion-event will be
generated immediately after activation of this state.
If multiple outgoing transitions of a state have no triggers then these transitions

have to be separated be mutually exclusive guards.
8.4.2.5 Guards
A guard is an additional Boolean condition for firing a transition and will be
evaluated when the transitions trigger event is generated. As long as the guard is
evaluated to FALSE the transition will not fire and the trigger event will be
deleted. Special to change-triggers
is that their trigger events exist as long as the corresponding Boolean expressions
are TRUE.
Notation:
guard ::= [ boolean-expression ]
The Boolean expression contains attributes or variables, respectively, of the state

machine and where necessary arguments of the trigger event. These arguments are
only assigned to the state machine attributes when the transition is actually firing.
As stated before an implicit completion-trigger is assigned to transitions without

trigger.
8.4.2.6 Priorities
As soon as multiple outgoing transitions of a state may fire simultaneously a
decision must be made which of these transitions is allowed to fire. Therefore, each
transition will be given a number (1, 2, 3, etc.) according to its priority. If there are
some identical priority numbers, a decision is made at random for these transitions.
8-62 SimulationX 3
Statechart Designer
1 1
2
Figure 8.45: Priorities of transitions
The priority number is written at the transition close to the source state.
The assignment of priorities for firing transitions is an addition to the UML

standard. This standard is limited to a random choice made according to the
sequence of the graphical notation of the transitions.
8.4.2.7 Self-Transitions und internal Transitions

Self-transitions are transitions where source and target state are identical.
In case the transition is firing the sequence of activities will be as follows:

exit activity of the state,
transition activity,
entry activity of the state.
State Name
entry / Activity
exit / Activity Trigger [ Guard ] / Activity
Figure 8.46: Self-transition
A time-trigger belonging to the states outgoing transition will restart its internal
clock every time the self-transition is firing and hence the state is exited and re-
entered.
Internal transitions are listed within a state with trigger, guard, and activity.
Guards are optional. Internal transitions are executed as long as the state is active
and all conditions are complied. Contrary to self-transitions the firing of internal
transitions does not execute entry and exit activities of the state. The transitions
SimulationX 3 8-63
may use an identical trigger event while a guard specifies which transition will
fire. Parameters contained in the trigger event can be evaluated in the transition
activity.
Internal transitions are in relation to external transitions, including self-transitions,

of lower priority. That implies, if an external and an internal transition are
executable simultaneously then the external transition has priority to fire. The
conditions of the internal transitions will be evaluated in the sequence of their
notation top to bottom.
State Name
entry / Activity
exit / Activity
Trigger [ Guard ] / Activity
Figure 8.47: Internal transition
8.4.2.8 Composite States

Composite states differ from simple states by the existence of an additional
decomposition compartment.
The composite state may contain the following compartments (cf. Figure 8.48):
name compartment with the states name
internal activities compartment with internal activities
internal transitions compartment with internal transitions
decomposition compartment with substates.
The decomposition compartment contains one or more orthogonal regions

comprising each an amount of states, pseudostates, and transitions.
Within the defined subset a decomposition compartment is limited to a single

region. The composite state is therefore non-orthogonal.
All hitherto described states can be applied to the decomposition compartment. A

substate may be a composite state as well.
Internal transitions of the composite state are also valid for all substates. When
such a transition is triggered it will be executed within the active substate without
leaving the substate. Transitions of a hierarchically lower substate are of higher
priority than the transitions of the superstate (lower-first priority).
8-64 SimulationX 3
Statechart Designer
State Name
entry / Activity
exit / Activity
Trigger [ Guard ] / Activity
Figure 8.48: Composite state
When entering a non-orthogonal composite state the following cases can be

distinguished (see Figure 8.49):
Default entry: The incoming transition ends on the composite states outer
boundary. The initial transition outgoing from the initial state activates the
target state. An activity can be assigned to the initial transition but no trigger
or guard. The composite states entry activity will be executed before the
initial transitions transition activity.
Explicit entry: The incoming transition points to a substate of the composite
state. This substate will be activated and its entry activity is executed after the
composite states entry activity.
Shallow history entry: The incoming transition points to a shallow history
pseudostate (shallow history). The last active substate of the composite state
will be reactivated. In case the composite state is entered for the first time the
default history state will be entered. The default history state is the substate
which is the target of the single transition emanating from the history
pseudostate. The composite states entry activity is executed before the
reactivated substates entry activity.
Default Entry Explicit Entry Shallow History Entry
Default History State
Figure 8.49: Entry options into composite states
SimulationX 3 8-65
Exiting a non-orthogonal composite state is done either by triggering a high-level

transition originating from the outer boundary of the composite state or by
triggering a low-level transition directed from a substate to an exterior state (cf.
Figure 8.50). The exit is carried out recursively starting with the innermost active
state. While exiting the exit activities of the states are executed in ascending
hierarchical order.
Exit via High-Level-Transition

T1 [ G1 ] / A1
Exit via Low-Level-Transition

T2 [ G2 ] / A2
Figure 8.50: Exit options from composite states
According to UML-definitions low-level transitions possess a higher priority than

high-level transitions.
In an active configuration as shown in Figure 8.51 low-level transitions t1, t2, t3

and t4 are of higher priority than high-level transition t0.
In case a transition tj (t1, t4) and transition t0 could fire by signal-triggers T0,
T1, T4 at the same point then tj will fire. Trigger T0 will have no effect.
1 T0 /
T1 / 1 t4
t0
T4 /
t1
2
1 T2 /
T5 / 1
t2
1
t3 T3 /
Figure 8.51: Active configuration (state A, state A2) with signal-trigger T0

of high-level transition t0
8-66 SimulationX 3
Statechart Designer
To initiate emergency functionality via a high-level transition an additional

definition has to be made:
Assignment of priority number 0 to a high-level transition raises this transition to
the highest-priority transition of the composite state and all its substates.
The highest-priority transition (cf. Figure 8.52) is firing as soon as the

corresponding trigger is activated and immediately deactivates the active substate
as well as the composite state itself.
Highest Priority
0 T0 /
T1 / 1 t4
t0
T4 /
t1
2
1 T2 /
T5 / 1
t2
1
t3 T3 /
Figure 8.52: Definition of high-level transition t0 as highest-priority
Restrictions of this subset in relation to the UML standard

no self-transitions to composite states
no entry point pseudostate, no exit point pseudostate
no termination pseudostate
no final state
no deep history entry.
8.4.3 Statechart Designer of SimulationX

The Statechart Designer is part of the TypeDesigner and allows specific behavior
instructions. It can be used to model time and state discrete control algorithms in
SimulationX. The design of the models is graphical, based on the UML-statecharts.
The integrated Statechart compiler translates the statecharts automatically into

Modelica code. Furthermore the states can be visualized dynamically in
SimulationX
SimulationX 3 8-67
8.4.3.1 Start and Interface

The Statechart Designer is started on the behavior page of the TypeDesigner via
the selection box item State Chart.
Modeling
View
Properties
Manager
Model Explorer
and/or Signal
Event Definition
Figure 8.53: Statechart Worksheet
To facilitate the modeling process the interface is divided in 3 parts. The modeling
view is the central part in which the statecharts are created. Beside this the
properties manager displays the corresponding properties of the selected element.
The Model-Explorer or Signal-Event-Definition table respectively is located just

below. The Model-Explorer displays the hierarchic tree structure of the model.
8.4.3.2 Modeling
The selection of the notation element is done via the symbol panel. Once selected,
the element (e.g. state) can be drawn on the modeling view using the mouse.
8-68 SimulationX 3
Statechart Designer
Statechart scaling
Self-Transition inserting
Transition inserting
ShallowHistory inserting
Junction inserting
Initial State inserting
State inserting
Chart Export/Import
The Property Manager allows modifying the

property details and the aspect, e.g. size, color of
the selected element. The displayed context
sensitive properties are always related to the
selected item. The Modelica-code-snippets to
define e.g. the entry-action can be entered
directly; longer code can be entered in the
window that opens by a click on the button .
This button becomes visible by clicking the
corresponding lines. The entered Modelica-code
is automatically checked being correct; otherwise
an error message is displayed.
All notation elements can also be edited via a context-

menu.
SimulationX 3 8-69
During the modeling process certain design-rules are automatically checked to

ensure UML-compatibility of the statechart.
The handling description of the supported UML notation elements is as follows:
Insert a State
By clicking into the diagram view of the statechart-designer a state with a given
standard size can be created. A state can also be created by drawing a rectangle
with the pressed left mouse button.
Insert a Transition
Beginning in the start state a transition can be pulled towards the target state using
the pushed left mouse button.
A transition is figured by a directed, generally labeled arrow.
The label of a transition can contain the following elements:

Trigger
Guard ; see section 8.4.2.5
Activity ; see section 8.4.2.4
Priority ; see section 8.4.2.6
All described items of a transition can be specified in the Property Manager. The
label can be moved and resized at will by the simple use of the mouse. Accessorily
the anchoring of the label on the transition may be defined via Label Anchor in the
Property Manager.
8-70 SimulationX 3
Statechart Designer
By clicking on any part of the transition a new marker point is created, which can
be used to change the course of the transition. To remove a marker point, use the
context menu that opens by a right-click on it.
Creation of Self-Transitions
A self-transition is automatically created when pulling the left-pressed mouse out
of the state.
SimulationX 3 8-71
Trigger
The following triggers are explicitly supported in the Statechart Designer:
SignalTrigger:
ChangeTrigger:
TimeTrigger:
The trigger of a selected transition can be specified via the Property Manager. The
trigger type is defined in the selection box Type. The sense of the code in the
Expression-box depends on the trigger type. When a SignalTrigger is selected
automatically a default-SignalEvent is created, if not already present. (see section
Definition of Signal Events).
Creation of Pseudostates
Pseudo-states that cant be resized are created by a click on the Modeling View. In
the following some indications concerning the Pseudo-states:
The transition beginning in the InitialState has neither trigger nor condition.
Each InitialState mustnt have more than one outgoing transition.
There is only one trigger per Compound Transition.
Using History-States allows in a composite-state to determine dynamically
which state becomes active first at the activation of the composite-state.
All states are admitted as sub-states of a composite-state.
Definition of Signal Events

To use the signal-trigger it is essential that a corresponding signal-event name is
defined. If in a transition a signal name is used that has been unknown so far it is
defined automatically but the corresponding Boolean expression still needs to be
defined in the Signal-Event-Definition. This view can be activated in the
Statechart-Designer worksheet in place of the Model Explorer. In the Signal-Event-
Definition all signal-events which have already been defined are listed in a table
and it is possible to add and remove signal event definitions as well as to edit their
Boolean expressions.
8-72 SimulationX 3
Statechart Designer
On the click on the plus-button a window opens to define the SignalEvent. It is

also possible to enter code directly in the table. All inputs are automatically
validity-tested.
Event name: Name of the event displayed in the label of the transition (runE).
Event: Boolean expression (e.g. run > 0)
By a click on the minus-button a selected signal-event is erased. The event is

selected via clicking on the cell of the table-frame in front of the event name.
Model Explorer
The Model Explorer displays all used transitions and states of the model (including
pseudo-states), as well as their hierarchic structure and facilitates thus the
navigation in complex models. As a state is selected in the Model Explorer the
model is moved, where required, to display the corresponding state in the
Modeling View. Vice-versa a state is automatically highlighted in the Model
Explorer when selected in the Modeling View.
Zoom
To improve clearness of complex models the Zoom function allows
to increase or to decrease the displayed part of the model in the Modeling View.
SimulationX 3 8-73
Export and Import of Models

Models designed with the Statechart Designer can be exported into a binary file on
a data medium via export-button ( ) on the toolbar. Thereby the logic
information as well as the graphic information of the statechart is saved.
The saved models can be re-imported into the Statechart Designer. All logic and
graphic information is then automatically restored.
Printing of Models
Models designed with the Statechart Designer can be printed or simply previewed
using the print-button ( ) on the toolbar. Thereby the model-scaling, defined in
the options, is used for printing.
Generation of Modelica Code

On quitting the page Behavior of the TypeDesigner, by e.g. clicking on the
button ( ), the generation of Modelica-code is automatically started.
Thereby the logic information of the created model is analyzed and converted into
Modelica-source code which is integrated in the circumjacent type. Further the
logic and graphic information is saved as annotations in the type to enable the
possibility to display the statechart on the next opening of the SimulationX model.
Statechart Designer Preferences

The options dialog allowing customizing of the StateChart Designer opens by a
click on the button in the toolbar.
8-74 SimulationX 3
Statechart Designer
The options are grouped in the following categories:

General (Print settings)
Editor (Default state settings)
Modelica (Modelica settings for coverage)
8.4.3.3 Animated view of the statechart in SimulationX

SimulationX offers the possibility to display the state transitions during simulation.
The visualization is displayed as a Compound-structure. To this end click on the
corresponding element in the Model and use the button.
Figure 8.54: Animation view of the state chart
For the visualization Modelica graphic primitives with DynamicSelect statement

are used. Thus the visualization is fully compatible to the Modelica language
specification.
The visualization displays the following information:

A simplified statechart diagram
The currently active state (State is red)
The last active state (state with red border)
The last active transition (Transition is red)
SimulationX 3 8-75
Further it is possible to record the animation using the integrated recording tool of
SimulationX. Afterwards the recording can comfortably be replayed.
8.4.4 Semantics of Notational Elements in Modelica-Code

The semantics of the UML-Statechart subset in Modelica code [4] will be defined
by using the example of a linear drive (cf. Figure 8.55) including operator
commands and end stops.
Figure 8.55: Components of the linear drive
The controller program is specified as follows:

start and go left after the Run command was given
move 10 times between the left and right end stop
pause for 3 seconds and continue moving afterwards
stop immediately after the Halt command was given
after stop, on renewed Run command continue with moving into the direction
that was active when the Halt command was given.
Operator commands Run and Halt as well as the position x of the mass are
controller inputs. An output is the voltage to the DC-motor.
8.4.4.1 States
The controllers state machine includes a transient initial state and several states
which require periods of time (cf. Figure 8.56).
The names of the states are corresponding to the activities of the drive: Stop,
GoLeft, GoRight, and Pause. The value assignments to the control signals take
place in the entry activities after entering the states. In general these activities are
basic Modelica algorithms.
The Modelica code encapsulates the entry activities into when-clauses which detect
an entry into the corresponding state. After entering the Stop state the drives
voltage U and the counting variable count are set to zero. In states GoLeft and
GoRight voltage U is set to a predefined value and counting variable count is
incremented. Furthermore, the enumeration variable dir is set according to the
8-76 SimulationX 3
Statechart Designer
current moving direction. These activities are executed once when the state
becomes active.
Initial State
State
Entry Activity
Exit Activity
when ( state == StateT.Stop ) then

U := 0;
count := 0;
elsewhen ( state == StateT.GoLeft ) then
// ...
elsewhen ( state == StateT.GoRight ) then
// ...
elsewhen ( state == StateT.Pause ) then
U := 0;
count := 0;
t_PauseFinished := time + t_Pause;
end when;
Figure 8.56: States and entry activities of the state machine
Exit activities are executed in case the corresponding state is exited.
SimulationX 3 8-77
8.4.4.2 Transitions
A trigger, guard or activity can be optionally assigned to a transition between states
(Figure 8.57). An exception is the initial transition which is not allowed to have
trigger or guard. Modelica coding combines all transitions in an if-clause that will
detect the active state and set the state variable to the subsequent state. The
determination of the subsequent state is done by evaluating each transitions
trigger and guard.
Transition
Trigger
Guard
Activity
if ( pre( state ) == StateT.Stop ) then

// ... state := ...;
elseif ( pre( state ) == StateT.GoLeft ) then
// ... state := ...;
elseif ( pre( state ) == StateT.GoRight ) then
// ... state := ...;
elseif ( pre( state ) == StateT.Pause ) then
// ... state := ...;
end if;
Figure 8.57: Transitions of the state machine
8-78 SimulationX 3
Statechart Designer
8.4.4.3 Signal-Trigger
Signal-triggers will cause state transitions when expected messages arrive. These
messages may contain several arguments or are single commands such as Run or
Halt (Figure 8.58). The reception of a message is signaled by toggling a Boolean
variable. In case of a command the command variable and toggle variable are
identical. To recognize the reception of a message or command the Modelica
function change() is used.
Signal Trigger

if ( change( Run ) ) then
// ...
end if;
if ( change( Halt ) ) then
// ...
end if;
// ...
end if;
Figure 8.58: Signal-trigger of the state machine
SimulationX 3 8-79
Messages or commands can be inputs of the state machine or be generated within

the state machine. In the second case (Figure 8.59) the Boolean variables IsLeft
and IsRight are declared. The position x of the mass is monitored for exceeding
thresholds LimitLeft and LimitRight. Every crossing is signaled by toggling the
variables IsLeft or IsRight.
Boolean IsLeft, IsRight;

Real x, LimitLeft:=-0.4, LimitRight:=0.4;
when ( x < LimitLeft ) then

IsLeft := not IsLeft;
end when;
when ( x > LimitRight ) then

IsRight := not IsRight;
end when;
Figure 8.59: Generation of signal events
8-80 SimulationX 3
Statechart Designer
8.4.4.4 Change-Trigger
Change-triggers are firing state transitions when system variables fulfill predefined
conditions. These conditions are Boolean expressions. The trigger will become
active as soon as the expression is evaluated to TRUE and will stay active as long
as the expression continues to be TRUE. Regarding the linear drive the exceeding
of the left and right threshold are implemented as change-trigger (Figure 8.60).
Change-triggers are represented in Modelica as if-clauses containing the state
charts Boolean expression.
Change Trigger

// ...
state := StateT.Stop;
elseif ( x < LimitLeft ) then
state := StateT.GoRight;
end if;
// ...
end if;
Figure 8.60: Change-trigger of the state machine
SimulationX 3 8-81
8.4.4.5 Time-Trigger
Time-triggers cause state transitions after predefined times have elapsed (Figure
8.61). The time values are associated with after-clauses. They are relative to the
points in time at which the transitions source states are entered.
Time Trigger

// ...
elsewhen ( state == StateT.Pause ) then
U := 0; count := 0;
t_PauseFinished := time + t_Pause; // assign time limit
end when;
when ( time >= t_PauseFinished ) then

timeout := not timeout; // toggle timeout signal
end when;
if ( state == StateT.Stop ) then

//...
elseif ( state == StateT.Pause ) then
// ...
elseif ( change( timeout ) ) then // evaluate timeout signal
end if;
end if;
Figure 8.61: Time-trigger of the state machine
8-82 SimulationX 3
Statechart Designer
Time-triggers are organized in Modelica (Figure 8.61) as follows:

(1) The first when-clause detects if the source state of a timed transition is
entered and assigns the time value to the associated variable.
(2) A second when-clause toggles a timeout-signal as soon as the simulation
time exceeds the time limit.
(3) An if-change-clause detects the change of the timeout signal and assigns
the target state of the timed transition to the state variable.
8.4.4.6 Guards
Guards are additional Boolean expressions used for firing transitions. They are
evaluated only when the associated triggers are triggering. Regarding the linear
drive guards are needed to differentiate the Run command (Figure 8.62).
According to the requirements of the drive the last activity is resumed after a
restart. Therefore, a variable dir is defined which is set anew when the different
motions of the drive are started. Variable dir is evaluated in the Boolean
expressions of the guards which are associated to the transitions outgoing from the
Stop state. In the Modelica coding triggers and guards are related by AND-
operators.
SimulationX 3 8-83
Guard

if ( change( Run ) and ( dir == DirT.Left ) ) then
state := StateT.GoLeft;
elseif ( change( Run ) and ( dir == DirT.Right ) ) then
end if;
// ...
end if;
Figure 8.62: Guards as additional conditions
The condition of the transition from GoRight to Pause can be expressed as change-
trigger (Figure 8.60) or guard (Figure 8.63).
8-84 SimulationX 3
Statechart Designer
Guard
Boolean Complete;
Integer N_Max;
when( ) then
// ...
elsewhen ( state == StateT.GoRight ) then
U:= 10; count := count + 1; dir := DirT.Right;
Complete := not Complete;
end when;

// ...
elseif ( pre( state ) == StateT.GoRight ) then
elseif ( change( Complete ) and ( count > N_Max ) ) then
state := StateT.Pause;
elseif ( x > LimitRight ) then
state := StateT.GoLeft;
end if;
// ...
end if;
Figure 8.63: Relation of guard and completion-trigger
In case a guard is the only condition associated with a transition then this guard
will be related with a completion trigger in Modelica coding. A when-clause
SimulationX 3 8-85
detects the entry into the source state of the transition from GoRight to Pause and
releases the completion event as last operation. This is done by toggling the
Boolean variable Complete.
The transitions if-clause contains the AND-relation of the completion-trigger
change(Complete) and the guard.
8.4.4.7 Priorities
The priority numbers noted at the transitions are determining the sequence for the
test whether transitions can fire or not. In case of the linear drive the Halt
command was given the highest priority in order to safely stop the drive in any
circumstance.
Priority Number

// ...
if ( change( Halt ) ) then // Priority 1
elseif ( x < LimitLeft ) then // Priority 2
end if;
// ...
end if;
Figure 8.64: Priorities at the test of transition conditions
8-86 SimulationX 3
Statechart Designer
8.4.4.8 Transition Activities

Storing the moving direction can be done not only by using entry activities but also
by using transition activities with assigning the enumeration of the stopped motion
to the variable dir. These assignments are part of the if-clause for the determination
of the subsequent state. Commonly, transition activities are basic Modelica
algorithms.
Transition-Activity

// ...
dir := DirT.Left; // Transition-Activity
end if;
// ...
end if;
Figure 8.65: Transitions with activities
SimulationX 3 8-87
8.4.4.9 Composite States

Composite states are used in conjunction with high-level transitions, initial states,
history states, and junctions for modeling hierarchical state machines.
The Modelica representation defines:

independent state variables for the main level (highest hierarchy level) and
each composite state
independent entry activity sections for the main level and each composite state
independent transition sections for the main level and each composite state
entry variable containing the target state while entering the composite state
onto variable containing the target state when exiting the composite state
initial variable defining the state which will become active at default entry
history variable saving the last active state for the history entry
completion-trigger designating the deactivation of the composite state.
The hierarchical state diagram for the linear (Figure 8.66) drive uses a transition
from Stop to Go which is split by a junction and explicitly activates the substates
GoLeft or GoRight within the Go state.
In the Modelica section Transitions of Main (Figure 8.71) this transition from Stop
to Go is resolved in an if-elseif-clause with assigning the target GoLeft or GoRight
to the entry variable entryGoState. The target state on the main level is Go.
Priority number zero is assigned to the high-level transition from Go to Stop. This
transition is thereby upgraded to the highest-priority transition of the composite
state Go.
In the Modelica section Transitions of Go the signal event Halt, which is the
condition for transition from Go to Stop, is evaluated first in any substate. When
evaluation yields a positive result the target state Stop is assigned to the onto
variable ontoState and InActive is assigned to the state variable of Go.
8-88 SimulationX 3
Statechart Designer
Figure 8.66: Hierarchical state diagram containing explicit entries
In Entry Activities of Go (Figure 8.70) the state InActive is detected and hence, the
Boolean variable completeGo is toggled. Modelica section Transitions of Main
recognises this signal event and starts via variable ontoState the transition to the
target state.
This procedure is repeated for each level of hierarchy, i.e. for every composite
state nested within another composite state. Alternatives exist because of the
different entry options:
explicit entry (Figure 8.65)
history entry (Figure 8.72)
default entry (Figure 8.75)
SimulationX 3 8-89
model Controller
input SignalBlocks.InputPin Run[*];

input SignalBlocks.InputPin Halt[*];
input SignalBlocks.InputPin x[*];
output SignalBlocks.OutputPin U[*];
type StateT = enumeration( Stop, Go );

type GoStateT = enumeration( InActive, GoLeft, GoRight, Pause
);
type DirT = enumeration( Left, Right );
StateT state, ontoState;

GoStateT goState, entryGoState, historyGoState, initialGoState;
Boolean completeGo;
Boolean timeout;
Real t_pause_finished;
Figure 8.67: Modelica-coding of the drives controller: declaration
// Initialization
when initial() then
ontoState := StateT.Stop;
goState := GoStateT.InActive;
entryGoState := GoStateT.InActive;
initialGoState := GoStateT.InActive;
historyGoState := GoStateT.InActive;
completeGo := false;
timeout := false;
t_pause_finished := 0;
Limit_Left := -0.4;
Limit_Right := 0.4;
t_pause := 3;
N_max := 10;
dir := DirT.Left;
end;
Figure 8.68: Modelica-coding of the drives controller: initialisation
// Event Generation
when ( time >= t_pause_finished ) then
timeout := not timeout;
end when;
Figure 8.69: Modelica-coding of the drives controller: event generation
8-90 SimulationX 3
Statechart Designer
// Entry Activities of Main

U := 0;
count := 0;
elsewhen ( state == StateT.Go ) then
goState := entryGoState;
end when;
// Entry Activities of Go
when ( goState == GoStateT.GoLeft ) then
U := -10;
count := count + 1;
dir := DirT.Left;
elsewhen ( goState == GoStateT.GoRight ) then
U := +10;
count := count + 1;
dir := DirT.Right;
elsewhen ( goState == GoStateT.Pause ) then
U := 0;
count := 0;
t_pause_finished := time + t_pause;
elsewhen ( goState == GoStateT.InActive ) then
completeGo := not completeGo;
end when;
Figure 8.70: Modelica-coding of the drives controller: entry activities
// Transitions of Main
if ( change( Run ) and ( dir == DirT.Left ) ) then
state := StateT.Go;
entryGoState := GoStateT.GoLeft;
elseif ( change( Run ) and ( dir == DirT.Right ) ) then
state := StateT.Go;
entryGoState := GoStateT.GoRight;
end if;
elseif ( pre( state ) == StateT.Go ) then
if ( change( completeGo ) ) then
state := ontoState;
end if;
end if;
// Transitions of Go
if ( pre( goState ) == GoStateT.GoLeft ) then
goState := GoStateT.GoRight;
end if;
SimulationX 3 8-91
elseif ( pre( goState ) == GoStateT.GoRight ) then

elseif ( count > N_Max ) then
goState := GoStateT.Pause;
elseif ( x > LimitRight ) then
goState := GoStateT.GoLeft;
end if;
elseif ( pre( goState ) == GoStateT.Pause ) then
elseif ( change( Halt ) ) then
t_pause_finished := time;
elseif ( change( timeout ) ) then
goState := GoStateT.GoRight;
end if;
end if;
// Annotations
// ...
end Controller;
Figure 8.71: Modelica-coding of the drives controller: transitions
The re-entry in state Go via a history state (Figure 8.72) is done by the history
variable historyGoState which stores the identifier of the last active substate. The
assignment is carried out in the entry activities of the substates of Go (Figure
8.73).
For activation of Go in the section Transitions of Main the value of the history
variable historyGoState is assigned to the entry variable of Go (Figure 8.73).
When activating the state machine the historyGoState variable is initialised with
value GoLeft for first-time use in state Go.
8-92 SimulationX 3
Statechart Designer
Figure 8.72: Hierarchical state diagram containing a history entry
// Entry Activities of Main

U := 0;
count := 0;
elsewhen ( state == StateT.Go ) then
goState := entryGoState;
end when;
// Entry Activities of Go
when ( goState == GoStateT.GoLeft ) then
U := -10;
count := count + 1;
historyGoState := GoStateT.GoLeft;
elsewhen ( goState == GoStateT.GoRight ) then

U := +10;
count := count + 1;
historyGoState := GoStateT.GoRight;
SimulationX 3 8-93
elsewhen ( goState == GoStateT.Pause ) then

U := 0;
count := 0;
t_pause_finished := time + t_pause;
historyGoState := GoStateT.Pause;
elsewhen ( goState == GoStateT.InActive ) then

completeGo := not completeGo;
end when;
Figure 8.73: Modelica coding of the history functionality: setting the history variable
of Go
// Transitions of Main
if ( change( Run ) ) then
state := StateT.Go;
entryGoState := historyGostate;
end if;
elseif ( pre( state ) == StateT.Go ) then
if ( change( completeGo ) ) then
state := ontoState;
end if;
end if;
...
// Transitions of Go
if ( pre( goState ) == GoStateT.GoLeft ) then
// wie in Bild 3.12-5
end if;
Figure 8.74: Modelica coding of the history functionality: setting the entry variable
of Go
8-94 SimulationX 3
Statechart Designer
Figure 8.75: Hierarchical state diagram containing a default entry
The default entry is defined with an initial pseudostate having an outgoing

transition that points to a state. This state will be activated as soon as the composite
state has been entered. The target state, in this case GoLeft, is assigned to the initial
variable at start-up of the state machine. For the activation of Go in the section
Transitions of Main the value of the initial variable is assigned to the entry variable
of Go (analogue to Figure 8.74). The default entry used in this example will cause
the linear drive to start with moving to the left. Resuming the motion after Halt
will always start to the left as well.
8.4.4.10 Overall structure of Modelica coding

The Modelica code sections discussed in section 8.4.4 will be integrated into the
state machine coding as follows:
SimulationX 3 8-95
model XY
Declaration
Initialization when-initial-clause
Event Generation when-clauses
Entry Activities when-clauses
Transitions if-clauses
end XY
The coding contains:

Declaration type declaration,
I/O signals, internal signals,
state variables,
initial, entry, onto, and history variables of hierarchies,
time variables,
user variables,
parameters
Initialization assignment of initial value to variables,
instructions of the initial transitions
Event Generation generation of signal events according to the signal event
definition table,
generation of timeout events
Entry Activities instructions according to entry activities of the states,
assignment of limits to time variables, and
generation of completion events
for each level of hierarchy
Transitions assignment of the target state,
instructions according to the states exit activities,
instructions according to the transition activities, and
reset of time variables
for each level of hierarchy.
8-96 SimulationX 3
by
Interfaces
Data formats
9 Interfaces
9.1 Data formats
A number of formats are provided in SimulationX for the exchange of data with
other Windows applications by means of data media. A large variety of formats
can be generated and read through the availability of a wide range of options for
text and binary formats. Some elements save a data format to MS-Office
Applications (e. g. curve2D to *.xls) directly.
Please note that not every format is supported at every place in the program where
data is read and/or written.
9.1.1 Text Format

This universal data format is primarily used for the exchange of data with Office
applications.
You can set column and decimal separators as an option (Figure 9.1).
Figure 9.1: Optional Settings for text files
9.1.1.1 Save File

If you want to save data (such as result curves, characteristic curves) in text format,
the first thing you have to do is select the file type text file (*.txt) from the combo
SimulationX 3 9-1
User Manual 9. Interfaces
box in the file dialog box ( ). The Options button is then enabled. Click on this
button to open the dialog box for the text format settings (see Figure 9.1). You can
make the settings for the separators in this dialog box. Select the separator you
want using the radio buttons. What is meant by separator here is the column
separator.
The decimal separator is selected separately for the output of numbers. This
selection is independent of the current country setting of your computer.
If the check box Show dialog before saving chart is checked off, the global
settings are queried before each save, without the Options button having been
activated. If the check box is not marked, the settings for each file to be saved in
text format are valid until a new global setting is made (click on Options in the
file dialog box).
The format CSV (*.csv) is available as an additional text format. If you have
selected this format as the type of file from the combo box, no optional settings can
be made. A comma (,) is given as the column separator and a dot (.) as the decimal
separator.
9.1.1.2 Load File

You will be supported by an assistant to load external data. The number of pages
of the assistant can vary depending on the element that loads the data. This means
that missing pages there have no meaning for that particular element. The import
of text files is demonstrated below, using the Curve element (library Signal
Sources) as an example.
Select the text file (*.txt, *.csv) as the type of file in the file dialog box. All
files of this type are shown. Select the file you want to import and click "Open".
The import wizard is then activated.
Import Text Format Page 1

The first page (see Figure 9.2) lets you select the separators for the present file. In
this connection see also the settings that were made under Save File (cf.
9.1.1.1).
The first line of data to be imported is set in the Start import with field (thus
skipping over possible captions).
The lower area of the first page shows the data as contained in the file. Click on
one or the other option to update the display. Thus you have to know the specific
format of the data to be imported, and you can check in advance on whether or not
the format settings will supply the desired result.
9-2 SimulationX 3
Data formats
Figure 9.2: Import wizard, Text Format page 1
Import Text Format page 2

The data (x-values) on page 2 are shown in the form in which it will be imported
later on.
Figure 9.3: Import wizard, Text Format page2 (example)
To make the selection, enter the column number in the Column field or click on the
buttons next to the input field. The selected column is highlighted in color and
the values are converted and displayed in accordance with the separator setting. In
addition, the description and unit can be selected and displayed (see Figure 9.3). If
necessary, corrections can be made on page 1.
SimulationX 3 9-3
Import - Text format page3

On this page you can select the column which contains the y-values. To make the
selection, enter the column number in the Column field or click on the buttons
next to the input field. The selected column is highlighted in color and the values
are converted and displayed in accordance with the separator setting. With some
elements (e.g. hysteresis) the procedure on page 3 can repeat itself several times.
9.1.2 IEEE-Binary Format

This compact binary format is primarily used for data exchange with signal-
processing programs (such as measured-data recording and processing).
The data is stored in accordance with the IEEE standard. A number of options (see
Figure 9.4) permit adaptation to all defined binary formats.
An x-value and a y-value are saved for every point (each result curve has two
channels).
Figure 9.4: Settings for binary format
9.1.2.1 Save File

If you want to save data (such as result curves) in binary format, the first thing you
have to do is select the file type IEEE binary format (*.bin) from the combo box in
the file dialog box ( ). The Options button is then enabled. Click on this
button to open the dialog box for the binary format settings (see Figure 9.4). All
input for determining the format must be made in this dialog box.
In the Structure section a certain number of bytes can be placed before the data.
This is of particular interest for those programs which expect certain header
information when reading binary data.
In the Data Type section the range of values and the accuracy with which the data
is to be saved are determined.
Finally, the Storage Type determines whether the data is to be saved by channels
(channel-oriented, row-oriented) or by blocks (block-oriented, column-oriented).
If the check box Show dialog before saving chart is checked off, the global
settings are queried before each save, without the Options button having been
9-4 SimulationX 3
Data formats
activated. If the check box is not marked, the settings for each file to be saved in
binary format are valid until a new global setting is made (click on Options in
the file dialog box).
9.1.2.2 Load File

You will be supported by a wizard to load external data. The number of pages of
the assistant can vary depending on the model object that loads the data. This
means that missing pages have no meaning for that particular model object. The
import of binary data is demonstrated below, using the External Function object as
an example.
.. Select the IEEE binary format (*.bin) as the type of file in the file dialog box.
All files of this type are shown. Select the file you want to import and click
Open. The import wizard is then activated.
Import IEEE-Binary Format Page 1
Figure 9.5: Import wizard, page 1
The first page (see Figure 9.5) lets you select the format for the present file. In this
connection see also the settings that were made under Save File (further above).
The lower area of the first page shows the data as it would be imported in ac-
cordance with the setting made. Click on one or the other option to update the
display. Thus you have to know the specific format of the data to be imported, and
you can check in advance on whether or not the format settings will supply the
desired result.
On page 2 you can choose whether the arguments (x-values) for the points are to
be read in from the file.
SimulationX 3 9-5
To make the selection, enter the column number in the Column field or click on the
buttons next to the input field. The selected column is highlighted in color and
the values are displayed in accordance with the format setting (page 1) (see Figure
9.6). If necessary, corrections can be made on page 1.
Figure 9.6: Import wizard, Binary Format page 2 (example)
Figure 9.7: Import wizard, Binary Format page 3
On this page (see Figure 9.7) you can select the column which contains the
y-values. To make the selection, enter the column number in the Column field or
click on the buttons next to the input field. The selected column is highlighted
in color and the values are displayed in accordance with the format setting
(page 1).
9-6 SimulationX 3
Interfaces to MS Office, Data Exchange
9.1.3 ITI-Binary Format (*.rfb) and ITI-ASCII Format (*.rfu)

The ITI custom format supports the data exchange between ITI products. For
example, in the simplest case, this would be the transport of a result curve from
one result window (in computer 1) to another (in computer 2). The advantage of
these formats is that it is not necessary to specify a number of options beforehand.
A disadvantage is the limited circle of exchange partners.
It is a compact data format for fasten data exchange of result curves. There are no
especially settings needed.
9.1.4 XML-Format
It is a universal data format for import and export of data to other applications,
such as Internet applications and word processing.
An import in this format is not supported.
9.1.5 DIAdem-Headerformat
This format permits a storing of result curves in the DIAdem format of the GfS
GmbH Aachen. A <name.dat> file with all process-describing parameters and a
<name.bin> file, which contains the actual function values, are developed. You
find a specification of this format in your DIAdem manual.
9.2 Interfaces to MS Office, Data Exchange
There are Add-Ins for the data exchange with MS Office . In addition to the
installation the appropriate setup files are already put down on hard disk. Over
Start->ITI Software->SimulationX 3.7->Office Add-Ins these can be
implemented then.
This installation must be made by each user separately.

The Add-Ins have an online help, that gives important notes for the use.
9.3 COM Interface

ITI SimulationX provides a COM interface, which enables you to automate
typical, repeatedly occurring tasks. There are different ways to utilize this
interface:
an integrated script editor with macro recording capabilities
Visual Basic for Applications (VBA) as component of MS Office
Applications
Windows Script (VBScript, JScript)
Visual Basic Applications
C/C++ Applications, ...
The examples specified in this section are written in VBScript. Figure 9.8 shows
all classes integrated in ITI SimulationX (in parentheses the types mentioned).
SimulationX 3 9-7
Application
Documents (Document)
SimObjects (SimObject)
Parameters (Parameter)
Results (Result)
Curves (Curve)
Connections (Connection)
Parameters (Parameter)
Results (Result)
NaturalFrequencies (NaturalFrequency)
Deviations (Deviation)
EigenVectorElements (EigenVectorElement)
Energies (Energy)
InputOutputAnalysis*
Inputs (Input)*
Outputs (Output)*
ResultWindows (ResultWindow)
ResultPages (ResultPage)
ResultPanels (ResultPanel)
ResultSeries (ResultSerie)
ResultLines (ResultLine)
ResultTransformations (ResultTransformation)
Figure 9.8: Structure of COM objects in ITI SimulationX
9-8 SimulationX 3
COM Interface
For information on principles and exploitation of COM interfaces please refer to

the technical literature, e.g. at
http://msdn.microsoft.com/en-us/library/ms950396.aspx.
9.3.1 Classes
9.3.1.1 Application
The class Application represents the application frame of ITI SimulationX. It
manages simulation models as documents.
You start the program by creation of an object of class Application.
The property Visible defines the visibility of ITI SimulationX. Initially the main
window is invisible. It appears executing
sim.Visible = true
9.3.1.2 Documents (Document)

The collection class Documents manages all loaded simulation models as objects
of type Document. You can create a new empty model with the statement:
Set doc1 = sim.Documents.Add
An already existing model can be opened with the method Open.
' Open file (by file path name)

Set doc1 = sim.Documents.Open ("c:\user\model.isx")
' Open type (by identifier)

Set doc2 = sim.Documents.Open
("Modelica.Blocks.Examples.PID_Controller")
The return value of both methods is an object of the class Document.
With the class Document, they control the simulation calculation. Using the
following VBScript statements, you start a transient simulation and wait until the
calculation is complete. The property SolutionState informs you about the current
state of the computation.
const simStopped = 16
doc.Reset
doc.Start
While doc.SolutionState <> simStopped
Wend
MsgBox "Ready..."
SimulationX 3 9-9
The method Start has an optional parameter SimCalculationMode that allows the
selection of the simulation method (transient or stationary). With the following
sequence of statements a steady-state simulation is started. Note the differences in
waiting for the completion of the calculation.
const simReady = 2
const SimCalculationModeSteadyState = 2
doc.Reset
doc.Start SimCalculationModeSteadyState
While doc.SolutionState <> simReady
Wend
MsgBox "Ready..."
The new property Documents.Solver gets and sets the solver method. The
following values (depending on the available license options) are supported
simSolverBDF =0
simSolverMEBDF =1
simSolverCVODE =2
simSolverFixedStep =3
The Code Export can be activated by the function Document.ExportSourceCode.

If no function arguments (parameters, inputs, outputs) are set the most recently
saved code export options from the current model are used.
9.3.1.3 SimObjects (SimObject)

The collection class SimObjects manages the elements of a model or of the current
selection (class Selection). You can create a new element of type "Translational
Mass" using the method Add.
doc1.SimObjects.Add "Mechanics.Translation.Mass"
Optionally, you can give as additional parameters the name of the new element and
its X and Y position (in pixels) within the diagram view.
doc1.SimObjects.Add "Mechanics.Translation.Mass", "mass1", 90,
90
The return value of the method SimObjects.Add is an object of the class

SimObject.
A particular element is normally accessed via its name.
Set objMass = doc1.SimObjects("mass1")
With a "for each" statement you have access to all elements of a model or of
the current selection.
9-10 SimulationX 3
COM Interface
9.3.1.4 Connections (Connection)

The collection class Connections manages all connections within a document.
You can create a connection with the name "Connection1" between the connectors
of two elements by the following command:
doc1.Connections.Add "mass1.ctr2", "spring1.ctr1", "connection1"
9.3.1.5 Parameters (Parameter)

The collection class Parameters is available in different classes of the
ITI SimulationX object model. It enables to access to parameters of models,
elements, and connections. There are different ways to access a particular
parameter.
Set m1 = doc1.Parameters("mass1.m")
Set m2 = doc1.SimObjects("mass1").Parameters("m")
Both statements give the same result. The value of a parameter is represented by
the property value, to which numbers and functional expressions can be assigned.
doc1.Parameters("mass1.m").Value = 1.0
doc1.Parameters("source1.F").Value = "9.81*mass1.m"
The property Parameter.Start gets and sets the start attribute of parameters.
9.3.1.6 Curves (Curve)

The collection class Curves allows to access curve objects from within elements of
a simulation model. The following commands assign values to a curve:
Dim x(4)
Dim y(4)
For i=LBound(x) To UBound(x)
x(i) = i
y(i) = i*i
Next
Set curve = doc1.SimObjects("curve1").Curves("curve")
curve.XSequence.CurveValues = x
curve.YSequences(1).CurveValues = y
The values of a curve are accessed in SI units by default. The unit to be used can
be forced by an optional parameter.
' set unit

curve.YSequences(1).Quantity = "Mechanics.Translation.Displace"
curve.YSequences(1).Unit ("mm")
' in SI unit
curve.YSequences(1).CurveValues(TRUE) = y
' in current unit
curve.YSequences(1).CurveValues(FALSE) = y
SimulationX 3 9-11
9.3.1.7 Results (Result)

The collection class Results is available in different classes of the ITI SimulationX
object model. It enables to access result variables of models, elements, and
connections. There are different ways to access a particular result variable.
Set x1 = doc1.Results("connection1.x")
Set x2 = doc1.Connections("connection1").Results("x")
Both statements lead to the same result. The protocol of a result variable can be
enabled by setting the property Protocol. For interpretation of the simulation
results the class Result provides the properties MinValue, MaxValue (minimum
and maximum), MeanValue, RMSValue (root mean square value) and
LastValue. The following statements display the minimum and maximum value of
the result variable x1 in a message box:
MsgBox "Min: " & x1.MinValue & ", Max: " & x1.MaxValue
Access to all values of a protocol is provided by the property ProtValues.
For Each val In x1.ProtValues

MsgBox "Value: " & val
Next
The values of result variables are provided in SI units by default. The used unit can
be forced by an optional parameter.
' in SI unit
For Each val In x1.ProtValues(TRUE)
Next
' in current unit
For Each val In x1.ProtValues(FALSE)
Next
9-12 SimulationX 3
COM Interface
Access to the results of a steady-state simulation is done in a similar manner by the

property SteadyStateProtValues. Access to the results requires the specification
of other parameters:
SimSteadyStateResult steadyStateResult Kind of result variable
Int order order
bool bSI Results in SI units
(optional, default = vbTrue)
The following code fragment copies the data of a result curve of the steady-state
simulation into the column of an Excel spreadsheet.
const simSteadyStateArgument = 0
const simSteadyStateAmplitude = 1
const simSteadyStateFluctuationCoefficient = 2
const simSteadyStateExcitation = 3
const simSteadyStatePhase = 4
const simSteadyStateRealPart = 5
const simSteadyStateImagPart = 6
const simSteadyStateSumMask = 16
const simSteadyStateMeanMask = 32
res = simSteadyStateExcitation
order = 2.0
values = om.SteadyStateProtValues(res, order, vbFalse)
row = 2
col = 1
For Each v In val
excel.Cells(row, col) = v
row = row + 1
Next
To access the respective sum curve and the mean curve, the result type will be
provided with the appropriate mask. The order parameter has no meaning in this
case.
om.SteadyStateProtValues(res+simSteadyStateSumMask,
om.SteadyStateProtValues(res+simSteadyStateMeanMask,
For the full sample SteadyStateResults2Excel.vbs see the SimulationX collection

of examples.
9.3.1.8 Selection
The class Selection provides access to the current selection in a simulation model.
Access to the currently selected elements and connections is possible using the
SimulationX 3 9-13
properties SimObjects and Connections. The following statements show the

names and the comments of all selected elements:
For Each obj In doc1.Selection.SimObjects

MsgBox "Name: " & obj.name & ", Comment: " & obj.comment
Next
9.3.1.9 ResultWindows (ResultWindow)

The collection class ResultWindows contains the result windows of SimulationX.
As the result windows may contain curves from different models (Documents), the
result windows are managed by the application object.
Application
ResultWindows (ResultWindow)
ResultPages (ResultPage)
ResultPanels (ResultPanel)
ResultSeries (ResultSerie)
ResultLines (ResultLine)
ResultTransformations (ResultTransformation)
The following statements open a new window for the result variable
"Connection1.x" and set the display area for the X-and Y-axis.
Set wnd = sim.ResultWindows.Add("connection1.x")

wnd.SetMinMax 0.0, 1.0, -0.01, +0.01
The properties of all the relevant classes of SimulationX results window you can
query and set with the method GetProperty or SetProperty. The names of the
properties of each class can be found in the property bar of the result window (see
Figure 9.9).
For compatibility reasons, existing properties and methods have been retained.
The new property ResultWindow.FrozenResultMode gets and sets the behavior

of the frozen results. The following two values are supported
simFrozenResultModelCurve = 0 for independent curves
simFrozeResultsModeHistory = 1 for dependent curves
9-14 SimulationX 3
COM Interface
Figure 9.9: COM Properties in the Property Bar of a result window
9.3.1.10 NaturalFrequencies
The collection class NaturalFrequencies provides access to the results of the
natural frequency analysis.
Application
Appli
Documents
Appli (Document)
Appli
NaturalFrequencies (NaturalFrequency)
Deviations (Deviation)
EigenVectorElements (EigenVectorElement)
Energies (Energy)
With the following instruction sequence, you can run a natural frequency analysis:
set nf = doc.NaturalFrequencies
nf.DoCalculation vbFalse
The optional parameter bIgnoreFilter (default: vbTrue) indicates whether the

filters are ignored, which are be shown in the properties dialog for the natural
frequency analysis and thus all determined natural frequencies should be returned.
By the following code fragment, you can copy the determined Eigenvalues into an
Excel spreadsheet.
row = 1
excel.Cells(row, 1) = "No."
SimulationX 3 9-15
excel.Cells(row, 2) = "Re"
excel.Cells(row, 3) = "Im"
excel.Cells(row, 4) = "Abs"
excel.Cells(row, 5) = "Arg"
excel.Cells(row, 6) = "f[Hz] (damped)"
excel.Cells(row, 7) = "f[Hz] (undamped)"
excel.Cells(row, 8) = "D[-]"
excel.Cells(row, 9) = "Time Constant[s]"
ApplyFormat row, 1, 9, vbTrue, vbFalse, RGB(0, 0, 0)
for each f in nf
row = row + 1
excel.Cells(row, 1) = "f" & CStr(row-1)
excel.Cells(row, 2) = f.Re
excel.Cells(row, 3) = f.Im
excel.Cells(row, 4) = f.Abs
excel.Cells(row, 5) = f.Arg
excel.Cells(row, 6) = f.FDamped
excel.Cells(row, 7) = f.FUndamped
excel.Cells(row, 8) = f.D
excel.Cells(row, 9) = f.T
next
The collection classes Deviations, EigenVectorElements and Energies provide

features that allow access to the values calculated during the analysis. Use the
following instructions to determine the energy distribution for a specific natural
frequency. On the deviation or the eigenvectors, they resort to in the same way.
for each f in nf
row = 0
for each e in f.PotentialEnergies
row = row + 1
excel.Cells(row, 1) = e.Owner.GetRelIdent(doc)
excel.Cells(row, 2) = e.Value
next
for each e in f.KineticEnergies
row = row + 1
next
for each e in f.LossEnergies
row = row + 1
next
for each e in f.AddedEnergies
row = row + 1
next
next
9-16 SimulationX 3
COM Interface
The full sample NaturalFrequencies2Excel.vbs they find in the collection of

examples.
9.3.1.11 InputOutputAnalysys
The class InputOutputAnalysis permits automated access to transfer behavior.
This allows for easy variation calculations of a models transfer behavior. The
following steps describe how to set up script-based calculations of the transfer
behavior.
Application
Appli
Documents
Appli (Document)
Appli
InputOutputAnalysis
Inputs (Input)*
Outputs (Output)
Inputs and outputs of the transfer function are specified with the corresponding
listing classes. This requires calling the add-method for the respective listing class
with the ident of the parameters corresponding input or output.
const simIODivisionLinear = 0
const simIODivisionLogarithmic = 1
const simIOKindExcitationAmplitudeAndPhase = 0
const simIOKindExcitationRealAndImaginary = 1
const simIOKindExcitationPeriodicalTimeSignal = 2
set io = doc.InputOutputAnalysis
io.Inputs.RemoveAll
io.Outputs.RemoveAll
io.Inputs.Add("MotorTorque.in1")
io.Outputs.Add("carMotion.a")
Before the calculation, optional parameters can be modified:

io.MinFrequency = 0 'minimum frequency
io.MaxFrequency = 100 'maximum frequency
io.FrequencyPoints = 101 'number of frequency
points
io.FrequencyDivision = simIODivisionLinear 'kind of frequency d
ivision
Excitation can be specified for each input individually. For constant excitation,
absolute value and phase or real and imaginary part need to be provided.
SimulationX 3 9-17
io.Inputs(1).SetConstantExcitation simIOKindExcitationAmplitudeA
ndPhase, 1.0, 0.0
It is also possible to use characteristic lines (absolute value and phase or real and
imaginary part over the frequency) as an array (n x 3) or a periodical time signal as
an array (n x 2) for the parameterization of the excitation.
The calculation is started with the method DoCalculation.
io.DoCalculation
The following results are available upon successful calculation:

z = io.Zeros
p = io.Poles
r = io.Outputs(1).Response
All results are returned as an array (n x 2) that means as a list of pairs consisting of
a real and an imaginary part. A complete example
InputOutputAnalysisAnalysis.vbs can be found in the SimulationX sample browser.
9.3.2 Examples
The following examples demonstrate the utilization of the COM interface of
ITI SimulationX.
At http://www.microsoft.com/com/default.mspx you find information how to use

the languages VBScript and JScript.
To execute VBScript or JScript scripts on your computer, the following steps are
necessary:
1. Input the source code into an editor.
2. Save the file using an arbitrary name and the file extension *.vbs and *js, resp.
3. Start the script by double clicking the corresponding symbol in the file view of
the Windows-Explorer.
To execute the ITIScript, open the ITI-Script editor (menu Extras/Macro/ITI-Script
Editor). To use this editor you need the Microsoft Script Debugger. For more
information please see http://support.microsoft.com/kb/188135/en .
9.3.2.1 VBScript Example
' Constants
simStopped = 16' Start of ITI SimulationX with a new Document

Set doc = sim.Documents.Add()
' Remove the comment on the following line

' when ITI SimulationX should be visible during
' the execution of this macro
'sim.visible = true
9-18 SimulationX 3
COM Interface
' building a simple model

doc.SimObjects.Add "Mechanics.Translation.Mass", "mass1", 90, 90
doc.SimObjects.Add "Mechanics.Translation.Spring", "spring1", 180, 90
doc.SimObjects.Add "Mechanics.Translation.Damper", "damper1", 180, 150
doc.Connections.Add "mass1.ctr2", "spring1.ctr1", "connection1"
doc.Connections("connection1").AddLine "damper1.ctr1", 145, 105
' setting model parameters

doc.SimObjects("mass1").Parameters("m").Value = 0.5
doc.SimObjects("spring1").Parameters("k").Value = 1000
doc.Connections("connection1").Parameters("x0").Value = 0.01
doc.Connections("connection1").Results("x").Protocol = True
' open and configure result windows

Set wnd = sim.ResultWindows.Add("connection1.x")
wnd.SetMinMax 0.0, 1.0, -0.01, +0.01
' Calulation of variants of damping b = 0 ... 10
For b = 0.0 To 10.0 Step 1.0

doc.Parameters("damper1.b").Value = b
doc.Reset
doc.Start
' wait until the calculation is finished

wscript.Sleep(100)
Wend
Next
' terminate ITI SimulationX

MsgBox "ITI SimulationX will be closed..."
sim.Quit
9.3.2.2 Jscript Example
// Constants
var simStopped = 16
// Start of ITI SimulationX with a new document

var sim = new ActiveXObject("iti.sim37");
var doc = sim.Documents.Add();
// Remove the comment on the following line

// when ITI SimulationX should be visible during
// the execution of this macro
// sim.visible
// building a simple model
doc.SimObjects.Add( "Mechanics.Translation.Mass", "mass1", 90, 90);
doc.SimObjects.Add( "Mechanics.Translation.Spring", "spring1", 180,
90);
doc.SimObjects.Add( "Mechanics.Translation.Damper", "damper1", 180,
150);
doc.Connections.Add( "mass1.ctr2", "spring1.ctr1", "connection1");
doc.Connections("connection1").AddLine( "damper1.ctr1", 145, 105);
SimulationX 3 9-19
// setting model parameters
doc.SimObjects("mass1").Parameters("m").Value = 0.5;
doc.SimObjects("spring1").Parameters("k").Value = 1000;
doc.Connections("connection1").Parameters("x0").Value = 0.01;
doc.Connections("connection1").Results("x").Protocol = true;
doc.Connections("connection1").Results("v").Protocol = true;
// open result windows

var wnd = sim.ResultWindows.Add("connection1.x");
wnd.SetMinMax(0.0, 1.0, -0.01, +0.01);
// calculation of variants of damping b = 0...10
for (b=0.0; b<=10.0; b+=1.0)

{
doc.Parameters("damper1.b").Value = b;
doc.Reset();
doc.Start();
while(doc.SolutionState != simStopped)
WScript.Sleep(100);
}
var WSHShell = WScript.CreateObject("WScript.Shell");
WSHShell.Popup("calculation finished");
// terminate ITI SimulationX
sim.Quit();
9.3.2.3 ITI-Script Example

Sub Sample()
' Constants
simStopped = 16
' Start of ITI SimulationX with a new document
Set doc = Documents.Add()
' building a simple model
doc.SimObjects.Add "Mechanics.Translation.Mass", "mass1", 90, 90

doc.SimObjects.Add "Mechanics.Translation.Spring", "spring1", 180, 90
doc.SimObjects.Add "Mechanics.Translation.Damper", "damper1", 180, 150
doc.Connections.Add "mass1.ctr2", "spring1.ctr1", "connection1"
doc.Connections("connection1").AddLine "damper1.ctr1", 145, 105
' setting model parameters
doc.SimObjects("mass1").Parameters("m").Value = 0.5
doc.SimObjects("spring1").Parameters("k").Value = 1000
doc.Connections("connection1").Parameters("x0").Value = 0.01
doc.Connections("connection1").Results("x").Protocol = True
' Open result windows
Set wnd = ResultWindows.Add("connection1.x")

wnd.SetMinMax 0.0, 1.0, -0.01, +0.01
9-20 SimulationX 3
COM Interface
' Calculation of variants of damping b = 0 ... 10
For b = 0.0 To 10.0 Step 1.0

doc.Parameters("damper1.b").Value = b
doc.Reset
doc.Start
' wait until the calculation is finished

itiscript.Sleep(100)
Wend
Next
End Sub
9.3.3 Code Export via COM Interface

This chapter describes the COM Interface to transfer the functionality of a
complete SimulationX model into source code of the C programming language.
The interface basically consists of the two functions ExportSourceCode and
ExportSourceCode2, which belong to the class Document.
ExportSourceCode( [in] SimCodeExportProject prjType,

[in] SimCodeExportSaveOutputsApproach
outputsApproach,
[in] BSTR prjName,
[in] BSTR prjPath,
[in] int prjParam,
[in] SAFEARRAY(VARIANT) inputs,
[in] SAFEARRAY(VARIANT) outputs,
[in] SAFEARRAY(VARIANT) parameters,
[in, defaultvalue("")] BSTR settings,
[out, retval] SAFEARRAY(VARIANT)* msgs)
ExportSourceCode2( [in] SimCodeExportProject prjType,

[in] SimCodeExportSaveOutputsApproach
outputsApproach,
[in] BSTR prjName,
[in] BSTR prjPath,
[in] int prjParam,
[in] SAFEARRAY(VARIANT) inputs,
[in] SAFEARRAY(VARIANT) outputs,
[in] SAFEARRAY(VARIANT) parameters,
[in] BSTR additionalLibs,
[in] BSTR additionalLibPath,
[in, defaultvalue("")] BSTR settings,
[out, retval] SAFEARRAY(VARIANT)* msgs)
The function ExportSourceCode2 differs only by the two additional parameters

additionalLibs and additionalLibPath of the function ExportSourceCode. The
indication of these parameters is necessary if the exported model includes external
SimulationX 3 9-21
functions that are implemented in a LIB or DLL (Dynamic Link Library). The so-
specified libraries will be added when creating the executable model during the
link process.
Parameter Description
prjType This parameter specifies the Code Export project type.
The following project types are supported:
Project type Val.
simCodeExportProjectWithoutSolver 0
(C-Code without Solver)
simCodeExportProjectEmbeddedSolver 1
(Executable model)
simCodeExportProjectSFunction 2
(Matlab/Simulink S-Function)
simCodeExportProjectFMIModelExchange 3
(FMI for Model Exchange)
simCodeExportProjectFMICoSimulation 4
(FMI for Co-Simulation)
simCodeExportProjectSimpack 5
(SIMPACK)
simCodeExportProjectScaleRT 6
(SCALE-RT)
simCodeExportProjectDSpace1006 8
(dSPACE DS1006)
simCodeExportProjectNIVeriStand 9
(NI VeriStand)
simCodeExportProjectNILabVIEW 10
(NI LabVIEW CDS)
simCodeExportProjectVehicleSim 12
(CarSim, BikeSim, TruckSim component)
simCodeExportProjectEtasLabcar 13
(ETAS Labcar)
simCodeExportProjectAutomationStudio 14
(B&R Automation Studio)
simCodeExportProjectFMIModelExchange2 15
0
(FMI for Model Exchange 2.0)
simCodeExportProjectFMICoSimulation20 16
(FMI for Co-Simulation 2.0)
9-22 SimulationX 3
COM Interface
outputsApproach This parameter is only relevant for the project type

Executable Model and determines how the simulation
results (the outputs) are logged (stored). The following
types of logging are supported:
Project type Value
simCodeExportSaveOutputsEqidistant 0
(Save outputs equidistantly with
dtProtMin)
simCodeExportSaveOutputsAll (Save 1
outputs at every valid step)
simCodeExportSaveOutputsAtleastwithdtPro 2
t (Save at least after dtProtMin)
prjName Specifies the project name.

prjPath Determines the location of the files belonging to the
project.
prjParam This parameter is only relevant for the project type
Executable Model and defines the used solver:
Project type Value
ITI Fixed-Step Solver (Solver with 1
constant step size, suitable for
stability tests for real-time
simulations)
Sundials CVode Solver (Suitable for 2
stiff models)
This project-specific parameter is obsolete and superseded
by the generic string parameter settings.
inputs This parameter provides an array of inputs. The individual
array elements are of type String and match the names of
the input variables.
outputs This parameter provides an array of outputs. The
individual array elements are of type String and match the
names of the output variables.
parameters This parameter provides an array of parameters. The
individual array elements are of type String and
correspond to the name of the parameter values.
additionalLibs This parameter is a string with additional libraries (. Lib
files). The individual libraries are separated by space.
additionalLibPath This parameter is a string of directories in which the
additional libraries can be found. The individual
directories are separated by a semicolon.
SimulationX 3 9-23
settings This optional parameter is a string, that is composed of

key:value pairs. These pairs are separated by semicolons
(e.g. author:John Doe;exposeVariables:false). The
following table lists the various keys and their associated
possible values for specific projects. With this parameter
it is possible to map the configuration options offered in
the Code Export wizard when exporting via the COM
interface. Further details on the meaning of each key-
value pairs can be found in Section 9.5.
Project type Key Value
Executabl solverType fixStepSolver
e Model
cvodeSolver
MATLAB/ solverType noSolver
Simulink
fixStepSolver
S-
Function cvodeSolver
altParamNames oldParamName1
|newParamName
1,...,oldPara
mNameN|newPar
amNameN
altInputNames oldInputName1
|newInputName
1,...,oldInpu
tNameN|newInp
utNameN
altOutputNames oldOutputName
1|newOutputNa
me1,...,oldOu
tputNameN|new
OutputNameN
FMI author <Name>
(ME/ME
2.0/Co- description <description>
Sim/Co- exposeVariables [true,false]
Sim 2.0)
exposeStates [true,false]
htmlDocFile <file name>
includeDllWin32 [true,false]
includeDllWin64 [true,false]
includeSources [true,false]
logging [true,false]
modelImgFile <file name>
9-24 SimulationX 3
COM Interface
version <Version>
solverType (1) fixStepSolver
cvodeSolver
SIMPACK uforce [20-40]
dSPACE additionalCFiles <file names>
DS1006
compilerOptions <Compiler
Options>
initialSimState Stop
Pause
Run
maxOverrunCount <number>
overrunType stopSim
queue
Count
simStop stop
Never
All addOutputs all

Project
types firstLevel
topmost
addInputs all
firstLevel
topmost
addParameters all
firstLevel
Topmost
build (1) [true,false]
useCodeOptimizat [true,false]
ion (2)
(1) This key is only relevant for the project type FMI for
Co-Simulation 2.0 and defines the used solver of the
generated FMU. The default value is fixStepSolver.
(2) By using this key, you can choose whether after the
successful code generation a binary is created or not. The
default value is true.
(3) By using this key, you can choose whether after the
SimulationX 3 9-25
successful code generation the binary is compiled with

code optimization or not. The default is value true.
Return Value Description

The function returns an array with status messages. These
msgs can be of type error, warning or information. Normally,
the returned array is empty.
Note: If no inputs, outputs, or parameters are passed or their values are not valid,
the corresponding values, if there are any, are used directly from the model.
After the actual code generation, SimulationX attempts to create a binary from the
generated code for the specified project. Therefor a Microsoft compiler that is
supported by SimulationX must be installed. Which compilers are supported by
SimulationX, you can read in section 9.5.
Example (VBScript)
In the following example, a model that exists basically of two connected function
elements (function1, function2) shall be exported. The output of function1 is the
output of function2, where the output is to be controlled by a parameter function1.
Function2 computes a sinus. As output variables, the corresponding outputs of the
two function elements are chosen. Function1.x is just chosen as the input variable
in order to provoke a warning.
const projectTypeExecutableModel = 1 'prjType

const SaveOutputsAtleastwithdtProt = 2 'outputsApproach
const CVodeSolver = 2 'prjParam
'Defining the inputs, outputs and parameters
opts = Array("function1.y", "function2.y")
ipts = Array("function1.x")
params = Array("function1.F")
'Starting SimulationX
set sim = CreateObject("iti.simx37")
sim.Visible = true
sim.Interactive = true
'Opening the model to be exported

set doc =
sim.Documents.Open("C:\Users\Public\Documents\SimulationX
3.7\Samples\Scripting\ScriptingSample.isx")
'Exporting the model
msgs = doc.ExportSourceCode(projectTypeExecutableModel,
SaveOutputsAtleastwithdtProt, "COMTest",
"C:\CodeExport\ComTest", CVodeSolver, Array(ipts(0)),
Array(opts(0),opts(1)), Array(params(0)))
'Necessary for the case that the msgs array is empty
9-26 SimulationX 3
Co-Simulation Interface
size = -1
On Error Resume Next
size = UBound(msgs)
On Error GoTo 0
'Output the messages

if size > -1 then
size = UBound(msgs)
for i=0 to size
MsgBox msgs(i)
Next
end if
9.4 Co-Simulation Interface

9.4.1 Co-Simulation with SimulationX Coupling Element
9.4.1.1 Description of Communication Protocol
The co-simulation of SimulationX uses the TCP/IP protocol.
ITI SimulationX can take control over the simulation process as master or can be
controlled as slave by the co-simulator.
Figure 9.10: Communication between the systems
The communication protocol between the two partners can be described as follows.
To make the communication as easy as possible the receiver should know the exact
length of each incoming package. Therefore it is useful that client and server make
a agreement at the beginning of the communication about the structure of packages
SimulationX 3 9-27
to be interchanged. To transfer this information, a fixed-sized control package must

be transmitted by the client.
Control Package Structure:

Field Type Size Comment
[Byte]
Package Code unsigned 4 PACKAGE_CONTROL =
0x0011
Communication Step Size double 8 Communication Step Size
dtComm dtComm
Number of transmitter unsigned 4
channels n
Number of receiver channels unsigned 4
m
The Package Code contains additional information about the package. In the
current prototype it contains only a sign for distinction between control and data
packages.
Data Package Structure:

Field Type Size Comment
[Byte]
Package Code unsigned 4 PACKAGE_DATA =
0x0010
Current Simulation Time t double 8
Current Calculation Step Size double 8
dt
Number of Channels n unsigned 4
Valuet[Channel 1] double 8
Valuet-dt[Channel 1] double 8 can be used together with dt
for extrapolation
...
Valuet[Channel n] double 8
Valuet-dt[Channel n] double 8
The standard way to communicate over sockets is to use the TCP/IP byte order for
all packages. Before sending each communication partner should convert his data
into this format by using the C-Runtime function htonl (host to network).
9-28 SimulationX 3
The receiver of the package can use the C-Runtime function ntohl (network to
host) to reconvert the data to its machine dependent number format. Therefore, it
isn't necessary to have an option parameter in the coupling element's property
dialog to switch between both data representations. Anyway the coupling element
includes such an option for testing co-simulation.
Both simulators can use their own calculation step size between the
communication steps. Values between the communication points can be calculated
by linear extrapolation. Therefore, the previous value of each variable and the
corresponding calculation step size are included in the exchanged packages.
Communication Steps: tk tk+1 tk+2 tk+3

Calculation Steps: ti ti+1 ti+2 ti+3 ti+4
cosimulation without extrapolation

t
cosimulation with linear extrapolation

t
Figure 9.11: Communication time diagram
9.4.1.2 Using Coupling Element in SimulationX

The coupling element has a signal input and output. If you want to transfer more
than one value to the other simulator, then combine the input signals with a
multiplexer as a vector and use a demultiplexer to split the output vector into
several signals. Multiplexer and demultiplexer are not part of a library. Use the
TypeDesigner to create them both instead.
SimulationX 3 9-29
Figure 9.12: Coupling element
The coupling element in ITI SimulationX hosts the following parameters:

Parameter Type Comment
Working Mode Enumeration Client (standard) or server (not
implemented yet)
IP-Address or Host String Only available in client mode
Name
Port Number Integer
Communication Step Double Simulation time between two
Size communications
Extrapolation Mode Enumeration None or linear extrapolation
Timeout Double Maximum time for response from
server to prevent waiting without end
Use TCP/IP Byte Order Boolean Use TCP/IP byte order (standard)
Dimension of output integer Number of receiver channels
vector Remark: The number of transmitter
channels will be calculated from the
dimension of signal input x.
9.4.2 Co-Simulation with Simulink

The co-simulation of ITI SimulationX and Simulink is done by the general
coupling element in SimulationX; at the Simulink side an s-Function will be used.
9-30 SimulationX 3
Figure 9.13: Coupling ITI SimulationX with Simulink
Before using the co-simulation makes sure that the following settings in
ITI SimulationX and Simulink are equal:
Simulation time
Communication step size
Dimension of output vector of s-function and dimension of input vector of

coupling element in ITI SimulationX. The coupling element in ITI SimulationX
hosts the following parameters:
Working Mode Enumeration Client (standard) or server (not
implemented yet)
IP-Address or Host String Only available in client mode
Name
Port Number Integer
Communication Step Double Simulation time between two
Size communications
Extrapolation Mode Enumeration None or linear extrapolation
Timeout Double Maximum time for response from
server to prevent waiting without end
Use TCP/IP Byte Order Boolean Use TCP/IP byte order (standard)
Dimension of output integer Number of receiver channels m
vector Remark: The number of transmitter
channels will be calculated from the
dimension of signal input x.
The s-Function in Simulink has the following set of parameters:
SimulationX 3 9-31

IP-Address or Host String
Name
Port Number Integer
Communication Step Double Returns an error , if this size differs
Size from the step size received from
SimulationX
Dimension of input Integer Number of transmitter channels to
vector SimulationX
Dimension of output Integer Number of receiver channels from
vector SimulationX returns an error if
dimension differs from the dimension
received from SimulationX
To start the co-simulation you must first start Simulink. The s-function waits for
the start of calculation of ITI SimulationX. If any of the values listed above do not
match, then the s-function will report an error.
Using the sample model:
1. Set the Working directory of MATLAB to the directory of the sample.
2. Execute start.m this script will start Simulink and load the model and his
parameters
3. Start ITI SimulationX and load the file "drive_cosim.ism"
4. Start the simulation in Simulink
5. Start the simulation in ITI SimulationX
The simulation calculation runs now.
9.4.3 Co-Simulation with CarSim, BikeSim, TruckSim

9.4.3.1 Introduction
VehicleSim is a toolset for the efficient simulation of cars, trucks and motor-
cycles. SimulationX models and VehicleSim models are connected by using a
special co-simulation block (included in the package Co-Simulation/CarSim,
BikeSim, TruckSim) in the SimulationX model. This block utilizes the VehicleSim
API (Application Programming Interface) [7] for data exchange and
synchronization of SimulationX and VehicleSim.
9.4.3.2 Workflow
The following steps have to be carried out for doing co-simulation between
SimulationX and VehicleSim:
Prepare the VehicleSim model
Prepare the SimulationX model
9-32 SimulationX 3
Run the simulation in SimulationX and VehicleSim

Post processing in VehicleSim and SimulationX
The co-simulation was tested with CarSim. Hence we will use the term CarSim in
the following description. It should work with BikeSim and TruckSim in the same
way.
9.4.3.3 The Sample Model

This section shows how the SimulationX model of an engine combined with a
powertrain replaces the engine model of CarSim. The SimulationX model is shown
in the following figure.
Figure 9.14: SimulationX model of the engine with a very simple dual mass flywheel
model
All engine parameters are kept at their default values. The changed parameters of
the other model objects are shown in the following table.
Name Value Unit
dms1.J 0.02 kgm
dms1.om 800 (fixed) rpm
dms2.J 0.02 kgm
dms2.om0 800 (fixed) Rpm
springDamper.kind Spring-Damper
springDamper.k 10000 Nm/rad
springDamper.b 10 Nms/rad
injection.F 1
9.4.3.4 Preparation of the CarSim Model

At first the CarSim model has to be prepared. We have to change the powertrain
configuration to replace the internal engine model by our SimulationX engine.
Open the powertrain screen in CarSim and switch to External engine model"as
shown in the following figure.
SimulationX 3 9-33
Figure 9.15: Change to External engine model
The block diagram changes as shown in Figure 9.15. In order to replace the
internal engine model the engine speed is to be computed by the SimulationX
model and to be fed to CarSim as IMP_AV_ENG. The reaction torque of the
driveline (EXP_M_EngOut) has to be fed back to the powertrain in SimulationX.
To prepare this data exchange the CarSim variable IMP_AV_ENG has to be

imported into CarSim from the SimulationX model. Change to the CarSim Run
Control page, click the Models button and change to Models: Self-Contained
Solvers.
Figure 9.16: Switch to Self-Contained Solvers
Create a new dataset, call it "SimulationX" and open it.
On this screen change one of the Misc. Links to I/O Channels/I/O Channels:
Import as shown below
9-34 SimulationX 3
Figure 9.17: Prepare the variable import
Create a new dataset as usual and add the variable IMP_AV_ENG to the list of
Active Import Variables.
Select Replace for mode as shown in the above figure. If the Mode selector is
disabled open the associated Parsfile and do the change there.
How this variable is connected to a SimulationX output and how CarSim outputs
are connected to SimulationX inputs is shown in the next section.
Figure 9.18: Add the import variable
SimulationX 3 9-35
9.4.3.5 Preparation of the SimulationX Model

Our engine model has to be changed a little bit. To feed the torque
EXP_M_EngOut computed in CarSim back to the SimulationX model we add an
External Torque (Mechanics.Rotation.Source) element to the model as shown in
Figure 9.19 and rename it to "loadTorque". Leave the parameter T at its default
setting "in1". In this way the value of the signal input "in1" is fed as load torque to
the driveline. If you want to connect other variables to CarSim take care of the
sign.
The powertrain speed will be sent to CarSim and assigned to the variable
IMP_AV_ENG. Hence we add a speed sensor (Mechanics.Rotation.Sensor) to our
model.
Figure 9.19: Engine model with loadTorque and speed sensor
Now we add the VehicleSim co-simulation block. It is included in the package

CoSimulation.VehicleSim.
Figure 9.20: SimulationX VehicleSim co-simulation block
The block has the following properties:
9-36 SimulationX 3
Figure 9.21: Property window of the VehicleSim co-simulation block
Simfile Name (simfile)

To communicate with CarSim using its API, the recently used simfile.sim must be
given. This file contains links to the other data files used by CarSim. The file is
located in the current database folder. This folder is selected during CarSim start
up in the following dialog box.
Figure 9.22: Database selection during CarSim start up
A file selection window opens when you press the button at the end of the edit box
of the parameter simfile in the property window of the VehicleSim co-simulation
block. Go to the current database folder and select the current CarSim simfile.sim.
SimulationX 3 9-37
Step Size ts
This step size is used to communicate with CarSim and to update inputs and
outputs. The CarSim step size should have the same value. If the CarSim step size
is different, an error message is shown and the simulation run does not start.
As stated in [7] chapter "4. Extending Math Models Using Import and Export
Arrays") a one-step time delay is introduced between CarSim and SimulationX.
This may lead to numerical instabilities for closed loop models with a tight
coupling. Reduce the step size ts in such cases.
For our sample model we use a step size of 1 ms.
Number of Inputs nu, Number of Outputs ny
The block communicates via the signal input u and the signal output y with the
enclosing SimulationX model. These signal connectors can carry vectors of
variables. The dimension of these vectors is defined by nu (for input u) und ny
(for output y).
For connecting scalar signal connectors to these vector connectors, the
multiplexers and demultiplexers of the package CoSimulation.MuxDemux can be
used (see below).
In our example one signal (the powertrain speed) is sent to CarSim. Hence we set
nu = 1. The reaction torque of the CarSim model is fed back to the powertrain
model. Additionally we want to observe the speed of the car computed in CarSim.
Thus set ny = 2.
Import variable uImp[nu], Export variables yExp[ny]

These parameters are vectors of strings. The dimension is respectively nu or ny.
Here we must enter the names of the CarSim variable which have to be connected
with the block inputs and outputs. If one of the names is not found in the CarSim
database, a warning message is shown during start-up of the simulation run.
Figure 9.23: Parameters of the co-simulation block
9-38 SimulationX 3
The powertrain speed is imported to CarSim (see Figure 5) as IMP_AV_ENG.

Thus enter {"IMP_AV_ENG"} for uImp. In addition to the CarSim reaction
torque (EXP_M_EngOut) we want to observe the vehicle speed (VX). Hence enter
{"EXP_M_EngOut","VX"} for yExp
At the end of the described modifications the block should have the following
properties:
As last step the co-simulation block is to be connected with the powertrain model.
We connect the input u with the output of the speed sensor (speed.om). The output
has the dimension ny=2. Hence we need a demultiplexer
(MuxDemux.Demultiplex2) to split this vector into scalars.
In this way we end up with the model shown in Figure 9.24.
Figure 9.24: SimulationX model ready for co-simulation with CarSim
Now the SimulationX model is ready for co-simulation with CarSim.

If you want to transfer more than one signal to CarSim you have to adapt the
dimension by using the parameter nu and use the corresponding multiplexer block
to combine the signals to a vector. In the package CoSimulation.MuxDemux
multiplexers and demultiplexer of dimension 2 to 5 are provided. If you need
higher dimensions you can easily create your own blocks using the existing ones as
guideline. The implementation of these blocks is open and can be viewed by using
the SimulationX TypeDesigner (see chapter 8).
9.4.3.6 Co-Simulation
After the following settings on the CarSim "Self Contained Solvers" page, the
co-simulation can be started. Change now to CarSim and open the dataset we
created at the beginning by clicking on the SimulationX button on the Run
Control screen.
Figure 9.25: The CarSim Run control
SimulationX 3 9-39
Figure 9.26: Select the VehicleSimXStarter.exe as external wrapper program
Switch on Use external wrapper program and select the executable

"VehicleSimXStarter.exe" as External wrapper program. The VehicleSimXStarter
application depends on the used SimulationX version and the path to the right
depends on the operating system version. It is located in the subdirectory "ITI-
Software/SimulationX/Tools" of the following folder:
SimulationX 32bit on Windows 32bit "program files" folder
SimulationX 32bit on Windows 64bit "program files (x86)" folder
SimulationX 64bit on Windows 64bit "program files" folder
On 64bit operating systems the "For 64-bit Windows OS" drop down box is
displayed. Choose here the same solver version as the used SimulationX version,
32bit or 64bit. Make sure, the "Specify alternative VS solver DLL files" checkbox
is unchecked, if no solver is selected.
Furthermore input 0.001 s as Time step. This value must be equal to the parameter
ts of the SimulationX co-simulation block.
Now the simulation run can be started by pressing the Run Math Model button
on the CarSim Run Control Screen. Make sure that SimulationX is running and the
model containing the VehicleSim co-simulation block is the active one. Instead of
the CarSim internal computation routine the "VehicleSimXStarter" application is
started. This application executes the following actions:
Connects itself to the running SimulationX instance, or opens a new
SimulationX instance.
Connects itself to the active model.
Checks whether this model contains a VehicleSim co-simulation block.
9-40 SimulationX 3
Resets the active model if necessary.

Starts the simulation in SimulationX. Now the VehicleSim co-simulation
block communicates via the VehicleSim API with CarSim.
Shows status messages during the simulation run.
Closes itself after the simulation run.
If SimulationX could not be found or opened, or if the active model does not
contain a VehicleSim co-simulation block an error message is shown and the
simulation run is not started.
Figure 9.27: The VehicleSimXStarter is connected to SimulationX, the co-simulation is

running
The co-simulation run stops under the following conditions:

If the Stop button of the VehicleSimXStarter is pressed. It can be
continued by pressing the Start button.
If the CarSim stop time is reached or a CarSim stop condition becomes true.
In this case a message in SimulationX is shown.
If the Stop button in SimulationX is pressed, the stop time is reached, or a
termination condition becomes true. The VehicleSimXStarter closes
automatically in that case. The simulation can be continued by pressing the
SimulationX Start button.
The simulation run can be started as usual from SimulationX too. In this case it is
possible that the CarSim model data are not transferred to the database files which
are loaded by the CarSim API during co-simulation. Even if you save the CarSim
database the data are not written to these files. This is done by CarSim, when you
start the external wrapper program, the VehicleSimXStarter in our case. Hence it is
safer to start the co-simulation from CarSim. It is safe to start the co-simulation in
SimulationX if you already started it once by using CarSim and did not change the
CarSim model meanwhile.
SimulationX 3 9-41
9.4.3.7 Post processing in CarSim and SimulationX

After co-simulation runs the usual post processing functions of CarSim (Animate,
Plot) and SimulationX are available. The following figure shows the SimulationX
result window and the CarSim plot of the vehicle speed.
Figure 9.28: Vehicle speed in SimulationX and CarSim
9.5 Code Export

9.5.1 Introduction
When using the Code Export, you can transfer the functionality of a complete
SimulationX model into source code of the C programming language.
SimulationX Model
Code Export Wizard
Exported C-Code
9-42 SimulationX 3
Code Export
This source code can be used for, e.g.:

Accelerated simulation
Model integration in other simulation programs
Hardware in the Loop (HIL) applications
The model will be exported as an explicit ordinary differential equation. Before the
export the user defines inputs, outputs, and parameters, which will form the
interface of the exported model (see Figure 9.29). A wizard supports the interface
definition.
By a special symbolic analysis the model will be transferred into an ordinary
differential equation of the form:
x& = f ( x, u, p, z, zf, t )
y = g( x, u, p, z, zf, t )
z = h1( x, u, p, zf, t )
zf = h2 ( x, x&, u, p, z, t )
The variables are:
x ......... state variable
u ......... input variable
y ......... output variable
p ......... parameter
z ......... discrete variable
zf ........ zerofunction
t .......... time
Figure 9.29: Process of C-Code Generation
SimulationX 3 9-43
The model functionality is implemented in the file '<Projectname>.c' .

It is splitted in the following 3 functions:
1. Determination of initial values (InitializeConditions)
2. Calculation of the output quantities (CalcOutputs)
3. Calculation of the derivatives of the state quantities (CalcDerivatives)
Depending on the intended purpose of the model code interface functions are
generated, which ensure compatibility with the target system.
All available project types are shown in the following table:
Project type Comment
C-Code (without Solver) Only the model functionality will be exported
Executable Model Model functionality and solver
For accelerated simulation runs on any
hardware platform
Model integration into other simulation or
dimensioning tools
MATLAB/ Automatic generation of s-function code for
Simulink S-Function MATLAB/Simulink
Further processing with the Simulink Coder
(former Real-Time Workshop) is possible.
Thus the following HiL platforms can be
addressed:
dSPACE
ETAS
OpalRT
NI VeriStand Real-time test and simulation software NI
VeriStand from National Instruments
NI LabView Control Design Integration of SimulationX models in NI
& Simulation LabVIEW
FMI for Model Exchange Exports the model functionality in a FMU (for
Model Exchange)
FMI for Co-Simulation Exports the model functionality in a FMU (for
Co-Simulation)
9-44 SimulationX 3
Code Export
CarSim, BikeSim, Model integration into VehicleSim, a toolset for

TruckSim component the efficient simulation of cars, trucks and
motorcycles from the Mechanical Simulation
Corporation
ETAS LABCAR Modular HiL Testing System for Automotive
Electronic Control Units from ETAS GmbH
B&R Automation Studio Export of model functionality including the
solver as program object of the B&R
Automation Studio
FMI for Model Exchange 1.0 Exports the model functionality in a FMU (for
and 2.0 Model Exchange 1.0 and 2.0)
FMI for Co-Simulation 1.0 Exports the model functionality in a FMU (for
and 2.0 Co-Simulation 1.0 and 2.0)
Table 9.1: Project types and their use
If you would like to use the Code Export with other targets, you can choose the
project type C-Code (without solver) and can also write the corresponding
interfaces by your own. If you need further help, please contact us.
9.5.2 Code Export Wizard

For the Code Export a wizard was implemented that guides
you through the code generation process. The wizard is
started by the menu Export/C-Code.
The wizard guides you through all necessary steps for the chosen project type. All
settings will be saved together with the simulation model.
9.5.2.1 Dialog page Project

On the project page (see Figure 9.30) you define the project type, project name
and the storage location of the files of the project. By default the project has the
same name as the model. This name can be edited.
During code generation a file "generated.txt" with a list of the names of all auto-
matically produced files is created. When enabling the checkbox Delete existing
project files all files listed in "generated.txt" are deleted before a new code
generation.
SimulationX 3 9-45
Figure 9.30: Code Export Wizard Page Project
Possible other settings depend on the selected project type. These settings will be
discussed in later sections.
Set the check box Enter additional libraries when the model contains external
functions and you want to specify for which libraries code should be generated to
dynamically call functions in a DLL. For more information of this topic, see
section 9.5.2.6.
With the button you start the code generation for a project which has
already been defined. The dialog pages for inputs, outputs and parameters are
skipped in this case.
The assignment of the parameters and of the inputs and outputs is stored in the file
"Readme.txt" for documentation.
9-46 SimulationX 3
Code Export
9.5.2.2 Selection of signal inputs
Figure 9.31: Selection window of the signal inputs
This selection is available only for

C-Code (without Solver)
Executable Model
MATLAB/Simulink S-Function
NI VeriStand
NI LabVIEW Control Design & Simulation
FMI for Model Exchange
FMI for Co-Simulation
CarSim, BikeSim, TruckSim component
ETAS LABCAR
B&R Automation Studio
Any model object with a signal input (see Figure 9.31) could be selected. By using
Drag-and-Drop, drag and insert a signal input from the object list to the selection
field (double click may also be used).
In addition, there is the option to select all signal inputs of the model by pushing
the button or to select all topmost inputs by pushing the button .
SimulationX 3 9-47
Furthermore, you can automatically add all Modelica connectors at model level as
inputs by clicking this button .
With you can move the signal input in the selection upwards or downwards.
The selected order will be used for instance in the project type Simulink S-
Function to create the inputs in the resulting block. To delete a selected input, use
the button .
By using this button you can open the Filter- and Sort Dialog.
This dialog offers the possibility to filter the tree view according to the specified
criteria and sort the tree elements. The sorting is case-sensitive and the individual
layers are sorted separately.
Note:
The table with the selected elements can be sorted by clicking on a column of the
table header. Thus, it is possible to find a particular item in a long list of selected
elements.
9.5.2.3 Selection of outputs

All signal outputs and result quantities, including variables in the variables list can
be chosen as outputs for the model to be generated. Figure 9.32 shows an example
for this selection.
The same control functions as for the signal inputs can be applied. In addition,
there is the option to select all result variables of the model by pushing the button
or to select all topmost results by pushing the button . Furthermore, you
can automatically add all Modelica connectors at model level as outputs by
clicking this button .
9-48 SimulationX 3
Code Export
Figure 9.32: Selection window of the outputs
9.5.2.4 Parameter selection
Figure 9.33: Selection window of parameters
On this page parameters of the model can be made accessible from outside for the
Code Export. The appliance is the same as for signal inputs.
SimulationX 3 9-49
Note: You can select only one parameter of a parameter set as a parameter in the
Code Export wizard, so that no assignment equations are generated in the GSA.
Furthermore, parameters that refer to other parameters are not eligible.
9.5.2.5 Selection of characteristic curves (only NI VeriStand)

Any curve can be selected. Insert a curve from the object list to the selection field
by double click or Drag-and-Drop.
9.5.2.6 (Additional) Libraries

After the Global Symbolic Analysis (GSA), the additional libraries that are
necessary for calling the external functions in the model are shown on this page.
For each library it is possible to determine whether code should be generated to

dynamically call functions in a DLL. If not, the appropriate static or import
libraries (LIB) for the build process are necessary. The paths to these libraries can
be specified in the input field Additional Library Paths. Individual libraries can
get manually added and deleted with the appropriate button see Figure 9.34.
Figure 9.34: Selection of additional libraries
9-50 SimulationX 3
Code Export
9.5.2.7 Code Generation
Figure 9.35: Progress of the code generation
With this page the generation of the code actually starts, but before a symbolic
analysis of the model take place. The aim of this analysis is the transformation into
a system of ordinary differential equations (ODE). During this process the
calculation algorithm will be optimized, too.
During the export process you can follow the progress in the code generation
window (Figure 9.35).
All files generated by the Code Export are stored in the specified project directory.
They can be used for further processing (e.g. compiling, linking) on the target
platform now.
The names of the generated files are listed in the file "generated.txt".
The file Readme.txt contains a list of the inputs, outputs, and parameters of the
model.
Figure 9.36: Message for successful export
SimulationX 3 9-51
When the generation of the exported code finished successfully, you will get a
message as in Figure 9.36.
9.5.2.8 Post-Processing
On this page you can compile and start the generated project. This dialog page is
available only for:
Executable Model
MATLAB/Simulink S-Function
NI VeriStand
NI LabVIEW Control Design & Simulation
FMI for Model Exchange
FMI for Co-Simulation
CarSim, BikeSim, TruckSim component
ETAS Labcar
FMI for Model Exchange 2.0
FMI for Co-Simulation 2.0
Select the development environment under which your project to be translated.
SimulationX automatically detects the following on your system installed
Microsoft C compiler:
Microsoft Visual C/C++ 6.0
Microsoft Visual C/C++ .Net
Microsoft Visual C/C++ .Net 2003
Microsoft Visual C/C++ Toolkit 7.0
Microsoft Visual C/C++ 2005 (ab Standard Edition)
Microsoft Visual C/C++ 2008 Express Edition (kostenlos)
Microsoft Visual C/C++ 2008 (ab Standard Edition)
Microsoft Visual C/C++ 2010 Express Edition (kostenlos)
Microsoft Visual C/C++ 2010 (ab Professional Edition)
Microsoft Visual Studio Express 2012 fr Windows Desktop (kostenlos)
Microsoft Visual C++ 2015 Build Tools
In section 2.1.2 you can find more information about the development
environments that are supported by SimulationX.
9-52 SimulationX 3
Code Export
9.5.3 Project Types

9.5.3.1 C-Code (without Solver)
The sources for the model and files with various functions used by the model are
created. These sources can be integrated into your custom target project.
Dialog page Description
Signal inputs The current values of the inputs are expected as transfer
parameters _u of the exported functions.
Outputs The current values of the outputs are written into the
array _y in the function CalcOutputs.
Parameters The current values of the parameters are expected in the
array _p by the exported function.
9.5.3.2 Executable Model

For accelerated simulations, the model can be exported together with a solver. The
generated platform-independent sources will then be compiled and linked on the
desired target system. The resulting executable file ('executable model') carries the
computation out and writes the results in a text file.
The generation process of an executable model is shown in Figure 9.37.
Figure 9.37: Generation of an executable model
SimulationX 3 9-53
The following settings can be specified in the Code-Export wizard:

Project Besides the project name and the project directory you
can specify the used solver and how the outputs will be
saved.
Inputs The selected inputs can be set by passing a self-
implemented function via function pointer (in the
exported file "main.c", see comment "SetInputsFunc") to
the solver. The signature of this function is defined in the
exported file "ITI_Types.h". For further details please
contact the ITI support team.
Outputs The specified results will be written to the "outputs.txt"
file.
Parameters The current parameter values from the model will be
written to the file "parameter.txt". The executable model
reads this file after the start of the simulation.
Post-processing Here you can build and start the executable model (more
details below).
On the project page it is possible to choose a solver. The following options are
available:
Sundials CVODE (Suitable for stiff models)
ITI Fixed-Step Solvers (Solver with constant step size, suitable for stability
tests for real-time simulations)
Further yon can specify how the simulation results (outputs) are saved during the
simulation process:
Save all (Save outputs at every valid step)
Save equidistant (Save outputs equidistantly with dtProtMin)
At least after dtProtMin (previously called Save similar to SimulationX)
At least after dtProtMin and after Events
At least after dtProtMin, before and after Events
At least after dtProtMin and Event steps
Last Value
The accuracy and step size settings for the solver are saved in the source code of
the model (file <project_name>.h) as well as in the file "solversettings.txt". You
can use this file to change the settings without recompilation.
If the executable model finds this file in the start directory these settings will be
used, otherwise the settings from within the model are used.
9-54 SimulationX 3
Code Export
If you start the executable model with the command line parameter "/s <file
name>" the specified file is used.
The file "solversettings.txt" has the following format

Keyword = value
The following key values are available:

Keyword ITI Fixed-Step CVODE
tStart Start time
tStop Stop time
dtMin Integration step size Minimum calculation step size
dtMax Maximum calculation step size
limitdtMin 0 - No limitation of the
minimum step size
1 Minimum step size is
limited to dtMin
relTol Relative Tolerance
dtProtMin Defines how frequently variables are logged.
mode 0 - Euler Forward 0 - Adams variant
1 - ITI Standard (with 1 - BDF variant of CVODE (for stiff
constant step size) models)
2 - Heuns Method
3 - RKF23
4 - DOPRI5
minmax 0 disabled
1 Minimum
handling for state
variables
zeros 0 - No exact localization
1 - Exact localization of
events using zero functions
bHysteresis Algorithms for localization of events
consider a hysteresis of epsilon.
epsilon Value of hysteresis for localization of
events.
SimulationX 3 9-55
saveMode 6 - Last Value 0 - All

All other settings lead 1 - Equidistant
to equidistant saving 2 - At least after dtProtMin
of the results. 3 - At least after dtProtMin and after
Events
4 - At least after dtProtMin, before and
after Events
5 - At least after dtProtMin and event
steps,
6 - Last Value
traceOn 0 - suppress trace output 1 - enable trace output
effJac 0 Without efficient
Jacobian computation
1 - Efficient Jacobian
computation and
Gauss Method
2 Efficient Jacobian computation and
Sparse Matrix solver
maxOrder mode = 1: {1...5}

mode = 0: {1...12}
blTol Error tolerance for Implicit Block solvers
blLinSolv Implicit Block solvers: Solution of the linear system by
0: LU decomposition
1: QR decomposition
threadLimit Defines the number of logical processor cores used for the
parallelized variant calculation with OpenMP. For details, see
the section "Parallelized variant calculation".
Table 9.2: Format of the file solversettings.txt
The default value of mode is 1. That means that the Fixed-step solver uses the
two-step method ITI Standard. This solver is used for the real-time projects
dSPACE, NI Veristand, ProSys-RT, SCALE-RT, too. CVODE uses a BDF variant
(with maximum order equal to 5) which is well suited for stiff models. Therefore
the default value of iMaxOrder is 5. If you set mode=0 keep in mind that the
maximum order of the Adams variant is 12.
9-56 SimulationX 3
Code Export
Post-processing:
Select here the development environment under which the generated project is to
be compiled. SimulationX recognizes automatically the Microsoft C compilers
installed on your system.
For information about development environments supported by SimulationX, refer

to section 2.1.2.
Click on this button to specify additional options for Post-processing.
You can find detailed information about these options in the
following section.
Compiles and builds your generated project. The compilation and
build results are displayed in the output area.
Starts the execution of the compiled project. Information about the
execution is displayed in the output area.
Advanced options:
Here you have the possibility to specify additional libraries (.lib files) and the
appropriate directories where these files are located. This is necessary if the
exported model contains external functions, which are implemented in a DLL
(Dynamic Link Library). In such a way specified libraries are then added to the
executable model during the link process. Subsequently, you can start the
execution of the model by clicking the run button.
Click this button to use a convenient dialog for specifying the
additional libraries and corresponding directories. If you manually
enter the libraries and directories please ensure to separate the
libraries and directories by a semicolon.
By activating the option OpenMP, the variant calculation can be parallelized.

Then the corresponding option is set in the compiler. More information can be
found in the following section, Parallelized variant calculation.
By activating the option "Compile with Optimization" it is possible to increase the
calculating speed. Then the compiler will use the compiler option /O2. Be aware
that this can result in a significantly longer compile time.
Variant calculations:
In order to accomplish variant calculations, you must indicate the parameters
which can be varied during the export (see also section 9.5.2.4).
SimulationX 3 9-57
Parameter table
Result lists
The text file ("parameters.txt") is created during the export. It contains the current
SimulationX parameters in the first row. For more variants you can add new rows
with the corresponding values. When executing the model the appropriate
simulation runs are accomplished and a separate result file is stored for each
variant. In order to exclude a parameter record from the variant calculations, insert
at the beginning of the corresponding row the comment characters "//".
Due to the high optimization level of the C code, the simulation speed is
considerably higher compared to the simulation time in SimulationX. This enables
even faster simulation runs, parameter studies or optimization cycles.
The file "parameters.txt" is automatically read by the executable model if it can be
found in the start directory.
If you start the executable model with the command line parameter /p <file
name> this file is used. If no parameter file can be found, the executable model
uses the values set in SimulationX.
Parallelized variant calculation

Using OpenMP, it is possible to significantly speed up by parallelizing the variant
calculation. To perform a parallelized variant calculation it is necessary that the
compiler supports OpenMP and the machine has multiple logical processor
cores. Use the "thread-limit" option the SolverSettings file to determine how many
logical processor cores are used. If this value is less than or equal to 0, all available
processor cores are used. By default, this value is set to -1, so that all available
processor cores are used. If thread-limit is set to 1, there is no parallelism.
Attention:
When using the external functions which are not thread-safe, it can lead to
unexpected results.
9-58 SimulationX 3
Code Export
9.5.3.3 Simulink S-Function
Figure 9.38: MATLAB/Simulink S-Function generation
With this project type it is possible to create a Simulink S-Function based on a

SimulationX model (Figure 9.38 shows the process).
You can specify the following settings in the Code-Export wizard:
Project Note that the project name for export as Simulink
S-Function must not begin with a special character or a
number. Using the popup menu Type on the first page
of the Code Export Wizard you can select whether the
S-Function is to be generated with or without a solver.
Inputs The exported inputs correspond to the inputs of the
S-Function block. The sequence is the same as in the
selection window.
Outputs The exported outputs correspond to the outputs of the
S-Function block. The sequence is the same as in the
selection window.
SimulationX 3 9-59
Parameters The chosen parameters are available as S-Function

parameters. A mask is automatically generated which
eases the parameter input.
Post-processing Choose the MATLAB version and start the creation of
the S-Function. Please note that SimulationX identifies
only MATLAB installations of the same architecture
(x32/x64)
S-Function without solver

Here the Simulink solver is used for the computation of the S-Function. The
S-Function publishes its continuous state variables and sample times (if any) to
Simulink.
An appropriate solver and settings for step size control and accuracy have to be
found out using the hints of the Simulink manual.
Such a model integration is, in contrast to Co-Simulation (see also section 9.4.2),
the more efficient and numerically better solution to integrate a SimulationX model
in MATLAB/Simulink.
You should use the S-Function Export without Solver, if the exported model is to
be connected to another part of the continuous model in Simulink. Otherwise it is
possible that due to oversampling and the resulting delays in the signal exchange
false results can arise. This is true even if one of the Simulink variable step size
solvers is used.
S-Function with Fixed-Step Solver
In this case the S-Function also contains the SimulationX Fixed-Step Solver beside
the model functionality. The computation is done without usage of a Simulink
solver. The S-Function does not publish its continuous or discrete state variables
and sample times to Simulink. This enables the S-Function to be used in Function-
Call, Triggered and Enabled Subsystems. Thus this variant is especially suited to
be used in real-time applications. The integration step size used by the S-Function
internal solver can be independently chosen from the Simulink step size settings. If
the internal integration step size is smaller than the Simulink step size sub steps are
carried out automatically. In this way oversampling can be realized e.g. for stiff
systems. During these sub steps the inputs are treated as constant.
As aforementioned the S-Function does not publish sample times to Simulink.
Using a Simulink variable-step size solver the S-Function is called at arbitrary time
instances. To ensure a deterministic behavior the S-Function is to be placed inside
a Triggered or Function-Call Subsystem and to care for a constant sample rate
yourself. In order to achieve an optimum synchronization between the S-Function
and the enclosing Simulink model this sample time should be an integer multiple
of the S-Function integration step size.
If a Simulink Fixed-step size solver is used the S-Function is called with this
constant step size. The above described method can be used for oversampling.
9-60 SimulationX 3
Code Export
Some specifics need to be considered for usage in Enabled Subsystems. If the

subsystem is disabled the S-Function remains in its last computed state. After
enabling it continues from this state. However the S-Function internal time is set to
the current Simulink simulation time. This may lead to unexpected results if the
S-Function contains time dependent functions.
The integration method iMode and the fixed-step size dtMin can be selected in the
Solver pane of the S-Function block dialog. The integration method iMode can be
selected from EulerForward, ITI Standard, Heun, RKF23 or DOPRI5 fixed-step
size solvers where ITI Standard is used as default solver.
The model parameters chosen in the Code-Export Wizard can be set in the
Parameters pane of the S-Function block dialog.
You can export the S-function with the option "With FixedStep solver" when the
S-function should be connected in Simulink only with a discrete-time controller, or
the S-function as such (without Simulink components) through the Simulink Coder
is to be ported to a real-time platform. Compared with the internal Simulink
solvers, that often leads to performance gains. Therefore, even (if necessary)
oversampling can be used. This means that the SimulationX S-function works
internally with a smaller integration step size than the rest of the Simulink model.
S-Function with CVODE Solver
In this case the S-Function also contains the Sundials CVODE Solver beside the
model functionality. Therefore it is suitable for stiff systems in particular. Apart
from that the explanations for the Fixed-Step solver apply correspondingly.
The integration method iMode, the minimum step size dtMin, the maximum step
size dtMax, the absolute tolerance absTol, the relative tolerance relTol as well as
the maximum order of the integration method maxOrder can be selected in the
Solver pane of the S-Function block dialog. BDF which is the default and
Adams-Moulton can be selected as integration method.
Usage in Simulink
Again the model parameters chosen in the Code-Export Wizard can be set in the
parameters pane of the S-Function block dialog.
In order to use the exported model in MATLAB/Simulink, it must be processed
using the "mex" command in MATLAB before. This is achieved on the Post-
processing page of the Code-Export wizard (button Build - if MATLAB is
installed on your computer) or directly in MATLAB. To do this, select at first your
project directory as the working directory in MATLAB. To make your work easier,
an m-file "Build_S_Function.m" is created during export. It contains the "mex"
command with all necessary parameters. You can execute the m-file in MATLAB
or copy the content and execute it in the MATLAB command window. Note that
you have to specify certain data concerning the compiler selection when the "mex"
command is called for the first time.
To ensure that you can use the installed MATBAB version in the Code Export
wizard, the used versions of SimulationX and MATLAB have to be compatible.
SimulationX 3 9-61
That means, if you use SimulationX as a 64 bit version, the installed version of
MATLAB should be a 64 bit version as well.
After every export of the model the "mex" command must be executed again to
create the S-Function code from the changed source code. The source code of the
S-Function defines a mask with the names, default values and units of the exported
SimulationX parameters. The outputs of the S-Function are labeled with the names
of the corresponding connectors in SimulationX. This avoids mistakes during
parameterization and linking of the S-Function.
The built S-Function now can be used in a Simulink model via an S-Function
block. You can either generate the block by the Code-Export wizard or add the
block manually.
Generation of the S-Function block

The button Create Block will start the generation of the S-Function block. The
wizard opens (or creates) the Simulink model in the destination directory, creates
the S-Function block and enters the name of the S-Function. In order to get a valid
model, the S-Function binary is copied to the destination directory, too.
The following information is necessary for the creation of the S-Function block:
Destination directory Defines the folder for the Simulink model. If the directory
does not exist yet, it will be created.
Destination model Name of the Simulink model. If the model does not exist
in the destination directory, it will be created.
Block name Name of the S-Function block in the destination model.
Be aware that an already existing block with the same name will be replaced.
Manual creation of the S-Function block

Add an S-Function block from the User-Defined Functions library to your
Simulink model. In the parameter dialog of the block enter the project name under
S-function name. Note that this name is case-sensitive. The Simulink model and
the compiled code must be located in the same directory.
If you apply the changes for the first time, you could get an error message about
missing parameters. You can ignore this message. The field S-function
parameters will be filled automatically after the error message.
When the parameter dialog is closed, your block has the inputs and outputs and the
functionality of the exported SimulationX model. It may be connected to any
Simulink block.
9-62 SimulationX 3
Code Export
Usage within Simulink Coder

The produced S-Function can be also processed by the Simulink Coder in order to
generate code for one of the supported target platforms or computed using
Simulink Rapid Accelerator. To do so it is necessary to integrate additional source
code files in the build process. This is automatically done during the initialization
of the S-Function. It is no longer necessary to do it manually. The necessary files
are added to the S-Function parameter S-function modules.
To see which files are added, open the parameters dialog of the S-Function using
the "Look Under Mask" command of the context menu of the block.
In order to use dSPACE the files can also be added to the User-Make file (section
USER_SRCS).
9.5.3.4 NI VeriStand
With the project type NI VeriStand the real-time testing and simulation software
NI VeriStand from National Instruments is directly supported. It allows the real-
time simulation of SimulationX models.
The following limitation has to be considered.

Signals and variables are not supported, i.e. only the chosen parameters,
inputs and outputs can be accessed through the Simulation Interface Toolkit.
Figure 9.39: Code Export to NI VeriStand

Project Choose the project name and the project type.
Signal inputs Choose the inputs to be monitored and manipulated by the NI
VeriStand Workspace.
Outputs Choose the outputs to be monitored by the NI VeriStand
Workspace.
Parameters Choose the parameters to be monitored by the NI VeriStand
Workspace.
SimulationX 3 9-63
Curves Choose the curves to be monitored and manipulated by the NI

VeriStand Workspace.
Post-processing On this page you can compile and start the generated project.
Starts the build process of the project. The build
results are shown in the output panel.
The default value of the minimum calculation step size dtMin is not suitable for
real-time simulations. Therefore this step size needs to be adapted before the code
export process in the general simulation settings.
The minimum output step size dtProtMin is required to be an integer multiple
of the minimum calculation step size dtMin.
The minimum output step size dtProtMin has to be equal to the primary control
loop rate of NI VeriStand.
The default value of the primary control loop rate is 10000 sec which is suitable
for PC based tests. However a smaller rate may be required for tests on the real-
time hardware. The primary control loop rate (in micro seconds) can be adapted in
the NI System Explorer window when the Controller node of the system definition
file is selected.
9.5.3.5 NI LabVIEW Control Design and Simulation Module

Using this project type SimulationX models can be integrated with NI LabVIEW.
A valid license for the NI LabVIEW Control Design & Simulation Module from
National Instruments is needed.
The exported model is integrated with LabVIEW utilizing the NI External Model
Interface. This interface has the following limitations:
only one discrete sample time is supported
the sum: parameters + inputs + outputs must not exceed 25
If the exported model exceeds these restrictions an error message is produced

during initialization.
LabVIEW does not support the output of messages during the simulation run.
Hence trace messages of the model are shown only if an error occurs and the
simulation stops. LabVIEW allows scalar and vector parameters, inputs and
outputs. Even though SimulationX supports multi-dimensional values, these values
are flattened to scalars.
The build process was tested only under Windows as dll. Not under Mac OS,
Linux, or on real-time platforms. We support LabVIEW starting from Release
2009.
9-64 SimulationX 3
Code Export

Signal inputs Choose the inputs be used in the NI LabVIEW VI.
Outputs Choose the outputs to be used by the NI LabVIEW VI.
Parameters Choose the parameters to be accessed in the NI LabVIEW VI.
Please consider that the parameters are required to be constant
at runtime! Depending on the usage of parameters in the
SimulationX model it is possible that a parameter change is
only considered during the initialization phase. If you want to
change parameters at runtime you should use inputs instead.
Post-processing On this page you can compile and start the generated project.
Starts the build process of the project. The
build results are shown in the output panel.
This button is only active, if LabVIEW and
the Control Design & Simulation Module are
installed on your computer. Beside of this
one of the Microsoft Developer Studios has
to be installed too.
Figure 9.40: NI LabVIEW with external model from SimulationX
SimulationX 3 9-65
9.5.3.6 FMI
9.5.3.6.1 FMI for Model Exchange (1.0 and 2.0)

FMI (Functional Mock-up Interface) is a tool independent exchange format for
Model Exchange and Co-Simulation. It is developed and maintained by the
Modelica Association Project FMI (http://www.fmi-standard.org). A growing
number of simulation tools export and import of FMUs. FMUs are components
that implement FMU, they are zipped files ending with "fmu" and contain an
interface description as xml-file and the functionality as binary or C-source code.
In the variant Model Exchange the FMU contains the model functionality only, no
solver is included in the FMU.
The illustration in Figure 9.41 shows the schematic workflow of a FMI (for Model
Exchange) code export.
SimulationX
Model Solver
FMU for Model Exchange

Library (DLL)
FMU
Model
Code Export
h lib
C
Steps:
C-code generation (model equations)
Compilation and binding
Generation of model description
Packaging of files
Figure 9.41: FMI Code Export for Model Exchange

Project On the project page select the project type ("FMI for Model
Exchange") and specify the project name and the storage
location of the project files. By default the project has the same
name as the model. This name can be edited.
During code generation a file "generated.txt" with a list of the
names of all automatically produced files is created. When
enabling the checkbox "Delete existing project files" all files
listed in "generated.txt" are deleted before a new code
generation.
9-66 SimulationX 3
Code Export
FMI
Configuration
Option Description
Author String with the name and/or organization

of the model author
Version Version of the model
Description Short description of the model
Expose internal Expose internal variables of the model that

variables are not used in connections in the XML
description file. These variables are only
exposed by the model to inspect results.
Expose state Expose state references.

variables
Activate logging Mostly used to get debug information if

the model does not behave as desired.
Include source All needed C-sources and C-header files

code in FMU to compile and link the model
Platform Support Integrates the generated DLLs in the FMU

for selected platforms
Model Image Optional image file of model icon

(PNG)
SimulationX 3 9-67
Documentation Optional directory containing the model

documentation
Inputs On the inputs page select the input variables. The values of
these variables are defined outside of the model.
Outputs On this page select the output variables. These variables are
designed to be used in a model connection. So output variables
might be used in the calling function as input values to other
FMUs or other submodels.
Parameters On this page select the model parameters. The values of these
variables are constant after initialization, but may be changed
before a simulation run is started. For this example model no
parameters are specified.
External This page is only available from version 2.0 of FMI for Model
Resources Exchange. This page enables you to include external files into
the FMU. For more information, see section 9.5.3.6.3.
Code Generation With this page the generation of the code actually starts, but
before a symbolic analysis of the model takes place. All files
generated by the Code Export, including the XML model
description file, are stored in the specified project directory. At
the end of this process a zip-file is created to distribute the
FMU. The extension of the zip-file is .fmu.
Click on this button to specify additional
options for Post-processing. You can find
detailed information about these options
in the section 9.5.3.2.
Compiles and creates model-DLLs based
on the FMI configuration page. The
results of this process are displayed in the
output area. Then the generated DLLs
will be integrated into the FMU.
9.5.3.6.2 FMI for Co-Simulation (1.0 and 2.0)

FMI (Functional Mock-up Interface) is a tool independent exchange format for
Model Exchange and Co-Simulation. It is developed and maintained by the
Modelica Association Project FMI (http://www.fmi-standard.org). A growing
number of simulation tools export and import of FMUs. FMUs are components
that implement FMU, they are zipped files ending with "fmu" and contain an
interface description as xml-file and the functionality as binary or C-source code.
In the variant Co-simulation the FMU contains the model functionality and a
solver.
9-68 SimulationX 3
Code Export
Tool
Model Solver
FMU for Co-Simulation
Library (DLL)
Slave
FMU
Model Solver
Code Export
h lib
C
Steps:
C-code generation (model & solver)
Compilation and Binding
Generation of model description
Packaging of files
Figure 9.42: FMI Code Export for Co-Simulation
FMI for Co-Simulation defines interface routines for the communication between a
master and the individual simulation tools (slaves) in the co-simulation
environment. The most common master algorithm stops at each communication
point tci the time integration of all slaves, collects the outputs y (tci ) ( )from
all subsystems, evaluates the subsystem inputs u (tci ) ( ), distributes these
subsystem inputs to the slaves and continues the (co-)simulation with the next
communication step tci tci +1 = tci + hc +1 = + with fixed
communication step size . In each slave, an appropriate solver is used to integrate
one of the subsystems for a given communication step 1 tci tci +1 .
Figure 9.59shows the schematic workflow of a FMI (for Co-Simulation) code

export. A so generated FMU contains also a solver and can work as a slave
simulator in a co-simulation environment independent from SimulationX.

Project On the project page select the project type ("FMI for Co-
Simulation") and specify the project name and the storage
location of the project files.
By default the project has the same name as the model. This
name can be edited. During code generation a file
"generated.txt" with a list of the names of all automatically
produced files is created.
SimulationX 3 9-69
For FMI 2.0 you can select which solver is added to the
FMU either CVODE or the Fixed-step solver. The
Fixed-step solver is recommended for integration of the
FMU with real-time platforms like hardware-in-the-loop
systems. Please take care on correct specification of the
step-size parameters in that case and check whether the
model can be simulated in a stable and accurate way.
When enabling the checkbox Delete existing project files
all files listed in "generated.txt" are deleted before a new
code generation.
FMI Configuration
Option Description
Author String with the name and/or

organization of the model author
Version Version of the model
Description Short description of the model
Platform Integrates the generated DLLs in the

Support FMU for selected platforms
Model Image Optional image file of model icon

(PNG)
Documentation Optional directory containing the

model documentation
Inputs On the inputs page select the input variables. The slave
receives the values of these input variables before a
subinterval is simulated.
9-70 SimulationX 3
Code Export
Outputs On this page select the output variables. After the simulation
of the subinterval, the values of these outputs are transmitted
to the master.
Parameters On this page select the model parameters. In addition to that
the step-size and tolerance settings of the integrated solver
are provided as parameters.
External This page enables you to include external files into the
Resources FMU. For more information, see section 9.5.3.6.3.
beforehand a symbolic analysis of the model takes place. All
files generated by the Code Export, including the XML
model description file, are stored in the specified project
directory. At the end of this process a zip-file is created to
distribute the FMU. The extension of the zip-file is ".fmu".
Post-processing Click on this button to specify additional
options for Post-processing. You can
find detailed information about these
options in the section 9.5.3.2.
Compiles and creates model-DLLs based

on the FMI configuration page. The
results of this process are displayed in
the output area. Then the generated
DLLs will be integrated into the FMU.
9.5.3.6.3 External Resources

Model elements (e.g. Modelica.Blocks.Tables.CombiTable2D) use string
parameters to refer to files. These files are loaded at the start of a simulation
calculation.
The page External Resources enables you to integrate such files in order to get
an executable FMU. The FMI for Model Exchange 1.0 project type does not
support the integration of external resources because version 1.0 does not define a
location of the resources folder during the runtime of a FMU.
The list at the External Resources page contains all string parameters of the
model. Activate the checkbox for all parameters referencing to a file, which has to
be integrated into the FMU.
SimulationX 3 9-71
Figure 9.43: Definition of external resources
The Code Export copies the checked files into the resources subdirectory during
the code generation of the FMU. The values of the parameters are internally
adjusted in order to find the files automatically during the execution of the FMU.
If you selected a parameter as a FMU parameter and import the FMU in your target
tool, then you can assign an absolute path at the target computer or refer to a file in
the resource directory (e.g."fmu://resources/test.txt").
Figure 9.44: Referencing a FMU resource file
9.5.3.7 CarSim, BikeSim, TruckSim component (VehicleSim)

VehicleSim is a toolset for the efficient simulation of cars, trucks and motorcycles
from the Mechanical Simulation Corporation. The VehicleSim API (Application
Programming Interface) is used for the seamless integration of SimulationX
models within VehicleSim via Code Export.
9-72 SimulationX 3
Code Export
SimulationX models that are exported to VehicleSim contain a fixed step solver.
Before carry out the code export it is useful to test in SimulationX whether the
model can be computed by a fixed solver and which step size should be used. The
step size can be changed in VehicleSim.

Project On the project page select the project type ("CarSim,
BikeSim, TruckSim component") and specify the project
name and the storage location of the project files. By default
the project has the same name as the model. This name can
be edited. During code generation a file "generated.txt" with
a list of the names of all automatically produced files is
created. When enabling the checkbox "Delete existing
project files" all files listed in "generated.txt" are deleted
before a new code generation.
Inputs On the inputs page select the inputs for the SimulationX
model which can be connected to VehicleSim variables by
entering VehicleSim name. Inputs which are not assigned to
a VehicleSim variable are set to zero during the simulation
run.
Outputs On the outputs page select the output variables. Model
variables which shall only be observed in VehicleSim can
also be selected. If no VehicleSim Name is entered the
variable is added to the VehicleSim database using its
SimulationX identifier. VehicleSim supports strings with a
maximum length of 8 characters using ALL CAPS
(uppercase). Hence the SimulationX identifier is truncated
and transformed to ALL CAPS before adding it to the
VehicleSim database. If a given VehicleSim Name cannot
be found in the VehicleSim database the variable is added
using this name.
VehicleSim uses SI base units for its computation in the
same way as SimulationX does. Hence it is not necessary to
take care for unit conversions at all.
Parameters On this page select the model parameters which shall be
changeable in VehicleSim. A VehicleSim name can also be
entered. The parameters keep their original values from
SimulationX if they are not changed in VehicleSim.
SimulationX 3 9-73
files generated by the Code Export are stored in the
specified project directory.
Post-processing Select here the development environment under which the
generated project is to be compiled. SimulationX recognizes
automatically the Microsoft C compilers installed on your
system.
For information about development environments supported
by SimulationX, refer to section 2.1.2.
The result of the compilation is an executable program. It
contains all necessary calls to the VehicleSim API functions
to connect the inputs and outputs and to execute the
necessary computations.
Click on this button to specify additional
options for Post-processing. You can find
detailed information about these options in
section 9.5.3.2.
Compiles and builds your generated project.

The compilation and build results are
displayed in the output area.
Integration and simulation in VehicleSim

To integrate the generated executable within VehicleSim you have to select it as an
external wrapper program. Open the prepared VehicleSim dataset by clicking on
the SimulationX button on the Run Control screen.
Figure 9.45 The SimulationX dataset
Select Use external wrapper program and select the executable model
generated by SimulationX as shown in Figure 9.46.
9-74 SimulationX 3
Code Export
Figure 9.46 Select the generated executable as external wrapper program
The computation starts as usual by clicking on Run Math Model on the main page.
To change parameters enter their name followed by the new value (in SI units) to
the to the command edit field.
The solver parameters of the SimulationX model can be changed here too. The
generated executable adds parameters for the integration step size (SIMX_DT) and
the integration method (SIMX_MODE) as parameters to the VehicleSim database.
They can be changed as shown above.
The SimulationX integration step size should be smaller or equal to the

VehicleSim step size. The VehicleSim step size should be an integer multiple of
the SimulationX integration step size SIMX_DT. In this way the SimulationX
model can be computed using a smaller step size than the step size used by the
VehicleSim model.
The parameter SIMX_MODE changes the used integration method as follows:
SIMX_MODE Integration Method

0 Euler Forward
1 ITI Standard
2 Heuns Method
SimulationX 3 9-75
3 RKF23
4 DOPRI5
For more information see the ITI Tutorial 20 "Model Export to CarSim, BikeSim,
TruckSim"
(http://www.iti.de/fileadmin/Ressourcen/Tutorials/20_Code_Export_CarSim.pdf).
9.5.3.8 ETAS LABCAR

LABCAR is the modular HiL Testing System for Automotive Electronic Control
Units from the ETAS GmbH. As a real-time operating system a RT Linux is used,
that runs on a PC. The models are configured and linked with each other and with
the hardware I /O via the tool Labcar Operator Integration Platform (Connection
Manager) on the host computer.
It is possible to combine several SimulationX models with different project names

in ETAS LABCAR and run simultaneously.
SimulationX models that are exported to ETAS LABCAR contain a fixed step
solver. Before carry out the code export it is useful to test in SimulationX whether
the model can be computed by a fixed solver and which step size should be used.
The source files generated by the code-export are copied when a configuration is
deployed on the real-time platform. There the source code is compiled.
Dialog Page Description

Project On the project page select the project type ("ETAS
LABCAR") and specify the project name and the storage
location of the project files. By default the project has the
same name as the model. This name can be edited. During
code generation a file "generated.txt" with a list of the names
of all automatically produced files is created. When enabling
the checkbox "Delete existing project files" all files listed in
"generated.txt" are deleted before a new code generation.
Inputs On the inputs page select the inputs for the SimulationX
model. ETAS LABCAR supports scalar real variables as
inputs.
Outputs On the outputs page select the output variables. ETAS
LABCAR supports scalar real variables as outputs.
9-76 SimulationX 3
Code Export
Parameters On this page select the model parameters which shall be

changeable in LABCAR. For parameters (Calibration
Variables) different data types are supported, as well as
vectors and matrices. The parameters retain their original
values from SimulationX if they are not changed in
LABCAR.
files generated by the Code Export are stored in the specified
project directory.
9.5.3.9 B&R Automation Studio

With this project type, a SimulationX model can be integrated and used as a
program object in B&R Automation Studio. The user can finally choose whether
the target is a real PLC or one simulated with "ARSim". This allows the using of,
in SimulationX developed, control algorithms directly in a PLC control program.
Another use case is the export of a plant model in order to test a control program
written in B&R Automation Studio.
SimulationX models that are exported to B&R Automation Studio contain a fixed
step solver. Before the code export, it is advisable to test in SimulationX whether
the model can be computed by a fixed solver and which step size should be used.

On the project page select the project type ("B&R Automation
Studio") and specify the project name and where the project
files will be saved. By default, the project has the same name
as the model. This project folder contains all necessary files
B&R Automation Studio can access later on.
During code generation, a file called "generated.txt" is created
with a list of names for all automatically produced files. When
the checkbox "Delete existing project files" is ticked, all files
listed in "generated.txt" are deleted before new code is
generated.
Inputs Choose the inputs that should be included with the exported
model for manipulation in B&R Automation Studio.
Outputs Choose the outputs that should be included with the exported
model for monitoring and using in B&R Automation Studio.
Parameters Choose the parameters to be monitored and manipulated by
B&R Automation Studio.
SimulationX 3 9-77
Post-processing This page starts the actual C-code generation once the global
symbolic analysis is complete. All files generated during the
code-export are saved in the specified project directory.
In addition to the code of the model, also the configuration
files are generated to provide a convenient way of integrating
them as program object into B&R Automation Studio.
Integration into B&R Automation Studio
Choose "Insert/Insert Object" and then the category "Program" with the template
"Existing Program" to import the exported model in a B&R Automation Studio
project.
On the next dialog page, select the project folder that was created for the code-
export. This folder is marked with an icon (see Figure 9.47). On the following
page, complete the import process with the "Finish" button. Once done you can use
the inputs, outputs and parameters as variables in your own code.
For more information on the topic "Program Objects", please refer to the B&R
Automation Studio help section "Programming/Programs" and take special note of
"ANSI C POUs".
Figure 9.47: Workflow code export to B&R Automation Studio
9-78 SimulationX 3
Code Import
9.6 Code Import

9.6.1 FMU Import
A FMU (Functional Mockup Unit) is a zip-file with extension ".fmu" according to
the FMI specification (www.fmi-standard.org) and contains all data and
components to simulate a model in a simulation environment (see 0). Basically
these are the description of the interface (inputs, outputs, parameters) in a
XML-file and the model and solver functionality as binary or source code in
programing language C. For FMU import in SimulationX the FMU needs to
contain the functionality as Windows DLL (32 bit or 64 bit depending on the
version you are using).
To import a FMU in SimulationX select the menu Insert Functional Mockup

Unit.
After selecting the FMU in the "Open File" dialog the dialog for importing a FMU
appears (see Figure 9.48).
Under "Implementation" it is displayed whether it is a Model Exchange or a

Co-simulation FMU. If both implementations are available inside the FMU the
listbox is enabled and you can select, which version shall be imported.
In this dialog you can make the following settings.
Option Description
Expose Interval Variables By activation the local FMU variables will be
provided beside output variables for logging of
results. You should use these local variables in
result windows only but not inside the
SimulationX model. According to the FMI
specification this is only allowed for
FMI-outputs.
SimulationX 3 9-79
Ignore Array Variables FMI variables of higher dimensions are imported

as scalars. This might lead to a large number of
variables during import which can slow down
compilation and simulation. This amount of data
can be reduced by activation of that option.
Use Modelica Pins for Inputs The FMU inputs and outputs are not created as
and Outputs ITI connectors (signal inputs and signal outputs)
but as Modelica connectors.
Open Element Type in The automatically generated element type opens

TypeDesigner up in the type designers to make any changes.
This option is selected by default.
Insert Element as Component The generated element type is instantiated and

in Model placed as an element in the model. This option is
selected by default.
Figure 9.48: FMU Import Dialog
Press the button Info to see general information about the FMU. The import
recognizes automatically whether it is an FMU of version 1.0 or 2.0 and adapts the
import procedure accordingly.
If you exit the dialog with OK, an element type is created, according to the
FMU and your settings. The generated block has exactly the inputs, outputs and
parameters which are defined inside the FMU. On the page "FMI Settings" of the
properties window you can change the following parameters:
9-80 SimulationX 3
Code Import
Parameter Description
FMU File The complete filename of the FMU is stored in this
parameter. Please use it only to adapt the location of the
imported FMU-file if you moved the FMU to a different
folder. Dont use this parameter to reference to another
FMU. If the referenced FMU is not identical to the
imported one an error message will be generated by the
FMU. The content of this error message is FMU specific
but it should point out that the GUID (general unique
identifier) of the referenced FMU is not equal to the
imported one.
Keep unzipped FMU Just before the simulation starts the FMU is unzipped to a
temporary folder which is deleted after the simulation
run. If you want to avoid that you need to activate that
parameter. In that case the FMU is unzipped to the folder
specified by the parameter "FMUUnzipFolder" and can
be reused in subsequent simulation runs. This saves time
especially for larger FMUs.
Folder for unzipped When "keep" is active this parameter is enabled. You can
FMU enter the folder for unzipping the FMU. Please take care
to use different folders when you use multiple FMUs
simultaneously.
Visibility of FMU This setting is transferred directly to the FMU and is used
by certain FMUs. According to the FMI specification the
parameter might be used to display a GUI which might
be included within the FMU.
Logging of FMU This setting is transferred directly to the FMU and is used
by certain FMUs. According to the FMI specification the
parameter might be used in order to switch on logging of
messages for debugging. The possibly generated
messages are displayed in the SimulationX output
window.
Is Tolerance defined? This setting is transferred directly to the FMU and is used
(not for FMUs for by certain FMUs. According to the FMI specification the
Co-Simulation parameter might be used to inform the FMU whether the
Version 1.0) applied solver is tolerance-controlled.
When the Fixed-step solver is applied, false can be used.
For the other solvers true is recommended.
SimulationX 3 9-81
Tolerance This setting is transferred directly to the FMU and is used

(not for FMUs for by certain FMUs. According to the FMI specification this
Co-Simulation parameter can be used to inform the FMU about the
Version 1.0) tolerance settings of the applied solver in order to adapt
internally used tolerance settings. For the variable step-
size solvers of SimulationX, this value should not be
greater than the tolerance setting from the solver control
dialog.
Interactive? This setting is transferred directly to the FMU and is used

(only for FMUs for by certain FMUs. According to the FMI specification this
Co-Simulation parameter can be used in order to set the FMU in an
Version 1.0) interactive mode.
FMI Mime Type This setting is transferred directly to the FMU and is used
Co-Simulation parameter can be used to reference to the used simulation
Version 1.0) model for tool based co-simulations.
FMU Time Out This setting is transferred directly to the FMU and is used
Co-Simulation parameter can be used to specify a time out for network
Version 1.0) based co-simulations.
Strict FMI The FMI specification version 1.0 lets some room for
Compatibility Mode interpretation regarding the allowed calling sequence of
(only for FMUs for functions. FMUs generated by certain tools require a
Model Exchange more strict calling sequence than others which might
Version 1.0) reduce the performance of the simulation. The FMU
import recognizes such FMUs normally and sets this
parameter automatically. If problems occur anyway you
can try to solve it by changing this parameter.
For FMUs for Co-Simulation the additional dialog page "Master Algorithm" is
generated. Here you can enter the communication step size. SimulationX embeds
Co-Simulation FMUs as discrete subsystems. That means the data exchanges
happens at certain communication time instances only. In between inputs and
outputs are considered as being constant and an additional delay is introduced.
This might lead to stability and accuracy issues especially when you interconnect
continuous FMUs for Co-Simulation. Reduce the communication step-size in that
case. If you dont succeed you should use FMI for Model Exchange instead.
9-82 SimulationX 3
Code Import
9.6.2 Code Import from Simulink

SimulationX can import source code generated by the Simulink Coder (formerly
Real-Time Workshop (RTW)) as an FMU or using the RTWImport element. This
chapter describes both possibilities using the following Simulink model.
The Simulink coder generates in both cases source code for a DLL which can be
used in SimulationX. The DLL uses the fixed step solver of Simulink which has
been selected before the creation of the DLL. The simulation calculation runs
separately in SimulationX and the generated DLL. The data transfer between the
DLL and SimulationX will be done at the sample time steps.
Figure 9.49: Simulink model with interface to SimulationX
9.6.2.1 Code Import by FMU
Figure 9.50: Schema of Code Import (FMU)
SimulationX 3 9-83
The Simulink Coder generates from the Simulink model a FMU for Co-
Simulation, which can be imported by the FMU Import of SimulationX (see
section 9.6.1).
The interface of the FMU provides access to external inputs, outputs and
parameters of the Simulink model. Only scalar values of type Real, Boolean and
Integer can be transferred between SimulationX and the FMU.
Installation
The code export target has to be installed by a separate setup. The setup contains
the target template and a sample model. The setup copies the FMI Co-Simulation
Target for Simulink Coder to <MATLABROOT>\rtw\c\fmicosim. The directory
<MATLABROOT>\rtw\c\fmicosim\m must be added to the search path of
MATLAB. The C compiler of the Microsoft Visual Studio (Version 2010 or
higher) is supported as compiler.
Creation of FMU
The following options must be set for the solver in Simulink before the code
generation can start.
Key word Value
StartTime 0.0 (StopTime will be defined in SimulationX)
Type Fixed-step
Fixed-step size Needed communication step width (Auto is not allowed!)
Mode Single Tasking
First, fmicosim.tlc must be selected as the system target file.
Figure 9.51: Selection of FMU Target
9-84 SimulationX 3
Code Import
Then the template makefile has to be selected according to the used MATLAB
Release and the target platform for the FMU.
You can assume the appropriate setting from the following list:
MATLAB Release 2010 and later
o x32 Windows: fmi_malloc_vc.tmf
o x64 Windows: fmi_malloc_vcx64.tmf
MATLAB Release 2009:

o x32 Windows: fmi_malloc_vc_R2009.tmf


o
Figure 9.52: Definition of Template Makefile
Now you can start the code export and import the output file <modelname>.fmu in
SimulationX by using the FMU Import.
SimulationX 3 9-85
Figure 9.53: SimulationX Model with imported FMU
9.6.2.2 Code Import using RTW Import Element

Option Code Import from Simulink/RTW is required for the import. The option
contains the code export target, the RTWImport element and a sample model.
Figure 9.54: Schema of Code Import from RTW
Installation
The code export target SimulationX has to be installed. The installation is done by
copying the folder simx from the samples directory
<Samples>\Co-Simulation\src\matlab\RTWImport to the targets folder of
Matlab <MATLABROOT>\rtw\c. Then SimulationX is available in the target
9-86 SimulationX 3
Code Import
selection list. The C compiler of the Microsoft Visual Studio (Version 2003 or
higher) is supported as compiler.
Creation and usage of the exported Simulink model

The communication of the Simulink model and SimulationX will be done over
external inputs and outputs. All inputs and outputs must be scalar values of the
data type real. The following options must be set for the solver:
Key word Value
StartTime 0.0 (StopTime will be defined in SimulationX)
Type Fixed-step
Fixed-step size Needed communication step width (Auto is not allowed!)
Mode Single Tasking
When you have selected simx.tlc as system target file then you can build the DLL
for usage in SimulationX.
Figure 9.55: Selection of the SimulationX target file
The SimulationX model uses the element type Realtime Workshop Import of the
library Signalblocks/Co-Simulation to integrate the DLL. The parameter
RTW DLL allows selecting the DLL which has been created by Simulink.
The dimension of the input- and output vector must be set according to the in- and
outputs of the Simulink model.
SimulationX 3 9-87
Figure 9.56: SimulationX model with RTW Import block
9.7 Interfaces to other Tools

9.7.1 Optimization with OptiY
If the optimization tool OptiY Vs 4.1 from OptiY GmbH is installed it can be
directly started by the menu Extras Tools OptiY Optimization. Please
read the OptiY documentation for how to analyze and optimize SimulationX
models.
9.7.2 Optimization with Isight

The SimulationX component allows Isight to interact with SimulationX. The
primary functions of this component are to send scalar parameters from Isight to
SimulationX, run the simulation in the time domain, and retrieve scalar result data
from SimulationX.
It is important to make sure that the environment is set up properly to allow the
SimulationX component to interact with the SimulationX software.
Isight Vs 3.5-1 must be installed
SimulationX Vs 3.7 must be installed
SimulationX Component Vs 2.0.6 must be installed
9.7.2.1 Component Editor

1. Drag-and-Drop the SimulationX component to your Isight workflow.
9-88 SimulationX 3
Interfaces to other Tools
Figure 9.57: Workflow diagram with SimulationX Component
2. Double-click the SimulationX component icon to start the component editor.

The SimulationX component editor dialog box appears (see Figure 9.58).
3. Click the Open button. The File Open dialog appears.
4. Select any SimulationX model or project file you want to exchange data with.
5. Click Open. If SimulationX is not yet started a new instance of SimulationX
will be invisibly created. If SimulationX is already running the selected
SimulationX model file will be opened by the most recently started
SimulationX application.
6. Select an element from the model explorer of the SimulationX component
editor dialog. The Parameters and Results tables display the parameters and
result variables of the selected element, respectively.
7. You can click the Open button to change the SimulationX model file.
8. You can click the Refresh button to update the model explorer with the
selected SimulationX model file.
9. Click OK to save all changes and close the component editor.
9.7.2.2 Mapping of Parameters and Result Variables

The mapping defines how Isight passes information to and retrieves information
from SimulationX.
1. Open the SimulationX component editor.
2. Select the value of a parameter or a result variable of an element.
3. You can edit the name used to identify the Isight parameter in the yellow
highlighted text box (see Figure 9.58).
4. Click the Add button to add the mapping. The corresponding Isight
parameter will be automatically created by the SimulationX component.
SimulationX parameters map to Isight input parameters and SimulationX result
variables map to Isight output parameters.
5. You can change the value or data type of the created Isight parameters in the
parameters view.
SimulationX 3 9-89
Figure 9.58: SimulationX Component Editor Dialog Box
6. You can delete one or more mappings by selecting the mapping(s) from the
mapping table and clicking the Remove button.
7. Click the OK button to save the mapping information.
9.7.3 Optimization with optiSLang

If the optimization tool optiSLang Vs 4.0 from Dynardo GmbH is installed it can
be directly started by the menu Extras Tools optiSLang Optimization.
Please read the optiSLang documentation for how to analyze and optimize
SimulationX models.
9.7.4 FEM-Import
If the SimulationX FEM-Import is installed it can be directly started by the menu
Extras Tools FEM-Import. Please check the documentation in the
Mechanics Library Manual (Mechanics/Import Flexible Body) and the installed
tutorials for more information on the FEM-Import. Setup to install the FEM import
can be found on the installation DVD.
9-90 SimulationX 3
SafetyDesigner
9.8 SafetyDesigner
9.8.1 Introduction
In many industry sectors, potential risks are assessed by applying classical risk
analysis techniques, such as Failure Mode and Effects Analysis (FMEA) or Fault
Tree Analysis (FTA). The considerable effort required for this type of analysis is
justified by the nature of the hazards that may arise during operation and by the
financial stakes involved. FTA and FMEA provide valuable information about
various systems, but are primarily manual methods. As a result, it is not
uncommon for FTA and FMEA to take place only once or twice in the life cycle of
a system. In order for FTA or FMEA to be incorporated into the design process
efficiently, the SafetyDesigner in SimulationX helps overcome the problems
inherent to such manual techniques by estimating the reliability of the system
repeatedly throughout the product life cycle.
9.8.2 Global Workflow of Model based Safety Design

9.8.2.1 Conventional Safety Analysis
FTA and FMEA provide important information about a systems reliability and
safety. Available tools are based on numerical and stochastic approaches requiring
manual input of basic events (failures) and their propagation throughout the system
up to the top event as well as the corresponding data, such as failure rates for
example. As a result, FTA and FMEA are usually performed only once or twice in
a systems entire lifecycle. The (functional) design process, however, includes the
layout of the system structure. This topological information can be easily re-used
instead of defining it from scratch each time.
9.8.2.2 Model based Safety Design

Model-based safety design combines the design based on a physical model with
proven methods of safety analyses. Models must be both parameterized and
extended with input information for safety analyses. Model libraries can be used to
store typical default failure descriptions (failure modes) and data. Moreover, only
the effects of local failure and failures at a components inputs with respect to
output deviations have to be specified. This data has to be provided only once for
each model type in the library.
Upon instantiation, i.e. when a component is added to the system model, only a
few parameters have to be adjusted if the failure data of this instance differs from
the type in the library. The rest of the data is inherited automatically. The resulting
models, annotated with failure data, can be stored in libraries.
Since the goal is to provide all the required data for FTA and FMEA within the
framework of SimulationX, the SafetyDesigner converts the intrinsic topological
SimulationX 3 9-91
information of the physical model to the description language for HiP-HOPS, the
tool which is used as the analysis backend for FTA and FMEA.
HiP-HOPS come with a synthesis functionality which automatically generates fault

trees from the model. Furthermore, HiP-HOPS can analyze fault trees with respect
to the specified system output port.
Comparing analysis results with the defined safety goals may require model
modifications (replacing components, structural changes). As modifications may
change the systems failure behavior, the synthesis should be performed
immediately to allow for a new analysis to incorporate any changes.
Automatically generated fault trees are less error-prone than manually generated
ones, while the process is also faster and allows for more iterations. It can thus be
used already at early stages of the development to ensure a high quality of the
results.
9.8.3 Model based Safety Optimization

Improving the safety of a system involves many design options each of which
poses a trade-off between reliability and costs. Automated safety analyses can help
the designer in the decision making process, but structural changes in the model
can hardly be automated on the other hand and require manual input.
9.8.3.1 Semiautomatic Structural Optimization of Models

Traditional methods, such as parameter variations, are usually employed to
optimize the structure of a simulation model. The criteria are quantified by an
objective function that ideally combines all criteria into one single value from
which the minimum is to be determined. As this is not always possible, a Pareto
analysis is applied whose result is a set of solutions with equal distances from the
optimum. For situations when not only parameter values are changed, but also
components or entire subsystems are replaced, such modifications need to be
manageable automatically.
9.8.3.1.1 Requirements
When parts of a model are replaced, the modified model must meet particular
requirements with respect to the original model. The new model must be a
functional and physically correct model that can still be simulated. Secondly,
safety tools (synthesis and analysis) and the optimization algorithm must remain
applicable to the changed model.
Model Requirements
In order to maintain a working model after replacing any model parts, some
connection conditions must be fulfilled:
9-92 SimulationX 3
SafetyDesigner
Connections between the replacing part and the rest of the model must
remain intact including names and parameters of the connections.
Parameter and variable references from the unchanged part of the model
must be kept.
Optimization Requirements
In order to continue the optimization after the modification,
all optimization parameters and
all variables affecting the objective function
must be maintained.
9.8.3.1.2 Changing the Model Structure

The simplest transformation function is the substitution of one component with
another one, or more strictly speaking: the substitution of one instance of a model
with an instance of another model. The new models interface must fit with the old
(remaining) model. The topology of the model remains the same at the level where
the instance is replaced.
SimulationX is based on the concept of replaceable types. The minimum

requirements for the interface which all types have to meet can be specified by
using a template type. The user can define a list of types which can be used for the
replacement. The replaceable type acts as the optimization parameter, while the
individually selected type identifier represents one possible value for this
parameter.
For more complex changes of the model topology, the developer must take
additional measures in order to maintain the connection conditions. The
substitution of a simple pump by a redundant configuration using two pumps with
a switching device would be an example.
9.8.3.2 Handling of Design Choices in Models Modeling Concept

One possibility to facilitate automated changes to the model structure is to define
locations during the modeling process to be considered for structural variations.
A template type needs to be defined for the replaceable type specifying the
minimum interface requirements that each model variant must meet. It contains
connectors and parameters that are used outside these types.
This concept is easily applicable to the replacement of simple components. More

complex structures should be handled in the substitution process and must then be
wrapped by a new (compound) type:
1. Select a component or a more complex structure consisting of various
components which are to be replaced in the optimization process.
SimulationX 3 9-93
2. Identify the interface with the rest of the system (connectors, parameters and
variables communicating with the environment).
3. Build a sub-model containing this interface.
4. Repeat steps 1 to 3 with other potential variants (components or structures).
Ensure both models have the same interface.
5. Define a template type with this interface.
6. Create a type with the replaceable type using this template type.
Any complex changes to the structure adhering to the basic functionality of the
model can be converted in this way and must be taken into account during the
development of the model.
The components of sub-systems with the best optimization potential can be

determined by safety analyses with the original model. For instance, preferential
candidates are minimal cut sets with the highest probability determined by FTA or
cuts sets of only one component.
9.8.3.3 Description of Design Choices for Optimization - Implementations

Locations of variation (not only structural ones) are defined at the simulation
model level. Their existence must be communicated to the optimizer. It needs
information about reliability and costs for each alternative at these locations.
This is achieved by so-called implementations within the safety information for

each model and component. An implementation represents exactly one design
alternative for the current component and consists of a complete set of safety data.
It helps specify whether this current data came from another model or is defined
directly in the implementation.
This data is used by the optimizer to determine the minimum or maximum of the
object function for the given limit states and alternatives. The result of the
optimization is a list of trade-offs in which one implementation is selected for each
location of variation. When the designer selects one trade-off from the list, the
corresponding implementations need to be applied to the model, which requires
each list of parameters for the implementation to be set for the model. Replaceable
type parameters may be included in this list as well and allow for simple structural
changes to be handled like parameter changes.
9.8.4 Extension of SimulationX

9.8.4.1 Software Structure
HiP-HOPS developed by the University of Hull is the underlying analysis tool for
the SafetyDesginer in SimulationX and requires an input file with the topology of
the model and all data. Results are stored as HTML/XML files which can be
accessed by an HTML browser. Errors and warnings are sent to the standard
output.
9-94 SimulationX 3
SafetyDesigner
Input File
SimulationX
run HTML
HiP-HOPS
Figure 9.59: HiP-HOPS integration
9.8.4.2 Extension of GUI SafetyDesigner

The SafetyDesigner is the primary tool in SimulationX to specify data for safety
analyses. A self-explanatory and clear GUI with a non-modal, multi-page dialog
window forms the basis. Each page concerns a particular subset of the data. The
design is similar to the TypeDesigner in SimulationX.
The SafetyDesigner can be opened through the context menu of models or

components (Figure 9.60).
Figure 9.60: Starting the SafetyDesigner through the context menu
Each page has a headline with the name of the page and a short description of the
available settings.
The SafetyDesigner consists of the following pages which are listed on the left side
of each section:
1. General Information
2. Basic Events
3. Common Cause Failures
4. Output Deviations
SimulationX 3 9-95
5. Simulation parameters and their values
Pages
Implementations
Figure 9.61: Common parts of SafetyDesigner pages
Each set of pages is assigned to an implementation. The implementation can be

selected using the tabs at the bottom of each page (Figure 9.61). The tab with
creates a new implementation. One implementation is already present by default.
If a component model is instantiated, the failure data is inherited by the instance

automatically and is marked by a different text color of the entries in the
SafetyDesigner. Blue means it is inherited. In case the data is changed on the
model level, this change is propagated to this instance automatically. If, however,
an entry is changed in this instance, the color switches to black immediately. This
means that the data is no longer inherited and changes to the model have no effect
in the active instance.
9.8.4.2.1 Page General

On the page General, basic properties of an implementation as well as data which
is common to all implementations can be specified (Figure 9.62).
The name for each implementation is derived from the name of the model or
instance and is unique within this model or component, but it can also be changed.
9-96 SimulationX 3
SafetyDesigner
Figure 9.62: Page General
The origin of the failure data for each component can be selected from a combo
box (Figure 9.63).
Figure 9.63: Origin of the failure definition
Following options are available:

Not defined. This option is no longer supported.
Defined here The failure behavior is completely defined at this
model/instance. The complete definition can be found in
this SafetyDesigner.
Defined in the This model/instance is a compound. The failure
contained components. behavior is defined by the components inside, but not
here.
SimulationX 3 9-97
Defined in the The final definition of the failure behavior is merged

contained components from the contained components and the definitions in
and here. the current SafetyDesigner.
Defined in the assigned An implementation could be identified with another
type model and the definitions are taken from there. This is
basically useful, if replaceable models are used.
Defined in the assigned The final definition is merged from the other model and
type and here. the current SafetyDesigner.
The field Costs can be filled with an arbitrary number. This number comes without
any unit and is used to calculate the cumulative costs for the entire system and is
used during optimizations.
When the checkbox Current Implementation is ticked, the implementation is

taken into account for analyses unless any optimizations are scheduled. As the user
can switch between different implementations, this box can only be checked for
one implementation at a time.
Risk Time is common to all implementations. This number specifies the time when
failures of this instance may occur. If this parameter is not set, the global value
defined in the options of the Fault Tree Generation Wizard applies (see section
9.8.4.3.1).
The button Reset Data to default reads the data inherited from the model and
copies it to the instance. All former changes of the data in the instance are lost. All
text entries are colored blue and changes to the model data have effect on the
instance again.
If there is more than one implementation, the selected implementation can be

removed using the button Remove Implementation. All data belonging to this
implementation will be lost.
9.8.4.2.2 Page Basic Events

The page Basic Events (Figure 9.64) allows for local failure modes to be defined
which may be caused by this component.
Basic events are defined and listed on the left side of the page. The two buttons
above the list are used to create new basic events or to remove existing ones. On
the right side, properties of the selected event are shown with a short description.
9-98 SimulationX 3
SafetyDesigner
Figure 9.64: Page Basic Events
The combo box for the Calculation Mode (Figure 9.65) defines how the
probability of occurrence of this event is calculated with various modes, each
having a definite set of parameters.
Figure 9.65: Calculation Modes for Basic Events
These calculation modes are summarized in Table 9.3.
SimulationX 3 9-99
Calculation Mode Parameters Description

No Calculation - This event never occurs. This is the
default setting.
Constant failure Failure rate It assumes an exponential distribution.

and repair rates Repair rate The formula for unavailability is:

= (1 (+) )
+
If no repair rate is given, =0 is assumed.
The unavailability also depends on the
risk time t.
Constant failure Failure rate It is calculated as the above with repair
and mean time to MTTR rate
repair (MTTR) = 1 / MTTR.
Mean time to MTTF It is calculated as the above with failure

failure (MTTF) Repair rate rate
and constant repair = 1 / MTTF.
MTTF and MTTR mix between MTTR and MTTF

Fixed Fixed The value is taken directly.
unavailability unavailability
Binomial failure Failure rate This model is useful for representing

model Repair rate situations where m failed components out
of n will result in failure.
Number of
failures (n)
Minimum
number of
failures (m)
Poisson failure Failure rate This method can be used to model the
model Number of effects of limited numbers of replacement
components components.
(n)
Number of
spares (s)
9-100 SimulationX 3
SafetyDesigner
Dormant failure Failure rate This mode can be used when a component
mode with MTTR is a standby component and only activated
periodic inspection when its primary fails.
Inspection
interval
Variable Slope Calculates the three segments of the
Failure Rate Parameter 1 bathtub curve (1 decreasing, 2 constant, 3
Scale increasing failure rate) from 3 different
Parameter 1 Weibull distribution curves
End Interval 1
Scale
Parameter 2
End Interval 2
Slope
Parameter 3
Scale
Parameter 3
Table 9.3: Calculation modes for basic events
9.8.4.2.3 Page Potential Common Cause Failures (PCCF)

On this page, potential common cause failures can be defined (Figure 9.66).
Potential common cause failures (PCCF) are placeholders for external events that
affect different components at the same time. They can be used like local basic
events for defining output deviations, but occur globally. That means that more
than one component can react to global events. The actual common cause failures
(ACCF) and the mapping of PCCF to ACCF can be defined with the Fault Tree
Generation Wizard (see section 9.8.4.3.2 and 9.8.4.3.3 resp.)
A list of currently defined PCCFs is displayed on the left side of this page. The two
buttons above the list are used to create new PCCFs or to remove existing ones.
Defining a PCCF also requires a name for identification purposes. Optionally a

description can be added.
SimulationX 3 9-101
Figure 9.66: Page for potential common cause failures
9.8.4.2.4 Page Output Deviations

An output deviation is an unexpected behavior of a component at a particular port.
Causes for that might be:
local basic events (local failure modes of the component)
PCCF (global events, which have an effect to this component)
input deviations caused by other connected components
Output deviations are propagated over connections and become input deviations
for the next connected component. They are defined on the page Output
Deviations (Figure 9.67).
Output deviations are defined and listed on the left side of the page. The buttons
above the list are used to create output deviations, to remove existing ones or to
define failure classes.
The name of an output deviation consists of two parts separated by a dash: a failure
class name (e.g. OE) and a port name (e.g. B). The class name defines the failure
class which is propagated and the port name defines the output port.
9-102 SimulationX 3
SafetyDesigner
Figure 9.67: Page Output Deviations
If an output deviation is added to the list, a new unique name is generated from the
name of the known failure classes and a name of a port that belongs to the selected
component.
Failure classes constitute a global, abstract classification of reactions of parts or the

entire system to local failure modes (occurrences of basic events). Each system
provides different functionalities specified by these failure classes. In reliability
analysis, failure of one of the functionalities is designated as top event, and the
probability of occurrence is defined. By starting from this top event in FTA, it is
possible to determine the contributing basic events.
Two frequently used classes are:

O Omission of an output (in case of failure there is no output)
C Commission of an output (in case of failure there is unintended
output).
Both classes are predefined and can be selected from the combo box at the top of
this page. If more classes are needed, they can be added by pressing the third above
the list of output deviations (see section 9.8.4.2.5).
SimulationX 3 9-103
The next field is used to choose a port from a list of ports of the current model or
instance respectively. If the chosen failure class or port have different names, the
name of the output deviation is changed.
It is possible to provide a description for each output deviation.
The last field on this page defines a logical expression. It combines the different
sources of events using logical operators, e.g. and, or etc. Sources for events
are:
basic events (local failure modes)
PCCFs
failure classes defined as input through a port.
They are referenced by name and are logically true if an event occurs. When the
complete logical condition is fulfilled, the event is propagated as failure class via
the associated port.
A context sensitive menu is shown with valid inputs to help the user enter
expressions (Figure 9.68). They can be selected with the cursor keys and added by
pressing Enter.
Figure 9.68: Code completion menu
9.8.4.2.5 Dialog for Definition of Failure Classes

The dialog shown in Figure 9.69 is used to manage the global list of failure
classes. It can be accessed from the page Output Deviations in the SafetyDesigner
(see section 9.8.4.2.4) or by clicking the property dialog icon on the simulation
control toolbar.
On the left side of this page, there is a list of defined failure classes. Each failure
class consists of a unique name and a description. They are managed globally,
independent of the model, as they must also be accessible from inside external
libraries. If a library or model is loaded and contains references to unknown failure
classes, these classes are automatically added to the global list.
9-104 SimulationX 3
SafetyDesigner
By default, this list is stored for each user separately. By using this page, the user
can specify a file on a network share, for example, to use a common list across
different instances of SimulationX or a specific technical domain.
Such failure class files are XML files and can be opened via the corresponding
button. The list of failure classes is stored in the specified path.
Figure 9.69: Dialog for Definition of Failure Classes
Using the New and Delete buttons in the toolbar above the list of failure classes the
user can easily introduce new failure classes or remove them, when they are not
needed anymore.
When changing the name of a failure class, the dialog ensures that the user always
puts in a non-empty unique and valid identifier and reports the error otherwise.
Clicking the Close button clears the connection to the XML file and removes the
file name from the text box.
The button Export can be used to share a list of failure classes. Save as also
changes the path that SimulationX uses to store and restore a list of failure classes
while saving a list to the specified location.
With the New and Delete buttons on the toolbar above the list of failure classes, the
user can easily add new failure classes or remove them when they are no longer
SimulationX 3 9-105
needed.
When the name of a failure class is changed, the dialog returns a notification if a
duplicate or otherwise invalid identifier has been entered.
9.8.4.2.6 Page Connected Ports

This page (Figure 9.70) is shown when the SafetyDesigner is used for connections
in order to define the propagation of failure classes over a connection via
connected ports.
The page works similar to the page Output Deviations (see section 9.8.4.2.4).
A list of defined propagation rules can be found on the left hand side. Their names
consist of two components: the name of a failure class (e.g. O) and the relative
identifier (e.g. KB1.ctr1) of one port of this connection.
Figure 9.70: Page Connected Ports
Figure 9.71 shows the connected ports KC1.ctr1, KB.ctr1, and carrier_D1.ctr2.
They can be used as output ports or they can be referenced as inputs of failure
classes.
The Default combo box on the right is used to define the default behavior for the
selected connection. If it is not defined how a failure class is propagated over this
connection, the default behavior applies. Possible values are:
OR If a failure occurs at one port, the failure occurs also at all other
ports.
9-106 SimulationX 3
SafetyDesigner
AND If a failure occurs at n-1 ports, the failure occurs also at port n, if n
ports are connected.
OUTPUT For directed connections, e.g. signal connections, failures are
propagated from the output port to all connected input ports.
Figure 9.71: Connection of Ports
The combo box Class can be used to select a propagated failure class for output
deviations. This combo box can also be left empty. Then all failure classes are
propagated to the selected port when there is no other rule defined for this failure
class.
The combo box Port allows the user to select a port from the connected ports as
target for the propagation rule.
In the field Logical Expression the propagation rule can be defined similar to
output deviations (see section 9.8.4.2.4).
Additional keywords can be used for logical expressions: ANDPORT, ORPORT,
OUTPUTPORT and DEFAULT. They can be used for a particular port in the
same fashion as described above for the Default combo box. The keyword
DEFAULT refers to the current setting in the Default combo box.
Handling of Modelica Connections
Figure 9.72: One Mass Oscillator with Modelica connections
In contrast to ITI connections which may connect more than two components at
once, an individual Modelica connect statement only connects two components. In
SimulationX 3 9-107
practice it occurs frequently that a failure in some component depends on failure

events from several other components which are propagated via different connect
statements.
For example the Modelica model shown in Figure 9.72 contains several Modelica
connect statements: one defines the relation between damper1 and mass1 and
another one the relation between spring1 and mass1. These two connect
statements define how the three components damper1, spring1 and mass1 are
linked together. A combination of basic events in damper1 and spring1 should
lead to a failure in mass1. This kind of propagation would be difficult to model if
failure propagation could only be defined for individual Modelica connect
statements, e.g. one would have to introduce additional intermediate components
which make the simulation model more complicated and are not necessary for
transient simulation.
Therefore, the SimulationX SafetyDesigner handles Modelica connections, which

are transitively connected like in the example, together. From a user perspective
this approach allows to model failure propagation over Modelica connects the
same way as for undirected ITI connections.
9.8.4.3 Fault Tree Generation Wizard

The Fault Tree Generation Wizard provides global data for the safety analysis and
optimization. It starts when the fault tree analysis is opened from the menu
Analysis (Figure 9.73).
Figure 9.73: Starting Fault Tree Analysis
The wizard consists of several pages which can be selected by using the
corresponding buttons at the bottom.
The second and the third page focus on common cause failures. These pages are
only shown if Potential Common Cause Failures are specified in the model.
During optimization, the quantitative failure analysis is repeated by the optimizer

with different configurations. It uses a genetic algorithm to find a small set of the
most reliable and cost-efficient configurations. To specify optimization criteria,
additional parameters are required which can be defined on another page.
9-108 SimulationX 3
SafetyDesigner
9.8.4.3.1 Page Tools and Options

This page (Figure 9.74) lets the user select the type of analysis, provide global
parameters and configure the tools.
The combo box Analysis Type is used to select the desired mode of analysis.
Three options are available:
Qualitative Analysis
Quantitative Analysis
Reliability Optimization
Figure 9.74: Page Potential Common Cause Failures
If Qualitative Analysis is selected, only structural analyses are performed

(probabilities are ignored). This is especially useful to find single point failures.
Quantitative Analysis calculates the probabilities of occurrence for top level

events, e.g. failure of the whole system, using probabilistic parameters and
calculation models defined for basic event.
Reliability Optimization (not implemented yet) performs a quantitative analysis for

all structural variations with respect to all available implementations and selects a
small set of trade-offs with the best results.
For the quantitative analysis, it is possible to set the parameter Risk Time. It serves
as base unit for the probabilities within the model.
SimulationX 3 9-109
Table 9.4 summarizes a list of tool options with their values. The settings page
shows the default values in blue.
Name Registry key/ Annotation Default Description

value
Maximum maxCutSetSize 4 Specifies the cut-off limit for cut
Cut Set set size; cut sets above this will be
Size discarded.
Ignore ignoreOpenInputs true Ignores hanging input deviations

Open (i.e. input deviations that are not
Inputs connected).
Ignore ignoreCycles false Ignores cycles in the deviation
circular dependencies.
logic
Output warnings true When false, warning messages
Warnings are not displayes, only the
number of warnings remains.
Output outputDir <empty> Directory for output files. With
Directory the string <modelPath> the
directory of the model is used.
When empty, a temporary
directory is used. The output is
generated in a new directory
under the specified directory.
Output outputType <empty> This is a comma separated list of
Type different output types. Possible
output types are: XML, FTP,
EXCEL, NONE
Advanced advancedOptions <empty> Additional command line
options arguments which are provided to
the HiP-HOPS executable.
XML file XMLFile XML file in which output
deviation classes can be defined.
Only available as a global setting
(no annotation).
Table 9.4: Tool options
Model settings are available within a model for fault tree analysis. They are only
valid for a particular FTA model and are stored as annotations in the Modelica
code. Global settings apply to all FTA models. The global settings are stored
under the registry key HKEY_CURRENT_USER\Software\ITI
9-110 SimulationX 3
SafetyDesigner
GmbH\SimulationX x.y\FaultTreeGen. In general, the registry entries have the

same names as their corresponding annotations in the Modelica code.
The following table shows which values are used for fault tree analysis, depending
how and where they are defined.
Global Settings
Model Settings value defined value undefined
default value (not global value default value
modified)
user-defined value model value model value
A user-defined value can be identical to the default value. In this case, the value is
shown in black, which denotes that the value was modified by the user. Values
shown in blue were not modified by the user or were reset to its default value.
The value for the advanced options, however, is an exception. Both values from
the model and the global settings are merged and passed on to the HiP-HOPS
executable. Caution is advised for this operation.
9.8.4.3.2 Page Actual Common Cause Failures
Figure 9.75: Page Actual Common Cause Failures
This page (Figure 9.75) is used to define ACCF (see section 9.8.4.2.3).
SimulationX 3 9-111
ACCF are defined similar like Basic Events. Please refer to section 9.8.4.2.2 for
details.
9.8.4.3.3 Page Potential Common Cause Failures

On this page, PCCFs (see section 9.8.4.2.3) can be mapped to ACCFs in a table
(Figure 9.76).
In this table, multiple rows can be selected. If only one row is selected, an ACCF
can be assigned to a PCCF by using the combo box in the ACCF column.
Alternatively or if more than one row is selected an ACCF can be chosen from
the combo box beneath the table. It can be assigned to all selected PCCFs with the
Set button. The Clear button can be used to remove the ACCF setting from the
selected PCCFs.
Figure 9.76: Page Potential Common Cause Failures
The user has the possibility to sort the PCCFs. By clicking on the column headers,
the rows are sorted according this column alphabetically.
If holding the Shift-key during selection, more than one consecutive row can be
selected by clicking on the first and the last row.
If holding the Ctrl-key during selection, more the one row is selected or deselected,
when clicking on the row. They must not be consecutive. Using Ctrl-A all rows
can be selected at once.
9-112 SimulationX 3
SafetyDesigner
9.8.4.3.4 Page System Output

On this page (Figure 9.77), top level events (output deviations of a system), for
which fault trees are developed, can be selected. Such events are usually the most
relevant failures throughout the entire system.
Figure 9.77: Page System Output
The page System Output provides a tree of checkboxes for each output deviation
in the model. At least one output deviation must be selected.
Each selected output deviation can be modified with a separate severity value. This
value is shown in the output data for the corresponding top level event.
9.8.4.3.5 Page Analysis

This page (Figure 9.78) starts the analysis and summarizes warnings and error
messages of the analysis process.
Pressing the Finish button saves all settings of the wizard to the model. Pressing
Cancel closes the wizard without saving any changes.
SimulationX 3 9-113
Figure 9.78: Page Analysis
9.8.4.4 Integration in the Modeling Environment

The SafetyDesigner and the Fault Tree Generation Wizard are tightly integrated
into the modeling environment.
These dialogs can be opened through the context menus shown in Figure 9.79:
Figure 9.79: Menus to open the SafetyDesigner
Furthermore, the simulation mode control toolbar for selecting the analysis mode
has been extended by the fault tree mode (cf. Figure 9.80).
9-114 SimulationX 3
SafetyDesigner
Figure 9.80: Selecting the fault tree mode from the toolbar
If this mode is selected, the behavior of both the Run button and the property
dialog button changes.
The property dialog button opens the Fault Tree Generation Wizard on the first
page.
The Run button opens the Fault Tree Generation Wizard on the analysis page. A
fault tree analysis can thus be started with the settings from the previous run by
simply clicking the analysis button.
If the fault tree mode is set, double-clicking on types and components opens the
SafetyDesigner instead of the TypeDesigner or the parameter dialog respectively.
Both can still be opened through the context menu regardless.
The fault tree analysis is subject to the license model in SimulationX. In order to
run it, a license is required which can be obtained as a hardware key or license file.
9.8.4.5 Printing Capabilities

SimulationX comes with general printing capabilities for graphics, parameters and
results. A preview window (cf. Figure 9.81) allows the user to set up the layout of
the page including a particular view category.
View categories are:

Diagram View
3D View
Parameters
Results
Result Curves
Failure Data
SimulationX 3 9-115
Figure 9.81: Print Preview
This feature also supports printing of failure data (Figure 9.82). It can also be used
to get an overview of all failure data specified in the model.
Figure 9.82: Printed failure data of a component
9-116 SimulationX 3
Polygon Editor
9.8.4.6 COM-Interface
Most parts of the SafetyDesigner are also accessible for scripting using the COM
interface in SimulationX. An example script for the SafetyDesigner can be found
in the Scripting folder of the SimulationX samples directory.
9.9 Polygon Editor
The Polygon-Editor allows you to create, modify and optimize contact geometries
used in planar Polygon-Polygon contact elements. Using the 3D View the user may
modify these polygons to match the desired shape of the objects for which the
contact is modeled and for removing unnecessary points to reduce computation
time during simulation.
9.9.1 Preparation
The Polygon-Editor is opened using the menu: Extras->Tools->2D Polygon-
Editor. To start the editor you have to meet the following points:
The model has an open 3D View
A Polygon-Polygon contact element is present in the model and selected.
Figure 9.83: Model structure of the Polygon-Editor tutorial
9.9.2 Overview
The window of the Polygon-Editor is split into three components:
3D View (1)
The 3D View covers the biggest part of the editor. It is used to visualize contents
related to the contact element as well as for interactive data modifications.
Toolbar (2)
A toolbar sits at the upper part of the window. It contains several functions and
tools to be used in/with the 3D View.
Contact Data (3)

Contact data is displayed on the right side of the dialog.
SimulationX 3 9-117
Figure 9.84: Top-down view: Objects connected to the contact element are cut by the
contact plane to show the contact polygons at their exact position.
9.9.3 3D View
The 3D View draws contact polygons, elements and positions. The contact plane
splits the geometries into three parts: things above and below the plane as well as
things on the plane. Everything above the contact plane is removed per default to
get a better view of the two dimensional contact space and its polygons.
The camera is controlled by mouse/keyboard and/or the toolbar, just like the 3D
View in SimulationX. Polygons can be edited here.
9.9.4 Contact Data

This section shows parameters of the contact element, which can be changed if
required. Polygons can be generated using the buttons. It is also possible to define
the visible polygon in the 3D View.
Edit position and/or orientation using the two available input boxes. Each of them
provides different modes:
9-118 SimulationX 3
Polygon Editor
Orientation
Select Normal to enter the normal vector of the contact plane.
Select Matrix to enter orientation matrix of the contact plane.
Position
Select Distance to origin to enter the contact plane distance w.r.t. to the
model origin.
Select Global Position 1 to use and modify the global position of the contact
elements pin point 1. This point is the contact plane reference.
Select Global Position 2: to use and modify the global position of contact
elements pin point 2. This is the only translation kind which will not change
the position of the contact plane. It is only used for placing polygon2 within
the plane.
Select Plane Point to enter an arbitrary global point which is part of the
contact plane.
Hint:
Every modification will be applied to the model immediately.
9.9.5 Toolbar
The toolbar contains different tools and functionalities to be used with the 3D
View. It is split into the following sections:
Visualization:
Provides different visualization modes for the displayed elements:
everything below the contact plane
everything above the contact plane
everything cut by the cutting plane
intersection plane
Edit
deactivates interactive polygon editing
Redo/Undo changes made to the polygons
Camera Views
turns the camera 90 around one of the view axes
predefined plane views
intersection plane top-down view
SimulationX 3 9-119
Camera tools
free rotation
rotation around views X axis
rotation around views Y axis
rotation around views Z axis
Anti-Aliasing
toggles anti-aliasing
9.9.6 Generating Polygons

When pressing the Generate button for one of the polygons, all objects in the scene
corresponding to that contact side are cut by the contact plane, resulting in two-
dimensional intersection geometries. These geometries are interpreted as polygons
and will be used as contact geometry in your contact element.
If more than one polygon can be extracted from the intersection, a menu allows the
selection of one that should be used further.
Figure 9.85: Menu to select the desired polygon from all extracted polygons
9.9.7 Edit Polygons

To optimize or reshape contact polygons, they may be edited directly in the 3D
View. Find more about optimizing in the documentation of Polygon-Polygon
contact models.
Selection
Select a polygon point by clicking on it. A selected point is highlighted with a
yellow circle. You may select more than one point by pressing SHIFT while
clicking more points, or by using the rubber band selection mechanism keeping the
left mouse button pressed.
To select neighbor point(s) of the already selected one(s) use the cursor keys.
Pressing SHIFT will add the left/right neighbors just as if they were clicked.
9-120 SimulationX 3
Database Link
Edit
To remove selected points press DEL. If you click and hold a point with the left
mouse button you may move it anywhere on the contact plane. When having
multiple points selected all of them will be moved accordingly.
Figure 9.86:
Undo/Redo
To undo changes to the polygon(s) use the buttons in the toolbar, CTRL+Y and
CTRL+Z respectively.
9.10 Database Link

In SimulationX you can use a database link for the entering of element parameters.
By an example of the parameter input of a Spring-Damper element each step
is described.
Scheme of the database link
Figure 9.87: Scheme of database link
SimulationX 3 9-121
The database link provides the opportunity to use existing OLEDB data sources for
parameterization of ITI SimulationX models. Which data sources you can use
depends on the installed database driver (e.g. Access, Excel, SQL).
The database link can be adapted to existing data structures of an OLEDB data
source.
The tables of a database contain the data of the objects. Each column (field)
represents a parameter; the rows (records) contain the values of the parameters. An
object is identified by the values in the key columns.
The database link in SimulationX creates the assignment between the parameters in
SimulationX and the columns in the tables and transfers the data from the database
to the parameters of the simulation object. The database link supports the
following types of component:
Scalar parameters (real, integer, boolean, enumeration)
Strings
Characteristics
Curve sets and curve maps
Maps (2D/3D)
9.10.1 Creation of Database Link

The prerequisite is a database component, which is created in the type designer.
Figure 9.88: Creating a database component in the TypeDesigner
9-122 SimulationX 3
Database Link
At first you have to derive a new type from the existing type. Then you can add the
database link to the derived type using the type designer.
Example:
Click with right mouse button on the icon of the Spring-Damper-Backlash element
in the library bar and provide a derived type. The TypeDesigner opens. Now give
the derived type a name (e.g. SpringDamperDB2). Then go to the tab
Components und insert a Database Link (see Figure 9.88).
Afterwards they press the button Finish. For the further work Drag-and-Drop
the derived type into the diagram view.
The database link can be defined in the type designer (Button Binding) or
later in the properties window of the element.
After opening the properties dialog of the derived type the database control is
visible under parameters. Figure 9.89 shows the parameters, although still there is
no link to the data base.
The "Database link" control shows the information about the selected record. It is
possible to define the database link and to select data using the control.
Figure 9.89: Database control in the property dialog
Figure 9.90: Properties of a database link component (unlinked)
The data source will be a table (SpringDampers) in a MS-Access database

(Components.mdb). This file you find in your SimulationX path on
"...\Samples\Mechanics\Components.mdb").
9.10.2 Automatic creation of a data source

The data link wizard allows to create a suitable data source and to create the links
automatically.
SimulationX 3 9-123
Figure 9.91: Create data source
The following information is needed for generation:

1. Kind of data source
The following data sources are supported by default:
- Access database
- Excel Sheet
- SQL Server database
The support for other kinds of data sources can be implemented on request.
2. Properties of the data source
Depending on the kind of data source additional information is necessary (E.g.
name of database, location, login information)
3. Name of table
Enter the name of the table which should contain the data. If you enter the name
of an existing table, then it will be extended (if necessary).
4. Contents of table
The list at the end of the dialog allows to specify which component should be
stored in the database table.
The first column contains the name of the component and the second column
holds the name of the column in the database table. Colum name and
component name are equal by default, but you can change the column name.
The type of a column corresponds to the type of component and cannot be
changed. In the last column of the list you can decide whether the component data
9-124 SimulationX 3
Database Link
should be stored in the database table. The toolbar buttons allows creating and
removing additional columns. These additional columns can be bound to
components by entering the component name. The type of unbound columns can
be changed.
In addition to the columns in the list, a key column with the Name ID will be
created. The key column allows identifying each row in the database table (see
column explanations in section 9.10.3.2).
The button Finish creates (or extends) the table in the specified database. A
record with the values of the current components will be created too.
The database link stores the assignment of components and table columns
(linkage) and selects the new record. The created linkage can be edited afterwards.
Characteristics, curve maps, curve set and maps are stored in subordinated tables.
The schema is described in section 9.10.6.
Figure 9.92: Contents of table
9.10.3 Connect to existing database

The definition of a database link is performed by a wizard and consists of the
following steps:
Database selection
Table selection
Linking of parameters
Data selection
9.10.3.1 Database Selection

The connection with the database is described by a connection string. The
connection string contains all information about the database and the login. This
string can be created or edited with the help of an assistant, already defined
connections can be loaded from a UDL file, or you can edit it directly.
SimulationX 3 9-125
Figure 9.93: Selection of a database
Editing connection strings

Besides the absolute file directory, you can also use Modelica URIs and
environment variables for data-based sources (e.g. Excel) in the field Data
Source of the connection string. This makes sharing models much easier.
Environment variables are placed between percentage signs and replaced
with the corresponding system settings by SimulationX:
Data Source=%MYDATABASES%/mydb.xlsx;
Modelica URIs allow for specifying files relative to the Modelica path:
Data
Source=modelica://MyPackage/Databases/mydb.xlsx;
The above example searches for mydb.xlsx in the Modelica path of
MyPackage in the Databases directory.
Using an UDL File

The button Load UDL file allows selecting an UDL file to get the connection
string. You can decide whether the connection string of the UDL file is to be
copied to the database link (see Figure 9.93) or the UDL file name to be stored in
the database link (see Figure 9.94).
Figure 9.94: Using an UDL File
If the UDL file name is used, then the contents of the UDL file will be used as
source for the connection string whenever the database link opens the database.
You can easily change the connection by modifying the UDL file.
9-126 SimulationX 3
Database Link
Use the wizard
Figure 9.95: Selection of a database provider
The wizard allows creating and modifying a connection string.
Figure 9.96: Testing of a database connection
On the property page Connection information about the connection and login
can be entered. The appearance of the connection page depends on the selected
provider. The correctness of your input is tested with the button "Test
Connection".
If you do not allow to save the password, you will be asked for the password when
using the database link. You can enter additional parameters at the pages
Advanced and All depending from the selected provider.
Recommended Settings for MS Office datasources:
Office 97-Office 2007:
SimulationX 3 9-127
Datasource: Provider Extended Properties

Access Database (*.mdb) Microsroft Jet 4.0
OLEDB Provider
Excel (*.xls) Microsroft Jet 4.0 Excel 8.0
OLEDB Provider
from Office 2010:
Datasource: Provider Extended Properties
Access Database (*.mdb) Microsoft Office 12.0
Access Database Engine
OLEDB Provider
Excel (*.xls) Microsoft Office 12.0 Excel 12.0
OLEDB Provider
Excel (*.xlsx) Microsoft Office 12.0 Excel 12.0 Xml
OLEDB Provider
Excel (*.xls, *.xlsx) Microsoft Office 12.0 Excel 12.0
OLEDB Provider
Example:
Open the properties of the data link and select the desired provider (for the
example see Figure 9.95). After this you set under Connection the database
"Components.mdb" and the login data (user "Admin" and blank password). Now
you can test the data link.
9.10.3.2 Table Selection

When the information about the connection is complete, the table of the database
can be selected. You may also use views of the database as a table.
Figure 9.97: Selection of the database and the table
Example: Select the table "SpringDampers" of the database.

After the selection of the table you can display the contents of the whole table.
9-128 SimulationX 3
Database Link
Figure 9.98: Selected table
After the selection of the table SimulationX automatically tries to determine the
key columns and to define as key column. If that is not possible, then you define
these attitudes over the button Properties, at least one key column and a selector
column. This is verified in the properties of the table.
Figure 9.99: Table settings
Figure 9.114 shows the selection of the example.

The columns in the tabular view are arranged in the following order:
1. Selector columns
2. Columns linked to parameters
3. View columns
Explanation of columns:
Key column: Every row in the database table is identified by the values in
the key columns of the table. The values of the key columns
will be stored in the ITI SimulationX model to find the
selected record at a later time.
SimulationX 3 9-129
Selector column: The content of the selector column of the current record is
shown by the selector.
The content of the key column is sometimes not meaningful

for the user. Therefore you can define selector columns which
are different from the key columns.
View column: View columns are shown during the selection of a record
only. They do not need to be linked to a parameter.
A table must have at least one key column and one selector column.
9.10.3.3 Linkage of Parameters

In the next step you assign the parameters to the columns of the selected table. The
chart contains parameters of the object. You can assign a column of the table using
the combo box in the second column of the chart. The unit of the value in the table
is selected from the combo box in the third column of the chart.
Example: Link the parameters k and b to the respective columns in the table.
The definition of the database link is now complete and the settings will be stored.
The following data selection defines the default record of the database link.
The database link supports also the linkage of curves and maps. In this case a
button opens the dialog for the definition of bindings. The linkage of curves and
maps is described in section 9.10.6.
Figure 9.100: Parameter links
It is possible to select a record either by using the arrow buttons of the selector or
via a tabular view ( ). The tabular view shows a chart with the records contained
in the table.
9-130 SimulationX 3
Database Link
The first row of the column captions contains the name of the respective parameter
and the unit of measurement of the values in the table. The second row displays the
column name in the database.
The parameters which are set from the database are highlighted in the properties
dialog of the element. The marking will be removed once the value was changed
manually.
9.10.4 Data Selection

Example:
Carry out simulation runs with a model like using the parameter sets from the
table.
Parameters: Mass1.m 500g

Mass1.x0 5mm
preset1.kind Fixed
Figure 9.101: Parameter setting in table view
SimulationX 3 9-131
Figure 9.102: Element with parameters
Data record filtering:

You can reduce the amount of displayed records by defining a filter. The filter
button shows and hides the criteria of the filter.
The filter is shown as a table, the rows and columns are combined in the following
way: The conditions of a row are combined with a logical AND. Each row in the
table is combined with a logical OR.
The toggle button Active enables and disables the filter. Die button "Delete"
removes all conditions. The button at a condition shows the following dialog for
entering/modifying a condition.
First select a Field (Column) which should be used in the condition. Depending
from the selected field you can select a relation. The combo box of the values
shows all occurring values of the current query. You can select one of these values,
but you can also enter a value.
Example:
k>=9000 b=20
(k>=900 AND b=20) OR (b=25)
b=25
Figure 9.103: Condition dialog
9-132 SimulationX 3
Database Link
9.10.5 Removal of a Database Link

In order to remove a database link delete the database component in the type or
remove all links to parameters in the second step of the wizard (see section
9.10.3.3).
9.10.6 Linkage of curves and maps

The database link supports the linkage of curves, 2D- and 3D maps. The contents
of curves and maps cannot be stored in one field of the element table. They must
be stored in an extra table. The following steps are necessary for linkage of curves:
1. Select table containing the curve/map
2. Define relation between element- and curve table
The examples below demonstrate the linkage of a curve and a map. For this you
can use the database "...\Samples\Mechanics\Components.mdb". It includes a table
Elements and a table Curves.
9.10.6.1 Curves
Curve, CurveSet and CurveFamily consists of two or more sequences (x, y[1],
y[2]).
Each sequence in a curve contains the same count of values. Thats why curves can
be stored in the following way.
The curves table contains a column containing the ID of the curve and a column
for each sequence in the curve. The element table references by the column Curve
to the curve ID.
Figure 9.104: Sample curve
The advantage of the type of storage is the readability in the database and changes
in the database are easy.
SimulationX 3 9-133
Figure 9.105: Relations and content of the sample tables
Example: Derive a new type from an element Curve of the library Signal Sources.
Add by the help of the TypeDesigner a component Parameter and a component
Database-Link to this type. Finish the extension of the type.
Now open the properties dialog of the extended element. As next you have to link
the database by linking the table Elements (see section 9.10.3.1).
Select the ID as key column and as selector column in the properties dialog.
During linking of parameters you select in the row

curve - a link to Curves. By the button you get to
the linking dialog of curves.
To link a curve includes the following steps:

1. Select curve table
2. Define Relation
between element-
and curves table
3. Selection of sorting
column
4. Link the sequences
of the curve to
columns of the curve
table
Master- and detail columns

are used for the linkage of
maps.
Now you can switch between the curves of the table by using the control surface.
9-134 SimulationX 3
Database Link
Figure 9.106: Element Curve with control surface to curve selection
9.10.6.2 Maps
Maps are also built out of the following sequences:
o 2D-Map: x, y, f
o 3D-Map: x, y, z, f
Figure 9.107: Sample 2D map
Figure 9.108: Relations and content of the sample tables
The sequences in a map can contain different count of values. Therefore each
sequence will be stored separate in the sequences table and the element table
contains ID fields (SeqX,SeqY,SeqF) for each sequence of the map. A record of the
SimulationX 3 9-135
sequence table contains the ID of the sequence the value (Val) and the position
(Line) of the value in the sequence.
To link a map includes the following steps:
1. Select sequence table

2. Select sort column
3. Assign sequences to value
column in sequence table
4. Define relation between
sequence ID in element
table (Master) and ID in
sequence table (Detail)
9.10.7 Hierarchical database links

Database links of compound types can control the database link of their contained
elements. Such hierarchical database links allow considering the relations between
the tables of a database. They can also be used to enforce the selection of the same
record for several database links.
The following example (see Figure 9.109) demonstrates the linkage of a
subordinated database link.
The gear contains two wheels (Wheel1, Wheel2), their database links are linked to
the table Wheels. This table contains the properties of the wheels. The database
link of the gear uses the table Gears. This table defines the possible combinations
of wheels and contains the ratio of the wheel combination. The aim is the
automatic selection of the wheels depending from the selected gear.
Before the Gear can be linked to the database, the database link of both wheels
must be completely defined. This can be done by defining the database link at the
wheel type or by separate definition for each wheel element.
The parameter of the gear is linked to the corresponding column of the gears table.
9-136 SimulationX 3
Database Link
Figure 9.109: Sample gears database
The linkage of the subordinated database links will be done by the following
dialog:
Figure 9.110: Linkage dialog for a subordinated database link
The first line of the grid column captions contains the name of the database link
and the second line contains the table used by the database link. The relations
between the tables are set by the combo box.
For each wheel will be a relation defined:
SimulationX 3 9-137
o Wheel1.dbLink1: Gears.Wheel1 Wheels.ID

o Wheel2.dbLink1: Gears.Wheel2 Wheels.ID
When a gear will be selected, then automatically Wheel1.dbLink selects the record
with the ID of Gears.Wheel1 and Wheel2.dbLink selects the record with the ID of
Gears.Wheel2.
9-138 SimulationX 3
by
Modelica
General Hints
10 Modelica in SimulationX
10.1 General Hints
SimulationX is a simulation and modeling tool which uses the modeling language
Modelica for describing models. This language is continually improved and has
become a de facto standard in the world of multiphysics modeling. The language is
developed by the Modelica Association (www.modelica.org).
In SimulationX, Modelica is used wherever model behavior is described. This

includes ESI ITIs commercial libraries, third-party libraries for SimulationX or
platform independent libraries, such as the Modelica Standard Library (MSL).
Definitions based on this standard are also employed when the SimulationX
TypeDesigner is used for custom model types or flexible parameterization through
the corresponding expressions (e.g. if then else).
Since SimulationX 3.7 is supported the Modelica standard 3.2r2 for the
interpretation of model code.
When working with SimulationX it is not necessary to look into the language
standard to a great extent. Models can be created with the help of the libraries via
the graphical user interface as described in section 4.2. The storage of the models
follows the Modelica syntax, but includes a SimulationX specific basic type for
simulation data. It is also possible to create models by typing the Modelica source
code and run those within SimulationX.
It is strongly recommended to know the subset of the language standard that

comprises the mathematical and algorithmic description of systems (Chapter 3, 8,
10 and 11 of the Modelica specification). For the creation of own Modelica classes
it is recommended to make use of the TypeDesigner (see chapter 8). This eases
the modeling in Modelica by supporting the user e.g. when declaring variables or
when deriving from basic classes. In those cases the appropriate syntax will be
generated automatically. On the other hand it is possible to edit the source code
directly making use of the key word highlighting feature.
Attention should be paid to the fact that libraries which are supplied with
SimulationX or additionally acquired cant be used in other simulation
environments due to the licensing mechanism. Also, the concept of SimulationX
connections is beyond the Modelica specification. Other Simulators so far do no
support this concept of connections. Please, keep this in mind should you want to
develop models for other target systems than SimulationX. The same applies for
the utilization of the respective element ports in user-defined types.
SimulationX 3 10-1
User Manual 10. Modelica in SimulationX
More information about Modelica can be found under [4] and

http://www.modelica.org.
10.2 Modeling with the Modelica-Standard-Library

10.2.1 Installation
The Modelica Standard Library is part of the installation of SimulationX.
Optionally the library can also be downloaded for free from the web site of the
Modelica Association (http://www.modelica.org). In order to load the Modelica
Standard Library properly one has to adjust the Modelica Search Path
(MODELICAPATH).
If the library was installed, the Modelica search path (MODELICAPATH) is set
correctly already. Otherwise, it is still adapting.
Figure 10.1: Choosing the Modelica Search Path (MODELICAPATH)
The Modelica-path (MODELICAPATH) will be set up as follows:

1. Click in menu Extras on Options.
2. Choose in Dialog Options tab Directories.
3. Click in Selection on Modelica Search Path (MODELICAPATH).
4. Insert in directories a new entry or change an existing entry in Directories.
Make sure that the properly root directory of the Modelica standard
library is filled in the selected directory.
10-2 SimulationX 3
Modeling with the Modelica-Standard-Library
The library can be changed in SimulationX. If this should be prevented the data
have to be put to Read only in the file system. In that case the editing tools in the
TypeDesigner are invisible or deactivated.
In general the usage of the types of the Modelica Standard Library is carried out
analogically to the modeling with SimulationXs library elements. That is to say
they will be positioned by dragging with the mouse in the model.
By the context menu of a type and the function Open it can be opened in the
TypeDesigner, or in different views for a process (see also 4.2.2.1). Also note the
settings for Modelica files in section 7.6.5. Saving the changes can be made
according section 5.2.1.
However, there are some differences that shall be described in the following.
1. Not all displayed entries in the library bar (section 4.2.2) of the Modelica
Standard Library are types that are usable in a model as element (i.e. via
Drag & Drop in the diagram view placeable). The bar shows all contained
packages (packages, libraries), documentations, functions, icons, ports,
classes (types) and complete sample models. Packages will be displayed in
the library bar as blue boxes (see Figure 10.2). A small symbol having the
form of a folder or of a paper sheet on the left indicates additionally the
saving location of the package. For more information about this refer to
section 4.2.2.
Figure 10.2: The Modelica Standard Library in the library bar
2. The Modelica Standard Library does not contain any connections like
SimulationX, i.e. the graphical connection between Modelica objects are not
model objects. Consequentially they do not have names nor results or initial
values. Those are only changeable and/or readable at connected elements.
SimulationX 3 10-3
Modelica elements are to be connected directly by means of their ports.
3. The usage of functions of the Modelica Standard Library is either carried out
by giving the complete Idents (e.g.
x=Modelica.Math.leastSquares(A,b)) or by import of packages
(see Chapter 7) and simple calls in the model ( x=leastSquares(A,b)).
The Ident is to be taken from the lower part of the library bar (Figure 10.3).
Figure 10.3: Information about the library elements in the lower window of the library
bar
10.3 Combining the SimulationX Libraries with the

Modelica Standard Library
Due to the fact that connections of different types actually do not exist, e.g. a
translational inertia of the Modelica Standard Library cannot be directly connected
with a mass from the Library Linear Mechanics of SimulationX. This can be
overcome by an easily defined interface. This interface has to be defined as
Modelica class model or as external type. This element type contains each of the
appropriate port types and connects the physical variables by equations. That is to
say that the sum of both flow quantities is zero, while both potential quantities
have to be equivalent. To fulfill this functionality a package called "Modelica
Compatibility Types" within the SimulationX library has been defined.
10.4 Differences in SimulationX
SimulationX supports Modelica, described by the Modelica Language
Specification Version 3.2r2 (in the following referred to as MLS).
10-4 SimulationX 3
Differences in SimulationX
In the following the notation and the differences (extensions and/or restrictions) are
described. The arrangement is according to the Modelica specification.
Models that use the SimulationX specific extensions are not conform to the MLS
and cannot be processed by other Modelica-supported tools if necessary.
10.4.1 Lexical Structure and Syntax

The lexical structure is described in Chapter 2 of the MLS.
Lexical units are contiguous character strings without separators (spaces,
tabulators, line feeds) in-between.
Name ::= Letter { Letter | Digit | '_' } .

Number ::= ( Digit { Digit } [ '.' { Digit } ] | '.' Digit {
Digit } )
[ 'e' | 'E' [ '+' | '-' ] Digit { Digit } ] .
Digit ::= '0' .. '9' .
Letter ::= 'A' .. 'Z' | 'a' .. 'z' .
String ::= '"' ... any character ... '"' .
UnitString ::= ''' [ Unit ] [ '->' Unit ] '''
Unit ::= String describing a physical unit of measurement
Modelica key words:
algorithm and annotation assert

block break class connect
connector constant constrainedby der
discrete each else elseif
elsewhen encapsulated end enumeration
equation expandable extends external
false final flow for
function if import in
initial inner input loop
model not operator or
outer output package parameter
partial protected public record
redeclare replaceable return stream
then true type when
SimulationX 3 10-5
while within
These keywords must not be used for names and the designators.
In SimulationX there are the following additional keywords:
version defines the version number of the type

required a special version of the type is needed
nondiscrete turns an otherwise discrete variable (integer, boolean) into
a non-discrete variable
accept marks particular algorithm sections for the handling of
impulses (impact)
_iti_special Marks special string parameters
_iti_parameter Parameters, which do not have to be constant
_iti_startparam Parameters, which are used as initial values
The syntax of Modelica is described in the Appendix B of the MLS.
10.4.2 Operators and Expressions

Operators and expressions are described in Chapter 3 of the MLS.
10.4.2.1 Arithmetic Operators

^ Exponentiation
* Multiplication
/ Division
+ Addition
- Subtraction
When using these operators with vectors and matrices special rules apply. (e.g.
scalar product, see MLS chapter 10.6) For an element-wise linkage of multi-
dimensional values special operators can be used:
.+ Element-wise addition
.- Element-wise subtraction
.* Element-wise multiplication
./ Element-wise Division
.^ Element-wise Exponentiation
10-6 SimulationX 3
10.4.2.2 Equality, Relation, and logical Operators

> greater than
>= greater than or equal
< less than
<= less than or equal to
== equality within expression
<> Inequality
not negation, unary operator
and logical and
or logical or
In SimulationX there are the following additional operators and expressions.
10.4.2.3 Numeric Functions

sin(x) sine
cos(x) cosine
tan(x) tangent
sinh(x) hyperbolic sine
cosh(x) hyperbolic cosine
tanh(x) hyperbolic tangent
asin(x) inverse sine (asin)
acos(x) inverse cosine (acos)
atan(x) inverse tangent (atan)
atan2(x,y) four quadrant inverse tangent
exp(x) Exponential (Basis e; x>0)
log(x) Logarithm (Basis e; x>0)
log10(x) Logarithm (Basis 10; x>0)
sqrt(x) Square root
In SimulationX additionally available:

arcsin(x) inverse sin (asin)
arccos(x) inverse cosine (acos)
arctan(x) inverse tangent (atan)
log(b,x) Logarithm (Basis b; x>0)
SimulationX 3 10-7
lg(x) Logarithm (basis 10; x>0)
When applying the function with multidimensional values (vectors, matrices)

they are applied element-wise and return a value of the same dimension.
10.4.3 Classes, Types and Declarations

Classes, types and declarations are described in Chapter 4 of the MLS.
These are provided in SimulationX by the help of the TypeDesigner.
10.4.3.1 Component Declaration

The syntax of type_prefix (cf. MLS 4.4.1) has been extended:
type_prefix :
[ flow ]
[ discrete | nondiscrete | parameter | constant ]
[ input | output ]
[ _iti_parameter | _iti_parameter | _iti_special ]
For the meaning of the new keywords see chapters 10.4.1.
10.4.3.2 Attributes of pre-defined Types

Pre-defined simple types have attributes (cf. MLS 4.8). Attributes hold additional
information which is evaluated by the GUI, the symbolic analysis (GSA) or the
solver.
Following attributes are supported:
Defined
Standard Evalua-
Attribute Type with Description
value ted by
Type
min as variable - GSA, Real, Lower limit of the
DBL_MAX Solver Integer, value. See
Enume- Minima and
ration Maxima
max as variable DBL_MAX GSA, Real, Upper limit of the

Solver Integer, value. See
Enume- Minima and
ration Maxima
start as variable empty GSA, Real, The initial value

Solver Integer, at start time.
Boolean
10-8 SimulationX 3
fixed Boolean true Solver Real, true -> The initial

Integer, value is binding
Boolean false -> The
initial value is just
a guess to
calculate
consistent inital
conditions.
notfixed Boolean true Solver Real, true -> The state
Integer, can change its
Boolean value at event
instants, even if
this is not a
physical behavior.
nominal Real empty Solver Real Is used to scale
the state by the
solver.
stateSelect enumeration StateSelect. GSA Real Enumaration
StateSelect default value who affects
the choice of
states in the GSA.
See below.
iterSelect enumeration StateSelect. GSA Real Enumaration
StateSelect default value who affects
the choice of
iteration variables
in the GSA. See
below.
minNotReached Boolean false GSA, Real true -> The lower
Solver limit is not
reached. See
Minima and
Maxima
maxNotReached Boolean false GSA, Real true -> The upper

Solver limit is not
reached. See
Minima and
Maxima
absTol Real global Solver Real If set -> the
setting absolute tolerance
for this state
else -> the global
setting is used.
SimulationX 3 10-9
relTol Real global Solver Real If set -> the

setting relative tolerance
for this state
else -> the global
setting is used.
discontChange Boolean false Solver Real The state may
jump during
integration.
quantity String Basics. GUI Real, The physical
Unitless Integer quantity.
comment String empty GUI all The shown
comment.
active Boolean true GSA all (read only) The
parameter/ the
variable is active
(not switched off
by
ActivityGroups or
conditional
declaration).
Minima and Maxima

In SimulationX the values of the attributes min, max, min, minNotReached
and maxNotReached are used to determine whether a variable can be zero or not.
This attributes are important for solving equations with multiple variables when
transposing may result in division by zero. If the variable can be zero, no division
takes place, and the equation becomes implicit. That means that the variable which
is made the subject becomes a state and the numerical solver has to find the
solution.
Such implicit equations are numerically hard to solve. Therefore one should try to
avoid them by setting min and max attributes properly.
10.4.4 Name Spaces and Identifiers

Name Spaces and Identifiers are described in Chapter 5 of the MLS.
10.4.4.1 References on local parameters

In Modelica the search for referenced designators in modifications always begins
in the surrounded type. In parameters it is often meaningful to reference other
parameters of the same object. In order to simplify this, one can place in
SimulationX a 'self.' in front of the reference. In this case the search begins in
the surrounded component name space of the parameter. Thus, such objects can be
copied without additional modifications. During the input of expressions in
parameters SimulationX inserts automatically the 'self.', if necessary.
10-10 SimulationX 3
10.4.5 Inheritance, Modification und Redeclaration

Inheritance, Modification and Redeclaration are described in Chapter 7 of MLS.
10.4.6 Equations
Equations are described in Chapter 8 of the MLS.
Syntax:
Reference = Expression ;
(OutputExpressionList) = FunctionCall;
In equations the equality of two expressions is expressed by '='. This is not an

assignment but it means that this equality applies during the simulation.
The evaluation order of the equations is undefined. They can also be sorted by
other variables, if required.
By entering discontinuous expressions (e.g. if then else ) discontinuous
equations can be created as well.
The second form of assignments or equations is used if the called function has
several return values. Here the variables on the left side are assigned with the
output variables of the function through the order. The variables for non-required
return values can be omitted from the list. Only the separating comma needs to be
written then. The commas at the end of the list can be omitted.
Example:
when initial() then
reinit(state,y0);
end when;
der(state) = G/Ti * x;
y = state + G*x;
xv = vector(x);
if size(B,1)>1 then
p = B[1:n] / B[n1];
if size(A,1) >= size(B,1) then
q[1:n]=(A[1:n]-A[n1]* B[1:n]/B[n1])/B[n1];
q[n1] = A[n1]/B[n1];
else
q[1:n]=A[1:n]/B[n1];
end if;
der(z[:,1])= - p[1] * z[:,n] + q[1] * xv;
for k in 2:n loop
der(z[:,k])=z[:,k-1]-p[k]*z[:,n]+q[k]*xv;
end for;
yv = z[:,n] + q[n1] *xv;
else
yv = A[1]/B[1] * xv;
end if;
SimulationX 3 10-11
y = if ndims(x)>0 then yv else scalar(yv);
10.4.6.1 The for Statement

Syntax:
for Name in Expression, Name in Expression,... loop
{ Equation ; }
end for;
The expression in a for statement must be a vector expression. It is evaluated once

at start of the loop. The elements of the vector are assigned subsequently to the
loop variable and for each element the loop body is executed.
Examples:
for i in 1:10 loop ... end for
// i gets the values 1,2,3,...,10
for i in 1.0 : 1.5 : 5.5 loop ... end for

// i gets the values 1.0,2.5,4.0,5.5
for i in { 1,3,6,7 } loop ... end for

// i gets the values 1,3,6,7
for i in { { 1,2 }, {3,4}} loop ... end for

// i gets the values {1,2} and {3,4}
The for statement declares a local variable only visible inside the loop body. It can
shadow external variables with the same name.
In for statements within equation sections the ranges must be constant.
Derivation of the range

In a for statement the range for a loop variable can also be omitted if this variable
is used as an array index within the loop. The range is derived from the size of the
array in the indexed dimension as 1:size(array,indexpos) then. When the variable is
used as an index several times, the respective dimensions must coincide.
Several loop variables
for i in 1:2, j in {1,2,3} loop

x[i+j]=i+j;
end for;
is equivalent tou
for i in 1:2 loop

for j in {1,2,3} loop
10-12 SimulationX 3
x[i+j]=i+j;
end for;
end for;
Loops which have a constant range are expanded by the symbolic analysis if
required.
10.4.6.2 If Statement
Syntax:
if Expression then
{ Equation ; }
elseif Expression then
{ Equation ; }
else
{ Equation ; }
end if;
The if statement consists of an if section which can be followed by several elseif

sections. The end is an optional end section.
The expression in the if and elseif sections must be a scalar Boolean value. These
expressions are evaluated one after the other. If an expression provides true, the
corresponding statement block will be selected. If none of the expressions provides
true, the else branch will be selected if it exists, otherwise nothing will be selected.
The selected equation section will be processed if the equations are fulfilled in the
selected section during the simulation.
if statements in equation sections which do not have constant conditions, must

have an else section and the number of equations must be the same in all
sections.
If if or elseif sections have constant conditions, the sections with inapplicable

conditions will be eliminated. If the if statement has only one constant applicable
condition left, the if statement will be replaced by its contents.
10.4.6.3 The when Statement

Syntax:
when Expression then
{ Equation ; }
elsewhen Expression then
{ Equation ; }
end when;
The when statement consists of a when section which can be followed by several
elsewhen sections.
SimulationX 3 10-13
The expression in the when statement must be a discrete Boolean expression. It can
be a scalar or a vector. The statements inside the body of the when-statement are
only executed when the expression becomes true. This happens only at
discontinuities (discrete expression). During continuous integration, the body is
never executed.
if b is a scalar, then
when b then ... end when;
it is equivalent to
if edge(b) then ... end if;
if b is a vector then
it is equivalent to
if edge(b[1]) or edge(b[2]) or ... edge(b[n]) then
... end if;
The following restrictions apply to when statements in equation sections:

They must have the form variable = expression; or
(var1, var2, ... ) = function(...);
assert(...), terminate(...), reinit(...) are admissible.
for or if statements are admissible, with the same restrictions being
applicable to the contained equations.
The different when/elsewhen sections must have the same variable
references on the left side.
In if statements within when statements the same variable references must
be on the left side if the conditions are not constant.
when statements cannot be nested.
when statements cannot be used in functions.
10.4.7 Connectors and connect Equations

Connectors and connect equations are described in Chapter 9 of the MLS.
In SimulationX (even more than two) connectors from pre-defined libraries can be
connected in any quantity with (one) suitable connecting object (connection) by
means of connect equations. The direct connection of two of these connectors is
not supported.
10.4.8 Arrays
Arrays are described in Chapter 10 of the MLS.
Array is the general denotation of a value of higher dimensions. Scalars have the
dimension 0, Vectors the dimension 1, and Matrices the dimension 2.
10-14 SimulationX 3
The Elements of an array are the (scalar) values contained in it. Functions defined
for scalars have been extended to arrays; they are applied element-wise. They
return an array with the same dimensions.
Variables hold values. They have a name and can be referenced in expressions.
SimulationX supports the declaration of arrays with arbitrary (unknown)

dimensions for pre-defined types, e.g.
Real x[*]
The dimension of x is deduced from the context in which the x is used. It can be
also a scalar.
10.4.9 Assignments and Algorithm sections

Algorithms are described in Chapter 11 of the MLS.
10.4.9.1 Algorithm and Assignments

Syntax:
Reference:= Expression ;
(OutputExpressionList) := FunctionCall;
In algorithms the assignment operator is ":=", the character '=' cannot be used
there. Assignments are processed in the order in which they were put down.
Examples:
Y = if(t<0.2) then 0 else 1
or
when sample(start,interval)then
y:=x;
end when;
z:=sign(sin(pi*x/I));
when{change(z),initial()}then
if(x/I)<0 then
y:=I*ceil(x/I);
else
y:=I*floor(x/I);
end if;
SimulationX 3 10-15
end when;
10.4.9.2 The for Statement

Syntax:
for Name in Expression, Name in Expression,... loop
{ Algorithm ; }
end for;
The expression in a for statement must be a vector expression. It is evaluated once

at start of the loop. The elements of the vector are assigned subsequently to the
loop variable and for each element the loop body is executed.
10.4.9.3 If Statement
Syntax:
if Expression then
{ Algorithm ; }
elseif Expression then
{ Algorithm ; }
else
{ Algorithm ; }
end if;
The if statement consists of an if section which can be followed by several elseif

sections. The end is an optional end section.
The expression in the if and elseif sections must be a scalar Boolean value. These
expressions are evaluated one after the other. If an expression provides true, the
corresponding statement block will be selected. If none of the expressions provides
true, the else branch will be selected if it exists, otherwise nothing will be selected.
The selected statement block will be processed in an algorithm then.
10.4.9.4 The when Statement

Syntax:
when Expression then
{ Algorithm ; }
elsewhen Expression then
{ Algorithm ; }
end when;
The when statement consists of a when section which can be followed by several
elsewhen sections.
The expression in the when statement must be a discrete Boolean expression. It can
be a scalar or a vector. The statements inside the body of the when-statement are
only executed when the expression becomes true. This happens only at
10-16 SimulationX 3
discontinuities (discrete expression). During continuous integration, the body is

never executed.
if b is a scalar, then
it is equivalent to
if edge(b) then ... end if;
if b is a n Vector then
it is equivalent to
if edge(b[1]) or edge(b[2]) or ... edge(b[n]) then ... end if;
when statements cannot be nested.
when statements cannot be used in functions.
10.4.9.5 The while Statement

Syntax:
while Expression loop
{ Algorithm }
end while;
In addition to the for statement exists the while statement. This could be used
inside of algorithms. The expression in a while statement must be a scalar Boolean
value. The loop body is executed as long as the expression evaluates to true.
10.4.10 Functions
Functions are described in Chapter 12 of the MLS.
10.4.11 Libraries (Packages)

Packages are described in Chapter 13 of the MLS.
10.4.12 Annotations
Annotations are described in Chapter 17 of the MLS.
In SimulationX 3.5 annotations for version treatment are not supported.
SimulationX 3 10-17
10.5 Conversion of models for use in SimulationX (since

version 3.7)
10.5.1 Introduction
Introducing the Modelica standard 3.2r2 for the interpretation of model code may
impact existing models. The benefits of these changes include more robust
modeling, a better recognition of differing notations also through clearer warning
messages and improved notifications for the user.
These changes may require modifications of models and libraries in order for them
to work properly.
The following instructions are meant to help you recognize whether custom
models or libraries may be affected by those changes and how to perform the
necessary modifications. To that end, this document provides a list of key areas
which guides you through a systematic conversion of the model source code
providing useful hints what to do should errors occur.
It is assumed though that the user has already a fairly good knowledge of the
Modelica language, the SimulationX TypeDesigner or other external modeling text
editors for modeling. Moreover, it is advisable you have skills in numerical
treatment of algebraic differential equations.
Major changes in SimulationX relate to:
Warnings and error messages during the symbolic analysis, e.g.:

checking the appropriate variability (discrete/continuous) of variables in
equations and assignments,
additional checks for ensured consistency of models and their Modelica
compliance
Event handling
Initialization
Initialization of variables in algorithms
Handling of the stateSelect attribute
The individual sections describe the changes in SimulationX and the related model
modifications required
10.5.2 New warnings and error messages

In SimulationX 3.7, all warnings and error messages have a name to identify them.
This name is shown at the end of the message. The following table lists new
notifications with their idents, the message text and a description. The messages
contain placeholders for the information to be inserted for the specific case.
Whether a message is shown as an error, warning, notification or not at all depends
10-18 SimulationX 3
Conversion of models for use in SimulationX (since version 3.7)
on the chosen control level which can be changed (Extras /Options/

General/Warnings and Errors).
Check.ArgumentTypeMismatch
When calling the function "%1", the type "%3" of the
argument "%2" is not compatible with the expected type "%5"
for the input parameter "%4".
The types of the arguments when calling a function do not match the types of the
function parameters. Change the function call to match the function.
Check.BusSameType
All variables, which are connected via a bus line, must
have the same value type. This applies to %1
Variables connected through a bus component (vector element) must be of the
same type. Change the variables type that does not match the transmitted signal
over the bus connection. (see 10.5.8) .
Check.ConnectorComponentsDim
The dimension of the components %1 (%2) and %3 (%4) of the
connected connectors must be equal.
If two conservative ports are connected with each other, the dimensions of the port
components must match. Change the dimension declaration of the affected
components.
Check.DerivativeReferenceSelf
The derivative annotation of function %1 refers to itself.
In the functions derivative annotation, the name of the derived function is the
function itself. Please change the name to the function of the derivative.
Check.DimAssignEach
In a modification with each, the lower %1 dimensions of the
variable must have the same dimension as the expression on
right hand side (left dimension: %2, right dimension
%3).").
For modifications with each, all components of the array declared at this point are
given the value of the modification. The dimension of the values must match the
dimension of the modified components. Please adjust the values dimension.
Check.DimMustBeKnownAtCompileTime
The dimension of %1 must be known at compile time.
All information about the variables dimension outside the function must be
available for calculations during the symbolic analysis.
SimulationX 3 10-19
Check.DimMustMatchBusGenVar
The dimension of variable %1 (%2) must match the dimension
of the bus generator variable %3 (%4):
All ports connected over signal connections (bus generator variables in this case)
must have the same dimension.
Check.EquationTypeMismatch
The types of the left and right expression in the equation
must be compatible. left: %1 right: %2
Types on the right side in the equation do not match the type on the left. Please
correct this.
Check.EventsDependFromNonDiscrete
An event generating expression %1 may not depend from
noEvent-conditions: %2.
An expression (comparison or function) triggering an event must not depend on a
noEvent expression since discontinuities may no longer be found properly.
Check.FixedAndStartAttrMissing
The following variable %1 have fixed=true but no start
value is defined. %2 will be used.
If there is no start attribute given, the default value (0) is used.
Check.IfThenElseAltTypes
The alternative expressions of if ... then <expr1>. else
<expr2> must have the same value type. Here: if ... then %1
else %2.
Types of alternative expression of if/then/else do not match. Please correct this.
Check.RealEquality
In a %1 relation the arguments (here %2) cannot be of Real
type.
Comparison for equality (==) or unequality (<>) with real variables are not
permitted as numeric errors may occur. Please use the operators <= or >= instead.
Check.RecordCompModification
The record %1 is modified in %2 and the component %3 is
modified in %5 (=%4).
The component modification will be ignored.
Records can be modified on several levels. Either you modify the record as a
whole or just its components. A record modification always overwrites the
modification of components, also if it is lower in the hierarchy.
10-20 SimulationX 3
Check.SubscriptOnEmptyArray
The array "%1" is empty (%2) but there is a subscription on
it.
If an array is empty meaning that the value of at least one dimension is 0, accessing
components through subscription is not possible. This can be fixed the value is
tested with size(v,d)>0 beforehand.
Check.WhenInLoop
A when statement cannot be used in a for or while loop
statement.
Algorithms must not contain when in loops as they do not include information
about the number of passes and hence required events cannot be generated
correctly. Please use a loop within a when block instead.
IndexRecduction.NotDifferentiableEqns
The equations:
%1cannot be differentiated for symbolic index reduction.
If equations cannot be differentiated, index reduction is impossible and the model
cannot be simulated at worst. There are several ways to fix this:
Restructure the model to make index reduction redundant (e.g. integration of
elasticities in rigid connections)
Manipulate the choice of state with stateSelect to avoid derivatives of the
equation
Reduce expressions, usually in functions, to allow for differentiations again.
InitialSystem.IterationVar
There is no unique solution for the variable %1. If
applicable, add a fixed initial value, initial equation or
initial assignment.
The initial system is underdetermined (missing equations). This may cause an
undesirable initial state of the model. This can be fixed with additional fixed initial
values.
InitialSystem.MissingInitialAssignment
For the variable "%1" is no assignment in the initial
system. The startvalue "%2" is used.
The initial system is underdetermined (missing equations). This is fixed by the
analysis through assigning a start value (automatic fixation).
SimulationX 3 10-21
InitialSystem.MultipleAlgorithmOutputVar
The variables:
%1 are outputs of several algorithm sections. The result
system is may hard to solve.
The calculation of a variable is calculated in multiple algorithms results in an
equation, which requires the variable to receive the same value in each of the
algorithms. This however is usually not the purpose of such calculations. Merge
the algorithms in order for the variable to be calculated only in one algorithm or
introduce new variables to achieve the same condition.
InitialSystem.TooManyInitialEqns.Initial
The initial System is overdetermined. Remove some of the
following initial equations: %1
The initial system contains more equations than variables. If it is numerically
consistent, it can be simulated. If not, you need to undo the fixations of initial
values or remove initial equations.
InitialSystem.TooManyInitialEqns.Start
The system of equations for the initial value computation
is overdetermined.
Free some of the following fixations: %1
InitialSystem.TooManyInitialEqns.StartInitial
The system of equations for the initial value computation
is overdetermined. Free some of the following fixations: %1
They are in conflict with the following initial Equations:
%2
InitialSystem.WhenStatement
When-statements not valid in an initial section!
%1
When statements in initial equation sections are not needed. They would always
apply (when initial()) or not at all (all other conditions). Please correct this
accordingly.
10-22 SimulationX 3
Modelica.AssignedFlowVar
The not connected flow variable %1 has an assignment. It
will be implicitly set to zero.
Flow components of unconnected Modelica connectors are always set to 0.
Remove the extra equation.
Modelica.AssignmentFromNonDiscreteToDiscrete
From the following discrete variables %1 need to be are
assigned from the following non discrete equations: %2
The discrete variables may change because of that during
the continuous calculation.
Discrete variables should always be calculated with discrete equations. This is
ensured if you place the equation in a when block.
Modelica.CondRecordComps
Conditional declarations inside of records are not
implemented. The declaration condition "%2" of component
%1 is ignored.
To avoid this warning, remove the declaration condition for the record
component.
Modelica.DiscreteRealnoWhen
The variable "%1" was declared as "discrete" but is not
assigned inside a when-statement.
The keyword discrete calls for the calculation of the variable in a when block.
If this is not desired, remove the expression.
Modelica.EachGenerated
The missing "each" for "%1" was generated.
If nonscalar parameters and attributes are modified with a scalar, this warning is
displayed and an each expression that may be required is automatically generated.
To avoid that, create a modification with the right dimension or write each
explicitly before it.
Modelica.FunctionInputAssigned
In the Function "%1" is an assignment to input "%2" in the
statement "%3".
Input variables must not be assigned in functions. Add an auxiliary variable and
use it to achieve the desired behavior.
SimulationX 3 10-23
Modelica.MultipleWhenAssignedVar
The variable %1 is assignend in the following when-
equations: %2
Use when .. elsewhen .. end when do ensure a defined
priority
Merge the assignments from several when statements into one.
Modelica.NonRealAlgebraicLoop
The following algebraic loop contains only non real type
variables: %1.
The algebraic loop contains discrete variables. This often causes long iteration
times or results in a cycle in the event iteration. In order to avoid this, please break
the loop by referencing an included variable v with pre(v).
Modelica.NonScalarRelationOperand
The operands of: %1
have to be scalar expressions. %2%3%4.
Rephrase the comparison in a way that only scalar quantities are compared directly
with each other.
Modelica.TypeInconsistentAssignment
The assignment: %1
is not type safe. It is an assignment from %3 to %2.
The data types in an assignment or a modification do not match. Please correct
this.
Modelica.VariabilityMismatched
The Variability "%1" of the defined Variable "%2" is lower
than the Variability "%3" of the definition expression
"%4".
The reason for that is that the following Variable(s) have
a higher variability: %5
Variables can only be modified with expressions of equal or lower variability.
Increase the variables variability (constant-> parameter-> (variable)) or use a
constant expression.
Modelica.WhenConditionDependsFromLoop
The conditions: %1
of the following when-clauses depends on the unknowns of
the same algebraic loop: %2
You may be able to cut the dependency by using "pre(...)"
around the references in the when-condition.
Please avoid the algebraic loop.
10-24 SimulationX 3
Modelica.WhenInAlgebraicLoop
The following when-clauses are part of an algebraic loop.
They are evaluated more than once because of the solution
algorithm: %1.
Please avoid the algebraic loop.
StateSelection.AlgebraicReinit
The variable %1 is not a continuous time state, therefore
the reinit has no effect.
Please remove reinit.
StateSelection.InvalidNever
There is no assigning equation for the variable %1, which
is market with StateSelect.never.
Please remove StateSelect.never.
StateSelection.InvalidReinit
The variable %1, which is used in an "reinit" operator, was
not selected as continues time state, The "reinit" call
will not succeed!
Please remove reinit.
StateSelection.InvalidReinitNever
The variable %1 is used in an "reinit" operator but is also
market with StateSelect.never.
Please remove StateSelect.never.
StateSelection.NotSelectableCandidate
The following variables have stateSelect =
StateSelect.always:
%1 requiring them to be continuous time state variables.
However, that is at least %2 to many.
It is necessary to modify the stateSelect attributes or the
model.
Please remove StateSelect.always.
StateSelection.NotSelectableCandidateAlwaysReinit
The following variables are used in reinit or have
stateSelect = StateSelect.always:
However, that are at least %2 to many.
Please remove StateSelect.always and/or reinit for a variable.
SimulationX 3 10-25
StateSelection.NotSelectableCandidateReinit
The following variables are used in reinit:
However, that is at least %2 too many.
Please remove reinit for a variable.
StateSelection.NotSelectableStates
The equation:
%1 constrains the continuous time variables:
%2 requiring them to be continuous time state variables. It
is necessary to modify the stateSelect attributes or the
model.
Please remove StateSelect.always for a variable.
Value.SampleIntervalPositive
The second argument of %1 must give a positive (>0) value
(currently %2).
Make sure that the second argument of sample is >0.
10.5.3 Event Handling

Event handling is used for discontinuities in models and for changes of discrete
states during a simulation. The points are either given directly by the model
through operators sample() or are determined by changes in the results from
comparisons of continuous variables. In this case, the continuous calculation is
paused at this point and iteration for solving the altered, mixed discrete-continuous
equation systems is performed.
This so-called event iteration now consists of two stacked iteration loops:
the outer event iteration and
the inner event iteration.
The inner event iteration is new since SimulationX 3.7. For models with algebraic
loops as functions of discrete variables, this can lead to other discrete states after
the iteration and hence to different results. Up to SimulationX 3.6, only the outer
event iterations were taken into account. Algebraic loops with discrete variables
would not be solved, but assigned only once.
10.5.3.1 Terms
Appendix C of the Modelica specifications includes the equation system to be
solved:
relation()
(, )
10-26 SimulationX 3
0 = (, )
mit = [ , , , , , pre(), ], wobei:
p Modelica variables declared as parameter or constant, i.e.,

variables without any time-dependency.
t Modelica variable time, the independent (real) variable.
x(t) Modelica variables of type Real, appearing differentiated.
m(te) Modelica variables of type discrete Real, Boolean, Integer
which are unknown. These variables change their value
only at event instants te. pre(m) are the values of m
immediately before the current event occurred.
y(t) Modelica variables of type Real which do not fall into any
other category (= algebraic variables).
c(te) The conditions of all if-expressions generated including
when-clauses after conversion, see Section 8.3.5).
relation(v) A relation containing variables vi, e.g. v1 > v2, v3 >= 0.
and the following algorithm for the event iteration:
known variables: x, t, p
unknown variables: dx/dt, y, m, pre(m), c
// pre(m) = value of m before event occurred
loop
solve (1) for the unknowns, with pre(m) fixed
if m == pre(m) then break
pre(m) := m
end loop
The shown loop describes the outer event iteration, while solve(1) is called
outer event step. If the systems contains algebraic loops as functions of discrete
variables, solve(1)requires an iteration for solving the equation system. This is
the inner event iteration and is performed within the outer event step.
The inner event iteration consists of

an inner event step,
a test to check whether the discrete variable may have changed and
the calculation of consistent initial values.
During each inner event step, all assignments including the discrete assignments
are performed. During the calculation, the values of c and m may change; reinit
instructions in equations are not executed immediately, but only the values of the
second argument are calculated and saved separately.
SimulationX 3 10-27
Transient system pre(m)==m,

Transient system
M, depends of pre(m) detected event
will updated
m constant
aktualisiert x' is calculated
Transient system
m, x' is calculated
Consistent m' := m
Event Step
initial values Event Step
Internal Event iteration Can be omitted if no

algebraic loops between
discrete and continuous
m == m' variables exist
No ?
Yes
reinit(x,xr)
If reinit is executed,
always pre (m) <> m
applies as it happened in
When Block -> New
pre(m):=m pre(m)==m External Event step
No ?
Yes
Valid Step
Figure 10.4: Event iteration
Afterwards, consistent initial values are calculated for the continuous and real-
discrete part of the equation, while the discrete, non-real variables remain constant.
The inner event iteration runs as long as the values of the discrete state variables m
and the logical value of the condition c have become stable. For the active
reinit instructions, the saved values are then assigned to the variables x in (1).
The test checks whether the discrete variables have changed compared to the pre-
values. If so, they are updated and a new outer event step is performed. If not, the
step is validated and the continuous simulation is resumed. Also performing
reinit assignment trigger a new outer event step (cf. Figure 10.4).
The introduction of the inner event iteration has the following effects:
As the equation system with constant pre-values is calculated several times,
also instructions in when blocks are executed multiple times. This also
affects when sample() blocks.
The discrete/continuous system is solved, that means the discrete state
followst he changes in the continuous system at the iteration point
immediately so long as it stops changing. This is rather awkward for
modeling discrete controllers with a proportional part.
10-28 SimulationX 3
In order to avoid that, explicit precautions against multiple executions must be

taken and/or algebraic loops as functions of discrete variables m must be broken
down by substituting m with pre(m)at appropriate points.
10.5.3.2 Multiple executions of instructions in when blocks

Example model:
model Modell1
extends SimModel;
algorithm
when sample(0, 0.1) then
Modelica.Utilities.Streams.print(String(time));
end when;
end Modell1;
The same character string is completely written down several times (twice each).
Reason: the inner event iteration:
when is transformed into
Boolean b;
...
if b and not pre(b) then end if;
as long as pre(b)is not set to the value of b, the condition remains true
This is the case at least twice:
o First event step: b changes -> another step must be performed
o Second event step: a test is run to look for changes
Only then are the pre-values being applied
Problem:
when is intended for content to be executed only once
variables in algorithm which are assigned in when are discrete by default
and are set to the pre-value at the beginning of the algorithm
The singular execution can only be achieved by introducing an auxiliary variable

and by using the SimulationX specific annotation
NoAlgorithmInitialization:
model Modell1
extends SimModel;
Real t1(start=time.start-1)
annotation(NoAlgorithmInitialization=true);
algorithm
when sample(0, 0.1) then
if t1 < time then
t1:=time;
SimulationX 3 10-29
Modelica.Utilities.Streams.print(String(time));
end if;
end when;
end Modell1;
So t1 keeps the value from the previous pass and the test t1 < time fails the
next time and the content of the if block is not executed another time.
10.5.3.3 Avoiding algebraic loops with discrete variables

In the past:
In SimulationX 3.6, an event step consists of
1. a calculation of the system equations, while discrete equations in the
equation and algorithm section are evaluated as assignments
2. a subsequent calculation of the intial values for the continuous variables.
In the example model modelicaConformEventIter, SimulationX 3.6 executes

the expression y = -x/2 as an instruction at time index time = 0.5 when x
= 0. So y = 0 and the following calculation of the initial value returns x =
0.5. Figure 10.5 shows the result curve calculated with SimulationX 3.6.
model modelicaConformEventIter
extends SimModel; //< (just for running as ism
model)
Real x;
Real y(start=0.5,fixed=true);
equation
x = time - y;
when x >= 0 then
y = -x/2;
end when;
end modelicaConformEventIter;
-
1.0 x
y
0.8
0.6
0.4
0.2
0.0
-0.2
-0.4
s
0.0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0
Figure 10.5: Simulation result for model modelicaConformEventIter as

calculated with SimulationX 3.6
10-30 SimulationX 3
Now:
The Modelica specifications say, however, that the equation in the when block
becomes active and the overall system must be solved once the expression x > 0
is true. For the point the when condition is met, the equation system that must be
solved looks as follows:
x = time y;
y = - x/2;
Integrating the second equation into the first one and solving it for x returns x =
2*time. For time index time=0.5, x = 1 and y = -0.5. This is also reflected
in the result curve calculated with SimulationX 3.7 shown in Figure 10.6. Note the
occurring deviations from the curve calculated with SimulationX 3.6 starting at
time index ab time = 0.5 as shown in Figure 10.5.
x
y
-
-0
s
0.0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0
Figure 10.6: Modelica-compliant simulation result calculated with SimulationX 3.7

for model modelicaConformEventIter
Solution:
SimulationX 3.7 delivers the same results as SimulationX 3.6 for equations and
relations who are directly or indirectly embedded in the when condition if you use
the known limit pre(y) from the left side instead of the discrete variable. For
discrete variables like y, pre(y) is the value in the first event for y from the
calculation of the initial value before the simulation. Usually, this is the fixed
initial value of the variable. In the subsequent event step, pre(y) takes the value
of y from the previous event. The value pre(y) is no longer variable in the
current event and can be regarded as given for the equations in the current event.
Therefore, all equations and relations in the following model
modelicaConformEventIterWithPre can be treated sequentially in the
appropriate order without the need to solve the equation systems in iterations. The
model returns the same result as the one shown in Figure 10.5 which was
calculated with SimulationX 3.6 for the model modelicaConformEventIter.
SimulationX 3 10-31
model modelicaConformEventIterWithPre
extends SimModel; //< (just for running as ism
model)
Real x;
Real y(start=0.5,fixed=true);
equation
x = time pre(y);
when x >= 0 then
y = -x/2;
end when;
end modelicaConformEventIterWithPre;
10.5.4 Initialization
During the initialization, the model consisting of discrete and continuous variables
and their equations is put in a consistent state.
For the initialization, a special equation system is created. It consists of:
the normal (transient) equations and algorithms,
the contents of the when initial() blocks,
equations pre(mk) = mk for all mk which are calculated in other when
blocks,
the initial algorithm and initial equation sections and
the equations for the fixed initial values.
All variables are considered unknowns. They include pre(m)and the states x
which are independent of their corresponding m or der(x)in contrast to transient
systems. They all form an algebraic system whose solution may require an
iteration. All equations in when initial()can be executed multiple times. Non-
fixed initial values are used as initial values for the iteration and are set in advance.
The initialization is treated as inner event iteration, but uses the initialization
system, and initial() returns always true and sample(0,) always false.
The iteration is complete when the system has reached a consistent state and the
discrete variables have stopped changing. At the end, the transient system is
calculated once executing the instructions in when initial(). After the
initialization, a normal event iteration is performed for the start time.
10-32 SimulationX 3
Initial Values Initialization System

m, pre(m) constant
m' := m
Consistent Initialization System
pre(m) ' := pre(m)
Initial Values m, pre(m) is calculated
Event Step
No
m' == m,
pre(m)' == pre(m)
?
Yes
pre(m):=m Transient System

when intial() Blocks are
executed
sample(0,) is false
Event Step
Event Iteration see Figure 10.4
Figure 10.7: Initialization
10.5.5 Variability
10.5.5.1 Observing variability
For modifications of constants, parameters and variables, it is vital to take the
variability into account:
Variability Meaning
constant Constant (literal). Is calculated during the global symbolic
analysis (GSA). Changes require a new GSA.
parameter Constant. Can be calculated during the GSA. Can be
changed without a new GSA.
parameter Is calculated through initial equations, is constant
(fixed=false) afterwards. If the parameter has a modification, the fixed
attribute is ignored.
SimulationX 3 10-33
_iti_start_param ESI ITI-specific. Constant. For providing initial values

with fixed flag. Modifies the start attribute and implies
the corresponding fixed attribute.
_iti_parameter Parameter which can be variable. If constant, it behaves
like a parameter (fixed=true), otherwise like variable (the
content determines the variability)
Not specified Time-variable. Changes of the modification require new
(variable) GSA.
During the modification of variables with different variability, other variables can
be referenced. The following limitations apply:
Variability Can be modified with

constant constant
parameter parameter, constant
_iti_start_param _iti_start_param, parameter, constant
_iti_parameter variable, _iti_parameter, parameter, variable
variable variable, _iti_parameter, parameter, variable
Example:
If a parameter p is modified with a variable v (p = v), the following error
message appears:
"The variability "parameter" of the defined variable "p" is lower than the
variability "variable" of the assignment "v".
This is due to the following variables with a higher variability:
v(variable)
This also happens if the variable v was modified with a constant value.
Up to SimulationX 3.6, the content of the modification determines the variability,
while variables declared as constant or parameter could be modified with
variables with a constant modification.
10.5.5.2 Discrete and continuous variables and expressions with noEvent

Discrete variables are no longer blocked until the runtime from changing their
values outside of event steps. They are now checked at the compile time for invalid
continuous expressions to discrete variables which would trigger an error message.
Discrete expressions are (by definition):
10-34 SimulationX 3
constant and parameter expressions,

Discrete variables, i.e. integer/Boolean/string/enumeration variables without
nondiscrete in the declaration,
Real variables which are assigned in when blocks (except when
initial())
Function calls with exclusively discrete inputs
Expressions in when blocks
Comparative operations that are not part of noEvent()
Event generating functions, e.g. ceil, floor, div, mod, rem and
functions with annotation InlineNoEvent=false if it is not part of
noEvent()(do not create an event in this case)
Functions pre, edge, change
If noEvent is placed around an expression, it only affects the included

comparisons and event generating function calls. They no longer create events and
are no longer automatically discrete, but are regarded as continuous if not all
arguments are discrete. Expressions within noEvent(..) which contain only
discrete variables (and other discrete expressions) remain discrete.
If a comparison includes noEvent(), they are treated as continuous (not discrete). If

the condition of an if-then-else instruction is a noEvent expression, alternatives of
this instruction must not include any event-generating function, such as floor(),
ceil(), div(), mod(), integer(). This is also true for if-then-else equations
and if-then-else expressions. Also other comparisons which can generate events
must not depend on it.
Example:
model EventGeneratingFunctionsIf
Real x(start=0,fixed=true);
equation
der(x) + x =
if noEvent(time > 0.5) then
ceil(10*time) // depends from continuous
relations -> error
else
floor(10*time); // depends from continuous
relations -> error
end EventGeneratingFunctionsIf;
10.5.6 Algorithms
10.5.6.1 Initialization of variables in algorithms
According to the Modelica specifications, algorithms must not include any
repositories. The solver therefore resets all assigned continuous variables to their
SimulationX 3 10-35
initial values or to 0 if no initial value is available before executing an algorithm.

The discrete variables are set to their pre-values.
In models with restricted assignments for variables within algorithms, this can
result in assigned values to not go through and variables to keep their initial value
or to remain 0.
Example:
In this model, y is supposed to be overwritten in certain time intervals:
Real[3] y(start={1,2,3});
algorithm
if sample(0,0.1) then
y := {1,2,3}*time;
end if;
Problem:
Variable y is calculated within the algorithm. Before each pass, y is initialized.
sample()returns true only during the first outer event step, so the initial value
remains unchanged during the second pass and thus also at the end.
Solution:
There are several options to solve this problem:
1. Variable y is calculated in an equation section.
However, this is not always possible, e.g. for algorithms with a variable that
overwrites itself (y:=y+1).
This would require fort the example to also have an else branch (as the
condition is not constant), which makes modeling the desired behavior more
difficult.
2. Variable y is calculated in the when block.
Real[3] y(start={1,2,3});
algorithm
when sample(0,0.1) then
y := {1,2,3}*time;
end if;
This makes the variable discrete and initializes it to the pre-value when the
algorithm is executed anew. As the latter is updated after an outer event step,
the desired value is preserved due to the second pass ignoring the
instructions in the when block.
3. Variable y receives the annotation
NoAlgorithmInitialization=true:
10-36 SimulationX 3
Real[3] y(start={1,2,3})
annotation(NoAlgorithmInitialization=true);
algorithm
if sample(0,0.1) then
y := {1,2,3}*time;
end if;
This annotation prevents the assignment of the start or pre-value as

mentioned above so that the previously assigned value is preserved, once the
condition is not true.
10.5.6.2 Outputs of algorithms

In order to ensure a conform behavior of Modelica models, restricted outputs of
algorithms with a condition that is constantly False are no longer removed from
the algorithm. That means that they are always set to their pre-value or start
value at the beginning of the algorithm. They are also considered output of the
algorithm (i.e. they are calculated by the algorithm) if they are not assigned in the
algorithm due to their constant condition set to False.
One exception are variables with the annotation

NoAlgorithmInitialization=true. These variables are not reset to their
initial or pre-value at the beginning of the algorithm. If they are assigned False
only within the constant condition, they do not have a defined value. Hence they
are no longer interpreted as an output of the algorithm.
10.5.7 The stateSelect attribute

Up to SimulatoinX 3.6, the stateSelect attribute had been used to define
whether a variable becomes an iteration variable within an algebraic loop. That
was not compliant with the Modelica specifications.
In Modelica, this attribute defines:

which variable becomes/remains an ODE state during the index reduction
and which variable becomes a dummy variable.
Whether a variabl becomes an ODE State despite the fact that no derivation
is included in the original system.
In order to make the functionality of stateSelect available also in

SimulationX 3.7, a new attribut iterSelect has been introduced.
It is an enumeration with the same range of values (type) as stateSelect.
SimulationX 3 10-37
v.iterSelect=StateSelect.never The system tries to prevent v from

becoming an iteration variable
(unless there is no other way, which
will result in a warning message)
v.iterSelect=StateSelect.avoid The system tries to prevent v from
becoming an iteration variable
(unless there is no other way, but no
warning message will be shown)
v.iterSelect=StateSelect.default No special treatment
v.iterSelect=StateSelect.prefer Preferred during the selection of the
iteration variable in blocks.
v.iterSelect= StateSelect.always Always becomes an iteration
variable, an explicitly assigned
equation becomes a residual and is
solved numerically.
The attribute iterSelect should only be used if absolutely necessary!
For non-functional models with stateSelect, the attribute should be deleted for
the time being or set to StateSelect.default to investigate the model further.
10.5.8 Bus systems

Bus systems in SimulationX are represented by signal connections carrying
vectors. In Modelica, all elements of a vector must have the same data type.
Throughout a bus system, different data can be transmitted over different
connections. Therefore, SimulationX allows for all vector elements to be treated as
separate variables. In SimulationX 3.6, this did not require a particular designation.
In SimulationX 3.7, however, the output port must have the annotation
DecomposeArray=true.
This port is called generator port and determines the dimensions of the bus which
all connected input ports adapt. The data type of the vector element is derived from
the variables that are connected with the input ports through equations. Only
simple types, such as real, integer, Boolean, string and enumeration types, are
permitted.
The expression in the dimension of the generator port and the selectors of the
vector element at the input ports must be constant and calculable for the analysis
time during reading from and writing to the bus. Any changes later on require a
new analysis.
It is also tested whether the variable connected with a bus component have the
same value type. If not, an error message is shown.
10-38 SimulationX 3
The following example includes a simple bus system with a controller and an
actuator as well as a bus generator and two sensors. For better readability, all
graphical annotations have been removed.
model Model1 "Simple BusSystem"

model BusGenerator "Bus Generator"
parameter Integer n=6 "No. of Bus Channels";
output SignalBlocks.OutputPin bus[n] "Bus Generator Port"
annotation(DecomposeArray=true);
end BusGenerator;
model Controller "Controller"
input SignalBlocks.InputPin bus[:] "Connector to Bus";
Real pR=sin(2*pi*self.time) "Real Bus Input";
Integer pI=integer(pR+0.5) "Integer Bus Input";
Boolean pB=if pR>0.5 or pR<-0.5 then true else false "Boolean
Bus Input";
Real varR "Real Bus Output";
Integer varI "Integer Bus Output";
Boolean varB "Boolean Bus Output";
equation
// write bus signals
bus[1] = pR;
bus[2] = pI;
bus[3] = pB;
// read bus signals

varR = bus[4];
varI = bus[5];
varB = bus[6];
end Controller;
model Actuator "Actuator"
input SignalBlocks.InputPin bus[:] "Connector to Bus";
Real varpR=cos(2*pi*self.time) "Real Bus Input";
Real varR "Real Variable (Function of pR and Outputs)";
Boolean varB "Boolean Variable (Function of varR)";
Real pR_res "Real Bus Output";
Integer pI_res "Integer Bus Output";
Boolean pB_res "Boolean Bus Output";
equation
// read bus signals

pR_res = bus[1];
pI_res = bus[2];
pB_res = bus[3];
// approach
varpR=cos(2*pi*self.time) "Real Bus Input";
varR =varpR + pR_res + pI_res + (if pB_res then 1 else 0);
varB = if varR>1 then true else false;
// write bus signals

bus[4] = pR;
bus[5] = integer(varR);
bus[6] = varB; // write a boolean signal
SimulationX 3 10-39
end Actuator;
model Sensor "Sensor"
input SignalBlocks.InputPin bus[:] "Signal Input";
Variable busOut "Selected Signal";
parameter SelectBusChannel channel "Select Bus Channel";
type SelectBusChannel = enumeration(
c1 "Bus Channel 1",
c2 "Bus Channel 2",
c3 "Bus Channel 1",
c4 "Bus Channel 2",
c5 "Bus Channel 1",
c6 "Bus Channel 2") "Select Bus Channel";
equation
// read bus signals
busOut = bus[channel];
end Sensor;
BusGenerator busGenerator1;
Controller controller;
Actuator actuator;
Sensor sensor1(channel=Sensor.SelectBusChannel.c1);
Sensor sensor2(channel=Sensor.SelectBusChannel.c2);
SignalBlocks.Connection bus;
equation
connect(bus,actuator.bus);
connect(bus,busGenerator1.bus);
connect(bus,controller.bus);
connect(bus,sensor2.bus);
connect(bus,sensor1.bus);
end Model1;
10.5.9 Miscellaneous
10.5.9.1 Assigning a variable in when blocks in the equation section
In the past (example):
when x>1 then
y = 1;
end when;
when x<-1 then
y = -1;
end when;
Problem: Error: The equation system is structurally singular. There are too many
equations.
Solution:
when x>1 then
y = 1;
elsewhen x<-1 then
y = -1;
end when;
Use when .. elsewhen .. end when in order to define an unambiguous order.
10-40 SimulationX 3
10.5.9.2 The operator last(v) at the starting time

The last()operator is a SimulationX-specific operator which derives the value
of a variable during the simulation from the point of the last valid step.
At the point of initialization, the operator delivers the value for the start attribute.
As a new feature in SimulationX 3.7, the value is updated after the initialization
iteration, but before the first event iteration at the starting time. That way, it returns
the result of the calculation of consistent initial values before the first event
iteration, which corresponds more or less with the behavior during the simulation.
The existing value of the start attribute is especially useless for variables with
fixed =false as it is merely an estimate where the iteration is supposed to start
and is updated during the calculation of the initial value.
10.5.9.3 Global parameters and variables in the model

The parameters and variables in the model
tStart, tStop, dt, dtProtMin, absTol, relTol, dtMin,
dtMax, dtDetect, gravity, gravity3D, pAtm, TAtm, iSim,
nSim
are now marked as inner so that they can be addressed through a local outer
declaration, e.g.
outer parameter Real dtMax;
10.5.9.4 References to variables of other types

Because of resolving references is now fully conformant to the Modelica
specification it is not possible to refer to variables of other types directly. Also
references inside the model hierarchy are not permitted anymore.
Example:
model A
model B
Real b=a; // <- Error: unknown variable a referenced
end B;
Real a=1;
B c;
end A;
A d;
Referencing of constants is allowed:
model A
model B
Real b=a; // <- ok, a is a constant
end B;
SimulationX 3 10-41
constant Real a=1;

B c;
end A;
A d;
To solve this problem, the inner/outer concept of Modelica has to be used.
Solution:
model A
model B
// resolved to enclosing inner with same name
outer Real A;
Real b=a; // ok: a is outer variable
end B;
inner Real a=1; // used variable
B c;
end A;
A d;
10.5.9.5 Input variables

Assignments to input variables in functions and blocks are not permitted. An
auxiliary variablie is required.
Error message: In the function "", something is assigned to

input "beta" in the statement
"beta:=max(beta,0.10000000000000001);".
10.5.9.6 Model variable time

The model variable t containing the current simulation time was renamed to
time; t is now only an alias for compatibility purposes in older models. New
models use time.
10.5.9.7 Settings in the simulation control dialog

The settings "no symbolic derivation" and "no index reduction" are no longer
available.
The former is now part of the index reduction. Models can no longer be simulated
without index reduction. These settings have become obsolete anyway as potential
conflicts which they were supposed to address no longer occur due to the
integration of both steps.
Also the switch for "Optimization for ODE" has been removed (now performed by
default).
10-42 SimulationX 3
10.5.9.8 Propagation of parameter activity

In SimulationX 3.6 the activity (active attribute) of parameters was propagated
from inner (compound-) parameters to outer parameters as soon they were
referenced directly at the inner, e.g.
element1.p=p;
element2.p=p;
means
p.active:=element1.p.active;
p.active:=element2.p.active; .
Therefore it was not clear, which value p.active gets at the end, because the
values of element1.p.active and element2.p.active may be different in
general.
To reach unambiguousness, in SimulationX (since version 3.7) the attribute is only

propagated if there is an 1:1 relation between inner and outer parameters, e.g. in
the example above, the attribut is not propagated anymore.
To get the propagation also in case of multiple references from a dedicated inner
parameter, the references in all other inner parameters have to be put in
parenthesis.
Thus, are not counted as direct references anymore and will be ignored, e.g.:
element1.p=p;
element2.p=(p);
means
p.active:=element1.p.active;
element2.p.active hat keine Bedeutung mehr fr den Wert von p.active.
SimulationX 3 10-43
10-44 SimulationX 3
by
FAQ
General
11 FAQ Frequently asked questions

11.1 General
Will I receive support within SimulationX?
Within SimulationX you have the Windows-typical Online Help menu, where
you find useful information and hints for most functions and almost all library
elements. Just access the "Help" menu.
How can I get in touch with ITI for any technical questions?
Whenever questions and problems occur, you can rely on rapid and professional
back-up from the ITI support team. The simplest and quickest way is to use the
ITI HelpDesk online, which is open to everyone. Alternatively, send an email to
support@simulationx.com. Either option you chose we will respond as quickly
as possible.
Where can I get information and the latest version of SimulationX?

In your personal area in our customer center on http://www.simulationx.com/
you can find the latest information and get quick access to our highly qualified
ESI ITI staff. You also receive the latest news on current developments of
SimulationX. Just fill out the registration form, select a user name and
password. Once registered youll be able to modify your personal data at any
time. You will find a lot of information, which could answer your questions, as
well as tutorials, application examples and download options for additional
tools, in our customer center.
How to register for the ITI HelpDesk?

In order to use the ITI HelpDESK please follow this
http://helpdesk.simulationx.coml. Once your registration is completed, you will
immediately receive a user name and password, allowing you to log on to the
HelpDesk.
Can I get support in my country?
Yes. We have a large number of authorized partners all over the world who
offer technical support. To find out your local partner, please have a look at our
partner list online on https://www.simulationx.com/iti/international-
distributors.html .
SimulationX 3 11-1
User Manual 11. FAQ Frequently asked questions
11.2 Installation/Licensing
Problem Reason/Help
I used the student Start SimulationX as Student Edition. Open the dialog
edition and would Licensing in the menu Extras Options of
like to use a certain SimulationX program. Select below SimulationX start as:
edition (Evaluation, the desired edition for the next program start.
Professional, etc.)
now.
Please close SimulationX. After the restart you are requested

to select a license medium - Key/Dongle or license file -
according to the desired edition.
I receive the
following error
message when
starting
SimulationX.
Please examine first whether you use the license file on the
computer from which it has been requested.
Moreover you should always use the configuration of the

computer which was present at the time of the license
requirement. The WLAN and other network-dependent
devices, as PDA can affect the MAC address read out by the
program. Normally it helps to turn on/off the appropriate
devices, in order to solve the problem. If this does not lead to
success, please request a new license file from ITI.
11-2 SimulationX 3
Installation/Licensing
I receive the All licenses of this file are being used. The users are
following error displayed as follows (for single-user license - the computer
message when name, for network license - user+++computer name). Select
starting another license file.
SimulationX: If no user is present and you receive this message never-
"No free license theless, then the license file is probably damaged. Overwrite
available." the existing license file with the before provided backup
copy.
I do not see the Check under Extras Options in the tab Libraries and
newly acquired Modules, if the appropriate libraries selected for use. If
libraries. necessary, they put the appropriate hooks.
When you start For this problem there are several causes:
SimulationX 1. There is no key detected because the protective
the key is not software is not installed or is not running properly. To
recognized even check if the service for the protection software is
though it is running, go under Start Control Panel
plugged. Administrative Tools ->Services. A service like
Sentinel Protection Server should be running. If this
is not the case, start the service manually.
2. If the service does not appear in the list, try to re-

install it by running the setup of SimulationX and
install the protection software. Alternatively the driver
can be found here: http://www.safenet-
inc.com/support-downloads/sentinel-drivers/
3. If this service does not start and it is used by other

software on this computer (e.g. NI software), then
apply the workaround which you can find on the
Install-CD in the directory Dongle. Double-click the
file NIWorkAround.reg makes the appropriate entries
in the registry. After a restart of the computer the
service should work properly.
The Cmcontainer is First, make sure, that the CodeMeter Runtime is installed on
not listed below the that computer and the CodeMeter Network server is running.
computer, where it The latter needs to be started manually after the setup. To do
is located so, go to the http://localhost:22350/ConfigServer.html and
physically. tick the box behind Run Network Server.
SimulationX 3 11-3
CodeMeter Runtime Installers are available for both 32bit

and 64bit Windows operating systems.
The computer, If the desired computer is not listed after a scan of the entire
where the network, you have the option to manually add it to the server
Cmcontainer is search list of your local CodeMeter License Server.
located physically, To see a list of computers currently visible to your
is not listed in the CodeMeter License Server, click Refresh and see the
network tree. proposed computers in the drop down list below the search
text field.
To add a computer to this list, you need to go to the

configuration site http://localhost:22350/Configuration.html.
The button also takes you there. When done with the
changes, click Refresh again, to make sure it appears in the
drop down list.
Please note, that an empty server search list implicates
CodeMeter to scan the current subnet, but if the list is non-
empty, CodeMeter scans only the listed computers for
license containers.
The Activate this There are different reasons for this:
container button is The selected container is only valid for a previous
disabled. version of SimulationX. The version number is
derived from the Registration number.
The expiration date of the current edition module has
passed.
The container only allows local use, but you are trying
to access it from a remote computer.
There are no free licenses for the current edition left.
11-4 SimulationX 3
Simulation/Computation
11.3 Simulation/Computation
All troubleshooting actions which depend on the error message are marked by .
Since the causes leading to this warning or error message are rather complex in
most cases you should read the complete Reason/Help text before you begin to
localize the problem.
11.3.1 BDF and MEBDF Solver

The following section extends section 6.9. It describes the handling with warnings,
error messages and selected problems occurring during the simulation with BDF
and MEBDF. For debugging and troubleshooting it is recommended to repeat the
following sections of chapter 6
6.1.2 Workflow of the Calculation over Time,
6.1.3 Available Solvers,
6.4 Equilibrium (Static / Steady-State) or
6.9 Troubleshooting: What should I do if
and to know the used terminology according to chapter 13.
The following predeterminations are valid

Tracing can be activated according to 6.1.1.4. The relevant tracing item will be
referred by its name, e.g. Solver/States
The usage of the parameter traceOn is described in section 6.1.1.4.
See 6.1.1.5 for further simulation parameters of menu Simulation/Transient
Settings/Solver/Further Parameters. The relevant parameters are referred by
its name, e.g. dblResRelError.
Error message Reason/Help

Warning: The Parameters without a value are interpreted as zero.
parameter has You may ignore this warning if you are sure that the
no start value, 0 is value zero is entered for all empty parameters. When
assumed. you expand this message, all respective parameters will
be displayed.
Warning: System is This warning usually indicates a modeling error or an
singular! unfavorable model structure. It is displayed when the
Jacobian matrix of the model is structurally singular. This is
the case, for instance, if:
1. Zero lines occur:
No state variables and no derivatives are entered in the
equation.
SimulationX 3 11-5
This case exists, for instance, if electric connections

are switched off through ideal switches, i.e. if they
are in limbo. floating potentials, node potentials
2. Zero columns occur:
There is no equation for the respective state variable and
its derivatives.
3. Columns with only one entry which is not zero occur
twice: There is only one equation for two state variables
or their derivatives.
The third case occurs most frequently. Reasons could
be:
Constraints connected in parallel (use just one
constraint instead),
Rigid frictions connected in parallel (use just one
friction element which contains the sum of the
sticking and slipping friction forces of the two
original frictions
Rigid end stop in parallel with rigid friction (use
the built-in friction of the end stop instead)
over-determined multi-body models,
parallel-connected voltage sources,
series-connected current sources.
If you expand the trace message, you get information
about the state variables and equations where the
problems occur.
For the analysis:
In the expanded trace message the following additional
information is provided for each singular part of the model:
The number of equations and the number of states
(smaller than the number of equations), where all
other states and their derivatives do not contribute to
the selected equations.
or
The number of states and the number of equations
(smaller than the number of states), where the selected
states and their derivatives do not contribute to other
equations than the selected ones.
or
When the number of states and equations are equal,
both messages are shown and are marked as (a) and
(b).
11-6 SimulationX 3
For columns with only zero values no equations were listed.

For rows with only zero values no states were listed.
This can be reviewed if the tracing for Solver
Jacobian is turned on and the two Jacobian matrices
dF/dY and dF/dYP right before the appearance of the
singularity warning are observed. Therefore these
matrices have to be understood as being placed on top
of each other. Zero rows or columns will show only
zero elements in both matrices (if required, the tracing
can be restricted using the parameter traceOn).
The states involved in the singularity can also be searched in
the model directly from the tracing message (see Section
6.1.1.4).
In order to find out the assignment between an equation
name and the equation itself, the symbolic Jacobian
generated during the symbolic analysis can be used (enable
Equations Symbolic Jacobian).
SimulationX can principally compute singular models.
However, the index cannot be computed. Due to this the
initial value computation and the time domain simulation can
fail especially with differential algebraic equations (DAE).
Calculation times will also be extended.
Therefore, you should modify your model as long as
this message does not longer appear.
Calculation of This problem can occur if
consistent initial 1. no consistent initial values exist for the model,
values failed! 2. inconsistent initial values are defined and fixed for a
DAE,
3. the algorithm fails.
Examples for the first case are mutually contradictory
equations or non-solvable equations like x = x + 1 or
x2 + 1 = 0 .
The second case is present if there are fixed initial values for
rigidly coupled connections (for example by a rigid gear)
with inconsistent initial values (not matching the gear ratio).
Another example is the equation x 2 1 = 0 with fixed initial
value not equal to 1 or -1.
The third case occurs for the equation x 2 1 = 0 with a non-
fixed initial value equal to zero. Assuming the Global
Symbolic Analysis does not solve this equation and the
Jacobian is symbolically calculated the linearized equation
SimulationX 3 11-7
reads 2 0 (x 0) 1 = 0 which is non-solvable.

The equations which cannot be fulfilled in the initial value
computation, or the variables which do not converge, are
displayed in the details of the trace messages. The problem
usually stays in the closer environment.
Check now whether your model is a DAE. Display the
indices of the state variables using Solver Indices of
States.
If a state variable has an index greater than zero, it is a
DAE. Check carefully whether you have fixed initial
values in the environment of the non-fulfilled equation
which contradict the equation. Either enter there
consistent values or switch the initial values to free.
If all these steps fail, it may be that the algorithm for the
computation of consistent initial values fails. This occurs, for
instance, with too short or too wide step sizes.
Therefore, first try to reduce the minimum step size
dtMin. If this does not help increase it again and relax
the error bounds instead. For more information see
section 6.8.2.
In order to find out whether too big residuals are the reason
for a failed initial value computation, first expand the error
message. The tracing option Solver Residual Vectors
helps to observe whether residuals have changed in a regular
or irregular erratic way, or whether they have changed only a
little bit or not at all.
1. In the latter case the tracing option Solver Errors in
the residuals through the solution of the linear
system helps to find out whether the equation system
could not be solved.
An explanation can be found by observing the Jacobian
matrices (Solver Jacobian in the tracing). If the
system cannot be solved due to fixed non-consistent
initial values at least one residual is usually located
beyond the tolerance region and no variable states
contribute to this residual(s) (The tracing displays ()
and the message Step 50 of the Calc Initial Values
DAE: Linear system not solvable is generated last
before the error message). The same behavior is
observed when non-fixed initial values contribute to an
equation (see the symbolic Jacobian, tracing options
Equations Symbolic Jacobian and Equations
Symbolic Jacobian for derivations), but the current
11-8 SimulationX 3
derivative of the equation(s) by these states (tracing

option Solver Jacobian) is currently zero.
Remove the incorrect fixations on the initial values or
change the initial values.
If the values shall be accepted even though the linear
equation system cannot be solved, you can increase
the residual tolerances (menu Simulation
Transient Settings , tab Solver, button
Further Parameters,
dblEquaAbsTolFacForDer and dblEquTol)
or the factor for the definition of the of the
unavoidable error during residual computation or the
minimum tolerance respectively -
dblResRelError.
If the derivatives with respect to non-fixed variables
are zero, then calculate the Jacobian Matrix
numerically (menu Simulation Transient Settings
, tab Solver, button Settings). A suitable
homotopy method (see 6.1.2.3) could also help to
leave the singularity.
Damping may be one reason when the residuals only
change slowly. The last row of the tracing Solver
Newton Updates displays the damping factors.
Factors less than 1 indicate that state variables have
exceeded their feasible region (Solver Exceeding
of Minimum/Maximum of states).
In analogy to the Exceeding of Minimum/
Maximum of states (see below) you have to check
whether this is correct model behavior, is caused by an
error in model elements, or arises during the
computation of the iteration steps. For the analysis the
tracing of states (Solver States) and Newton
updates (Solver Newton updates) can be used.
If the observed behavior corresponds to what is
modeled, the model has to be modified (adding or
removing elements; changing initial values or
parameters).
If the model behaves correctly, the attributes min,
minNotReached, max and maxNotReached of
the concerned states can be changed such that the
solution remains in the feasible region (for changing
SimulationX 3 11-9
attributes see section 5.3.1).

2. Repeated erratic changes may be caused by jumps in the
residual computation or errors due to numerical
cancellation effects.
They can be analyzed through the tracing of Equations
Calculation of the equations.
3. Irregular erratic changes indicate initial values beyond
the convergence range.
The equations belonging to a particular residual can be
found by tracing the symbolic Jacobian during the
symbolic analysis (tracing Equations Symbolic
Jacobian).
Think about a suitable homotopy method (see 6.1.2.3)
for the solution.
It can be possible that unsuited values occur at the
beginning of the event iteration. Then change the value
of the parameter iSetValuesToNominal (menu
Simulation Transient Settings , tab Solver,
button Further Parameters). This effects that state
variables and derivatives whose initial values are not
fixed will be set on their nominal values.
Calculation of It is a common modeling mistake that state variables shall
consistent values discontinuously change its value at events/discontinuities but
failed after a they are not capable of such discontinuous behavior. Thus
discontinuity. the value of the state variable is considered as fixed during
the reinitialization of the systems of equation at events/
discontinuities.
Examples:
1. Discontinuous voltage changes over capacitors can only
be achieved by infinite currents (cf. Figure 11.1).
2. Jumps in the transmission ratio of rigid transmissions
cause discontinuous changes of the angle or the angular
velocity. This is physically impossible!
Most troubleshooting advices from Calculation of
consistent initial values failed! are applicable.
We recommend to reduce the tracing output by the
parameter traceOn (e.g. time> 0.56). Best choose the
instant in simulation time just before the occurance of the
error message.
11-10 SimulationX 3
Figure 11.1: False modeling: A capacitor is shorted with an

ideal switch (The model simulates successfully
if the voltage in the upper right connection is
allowed to change discontinuously.)
The problem solution is highly problem dependent. If state

variables are allowed to change discontinuously at
events/discontinuities the notFixed attribute should be set
to true in the attributes dialog (see also section 5.3.1).
Calculation of This message occurs when the calculation was stopped by
consistent initial the user (Simulation Stop or button clicked) during
values stopped an initial value calculation.
The calculated Check whether you have entered and fixed your initial
initial state does values (see section 6.1.2.2, Figure 6.5).
not fulfill my Free initial values merely serve as start values for the
expectations... iterative calculation algorithm. In general, they are changed
by the program.
Error: Cycle found Expand the error message to read the clues of the
during the Event- involved discrete variables and the signs of the
Iteration. zerofunctions.
If more tracing information is required and there are
many event iterations or time steps before the actual
error occurs the tracing output should be restricted by
the parameter traceOn.
The changes of discrete variables can be traced by
Variable Change of values of discrete
Variables.
The zerofunctions and the corresponding sign changes
can be traced by Discontinuities Sign Change of
Zero Functions.
SimulationX 3 11-11
To analyze both the change-over conditions for the

discrete variables and the sign changes of
zerofunctions the Equations Calculation of the
event steps should be traced. The relevant changing
discrete variables, the zerofunctions and the depending
state variables may be located in the tracing output by
the help of the output search function. Thus the
changes of the values between single event steps can
be monitored.
If this event step debugging is too complicated the
state variables, their derivatives and the Newton
update can be traced by Solver States and
Solver Newton update, respectively. Then the
quantities changing their values during the initial
value calculation depending on discrete state variables
can be observed. After each initial value calculation
the state variables and their derivatives hold the values
which lead to the change-over.
The changes in the state variables and their derivatives
result from the change-over of discrete state variables
and hence from the changing residuals. For more
information about these changes in the residuals and
the necessary solver corrections during the initial
value calculation the tracing of Solver Residual
Vectors may be selected.
If the error cause and the troubleshooting are not
obvious the accuracy of the relevant state variables
needs to be increased. For this purpose the absolute
and the relative tolerances (absTol/relTol) and if
necessary the minimum calculation step size dtMin
may be decreased by one order of magnitude. Thus the
absolute values of the residuals after the initial value
calculation also decrease and the variables better
approximate their true values. This process may be
repeated until the approximation of the variables is
sufficient.
If the change-over conditions of the relevant changing
discrete variables and the zerofunctions rather tend to
no (sufficient) change a cycle during the event iteration
is very probably even for the exactly solved system of
equations. Such a case leads to problems of the
change-over conditions of the discrete variables and
the zerofunctions or to problems of the system of
11-12 SimulationX 3
equations due to inappropriate equations. A model

correction is then required.
The required This message indicates that high natural frequencies or low
accuracy cannot be time constants of the model are calculated inexactly.
reached... The elimination of such elements (if not required) may lead
to a faster calculation.
The error message also prints the name of the
problematic state variable. This information is useful
for potential model changes or model reductions.
Reduce the minimum calculation step size dtMin
(menu Simulation/Transient Settings/General) first.
If this is not successful relax the error criteria slightly.
However, error criteria which are relaxed too much,
lead to inexact results.
In certain cases selection of another solver
(Simulation Transient Settings Solver) the
BDF Method or MEBDF Method could help.
If a lot of state variables without parentheses are output the
state variables with the greatest relative changes may be
analyzed first. Alternatively the protocols of the relevant
variables may be plotted. Make sure that the minimum
output step size (Menu Simulation Transient Settings
Genearl, dtProtMin) is sufficiently small.
If the reduction of the time step size does not lead to a
reduction of the error, this may indicate a discontinuous
change of the corresponding state, where the discontinuity
handling was suppressed by noEvent. If the discontinuity
processing is required, remove the noEvent. If no
discontinuity treatment is required, the respective quantity
can be excluded from the accuracy check if it is accessible in
the model. In order to do this, find the state in the model and
set its attribute discontChange to true (see section 5.3.1).
Error: The Proceed as described in the previous step.
solution failed to A reduction of the maximum method order helps with
converge! strongly non-linear models.
For more information check the reasons for the last failed
steps (activate in Simulation Transient Settings...
SimulationX 3 11-13
Tracing under Solver Failed Steps Details, expand

the trace message). Edit the parameter traceOn if
necessary. In order to see whether there have been valid
steps in between, also activate Solver Successful
steps Details.
The following messages may arise
The estimated rate of convergence is greater than
dblMaxConvRate (menu Simulation Transient
Settings Solver Further Parameters).
The tracing of Solver Newton Updates, Solver
States and Solver Residual Vectors should
be selected to output the Newton updates and the
residuals.
Hence it can be observed which Newton updates are
relevant (state variables and expressions without
parentheses), which of them increase or remain
constant and which residuals increase.
The problem solution is highly problem dependent.
Newton updates behaving like the residual vectors
usually indicate problems of the calculation of the
residuals or are due to a very small region of
convergence. The calculation of the residuals can be
traced by Equations Calculation of the
equations.
Decrease the minimum calculation step size dtMin
(menu Simulation Transient Settings
General) if the region of convergence is too small.
Using a smaller minimum calculation step size dtMin
the residual vectors of the predictor step should almost
linearly (with respect to the step size) decrease, too. If
these residual vectors of the predictor step are small
enough the residual vectors of the subsequent corrector
steps should decrease, too. If not there is probably a
problem with the calculation of the residual vectors.
Frequent problem causes are discontinuities of the
calculation of the residual vectors, i.e. a small change
in the input variables results in large changes in the
output variables. For example this may result from
discontinuities deactivated by the noEvent()
operator. In such cases the noEvent() operator
should be removed or the transition of the different
branches of the assignment/equation should be turned
into a continuous transition.
11-14 SimulationX 3
Another problem cause is the loss of accuracy due to

the floating-point arithmetic, for example in
subtracting two large and nearly equal numbers. This
can be tried to avoid by changes in the system of
equations.
There are too many corrector steps, steps with too big
residuals, steps with too big Newton updates.
The changes in the corrector iteration can be traced by
Solver Newton Updates and Solver Residual
Vectors. We recommend to reduce the tracing output
by the parameter traceOn (e.g. time > 0.56). It may
be also useful to trace the Solver States,
Solver Derivatives and Solver Jacobian for
a better understanding of the behavior. However good
model knowledge is required for the debugging.
If there are only steps with too big residuals but no
steps with too big Newton updates the too large
residuals are output in the following way
Residual name (Corrector step) (Residual Value)
The subsequent output of the too large residuals at the
end of the corrector iteration is
Residual name Residual value (Dependent state
variables and their derivatives).
The absolute value of the residual is compared with the
tolerance of the equations dblEquTol (if positive) or
the absolute tolerance of the equations (if set) or the
general absolute tolerance absTol. If the state
variable corresponding to the relevant equation has got
a necessary derivative (e.g. purely as protocol variable)
which does not contribute to the system of equations
then the tolerance is multiplied by
dblEquaAbsTolFacForDer. If the unavoidable
error during the computation of this equation is
comparatively large, the error bound will be increased
under consideration of dblResRelError. The
analysis of the tracing Equations Calculation of
the equations,Equations Calculations of partial
derivations,Solver Newton Updates and
Solver Residual Vectors may reveal why the
residuals do not decrease and where corrections are
required. If however the residual values should be
accepted then the exceeded tolerances or
dblResRelError need to be increased such that the
SimulationX 3 11-15
equation tolerances are greater than the absolute values

of the residuals.
Changes of the states are too big:
This message is output when the MEBDF solver is
used. The troubleshooting advices from the previous
step (There are too many corrector steps, steps with
too big residuals, steps with too big Newton updates)
are applicable here. Here the residual tolerances are not
used.
The value of a state variable sometimes does not change
during a Newton step even though the absolute value of the
corresponding Newton update (Solver Newton
Updates) is greater than 1e-15*absolute value of state
(Solver States). In that case the corresponding derivate
(Solver Derivatives) is equal to zero and appears on the
left-hand side of an equation (e.g. Equations Symbolic
Jacobian).
Here a special treatment for ordinary differential
equations works: Is the absolute value of the right-hand
side smaller than dblExplicitOdeIs0 (Default
value 1e-20, Further Parameters, c.f. 6.1.1.5),
then the left-hand side will be set equal to zero.
Does the right-hand side oscillate around zero (even
though it should be equal to zero e.g. as numerical
difference of two equal values), then the parameter
dblExplicitOdeIs0 should not be changed
because it prevents from unnecessarily small time
steps.
Does the absolute value of the right-hand side grow slowly
after it has been zero for a while (e. g the velocity while
starting a car), a negative value for dblExplicitOdeIs0
should be set. Otherwise the special treatment can lead to
invalid steps.
Linear system not We recommend to reduce the tracing output by the
solvable and order parameter traceOn (e.g. time > 0.56). Detailed information
and step size not on the problem cause may be gained by appropriate tracing.
reducible 1. The tracing Solver ->Failed Steps ->Details displays a
non-solvable equation.
2. The tracing Solver ->Errors in the residuals through
the solution of the linear system displays the non-
solvable linearized equations. Solver ->Residual
11-16 SimulationX 3
Vectors and Solver ->Jacobian display the iteration

steps of the linearized system of equations. Equations -
>Symbolic Jacobian and Equations ->Symbolic
Jacobian for derivations indicate which symbolic
equation belongs to which equation name and which
elements of the Jacobian vanish.
Thus the singularities of the non-solvable system of
equations can be debugged.
The reduction of the pivot limits
dblPivGaussNotZero (c.f. 6.1.1.5) or
dblPivSparseNotZero (c.f. 6.1.1.5) of the
appropriate solvers may be of help if there are small
elements in the Jacobian or an ill-conditioned Jacobian.
Additionally the RHS threshold
dblRightSideGaussNotZero (c.f. 6.1.1.5) may
be increased if the found solution shall be accepted.
However model corrections are probably required and
recommended.
Exceeding of Predictor, maximum/minimum of the state exceeded.
Minimum/ The name of the state variable, its value and the exceeded
Maximum of states maximum/minimum during the predictor step are displayed.
Detailed model knowledge is required for the assessment of
the problem cause. It can be an error in the model elements
or an erroneous prediction during the predictor step.
The relevant state variable may be displayed in a result
window. It is recommended to set a high protocol
resolution (dtProtMin = dtMin) for the time of
the debugging.
If the observed behavior meets the model behavior a
model change is required. Consider e.g. a pump
feeding in a closed volume of a hydraulic circuit. The
pressure of the volume will increase until it exceeds the
allowed maximum.
If the model behavior is correct the attributes in the
attributes dialog (see section 5.3.1) min,
the relevant state variable may be adjusted to set the
feasible region.
SimulationX 3 11-17
If the value (leading to the error message) must not be

taken the model (e.g. start values, model parameters)
needs to be modified.
If the predictor step is too large reducing the minimum
calculation step size dtMin may help.
Error: Exception The exception during the calculation (usually during the
during the calculation of the residuals, rarely during the calculation of
calculation the derivatives or in the DAE solver) aborts the simulation.
The first two cases are easier to debug. It is recommended to
restrict the tracing output by the parameter traceOn (e.g.
time > 0.56). The analysis of the tracing output of
Equations Calculation of the equations and
Equations Calculations of partial derivations may
reveal the error cause that is displayed at the bottom of the
last expanded trace. This error may then be backtracked.
Some additional solver information (Solver Failed
Steps Details, Solver Successful Steps Details,
Solver States or SolverResidual Vectors) may be
useful for structuring the trace output.
Mostly the model equations need to be modified. In
some cases the error is due to invalid values of state
variables. Then it is advisable to adjust the attributes in
the attributes dialog (see section 5.3.1) min,
the relevant state variable to set its feasible region.
Error during the This message indicates an inherited error which occurs if a
calculation of the state variable leaves its feasible region during the corrector
damping factor for iteration.
the Newton update The relevant state variables can be traced by Solver
Exceeding of Minimum Maximum of states. Thus it
should first be analyzed why the state variables reach invalid
values.
Steady State It is important to check carefully whether your system has an
(Equilibrium) not equilibrium solution at all. You can check this by computing
found! the model over a larger period of time. If all oscillations
decay, your model probably has an equilibrium. There also
exist periodically oscillating systems which have
equilibriums (e.g. the undamped one mass oscillator).
section 6.4, Figure 6.31 shows simple models which do not
have an equilibrium.
When you are sure that equilibrium exists, it may be
11-18 SimulationX 3
that the solver method cannot find it. A non-linear

system of equations is solved with a special iterative
method. The initial values are used as start values for
the iteration if there was no (initial value) calculation
before or the simulation was reset. Otherwise if there
was a successful (initial value) calculation before the
current values are used as start values.
If the state which is to be determined is too far from
the start values, it cannot be found. Then you may
enter initial values manually which are closer to the
solution. With a little auxiliary calculation or a pre-
simulation over a certain time you will get usable
values.
After this pre-simulation the calculation of the
equilibrium can be started. All time-dependent values
(e.g. time-dependent characteristic curves, functions or
presets) need to be set to the current point in time of
the equilibrium calculation.
If the calculation of the equilibrium fails due to too
large residual vectors, the tracing of the residual
vectors (Solver Residual Vectors) displays if
there are only marginal, continuous or discontinuous
changes or if there are changes at all.
Expand the error message to check if too large
residuals result in the failed equilibrium calculation.
The mapping between the residuals and the equations
can be displayed by tracing of the Equations
Symbolic Jacobian during the global symbolical
analysis.
If there are no changes at all in the residual vectors the
tracing of Solver Errors in residuals through the
solution of the linear system may indicate whether
the system of equations is solvable or not. The tracing
Solver Jacobian may give a further clue.
Damping may be one reason if the residuals only
change slowly. The damping factors are displayed in
the last row of the tracing Solver Newton
Updates. Factors less than 1 indicate that state
variables exceeded their feasible region. (Solver
Exceeding of Minimum/Maximum of states). If this
does not apply then the check of the sufficient gradient
may be virtually deactivated by setting
dblMinAlpha and rho to a value marginally less
SimulationX 3 11-19
than 1 (e.g. 0.99999) for the equilibrium calculation.

If the feasible region has been left, in analogy to the
Exceeding of Minimum/Maximum of states (see
below) you have to check whether this is correct model
behavior, is caused by an error in model elements, or
arises during the computation. The tracing of states
(Solver/States) and Newton updates (Solver
Newton Updates) can be used for the analysis.
If the observed behavior corresponds to what is
modeled, the model has to be modified (adding or
removing elements; changing initial values or
parameters).
If the model behaves correctly, the attributes min,
the concerned states can be changed such that the
solution remains in the feasible region (for changing
attributes see section 5.3.1).
Repeating erratic changes may be caused by jumps in
the residual computation or errors due to numerical
cancellation effects. They can be analyzed in the
tracing Equations Calculation of the equations.
Irregular erratic changes indicate initial values outside
the convergence region (see above). Then trying a
homotopy method (see 6.1.2.3) can sometimes help to
find a solution.
Calculation of This message occurs if the calculation of the equilibrium has
equilibrium been stopped by the user (Menu Simulation Stop or
stopped have been used).
Error: At least one The value for the absolute tolerance absTol must be non-
absolute tolerance negative (menu Simulation Transient Settings
is less or equal General).
zero! Set absTol to a non-negative value (positive if
possible)
If absTol is already non-negative, absTol has been
changed individually for the displayed state variable or one
of its synonyms (tracing option Equations/Variables). In
order to solve the problem, trace the equations at the end of
symbolical analysis (Equations Equations at end of
symbolical analysis).
After expanding the output, one can search for absTol with
11-20 SimulationX 3
a negative value and the associated variable. The variable

can now be found in the model and its attribute absTol can
be changed (see section 5.3.1).
Error: At least one The value for the relative tolerance relTol must be non-
relative tolerance is negative (menu Simulation Transient Settings
less or equal zero! General).
Set relTol to a non-negative value (positive if
possible)
If relTol is already non-negative, relTol has been
changed individually for the displayed state variable or one
of its synonyms (tracing option Equations Variables).
In order to solve the problem, trace the equations at the end
of symbolical analysis (Equations Equations at end of
symbolical analysis). After expanding the output, one can
search for relTol with a negative value and the
associated variable. The variable now can be found in the
model and its attribute relTol can be changed (see section
5.3.1).
Error: The number This error message occurs if the number of equations does
of states and the not match the number of state variables in the Modelica
number of equation section(s) of at least one of the model elements.
equations are not This often indicates a programming error of the custom
equal! Modelica equations.
The time domain Long computation times may have the following reasons:
simulation takes (a) Extensive models,
very long! (b) Strongly non-linear models,
(c) High eigenfrequencies in the model,
(d) Frequently occurring events (discontinuities),
(e) The computer hardware capability is not sufficient.

As to a) Large models always need longer calculation times.

Follow the following principles in modeling:
Create models which are not too detailed. Tailor
your models for the computation task.
Use the libraries for modeling. The modeling of
physical systems by means of signal blocks is often
inefficient and prone to errors.
More complex relationships (control algorithms,
behavior models...) are frequently imaged with
complicated signal structures. This can usually be
SimulationX 3 11-21
done simpler and more efficiently using Modelica

for programming.
ITI GmbH has rich experiences in efficient modeling of
complex systems. Make use of these experiences.
As to b) If you deal with highly non-linear models, it is
important that you scan spots where slopes change highly,
with a small step size.
Check whether the model can be linearized. Another
option is to model the high change with a characteristic
curve which has a kink. This method has been applied,
for instance, to the electric diode.
As to c) To find out whether the model has high natural
frequencies, start the natural frequency analysis (see 6.5.1).
As long as a model part oscillates with a frequency in this
range, you must use small step sizes for your calculation.
Only after they have decayed sufficiently, the advantages of
the stiff BDF method take effect.
Stiff model parts can often be modeled as ideally rigid
or a model reduction can be performed.
As to d) Event time instants are determined exactly with the
step size control. The continuous integration is stopped and
the model is reinitialized. All these steps need time for
calculation.
Therefore, try to create as few events as possible. The
occurring events can be traced by Discontinuities
Sign Change of Zero Functions.
When you work with characteristic curves, an event will be
created at every sampling point in linear and staircase
interpolation. You can reduce the number of events there by:
reducing the number of sampling points,
using spline interpolation, arc, hyperbolic or quadratic
approximation, or
activating "No Handling of Discontinuities" (if
possible).
As to e) Refer to the hardware requirements of SimulationX.
If you log a very large number of result variables and only
little main memory is available, the results are entered during
the computation in the dislocation file on your hard disk (cf.
section 7.6.4). The frequent accesses slow down the
computation highly.
11-22 SimulationX 3
In this case, you should:

clear storage of the main memory (menu Extras
Options Storage),
reduce the number of events to be logged,
increase the value of the minimum output step size
dtProtMin.
Other reasons for low computation speeds are:
many event windows,
many immediate displays,
many tracing outputs (output window),
animation of complex 3D models on a graphics board
without 3D hardware acceleration.
Examination of slow simulations caused by the solver:

At the end of a simulation the computational effort can
be recorded (tracing option Solver Summary).
Here you can see if there have been many
discontinuities or many invalid steps, which are one
reason for a slow simulation. Beside this, frequent
limitations and resets of the time step size below the
maximum time step size due to zero functions as well
as due to the error estimation during simulation will
cause many successful steps and are another reason for
slow simulation. Reviewing the protocol of the result
quantity dt (current step size; accessible through the
Model Explorer or the properties window of the
model) allows to identify the critical time intervals.
Therefore the Minimum Output Step Size
dtProtMin should be sufficiently small, so that all
step sizes of interest will be displayed.
Using the (ME)BDF solver most of the computation
time is usually required for the computation of
residuals. Therefore the number of residual
computations is a good measure to identify intervals of
slow simulation speeds. The number of residual
computations is stored in the 7th component of the
solverInfo vector (accessible through the Model
Explorer or the properties window of the model). The
interesting time intervals will show a significant
increase of residual computations.
SimulationX 3 11-23
The identified critical time intervals can now be

entered into the traceOn parameter of the model in
order to allow a closer examination.
In case that many discontinuities appear, this can be
traced using the tracing option Discontinuities
Discontinuities. The reasons for the discontinuities
can be identified by tracing Variable Value
Change of Discrete variables and Discontinuities
Sign Change of Zerofunctions also. In order to only
identify the time instants where discontinuities take
place, the 8th component of the solverInfo vector
(accessible through the Model Explorer or the
properties window of the model) can be examined. For
this dtProtMin should be at maximum equal to
dtMin. For very small intervals between
discontinuities dtProtMin should be set to
dtDetect.
In the case of many invalid steps additional
information can also be collected from the
solverInfo vector. Of interest are the components
3 (number of not accepted steps, either failed or not
accepted due to discontinuities), 4 (number of failed
steps with too big error estimation) and 5 (number of
failed steps due to insufficient convergence). The result
window displays their number between the last
successful step and the current successful step, so the
Minimum Output Step Size dtProtMin should be set
sufficiently small. Failed steps can also be recorded in
the tracing (tracing option Solver FailedSteps
Details). The tracing allows finding out the reason for
a failed step. The problem examination continues as
described for the respective errors in the examined
interval.
The tracing of the limitation of the solver step size due
to zero crossings is shown by (Discontinuities
Time Limitation due to zerofunction estimation
before a step and Discontinuities Time set back due
to sign change of a zerofunction after a valid step).
If none of the above reasons applies but nonetheless
many successful steps with small step size are
encountered, the error estimation is the reason for the
problem. The 6th entry of the solverInfo vector
11-24 SimulationX 3
should not be significantly larger then 1 (again,

dtProtMin should be sufficiently small). The
SimulationX Performance Analyzer (menu
Simulation Performance Analyzer) identifies
the state variables, which force the solver to a small
step size. The performance analyzer has first to be
activated (checkbox on top of the dialog) and then will
record information during simulation. Also check the
box for Record the values during simulation time.
After a simulation, critical time intervals can now be
observed and the states can be sorted according to their
influence on step size reduction. Of particular interest
are states, whose influence significantly grows between
the start and the end of the observed time interval.
These can be examined by opening a result window
and observing the interval in question (again,
dtProtMin should be sufficiently small). If the
quantity is not directly accessible, a general function
element (f(x) in the Signal Blocks library) can be used
for display. The internal quantity to be displayed is
entered as the expression of the general function block.
If the strong change of the corresponding state
variables is correct, they have usually correspondingly
small time steps chosen to represent this quantity with
sufficient accuracy. If the corresponding state variables
are not interesting for the calculation, then the major
changes can be skipped without reducing the time step
size. In this case, discontChange can be set to true
in the corresponding attributes dialog (see section
5.3.1).
Can I be sure that There are built-in tests in the solver methods which verify
the simulation that the results are correct. These tests refer to the state
results are correct? variables. Only a single simulation step is required to check
or the state variables and their values (Solver/States).
Computated results Inexplicable results often occur due to:
do not meet my modeling errors,
expectations. the input of incorrect parameters,
insufficient knowledge of the system,
wrong expectations,
insufficient knowledge of the software.
SimulationX 3 11-25
When the solver computes a model without error messages

the results should entirely correspond with the model. There
are exceptions if error criteria relative and absolute tolerance
(see section 6.1.1.1) and nominal values in the attributes
dialog (see section 5.3.1) of the corresponding variables are
not set adequately with respect to the models quality or if
the step sizes are too large.
Then freeze the results and repeat the computation with
smaller step sizes and stricter error bounds. When the results
do not considerably change any longer the optimum settings
were found. Comparative calculations can also be performed
by usage of alternative solvers (switch between the BDF, the
MEBDF and the CVODE method).
A step is accepted when the convergence test and the error
test passed successfully. Both tests use the tolerance =
relTol * value of the state variable + absTol * nominal
value.
The Convergence Test checks the Newton correction

and the changes in the Newton correction during the
iteration in comparison to the tolerance (and during
the BDF method also the residue value in comparison
to the equation tolerance). It estimates the error
between the computed result and the exact result of
the discretized system.
The Error Test checks the difference between the
predictor step and the last corrector step (= sum of the
Newton correction during the corrector iteration) as an
estimator for the discretization error in comparison to
the tolerance. The discretization error is the results
deviation for the discretized system from the DAE
system. It results from replacing derivations of state
variables by difference quotients. For method order 1,
the slope of the tangent at the current point is replaced
by the slope of a secant. This discretization error has a
particular effect when the result curve of the DAE
system changes significantly compared to previous
results. This requires the step size to be reduced
accordingly in order to reflect this in the result.
Concise summary: If the state variable has a great value,

the summand relTol * value of the state variable
dominates. If the value is small, absTol * nominal value
dominates instead. The choice of the nominal value can
11-26 SimulationX 3
impact the accuracy of the calculation if the value of the

state variable converges to zero.
General note on the calculation of tolerance: If the
tolerance is set too low, the step sizes become too small and
the calculation is slowed down or does not yield any result at
all. If the tolerance is set too high, deviations from the
correct value may be too great. This may cause subsequent
errors due to calculations within invalid ranges.
11.3.2 Fixed Step Solver and CVODE

The following section describes the content of warnings and errors which can
occur when using the Fixed Step solver or CVODE and gives hints about their
causes. For debugging and troubleshooting it is recommended to repeat the
corresponding sections
6.1.3.2 Fixed Step Solveror
6.1.3.3 CVODE
and to be aware of the used terminology according to Chapter 12.
The activation of tracing messages is described insection 6.1.1.4.. In the following

we will only refer to the relevant tracing item, e.g. Solver/States
11.3.2.1 Warnings in the context of non-solvable blocks

Quantities which are computed simultaneously inside so called blocks are a
particularity of the Fixed Step Solver and CVODE. These blocks correspond to
systems of linear or non-linear equations which are solved by a variant of the
(iterative) Newton method. The solution can sometimes fail. Then the following
error message occurs.

"Error: System of This message enumerates all involved block variables of the
equations with the non-solvable block and the iteration step when the solution
DAE state(s) fails.
cannot be solved!
"
or
"Error: Equation
with the DAE
state(s) cannot
be solved! ")
SimulationX 3 11-27
An error message follows the above output. It tells us when the error occurs
(during the initialization, at an integration step, during the reinitialization after a
discontinuity, etc.). That is important to find the block equations inside the tracing
Equations/Symbolic Jacobian.
In most cases one of the following four messages will be displayed before the
above error message. They give us more detailed indications why the solution of
the block equations fails.
"Residual is not in This message includes information about the size of the non-
the image of solvable block, the involved block variables, the number of
Jacobian ... with the the non-solvable linearized equation (if all preceding
DAE state(s) ..." equations could be solved) and if the Jacobian has only one
column the values of Jacobian and the residual.
Select the tracing Equations Symbolic Jacobian
and search for one or more involved block variables in
the displayed equations. After you have found the
sought block, try to find out why it is not solvable.
E.g. inconsistent initial values can be the reason for the output of this message
during the initialization:
21.Step: Residual is not in the image of 2*1-Jacobian with the DAE state
_der_connection3.phi: res[1] = 6.5741692360397401 (>4.4408920985006302e-
013) != jac[1][0] * s = 1 * 0
Two error messages follow:

Error: System of equations with the DAE state(s) _der_connection3.phi cannot be
solved! After 21 steps residual is not in the image of the Jacobian.
Calculation aborted because of a problem during the calculation of initial
conditions.
Consider the block equations and the initial values of the involved variables
(several equations have been combined) inside the output of the tracing
Equations/Symbolic Jacobian.
initial: connT.om0.fixed:=true;;
initial: connection3.om0.fixed:=true;
initial: der_connection3.phi=connection3.om.start=connection3.om0=0;
initial: der_connT.phi=connT.om.start=connT.om0=20;
initial:{{
EQUATION<>{_der_connection3.phi=0.65741692360397397*_der_connT.phi}
EQUATION<>{_der_connection3.phi=connection3.om.start}
}};
11-28 SimulationX 3
Then we can easily identify the cause of the problem here: the given initial values
were fixed and are inconsistent.

"the value is One of these two messages will be traced when one block
below the minimum variable tried to leave its valid range, i.e. deceeded its
() of the DAE minimum or exceeded its maximum. It includes moreover
state ", information about the value of the limit violation, the
"the value boundary set in the model and the damping factor which
exceeds the prevents the limit exceedance.
maximum () of Select the tracing Equations Symbolic Jacobian
the DAE state ", and search in the displayed equations for one involved
block variable and the corresponding block equations.
Have a look at them and also at the current values of
the block variables (result window). Try to find out
why the variable tried to leave its valid range.
"Reducing the When multiple limit violations occur consecutively, the

damping factor to solver repeats to reduce the damping factor until its value is
because of the equal to zero. In that case the second message will be traced.
DAE state ",
"DAE state
exceeds a border"
Actually the values of all variables can only be examined by opening a result
window (dtProtMin should be sufficiently small). If the quantity is not directly
accessible, a general function element (f(x) in the Signal Blocks library) may be
used. Then its name must be entered as expression of the general function block.
SimulationX 3 11-29
11-30 SimulationX 3
by
Definitions
12 Definitions
3D-View For models with elements from the libraries MBS
Mechanics, Planar Mechanics, Power Transmissions,
and Animation Bodies a 3D-View is available, in which
the spatial arrangement and the geometry can be
represented and edited. Furthermore, the movement of
the elements can be visualized during simulation and
animation.
Algorithm Is a part of the behavioral description of a type for the
computation of result variables during the simulation.
Analysis Tools integrated in SimulationX, which are helpful for a
fast evaluation of a model. There are different kinds of
analysis:
Model analysis
Transient analysis in the time domain
Linear system analysis.
Natural frequencies and mode shapes of the
linearized system.
Input-Output analysis
Result analysis
FFT Spectral analysis of any physical signal after
the simulation in the time domain
Frequency Response Function (FRF) - computation
of the complex transfer function from input and
output signals simulated in the time domain
Order Analysis
Code export In SimulationX integrated tool for transferring the

functionality of a complete SimulationX model in C-
code. Before the export it is specified, which inputs,
outputs, parameters and characteristic curves will be
available as interfaces in the exported model.
Combo Box Window for the selection of given variants (e.g. units in
the property window or result variables in the result
window)
Component Part of a model or of an element type (parameter,
variables, elements, and connections)
Compound A compound is an element, which is an instance of a
compound type.
SimulationX 3 12-1
User Manual 12. Definitions
Compound Type A Compound type is a combination containing a

submodel structure (including parameters and
description of behavior). Compound types are created
from existing sub-model structures using the
TypeDesigner.
Connection Is a link between elements, which is characterized by its
type (e.g. linear mechanical) and data (parameters,
result variables). A connection can link more than 2
elements. If a connection has branches, it additionally
possesses one or more nodes.
Connector Also termed as pin or port. Designated point of an
element or a Component, at which it can be connected
to another component (e.g., for the transmission of
information). There are different types of connectors
(e.g. for Linear and Rotational Mechanics, Hydraulics,
Electronics, or Signal Inputs and Outputs). Only
connectors of the same type can be linked. Each
connector possesses with respect to the element a
unique name.
Convergency Domain a) During the initial value or equilibrium calculation:
The Domain number of those initial values, for
which the iteration converges to a solution of the
equation system.
or
b) in a time step in implicit methods:
The quantity of predictor values converges for the
corrector iteration to a solution of the system.
Circuit Is part of a model structure containing elements from
one of the Libraries Hydraulics, Pneumatics or
Thermal-Fluid and the associated Connections. Due to
the fluid propagation all connections of the circuit have
the same fluid type.
Diagram view In the diagram view the structure of a model is
composed, edited, and displayed using element symbols
and connecting lines.
Discrete Variable A discrete variable is a result quantity, whose value
changes only at discrete time instants (i.e., at so-called
events).
Domain A (physical) domain in SimulationX is the overall set of
connection type, connector type, possibly fluid types, as
well as physical dimensions, which belong to one
12-2 SimulationX 3
specific physical discipline (e.g., linear mechanics,
rotational mechanics, hydraulics, electronics, etc.) The
availability of a certain domain (e.g. of a connector
type) may depend on the license. Since domains are
internally pre-defined in SimulationX, they cannot be
created by the user.
Element The element is a component of a model. It is created
from an element type. The type specifies the selection
and kind of parameters, the connectors, the result
variables and the algorithms and/or equations. The
element carries the values of the parameters and
variables. (e.g. an element mass1 in the diagram view
is derived from the Element Type
Mechanics.Translation.Mass and has its properties.)
Element Type Description of a class of elements, which have the same
connectors, parameters, algorithms, equations, internal
components, etc. (e.g., the Mass in the library Linear
Mechanics represents an Element Type with the
identifier Mechanics.Translation.Mass
Equation Equations formulate the properties, dependencies, and
physical laws, which hold for a model or a type. Apart
from parameters, equations usually contain several state
and result variables, thus several equations are coupled.
In order to compute the unknown quantities (the state
variables), the set of equations must be solved using a
Solver.
Equilibrium The equilibrium is the state of a model, where
a) the time derivation of all state variables is zero, or
b) the highest derivatives (e.g., the accelerations in
mechanics) are zero.
In mechanics case a) is often termed as static
equilibrium, in fluid power however as steady-state
equilibrium. A system (i.e., a model) can have exactly
one equilibrium, several equilibria, or also none.
Event Time instant during the simulation run, at which
a) state variables of the model (or their derivatives)
change discontinuously,
or
b) the model equations change their structure.
Examples for discontinuities are kinks or jumps in
characteristic curves. Structural changes arise at end
SimulationX 3 12-3
stops, at the transition between sticking and sliding

friction, opening/closing of valves, or backlash in
mechanical elements. Events are recognized by the
Solver before their appearance and especially treated.
External Types User-defined types, which were created below the
predefined package ExternalTypes. They are no longer
supported in SimulationX 3.6 and later, see Chapt. 8.
Fast Fourier The Fast Fourier Transformation permits the
Transformation (FFT) determination of an amplitude response over the
frequency for an available time signal.
Fluid The fluid is a component of a hydraulic, pneumatic or a
thermal-fluid connection. Each fluid has a clear
designator (name), who assigns a database record of
fluid characteristics (and/or the necessary parameters
for their computation) to it.
The fluid database is read when starting SimulationX.
After the fluid type is selected in the parameter dialog
of the connection, the fluid is propagated via the
connected elements to all other connections which
belong to the same circuit. Thus, a uniform fluid is used
in each circuit.
A model might have different circuits, however.
FluidDesigner Integrated tool in SimulationX for developing of user
defined fluid types for the libraries Hydraulics and
Pneumatics (Fluids, gases und mixtures).
Flow Quantity For the physical modeling the SimulationX libraries use
a network approach, where the model is understood as
an assembly of nodes and branches. Flow Quantities
flow through the branches (e.g. currents in electrical
networks).
Frequency Response Numerically determined transfer function between an
Function (FRF) input signal and an output signal. Consists of amplitude
response and phase response (in each case over the
frequency).
Global Types These types exist independently of a model and can be
used in several models. With a transfer of the models
on other computer systems global types, which are used
by these models also have to be transferred separately.
Initial Algorithm Same as Algorithms, but they are only valid while
initial value computation. They are valid additionally to
the equations and algorithms.
12-4 SimulationX 3
They can be used for computation of initial values of
variables or constant parameters (e.g., constant parame-
ters, which must be computed by an iteration loop).
Initial Equations Same as Equations, but they are only valid while initial
value computation. They are valid additionally to the
equations and algorithms.
They can be used for the computation of initial
constraints and describe also the initial state of a model
(or element). They can be used for the computation of
initial values of variables or constant parameters.
Input-Output Analysis Analytically certain response of a model at a defined
output after excitations at a defined input. Represented
as amplitude/phase or real and imaginary part of the
complex system response over the frequency.
ITI Script The integrated Script language of SimulationX for
controlling the simulation over the applications COM
interface.
Internal Types These are all types delivered with the software (contents
of the libraries).
Library Group of functionally related Element Types (e.g., the
Element Types, for a damper, a spring, or a friction, are
contained in the library Linear Mechanics).
Linear System Analysis At the linear system analysis a linearization of the
model takes place around the current operating point.
The results apply thus with nonlinear models only
within an (small) environment around this operating
point.
This are:
Natural Frequencies and Mode Shapes
Input-Output Analysis.
Library Bar Hierarchically structured view of the libraries (e.g.,
Mechanics, Linear Mechanics, Signal Blocks, etc.) and
the element types contained within (e.g., spring, mass,
damper). In the library bar the types appear as symbols,
which provide access to the corresponding type.
Local Types These types are defined within a (superordinate) model
and can be used only there. They are part of the model
and are transferred with it.
Model Representation of a system or a process using of
elements, connections, algorithms, and equations.
SimulationX 3 12-5
A model is always a type of the class model (Element-

type) and can be instantiated.
Model Explorer Structured display and input tool for the properties of
elements and connections in a simulation model. The
treestructured view shows the element and type
hierarchy of the model. The parameters and result
variables of a selected component are displayed in
tabular form and can be edited in the table.
Modelica Quasi-standard of a model description language, which
is developed and maintained by the Modelica
Association. Modelica is a registered trademark of the
Modelica Association. Syntax and semantics of
Modelica are used in SimulationX.
Module Loadable software component (exe, DLL, cat), which
may also contain implementations of element types.
Optimization A process, in which selected parameters of the model
are tuned in such a way, that the behavior of the model
(time functions or values of result variables) is adapted
to a reference in the best possible way (according to
some criterion). For the optimization in SimulationX
separate software is available. It supports the
description of the optimization problem and automates
the optimization process.
Output Area In the Output Area status messages, warnings, and error
messages are logged. These messages are assigned to
different categories (e.g., Simulation or File). The
contents of the output area can be stored, exported in
text format, and printed.
Parameter A parameter is a component of a model, element, or
connection and specifies quantitative properties. The
kind of the parameters is defined in the element type.
The value (a constant or an expression) of the parameter
is entered using the SimulationX user interface or set
via the COM interface.
Polygon Editor Tool for creation, modifying and optimizing contact
geometries used in planar Polygon-Polygon contact
elements.
Potential Quantity For the physical modeling the SimulationX libraries use
a network approach, where the model is understood as
an assembly of nodes and branches. Potential quantities
are physical quantities, which reflect the state of the
12-6 SimulationX 3
system (e.g. temperatures or pressures). They can be
measured at the nodes. The difference of the potential
quantities along a branch is also termed an across
quantity or potential difference.
Property Window Property windows serve for the displaying and
modification of properties of the components (elements,
connections) in a simulation model. On the individual
registration cards values, units, and protocol attributes
can be entered or set.
Protocol Attribute The Protocol Attribute indicates that the computed data
(i.e. time history) of a certain result variable is to be
stored together with the model and can be displayed
after the simulation in a result window.
Propagation Mechanism, which guarantees that all connections of a
Circuit use the same fluid type. Additionally, other
settings of the connection are propagated, i.e., passed on
to all other connections of the circuit. In hydraulics this
concerns the options for temperature and gas fraction
calculation.
Residual Result of the right-hand side of an equation, which was
rearranged in such a way that the left-hand side is zero.
For each vector of state variables, a vector of residuals
is computed. The Solver tries to minimize the residuals
using an iterative method.
Result Variable Variable of a Model, an element or a connection, for
which during the simulation an evolution in time is
computed.
Result Window Window for the representation of the simulation results
in graphical form, as x(t) or x(y) diagrams. There is the
possibility of representing several result processes in
one window.
Simulation In the simulation the evolution of the model behavior in
time is determined. This depends on the model structure
as well as the used parameters and initial values. As
result the user receives the evolution in time of all result
variables and can evaluate it.
Solver Package of numeric solution methods, with which the
state variables of a Model are computed for each time
instant during the simulation run.
Start values Usually, not all initial values in a model are set by the
user. Thus the solver must try to find iteratively
SimulationX 3 12-7
consistent initial values before solving the differential

equation system. Start values of variables can be
entered via the Attributes dialog of a variable. There
they can also be fixated. Furthermore, start values can
be linked to initial parameters. Usually the are
commented with Initial (Initial Displacement,
Initial Velocity, etc.) Those parameters have a fixation
pin.
Start values are not equal to initial values. In contrast to
start values, initial values can be modified while initial
value calculation. Only, if the start value is fixed, they
will be also used as initial value.
If the convergence is poor or if several solutions exist,
the iteration process can be influenced by a suitable
start value selection.
Statechart Designer The tool can be used to comfortably model and simulate
complex time-discrete and state-discrete control
systems inside SimulationX. Based on a large subset of
UML it supports reliable modeling of physical effects or
technical sub-systems with discrete states (e.g. friction,
hysteresis, valves, and switches).
State Variable A variable, which describes an essential property of the
model. The calculation of state variables usually cannot
be formulated in explicit form by the modeler. The
values of state variables normally are calculated
iteratively by an equation solver.
Steady State simulation Calculation of periodic steady states of nonlinear and
in the frequency linear systems depending on an increasing or decreasing
domain reference quantity (in contrast to the transient
simulation without considering the rate of change of the
reference quantity, i.e., for infinitely slow variation).
This allows, for example, computing and visualizing the
steady states for different rotary speeds (i.e., a speed
range) for a driveline.
Tracing Information, which can be displayed during the
simulation, in order to facilitate a searching for errors.
With the help of the tree-structured view of the different
trace options the logging of individual kinds of events
in the output-area can be switched on or off.
Transient simulation in Solution of the differential equations by integration in
the time domain time domain for linear and nonlinear models. It will
calculate transient solutions; taking into account the
12-8 SimulationX 3
variations over time (e.g. speed of resonance crossings
or time-dependent change of quantities). In contrast to
the steady-state simulation the system is not in steady
state.
Type Description of a class of elements or connections,
having the same connectors, parameters, algorithms,
equations, internal components etc.
TypeDesigner Integrated tool in SimulationX for the development of
new element types.
Using the TypeDesigner, the user (type developer)
specifies a symbol, connectors, components, Activity
Groups, behavior (algorithm and equations), and
documentation of the new element type.
Wizard A program module, which leads the user step by step
through a task (e. g. optimization wizard or variant
wizard).
Zero-functions Zero-functions are used for the detection of
statedependent events. They cross zero at the time
instant of the event they are associated with. Zero-
functions are generated automatically by the symbolic
analysis. For example: The expression if x>10 then 0
else 5 generates the zero-function x-10.
SimulationX 3 12-9
12-10 SimulationX 3
Bibliography
13 Bibliography
[1] K.E. Brenan, S.L. Campbell, L.R. Petzold:

Numerical Solution of Initial-Value Problems in Differential-Algebraic
Equations.
Society for Industrial and Applied Mathematics
Philadelphia 1996
[2] E. Hairer, S.P. Norsett, G. Wanner:

Solving Ordinary Differential Equations II - 2nd rev. Edition.
Springer Verlag
Berlin Heidelberg 1993
[3] C. Geiger, C. Kanzow:

Numerische Verfahren zur Lsung unrestringierter Optimierungsaufgaben
(german book)
Springer Verlag
Berlin Heidelberg 1999
[4] Modelica Association

Modelica A Unified Object-Oriented Language for Physical System
Modeling, Language Specification, Version 3.2 Revision 2
Modelica Association 2013, Link, http://www.Modelica.org
[5] A. C. Hindmarsh, P. N. Brown, K. E. Grant, S. L. Lee, R. Serban, D. E.

Shumaker, and C. S. Woodward, "SUNDIALS: Suite of Nonlinear and
Differential/Algebraic Equation Solvers," ACM Transactions on
Mathematical Software, 31(3), pp. 363-396, 2005.
(www.llnl.gov/casc/sundials/)
[6] Object Management Group

OMG Unified Modeling Language (UML) Specification, version 2.1.2
http://www.omg.org/docs/formal/07-11-02.pdf
November 2007
[7] Mechanical Simulation Corporation

The VehicleSim API, Running and Extending VSSolver Programs.
August 2010
SimulationX 3 13-1
User Manual
13-2 SimulationX 3
Index
14 Index
curve ............................................. 5-50
3 curve family ................................. 5-53
3D view .............................................5-60 curve set ....................................... 5-53
camera ...........................................5-61 data export .................................... 5-42
connect ..........................................5-73 data import ................................... 5-42
connector ......................................5-60 data input ...................................... 5-42
construction ..................................5-71 dialog............................................ 5-41
coordinate system .........................5-60 interpolation ................................. 5-43
disconnecting ................................5-73 properties...................................... 5-49
global settings ...............................5-62 toolbar .......................................... 5-42
local settings .................................5-67 Characteristic maps
origin .............................................5-60 2D-map ........................................ 5-53
positioning ....................................5-72 3D-map ........................................ 5-59
Realistic ........................................5-64 data export .................................... 5-55
select an element ...........................5-70 data input ...................................... 5-55
settings ..........................................5-62 dialog............................................ 5-53
Standard view ...............................5-64 properties...................................... 5-57
Technical view ..............................5-64 toolbar .......................................... 5-54
visualization ..................................5-67 Class
Wireframe .....................................5-64 application ...................................... 9-9
connections .................................. 9-11
A curves ........................................... 9-11
document ........................................ 9-9
Activity groups..................................8-23 parameters .................................... 9-11
Algotithm ..........................................8-27 results ........................................... 9-12
Analysis
selection ....................................... 9-13
equilibrium......................................6-1 SimObjects ................................... 9-10
linear ....................................... 3-7, 6-1
Code Export ..................................... 9-42
stady state .......................................6-1 C-code without solver .................. 9-53
transient ..........................................6-1
ETAS LABCAR .......................... 9-76
Animation ................................. 6-1, 6-42
Executable Model ........................ 9-53
play back .......................................6-45 MATLAB/Simulink S-Function .. 9-59
record ............................................6-45
NI LabView ................................. 9-64
save ...............................................6-45 Post Processing ............................ 9-52
Approximation
project ..... 9-45, 9-66, 9-69, 9-73, 9-76
by circular arcs..............................5-46 requirements................................... 2-1
by hyperbolas ................................5-45
source code.......................... 9-21, 9-42
quadratical ....................................5-47
VehicleSim................................... 9-72
tolerance ........................................5-52 wizard ........................................... 9-45
Code Import
C
FMU code import......................... 9-79
Characteristic curves .........................5-41 COM interface ........................... 7-60, 9-7
approximation ...............................5-43 Compare Models .............................. 5-81
continuation of the curve ..............5-48 Components...................................... 8-15
SimulationX 3 14-1
User manual 14. Index
Compound ........................................ 8-32 copy elements ............................... 5-15

inner components ......................... 8-34 label .............................................. 5-15
inner connectors ........................... 8-33 move elements .............................. 5-14
Computation ....................................... 1-1 select an element .......................... 5-13
consistent inital values ................. 6-17 select several elements ................. 5-13
differential algebraic equations .... 6-18 Element type
in the time domain.......................... 6-1 delete .............................................. 4-7
ordinary differential equations ..... 6-17 extending ...................................... 8-31
solver ............................................ 6-30 inheritance .................................... 8-31
time steps...................................... 6-30 new ................................................. 4-7
Connection.......................................... 5-9 new derivative ................................ 4-8
connector ...................................... 8-14 new version .................................... 4-8
Controls ............................................ 5-77 open ................................................ 4-8
Co-Simulation .................................. 9-27 reload .............................................. 4-8
control package ............................ 9-28 safety ............................................ 8-30
coupling element .......................... 9-29 storing as file .................................. 4-7
Simulink ....................................... 9-30 unload ............................................. 4-9
VehicleSim ................................... 9-32 user-defined .............................4-5, 5-9
version management(SVN) .......... 4-10
D Equation ............................................ 8-27
Data formats ....................................... 9-1 Equilibrum ........................................ 6-69
DIAdem-Header ............................. 9-7 Event ................................................. 6-30
IEEE-binr ..................................... 9-4
load file .......................................... 9-5 F
save file .......................................... 9-4 Fast Fourier Transformation ............. 7-52
text .................................................. 9-1 FluidDesigner
Database hydraulics ..................................... 8-49
data selection .............................. 9-130 mixtures ........................................ 8-56
link ............................................. 9-121 pneumatics .................................... 8-55
table ............................................ 9-128 Forms ................................................ 5-79
Database link Frequency
database selection ....................... 9-125 response function.......................... 7-53
Drag and Drop ... 4-9, 5-10, 5-14, 6-82, 6-
89, 8-14 G
Global parameters ............................. 5-25
E Global symbolic analysis .........6-15, 8-26
Edition GUI ..............................................4-1, 5-3
ANALYZER ........................ 2-4, 2-16 3D view ........................................ 4-12
change to... ..................................... 2-5 diagram view ................................ 4-12
EVALUATION version ............... 2-11 documentation view ..................... 4-12
PROFESSIONAL ................ 2-4, 2-16 library bar ....................................... 4-3
STUDENT ................. 2-4, 2-14, 2-16 menu bar ......................................... 4-2
VIEWER .................... 2-4, 2-14, 2-16 output area .................................... 4-17
Element .................................. 8-25, 10-15 result window manager ................ 4-17
connecting elements ....................... 3-5 structure view ................................. 5-3
text view ....................................... 4-12
14-2 SimulationX 3
Index
toolbar .............................................4-2 connection ...................................... 5-9

diagram view....................... 4-12, 8-25
H element ........................................... 5-9
Homotopy .........................................6-20 entering parameters ........................ 3-6
artificial parameter ........................6-25 model explorer ............................. 4-14
natural parameter ..........................6-22 model structure ............................ 5-10
properties dialog .......................... 8-25
I select a connection ....................... 5-14
select an element .......................... 5-13
Installation...........................................2-5
select several elements ................. 5-13
Basics ............................................. 2-1 special model components ........... 5-76
Batch processing .......................... 2-15 Model Explorer ....................... 4-14, 7-10
network license .............................2-21 Modelica ................................. 1-3, 8-30
update a license .............................2-25 libraries .......................................... 5-7
Interpolation source code................................... 8-27
linear interpolation ........................5-44 standard library ............................ 10-2
spline interpolation .......................5-44 Modeling ............................................ 1-1
stair function .................................5-43 network modeling .......................... 5-1
ITIScript ............................................9-18 physical object oriented ................. 5-1
signal based .................................... 5-2
J with equation and algorithm .......... 5-3
JScript ...............................................9-18 Modeling error ...................... 11-5, 11-25
Momentary display.................... 5-76, 7-1
K
Klasse N
ResultWindows .............................9-17 Natural frequencies ............................ 3-7
L O
Library Optimization ....................................... 1-1
library bar .......................................4-3 Isight ............................................ 9-88
License optiSLang ..................................... 9-90
license file .....................................2-26 OtiY.............................................. 9-88
managed ........................................2-28 Order Analysis ................................. 6-95
network ............................... 2-29, 2-30
Linear system analysis ......................6-70 P
input-output analysis.....................6-81 Parameter .......................................... 5-21
natural frequencies and mode shapes add ................................................ 4-16
..................................................6-72 description by characteristics ....... 5-33
Local type description by formulas ............... 5-32
enumeration ..................................8-20 Export ........................................... 5-30
function .........................................8-20 Import ........................................... 5-31
Simblocks ........................... 8-18, 8-21 logical terms ................................. 5-22
mathematical expression .............. 5-22
M multidimensional ......................... 5-26
Model nonlinear property ........................ 5-32
SimulationX 3 14-3
physical units................................ 5-24 S

remove .......................................... 4-16
Simulation ........................................... 1-1
variable element parameter .......... 5-35
control............................................. 3-8
variables ....................................... 5-23
equilibrum .................................... 6-69
Power balance................................. 6-111
performance analyzer ................... 6-41
Print engine....................................... 7-54
reset points...................................... 6-7
Program protection ...........................2-16 settings ............................................ 6-3
dongle ........................................... 2-16 steady state ..........................3-10, 6-46
license file .................................... 2-19 steady-state ..................................... 1-3
USB Key ...................................... 2-17 step size ...................................... 11-13
Property window .............................. 5-16 transient .......................................... 6-1
SimulationX .............................1-1, 9-122
R
changing parameters ....................... 3-2
Resolve External References ............ 5-80 creating a model ............................. 3-4
Result curve editions ........................................... 2-3
calculated points ........................... 7-18 Evaluation version .......................... 2-3
freezing......................................... 7-36 Installation ...................................... 2-5
Result variable .................................. 5-25 interfaces ........................................ 9-7
add ................................................ 4-16 libraries ........................................... 5-6
move ............................................. 7-18 open a model .................................. 3-2
remove .......................................... 4-16 reinstallation ................................. 2-10
Result window .................................... 7-8 release ............................................. 2-9
auxiliary lines ............................... 7-23 run a simulation .............................. 3-3
axes properties.............................. 7-45 sample models ................................ 3-1
bar chart........................................ 7-15 update ........................................... 2-10
curve properties ............................ 7-45 Solver .................. 6-13, 6-30, 11-8, 11-13
line graph...................................... 7-14 BDF method ................................. 6-32
manager ............................... 7-12, 7-51 CVODE ........................................ 6-38
open ................................................ 3-3 Gauss method ............................... 6-35
page properties ............................. 7-39 Jacobian matrices ......................... 6-35
panel ............................................. 7-19 MEBDF method ........................... 6-32
panel properties ............................ 7-42 settings .......................................... 6-34
pie chart ........................................ 7-16 Special controls................................. 5-21
polar coordinates .......................... 7-15 characteristic curves ..................... 5-40
post processing ............................. 7-27 characteristic maps ....................... 5-40
properties ...................................... 7-11 for initial values ............................ 5-24
property bar .................................. 7-37 for parameters ............................... 5-22
result bar ....................................... 7-11 for result variables ........................ 5-25
Sankey diagram ............................ 7-16 Statechart
transformation .............................. 7-27 composite states............................ 8-64
window properties ........................ 7-37 pseudostate ................................... 8-59
y(t)-chart....................................... 7-17 self-transition ................................ 8-63
y(x)-chart ...................................... 7-17 state............................................... 8-57
zoom ............................................. 7-22 transition ....................................... 8-58
trigger ........................................... 8-60
worksheet ..................................... 8-68
14-4 SimulationX 3
Index
Statechart Designer ...........................8-56 components .................................. 8-15

model explorer ..............................8-73 compound ..................................... 8-32
modelica code ...............................8-76 connector ...................................... 8-14
modeling .......................................8-68 documentation .............................. 8-29
Swinging forms ...................................3-7 element type extending ................ 8-31
external functions ......................... 8-37
T
Tools U
FEM Import ..................................9-90 User-defined types ............................. 8-1
Isight .............................................9-88 global types .................................... 8-1
optiSLang......................................9-90 import of External Types ............... 8-7
OtiY ..............................................9-88 local types ...................................... 8-1
Tracing ........................... 6-3, 6-11, 11-14
TypeDesigner .. 4-16, 8-11, 8-24, 8-30, 8- V
31, 10-1 Variants wizard ....................... 6-87, 6-88
activity groups ..............................8-23 VBScript ........................................... 9-18
base type .......................................8-31
behavior ........................................8-26
SimulationX 3 14-5
14-6 SimulationX 3

User Manual

Hochgeladen von

Dokumentinformationen

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

User Manual

Hochgeladen von

Copyright:

Verfügbare Formate

User Manual

Fr die Nutzung von ESI-ITI-Software gelten ausschlielich die Vertragsbedingungen der

ESI ITI GmbH

About the Manuals

Part I: User Manual

Part II: Library Manual

Option, not included in the Basic Module of

Serif Variable, mathematical expression

2.6 SimulationX the Licensing 2-20

3 Getting Started 3-1

3.2.3 Entering Parameters 3-6

4 Graphical User Interface (GUI) 4-1

5 Modeling Fundamentals 5-1

5.2.3 Model Creation and Modification 5-9

5.4.4.3 Settings 5-62

6.3.1.2 Period Vector, Period Variable and Period Computation 6-49

6.6.1 Range of Application 6-87

7 Result Analysis, Documentation and Settings 7-1

7.2.1 To Open the Visualizer 7-2

7.3.9 Settings 7-37

8 Customizing and Extension 8-1

8.3.1.5 Heat Expansion 8-54

8.4.4.8 Transition Activities 8-87

9.4.2 Co-Simulation with Simulink 9-30

9.6.2.2 Code Import using RTW Import Element 9-86

9.8.4.6 COM-Interface 9-117

10 Modelica in SimulationX 10-1

10.4.4 Name Spaces and Identifiers 10-10

10.5.9.3 Global parameters and variables in the model 10-41

11 FAQ Frequently asked questions 11-1

1.1 Fields of Application

SimulationX is a program package for the modeling, computation, simulation,

1.2 Solution Concept

SimulationX unites modeling concepts on different levels. On the one hand,

From Version 3 an implementation of CVODE is available in addition. You can

1.3 Scope of Computation

Despite of the sophisticated modeling tools, model development is still a

Frequently, an equilibrium of the system must be determined which will be the

At every point of operation SimulationX can perform a structure analysis of the

1.5 Software Development

For the installation of SimulationX you need the rights of access of an

2.1.1 Hard and Software Conditions for SimulationX

Component Minimum requirements Recommended Configuration

2.1.2 Requirements of Code Export and external Solver

Development Environment SimulationX 32bit SimulationX 64bit

Please note the license conditions of Microsoft.

2.2.2 Evaluation version

OPTIONS which can be tested with COMPLETE FUNCTIONALITY for a limited

2.2.3 The Student Edition

Figure 2.1: Available model elements in the Student Edition (extract).

2.2.4 The Viewer Edition

2.2.5 The Analyzer Edition

2.2.6 The Professional Edition

2.2.7 Change edition

Figure 2.2: Switch the Edition in SimulationX

2.3 Installing SimulationX

Figure 2.3: Start screen

Figure 2.4: Welcome screen

Figure 2.5: Start of install wizard

One of these prerequisites is the installation of DirectX to enable the best

Uninstalling an older version of SimulationX is not necessary. Different versions

Figure 2.6: License agreement

Customized The user can choose the features he wants to be installed.

Figure 2.7: Possible setup types