Simcenter Submodel

Editor 17
Restricted © Siemens 2019 Where today meets tomorrow.
Simcenter Submodel Editor

Getting started
Submodel definitions
Enumeration example
Mass-spring examples
Modeler - sorting components
Discontinuity handling examples
Dynamic block example
User library

Restricted © Siemens 2019

Page 2 2019-06-29 Siemens Digital Industries Software
Getting started: what is the Submodel Editor?

 Specific tool to create user submodels

 Extends Amesim modelling capabilities to user
specific needs
 Category management
 category icons
 component icons
 Submodel management
 Create or edit a submodel
 Edit submodel code (C or Fortran)
 Compile submodel with various
compilers
 Generate HTML documentation

Restricted © Siemens 2019

Page 3 2019-06-29 Siemens Digital Industries Software
Getting started: Submodel Editor GUI

 Starting from an existing icon

 Create new submodel

 Open existing submodel

Restricted © Siemens 2019

Page 4 2019-06-29 Siemens Digital Industries Software
Getting started: Submodel Editor GUI

Icon

Parameter and Category

variable details tree
Ports, variables
and parameters

Options

Restricted © Siemens 2019

Page 5 2019-06-29 Siemens Digital Industries Software
Simcenter Submodel Editor

Getting started
Step 1: create a category
Step 2: create an icon
Step 3: create a submodel
Submodel definitions
Enumeration example
Mass-spring examples
Modeler - sorting components
Discontinuity handling examples
Dynamic block example
User library

Restricted © Siemens 2019

Page 6 2019-06-29 Siemens Digital Industries Software
Getting started: creating a category

 Modelling -> Category Settings menu

 Add category

 Select a target directory for storing the future

category files

 Submodel Editor offers to add it in the path list

 Automatically synchronized with Amesim if it is
already opened

Restricted © Siemens 2019

Page 7 2019-06-29 Siemens Digital Industries Software
Getting started: creating a category

 Step 1: set the name of the category. Corresponds to

the name of the files storing category data
 Single word
 invisible to end users

 Step 2: Category title = label displayed to end user

Restricted © Siemens 2019

Page 8 2019-06-29 Siemens Digital Industries Software
Getting started: creating a category

 Icon designer

 Draw icon
 Load existing
bitmap

 Save

Restricted © Siemens 2019

Page 9 2019-06-29 Siemens Digital Industries Software
Getting started: creating a category

 New category appears at the end of the library tree

 Several files have been created in the category directory

Restricted © Siemens 2019

Page 10 2019-06-29 Siemens Digital Industries Software
Getting started: set category specific color

 Default category color is black

 Right click on category in library tree

 Menu “Color Preferences”

Restricted © Siemens 2019

Page 11 2019-06-29 Siemens Digital Industries Software
Simcenter Submodel Editor

Getting started
Step 1: create a category
Step 2: create an icon
Step 3: create a submodel
Submodel definitions
Enumeration example
Mass-spring examples
Modeler - sorting components
Discontinuity handling examples
Dynamic block example
User library

Restricted © Siemens 2019

Page 12 2019-06-29 Siemens Digital Industries Software
Getting started: creating an icon

 Right click on category in library tree

 Menu “Add component”

Restricted © Siemens 2019

Page 13 2019-06-29 Siemens Digital Industries Software
Getting started: creating an icon

 Set icon size

 Draw icon
 Select port type

Restricted © Siemens 2019

Page 14 2019-06-29 Siemens Digital Industries Software
Getting started: creating an icon

 Drag and drop the ports on the

icon

Restricted © Siemens 2019

Page 15 2019-06-29 Siemens Digital Industries Software
Getting started: creating an icon

 Save the icon

 Set a name
 Set a description

 New icon appears in

the category

Restricted © Siemens 2019

Page 16 2019-06-29 Siemens Digital Industries Software
Simcenter Submodel Editor

Getting started
Step 1: create a category
Step 2: create an icon
Step 3: create a submodel
Submodel definitions
Enumeration example
Mass-spring examples
Modeler - sorting components
Discontinuity handling examples
Dynamic block example
User library

Restricted © Siemens 2019

Page 17 2019-06-29 Siemens Digital Industries Software
Getting started: creating a submodel

 Select the icon in category

 Select “NEW SUBMODEL”

Restricted © Siemens 2019

Page 18 2019-06-29 Siemens Digital Industries Software
Getting started: creating a submodel

 The number of ports in submodel is already

set, and depends on icon

 Port types (signal and lshaft) have been set

during icon creation

 Other fields are empty

Restricted © Siemens 2019

Page 19 2019-06-29 Siemens Digital Industries Software
Getting started: power sensor basic features

External variables Parameters Physical equation

Power = gain * (force * velocity - offset )

Restricted © Siemens 2019

Page 20 2019-06-29 Siemens Digital Industries Software
Getting started: power sensor

 Parameter and variable characteristics must

be set

 Submodel traffic light becomes green when

setup is complete

Contextual WARNING: impossible to save

messages as long as traffic light is red

Restricted © Siemens 2019

Page 21 2019-06-29 Siemens Digital Industries Software
Getting started: power sensor variables at port 1

Restricted © Siemens 2019

Page 22 2019-06-29 Siemens Digital Industries Software
Getting started: power sensor variables at port 2

Restricted © Siemens 2019

Page 23 2019-06-29 Siemens Digital Industries Software
Getting started: power sensor variables at port 3

Restricted © Siemens 2019

Page 24 2019-06-29 Siemens Digital Industries Software
Getting started: power sensor real parameters

Restricted © Siemens 2019

Page 25 2019-06-29 Siemens Digital Industries Software
Getting started: power sensor global checking

 Submodel traffic light is green:

setup is complete

 Submodel is ready to be saved

Restricted © Siemens 2019

Page 26 2019-06-29 Siemens Digital Industries Software
Getting started: saving submodel

 Submodel name
 Uppercase letters only
 Starts with a letter
 Underscore allowed

 Save in directory storing the

category

Do not select the submodels

directory

Restricted © Siemens 2019

Page 27 2019-06-29 Siemens Digital Industries Software
Getting started: generating submodel code

 Submodel Editor generates a code skeleton, i.e. a piece of code containing pre-defined functions called by
Amesim during simulation

Select langage for source code

(C or Fortran)

Edit source code

(Re)generate code skeleton

Restricted © Siemens 2019

Page 28 2019-06-29 Siemens Digital Industries Software
Getting started: submodel code functions

 Initialization function
 Called once at the start of simulation.
 Contains initialization statements (parameter checks, data file reading…)
 Access to state variable initial values

 Calculation function
 Called at each time step by the solver
 Contains calculation statements

 End of simulation function (optional)

 Called once at end of simulation
 Can close optional files or free some memory

 Multi line macro calculation function (optional)

 One function per multi line macro
 Calculation statements only

Restricted © Siemens 2019

Page 29 2019-06-29 Siemens Digital Industries Software
Getting started: edit submodel code

 Default source code editor is embedded in Submodel

Editor

 This can be parametrized

Restricted © Siemens 2019

Page 30 2019-06-29 Siemens Digital Industries Software
Getting started: setting source code editor

 Select Tools -> Options -> Preferences

 Default source code editor is Submodel

Editor

 Other text editors can be used

Restricted © Siemens 2019

Page 31 2019-06-29 Siemens Digital Industries Software
Getting started: initialization function

Areas reserved to user

Warning and error message

code automatically generated

Restricted © Siemens 2019

Page 32 2019-06-29 Siemens Digital Industries Software
Getting started: calculation function

Areas reserved to user

Any code written out of these

reserved areas will be lost

Restricted © Siemens 2019

Page 33 2019-06-29 Siemens Digital Industries Software
Getting started: calculation statements

Variables are referred as C

pointers: using *v to refer to
the value is mandatory

Calculation equations

Restricted © Siemens 2019

Page 34 2019-06-29 Siemens Digital Industries Software
Getting started: selecting compiler

 Select Tools  Options -> Preferences

 Several compilers can be used, as long

as these are installed on the machine

 Gcc can compile both C and Fortran

code

Restricted © Siemens 2019

Page 35 2019-06-29 Siemens Digital Industries Software
Getting started: compilation

Compilation with gcc of

C submodel code

Restricted © Siemens 2019

Page 36 2019-06-29 Siemens Digital Industries Software
Getting started: testing power sensor in Amesim

Restricted © Siemens 2019

Page 37 2019-06-29 Siemens Digital Industries Software
Getting started: testing power sensor in Amesim

Successful
compilation
with gcc

Restricted © Siemens 2019

Page 38 2019-06-29 Siemens Digital Industries Software
Getting started: testing power sensor in Amesim

 Non default parameters:

 Signal source UD00-1

 Damper rating of
SD0000 = 100 N/(m/s)
 Mass of MAS001 = 50
kg

Restricted © Siemens 2019

Page 39 2019-06-29 Siemens Digital Industries Software
Getting started: Amesim – Submodel Editor synchronization

 When Amesim and Submodel Editor are

opened simultaneously, each time the
submodel is modified, the Amesim model(s)
must be synchronized.

 In Submodel Editor: save and recompile

submodel

 In Amesim:

 If category icons are modified: select

Modelling  Update categories
 Perform a Check submodels (Ctrl + K)
 If no change is detected by Update
Assistant, force a model recompilation
(Ctrl + T)

Restricted © Siemens 2019

Page 40 2019-06-29 Siemens Digital Industries Software
Getting started: Amesim – Submodel Editor synchronization

Restricted © Siemens 2019

Page 41 2019-06-29 Siemens Digital Industries Software
Getting started: testing power sensor in Amesim

 Adding a second sensor to the model

 Requires to remove
the submodel
currently associated
to the spring
damper

 Right click on
component +
remove submodel
menu item

Restricted © Siemens 2019

Page 42 2019-06-29 Siemens Digital Industries Software
Getting started: testing power sensor in Amesim

 Model contains an implicit

loop

 Comes from the

connection between the
spring damper and the
sensor

More explanations on
implicit loops on
modeler chapter

Restricted © Siemens 2019

Page 43 2019-06-29 Siemens Digital Industries Software
Getting started: power sensor external variables

 v1 is changed from
“basic” variable to
“duplicate”

 It is set as duplicate of v3

Restricted © Siemens 2019

Page 44 2019-06-29 Siemens Digital Industries Software
Getting started: power sensor external variables

 F3 is changed from
“basic” variable to
“duplicate”

 It is set as duplicate of F1

 Save as
POWER_SENSOR2

Restricted © Siemens 2019

Page 45 2019-06-29 Siemens Digital Industries Software
Getting started: external variables

 V1 and F3 are not

accessible in the code

Restricted © Siemens 2019

Page 46 2019-06-29 Siemens Digital Industries Software
Getting started: power sensor external variables

 Replace
POWER_SENSOR1 by
POWER_SENSOR2

 Go to simulation mode

Restricted © Siemens 2019

Page 47 2019-06-29 Siemens Digital Industries Software
Getting started: power sensor external variables

 Implicit loop has

disappeared

Restricted © Siemens 2019

Page 48 2019-06-29 Siemens Digital Industries Software
Getting started: power sensor external variables

 Why did we have an implicit loop?

 Comes from connection between spring damper and power sensor

 F1 and X1 are basic variables
 F1 depends on X1 (spring)
 X1 depends on F1 (F1 is input to sensor)

 The modeller can not determine a calling sequence between spring and sensor

X1 X2 (dX2/dt = …)

F1(X1) F2

Restricted © Siemens 2019

Page 49 2019-06-29 Siemens Digital Industries Software
Getting started: power sensor external variables

 Why did we have an implicit loop?

 X1 declared as duplicate of X2 => X1 by-passes the call to the sensor

 X2 is explicit state => value is already known

 The modeller can call the spring first

X1=X2 X2 (dX2/dt = …)

F1(X2) F2

Restricted © Siemens 2019

Page 50 2019-06-29 Siemens Digital Industries Software
Getting started: generate documentation

 Menu Documentation -> Create HTML skeleton

 HTML canvas to be filled by user

 Stored in ‘doc’ folder of the category
 ‘png’ folder stores icon and external variable
pictures

Restricted © Siemens 2019

Page 51 2019-06-29 Siemens Digital Industries Software
Getting started: generate documentation

 HTML editor must be set in preferences

 Once documentation HTML exists, Edit item is

available

Restricted © Siemens 2019

Page 52 2019-06-29 Siemens Digital Industries Software
Getting started: view documentation

 Paragraphs are empty and must be

filled by user

 Arrays storing parameter and variable

characteristics are generated
automatically

Restricted © Siemens 2019

Page 53 2019-06-29 Siemens Digital Industries Software
Getting started: edit documentation

 Insert text in standard HTML form

 Note that Amesim documentation

uses specific javascript for
rendering

Restricted © Siemens 2019

Page 54 2019-06-29 Siemens Digital Industries Software
Simcenter Submodel Editor

Getting started
Submodel definitions
Enumeration example
Mass-spring examples
Modeler - sorting components
Discontinuity handling examples
Dynamic block example
User library

Restricted © Siemens 2019

Page 55 2019-06-29 Siemens Digital Industries Software
Port connection

 Establish contact with neighbour Green squares materialize the

ports when close enough
submodels
 Port appearance corresponds to specific
port type
 Port numbering imposed by LMS Amesim
in counter-clockwise order, starting from
bottom face
 Information passed in both directions
(multiport approach)
 Information quantities = external variables

Port 1 has 2
variables
Restricted © Siemens 2019
Page 56 2019-06-29 Siemens Digital Industries Software
External variables

 2 sort of external variables  Connection rules

 Output (green)
 Input (red)  Units must be identical
 Order of outputs vs inputs must be
 Outputs always ordered first in the list identical
 All inputs must have a corresponding
output
 Outputs can remain unconnected

Restricted © Siemens 2019

Page 57 2019-06-29 Siemens Digital Industries Software
Parameters and variables

 Parameter  Variable

 Quantity set once and constant  Quantity changing during simulation

during simulation  Always floating number
 3 possible types  External variable: quantity exchanged
 Real (floating number) with another submodel through port
 Integer  Internal variable: quantity private to
 Text the submodel

 Examples
 Diameter, mass
 Number of cells
 File name

Restricted © Siemens 2019

Page 58 2019-06-29 Siemens Digital Industries Software
Parameters and variables

Variables

Parameters (rp array )

Restricted © Siemens 2019

Page 59 2019-06-29 Siemens Digital Industries Software
Real, integer and pointer stores

 Real, integer and pointer stores are

 Working arrays private to each instance of a submodel

 Accessible in read and write mode
 Values remain in memory between consecutive calls
 Dimension is defined in Ameset (fixed on function of structural parameters)
 “C” array for real stores, “ic” for integer stores, “ps” for pointer stores

 Common uses

 Store id of objects created by LMS Amesim functions during initialization

(expression, spline…)
 Store complex quantities computed once during the whole simulation
 Store a region index, mandatory for handling a discontinuity

Restricted © Siemens 2019

Page 60 2019-06-29 Siemens Digital Industries Software
Real, integer and pointer stores

 Value stored in ic[0] will

remain in memory between
consecutive calls

Restricted © Siemens 2019

Page 61 2019-06-29 Siemens Digital Industries Software
Real, integer and pointer stores

 Value stored in ic[0] is an input

to calculation function

 It is sent directly to expeval

utility function

Restricted © Siemens 2019

Page 62 2019-06-29 Siemens Digital Industries Software
Types of variables

 Basic
 Explicit state
 Implicit state
 Discrete
 Constraint
 Fixed
 Duplicate
 One line macro
 Multi line macro
 Activity
 Activity state For internal
 Power variables only
 Energy
 Energy state

Restricted © Siemens 2019

Page 63 2019-06-29 Siemens Digital Industries Software
Types of output variables: basic

 Simplest type

 Its value is evaluated in

the calculation function

 More likely to create

connection implicit loops

 Example of sensor or
spring SPR50

Restricted © Siemens 2019

Page 64 2019-06-29 Siemens Digital Industries Software
Types of output variables: explicit state

 Defines an Ordinary Differential Equation (ODE)

𝑑𝑥
= 𝑓 (𝑥 ,𝑡 ,𝑢)
𝑑𝑡
 In submodel code, it is represented by is a couple of C variables (x, dx)

 dx is the derivative of x with respect to time: it is computed by submodel

Go to application
 x is integrated by solver: it can not be modified by submodel (except during example : 1D mass
simulation start)
Go to application
 x initial value is defined by user as a parameter example : 1D spring

Restricted © Siemens 2019

Page 65 2019-06-29 Siemens Digital Industries Software
Types of output variables: explicit state

 Integrator example

𝑑𝑥
=𝑘 . 𝑖𝑛𝑝𝑢𝑡
𝑑𝑡

Restricted © Siemens 2019

Page 66 2019-06-29 Siemens Digital Industries Software
Types of output variables: explicit state

 x and dx are passed through

submodel as argument

 x is sent to initialization
function => its starting value
can be modified by
submodel

 Submodel computes dx

Restricted © Siemens 2019

Page 67 2019-06-29 Siemens Digital Industries Software
Types of output variables: implicit state

 Defines a Differential Algebraic Equation (DAE)

𝑑𝑥
𝑓 (𝑥 , ,𝑡 ,𝑢)=0
𝑑𝑡
 In submodel code, it is represented by is a couple of C variables (x, dx)

 dx is the derivative on input to submodel

 dx will be overwritten with the residual of equation

 x is evaluated by solver: it can not be modified by submodel (except during

simulation start)
Go to application
 x initial value is defined by user as a parameter example : 1D mass

Restricted © Siemens 2019

Page 68 2019-06-29 Siemens Digital Industries Software
Types of output variables: implicit state

 Differentiator example

 Constraint equation
forces x to follow input

𝑑𝑥
𝑜𝑢𝑡𝑝𝑢𝑡=
𝑑𝑡
𝑟𝑒𝑠 ( 𝑥 )=𝑥 − 𝑖𝑛𝑝𝑢𝑡

Restricted © Siemens 2019

Page 69 2019-06-29 Siemens Digital Industries Software
Types of output variables: implicit state

 At first call, x is initialized

with the value of input

 Dx contains the derivative of

x, estimated by the solver

 dx is overwritten by the
residual of the DAE

Restricted © Siemens 2019

Page 70 2019-06-29 Siemens Digital Industries Software
Types of output variables: constraint

 Defines a constraint equation

𝑓 ( 𝑥 ,𝑡 ,𝑢)= 0
 In submodel code, it is represented by is a couple of C variables (x, rx)

 rx will be set with the residual of equation

 x is evaluated by solver: it can not be modified by submodel (except during

simulation start)

 x initial value is defined by user as a parameter

Restricted © Siemens 2019

Page 71 2019-06-29 Siemens Digital Industries Software
Types of output variables: duplicate

 “duplicates” the same variable on a port F2 = dup( F1) F1

 Helps the modeler to sort submodels

 Does not appear in submodel code

 Very useful when

 the same quantity is passed through
several ports
 An input is passed without modification to V1=dup(V3)
another port V3 X1=dup(X3)
X3
 2 types of duplicate
 Simple: u = v
 Sign reversed: u = -v

Restricted © Siemens 2019

Page 72 2019-06-29 Siemens Digital Industries Software
Types of output variables: duplicate

 Illustration in code
generated by Amesim
model
 V[0] is the output from the
sine wave

 V[2] and v[4] are duplicates of

v[0]

 V[2] and v[4] are sent to

integrators

Restricted © Siemens 2019

Page 73 2019-06-29 Siemens Digital Industries Software
Types of output variables: one line macro

 Extension of duplicates to more complex

equations V3 V2 = V3*V1

 Equation can depend on submodel input

variables, states, real parameters, real stores,
time

 Equation must fit in one line

V1
 Limited to scalars (vectors not allowed)

 Variable not sent to calculation function

Restricted © Siemens 2019

Page 74 2019-06-29 Siemens Digital Industries Software
Types of output variables: one line macro

 Illustration with summing

junction

Restricted © Siemens 2019

Page 75 2019-06-29 Siemens Digital Industries Software
Types of output variables: multi line macro

 Extension of one line macro to several

lines of code V1 one line macro
X1 multi line macro
 Equation can depend on submodel input
variables, states, parameters, stores,
time

 Possibility to call external functions (fluid

properties…)

 Specific C function created for each multi

line macro

Restricted © Siemens 2019

Page 76 2019-06-29 Siemens Digital Industries Software
Types of output variables: multi line macro

 Q: Why does CAM00 need multi line macro ?

 A: to break connection implicit loop at port 1

X1
V1
F1

 Spring damper force F1 depends on X1 and V1

 Need to indicate to modeler that V1 and X1

computed by CAM00 do not depend on F1

Restricted © Siemens 2019

Page 77 2019-06-29 Siemens Digital Industries Software
Types of output variables: multi line macro

 X1 declared as multi line

macro

 Depends on acam
variable (cam angle)

Restricted © Siemens 2019

Page 78 2019-06-29 Siemens Digital Industries Software
Types of output variables: multi line macro

 X1 declared as multi line

macro

 Depends on acam variable

(cam angle) passed through
argument list

 All parameters and stores

are available

 X1 is a return value

Restricted © Siemens 2019

Page 79 2019-06-29 Siemens Digital Industries Software
Types of output variables: multi line share

 Extension of same multi line macro to

several variables

 To be used when several multi line

macros have similar list of arguments
(i.e. similar dependencies)

 Share the same piece of multi line macro

code Acam internal variable multi line macro (aca)
X1 multi line macro (acam)
 Prevent code duplication, reduces CPU
time

Restricted © Siemens 2019

Page 80 2019-06-29 Siemens Digital Industries Software
Types of output variables: multi line share

 Acam internal multi line macro

 X1 multi line macro (acam)
 Tfratio multi line macro (acam)

 3 multi line macros x1

 2 of them depend on acam
 Acam depends on internal state variable
Acam
(aca)
tfratio
 X1 and Tfratio can be merged with acam

Restricted © Siemens 2019

Page 81 2019-06-29 Siemens Digital Industries Software
Types of output variables: multi line share

 Acam remains a multi line macro

 X1 and tfratio are declared as multi line
share
 They share the multi line macro ‘acam’

Restricted © Siemens 2019

Page 82 2019-06-29 Siemens Digital Industries Software
Types of output variables: multi line share

 Code comments

Restricted © Siemens 2019

Page 83 2019-06-29 Siemens Digital Industries Software
Types of output variables: multi line share

 Multi line macro code including

tfratio and x1 as output arguments

Restricted © Siemens 2019

Page 84 2019-06-29 Siemens Digital Industries Software
Types of output variables: fixed

 Variable constant during simulation

 Use case = submodel provides a constant signal V1 = k

that must be passed through a port

 As variable is known before submodel call, helps

breaking implicit loops

 Value accessible in submodel initialization function

Restricted © Siemens 2019

Page 85 2019-06-29 Siemens Digital Industries Software
Types of output variables: discrete

 Variable constant step by step

 Value can be changed only at simulation

start or discontinuity restart (flag==0)

 Initial value set as a parameter

 see “time discontinuity” example

Restricted © Siemens 2019

Page 86 2019-06-29 Siemens Digital Industries Software
Types of output variables: activity, power, energy

 Compute activity, power or energy of a

physical quantity

 Specific to internal variables

 Limited to physical domains handled in

Amesim

 Physical types related to bond graph

vocabulary (C, R, I, S, RS)

 Variable name and title automatically

generated

Restricted © Siemens 2019

Page 87 2019-06-29 Siemens Digital Industries Software
Types of output variables: activity, power, energy

 Computations are optional

(since time consuming) and
can be disabled in Amesim
Run Parameters dialog

Restricted © Siemens 2019

Page 88 2019-06-29 Siemens Digital Industries Software
Types of output variables: activity, power, energy

 Example on mechanical spring

 3 internal variables are created

 Physical type set to “C” for capacitive

element

 Physical domain is “mechanical”

Restricted © Siemens 2019

Page 89 2019-06-29 Siemens Digital Industries Software
Types of output variables: activity, power, energy

 1 private section where code is

to be written

 Power is computed analytically

in “powCspr” variable

 This variable is used to fill

energy state and activity

Restricted © Siemens 2019

Page 90 2019-06-29 Siemens Digital Industries Software
Min, Max, Default values

 Numerical parameters (real, integer) and

some types of variables (state, discrete,
fixed…) require an initial value

 The initial value is set in Amesim parameters

mode by the user

 The submodel can also alter this value for

variables during initialization phase (and
discontinuity restart)

 The initial value has boundaries (min and

max)

 And also a default value set in Ameset

 Variable hidden when Min=Max=Default

Restricted © Siemens 2019

Page 91 2019-06-29 Siemens Digital Industries Software
Min, Max, Default values

 Submodel Editor inserts some test  No automatic code for real parameters and
code for integer parameters only variables because boundaries may be
accepted or refused

Restricted © Siemens 2019

Page 92 2019-06-29 Siemens Digital Industries Software
Submodel requires time

 When selected, send the time “t” to the

calculation function

Restricted © Siemens 2019

Page 93 2019-06-29 Siemens Digital Industries Software
Submodel requires discontinuity flag

 When selected, send the discontinuity

flag “flag” to the calculation function

 Mandatory when submodel handles

discontinuities

Restricted © Siemens 2019

Page 94 2019-06-29 Siemens Digital Industries Software
SI unit conversion

 Real parameters and variable have units

 The SI unit has strong advantages and

some drawbacks

 SI units sometimes badly scaled

 Common units easier to use for end
users (e.g. injector flow rate in m**3/s is
a non sense)

 When selected, LMS Ameset

automatically inserts code converting
parameters and variables to SI unit inside
the submodel calculation function

Restricted © Siemens 2019

Page 95 2019-06-29 Siemens Digital Industries Software
SI unit conversion

 Pressure inputs are

converted from bar to Pa

 Pressure outputs are converted

from Pa to bar
 Flow rate is converted from m**3/s
to L/min

Restricted © Siemens 2019

Page 96 2019-06-29 Siemens Digital Industries Software
Submodel has end of simulation section

 When selected, creates a function to be

called at the end of the simulation
“nameend_”

 Useful to free memory allocated locally or

close files

Restricted © Siemens 2019

Page 97 2019-06-29 Siemens Digital Industries Software
Call to calculation function

 Some submodel outputs are completely

determined by duplicates, one line and
multi line macros

 Calling the calculation is a waste of time

 This can be disabled

V3 V2 = V3*V1

V1

Restricted © Siemens 2019

Page 98 2019-06-29 Siemens Digital Industries Software
Simcenter Submodel Editor

Getting started
Submodel definitions
Enumeration example
Mass-spring examples
Modeler - sorting components
Discontinuity handling examples
Dynamic block example
User library

Restricted © Siemens 2019

Page 99 2019-06-29 Siemens Digital Industries Software
Introduction

 This exercise will focus on ways to improve the organization of

submodel parameters

 Objectives of exercise:

 Create an enumeration parameter

 Tune the visibility attribute of parameters
 Set optional icon layers
 Use preview

Restricted © Siemens 2019

Page 100 2019-06-29 Siemens Digital Industries Software
Using enumeration

 A parameter dialog
similar to Amesim
dialog appears

 Useful to debug the

submodel look and
feel before using it in
 Select hydraulic orifice OR000 in Amesim
Ameset (open OR000.spe in
$AME/libhydr/submodels)

 Click on View -> preview parameters

Restricted © Siemens 2019

Page 101 2019-06-29 Siemens Digital Industries Software
Using enumeration

 Draw your attention on the first

parameter title: not that obvious

 Also look at the other parameters:

too many parameters for setting a
simple orifice!

 OR000 can be set by 2 different

manners, but all parameters are
always visible
 => this is too complex for end users

 Enumeration is a predefined list of

strings. It is a nice way to clarify
parameter setting

Restricted © Siemens 2019

Page 102 2019-06-29 Siemens Digital Industries Software
Using enumeration

 Save OR000 as OR000_ENUM

 Select category directory as

destination directory

Restricted © Siemens 2019

Page 103 2019-06-29 Siemens Digital Industries Software
Using enumeration

 Select the ‘method’ integer

parameter

 Change its type from

‘standard’ to ‘enumeration’

 Next step is setting of

‘enumeration list’

Restricted © Siemens 2019

Page 104 2019-06-29 Siemens Digital Industries Software
Using enumeration

 Simplify title

 Configure enumeration: fill the enumeration list

with user-friendly sentences

Restricted © Siemens 2019

Page 105 2019-06-29 Siemens Digital Industries Software
Using enumeration

 The parameter preview

shows a clearer
parameter

 BUT the list of

parameters is still very
long

Restricted © Siemens 2019

Page 106 2019-06-29 Siemens Digital Industries Software
Using enumeration: tune visibility

 Set the ‘visibility’ field with boolean

expressions depending on ‘method’

 ‘qchar’ and ‘dpchar’ are visible when method is

1, hidden otherwise

 ‘ordiam’ is visible when method is 2, hidden

otherwise

Restricted © Siemens 2019

Page 107 2019-06-29 Siemens Digital Industries Software
Using enumeration: tune visibility

 Parameters appear and disappear

depending on the value of the
enumeration

Restricted © Siemens 2019

Page 108 2019-06-29 Siemens Digital Industries Software
Using enumeration: icon layers

 Select an enumeration value

 Click on “edit bitmap” button
 Icon designer with icon appears

Restricted © Siemens 2019

Page 109 2019-06-29 Siemens Digital Industries Software
Using enumeration : icon layers

 Save a layer for each

enumeration value

Restricted © Siemens 2019

Page 110 2019-06-29 Siemens Digital Industries Software
Using enumeration : icon layers

 Enumeration bitmaps are written as supplementary layers on the component icon or on

the framework bitmap if it exists

Restricted © Siemens 2019

Page 111 2019-06-29 Siemens Digital Industries Software
Simcenter Submodel Editor

Getting started
Submodel definitions
Enumeration example
Mass-spring examples
Modeler - sorting components
Discontinuity handling examples
Dynamic block example
User library

Restricted © Siemens 2019

Page 112 2019-06-29 Siemens Digital Industries Software
Introduction

 This chapter contains 2 examples of spring and 2 examples of mass (1D Mechanical)

 Objective of these exercises:

 Practice on more examples
 Manipulate explicit and implicit states
 See the impact of number of variables on solver

Restricted © Siemens 2019

Page 113 2019-06-29 Siemens Digital Industries Software
Example 1: Spring

for x,v + + for x,v

 Constitutive law

𝐹 =𝑘 ∆ 𝑥
X2=0 X1=0
 Displacements and velocities
orientation correspond to the orientation
of the flux arrows

𝐹 = 𝑓 0+ 𝑘( 𝑥 1+ 𝑥 2)
F = f0

X2
F = f0 + k.X2

X2 X1
F = f0 + k.X2 + k.X1
Restricted © Siemens 2019
Page 114 2019-06-29 Siemens Digital Industries Software
Example 1: Spring

for v + + for v
 Constitutive law using a differential
equation
𝑑𝐹
 Velocity orientation correspond to the =𝑘 ∆ 𝑣
orientation of the flux arrows 𝑑𝑡
 F is declared as an explicit state
variable.

{
As CPU time depends directly on the
number of state variables, this type of 𝑑𝐹
modelling must be used only when
=𝑘 ( 𝑣 1+ 𝑣 2 )
necessary: when the displacements at ports
are not available. 𝑑𝑡
𝐹 ( 𝑡 0 )= 𝑓 0

Restricted © Siemens 2019

Page 115 2019-06-29 Siemens Digital Industries Software
Example 1: Spring

SPR50 SPR51

{
𝑑𝐹
𝐹 = 𝑓 0+ 𝑘( 𝑥 1+ 𝑥 2) =𝑘 ( 𝑣 1+ 𝑣 2 )
𝑑𝑡
𝐹 ( 𝑡 0 )= 𝑓 0
 Test both submodels in Amesim with several mass/springs
 Compare RUN STAT results

Restricted © Siemens 2019

Page 116 2019-06-29 Siemens Digital Industries Software
Example 1: SPR50

 Velocity and displacement

inputs
 Force output
 K stiffness
 F0 compression when both
displacements are zero
 Force2 duplicate of force1

Restricted © Siemens 2019

Page 117 2019-06-29 Siemens Digital Industries Software
Example 1: SPR50 – initialization code

 Simple test on value of k

 Warning and error messages
are added automatically

Restricted © Siemens 2019

Page 118 2019-06-29 Siemens Digital Industries Software
Example 1: SPR50 – calculation code

 Equation setting force1.

 Force2 is automatically set by

code generator since it is a
duplicate

Restricted © Siemens 2019

Page 119 2019-06-29 Siemens Digital Industries Software
Example 1: SPR51

 Velocity and displacement

inputs
 Force1 explicit state
 K stiffness
 Force2 duplicate of force1

Restricted © Siemens 2019

Page 120 2019-06-29 Siemens Digital Industries Software
Example 1: SPR51 – calculation code

 Equation setting the

derivative of force1
 Force2 is automatically set
by code generator since it
is a duplicate

Restricted © Siemens 2019

Page 121 2019-06-29 Siemens Digital Industries Software
Example 1: Spring test model

 Test definition: 80 inertia and springs

 First case: MAS002 / SPR50 = 160 states
 Second case: MAS002 / SPR51 = 240 states

Restricted © Siemens 2019

Page 122 2019-06-29 Siemens Digital Industries Software
Example 1: Spring (parameter values)

Restricted © Siemens 2019

Page 123 2019-06-29 Siemens Digital Industries Software
Example 1: Spring (RSTAT comparison)

SPR51 SPR50

CPU 7 times
bigger !!!!

Restricted © Siemens 2019

Page 124 2019-06-29 Siemens Digital Industries Software
Example 1: Spring

 Solver seems to have regular difficulties with redundant states (SPR51)

Restricted © Siemens 2019

Page 125 2019-06-29 Siemens Digital Industries Software
Example 1: Spring

 The global tendency for CPU is F(N²) with or without optimized solver for stiff
systems (i.e. using BDF methods)

CPU [s]
- with optimized solver
- without optimized solver

Restricted © Siemens 2019

Page 126 2019-06-29 Siemens Digital Industries Software
Example 2: Mass

 Create a new submodel from existing mass icon

(e.g. mass2port)

 Select NEW SUBMODEL

 Specify submodel fields

 Input/output variables
 Inputs: force [N]
 Outputs: velocity [m/s]

 internal variables:
 Acceleration [m/s/s] (optional)

𝑑𝑣
=∑ 𝐹
 Parameters
 Mass [kg] 𝑚
 Constitutive law
𝑑𝑡
Restricted © Siemens 2019
Page 127 2019-06-29 Siemens Digital Industries Software
Example 2: Mass

MAS50
 Constitutive law expressed with an explicit state variable (v1, dv1)
 dv1 symbolises the instantaneous derivative of v1

𝐹 2−𝐹 1
𝑎𝑐𝑐 1=𝑑𝑣 1=
𝑚

 Note the sign convention (F1 and F2 are opposite orientation)

Restricted © Siemens 2019

Page 128 2019-06-29 Siemens Digital Industries Software
Example 2: Mass

 Do not forget to declare v1 as

explicit state

 Edit code and compile submodel

 Test submodel in Amesim

Restricted © Siemens 2019

Page 129 2019-06-29 Siemens Digital Industries Software
Example 2: Mass

 Test must ensure that connection on

both ports is correct

 Spring rate = 1000 N/m

 Damper rating = 100 N/(m/s)
 Initial velocity = 1 m/s

Restricted © Siemens 2019

Page 130 2019-06-29 Siemens Digital Industries Software
Example 2: Mass

MAS51
 Constitutive law expressed with an implicit state variable (v1, resv1)
 resv1 symbolises the residual of differential algebraic equation

𝑟𝑒𝑠𝑣 1=( 𝐹 2 − 𝐹 1) −𝑚 .𝑟𝑒𝑠𝑣 1

resv1 = dv1 / dt

 Note the resv1 variable stores the derivative of v1 on input to the submodel

Restricted © Siemens 2019

Page 131 2019-06-29 Siemens Digital Industries Software
Example 2: Mass

 MAS51 is similar to MAS50 with v1

changed to implicit state

 Edit code and compile submodel

 Test submodel in Amesim

Restricted © Siemens 2019

Page 132 2019-06-29 Siemens Digital Industries Software
Example 2: Mass

 Test must ensure that connection on

both ports is correct

 Spring rate = 1000 N/m

 Damper rating = 100 N/(m/s)
 Initial velocity = 1 m/s

Restricted © Siemens 2019

Page 133 2019-06-29 Siemens Digital Industries Software
Example 2: Mass

 Conclusions

 Both submodels produce similar results

 MAS51 introduced implicit states

 Force the use of DASSL solver
 Impossible to use fixed step solver: no export
to a Real Time platform

Restricted © Siemens 2019

Page 134 2019-06-29 Siemens Digital Industries Software
Example 2: Mass

 One more word on minimal configuration: 4 examples using different

configurations

 Config 1: model with 2 explicit states in the mass

(v, x) - MAS001 and SPR50

 Config 2: model with 1 explicit state in the mass (v)

and 1 explicit state in the spring (F) - MAS50 and
SPR000

 Config 3: model with 2 explicit states in the mass

(v, x) and 1 explicit state in the spring (F) -
MAS001 and SPR51

 Config 4: model with 1 implicit state in the mass (v)

and 1 explicit state in spring (F) – MAS51 and
SPR000

Restricted © Siemens 2019

Page 135 2019-06-29 Siemens Digital Industries Software
Example 2: Mass

 Submodel Parameters  Simulation Parameters

 Spring stiffness = 100000 N/m  200s simulation

 Mass = 100 kg  Print interval = 0.001s
 Initial velocity = 1 m/s  Tolerance = 1e-7

Restricted © Siemens 2019

Page 136 2019-06-29 Siemens Digital Industries Software
Example 2: Mass

Config 1 Config 2 Config 3 Config 4  CPU time is similar

 Number of function
evaluation is similar

 Config 1 uses BDF

steps

 Configs 2 and 3 use

Adams steps

 Config 4 always in
BDF (DASSL)

Restricted © Siemens 2019

Page 137 2019-06-29 Siemens Digital Industries Software
Example 2: Mass

 Linear analysis at t=0s

Config 1  Config 3 shows 3 eigenvalues (3 state

variables used), but one of them has a 0Hz
frequency: one state variable unnecessary.
The system is perfectly defined with 2 state
variables (configs 1, 2 and 4)
 The frequency is the same for the 2 state
Config 2 variables The 4 models describe the same
system
 The real part is = 0  The system is purely
oscillatory (no damping)

Config 3 Config 4

Restricted © Siemens 2019

Page 138 2019-06-29 Siemens Digital Industries Software
Example 2: Mass

 Stabilizing run

 Finds equilibrium position

 Mass inclination set to 90

degrees => mass is vertical

 Velocity should be null at

equilibrium
 Spring force should
compensate the weight

Restricted © Siemens 2019

Page 139 2019-06-29 Siemens Digital Industries Software
Example 2: Mass

 Stabilizing run

 Both configs (1 and 3) compute the same

Config 1
force (980.665N = 100kg * 9.80665)

 Config 1 displacement is correct:

9.80665mm

 Config 3 displacement is wrong:

4.9033mm
Config 3
 Spring force and mass displacement are
not linked in config 3.

Restricted © Siemens 2019

Page 140 2019-06-29 Siemens Digital Industries Software
Simcenter Submodel Editor

Getting started
Submodel definitions
Enumeration example
Mass-spring examples
Modeler - sorting components
Discontinuity handling examples
Dynamic block example
User library

Restricted © Siemens 2019

Page 141 2019-06-29 Siemens Digital Industries Software
Amesim modeler

 This formulation of ODE is the typical

equation solved by Amesim

 F corresponds to the system set of

equations dy
 f (t , y ) for t sta rt t ten d
 Each component/submodel dt
introduces a list of equations to the
whole system y (t sta rt )  A
 Howe does Amesim generate f ?

Restricted © Siemens 2019

Page 142 2019-06-29 Siemens Digital Industries Software
Amesim modeler

 Before compiling the code, the “F”

function is created (see f below)
 F contains the list of submodel
calculation functions
• “LocalFunctionEval” for ODE
systems
• “res” for DAE systems

 This list is a sequential call list :

submodels need to be “ordered”
by the modeler

 Note that 0 port submodels are

always placed first in the list

Restricted © Siemens 2019

Page 143 2019-06-29 Siemens Digital Industries Software
Amesim modeler

 Each component has inputs and outputs

 Multi port approach: information at ports is going in both directions

 Problem: a submodel can be called only when its inputs are known
 A can be called when vB is known
 B can be called when vA is known

vB

A vA B

Restricted © Siemens 2019

Page 144 2019-06-29 Siemens Digital Industries Software
Amesim modeler

 Mass and spring example

 V, X are state variables => already

known since calculated by integrator

 Spring inputs are known => the

F
spring can be called

M V  Mass input (F) is known => mass

can be called
X

Restricted © Siemens 2019

Page 145 2019-06-29 Siemens Digital Industries Software
Amesim modeler

 Call order (inputs, outputs, Y

states from integrator, Y' contains
derivatives of Y)

 V = Yi
 X = Yj
 SPRING(V, X, F)
 MASS(F, V, V', X, X')
 Y'i = V'
 Y'j = X'

Restricted © Siemens 2019

Page 146 2019-06-29 Siemens Digital Industries Software
Amesim modeler

 Example creating an implicit loop

 Both vA and vB require the call to the submodel calculation function to be

computed (basic outputs)
 It is not possible to determine a call order between A and B

inpA vB

A vA inpB B

Restricted © Siemens 2019

Page 147 2019-06-29 Siemens Digital Industries Software
Amesim modeler

 Example creating an implicit loop

 The modeler introduces an implicit variable Z1

 Z1 materializes the constraint equation inpB – vA = 0

 Z1 is estimated by the solver => Z1 is known at the beginning of the call

sequence

inpA vB

A vA inpB B
Z1

Restricted © Siemens 2019

Page 148 2019-06-29 Siemens Digital Industries Software
Amesim modeler

 Call sequence (inputs, outputs)

 inpB = Z1
 B(inpB, vB)
 inpA = vB
 A(inpA, vA)
 Residual(Z1) = inpB – vA

Solver job = minimize residual(Z1)

inpA vB

A vA inpB B
Z1

Restricted © Siemens 2019

Page 149 2019-06-29 Siemens Digital Industries Software
Amesim modeler

 Reducing the residual of generated implicits is a difficult task

 Constraint equations can be badly scaled

 Solver totally ignores what a good starting value could be
 DAE systems usually have difficulties to start simulation (or restart after a
discontinuity)

 Remember that a submodel is viewed as a blackbox by the modeler: submodel can

be called only when ALL its inputs are known

 How to break implicit loops:

 Strategy consists in indicating to the modeler how outputs can be computed with
fewer inputs

Restricted © Siemens 2019

Page 150 2019-06-29 Siemens Digital Industries Software
Amesim modeler

 How to break implicit loops – tips and tricks

 Use advantage of variables computed by solver and not by submodel
 Explicit and implicit states
 Constraints
 Fixed variables
 Discrete variables
  the variable is known before the submodel is called

v1 V1 and x1 are
x1 explicit states

Restricted © Siemens 2019

Page 151 2019-06-29 Siemens Digital Industries Software
Amesim modeler

 Warning: pathological case

 Internal variable declared as explicit state
 External variable declared as basic output

inpA  If v1 really must be an

internal variable then
A declare vA as a multi line
macro, depending on v1
dv1 = F(inpA) vA
vA = v1

 V1 internal variable declared as explicit state

Restricted © Siemens 2019

Page 152 2019-06-29 Siemens Digital Industries Software
Amesim modeler

 Warning: pathological case

 If v1 really must be an internal variable then declare vA as a multi line
macro, depending on v1

inpA

A
dv1 = F(inpA)
vA = F(v1)

 VA is viewed as an independent submodel by the modeler

 vA does not depend on inpA

Restricted © Siemens 2019

Page 153 2019-06-29 Siemens Digital Industries Software
Amesim modeler

 How to break implicit loops – tips and tricks

 Declare external variables as macro
 Duplicates
 One line macros
 Multi line macros

U
Signal output is a one line
macro
U = a.V3 + b
U is determined without F1
V3 F1

Restricted © Siemens 2019

Page 154 2019-06-29 Siemens Digital Industries Software
Amesim modeler

 How to break implicit loops – tips and tricks

 Use “input unused” when an input is declared for

connection compatibility but is never used by the
submodel

V3 is input on port 3, although

never used since only x3 is
necessary for port 2

Duplicate of v3
V3
X3

Restricted © Siemens 2019

Page 155 2019-06-29 Siemens Digital Industries Software
Amesim modeler – finding generated implicits

 It is sometimes difficult to find where the implicit variable

has been stored by Amesim
 Multiple loops
 Imbricated loops

Restricted © Siemens 2019

Page 156 2019-06-29 Siemens Digital Industries Software
Amesim modeler – finding generated implicits

 Amesim can highlight the whole loop by clicking on

the arrow buttons

 But the exact place where the implicit is inserted is

not visible

Restricted © Siemens 2019

Page 157 2019-06-29 Siemens Digital Industries Software
Amesim modeler – finding generated implicits

 Implicit variables are always placed at the end of the list of

equations
 These represent the last lines in the State contributions tab of the
Performance Analyzer
 Double-click on the implicit in the list to highlight the parent
submodel in green

Restricted © Siemens 2019

Page 158 2019-06-29 Siemens Digital Industries Software
Simcenter Submodel Editor

Getting started
Submodel definitions
Enumeration example
Mass-spring examples
Modeler - sorting components
Discontinuity handling examples
Dynamic block example
User library

Restricted © Siemens 2019

Page 159 2019-06-29 Siemens Digital Industries Software
Discontinuity handling examples

Definition

 A discontinuity is characterized by a physical quantity

jumping from one value to another instantaneously

 The discontinuity can occur in the derivatives of state

equations (first, second…)

 The solver does not detect discontinuities: it is the

responsibility of submodels to detect discontinuities
and inform the solver using specific functions (disloc,
distim, dishan)

Restricted © Siemens 2019

Page 160 2019-06-29 Siemens Digital Industries Software
Discontinuity handling examples

 Examples of discontinuities

 Backlash  Hysteresis

 Endstops

 Frictional stick-slip  Duty cycle involving steps, ramps

or discrete signals

 Linear interpolation of tabulated

 Open or closed check valve data

Restricted © Siemens 2019

Page 161 2019-06-29 Siemens Digital Industries Software
Discontinuity handling principle

 When a discontinuity is registered, the solver Flag == 0

locates the precise time corresponding to the
event, and reduces it integration step to end
up at this point
solver submodels
 The solver then stops and restart just after the
discontinuity, and informs the submodels a
restart is in progress.
disloc, dishan, distim

 The communication between solver and submodels is established

 With the value of the “flag” integer variable

 Through the specific functions disloc, dishan, distim

Restricted © Siemens 2019

Page 162 2019-06-29 Siemens Digital Industries Software
Discontinuity handling functions

 disloc: handles a discontinuity of a precise event to machine accuracy.

 extern void disloc_(int *logi);

 dishan: handles a discontinuity of a precise event to user specified accuracy

 extern void dishan_(int *log1, int *log2);

 distim: handles a discontinuity at a specified time

 extern void distim_(double *time);

 Check HTML documentation + Technical Bulletin 121

Restricted © Siemens 2019

Page 163 2019-06-29 Siemens Digital Industries Software
Discontinuity handling flag variable

 Option “requires discontinuity flag” must be selected in Submodel Editor

 Integer “flag” sent to calculation function

Restricted © Siemens 2019

Page 164 2019-06-29 Siemens Digital Industries Software
Simcenter Submodel Editor

Getting started
Submodel definitions
Enumeration example
Mass-spring examples
Modeler - sorting components
Discontinuity handling examples
Example 1: Absolute value
Example 2: more than 2 regions
Example 3: time discontinuity sampler
Example 4: check valve with hysteresis
Example 5: bouncing ball (elastic contact)
Example 6: bouncing ball (restitution coeff.)
Dynamic block example
User library

Restricted © Siemens 2019

Page 165 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : code illustration

Without
discontinuity
handling

With
discontinuity
handling

Restricted © Siemens 2019

Page 166 2019-06-29 Siemens Digital Industries Software
Discontinuity handling code illustration

 First part: (re)start part, also called “flag==0” part

 Determine working condition (x positive or

negative), or “region”

 Store this region in an integer store, element of

the “ic” array. The ic array remains in memory
between consecutive calls.

 This part of code is executed at every restart, even

caused by another submodel

Restricted © Siemens 2019

Page 167 2019-06-29 Siemens Digital Industries Software
Discontinuity handling code illustration

 Second part: effective calculation part

 Calculations are performed depending on ic value

 The equation y=x can be used even though x is

negative !!! Continuity process

 Once equations are done, a test is performed to ensure

the code is in the correct region; logi = 1 means we are not
in the correct region

 Disloc transfers the “logi” information to the solver

Restricted © Siemens 2019

Page 168 2019-06-29 Siemens Digital Industries Software
Simcenter Submodel Editor

Getting started
Submodel definitions
Enumeration example
Mass-spring examples
Modeler - sorting components
Discontinuity handling examples
Example 1: Absolute value
Example 2: more than 2 regions
Example 3: time discontinuity sampler
Example 4: check valve with hysteresis
Example 5: bouncing ball (elastic contact)
Example 6: bouncing ball (restitution coeff.)
Dynamic block example
User library

Restricted © Siemens 2019

Page 169 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : more than 2 regions

 Same kind of work as example of

y=abs(x)
 The ic[0] takes as many values as
existing regions (3 regions)
 A simple f(x) icon from signal library will
be used

Restricted © Siemens 2019

Page 170 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : more than 2 regions

 Regions must be exclusive

 Y = x when x > threshold
 Y = 0 when x <= threshold and x > -threshold
 Y = -x when x <= -threshold

-1 0 1

Restricted © Siemens 2019

Page 171 2019-06-29 Siemens Digital Industries Software
Simcenter Submodel Editor

Definitions
Example 1: Absolute value
Example 2: more than 2 regions
Example 3: sampler (time
discontinuity)
Example 4: check valve (hysteresis)
Example 5: bouncing ball (elastic contact)
Example 6: bouncing ball with restitution
coefficient (resetting states)

Restricted © Siemens 2019

Page 172 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : time discontinuity

 X is input signal
 Y is the value of x at last sample time
 Constant sampling period in s

Restricted © Siemens 2019

Page 173 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : sampler example

 Variables
 X is input signal
 Y is basic output
 Xk is internal discrete state
 Tnext internal discrete state

 Parameters
 Period is real parameter

Restricted © Siemens 2019

Page 174 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : sampler example

X Xk tnext period

Restricted © Siemens 2019

Page 175 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : sampler example

 Each time t reaches tnext

 tnext is incremented
 x is sampled in xk

Restricted © Siemens 2019

Page 176 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : sampler example

 Introduce at least one state

variable: solvers do not like to
work on too simple models

 The square wave source

ensures the sampler is not
perturbed by neighbour
discontinuities

Restricted © Siemens 2019

Page 177 2019-06-29 Siemens Digital Industries Software
Simcenter Submodel Editor

Definitions
Example 1: Absolute value
Example 2: more than 2 regions
Example 3: sampler (time discontinuity)
Example 4: check valve (hysteresis)
Example 5: bouncing ball (elastic contact)
Example 6: bouncing ball with restitution
coefficient (resetting states)

Restricted © Siemens 2019

Page 178 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : check valve with hysteresis

 An ideal check valve opens and closes instantaneously.

 This generates many discontinuities and slows down the simulation.

 Hysteresis is introduced to avoid this problem.

Restricted © Siemens 2019

Page 179 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : check valve with hysteresis

 Part 1: condition for determining correct region

 At first time there is no history: check dp as

with no hysteresis

 Selection depends on history: change ic only

if dp out of hysteresis zone

Restricted © Siemens 2019

Page 180 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : check valve with hysteresis

 Part 2: equation statements + condition for

leaving region (discontinuity)

 Leaving region (logi=1) only when out of

region boundary + hysteresis

Restricted © Siemens 2019

Page 181 2019-06-29 Siemens Digital Industries Software
Simcenter Submodel Editor

Definitions
Example 1: Absolute value
Example 2: more than 2 regions
Example 3: sampler (time discontinuity)
Example 4: check valve (hysteresis)
Example 5: bouncing ball (elastic
contact)
Example 6: bouncing ball with restitution
coefficient (resetting states)

Restricted © Siemens 2019

Page 182 2019-06-29 Siemens Digital Industries Software
Discontinuity handling: bouncing ball

 There are 2 distinct regions

 The ball is moving freely under gravity  The ball is in contact with the floor

 v ball velocity [m/s]  F reaction force of the floor [N]

 y ball displacement [m]  m mass of the ball [kg]

Times at which the ball hits the floor are unknown events
These will be handled as discontinuities

Restricted © Siemens 2019

Page 183 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball

 Create a new submodel from zero velocity source

(Mechanical library)

 What are the input / output external variables?

 Inputs
 Velocity [m/s]
 Displacement [m]
 Output
 Force [N]

 Internal variable

 Gap [m]: the sign of this value will indicate whether

there is contact or not

Restricted © Siemens 2019

Page 184 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball

 The contact between the ball and the floor will be

modelled by a spring k and a damper b

𝐹 =𝑘 . ∆ 𝑦 + 𝑏 .𝑣
 With the Mechanical sign convention, positive
quantities are in the direction of the arrow

 A positive velocity and displacement will be

measured downwards

 A positive force will oppose them

Restricted © Siemens 2019

Page 185 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball

 Create a NEW SUBMODEL based on zero velocity

source icon

 Exercise: create the model with and without

discontinuity handling and look at the impact on
simulation

Restricted © Siemens 2019

Page 186 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball

 Discontinuity handling on the sign on gap

 Definition of 2 zones

 Zone 1: gap <= 0 there is contact

 Zone 2: gap > 0 there is no contact

Not ok Not ok Ok
Y=0 not handled Overlap on y=0

𝑦> 𝑦 0 𝑦≥𝑦0 𝑦≥𝑦0

𝑦< 𝑦 0 𝑦≤𝑦0 𝑦< 𝑦 0
Restricted © Siemens 2019
Page 187 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball

Details of variables

Restricted © Siemens 2019

Page 188 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball

Details of real parameters

Restricted © Siemens 2019

Page 189 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball

 Step 1: code ignoring the discontinuities

Restricted © Siemens 2019

Page 190 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball

 Test in Amesim

Free fall on 100s

Small print interval
Use of RSTAT to get
solver info

Restricted © Siemens 2019

Page 191 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball

 The ball bounces and

reaches an equilibrium at
the end of the simulation

Restricted © Siemens 2019

Page 192 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball

 The solver is obliged to

reduce it step size at
each bounce

 The sharp change in the

floor force has a strong
impact on simulation

Restricted © Siemens 2019

Page 193 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball

 The solver is obliged to

reduce it step size at
each bounce

 The sharp change in the

floor force has a strong
impact on simulation

Zoom around 20s

Restricted © Siemens 2019

Page 194 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball

 Direct impact on number

of function evaluations,
and CPU time

Restricted © Siemens 2019

Page 195 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball

 Step2: handle discontinuities

 Add an enumeration to optionally

handle the discontinuities in the floor
submodel

Restricted © Siemens 2019

Page 196 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball

 Perform check submodels test model

 Run the test with and without discontinuity

handling

 Compare run statistics

Restricted © Siemens 2019

Page 197 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball

 Step size during impact

can be 10 times smaller
when not handled by a
discontinuity

 Solver seems to be more

cautious and less
aggressive after
unhandled bounce

Restricted © Siemens 2019

Page 198 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball

 Direct impact on
number of steps and
function evaluations

Restricted © Siemens 2019

Page 199 2019-06-29 Siemens Digital Industries Software
Simcenter Submodel Editor

Definitions
Example 1: Absolute value
Example 2: more than 2 regions
Example 3: sampler (time discontinuity)
Example 4: check valve (hysteresis)
Example 5: bouncing ball (elastic contact)
Example 6: bouncing ball with
restitution coefficient (resetting states)

Restricted © Siemens 2019

Page 200 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball with restitution
coefficient

 Submodel using a restitution coefficient

 Alternative modelling of bounce effect (kind of ideal contact)

 Illustrates the possible reset of state variables

 When the ball hits the floor, its velocity is reversed in sign and its magnitude is
multiplied by a constant factor lower than one.
 The factor is called the coefficient of restitution

Icon with no port

Restricted © Siemens 2019

Page 201 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball with restitution
coefficient

 Start a NEW SUBMODEL from icon gravityicon

 2 internal explicit state variables

 Velocity [m/s]
 Displacement [m]
𝑑𝑣
 2 real parameters
=𝑔
 Floor altitude [m]
 Coefficient of restitution [null] 𝑑𝑡
𝑑𝑦
=𝑣
𝑑𝑡

Restricted © Siemens 2019

Page 202 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball with restitution
coefficient

Restricted © Siemens 2019

Page 203 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball with restitution
coefficient

Restricted © Siemens 2019

Page 204 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball with restitution
coefficient

Displacement and
velocity can be reset
when flag == 0

getgravity : standard
Amesim function

Restricted © Siemens 2019

Page 205 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball with restitution
coefficient

 Build test model in Amesim

 Run simulation with following

simulation parameters

Restricted © Siemens 2019

Page 206 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball with restitution
coefficient

 The curve shows the bounce when the

displacement reaches 10m

 The curve looks a bit poor

 2 solutions to improve it
 Reduce print interval
 Activate “discontinuity printout”

Restricted © Siemens 2019

Page 207 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball with restitution
coefficient

 Same curve with

discontinuity printout

 2 points added each time

the ball hits the floor

Restricted © Siemens 2019

Page 208 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball with restitution
coefficient

 Zoom comparing both

curves

 Standard printout
points are identical

 One visible point (2

points in reality)
appear when y=10m

Restricted © Siemens 2019

Page 209 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball with restitution
coefficient

 Run the simulation for 20s instead of 10s

Restricted © Siemens 2019

Page 210 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball with restitution
coefficient

 20 consecutive restart error on some

machines

 The modelling implies an infinite number of

bounces before the ball comes to rest =
numerical disaster

 Solution = tolerance on velocity

Restricted © Siemens 2019

Page 211 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball with restitution
coefficient

 Tolerance on velocity

 New real parameter vthres

Restricted © Siemens 2019

Page 212 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball with restitution
coefficient

Tolerance on velocity

Store acceleration in a real

store c[0] during Acceleration is
initialization phase cancelled when
velocity is too small

Restricted © Siemens 2019

Page 213 2019-06-29 Siemens Digital Industries Software
Discontinuity handling : bouncing ball with restitution
coefficient

 Tolerance of 1e-6m/s is enough to allow the ball to come at rest

Restricted © Siemens 2019

Page 214 2019-06-29 Siemens Digital Industries Software
Simcenter Submodel Editor

Getting started
Submodel definitions
Enumeration example
Mass-spring examples
Modeler - sorting components
Discontinuity handling examples
Dynamic block example
User library

Restricted © Siemens 2019

Page 215 2019-06-29 Siemens Digital Industries Software
Introduction

 This chapter contains an example of dynamic block

 Objective of this exercise:

 Discover ways to improve submodel flexibility
 Reduce the number of submodels
 Apply the ‘force recompile’ feature

Restricted © Siemens 2019

Page 216 2019-06-29 Siemens Digital Industries Software
Introduction

 Definition of a dynamic block: submodel having a variable structure

 Number of parameters
 Number of variables
 Dimension of variables, stores

 Any change has an impact on the size of the model: recompilation is

necessary

 Main objectives
 Create and manipulate a dynamic block
 Create multiple sine wave source
 Use ‘force recompilation’ feature

 Limitations
 Limited to C code (no Fortran)

Restricted © Siemens 2019

Page 217 2019-06-29 Siemens Digital Industries Software
Applications

 Transfer function with variable numerator and denominator order

 Variable number of nodes in hydraulic line, or mechanical rope

 Optional intensive calculations (e.g. friction model, PID -> PI) where
dimension is set to 1 or 0

Restricted © Siemens 2019

Page 218 2019-06-29 Siemens Digital Industries Software
dynamic block - characteristics

 1 output variable (scalar)

 1 Integer parameter setting the number of sine waves

 Frequency and amplitude real parameters with a group size

depending on this integer

 1 internal variable with dimension set to number of sine waves for

storing all the frequencies

Restricted © Siemens 2019

Page 219 2019-06-29 Siemens Digital Industries Software
dynamic block – multiple sine wave

 Select the standard icon for

sinew wave or harmonics

 Create NEW SUBOMDEL

Restricted © Siemens 2019

Page 220 2019-06-29 Siemens Digital Industries Software
dynamic block - multiple sine wave

 Define 1 basic
output variable

Restricted © Siemens 2019

Page 221 2019-06-29 Siemens Digital Industries Software
Dynamic block - multiple sine wave

 Define 1 integer parameter

 ‘recompile on value change’

flag is set to true

Restricted © Siemens 2019

Page 222 2019-06-29 Siemens Digital Industries Software
Dynamic block - multiple sine wave

 Define 3 real parameters frequency, amplitude and phase

 Non empty group size field makes the submodel dynamic

 freq and amp are not simple parameters, but groups of parameters frequency1, frequency2, … frequencyN

Restricted © Siemens 2019

Page 223 2019-06-29 Siemens Digital Industries Software
Dynamic block - multiple sine wave

 Define 1 internal basic variable

 The dimension is set to ‘numSine’

 Each time numSine will be changed, the model will

be recompiled

Restricted © Siemens 2019

Page 224 2019-06-29 Siemens Digital Industries Software
Dynamic block - multiple sine wave

 Some specific code is introduced to

get the dimension of the vectors and
sizes of the groups

 name_size for size of parameter

‘name’

 name_dim for dimension of vector

‘name’

 frequency and amplitude are arrays of

double and not simple double

Restricted © Siemens 2019

Page 225 2019-06-29 Siemens Digital Industries Software
Dynamic block - multiple sine wave

 Note that in C, array

indexation starts at 0: freq[0]
is the first item

 I integer must be declared

 Freq has been converted in

rad/s in initialization phase

Restricted © Siemens 2019

Page 226 2019-06-29 Siemens Digital Industries Software
Dynamic block - multiple sine wave

 MULTISINE is tested in Amesim

by comparison with an equivalent
submodel HARM00

 Note the icon specific to numSine

parameter indicating a mandatory
recompilation

Restricted © Siemens 2019

Page 227 2019-06-29 Siemens Digital Industries Software
Dynamic block - multiple sine wave

 Note the icon specific to numSine

parameter indicating it is locked in
simulation mode

Restricted © Siemens 2019

Page 228 2019-06-29 Siemens Digital Industries Software
Dynamic block - multiple sine wave

 Curves produced by
both models are
identical

 Test is successful

Restricted © Siemens 2019

Page 229 2019-06-29 Siemens Digital Industries Software
Simcenter Submodel Editor

Getting started
Submodel definitions
Enumeration example
Mass-spring examples
Modeler - sorting components
Discontinuity handling examples
Dynamic block example
User library

Restricted © Siemens 2019

Page 230 2019-06-29 Siemens Digital Industries Software
Context

 Why create a user library?

 Share some code common to several submodels
 Protect some IP
 Import code from a third party

 Difficulties
 Various compilers (GCC, Microsoft, Intel…)
 Various languages (Fortran, C)
 Static or dynamic library?
 How to link it with Amesim model?

Restricted © Siemens 2019

Page 231 2019-06-29 Siemens Digital Industries Software
Static library

 Advantages
 An archive file is created (.lib or .a) gathering object files: source code is no
longer visible, protecting the IP (if compiled in RELEASE mode)
 Static library is incorporated within the simulation executable during the
compilation (link process): the library is no longer needed after the model is
compiled
 C and Fortran are compatible (some rules must be followed)

 Drawbacks
 Objects must be compiled with compatible compilers: gcc libraries are not
compatible with Microsoft Visual libraries
 Libraries must be compiled with different compilers such that they can be
used by the end user independently of the compiler used; this is exactly
what is done for standard libraries and submodels

Restricted © Siemens 2019

Page 232 2019-06-29 Siemens Digital Industries Software
Step1: create directory structure

 Amesim libraries have an organized folder structure. A library

NAME corresponds to a libname folder in main Amesim directory

 Start to use the working directory where submodels are already

stored
 Create the following lib structure in it

Restricted © Siemens 2019

Page 233 2019-06-29 Siemens Digital Industries Software
Step2: create source files

my_utils.c
 In source directory, create a header and a source file

 The source file contains the code statement

 The header file contains the declaration of function
prototypes to be called by other codes (e.g. submodel
code)

my_utils.h

Restricted © Siemens 2019

Page 234 2019-06-29 Siemens Digital Industries Software
Step3: compile code

 The compilation of a library is done in 2 stages

 Step 1: compiling code to produce object files
 Step 2: linking objects files into a single archive (or library)

 Using gcc  Using Visual C++ in 32 bits

 AMEcc_DEBUG -gcc *.c  call vcvars32

 cd ..\win32-gcc  AMEcc_DEBUG *.c
 ar –rcv libMYTEST.a *.o  cd ..\win32
 lib *.obj /out:MYTEST.lib

Restricted © Siemens 2019

Page 235 2019-06-29 Siemens Digital Industries Software
Step4: link with Amesim

 Create a file called AME.make in the library structure

$(CC) -I"$(AME)/lib" -c
$(CC)
-L"$(THISNODE)/lib/$(MACHINETYPE)" -lMYTEST
win32:"$(THISNODE)\lib\$(MACHINETYPE)\MYTEST.lib"
win64:"$(THISNODE)\lib\$(MACHINETYPE)\MYTEST.lib"

Restricted © Siemens 2019

Page 236 2019-06-29 Siemens Digital Industries Software
Step4: link with Amesim

 In submodel code

 Include the header file containing function

prototypes in the private section

 Call the function as other functions

Restricted © Siemens 2019

Page 237 2019-06-29 Siemens Digital Industries Software
Presenter
Title
Group / Region / Department XY

[email protected]
Thank you for your attention.
Any question?
How does the solver work?

 Step 1: predictor
 Predict y(1)n+1 with explicit
y(1)n+1
method

y’n
yn

yn+1 = yn + h.y’n
tn tn+1
t
h
Restricted © Siemens 2019
Page 240 2019-06-29 Siemens Digital Industries Software
How does the solver work?

 Step 1: predictor
 Predict y(1)n+1 with explicit
y(1)n+1 y’(1)n+1
method

 Step 2: corrector
 evaluate y’(1)n+1

y’n
yn

tn tn+1
t
h
Restricted © Siemens 2019
Page 241 2019-06-29 Siemens Digital Industries Software
How does the solver work?

 Step 1: predictor
 Predict y(1)n+1 with explicit
y(1)n+1 y’(1)n+1
method

 Step 2: corrector
 evaluate y’(1)n+1 y(2)n+1
 refine y(2)n+1 with implicit
method y’n
yn

yn+1 = yn + h.y’n+1
tn tn+1
t
h
Restricted © Siemens 2019
Page 242 2019-06-29 Siemens Digital Industries Software
How does the solver work?

 Step 1: predictor
 Predict y(1)n+1 with explicit
y(1)n+1 y’(1)n+1
method

 Step 2: corrector
 evaluate y’(1)n+1 y(2)n+1 y’(2)n+1
 refine y(2)n+1 with implicit
method y’n
y(3)n+1
yn
 Step k: corrector
 Evaluate y’(k)n+1
 Refine y(k)n+1 with implicit
method

 until y’(k+1)n+1 ≈ y’(k)n+1

tn tn+1
t
h
Restricted © Siemens 2019
Page 243 2019-06-29 Siemens Digital Industries Software