Cameo Simulation Toolkit UserGuide

Cameo Simulation Toolkit 2021x
Refresh2
User Guide
No Magic, Inc., a Dassault Systèmes company, 2021

All material contained herein is considered proprietary information owned by No Magic, Inc. and is not
to be shared, copied, or reproduced by any means. All information copyright 1998-2021 by No Magic,
Incorporated, a Dassault Systèmes company. All Rights Reserved.
Copyright © 1998 – 2021 No Magic, Incorporated, a Dassault Systèmes company.

Contents
Why Simulation? 9
Business Benefits 9
Installation and licensing 10
System requirements 10
Modeling Tools* 10
FLEXnet License Server 12
Basic concepts 12
Plugin installation 13
Plugin licensing 15
Uninstalling plugins and deactivating licenses 16
Updating plugins 16
User Guide 16
Getting started 17
Introduction to Cameo Simulation Toolkit 17
Key features 18
Simulation project template 19
Model simulation 21
Elements simulation 22
Simulating a Simulation Configuration 42
Subset property 44
Simulation Configuration and UI modeling 46
Project options 47
SimulationConfig stereotype 49
Simulation log 59
Simulation time and simulation clock 61
Automatic start of active objects 69
UI modeling diagram simulation 70
ImageSwitcher and ActiveImage 75
Copyright © 1998 – 2021 No Magic, Incorporated, a Dassault Systèmes company. 3

Contents
Time series chart 87
Timeline chart 111
Histogram 125
Nested UI Configuration stereotype 129
Reusable UI Mockup 139
CSV export 141
Nested property selection for configurations 144
Attached files supported 145
Web Server for Cameo Simulation Toolkit 147
Animation 180
Active, visited, and last visited elements 180
Customizing animation 182
Animation speed option 183
Opening a diagram of an executing behavior 184
Simulation information in diagrams 185
Simulation debugging 197
Understanding simulation sessions 197
Debug process simulation 199
Simulation console 200
Runtime Value Monitoring 206
Updating default values 247
Breakpoints 250
Disabling updates in Simulation panes 254
Validation and verification 254
State Machine simulation 256
Supported elements 258
Adapting models for State Machine simulation 259
Running a State Machine simulation 279
State Machine duration simulation 281
Sample projects 282
Activity simulation 286

Contents
Activity simulation engine 287
Creating a model for Activity simulation 295
Executing Activities 311
Activity duration simulation 317
Duration analysis 326
Running a Call Action simulation without a target pin 331
Activity Partition execution and allocated Behavior 332
Execution of incomplete/dummy models 334
Using utility functions of Simulation 344
Streaming Activity simulation 347
Interaction simulation 352
Supported elements in interaction simulation 352
Creating a model for interaction simulation 368
Executing an interaction model 381
Recording simulation as a Sequence diagram 387
Use Case simulation 398
Actions associated with actors within a Use Case diagram. 399
Parametric evaluator 399
Specifying the language for the expression 400
Automatic and manual initialization of objects/values 403
Value binding 405
Evaluating expressions 413
Evaluation with causality 421
Constraints on parts 425
Dynamic constraint 426
Parametric debugging 430
Manual value updates using the Parametric Evaluator 430
Communicating with evaluators through simulation console 432
Built-in Math 434
Integration with external Evaluators 449
Sample project 475

Contents
Simulation of SysML models 476
A Functional Mockup Unit blocks simulation. 477
Simulation of a Time Series chart. 478
FMI 2.0 co-simulation 478
Supported SysML elements 480
Requirements traceability from the Variables pane 499
Non-normative extensions 504
Action languages 507
The decision input that is unspecified and the guards that are empty. 507
Supported scripting languages 507
Reading enumeration literal value 508
References to elements with HTML 509
Value access and references by tags 510
Importing external libraries 512
Action scripts APIs 515
Server-side simulation 534
Preparing the environment for server-side simulation 534
Preparing projects for server-side simulation 535
Server-side simulation limitations 535
Simulation using REST API 535
Simulation using Jupyter Notebook 542
Simulation in Cameo Collaborator for Teamwork Cloud 548
Simulation with Simulation Template 553
Frequently asked questions 555
Activity simulation 555
Parametric evaluation 556
State Machine simulation 556
Simulation modeling: Do's and Don't's 557
Don’t: Create an fUML loop without any Action Activation 557
Do: Add an Action Activation in the loop 558
Developer Guide 559

Contents
Introduction 559
SimulationOptionProvider interface 559
Java APIs 560
Execution 561
Engine 564
fUML Helper 568
Parametric Helper as executing parametric simulation from an Activity 569
Tutorial 570
Stopwatch model sample 570
Stopwatch structure 571
Stopwatch Behavior 571
Creating an executable stopwatch model 571
Executing the stopwatch model 612
Creating User Interface mockups for the stopwatch model 635
Using simulation command line and showing test results through
Jenkins 644
Preparing a simulation project and Configs in MagicDraw 645
Running a project through simulate command line 646
Creating a JUnit test case and configuration file 647
Configuring Jenkins for the Automated testing 647
Simulate command arguments and parameters 649
Simulate command arguments with projects in Teamwork Cloud 652
Property file sample: Project-Config1.properties 653
JUnit test sample: TestSimulationCommandLine.java 654
Ant configuration file sample: run_junit.xml 656
Analysis pattern 657
Rollup Pattern simulation 657
Monte Carlo simulation 660
Trade study analysis 666
Integrating widgets for simulation 677
The jQuery Knob widget. 678

Contents
Predefined variables 692
Additional resources and support 693

Web page 693
Online Information 694
E-mail 694
Bug reports 694
No Magic customer support system 695
Frequently asked questions 695

Cameo Simulation Toolkit provides the first in the industry extendable model execution framework
based on OMG fUML and W3C SCXML standards. It extends UPDM plugin to validate system behavior
by executing, animating, and debugging SysML Parametric models in the context of realistic mock-ups
of the intended user interface.
Why Simulation?
The purpose of a simulation is to gain system understanding without manipulating the real system,
either because it is not yet defined or available, or because it cannot be exercised directly due to cost,
time, resources or risk constraints. Simulation is typically performed on a model of the system.
With the Cameo Simulation Toolkit, users can test how the system reacts to user interaction or
predefined testing data and execution scenarios.
Business Benefits
Users will find that one of the key business benefits of the Cameo Simulation Toolkit is cost efficiency.
Employing Cameo Simulation Toolkit will assist enterprises in significantly reducing project costs,
allowing users to identify design errors before the actual production of components.
To learn how to install and use Cameo Simulation Toolkit, see:
• Installation and licensing(see page 10)

• User Guide(see page 16)
• Developer Guide(see page 559)
• Tutorial(see page 570)
• Additional resources and support(see page 693)
• Cameo Simulation Toolkit Documentation 2021x Refresh11

• Cameo Simulation Toolkit Documentation 2021x2
• Cameo Simulation Toolkit Documentation 19.0 SP43
• Cameo Simulation Toolkit Documentation 19.07
1 https://docs.nomagic.com/display/CST2021xR1/Cameo+Simulation+Toolkit+Documentation
2 https://docs.nomagic.com/display/CST2021x/Cameo+Simulation+Toolkit+Documentation
3 https://docs.nomagic.com/display/CST190SP4/Cameo+Simulation+Toolkit+Documentation
7 https://docs.nomagic.com/display/CST190/Cameo+Simulation+Toolkit+Documentation

Installation and licensing
In this section, you will learn about the system requirements, basic concepts, installation and licensing
procedures, and how to uninstall and update the plugin.
For more information, see No Magic product installation and licensing(see page 10).
Related pages
• System requirements(see page 10)

• Basic concepts(see page 12)
• Plugin installation(see page 13)
• Plugin licensing(see page 15)
• Uninstalling plugins and deactivating licenses(see page 16)
• Updating plugins(see page 16)
System requirements
Modeling Tools*
Resource Recommended
CPU Intel Core™ i5 or higher
RAM 16GB
The memory allocation for the modeling tool by project size:
Project Elements Count Allocated Memory 2

(including used projects)
Earlier 2021x and later

versions 1
1.5 million 1 million 6GB
5 million 3.5 million 11GB

 The amount of required memory proportionally increases if working on multiple
projects.
1
the project elements count is different due to the profiling data storing metamodel
optimized in 2021x (decrease by 40-80% in SysML and UAF projects).
2
these memory requirements are indicative and may vary by project specifics.
The operations that require more memory (1, 2, and 3.5 million of 2021x project elements
respectively):
• UPDM migration to UAF - 10GB, 10GB, 36GB

• Converting between UAF, DoDAF2, DoDAF, MODAF, NAF, NAF4 frameworks -
8GB, 9GB, 13GB
• Element/Content History - 10GB, 15GB, 27GB
• Project Merge - 11GB, 13GB, 21GB 3
• Project Clone - 12GB, 14GB, 22GB
3
strongly depends on the amount of detected changes between merged versions (in this
case, the specified required memory is for merging projects with 1.5k changes in total).
Disk space The recommended disk space for installation and configuration files is 3GB or more
depending on used plugins, project type (local or server), and project size. In addition to
this, large server projects require extra disk space for configuration files:
Project Elements Count Disk Space

(including used projects)
Earlier 2021x and

versions later
5 million 3.5 million 30GB
 The amount of required disk space proportionally increases if working on multiple

projects.
Note: Element History and Content History features usage requires significantly more disk
space due to intensive caching at the client-side.
Depending on the feature usage scenario (e.g., retrieving content history from old/distant
project versions multiple times), the disk space might increase by up to 100GB.
Display Full HD (1920x1080) or higher

resolution**

Operating Any Java SE 11-compatible operating system (Windows, Windows Server, Linux (RedHat/
Systems CentOS 7), Mac OS X).
Java Virtual Java version support8

Machine (JVM)
version
* Magic Software Architect, Magic Cyber Systems Engineer, Magic Systems of Systems Architect,
MagicDraw, Cameo Systems Modeler, Cameo Enterprise Architecture
** 800x600, 1280x1024 display resolutions are compatible with a laptop or a projector.
 Earlier versions
Windows XP and earlier versions are not supported.
Mac OS 10.6 Snow Leopard and earlier versions are not supported.
FLEXnet License Server

For system requirements, refer to the Release Note9 of the specific version.
Basic concepts
On this page
• Borrowing(see page 13)

• Configuration files(see page 13)
• License key(see page 13)
• Floating license(see page 13)
• Host ID/Target ID(see page 13)
• License type(see page 13)
• Vendor daemon(see page 13)
8 https://docs.nomagic.com/display/NMDOC/Java+version+support
9 https://docs.nomagic.com/display/NMDOC/Downloading+installation+files

Concept Description
Using a floating license in the offline mode.

If a license is used on a machine that is intermittently connected to the license server,
Borrowing the license can be borrowed from the server and used as an offline floating license. A
license can be borrowed from a license server for the selected period of time (default
24 hours).
The maximum license borrowing period is 2 months. If you would like to limit the
maximum borrowing period, please contact your sales representative.
The files where your defined settings and environment options are stored.
Configuration When upgrading your software, you can choose one of the following:
files
• If you want to import the environment options from an earlier modeling
tool or server version, select the location and click Import.
• If you are installing the software for the first time and/or do not want to
use earlier environment options, click Use Default.
A license for the dedicated Host ID/Target ID received after purchase.

License key
The floating license allows you to install and use the same license on multiple
machines. The FlexNet license server is used to manage floating licenses.
Floating license
A combination of 12 numbers and letters (also known as the MAC Address or Physical
Address), which identifies the network card of a machine. It is used to tie the license
Host ID/Target ID to a particular machine.
Seat (Nodelock). The license of a modeling tool dedicated to one working place.
License type Floating (Shareable). Allows you to install and use the same license of a modeling
tool on multiple machines.
 Please note, the license type of a modeling tool and a plugin used by this
tool must be the same.
A program developed by CATIA / No Magic to implement the FlexNet license server.

The vendor daemon tracks how many licenses are checked out and who has the
Vendor daemon licenses.
Plugin installation

Choose one of the following ways to install a plugin in a modeling tool:
• Install a plugin bundle (.rdzip) that comes with a modeling tool directly via the Resource/Plugin
Manager dialog.
• Install an individually purchased archived plugin file (.zip) via the Resource/Plugin
Manager dialog.
• Install a plugin manually
• Obtain and install a plugin from a web server
To install a plugin bundle (.rdzip) via the Resource/Plugin Manager dialog
1. Start your modeling tool.

2. From the modeling tool main menu, select Help > Resource/Plugin Manager.
3. Click the button.
4. In the Manage Resource Locations dialog, click Add. The Select Resource Location or
Distribution File dialog opens.
5. Specify the location of a plugin bundle (.rdzip) file and click Open. The resource location is added.
6. Click OK to import resources.
 You can extract the .rdzip file and then add selected plugins individually(see page 14).
To install an individual plugin from an archive file (.zip) via the Resource/Plugin Manager dialog
1. Start your modeling tool.

2. From the main menu of a modeling tool, select Help > Resource/Plugin Manager.
3. Click the Import button and specify the location of an archived plugin file (.zip) and click
Open. The plugin is extracted and installed automatically.
4. Restart your modeling tool.
To install a plugin manually
1. Extract an archived plugin file (.zip) file to the same directory where your modeling tool is
installed.
2. Start the modeling tool. The plugin is applied to your modeling tool.
You can also obtain the needed resources from a web server if you do not have the .rdzip file but have
been provided with an URL by your license manager.
To specify the server where the resources and their descriptor file are located
1. Open Resource/Plugin Manager and click .

2. In the Manage Resource Locations dialog, click Add URL. The Resource Server URL dialog
opens.

3. In the open Resource Server URL dialog, type or paste the server address.
4. Click OK.
The resources from the selected location are listed in the Resource/Plugin Manager.
For more information on managing resources, please see Resource Manager10.
 Getting help
If you run into any installation related problems, try the following:
checking the FAQ section11 for known problems
checking the No Magic Community forum12
contacting customer support13
14
Related pages
• Modeling tools and plugins licensing15

• FlexNet license server installation and licensing16
• Installation and licensing 17
18
Plugin licensing
10 https://docs.nomagic.com/display/MD2021x/Resource+Manager
11 http://www.nomagic.com/support/faq.html
12 https://community.nomagic.com/
13 https://docs.nomagic.com/display/NMDOC/Support
14 https://docs.nomagic.com/display/NMDOC/Installing+plugins
15 https://docs.nomagic.com/display/NMDOC/Modeling+tools+and+plugins+licensing
16 https://docs.nomagic.com/display/NMDOC/FlexNet+license+server+installation+and+licensing
17 https://docs.nomagic.com/display/NMDOC/Installation+and+licensing
18 https://docs.nomagic.com/display/NMDOC/Installing+plugins

On this page
Unable to render include or excerpt-include. Could not retrieve page.
Uninstalling plugins and deactivating licenses
On this page
Updating plugins
On this page
User Guide
Welcome! This user guide will walk you through the basics of using Cameo Simulation Toolkit.
Use the search box to find a specific topic or select one from the list below:

• Getting started(see page 17)
• Model simulation(see page 21)
• Simulation Configuration and UI modeling(see page 46)
• Animation(see page 180)
• Simulation debugging(see page 197)
• Validation and verification(see page 254)
• State Machine simulation(see page 256)
• Activity simulation(see page 286)
• Interaction simulation(see page 352)
• Use Case simulation(see page 398)
• Parametric evaluator(see page 399)
• Simulation of SysML models(see page 476)
• Action languages(see page 507)
• Server-side simulation(see page 534)
• Simulation with Simulation Template(see page 553)
• Frequently asked questions(see page 555)
• Simulation modeling: Do's and Don't's(see page 557)
Getting started
Cameo Simulation Toolkit is a MagicDraw plugin, which provides a unique set of tools supporting the
standardized construction, verification, and simulation of computational complete models based on a
foundational subset of the UML. It also enables Activity, State Machine and parametric simulation
(execution), animation, and debugging in UML and SysML models, including profiles, samples, and key
features(see page 18).
No Magic is the first in the industry to provide customers with an easy-to-use, standard-based
executable UML solution that integrates the semantics of different UML behaviors. The purpose of this
Getting Started section is to provide you with an overview of the plugin and a brief explanation of how
exactly this plugin works.
Related pages
• Behavior(see page 25)
Introduction to Cameo Simulation Toolkit
The purpose of simulation is to understand the function or performance of a system without

manipulating it directly because the real system may have not been completely defined or available, or
it cannot be experimented due to costs, time, resources, or any other constraints. A simulation is
typically performed on a model of a system.

With Cameo Simulation Toolkit, you can simulate a model and validate the functionality or performance
of a system in the context of a realistic mockup of the intended user interface. Cameo Simulation
Toolkit provides the solutions that enable you to predict how the system responds to user interactions,
predefined test data, and simulation scenarios.
Cameo Simulation Toolkit contains the Simulation Framework plugin that provides the basic GUI to
manage the runtime of any kind of executable models and integrations with any simulation engines.
The main functionalities of Cameo Simulation Toolkit are as follows
• Simulation Window
• Toolbars and Debugger pane: to control simulation or a model simulation.
• Simulation Console: to simulate log outputs and command lines for active engines.
• Sessions pane: to select particular sessions of simulation.
• Variables pane: to monitor the runtime values of each simulation session.
• Breakpoints pane
• Trigger options
• Pluggable Simulation Engines
• Animation simulation
• Model debugger
• Pluggable Events and Data Sources
• Pluggable Mockup Panels
• Model-driven Simulation Configurations
• Pluggable Parametric Evaluator and Action Languages
For the version compatibility of the plugin and modeling tools, please refer to the compatibility of
Cameo Simulation Toolkit plugin19 page.
After installing MagicDraw and the Cameo Simulation Toolkit plugin, you can find samples of Cameo
Simulation Toolkit projects in the Samples directory under the Simulation section on the Welcome
page (go to Help from the main menu > Show Welcome Screen).
You can also find the offline user manual by going to Help on the main menu > Other Documentation
> Cameo Simulation Toolkit User Guide.
Related pages
• Simulation console(see page 200)

• Animation(see page 180)
• Action languages(see page 507)
Key features
Cameo Simulation Toolkit is capable of running your UML or SysML models. The key features of Cameo
Simulation Toolkit are as follows
19 https://www.nomagic.com/support/compatibility#Cameo%20Simulation%20Toolkit%20plugin

• Simulation Framework
The general infrastructure (including the simulation toolbars, context menu, and panes) and
Open API for simulation.
• Activity Engine (fUML Engine)
The OMG fUML (a foundational subset of the Executable UML) standard.
• State-Machine Engine (SCXML Engine)
The W3C SCXML (State Charts XML) standard, which is an open-source Apache implementation.
• Interaction Engine
Enabling Cameo Simulation Toolkit to simulate interactions that are modeled with Sequence
diagrams.
• Parametric Engine
Enabling Cameo Simulation Toolkit to simulate SysML Parametric diagrams.
The simulation sample projects are available in the <md.install.dir>/samples/simulation directory.
Related page
• Activity simulation engine(see page 287)

• State Machine(see page 28)
• Interaction(see page 30)
• SysML Parametric Diagram20
Simulation project template
Simulation Project is a useful template that consists of fundamental diagrams and elements basically
required for the user to work on a simulation project. The template significantly reduces time spent on
working on the preparation of making simulation from scratch. The template is available in
the Simulation project category in the New Project dialog.
To open a template
1. Click File > New Project on the MagicDraw main menu.

2. Select Simulation > Simulation Project in the New Project dialog.
3. Name your project, select its location, create a directory for the project, and click OK.
20 https://docs.nomagic.com/display/SYSMLP2021xR2/SysML+Parametric+Diagram

The Simulation Project template arranges basic and necessary diagrams represented by Class and
Package diagrams including State Machine diagrams. The project template additionally encompasses
Simulation Configuration to which a Simulation Target is set.

Simulation project template with the class and package diagrams.
Related pages
• Class diagram21
• Package diagram22
• State Machine diagram23
Model simulation
On this page
• Elements simulation(see page 22)

• Simulating a simulation configuration(see page 42)
• Subset property(see page 44)
Cameo Simulation Toolkit allows you to run elements simulation in a MagicDraw project. Elements that
can be simulated are those that are supported by the simulation engines in Cameo Simulation Toolkit.
21 https://docs.nomagic.com/display/MD2021xR2/Class+diagram
22 https://docs.nomagic.com/display/MD2021xR2/Package+diagram
23 https://docs.nomagic.com/display/MD2021xR2/State+Machine+diagram

Any number of simulation engines can be implemented as separate plugins and registered to
Simulation Framework as the engines for some particular types of models.
The following table shows a list of simulation engines and their supported elements that come with
Cameo Simulation Toolkit
Simulation Supported elements

engine
Activity • Activities.
engine • Activity diagrams.
• Classes whose classifier behavior is an Activity.
• InstanceSpecifications of a class whose classifier behavior is an Activity.
State • State Machines.

Machine • State Machine diagrams.
engine • Classes whose classifier behavior is a State Machine.
• InstanceSpecifications of a Class whose classifier behavior is a State Machine.
Interaction • Interactions.
engine • Sequence diagrams.
• Classes whose classifier behavior is an Interaction.
• InstanceSpecification of a Class whose classifier behavior is an Interaction.
Parametric • Blocks that contain properties that are bound to other properties (or constraint
engine parameters) with connected binding connectors.
• SysML Parametric diagrams.
• InstanceSpecifications of a Block containing properties that are bound to other
properties (or constraint parameters) with connected binding connectors.
To create a simulation, do either of the following
• Run the elements that are supported by the engines.(see page 22)
• Create a Simulation Configuration(see page 42) including setting a target element to be simulated
by the Simulation Configuration and run the model from the Simulation Configuration.
Related pages
• Activity simulation engine(see page 287)

• Interaction simulation(see page 352)
Elements simulation

On this page
You can run a model simulation through the shortcut menu and the diagram toolbar.
To run a model simulation through the shortcut menu
1. Right-click an element either on a diagram and select Simulation > Run.
Or right-click it in the containment browser (see the following figure) and

select Simulation > Run, which will be enabled if the selected element is a Behavior or a diagram
whose context is a Behavior.

The Simulation window will open with a new simulation session in the Sessions pane.

2. Click the Start button on the toolbar of the Simulation pane to run the model.
To run a model through the diagram toolbar
1. Do any of the following

• Click the Run or Run with Context button on the diagram toolbar to run a diagram that
has a context Class or Behavior (Composite Structure diagram, Activity diagram, State-
Machine diagram, Use Case diagram, or Sequence diagram). Cameo Simulation Toolkit will
run the class or the behavior which is the context of the diagram.
• Select the element, which you want to run, on a Class diagram or a Package diagram, and
click the Run or Run with Context button on the diagram toolbar. Cameo Simulation
Toolkit will run the selected element on the diagram. A new simulation session in the
Sessions pane will open.
2. Click the Start button on the toolbar of the Simulation pane to run the model.
Behavior
On this page
You can simulate a Behavior (Activity, State-Machine, or Interaction) either with or without its context
Classifier by simply right-clicking the Behavior in the browser or on a diagram and select
either Simulation > Run or Simulation > Run with Context. Here, the classifier is the context of the
Behavior.
You can also set the Behavior as a target of Simulation Configuration (See Simulating a Simulation
Configuration(see page 42) for more details) as follows
• Running a Behavior with its context Classifier

If you run the Behavior with its context Classifier, Cameo Simulation Toolkit will initialize the
object of the Classifier, which is the Behavior's context, to be simulated. And it will simulate the
Behavior on the initialized object. If the Classifier has a Classifier Behavior, Cameo Simulation
Toolkit will start the Classifier Behavior of the context and wait until the object is in the idle state
(waiting for a signal) to start the Behavior.

• Running a Behavior without a context Classifier
If you run the Behavior without its context, Cameo Simulation Toolkit will create an object of the
Behavior and simulate it directly. Cameo Simulation Toolkit will also initialize values for the
properties and parameters of the simulating Behavior. You can modify the values through
the Variables pane before starting the simulation.
The simulation of the Behavior with its properties and parameters.

To simulate a Behavior from an Activity, a State Machine diagram, or an Interaction directly, do either of
the following
• Open the diagram and click Start on the Simulation window toolbar
• Right-click the diagram and select Simulation > Run.
The simulation of the Behavior, which is the context of the diagram, will run.
Activity
Whenever you run an Activity, Cameo Simulation Toolkit will create a new session for the Activity
simulation. If you run the Activity with its context, it will create another session under the session of the
context object in the Sessions pane. If you click it, the object of the Activity will appear in
the Variables pane. If there is an Activity diagram whose context is the simulating Activity, animation

effect on such diagram (for non-silent simulation) will begin playing.
 Note
When you use a read self action in an Activity, normally it returns an object, which is the
context of the Activity. However, if the context object does not exist, it will return an Activity
execution, which is the Activity's object.

Running an Activity.
Animation of fan Activity Simulation.

Related pages

State Machine
Similar to the Activity simulation, when you run a State Machine, Cameo Simulation Toolkit will create a
new session for a State Machine simulation. If there is a State Machine diagram that represents the
State Machine, animation effect on the diagram will begin playing at the start of non-silent mode
simulation.

Running a State Machine.

Animation of the State Machine simulation.
Related pages
• Activity(see page 26)

Interaction
If you run an Interaction, Cameo Simulation Toolkit will simulate it and play animation effect on a
Sequence diagram, which represents the Interaction.

Running an Interaction.

Animation of an Interaction simulation.
Related pages

Class
On this page
• Initialization of value properties using Arrays of default values(see page 34)

• Automatic instantiation of the implementation Class(see page 35)

You can run a Class element that is not a Behavior. Cameo Simulation Toolkit will initialize an object
from the selected Class. The default value of its parts and properties will be used for initialization. If the
selected Class has a defined Classifier Behavior which is Activity, State Machine or Interaction, it will
also be simulated. For example, if you execute the Calculator.mdzip24 Class, the simulation will be
performed on the Calculator State Machine as shown in the figure Animation of a State Machine
Simulation25 in the State Machine section.
State Machine as the Classifier Behavior of the Calculator Class.

If the Class does not have a Classifier Behavior, Cameo Simulation Toolkit will initialize the object from
the selected Class and show its values and parts in the Variables pane. For a SysML model, Cameo
Simulation Toolkit will update the values within the object with the constraint properties and the
binding connectors. Therefore, you can manipulate the values of the object when working with the
parametric model of the Class.
24 https://docs.nomagic.com/download/attachments/82761686/Calculator.mdzip?
api=v2&modificationDate=1510908736612&version=1
25 https://docs.nomagic.com/download/attachments/82761658/Figure_0007.png?

Running a SysML block that has no defined Classifier Behavior.
Animation of a SysML Parametric diagram.

You can simulate a system even though there is no Classifier Behavior in either the parent or its
subsystems. When Cameo Simulation Toolkit runs the system, all Classifiers that have or do not have
Classifier Behaviors will be simulated. The simulation will run the system and will stop only if you
terminate it by clicking the Stop button.
Initialization of value properties using Arrays of default values

Cameo Simulation Toolkit supports use of Arrays in Class/Block as a data type. A primitive value type,
e.g., String, Boolean, Integer, and Real, as a value property with a default value using an Array can be
initialized. The value property is shown in tree control structure on the Variables pane as shown in the
figure below.

Primitive value types are initialized as value properties with default values using Arrays.
Furthermore, the value property name as a variable can be used as a member of an Array. For
example, x = 5 and v = [2, 3, 4, x] make the initialized v = [2, 3, 4, 5].
 Note
• The initialization through an instance replaces the default value in the Array of the Block.
• Any missing values in Array slots are replaced by default values from the Array of the
Block.
Automatic instantiation of the implementation Class

Simulation Toolkit supports automatic instantiation of an implementation Class, if the super Class is
abstract (Is Abstract = true).
 Note
If there are multiple implementation Classes, Simulation Toolkit will randomly choose one.

Automatic instantiation of the implementation Class if the super Class is abstract.
Related pages
• Animation of a State Machine Simulation26

• Classifier Behavior property(see page 486)
Diagram
You can use the shortcut menu or the diagram toolbar to simulate a diagram. Cameo Simulation Toolkit
will simulate the element, which is the context of the selected diagram, the same way it simulates a
Behavior or a Class depending on the element which is the context of diagram. You can also specify the
diagram as a target of a Simulation Configuration (see Simulating a Simulation Configuration(see page
42) for more details).
To simulate a diagram do one of the following
• Right-click a diagram and select either Simulation > Run or Simulation > Run with Context (if
the context of the diagram is a Behavior).
26 https://docs.nomagic.com/download/attachments/17678500/Figure_0007.png?

• Click the Run button in the diagram toolbar and select either Run or Run with Context (if the
context of the diagram is a Behavior).
To terminate diagram simulation do one of the following
• Click the Terminate button in the diagram toolbar.

• Click the Terminate button in the Simulation pane.
Instance Specification
You can also run an InstanceSpecification. Cameo Simulation Toolkit will initialize an object from the
Classifier of the Instance Specification. The structure values of the object will be loaded from the slot of
the Instance Specification rather than from the default value of the properties of the Classifier.
To run an Instance Specification
• Right-click an Instance Specification and select either Simulation > Run or Simulation > Run
with Context if the classifier of the Instance Specification is a Behavior. You can also specify an
Instance Specification as a target of Simulation Configuration.

You can run an Instance Specification whose Classifier is a Behavior. In such case, Cameo Simulation
Toolkit will initialize the object from the Behavior and load the slot values to the object. Then it will
simulate the object in the same way as it simulates the object initialized from a Behavior.
If the Behavior, the Classifier of the Instance Specification, has a SysML Adjunct property whose primary
is a parameter of the Behavior (See Adjunct Property(see page 482)), Cameo Simulation Toolkit will set the
value of the parameter with the value of the Adjunct property. Therefore, you can use a slot value of
the Adjunct property to set the initial value of the parameter.

Simulation of an Instance Specification whose Classifier is a Behavior (with
Adjunct property).
Table
On this page
• Selecting SimulationConfig to run an instance(see page 41)
Cameo Simulation Toolkit provides the means to simulate a set of elements iteratively using a Generic
Table or an Instance Table. Each element in the table will be simulated one-by-one from the first to the
last row.

You can run the table by specifying it as a target of a Simulation Configuration and then run the
Simulation Configuration. You can also run an Instance or Generic Table using the toolbar button. The
toolbar button is dynamic. If you do not select any rows in the table, the toolbar button is Evaluate.
However, if you select a row in the table, the toolbar button will change to Evaluate Selected Rows.
To run a Generic Table
• Click Run or Run Selected Rows on the toolbar.

To run an Instance Table
• Click Evaluate or Evaluate Selected Rows on the toolbar.
 Note
For a model that has Behaviors (Classifier Behavior and/or Part Property with Behaviors), see
the autoStart tag in SimulationConfig(see page 49).
Selecting SimulationConfig to run an instance

To run a selected instance configuration with full setup, e.g., clock, plots, or UI, Simulation Toolkit
provides compatible SimulationConfigs. Those SimulationConfigs, which are listed in the Simulation
toolbar under the ► Run button of an Instance table, have the same type of the Execution Target as

the Classifier of the table. A SimulationConfig supports only one instance (one row) of the table.
Therefore, you must select a row so that the name of the SimulationConfig will be shown, for example,
as in the figure below. When you select a SimulationConfig to run, it will temporarily replace the
Execution Target of the Config with the selected table entry of an instance. Other settings of the
SimulationConfig, e.g., clock, charts, or UI, apply the same Behaviors as normal.
SimulationConfigs listed in the Simulation toolbar of the Instance table allow running an instance with full
setup, e.g., clock, plots, or UI.
Simulating a Simulation Configuration
Cameo Simulation Toolkit provides a Simulation Configuration. It is an element that you can use to run
an element with options that you can customize. You can see the details of such options in the next
chapter. You can run a Simulation Configuration through either the context menu or the main toolbar.
To run a Simulation Configuration, do one of the following

• In the main toolbar, click next to the Simulation Configuration name.
• In the Simulation ConfigurationDiagram, right-click a Simulation Configuration shape and

select Simulation > Run.
To terminate a Simulation Configuration, do one of the following
• In the main toolbar, click the Terminate button next to the Simulation Configuration name.

• Click the Terminate button in the Simulation pane.
Related page
Subset property
Cameo Simulation Toolkit supports and includes Subset properties in a simulation. It initializes subsets
at the beginning of simulation and also updates their values during simulation. The following figure
demonstrates a model with subsets

A Model with Subsets.
When the Cameo Simulation Toolkit starts running the model, it will add all runtime values of the
subsetting properties to the subsetted properties as illustrated in the following figure
Subsets after being initialized.
You can update or add a value in the subsetting or subsetted properties. Removing or changing a value
in the set of values of a subsetting property will cause the value to disappear or will cause a change in

the set of values in the subsetted property, and vice versa. Adding a value to the set of values in the
subsetted property causes it to appear in the set of values in the subsetting property.
Sample model
The model used in the figures on this page is the SpacecraftMassRollup sample model that comes
with your modeling tool.
To open this sample, do either of the following
• Download SpacecraftMassRollup.mdzip27.
• Find it in the modeling tool <modeling tool installation
directory>\samples\simulation\SpacecraftMassRollup.mdzip.
Simulation Configuration and UI modeling
This chapter discusses the components as follows
• Project options(see page 47)

Setting options for a Simulation project, e.g., animation, simulation framework, and Simulation
engines.
• SimulationConfig stereotype(see page 49)

«SimulationConfig» and the SimulationConfig stereotypes as a model-based execution
configuration through the «stereotype» SimulationConfig.
• Simulation log(see page 59)

Recording all event occurrences during simulation of a Simulation Configuration.
• Simulation time and simulation clock(see page 61)

Enabling Cameo Simulation Toolkit to obtain the amount of time spent on simulating a model
from a simulation clock.
• Automatic start of active objects(see page 69)

An active object whose Classifier is an active Class.
• UI modeling diagram simulation(see page 70)

UI components supporting the UI modeling diagram simulation.
• ImageSwitcher and ActiveImage(see page 75)

ImageSwitcher as a powerful animation tool and «ActiveImage» attributes.
27 https://docs.nomagic.com/download/attachments/82761697/SpacecraftMassRollup.mdzip?

• Time series chart(see page 87)
Displaying plots of runtime values with respect to simulation time and its properties.
• Timeline chart(see page 111)

Allowing you to see the active States of an object or a property during simulation or the Activities
simulated in an object.
• Histogram(see page 125)

Displaying the density of the underlying distribution of data and estimating the probability
density function of underlying variables.
• Nested UI Configuration stereotype(see page 129)

Creating complex UI mockup consisting of multiple UI Configs.
• Reusable UI Mockup(see page 139)

Improving the flexibility in user interface modeling from typing the property using the UI
component.
• CSV export(see page 141)

Exporting simulation results to a CSV file.
• Nested property selection for configurations(see page 144)

Supporting nested property selection for configurations, e.g., Time series charts, Timelines,
Sequence diagram generator, and CSV export.
• Attached files supported(see page 145)

Accessing files as «AttachedFile» by using only file names without paths in case of references to
files by names.
• Web Server for Cameo Simulation Toolkit(see page 147)

Exporting, opening and using UI mockups, and controlling a model simulation on a web browser
on any remote devices.
Project options
You can customize a simulation project, e.g., animation, simulation framework, and simulation engines
through project options. When you save the project, those project options will also be saved. In
addition, you can restore those options to default values with the Reset to Defaults button.
To customize project options
1. Open a simulation project.

2. On the main menu, click Options and select Project. The Project Options dialog opens.
3. On the left pane, click General > Simulation.
 Note
The Options > Project command will be available only if one or more projects are open.

The Simulation Project Options dialog.
Groups of the project options are as follows:

• Animation
Customize animations of the simulation: colors of annotated elements, auto open diagrams, and
silent options. See also customizing animation(see page 182).
• Simulation Framework
Customize general Behaviors of the simulation. See also validation and verification(see page 254)
and integration with external Evaluators(see page 449).
• Sequence Diagram Generator
Record the Sequence diagram generator. See also recording simulation as a Sequence
diagram(see page 387).
• fUML Engine
Customize Behaviors of Activity simulation. See also Activity simulation engine(see page 287).
• Parametric Evaluator
Customize Behaviors of Parametric simulation. See also integration with external Evaluators(see
page 449) and specifying the language for the expression(see page 400).
• SCXML Engine
Customize Behaviors of State Machine simulation. See also completion Events and Transitions(see
page 274) and State activation semantics(see page 273).
• Simulation Script Engine
Select JAR file(s) and load them to the script engine.
SimulationConfig stereotype
On this page
• Initialize References property(see page 54)

• Instantiation scope with excluded elements(see page 57)
Cameo Simulation Toolkit provides a model-based execution configuration through the

«stereotype» SimulationConfig. You can configure the stereotypes in the Specification window of
«SimulationConfig». The following figure shows the «SimulationConfig» and the SimulationConfig
stereotypes
To show up the «SimulationConfig» and the SimulationConfig stereotype
1. Right-click a Package in the Containment tree in a simulation project and select Create Diagram
> Simulation Configuration Diagram, which is the SimulationProfile stereotype applied.
2. Right-click the SimulationProfile [SimulationProfile.mdzip] stereotype in the Containment tree and
select Config > SimulationConfig [Class] and drag the Class to the diagram pane.

The «SimulationConfig» and its «stereotype».
The SimulationConfig «stereotype» contains tag definitions. You can sort these tag definitions
alphabetically by right-clicking it, and select Symbol Properties > Attributes Sort Mode > By Name.
Click the «SimulationConfig» to open its Specification window and see all of the tag definitions.
Tag definition Description
UI A user interface for configuration mockups that will start with a model simulation.
silent If the value is true, simulation will run without animation or idle time.
executionTarget An element from which simulation should start.
 Note
You can drag any element that can be simulated to a Simulation Configuration to
set executionTarget for the dragged element.
excludedElement A list of elements which will be excluded and not instantiated if not ready to be used or not
needed, e.g., Class, Package, Use Case, Actor, Behavior, Connector, Port, and State. See
also in Instantiation scope with excluded elements(see page 57).

log An element in which the execution trace will be recorded.
resultLocation A Package28, a Model, InstanceSpecification29, or an InstanceTable30 in which a context

object will be stored after simulation.
• If the resultLocation is specified by an InstanceSpecification31, the values of

the context object will be saved as slot values of the specified
InstanceSpecification.
• If the resultLocation is specified by a Package32 or a Model, Cameo
Simulation Toolkit will create a new InstanceSpecification33 owned by the
Package or the Model after the simulation. The values of the context object
will then be saved as slot values of the created InstanceSpecification.
• If the resultLocation is specified by an InstanceTable34, a new result instance
will be created and added as a new row with only visible columns of the
table. However, if the executionTarget and the resultLocation are the
same InstanceTable35, the result instance will be updated instead (only visible
columns of the table). See also Instance table36 in MagicDraw User Guide.
 Note
The following elements will not be saved
• InstanceTable without the Classifier set.
• Nested instances inside slots.
• If the resultLocation is not specified, the simulation results will not be saved
even though the simulationTarget is the InstanceSpecification37.
enginesPriority Simulation engines that can be used to simulate a model ordered by priority. The first
engine on the list has the highest priority. If the Simulation Configuration does not have a
tagged value for this tag definition, Cameo Simulation Toolkit will use the values that are
defined in the registered Simulation Engine Priority in the Project Options(see page 47)
dialog.
autoStart If true, a model simulation starts running automatically once it has been initialized.
Otherwise, you must click the Start button in the Simulation pane to run the simulation.
 Note
For Monte Carlo Simulation(see page 660) and Table Simulation(see page 40), the
conditions are as follows:
28 https://docs.nomagic.com/display/MD2021xR2/Package
29 https://docs.nomagic.com/display/MD2021xR2/Instance+Specification
30 https://docs.nomagic.com/display/MD2021xR2/Instance+table
32 https://docs.nomagic.com/display/MD2021xR2/Package

• If true, the simulation will be initialized, solve parametric, start
Behaviors, wait for Behaviors terminated or when endTime is
reached, and terminate. Those Behaviors are Blocks with Classifier
Behaviors and/or Part Property with Behaviors. If endTime is less
than the time of part Behaviors, e.g., duration constraints are
applied, the time of each iteration will be endTime. However, when
endTime is more than the time of part Behaviors, all part Behaviors
will be completed just once.
• If false, the simulation will be initialized, solve parametric, and
terminate. Behaviors will not be started.
clock ratio A ratio between a simulation clock and a real-time clock (1:10). For example, if the clock
ratio is 10, it means that one second on the simulation clock is equal to 10 seconds on the
real-time clock.
autostartActiveO If the value is true, the runtime objects whose classifier is active will start their behavior
bjects automatically in an asynchronous mode. Otherwise, their behavior will start using a
startObjectBehaviorAction.
executionListene A list of execution listeners that will receive events from a model simulation. An execution
rs listener can be a SequenceDiagramGeneratorConfig.
decimalPlaces Decimal places of all displayed numerical values in a model simulation, for example, in
the Variables pane, Tooltip, and the SimulationConsole pane. Their values must be
integers. If the precision of displayed numerical values is greater than or equal to 10% of
the absolute value, the numerical values will be displayed in exponential form.
fireValueChangeE If this value is true, a parametric simulation will be repeated immediately whenever the
vent value of any structural feature changes. Repeating simulation will give an impact on both
values carried over by binding connectors and specified in a constraint.
timeValue A property that will be used in a model-based clock. If the tagged value is specified, the
run-time value specified by the property will be used as the simulation time.
timeUnit A unit of a runtime value that specifies the simulation time. If the tagged value is
unspecified, the millisecond will be used by default.
constraintFailure A flag that indicates a simulation will pause at the constraint element where the failure
AsBreakpoint occurs.
rememberFailure If true, the failure status will be remembered until the termination, and the first failure
Status status will be recorded with its timestamp as fail, even though it passes at the end.
durationSimulati Specifies a duration mode of simulation in min, max, average, or random. Cameo
onMode Simulation Toolkit uses the duration mode to calculate the duration of an Action
simulation to which a duration constraint is applied.
treatAllClassifier This option (true by default) runs all Behaviors, including the ones in the subsystems.
sAsActive Even though the isActive property is false, if TreatAllClassifiersAsActive is true, Cameo
Simulation Toolkit will run all of the Behaviors of non-active Classifiers.

initializeReferenc If true, references will be initialized by creating new objects, instead of referencing to
es existing parts of the system. See also in Initialize References property(see page 54).
startTime Specifies when simulation will initiate (in integer).
endTime The time simulation terminates (in integer).
stepSize Increases as simulation time does (in real numbers or decimal places).
numberOfSteps Specifies the number of steps through which simulation will run.
numberOfRuns A number of runs of a particular configuration, especially for the sample size in Monte
Carlo simulation. The value must be greater than or equal to 1.
timeVariableNam This property returns time from the simulation clock (the default value is "simtime"). It
e returns the time on the simulation clock.
stepDelay Specifies how long the delay will be, if any, for each step.
runForksInParall If the value is true or undefined, all outgoing edges from the fork will run in parallel.
el
cloneReferences If true, creates new instances for all objects recursively. Otherwise, it creates instances
only for the first level and others remain in their original locations (the default is false).
startWebServer If true, starts a web server for a remote web-based UI mockup. Note that the HTML UI
must be generated first using the Generate HTML button in the UI diagram. After starting
SimulationConfig, the web server URL will appear in the Simulation Console window.
solveAfterInitiali If true, automatically starts initial solving. If false, manual start is required via Refresh in
zation the Variables pane, or press Start (F8).
addControlPanel If the value is true, adds the simulation control panel into the exported HTML UI.
animationSpeed Specifies the animation speed of a particular configuration in percentage. The default
value is 95, but you can enter your preferred value from 1 to 100.
recordTimestam If true, timestamp is recorded into a result instance name.

p
 Note
The naming of the newly created instance will not follow MagicDraw instance
naming criteria.
If false (by default), MagicDraw instance naming will be used instead, and the timestamp
will not be recorded and appended to the instance name.

Initialize References property
The property Initialize References in the Specification window of «SimulationConfig» allows Cameo
Simulation Toolkit to initialize all references between objects owned in a composite owner. The
following is the Specification window of «SimulationConfig» from the CoffeeMachine.mdzip38 sample.
38 https://docs.nomagic.com/display/SYSMLP185/_sample+models?
preview=%2F17664205%2F17664212%2FCoffeeMachine.mdzip

Initialize references in the Specification window of «SimulationConfig» Coffee
Machine.
 Note
Initialize References appears if you open the Specification window in the All or Expert
Properties mode.
The following are two types of references that you can initialize using the Initialize References option in
SimulationConfig
• References between objects created inside a system

This type of reference occurs when you create a project similar to the following example. The
following figure shows «block» c as a root context, a is a Part Property, and b is both the part and
reference properties. The «block c» contains an Internal Block diagram with a connector line (the
type of the connector is association named a-b) that connects two part properties a:a to b:b. The
connector specifies that reference property b will get the run time object value from Part Property
b. If there is no connector, an auto-generated value will be given to reference property b.

Initialization of Property.
• References to external objects
If you run a block, for example, the Variables pane will show the classifiers of the references.
When the InitializeReferences is false, the reference property in the block will not be initialized.
When it is true, the reference property will be initialized at run time.

Instantiation scope with excluded elements
To control what part of the model is used in simulation, you can use excludedElement to exclude and
not to instantiate any elements that are not ready to be used or not needed. When any Classifiers, e.g.,
Classes, Packages, Use Cases, Actors, Behaviors, Connectors, Ports, or States are selected, they will not
be instantiated by default instantiation. Excluded Classifiers will not be displayed in the list of types in
the Variables pane when clicked or right-clicked to select Add value. For example, a Part property is
set in excludedElement, so it will not be instantiated when running a simulation as shown in the figure
below. See also in Automatic instantiation of the implementation Class(see page 35).
Part property, CPU2, is not instantiated in the Variables pane, since it has been
set in excludedElement.
For nested Part properties, excludedElement can be set through «SelectPropertiesConfig» as shown in
the figure below. You can find the «SelectPropertiesConfig» control in the Simulation Configuration
Diagram toolbar.

Nested Part property, cache of CPU2, is not instantiated in the Variables pane,
since it has been set in excludedElement through «SelectPropertiesConfig».
Related pages

• Simulation log(see page 59)
• Automatic start of active objects(see page 69)
• Timeline chart(see page 111)
• Histogram(see page 125)
• Nested UI Configuration stereotype(see page 129)
• Reusable UI Mockup(see page 139)
• Nested property selection for configurations(see page 144)

• Instance table39
Simulation log
Cameo Simulation Toolkit provides a simulation log, which is an element to record all event
occurrences during simulation of a Simulation Configuration. It is a Class element applied with a
«SimulationLog» stereotype. The «SimulationLog» stereotype comes with tag definitions as the options
for selecting information that you want to record.
Simulation log.
The tag definitions of the «SimulationLog» stereotype are as follows
• recordedValues
To specify the property whose value will be recorded to the simulation log.
• recordSignals
To specify whether the simulation log will record signals that are sent during simulation. If the
value is true, all of the sent signals will be recorded.
• recordActivation
To specify whether the simulation log will record elements that are activated during simulation. If
the value is true, all of the activated elements will be recorded.
• recordCalls
To specify whether the simulation log will record Operations/Behaviors that are called during
simulation. If the value is true, all of the called Operations/Behaviors will be recorded.
• recordConstraintFailures
To specify whether the simulation log will record elements whose runtime values or objects fail
the constraints applied on them. If the value is true, the elements that cause constraint failures
will be recorded.
You can create a new simulation log element and set it as a tagged value of the log tag definition of the
Simulation Configuration as shown in the following figure

Simulation Config.
A model-based simulation log or trace has many benefits including
• The source of various customized reports and analysis using the MagicDraw validation
mechanism (as both are model-based).
• The capability to import simulation data into any other UML compliant tools.
You can record multiple simulation sessions or test results in the same «SimulationLog» element. The
session's start time can be seen as an attribute's name. You can also record the following runtime data
(see the following figure)
Signal Instance
(when recordSignals = true) under the "Signal Instances" node: timestamp (that is the relative
occurrence time in milliseconds: '0' when the simulation starts), signal type, and target (see the
following figure).
Sequence of Activation and Sequence of Deactivation

(when recordActivation = true) under the "Activation Sequence" node: timestamp and types of the
element being activated or deactivated.
Behavior Call and Operation Call

(when recordCalls = true) under the "Behavior Calls" and "Operation Calls" nodes respectively:
timestamp, type, target, and value(s).
Runtime Value
(when the recordedValues attribute has at least one Property selected) under the "Value Changes"
node: timestamp and the Property and value(s) of a selected Property.
Constraint Failure
(when recordedConstraintFailures = true) under the "Constraint Failures" node: timestamp, element,
target, and value(s).

Recorded runtime information from the Stopwatch sample.
Simulation time and simulation clock
When you simulate a model related to time (for example, a transition with a time trigger), Cameo
Simulation Toolkit will obtain simulation time from a simulation clock. The simulation time is the
amount of time spent on simulating a model. Cameo Simulation Toolkit also uses the simulation time in
a timestamp of a signal instance in the SimulationLog (see Simulation log(see page 59)), in a time series
chart (see Time series chart(see page 87)), and on messages of a generated Sequence diagram.
There are three types of simulation clocks in Cameo Simulation Toolkit:
• Built-in clock. This is the default simulation clock.

• Internal simulation clock. This clock is designed to precisely control the simulation time. Its
implementation is based on UML run-to-completion semantics and internal completion events.

• Model-based clock. You can select the model-based clock by making the property as the time
value tag definition of a Simulation Config. See Model-based Clock(see page 66) for further details
on the model-based clock.
 Note
Nanosecond and microsecond are supported only in the internal simulation clock and model-
based clock.
You can open the Simulation Clock dialog to see the internal simulation clock in real time by right-
clicking within the Simulation Sessions(see page 197) pane and selecting Show Simulation Clock.
The Simulation Clock dialog with the Step button.

You can show or hide simulation time in the Variables pane by selecting Show Simulation Time in the
Options menu.
The Show Simulation Time command in the Options menu.
 Note
The Step button in the Simulation Clock dialog is available only for the internal simulation
clock to allow manually increasing and ticking the internal simulation clock.

Related pages
• Built-in clock(see page 63)

• Internal simulation clock(see page 64)
• Model-based clock(see page 66)
• Understanding simulation sessions(see page 197)
Built-in clock
The built-in clock generates simulation time continuously during a model simulation. You can use the
clock ratio option in Cameo Simulation Toolkit to increase or decrease the amount of simulation time.
The clock ratio specifies the ratio between actual time and simulation time in the same interval. You can
set a ratio of the built-in clock for model simulation. The value you enter for the clock ratio tag
definition of a Simulation Config allows you to scale a ratio up or down (see the following figure). For
further information about stereotypes of the simulation configuration, see SimulationConfig
stereotype(see page 49).
The Simulation Configuration with the wpecified clock ratio.

For example, if a clock ratio is 10, it means that 10 seconds current time is equivalent to one-second
simulation time in the built-in clock. Therefore, the simulation clock is 10 times slower than the actual
clock.
 Note
• The current version of Cameo Simulation Toolkit allows you to pause or resume the
built-in clock.
• When you pause running simulation by either clicking the Suspend button or using
breakpoints, Cameo Simulation Toolkit will stop the built-in clock operation and all
running sessions temporarily. You can continue all of the activities by clicking
the Resume button.
Related pages

Internal simulation clock
On this page
• Simulation time in the console log(see page 65)
The internal simulation clock in Cameo Simulation Toolkit allows you to use a new simulation clock that
can increase its simulation time based on time Events and duration in a model. The following
properties in the Timing group in the Simulation Configuration(see page 49) Specification window enable
you to specify necessary options in the internal simulation clock
• Start Time
An integer value applies for starting the simulation clock.
• Step Size
A decimal value applies for increasing the simulation time. This value, as 1.0 by default unless
specified, is used together with Start Time.
• Step Delay
A decimal value applies for delaying each time step in the simulation clock.
• End Time
An integer value applies for stopping the simulation clock.
• Number Of Steps
An integer value together with Start Time and End Time, to calculate Step Size (if not specified)
for the simulation clock.
 Note
To enable the internal simulation clock, startTime must be specified as the Trigger, along
with stepSize, which is 1.0 by default unless specified. The FlashingLight.mdzip40,
StopWatch.mdzip41, CruiseControl.mdzip42, and CoffeeMachine.mdzip43 built-in sample
projects apply the internal simulation clock.
40 https://docs.nomagic.com/download/attachments/20851796/FlashingLight.mdzip?
41 https://docs.nomagic.com/download/attachments/82761953/StopWatch.mdzip?
42 https://docs.nomagic.com/download/attachments/82761953/CruiseControl.mdzip?
43 https://docs.nomagic.com/download/attachments/82761953/CoffeeMachine.mdzip?

FlashLight SimulationConfig.
Simulation time in the console log

Cameo Simulation Toolkit's clock display in the console log has undergone a change. From now on, the
simulation console will display the simulation time instead of the current date and time. The simulation
clock appears as "00:05:30,000" which is in the format of "HH:MM:SS,Milisecond". The simulation time
will be used for all simulations. The current date and time will no longer be displayed in the simulation
console log.
From the following State Machine diagram, s1 (State 1) takes two seconds to go to s2 (State 2), and s2
takes three seconds to go to s1 again. You can see the simulation time in the following Console log.

The simulation Console log showing the simulation time.
Related page
Model-based clock

Occasionally, you may want to have full control over the amount of simulation time to simulate your
model. Cameo Simulation Toolkit allows you to use a value of any selected property to determine the
simulation time. With this option, you can control the value of the simulation time with your model. The
model that enables you to use the runtime value as the simulation time is called "model-based clock".
Using the model-based clock requires you to specify the property, whose value will be used as the
simulation time, as the value of a timeValue tag definition of a Simulation Config. You can specify the
unit value for the simulation time through the timeUnit tag definition of the Simulation Configuration.
If the timeUnit is unspecified, the millisecond will be used by default.

The Simulation Configuration with timeUnit and timeValue setting for a model-
based Clock.
When you select to use a model-based clock, Cameo Simulation Toolkit will ignore the clock ratio. The
following are the constraints of the model-based clock
• There should be only one object of a classifier whose property is specified as timeValue. In the
preceding figure, the property time of the block Clock has been set as the timeValue of
the System Execution, which is a Simulation Config for simulating the System block. There
should be only one Clock object in each simulation.

• You should not use a time event to update simulation time in a clock model. Because, it obtains
simulation time from the model-based clock. In addition, a time event will be fired at a specific
time or duration, and simulation time cannot be updated unless it is fired. Therefore, if you use a
time event, simulation time will not be updated at all.
Related pages
Automatic start of active objects

An active object is an object whose Classifier is an active Class, a Class element with isActive = true.
When you run a Simulation Configuration with autoStartActiveObjects = true, Cameo Simulation
Toolkit will start the Classifier Behavior of the active Class right after the object is instantiated. The
following figure shows the stereo system's Simulation Configuration where the value
of autoStartActiveObjects is true. In this example, the Behavior of the active objects (Speaker,
Headphone, and Player) will start automatically once the object starts.
Simulation Configuration.
If the value of autoStartActiveObjects is false, or if the Classes or blocks are not active Classes, you
have to start each object using a startObjectBehavior Action. The first figure below shows the System
init Activity, which is the Classifier Behavior of a stereo system block. This Behavior uses
the startObjectBehavior Actions to start the Behaviors of objects, which are the internal parts of the
stereo system object (big speakers, small speakers, and dvd player). You can simplify the System
init activity, as shown in the second figure below, by making the blocks typing the big speakers, small
speakers, and dvd player, to be active blocks then you can simulate the stereo system through a
Simulation Configuration with autoStartActiveObjects = true.

System init Activity to start the Behavior of runtime objects using
startObjectBehavior Actions.
A Simplified System init Activity to be used with autoStartActiveObjects whose

value is true.
UI modeling diagram simulation

On this page
• Frames(see page 71)

• Panels(see page 71)
• Group boxes(see page 72)
• TextFields, checkboxes, and sliders(see page 72)
• Labels(see page 73)
• Buttons(see page 73)
• Combo boxes and spinners(see page 73)
• Radio buttons(see page 74)
The MagicDraw User Interface Modeling diagram becomes even more powerful and valuable when
used with Cameo Simulation Toolkit. Supported UI components are as follows
Frames
You need to drag a Classifier to a UI Frame to bind them together (Cameo Simulation Toolkit will
automatically apply a «UI» stereotype and set its represents tag to the Classifier). Once bound, the UI
Frame can represent the Classifier. The source tag of the applied «UI» stereotype will also be set as
com.nomagic.magicdraw.simulation.uiprototype.UIDiagramFrame by default.
 Note
• The represents and source tag values are necessary to run a simulation with UI.
• If you use the User Interface Configuration element on the diagram toolbars, you need
to manually specify the represents and source tag values accordingly.
Panels
A UI Panel can hold any supported UI components, such as buttons, labels, sliders, check boxes, text
fields, combo boxes, spinners, radio buttons, and even panels themselves.
• If a UI Panel resides in a UI Frame, drag the Property of a Classifier that the UI Frame represents
to the UI Panel to bind that Property to the UI Panel. The «NestedUIConfig» stereotype will be
automatically applied; its "feature" tag will then be set to the Property and its "Text" tag will also
be set to the name of that Property. In this case, the UI Panel represents the Property.
• If a UI Panel (child) resides in another UI Panel (parent), drag the Property of a Classifier that
types the Property and the parent UI Panel it represents to the child UI Panel to bind that
Property to the UI Panel. The «NestedUIConfig» stereotype will be automatically applied; its
"feature" tag will then be set to the Property and its "Text" tag will also be set to the name of that
Property. This functionality allows you to bind the nested parts (properties) of a Classifier to its
correspondent nested UI Panels in a UI Frame representing the Classifier.

• You can also reuse existing UI components (all supported ones, except the frame) in an existing
UI Frame in another UI Panel. To reuse existing components, drag the UI Frame model in the
Containment tree to that UI Panel. The «NestedUIConfig» stereotype will be automatically
applied if it has not been and its "config" tag will then be set to the UI Frame.
During runtime, UI components in the UI Panel can also display their documentation as a tooltip.
Runtime documentation of User Interface components displayed as a tooltip.
Group boxes
Group boxes have similar usages to Panels.
TextFields, checkboxes, and sliders

Drag a Property to one of these three UI components to bind the Property with that particular UI
component. The «RuntimeValue» stereotype will be automatically applied, its "element" tag will be set
to the Property, and its "Text" tag will also be set to the name of that Property. In this case, the UI

component represents the Property. Once represented, the UI component will reflect the value of the
represented Property in the Variables pane during simulation, and vice versa.
Labels
Drag a Property to a UI Label to bind the Property with that particular UI Label. The «RuntimeValue»
stereotype will be automatically applied, its "element" tag will be set to the Property, and its "Text" tag
will also be set to the name of that Property. In this case, the UI Label represents the Property. Once
represented, the UI Label will display the value of the represented Property in the Variables pane
during simulation.
Buttons
You can use a UI button to send Signal(s), call Operation(s), or call Behavior(s).
To use a UI button to send a Signal
• Drag a Signal to a UI button to associate it with the button. The «SignalInstance» stereotype will
be automatically applied, its "element" ("signal") tag will then be set to the Signal, and its "Text"
tag will also be set as the name of that Signal.
In addition, runtime values will be automatically created for all of the attributes and placed under the UI
button if the signal has attributes. You can specify the values to be used at runtime in the "value" tag of
these runtime values. If you click this UI button during simulation, it will send the associated Signal
along with its runtime values.
To use a UI button to call an operation
• Drag an Operation to a UI button to associate the Operation with the UI button.

The «OperationCall» stereotype will be automatically applied, its "element" tag will then be set to
the Operation, and its "Text" tag will also be set to the name of that Operation.
If you click this UI button is during simulation, it will call the associated Operation.
To use a UI button to call a behavior
• Drag a Behavior, such as an Activity, to a UI button to associate it with the button.

The «BehaviorCall» stereotype will be automatically applied, its "element" tag will then be set to
the Behavior, and its "Text" tag will also be set to the name of that Behavior.
If you click this UI button during simulation, it will call the associated Behavior.
Combo boxes and spinners

Drag a Property typed by Enumeration to one of these two UI components (ComboBoxes and Spinners)
to bind the Property to that particular UI component. The «RuntimeValue» stereotype will be
automatically applied, its "element" tag will then be set to the Property, and its "Text" tag will also be set
to the name of that Property. In this case, the UI component will represent the Property typed by

Enumeration. Once represented, the UI component will reflect the value (the selected Enumeration
Literal) of the represented Property in the Variables pane during simulation, and vice versa.
Radio buttons
Drag a Property typed by Enumeration to a UI Panel or GroupBox to bind the Property to that particular
UI panel or GroupBox. The «RuntimeValue» stereotype will be automatically applied, its "element" tag
will then be set to the Property, and its "Text" tag will also be set to the name of that Property. All
Enumeration Literals of the Property type will be automatically created as a vertical list of UI
RadioButtons. Each UI RadioButton will represent Enumeration Literal of the Property type accordingly.
Once represented, the UI RadioButton will display the value of the represented Property in
the Variables pane during simulation.
In addition, you can assign or re-assign other Enumeration Literals to an existing UI RadioButton by
dragging other Enumeration Literals of the same Property type to the existing UI RadioButton. Also, you
can create a single UI RadioButton to represent a particular Enumeration Literal by dragging the
Enumeration Literal to a UI Panel or GroupBox. The «RuntimeValue» stereotype will be automatically
applied, its "element" tag will then be set to Enumeration Literal, and its "Text" tag will also be set to the
name of the Enumeration Literal.
The following figure demonstrates an example of using MagicDraw's User Interface Modeling Diagram
with Cameo Simulation Toolkit.
Using the MagicDraw User Interface modeling diagram with Cameo Simulation
Toolkit.
The steps in this example are as follows

1. Drag a Classifier to a UI frame.
2. Drag each Signal to each UI button to associate it with the button.
3. Specify a value for each UI button's runtime value (the runtime value is located under each
UI button).
4. Drag any Classifier's property to a UI label to be represented.
5. Reference the frame in the "UI" tag of the SimulationConfig.
See the Calculator.mdzip sample for detailed instructions. When you drag any GUI elements to a
diagram, click Run to simulate the animation.
 Note
• The current version of Cameo Simulation Toolkit supports frames, panels, group boxes,
labels, buttons, check boxes, text fields, sliders, combo boxes, spinners, and radio
buttons only.
• Do not drag any model elements of an existing UI Frame (from the Containment tree) to
a diagram to create one more ComponentView/Frame symbol on the diagram. Cameo
Simulation Toolkit does not support two UI symbols of the same model element.
• Other samples include: SmallTestSamples.mdzip, StopWatch_advanced.mdzip, and
SimpleUI_labelUpdate.mdzip.
Sample models
The models used on this page are the CarBrakingAnalysis and Calculator sample models that come
with MagicDraw. To open a sample, do either of the following
• Download CarBrakingAnalysis.mdzip44 or Calculator.mdzip45.

• Find it in the modeling tool <modeling tool installation directory>\samples\simulation.
ImageSwitcher and ActiveImage
ImageSwitcher is a predefined subtype of UI config. It is a simple, yet flexible and powerful animation
tool. You can use ImageSwitcher to represent the state or the enumeration value of a runtime object.
To easily create an «ImageSwitcher» element, specify a represented Classifier, and create as many
attributes and different States as you wish to see them animate. Each attribute is called an
«ActiveImage» and has the following properties
• Image
An image that will be used in animation either from browsing the file or dragging the image
directly from a web browser.
• activeElement
An element that will use an image once it is activated. An active image represents a State of a
runtime object, whereas an activeElement is the state of a Classifier represented by the
44 https://docs.nomagic.com/download/attachments/82762044/CarBrakingAnalysis.mdzip?

ImageSwitcher. While the ImageSwitcher represents an enumeration, the activeElement is the
enumeration literal owned by the enumeration.
• onClick
A signal that will be triggered once an image is clicked.
Related pages
Representing object states
You can use an ActiveImage to represent each state of a runtime object whose Classifier is represented
by the ImageSwitcher that owns the ActiveImage. The FlashingLight.mdzip sample is used throughout
this page. You can open the sample by downloading it from the attached link.
To use the ImageSwitcher and ActiveImage to represent a state
1. Create an ImageSwitcher element, and set its represent tag definition with a Classifier whose
state will be represented by an active image owned by the ImageSwitcher.
2. Create an ActiveImage in the ImageSwitcher for each State of the Classifier represented by
the ImageSwitcher.
3. Specify the image that will be the image attribute of each created ActiveImage and set the State,
which will be represented by the ActiveImage, as the tagged value of the activeElement tag
definition.
The following figure illustrates an example of how to use ImageSwitcher and ActiveImage to represent
the States of a runtime object (see the FlashingLight.mdzip sample)

Using ImageSwitcher in the FlashingLight.mdzip sample with internal simulation
clock.
The image that appears on the web UI through ImageSwitcher is the same image that represents the
current State of simulation UI. If the image on the simulation UI is changed, the image on the Web UI
will change accordingly and vice versa. Either image is able to accept a signal by clicking the mouse.

Setting startWebServer to true in the Simulation Config to show the web UI.
Sample model
The model used in the figures of this page is the FlashingLight.mdzip sample model that comes with
MagicDraw. To open this sample, do either of the following
• Download FlashingLight.mdzip46.
directory>\samples\simulation\FlashingLight.mdzip.
Related pages

• Representing enumeration values(see page 79)

Representing enumeration values
To use the ImageSwitcher and ActiveImage to represent an enumeration value
1. Create an ImageSwitcher element, and specify the enumeration, whose values will be
represented by an ActiveImage of the ImageSwitcher, as the tagged value of the represent tag
definition of the ImageSwitcher element.
2. Create an Active image for each enumeration literal owned by the enumeration.
3. Specify an image that will be the image attribute of each created ActiveImage, and set the
enumeration literal that will be represented by the ActiveImage as the activeElement tag
definition.
You can use SmallTestSamples.mdzip as your example. This file is a sample project of Cameo Simulation
Toolkit. It is located in the <modeling_tool_installation_directory>\samples\simulation folder. In this
example, an ImageSwitcher was created to represent a VerdictKind enumeration. An ActiveImage was
created for each enumeration literal of the VerdictKind as follows

Image switcher and Active Image representing Enumeration and Enumeration Literals.
If a property is typed by an enumeration, you can use the ImageSwitcher and the ActiveImage to
represent it with a UI frame mockup of the Classifier that owns the property. Once you drag the
property to the panel owned by the UI frame mockup, Cameo Simulation Toolkit will prompt you to
select either an ImageSwitcher or a group of radio buttons to represent the value. If you select the
ImageSwitcher, the ActiveImage that represents the enumeration literal, which is the default value of
the property, will open in the panel or in the group box to which the property has been dragged.
The figure below shows the User Interface Modeling diagram of the SmallTestSamples.mdzip sample
project. It contains a UI frame that represents the Test Result dialog, which is the Classifier owning the
property typed by the VerdictKind enumeration. The property is result:VerdictKind, whose default
value is pass. Now, the ActiveImage that represents the value pass will be shown in the panel.
UI Modeling diagram containing a UI frame with Image Switcher.

When the UI mockup opens in the MagicDraw window during model simulation, the image shown in
the panel containing the ImageSwitcher will be the ActiveImage that represents the enumeration literal,
which is the runtime value of the property.
You can simulate the Test Result dialog in the SmallTestSamples.mdzip sample project. You can also
change a result value by selecting one of the radio buttons that represents the value: pass, fail,
inconclusive, or error. Now the image that corresponds to the value will appear.

UI Mockup whowing the property's value typed by enumeration.
You can view more information on reusing ImageSwitcher in the UI mockup in Nested UI Configuration
stereotype(see page 129).
The image that appears on the web UI through ImageSwitcher is the same image that represents the
current State of simulation UI. If the image on the simulation UI is changed, the image on the Web UI
will change accordingly and vice versa. Setting the show empty image for unspecified value option
(true/ false) on the «ImageSwitcher» will change the image on the web UI through ImageSwitcher to be
the same as the image that represents the simulation UI.

The generated HTML button on the toolbar of the UI diagram.
ImageSwitcher on the web UI representing the enumeration value that corresponds to the simulation UI.
Another more comprehensive and realistic sample is available in Cameo Simulation Toolkit is
Blackjack.mdzip. This sample contains a Blackjack game simulation in which Players can only stand or
hit, and the Dealer can stand on 17 or higher. Once you run the Run Blackjack Simulation Config, the
Blackjack game will begin by showing a Blackjack game table UI (see the following blackjack figure).
Note that this sample also demonstrates the Nested UI Configuration feature (see Nested UI
Configuration stereotype(see page 129) for more information). As the Dealer/Player has 7 possible card
slots, according to the Nested UI Configuration feature, the Dealer/Player thus has 7 corresponding
Value Properties, e.g., 'Card1', 'Card2', 'Card3', and so on.

UI showing Blackjack Table in the Blackjack.mdzip sample.
The image showing the card slots demonstrates the application of ImageSwitcher and enumeration.
Each card slot is actually a UI Panel having the NestedUIConfig stereotype applied in
which the NestedUIConfig's config tag is set to the Card Image Switcher ImageSwitcher, and
the NestedUIConfig's feature tag is set to the corresponding Value Property, e.g., 'Card1'. The Card
Image Switcher ImageSwitcher is set to represent the Card Value enumeration.
The Card Image Switcher ImageSwitcher contains 53 ActiveImages, each of which is the corresponding
Enumeration Literal of the Card Image enumeration. Note the Card Value enumeration also contains
53 Enumeration Literals.
• '0' Enumeration Literal represents a blank image; a card slot without any card.
• '1' - '52' Enumeration Literals represent the images of 52 distinct cards.

Image Switcher containing active image of 52 cards and blank image.
When the value of one of the 7 Value Properties changes, the card slot image will change accordingly.
See the Player's cards in the figure to better understand how it works as follows
• The value of the Player's 'Card1' Value Property is '49' Enumeration Literal, which is the
activeElement of the '49' ActiveImage. The '49' ActiveImage represents the ten of spades.
• The value of the Player's 'Card2' Value Property is '28' Enumeration Literal, which is the
activeElement of the '28' ActiveImage. The '28' ActiveImage represents the two of hearts.
• The value of the Player's 'Card3' Value Property is '0' Enumeration Literal, which represents a
blank card slot. Therefore, no card is open next to the two of hearts card.
UI and Variables panel showing the value of 7 value properties and the displayed image.
Related pages

• Representing object states(see page 76)
Time series chart
On this page
• Properties of Time series charts(see page 87)

• Using a Time series chart(see page 91)
• Showing Requirements or constraint violations(see page 92)
• Glossary(see page 94)
• Sample model(see page 94)
In Cameo Simulation Toolkit, a Time series chart displays plots of runtime values with respect to
simulation time. You can show a Time series chart of any runtime values during model simulation. The
Time series chart measures time on the X-axis (horizontal axis) and runtime values on the Y-axis
(vertical axis). The graph of the time series chart simulates the movement of the values or data over
time. It allows you to evaluate trend or monitor behavior in the selected values within a specific period
of time. You can use a time series chart to display real-time plotting of runtime values on the Y-axis,
along with simulation time on the X-axis (as in the simulation time and clock settings). You can also
customize most of the chart properties according to your preferences, including title, plot color, min
and max value, and external CSV. For further information, see the built-in sample
MotionAnalysis.mdzip, used throughout this page to demonstrate how to use the Time series chart in
your model.
Properties of Time series charts

The Specification window of a Time series chart contains the properties you can select or modify to
change the display of the Time series chart. The following figure shows the Specification dialog of the
Time series chart:

The properties of Time series chart in its Specification window.
The following table describes the function of each property of the Specification dialog of Time series
chart:

Property Function
Annotate Failures To annotate a Requirement and constraint failures as the chart plot area in red (true by
default).
Load CSV File A load CSV file is a file that the Time Series chart will load as a curved line graph. You can
import multiple CSV files into the Time series chart and load them as curved line graphs.
They will be represented with different colors and legend names (same as the filename
extension) so you can compare the differences between the actual results and the
desired line graphs.
Record Plot Data To specify the selected format of the file to be saved if Result File is specified.
As
Result File To specify the file name to be saved from the results in the selected file format specified
in the Record Plot Data As property. Otherwise, the results will be saved into model
elements.
Fixed Time Length To specify a fixed range of the time axis in a Time series chart. If you specify a value, the
time axis range will be fixed to that particular value. If you do not specify the value of
Fixed Time Location, the plot(s) will move to the left if the time range is greater than the
maximum value of the time axis. A fixed time length unit is specified by a time unit tag
definition of the simulation config. If you do not specify the time unit, Cameo Simulation
Toolkit will use the millisecond as the default unit.
Fixed Time To specify the start time of the time axis in a Time series chart. If you specify a value for
Location the Fixed Time Length but leave the Fixed Time Location value empty, the Time series
chart will work like an oscilloscope. The plot(s) will move to the left. A fixed time location
unit is specified by a time unit tag definition of the Simulation Config. If you do not
specify the time unit, Cameo Simulation Toolkit will use the millisecond as the default
unit.
Y Label To specify the label of the y-axis of the Time series chart.
Title To specify the title of a Time series chart.
Fixed Range To specify whether a Time series chart will automatically adjust the range on the Y-axis.
If the value is true, the range of the Y-axis will be fixed; otherwise, the range will
automatically change.
Grid X To show or hide a vertical grid line
Grid Y To show or hide a horizontal grid line.
Keep Open After To keep the Time series chart open after the termination of the simulation.
Termination
Max Value To specify an upper bound value of the Y-axis.
Min Value To specify a lower bound value of the Y-axis.
Plot Color To specify a plot color.

Property Function
Refresh Rate To specify a time interval to refresh a Time series chart. A refresh rate unit is specified by
a time unit tag definition of the Simulation Config. If no time unit is specified, the
millisecond will be used as the refresh rate unit.
Linear If true, the plot will connect 2 dots in a non-rectangular line at a time.
Interpolation
The following figure shows the configuration settings of both Time series chart and Simulation Config of
the MotionAnalysis.mdzip sample project. The Time series chart has been set as the "Represents" field
to the Motion Analysis block together with the "Values" field to the required properties (x, v, and a),
along with other properties as needed. Also, the Simulation Config "UI" field has been set to the Time
Series Chart (x-v-a plot).
The configuration settings of both Time series chart and Simulation Config of
the MotionAnalysis.mdzip sample project.
Once the simulation begins, the Time series chart displays real-time plotting of the x, v, and a
properties with time(s), as shown in the MotionAnalysis.mdzip sample.

Real-time plotting of the x, v, and a property with time(s) in the
MotionAnalysis.mdzip sample.
Using a Time series chart

To display a Time series chart
1. Open the context menu of the Variables pane.

2. Right-click the row of a runtime value, which must be shown on the Time series chart.
Select Show in time series chart (see the Time series chart(see page 218) for more information).
The Cameo Simulation Toolkit's Time series chart can also serve as a predefined subtype of UI config.
You can use it as a UI mockup of the SimulationConfig element just like an ImageSwitcher.
To use a Time series chart
1. Create a TimeSeriesChart element to represent a Classifier.

2. In the Specification window, specify the value tag definition and properties whose values will be
monitored in the Time series chart. These properties must be members of the Classifier
represented by the Time series chart element.

Showing Requirements or constraint violations
When Simulation Toolkit annotates a failure property in red (as the selected property to be represented
in the chart) on the Variables pane, the chart plot area during that period of failure will be also
rendered in red. There will be the tooltip shown in the red area with the full information exactly the
same as other tooltips, e.g., in the Instance table and Variables pane, when failure is shown in red.

Labels will be printed in red above the chart and at the center. The label format of a failed constraint is
shown as “<Name of the constraint property typed by the constraint Block> fails”, and the label format of a
failed Requirement is shown as “req <ID> fails”. However, if the name of constraint property is blank,
the label will not be printed. You can also manually disable this option via the Annotate Failures
property in the Time series chart Specification window for some reasons, e.g., too many failures with
overlapped labels in the chart.
Time series chart shows constraint violations with multiple labels.

You can zoom in the chart to see start time and end time points marked with big dots. You can also
display the time unit of each point by hovering the mouse over it as shown in the figure below. Labels
of failed validation will be included in the exported image (by setting Record Plot Data As PNG and
specifying Result File in the Time series chart Specification window). This feature also applies
to Representing Time series charts in a Timeline chart(see page 123).

Tooltip of the Time series chart shows the full information of failure, start time,
and end time points.
Glossary
• CSV
A CSV is a comma-separated values file that stores tabular data (text and number) in plain text.
Each line in the file is a record; each record consists of one or more fields, separated by commas.
• Runtime value
A runtime value refers to the value of the structural features contained in the created object
during model simulation.
• Time series chart
A Time series chart is a graph that can simulate runtime values over a specific period of time.
Sample model
The model used in the figures on this page is the Motion Analysis sample model that comes with a
modeling tool. To open this sample, do one of the following:
• Download MotionAnalysis.mdzip47.
• Find in modeling tool <modeling tool installation directory>\samples.
Related pages
• Specifying time axis' range in a Time series chart(see page 95)

• Exporting plots data(see page 97)
• Representing data from a CSV file in a line chart(see page 109)
• The Time series chart(see page 218)
47 https://docs.nomagic.com/download/attachments/82761967/MotionAnalysis.mdzip?

Specifying time axis' range in a Time series chart
You can specify the range of the time axis (horizontal axis) in a Time series chart by providing the values
of fixedTimeLength and fixedTimeLocation. The fixedTimeLength and fixedTimeLocation units are
specified by timeUnit when a model-based clock is used (For more information about model-based
clock, see Model-based Clock(see page 66)). Otherwise, the unit for value is the millisecond.
You can use the fixedTimeLength property to specify the range of the time axis. If you do not define
the value of fixedTimeLength, the time axis will expand as long as the maximum duration a simulation
will run. The following figure shows a Time series chart when the fixedTimeLength value is 100
seconds
A Time series chart when the fixedTimeLength value is 100 seconds.

You can also change the minimum value of the time axis in a Time series chart by specifying the value
for fixedTimeLocation. The following figure shows a Time series chart when
the fixedTimeLength value is 100 seconds, and the fixedTimeLocation value is 50 seconds

A Time series chart when the fixedTimeLength value is 100 seconds, and
the fixedTimeLocation value is 50 seconds.
If the value you define only that of the fixedTimeLength value, the minimum value of the time axis will
change automatically to adjust to the total length of time that you have defined as the value
of fixedTimeLength. This situation will occur when the simulation time is greater
than fixedTimeLength. If this happens, the maximum time axis value will be the actual simulation time
and the minimum time axis value will increase to preserve the current value of fixedTimeLength.
If fixedTimeLength is 100 seconds, the range of the time axis will be [0, 100] (If you do not
specify fixedTimeLocation, the minimum time axis value will be 0). However, if your simulation model
runs longer than the simulation time or more than 100 seconds, e.g., 115 seconds, the range of the
time axis will be [15, 115]. This particular Behavior of Cameo Simulation Toolkit's Time series chart is
similar to that of Oscilloscope when fixedTimeLocation is unspecified.

A Time series chart with fixedTimeLength 100 seconds and fixedTimeLocation
unspecified running longer than the simulation time.
Exporting plots data
A Time series chart provides two options for you to export your plot data in which time values (the
values that appear on the horizontal axis) and the corresponding recorded values (the values that
appear on the vertical axis) are plotted in a Time series chart. You can export the plot values to either a
comma-separated value file (CSV file) or the slot values of an instance model.

Related pages
Exporting plots data to a CSV file
The values plotted in a Time series chart are exportable to a CSV file.
To export plots data of a Time series chart to a CSV file
1. Click the Export Data toolbar button on the Time series chart's plot panel.
2. Enter a filename and select a location to save the file.

3. Click the Save button.
The following figure shows plotted values in the Time series chart

Plotted values in the Time series chart.
The following figure shows the exported plot values in a CSV file

Exported plot values in a CSV file.
If you exported the plotted values in a Time series chart to a CSV file, the exported plots data in the CSV
file would look like those shown in the first figure. The axes labels would appear in the first paragraph
of the file as the column header.
Related pages

• Exporting plots data to an instance model(see page 100)
Exporting plots data to an instance model
Cameo Simulation Toolkit also allows you to export plots data in a Time series chart to an Instance
model. The model for exported plots data in the simulation profile comprises of DataSet and Data
Classes. Whenever you export plots data to an instance model, Cameo Simulation Toolkit will create an
InstanceSpecification of a DataSet Class. The slot of a data property will contain a list of
InstanceSpecifications of the Data Class. The first instance on the list is an InstanceSpecification
containing the time values while the second one is an InstanceSpecification containing the values that
appear on the vertical axis of the first plot. If a Time series chart has more than one plot, the third
InstanceSpecification on the list will be an InstanceSpecification containing the values of the second
plot and so on.
To export plots data to an instance model
1. Click the Export to Instance toolbar button of the Time series chart's panel whose values you
want to export. The Element Selection dialog will open.
2. Select a package that will own the instance model you want to create.
3. Click the OK button. Cameo Simulation Toolkit will create the instance model containing the plots
data in a Time Series Chart as shown in the following figure

The instance model containing the plots data in a Time series chart.
To auto-save plot values into model on every simulation run
1. Do one of the following

• Double-click the Time series chart.
• Right-click the Time series chart and select Specification.
The Specification window will open as follows

2. Click the button beside the Plot Result Location property to edit its value. The Plot Result
Location property value takes the name of the Instance to save the values, as in the following
figure

3. Start the simulation. When the simulation terminates, the plot values will be written to the
Instance specification selected in the previous step, as in the following figure
Related pages

• Exporting plots data to a CSV file(see page 98)
Saving plot results to the model

The parameter Result Location in the <<SimulationConfig>>(see page 49) allows you to record and save
plot results on a Time series chart(see page 87) into the model when simulation is completed. You can
save the plot results in the Result Location parameter in the following formats: PNG file, CSV, or HTML
file by using the Record Plot Data As option in the Specification window48 of the Time series chart. The
feature works with the Time series chart both stand-alone and in the UI diagram. You can then include
the plot results into a generated document for reporting purposes.
Saving plot results using resultLocation in the <<SimulationConfig>>.
To save plot results using Result Location
1. Open the Specification window of a <<SimulationConfig>> and set Result Location to

an InstanceSpecification.
2. Open the Specification window of a TimeSeriesChart and set Record Plot Data As to the PNG,
CSV, or HTML format.
3. Run the <<SimulationConfig>> until it terminates. The expected plot result will be saved into the
InstanceSpecification. You can review the result through specification of the
 Note
48 https://docs.nomagic.com/display/MD2021xR2/Specification+window

• If Result Location is set to a package, the plot results will be saved into a new
InstanceSpecification at each runtime. However, if Result Location is set to an
InstanceSpecification, the results will be saved into the selected InstanceSpecification.
• After the simulation stopped, the plot results (both image and CSV values) will be saved
in the Image and Comment properties of the specified InstanceSpecification if
the Record Plot Data As option in Time series chart(see page 87) is not specified.
The following figure shows the plot image saved in the Specification of Instance Specification of the
bouncingBall model
The plot image saved in the Image property of the specified

InstanceSpecification of the bouncingBall model.
The image is too large to show in the Image property in the Specification window; therefore, you can
verify it by dragging the InstanceSpecification into the diagram.
To verify a plot image saved in the Image property of the selected InstancedSpecification

1. Drag the InstanceSpecification to the diagram.
2. click on the top left of the InstanceSpecification. The Compartments shortcut menu will
open.
The Compartments menu icon on the top left of the InstanceSpecification.
3. Select Stereotypes > Shape Image.
The following figure shows the CSV values saved in the Specification of Instance Specification of the
bouncingBall model

The plot CSV values are saved in the Body of the Comment property of the
specified InstanceSpecification of bouncingBall model.
You can also specify the Record Plot Data As option in the Time series chart to your preferred plot
result format (PNG, CSV, or HTML). If PNG is selected, you can verify the saved plot image by dragging
the InstanceSpecification to the diagram and click on the top left of the InstanceSpecification to
open the Compartments shortcut menu and select Stereotypes > Shape Image.

Verifying the saved plot image of the InstanceSpecification via Compartments >
Stereotypes > Shape Image.
If the Record Plot Data As option is HTML, the HTML source will be generated into the
Documentation/Hyperlinks property group. You can customize the title, logo, font, and other layouts
of the generated HTML source and use them in other reports.
HTML generated into the Documentation/Hyperlinks field of the

The generated HTML can be saved and opened with a browser as shown in the following figure

The HTML files of the saved plot results (The Record Plot Data As option is
HTML).
Related pages

• Specification window49
Representing data from a CSV file in a line chart
The Time series chart can read data from a CSV file and represent them in a curved line in the chart.
The property External CSV in the Time series chart enables you to import an external CSV file and load
data from the file.
The time Series Chart can read a CSV file with data in multiple columns and show them in lines in the
chart. (The first column is always the value of time on the y-axis) and read multiple CSV files and show
them all at once.
To show data from a CSV file in the Time series chart

1. Click the Load Data... button on the toolbar of the Time series chart's plot pane.
2. Select a CSV file (see an example of the result data in a CSV file), and the Time series chart will
show data from the columns in the file in lines.
The following figure shows a line chart. The solid line in the chart represents the values plotted
Cameo Simulation Toolkit while the dashed lines represent the values from the CSV file.

A line chart with the solid line representing the plotted values and dashed lines
representing the values from the CSV file.
Related pages

Timeline chart
On this page
• Properties of the Timeline chart(see page 111)

• Using a Timeline chart(see page 113)
• Showing the duration of empty/dummy Actions as duration constraints(see page 120)
• Exporting a Timeline chart(see page 122)
• Representing Time series charts in a Timeline chart(see page 123)
Unlike a Time Series chart(see page 87), a Timeline chart allows you to see the active States of an object or
a property during simulation or the Activities simulated in an object. The Timeline plot allows you to see
the animation of all active States while a model simulation is running, as well as which objects are active
in each State or when a State starts and ends.
Similar to the Time series chart, the Timeline chart also shows the x-axis and y-axis. The x-axis
represents time while the y-axis represents object State names in different values. The Timeline chart
identifies the changes in the object states and plots them along a timeline. The States are grouped by
region. Cameo Simulation Toolkit records changes in the active States and allows you to export them to
a CSV or TSV file. You can then import the CSV file into an Excel file to analyze the exported Timeline
chart, such as calculating the simulation duration, what object is in a particular State, and how long it
was busy or idle.
We use the sample project FlashingLight.mdzip50 throughout this section to demonstrate how to use
the Timeline chart in your model.
Properties of the Timeline chart

The Cameo Simulation Toolkit's Timeline chart can also serve as a predefined subtype of a UI Config(see
page 46). You can use it as a UI mockup of the SimulationConfig element just like an ImageSwitcher. The
Specification window of the Timeline chart will be as follows:

The properties of Timeline chart in the Specification window.
You can change the Timeline chart's display by modifying its properties, as shown in the following table.
Property Function
Annotate Failures To annotate a Requirement and constraint failures as the chart plot area in red (true by
default).

Property Function
Context Plot To show or hide a context plot.
Dynamic If true, the chart shows only States or Actions actually used and sorted by occurrence.
Otherwise, the list of static Behaviors is shown, and the chart contains information when
open.
Fixed To specify a fixed range of the time axis in a Timeline chart in milliseconds. If you specify a
Time Length value, the time axis range will be fixed to that particular value. If you do not specify the
value of the Fixed Time Location, the plot(s) will move to the left if the time range is
greater than the maximum value of the time axis. A fixed time length unit is specified by a
time unit tag definition of the Simulation Config. If you do not specify the time unit,
Cameo Simulation Toolkit uses 20,000 milliseconds as the default unit.
Fixed Time To specify the start time of the time axis in a Timeline chart. If you specify a value for the
Location Fixed Time Length but leave the Fixed Time Location value empty, the Timeline chart will
work like an oscilloscope. The plot(s) will move to the left. A fixed time location unit is
specified by a time unit tag definition of the Simulation Config. If you do not specify the
time unit, Cameo Simulation Toolkit uses the millisecond as the default unit.
Ignored Elements A list of elements (States, Actions, and Activities) which will be ignored and not displayed
in the Timeline chart. This list takes priority over the Value list.
Keep Open After To keep the Timeline chart open after the termination of the simulation.
Termination
Linear If true, the plot will connect 2 dots in a non-rectangular line at a time.
Interpolation
As
Result File To specify the file name to be saved from the results in the selected file format specified in
the Record Plot Data As property. Otherwise, the results will be saved into model
elements.
Timeline Mode To select whether to show the Timeline of a State or an Activity.
Title To specify the title of a Timeline Chart.
Using a Timeline chart

To display a Timeline chart

1. Open the shortcut menu of the Variables pane in the Simulation window.
2. Right-click the row of a runtime value you want to show on the Timeline chart and
select Show in Timeline Chart > State or Activity. This example uses State.
To use a Timeline chart
1. Create a Timeline chart element to represent a Classifier.

2. Open its Specification window and click next to the Value property to select the elements/
values to be monitored in the Timeline Chart. The Select Nested Properties dialog opens.

3. Select the values and click . The selected values of the Timeline chart appear in
the Value tag property of the Specification window.

4. Double-click Simulation Config Flashlight on the diagram pane to open its Specification
window.
5. Click next to the UI property field. The Select UI dialog opens.
6. Select the Timeline component and click to add it to the UI of the Simulation Config.

7. Click . The added Timeline component appears as one of the Simulation Config UI
properties in the Specification window.

8. Once you specify all of the values, the Simulation Config in the diagram pane shows the Timeline
chart along with the values that represent systems.
9. Run the Timeline Chart. You can see the animation of the active States in the Timeline Chart
when the Context Plot option is set to False and True. The following figure shows the Timeline
chart output when the Context Plot option in the Specification window is set to False.

The following figure shows the Timeline chart output when the Context Plot option in the
Specification window is set to True
10. Optionally, you can specify in the Ignored Elements property what State will be ignored and
not be recorded in the Timeline chart if the user does not want to see them. The following figure
shows the Timeline chart output when the Ignored Elements property is set to ignore the ticking
State and the off State of timer, and the on State of system

The Ignored Elements property set to ignore the ticking State and the off State
of timer, and the on State of system.
 Important
A Timeline chart shows only States and Actions which are actually used, e.g., Actions with
duration constraints and signaled States. The used elements will be displayed in the chart and
sorted in time order.
Showing the duration of empty/dummy Actions as duration constraints

To show the duration of empty/dummy Actions as duration constraints

• The Timeline Chart can show empty or dummy actions with duration constraints. The dummy
action can be either an empty call Behavior Action with no behavior assigned or an Opaque
Action with duration constraints, shown in the following example.
The Timeline Chart shows the Action names on the left-hand side and the duration simulation
performed on the Actions (not the Activities) on the right-hand side. The same thing applies to an
Action that has Behaviors assigned, but it is empty and has no diagram. The following figure shows the
Timeline chart of the empty/dummy actions from the above example.

The Timeline chart of the empty/dummy actions.
Exporting a Timeline chart

To export a Timeline chart
1. On the Timeline chart pane, e.g., System, click the Export Data button on the Timeline Chart
dialog.
2. The Timeline chart will be exported as a CSV format file. The exported Timeline chart in an Excel
file is in the figure as follows.

Representing Time series charts in a Timeline chart
To represent value properties as separated Time series charts in a Timeline chart
1. Open the Specification window of a Timeline chart and click the Value tag. Boolean,
Enumeration, and Numeric primitive value types, e.g., Number, Real, or Integer, are supported as
shown in the following figure.

Selecting numeric primitive value types in Value of a Timeline chart.
2. Run the simulation with the Timeline chart. The selected value properties will be included in the
Timeline chart and represented as the Time series chart with fixed height, as separate bars for
individual properties as shown in the figure below.
The selected jobsDoneIn value property is represented as the Time series

chart in form of separated bars in the Timeline chart.
Glossary
• Context plot
A Context plot is a Timeline chart property that enables the plot of the context. It appears on top
of the chart as a horizontal line.
• CSV
A CSV is a comma-separated values file that stores tabular data (text and number) in plain text.
Each line in the file is a record and each record consists of one or more fields, separated by
commas.
• Oscilloscope
A piece of equipment showing oscillations in an electric current as waves on the screen.
• Timeline chart
A Timeline chart is used to describe the Behaviors of both individual Classifiers and Interactions
of the Classifiers, focusing attention on the time of events triggering a State change.
• TSV
A TSV is a tab-separated values file that stores data in a tabular structure (e.g. database or
spreadsheet data). Each line in the file is a record and each record consists of one or more fields,
separated by tabs.
Sample model
The models used in the figures on this page are the FlashingLight and OntologicalBehaviorModeling
sample models that come with your modeling tool.

To open the sample, do either of the following
• Download FlashingLight.mdzip51 or OntologicalBehaviorModeling.mdzip52.

• Find it in the modeling tool <modeling tool installation directory>\samples\simulation\.
Histogram
On this page
• Properties of the Histogram(see page 126)

• Using the Histogram(see page 128)
Cameo Simulation Toolkit introduces built-in support for Monte Carlo analysis, allowing you to manage
uncertainties and estimate how random variation of sensitive parameters affects the overall
performance of the system being modeled. A Histogram shows the density of the underlying
distribution of data and estimates the probability density function of underlying variables. The total
area of the Histogram used for probability density is always normalized to 1. A Histogram also allows
you to dynamically view updates on those statistical values during the simulation. In addition, you can
customize the properties, including title, plot color, and labels. For more information about using the
Histogram in your model, see the built-in HingeMonteCarloAnalysis.mdzip53 sample as a
demonstration.
52 https://docs.nomagic.com/download/attachments/82761805/OntologicalBehaviorModeling.mdzip?
53 https://docs.nomagic.com/download/attachments/33195232/HingeMonteCarloAnalysis.mdzip?

A Histogram with dynamic statistical results (N, Mean, SD, and OutOfSpec).
Properties of the Histogram

The Specification dialog of the Histogram contains the properties you can select and modify to change
the display of the Histogram, as shown below.

The properties of the Histogram in its Specification dialog.
The following table describes the function of each property in the Specification dialog of the Histogram
Property Function
Dynamic If true, opening the Histogram during multiple executions shows dynamic results.
Otherwise, the Histogram will be open when all executions are completed.
 Note
When the Dynamic property is set to true, the animation of the Histogram with
dynamic statistical results (N, Mean, SD, and OutOfSpec) is available.
Grid X To show or hide a vertical grid line.
Grid Y To show or hide a horizontal grid line.

Property Function
Keep Open After To keep the Histogram open after the termination of the simulation.
Termination
As
Result File To specify the file name to be saved from the results in the selected file format specified
in the Record Plot Data As property. Otherwise, the results will be saved into model
elements.
Title To specify the title of the Histogram.
X Label To specify the label of the x-axis of the Histogram.
Y Label To specify the label of the y-axis of the Histogram.
 Note
The Histogram can be used only as a local user interface, and the Number Of Runs
«SimulationConfig» must be more than 1.
Using the Histogram

To use the Histogram
1. Create a Histogram element to a Represents Classifier, e.g., Hinge Analysis.

2. In the Specification window, specify the Value tag definition and properties whose values will be
monitored in the Histogram. These properties must be the members of the Classifier
represented by the Histogram element, e.g., hinge.clearance.
3. Set other properties as necessary, as shown in the property table, e.g., Name, Title, and
Dynamic.
4. Drag the Histogram to the Monte Carlo Analysis «SimulationConfig».
5. Verify that UI = Histogram is shown in the «SimulationConfig».
6. Run the Monte Carlo Analysis «SimulationConfig».
 Tips
You can export the Histogram data as a CSV file by clicking the icon at the top-left of the
Histogram pane. The Histogram is exported as a CSV file, shown below.

The Histogram is exported as a CSV file.
Nested UI Configuration stereotype
Cameo Simulation Toolkit provides a «NestedUIConfig» stereotype to create a complex UI mockup,

which consists of multiple UI Configs. This stereotype contains two tag definitions: (i) feature and (ii)
config. The feature tag is mandatory. It specifies which Property (part) of the context it will represent.
The Config tag specifies which existing UI configuration will be used and displayed as the UI of the
system part, which is represented by the Property specified in the feature tag. A Nested UI
Configuration can also show images of UI that is defined as the tagged value of Config tag definition,
such as Panel, activeImage, and Time series chart.

Images of Nested User Interface Configuration.
You can use a NestedUIConfig stereotype to either represent a part of a simulation context(see page 130)
(This part can nest components that represent the nested properties) or representing a part using
existing UI Configurations(see page 134). The NestedUIConfig stereotype can be applied with the UI Panel
or UI Group Box. When it is applied and its tag definitions are set, it can be represented as a part of its
owner component.
Related pages
Representing parts of a simulation context

A UI Panel or UI Group Box to which a NestedUIConfig stereotype is applied and a feature tag set can
represent some parts and nest other components. One of the samples that shows such purpose is
the SmallTestSamples.mdzip sample, which is located in the
<modeling_tool_installation_directory>\samples\simulation folder.
The following System Class diagram shows the structures of Class system and Class monitor

Structures of Class system and Class monitor.
On the same Class diagram, there are Instance Specifications of Class wystem and Class monitor that
will be used in the simulation as follows
Instance Specifications of Class system and Class monitor.

The User Interface Modeling diagram displays the UI configuration that will be used in the simulation as
follows

UI Configuration of Class system.
The following figure displays the UI configuration and the Specification of the UI Panel named panel1,
which represents the monitor1 Property, as a part of Class system

UI Configuration and its Specification.
When the test_nested_panels SimulationConfig is run, the UI mockup will be displayed. The following
figure exhibits the UI Panels and UI Group Boxes that represent the parts (Properties) of the Class
system and in-depth nested parts as well

The Simulation Variables panel and Runtime UI Mockup.
Representing parts using existing UI Configurations

You can also use a NestedUIConfig stereotype to show a part using existing UI Configurations. Any UI
Panels or UI Group Boxes that will be used for this purpose must be applied with the NestedUIConfig
stereotype and must also be set for both the feature and Config tags. The benefit of this purpose is that
you can reuse existing UI Configurations to illustrate any parts of contexts that have the same Class
represented. Thus, you do not need to create a new UI Configuration whenever you want to represent
another part that has the same Class represented.
The FlashLight sample will be used to show how to model a part using an existing UI Configuration. The
following steps show you how to create a UI Mockup that represents the entire system parts, which
uses only one UI Frame
1. Open the FlashLight sample, which is located in the <md.installed>/samples/simulation directory

(FlashingLight.mdzip). The following System Definition Class diagram shows the definition of the
FlashLight system. By default, when executing and running this sample, you will see the Button
and Light are shown in different Frames.
The following figure demonstrates the runtime User Interface Mockup that represents the Class
Button and Class Light

2. Right-click the Containment tree and
select New Diagram > Other Diagrams > User Interface Modeling Diagram to create a User
Interface Modeling diagram.
3. Create a UI Frame on the UI Modeling diagram by dragging the Class system to the newly created
UI Frame as follows
4. Create two UI panels in the UI Frame.

5. Drag the Light property to one of the UI panels to apply the NestedUIConfig stereotype to the UI
Panel and set the Light property to the feature tag of that UI panel as follows

6. Drag an existing UI Configuration named LampBulb to the UI panel that represents the Light
property. This will set the dragged UI Configuration to the Config tag of that UI panel as follows
After assigning the LampBulb UI Configuration to the UI panel representing the Light
Property, you will see the tagged value Specification of the UI panel that represents the Light
property in the Specification of the UI Panel dialog as follows

7. Drag the Button property to another UI panel. Now the UI panel represents the Button property
as part of Class system.
8. Drag an existing UI Configuration named PowerButton to the UI panel that represents the Button
property.

9. Create a new Simulation Configuration element on any Simulation Configuration diagrams; set
the simulationTarget tag to Class system and set the UI tag to the UI Frame that represents the
Class system.
10. Simulate and run the newly created Simulation Configuration. The UI Mockup will appear as
illustrated in the following figure

Reusable UI Mockup
Cameo Simulation Toolkit improves the flexibility in user interface modeling. You can reuse UI
components by typing the property using the UI component. The object, which is the value of the
property, represents a mock-up of the UI component. Once the object is created, the mock-up UI will be
created and shown in the MagicDraw window. Whenever the object is deleted, the mock-up UI will be
deleted as well. It is not necessary to add the UI component to the UI tag definition of the Simulation
Config stereotype.
To create and reuse a UI component
1. Create a UI Frame on a UI Modeling element diagram.

2. Drag the created UI Frame from the Containment browser to the UI Frame symbol in the UI
Modeling diagram to create a UI prototype as follows

3. Create a property in the block. Whenever this property is initialized, the UI Frame simulation will
run.
4. Use the UI Frame as a type for the created property.
You can use a UI Frame to create other properties and define it as the type of the properties. A UI
Mockup will start and will be deleted with an object that is the value of the property typed by a UI
component (including but not limited to the property in Step 3. You can show or hide a UI Mockup by
using the context menu of the instance of the property.
To hide a UI mockup

1. Right-click an instance of a property and click Hide Mock-up in the Variable panel.
2. Click the Close button.
To show a hidden UI mockup
• Right-click an instance of a property and click Show Mock-up.
You can also show or hide the other UI components, for example, time series chart and ImageSwitcher.
Related page
• Creating User Interface mockups for the stopwatch model(see page 635)
CSV export
On this page
• Support of Part properties(see page 143)
As of Version 18.4, Cameo Simulation Toolkit can export simulation results to a CSV file.
A new configuration, called CSV Export, has been added to export simulation results to a CSV file. CSV
files take the following properties:
• File Name
The name of the file that the exported results are written into. The path is the same as the
project directory (by default). Alternatively, a full path may be specified as D:
\ExportedCSVResults.csv
• Record Time
If true (by default), time will be recorded in the first column of the exported CSV file.
• Represents
Specifies the Classifier represented by the Configuration.
• Value
Specifies the properties of the Classifier (including nested properties) whose values will be
recorded and written to the CSV file.
• Write At The End
Records values only once at the end of execution, right before termination, rather than listening
and recording value changes during the execution. When Number of runs is more than 1 in the
main configuration, the values are recorded once in each iteration.
To export simulation results to a CSV file
1. Open a sample simulation project from the samples folder of Cameo Simulation Toolkit. Here
the HingeMonteCarloAnalysis(see page 141) sample is used.
2. Drag the CSV Export Configuration from the toolbox to the Simulation Configuration diagram.

3. Double-click the CSV Export Configuration and fill in values for File Name, Represents, and
Value from its Specification window. The File Name property is the name of the file in the
project's working directory. The Record Time property is for recording time in the first column of
the exported CSV file. The Represents property specifies the Classifier represented by the
Configuration, and the Values property refers to the values selected which will be written to the
exported CSV file. Optionally, you can also set the Write At The End property to record values
only once at the end of execution before termination. The following figure shows the parameters
of CSV Export configuration.
4. Set the created CSV export as a tagged value of the executionListeners tag definition of the
Simulation Configuration. This step is important for the results to be written to file. See the CSV
export configuration below:

5. Run the simulation and then stop it. The results will be written to the File Name specified in Step
3. See the parameters of CSV Export configuration below:
Support of Part properties

Not only can CSV export the values of properties with primitive types, e.g., Real, Integer, etc., but it can
also export the types of the properties that are not primitive. Selected Part names in the value tag will
be used as headers, and type names will be used as values of exported CSVs as shown in the figure
below.

Selected Part names used as headers and type names used as values of
exported CSVs.
Related pages
• Representing data from a CSV file in a line chart(see page 109)

Nested property selection for configurations

Cameo Simulation Toolkit, from version 18.4, includes support for nested property selection for
configurations, such as Time series charts, Timelines, Sequence diagram generator, and CSV export.
The Specification window for the aforementioned items will have the following two properties
• Represents
Specifies the Classifier represented by the Configuration.
• Value
The Value property takes nested property values.
The Select Nested Properties dialog will open if you click the button beside the Value property from
the Specification window.

Select Nested Properties dialog.
 Tip
Before the Value property can be specified, the Represents property has to be assigned a
value first.
Attached files supported

Cameo Simulation Toolkit can access files as «AttachedFile» in MagicDraw using only file names
(without paths), if there are references to files by names not found in project directories. The attached
files supported are as follows:
• CSV: Used by the LoadCSVFile tag of «TimeSeriesChart».
An attached file of BouncingResult.csv used by the LoadCSVFile tag of

«TimeSeriesChart».
• XLSX (Excel): Used by the filename tag of «fileSchema».
• M (MATLAB): Used by the Specification tag of «Constraint».
• FMU (FMI): Used as a «Block» «fmu» for FMI.
• JAR (external libraries): Used as external libraries (*.JAR) in script engine.
However, if the referenced file is in both project directory and in the attached file, the following
conditions are applied:
1. If the file is in the project directory and in the attached file, the file in the project directory will be
used without any displayed messages.
2. If the file is in the project directory but not in the attached file, the file in the project directory will
be used without any displayed messages.
3. If the file is not in the project directory but is in the attached file, the file in «AttachedFile» will be
used, and the following information message will be printed in the Console pane, “INFO: Load
'aFile' of Attached File within the project.”
4. If the file is not in the project directory and not in the attached file, the following error message
will be printed in the Console pane, “ERROR: Cannot find 'aFile' from the project directory or
attached file.”
Related pages
• Projects with file attachments in MagicDraw54

• Excel import plugin documentation(see page 145)
54 https://docs.nomagic.com/display/MD2021xR2/Projects+with+file+attachments

Web Server for Cameo Simulation Toolkit
Web Server for Cameo Simulation Toolkit is an optional free plugin. It allows Cameo Simulation Toolkit
to export, open, use UI mockups, and control a model simulation on a web browser on any remote
device. Cameo Simulation Toolkit and the Web Server plugins must be the same versions. Once the
Web Server plugin has been installed, it will appear as Installed in the Resource/Plugin Manager and
Environment Options dialogs.

The Web Server plugin for Cameo Simulation Toolkit to enable the Web UI
features.
The Web Server plugin for Cameo Simulation Toolkit supports the following Web UI features:
• Web project homepage

• HTML files
• Control panel with restart function for Web UI
• ImageSwitcher on Web UI
• Plotting on Web UI
To install the Web Server plugin for Cameo Simulation Toolkit
1. On the MagicDraw main menu, click Help > Resource/Plugin Manager.

2. Select Web Server for Cameo Simulation Toolkit and click Download / Install.
3. Download and install the plugin according to the instructions.
4. Restart MagicDraw.
To set a port number for the Web Server plugin
1. On the MagicDraw main menu, click Option > Environment. The Environment Options dialog
opens.
2. On the left pane, click Simulation.

3. Under the Web Server group, enter a new Port Number for Web Server.
4. Click OK and restart Web Server.
Activating the Start Web Server property (true) in Cameo Simulation Toolkit before running a
<<SimulationConfig>> automatically generates HTML files. When Web Server has started, and the
simulation is running, a hyperlink to each HTML file saved in the local project folder, along with the URL
of the Web UI, will appear on the Simulation Console tab. You can customize the content of the HTML
files at any time and update files by using the Generate HTML button on the diagram toolbar of the UI
modeling diagram.
Related page
Auto-generating web project homepage

With the Web Server for Cameo Simulation Toolkit plugin, you can use projects loaded in MagicDraw
version 19.0 through a web browser on any remote devices. To use this capability, you need to first
activate the web server in the Simulation window pane.

The Start Web Server button on the Simulation window to start/stop the web
server.
Once the web server has been started, it will produce a notification and a URL in the Simulation
Console pane. The URL launches a web UI mockup instead of a local mockup on a web browser. If you
click the URL, a project homepage will open in your default web browser. The homepage can load all of
the projects that you open in your modeling tools. You can switch projects to launch and the selected
project will also be activated in MagicDraw.
To open a web project homepage
1. Open a few simulation projects, e.g., Calculator and FlashingLight samples.

2. Click in the Simulation window to start the Web Server.
3. Click the URL to open a project homepage on your default web browser.
4. Click a project on the project homepage to open the Simulation Configurations page with a list of
Configurations.
5. Click a Configuration to open its related HTMLs, e.g. LampBulb and PowerButton as the UI
Mockups.

The project homepage of the Web UI allowing you to open different
projects on your browser.
6. Click the Back button on your browser to navigate back to the Simulation Config or homepage.
Note
• Projects without Simulation Configurations will not appear on the homepage.
• If the Web UI is used, local UI mockups will not be displayed.
 Tip
Opening/closing a project in MagicDraw, the home page will be the auto-regenerated project
list accordingly.

Auto-generating HTML files
On this page
• Embedded browser(see page 153)
When you start the Web Server option in your model's <<SimulationConfig>>, and Start Web Server is
true, Cameo Simulation Toolkit will automatically generate HTML files from all used UI Configurations.
This feature saves you a lot of time because you are not required to manually export them to get those
HTML files. You can then use UI Mockups instead of local UI Mockups and control your model
simulation on a web browser of any remote devices.

The Start Web Server Properties options in the <<SimulationConfig>>
Specification window to auto-generate HTML files.
When the <<SimulationConfig>> is run, the build-in web server will start, HTML files with a hyperlink to
each file in the local project folder will be generated, and a URL with a hyperlink will be shown in the
simulation Console pane (regardless of the Options mode you are using in the Console pane).
The web server notification, URL to open web UI, and browser types in the
simulation Console pane.
Embedded browser
Clicking the URL opens a popup menu either Embedded Browser or Web Browser, where you can view
and control the simulation through the Web UI. The Embedded Browser allows showing any web pages
in dock-able embedded windows in fixed places. These windows can be moved, docked, and float in the
MagicDraw window. When you open a saved project or re-run the project with the embedded browser
option, those windows will automatically be shown in the same locations, States (docked/floating), and
sizes. When the simulation is terminated, these windows will be closed automatically. To control the
simulation through the web UI, you need to enable the Add Control Panel(see page 165) option.

Embedded browser UI with Control Panel in MagicDraw.

Web browser UI with Control Panel on Google Chrome.
To run a model simulation on the Web Server
1. Double-click the <<SimulationConfig>> to open its Specification window.

2. Select Web Server Properties from the left-hand side pane and select the Start Web
Server check box (true).
3. Click the URL in the Console pane to open a web-browser as the UI.
 Important
• To prevent overwriting, HTML files will be not be regenerated if they have ever been
generated before.
• The HTML files will be generated anew after you customize the files, e.g., add a logo or
change the text color or size, using the same filename.
• You can delete or rename the existing HTML files if you need them to be regenerated.
• Avoid a duplicate name of «ui» object. If there are two «ui» objects of the same name,
e.g. «frame», only one of them will be auto-generated.
Depending on the circumstances, you may want to manually generate HTML files for further
customization of the web UI Mockups. Manually generating HTML files through either the UI diagram or
HTML supported controls is possible using the Generate HTML command. However, if the files already
exist, a warning message box will open to prevent you from accidentally overwriting
them. All generated HTML files will be written and stored in the project's working directory.
The Generate HTML button on the toolbar of the UI Modeling diagram.

To export a UI Modeling diagram from MagicDraw to HTML5
1. Double-click the UI Modeling diagram to open it.

2. Click . If the file already exists, a warning message box will appear. Otherwise, skip Step
3. A console message will show the information if the files were written successfully.
3. Click Yes to replace the existing files or No to cancel.
 Tip
Anyone with access to the network the web server is on will be able to access the web link via a
web-browser.

Sample model
The model used in the figures on this page is the Calculator sample model that comes with
MagicDraw.
• Download Calculator.mdzip55.
directory>\samples\simulation\Calculator.mdzip.
Related page
Generating an HTML table from a UI table, Time series chart, and CSV export
configuration
On this page
• Generating an HTML table from a UI table(see page 156)

• Generating an HTML table from a Time series chart and CSV export configuration(see page 164)
Generating an HTML table from a UI table

This feature of Cameo Simulation Toolkit enables you to export MagicDraw HTML tables in UI modeling
diagrams to HTML5, allowing them to be viewed in a web browser. The sample model used on this
page, SpacecraftMassRollup56, demonstrates how to create a User Interface table in the User Interface
Modeling diagram, generate HTML, run the simulation, and view the UI table in HTML5 in your web
browser. You can download SpacecraftMassRollup57 at the end of this page.
To generate an HTML table from a UI table component
1. Open SpacecraftMassRollup58 from the MagicDraw installation file: folder\samples\simulation.

2. Right-click the Model element in the containment tree. Select Create Diagram > Other
Diagrams > User Interface Modeling Diagram.
3. Drag a UI table component onto the newly created diagram.

4. Drag the spacecraft Block from the Structure Package in the Containment tree to the table.
5. Select Create UI Prototype. The table headers will change from Column 1 and Column
2 to Name and Value.
 Tip
If you drag the spacecraft Block to the table quickly, the column name will change
automatically, without having to select Create UI Prototype.

Selecting the Create UI Prototype menu that appears after dragging the spacecraft Block to the
table.
When you select the Create UI Prototype, the table column names change to Name and Value.
6. Right-click the UI table. Select Specification to bring up its Specification window as shown below.
Note that the Classifier is assigned to the Represents property.

7. Click beside the Value property and select the values you want to monitor from the tree
view in the Select Nested Properties dialog.
8. Click . The selected values will appear in the Value property in the UI table
Specification window.

9. Close the Specification window.
10. Run the spacecraft mass analysis Simulation Configuration. The Console messages will appear.
Running the spacecraft mass analysis Simulation Configuration.

The Console messages appearing in the Simulation Console with the filter Options set to Warn.
11. Note that a simulation web server has started. You can open the Specification window of
Simulation Configuration to see the Start Web Server (true) option.
12. Click the HTTP link, e.g., http://10.1.1.64:8080/ in the Console pane to view the simulation in real-
time in your browser.

 Note
The preferred browser is Google Chrome.
13. You can edit the Documentation/Hyperlink tag from the UI table's Specification window and
run the simulation again. It will show the table's descriptions. See the following two figures

Changing the Documentation/Hyperlinks tag will reflect on the table's descriptions in the browser.
The changes to the Documentation/Hyperlinks tag appearing as the HTML table's description.
14. You can edit the values from the web browser page. The simulation engine will automatically pick
the values up and re-calculate. In addition, verification status of runtime values(see page 243) is
supported and shown that there is constraint failure, which is colored in red.
Generating an HTML table from a Time series chart and CSV export
configuration
An HTML table can also be generated from a Time series chart and CSV export configuration.
To generate an HTML table from either a Time series chart or a CSV export configuration
1. Right-click a Time Series Chart or a CSV Export configuration and choose Tools > Generate
HTML Table.

2. This will generate an HTML file, which can be viewed either online or offline. A message stating,
"INFO: HTML table(s) is/are generated to the C:\Users\Downloads\CoffeeMachine_test1 folder, "
in the Console pane will appear in the Simulation Console pane.
Sample model
The model used in the figures on this page is the SpacecraftMassRollup sample model that comes
with your modeling tool.
• Download SpacecraftMassRollup.mdzip59.
directory>\samples\simulation\SpacecraftMassRollup.mdzip.
Control panel for Web UI

The simulation control panel for Web UI allows you to control a simulation directly from the Web UI
using the Start, Pause/Resume, Step Into, Step Over, and Terminate buttons when no simulation
window is used. These four buttons have the same functionality as those of the buttons on the

simulation toolbar. You can move the toolbar on the browser as desired. The following figure shows the
web UI Mockup of the Calculator sample model
The Web UI control panel with the restart function.

The Add Control Panel option in the Specification window of the <<Simulation Config>>(see page 49)
allows you to enable these buttons on the Web UI.
To enable the control panel buttons on the Web UI
1. Double-click the <<SimulationConfig>> on the diagram pane to open its Specification window.
2. Select the Add Control Panel check box under the Web Server option. The value will change to
true and the addControlPanel stereotype will be added in the <<SimulationConfig>>.

Enabling the Add Control Panel option in the Specification window of
<<SimulationConfig>>.
You can start and stop the Web Server using the Start/Stop Web Server button on the simulation
Console pane.
The Start/Stop Web Server button on the simulation Console pane.
Sample model
The model used in the figures on this page is the Calculator sample model that comes with
MagicDraw.
• Download Calculator.mdzip60.

directory>\samples\simulation\Calculator.mdzip.
Image switching in web user interface
ImageSwitcher can also be displayed on the web UI for most common image file formats (jpg, tif, png,
and gif) along with the standard UI modeling diagram. You must select the Generate HTML menu from
either the context menu (right-click) of each ImageSwitcher element or from the toolbar of UI diagram.
The Simulation Console pane will then display the following message: INFO: HTML file(s) is/are
generated to <projectName> folder.
The Generate HTML context menu of ImageSwitcher.

The Generate HTML button on the UI diagram toolbar.
The Start Web Server property option(see page 152) in the Specification window of <<Simulation Config>>
must be selected true. Otherwise, the Web Server cannot start, and you cannot use the web UI at all.
You can click the URL, e.g., http://10.1.1.64:8080/, on the simulation Console pane during simulation to
open the web UI.
Related page
Plotting on the web user interface
Additionally, you can deploy the Time series chart along with the standard UI modeling diagram on the
Web user interface. This web UI capability is enabled by selecting the menu Generate HTML from
either the context menu (right-click) of each Time series chart element or the toolbar of the UI diagram.

The Generate HTML context menu of Time series Chart.
The Generate HTML button on the UI diagram toolbar.

Once the Generate HTML menu has been selected, the following message: INFO: HTML file(s) is/are
generated to <projectName> folder will appear on the Simulation Console pane.
To plot on the web-based UI
1. Click on the UI diagram toolbar.

2. Double-click <<SimulationConfig>> to open its Specification window.
3. Select the Start Web Server property check box (true) to start the Web Server.
4. Run the simulation.
5. Click the URL, e.g., http://10.1.1.64:8080/, that appears on the Simulation Console pane when the
model simulation is running. The web UI will open in your web browser.
The chart that appears on the web UI is the same chart that represents the values of the simulation UI.
If the values on the chart simulation UI change, the corresponding chart will change accordingly. The
layout of the Time series chart is auto-aligned with the chart properties of the runtime UI, e.g., Title,
fixedRange, gridX, gridY, and plotColor.

The Time series Chart on the Web UI representing the values that correspond to
those of the chart in the simulation UI.
Related pages

Integrating custom HTML widgets
On this page
• Using the HTML widgets model library(see page 172)

• Integrating HTML widgets in projects(see page 174)
• Widgets in nested Parts supported(see page 178)
• Widgets in UI mockups on a web UI(see page 178)
Simulation supports the integration of custom HTML widgets through the build-in model library named
UI Widgets Library.mdzip. You can see its usage in WebUIWidgets in Samples on the Welcome
screen under Simulation.

For further technical details, please see also the tutorial for integrating widgets for simulation(see page
677).
 Note
HTML widgets work with most web browsers such as Google Chrome, Microsoft Edge
(Chromium), Mozilla Firefox, and Opera. However, if you use older versions of Internet
Explorer, e.g., IE 11, you must set the document mode to 11 by doing the following:
1. Open Internet Explorer.
2. Press F12. Go to the Emulation menu.
3. Under the Mode group, select the Document mode list and choose 11.
Using the HTML widgets model library

To use the HTML widgets model library
1. From the main menu, click File > Use Project > Use Local Project. The Use Project dialog
opens.
2. In the Use Project dialog, do the following:
• Click the From predefined location option.
• Choose <install.root>\modelLibraries.
• Select UI Widgets Library.mdzip.

3. Click Next. UI Widgets Library will be shown as the shared Package.
4. Click Finish. A question dialog about auxiliary resources will appear.
5. Click Yes. UI Widgets Library.mdzip will be shown in the Containment tree. There are build-in
widgets in the Package, e.g., JQueryKnob, LED, and KumaGuage. Those widgets are ready to be
customized and used as user interfaces.

 Note
• HTML widgets are self-containing, owned properties (not references to any model
elements except only themselves).
• To further customize «Widget», open the UI Widgets Library.mdzip library and modify,
save, and reattach the zip file of «Widget».
Integrating HTML widgets in projects

You can use widgets only in diagrams that are based on the Composite Structure diagram with the
conditions applied as follows
1. Drag the widget from a UI Widgets Library and drop it into the IBD/Composite Structure
diagram of the simulation context. Then use a Binding Connector to connect between the value
property of the system and Port of the widget with the same Type. The widget can be resized as
needed.

HTML widgets used as Type of Property in the IBD diagram of the simulation context.
2. You can customize properties of any widgets, e.g., changing colors of cursorKnob, through the
following steps:
a. Create an Instance Specification of the widget by right-clicking the widget and selecting
Tools > Create Instance. Then select a Part and Package to save.
b. Open the Specification window of the created Instance Specification. In the left pane of the
window, click Slots and choose either Create Value or Edit Value.
c. Use the modified Instance Specifications as Default Value of the Part properties in the
simulation context, as shown in the following figure.

Customizing values through creating instances of the widget, setting values of properties in Slot of
widgets, and using them as Part properties.
3. When running from a «SimulationConfig», you must set the executionTarget of the
«SimulationConfig» to the simulation context, and the following Events will occur as shown in the
next figure below:
a. «Widget» Parts in the executionTarget, found at any Package levels, will be automatically
generated as HTML files. All generated HTML files will be stored in the project's working
directory with the same name as the project.
b. The Web Server will automatically start.
 Note
If the Web Server plugin is not installed, a warning message with a link to install
the plugin will be printed in the Console panel. Widgets on the IBD will not work
until the plugin has been installed.
c. The Console pane will print all generated HTML files, the generated folder, and URL of the
Web UI with links.
Running simulation with HTML widgets from a «SimulationConfig».

4. You can also run the simulation directly from the IBD/Composite Structure diagram that contains
widgets either from the right-click menu of the diagram or the Containment tree, or the
Simulation toolbar of the diagram. Then the simulation will automatically generate HTML files,
and the Web Server will be automatically started, similar to Step 3.
5. Depending on the circumstances, you can manually regenerate HTML files for further
customization of the web UI. Manually regenerating HTML files is possible by right-clicking a
«SimulationConfig» and selecting Simulation > Generate HTML.

Manually regenerating HTML files through the Generate HTML command for HTML widgets.
 Note
• The Generate HTML command is available only when there is «Widget» as Part
(either Class or Block) in the executionTarget of a «SimulationConfig».
• If HTTP ERROR 404 ... occurs in the IBD/Composite Structure diagram, you must
use the Generate HTML command. This is because the error from HTML files is
not generated, but the startWebServer of the «SimulationConfig» is false.
6. However, if the HTML files already exist, a question dialog will be shown to prevent you from
accidentally overwriting them as shown in the figure below.
The question dialog to prevent accidentally overwriting the HTML file.

You can select one of the following buttons for a proper action:
• Yes: overwrite the existing <widget>.html file.
• Yes To All: overwrite all <widget>.html files.
• No: keep the existing <widget>.html file.

• No To All: keep all existing <widget>.html files.
 Note
The <project>_index.html file is always regenerated at the end of the process.
Widgets in nested Parts supported

You can use widgets in nested Parts. Simulation uses the name (or the element ID if the name does not
exist) of the property to construct the full path name for each generated HTML file name, e.g., a nested
widget, ld-m1:LED, of Monitor is generated m1_ld-m1.html, m2_ld-m1.html, and <Element ID>_ld-
m1.html.
Widgets in nested Parts and generated HTML file names.
 Note
When using widgets, you must define your Parts with distinctive names to shorten generated
widget file names that cannot normally be longer than 255 characters as limited by operating
systems.
Widgets in UI mockups on a web UI

You can reuse web UI widgets in UI mockups on a web UI when running a SimulationConfig(see page 49)
with startWebServer = true and UI = «Frame» «UI» hosted widgets.
To reuse web UI widgets in UI mockups
1. Create an IBD and connect the Ports of the widgets with value properties to work with runtime
values.
2. Drag a property typed widget to a «Frame» «UI». Simulation will automatically set the config
according to the feature. Image of the widget will automatically be shown, and «NestedUIConfig»
will be automatically set. You can use either a group box (by default) or panel as a place holder
shown below.

Web UI widgets in «Frame» «UI» mockups with the config and feature settings.
3. Run a SimulationConfig with startWebServer = true and UI = «Frame» «UI» hosted widgets. Then,
HTML files of the widgets will be generated, and the web server will be automatically started. You
must click the URL in the Console pane (INFO: Click <URL> to open web UI) and select either
Embedded Brower or Web Browser to show the web UI as shown below.
Widgets in UI mockups on a web UI through the Chrome browser.

Animation
Active elements on a diagram will be annotated during simulation using the same annotation
mechanism used in the active validation:
• Active and visited elements will be annotated in red and green respectively.
• Runtime values will be visible in the tooltip of annotated elements.
• Values flown through pins of action will be visible in the tooltip of annotated actions.
• Duration of called Activities will be visible in the tooltip of annotated call Behavior Actions if you
simulate the Activity with a specific duration mode.
 Note
If you select true as the value of the silent tag in the Simulation Configurations, Cameo
Simulation Toolkit will not animate simulation and will simulate models in silent mode (see
Simulation Configuration and UI modeling(see page 46) for more information).
Related pages
Active, visited, and last visited elements
On this page
• Animation of value propagation in the Internal Block diagram(see page 181)
Active Elements are the Elements a simulation session is focusing on (see Understanding simulation
sessions(see page 197) for more information). They can also be considered as the Elements that are
currently being simulated in a simulation session. They will be annotated in red by default. Once an
active Element has been simulated, it will become a visited Element and will be annotated in green by
default. The last visited element will be annotated in orange.

Element animation: active Element is red, last visited Element is orange, and
visited Elements are green.
Animation of value propagation in the Internal Block diagram

Animation of Ports and Connectors in the Internal Block diagram (IBD) when value flows through them
is annotated from activating the source part first, and then the Port, Connector, target Port, and target
part, as shown in the figure below. Those Ports include regular Ports, flow Ports, and proxy Ports with
flow properties. However, initialization will be at full speed and optimized without animation or delays.
The value will also be shown as an annotation during the animation.
Animation of value propagation in the Internal Block diagram.

Related page

Customizing animation
There are four kinds of annotated elements in a model simulation: (i) Active, (ii) Visited, (iii) Breakpoint,
and (iv) Last Visited elements. By default, active elements will be annotated with red, visited elements
with green, last visited elements with orange, and breakpoints with yellow. Cameo Simulation Toolkit
allows you to customize the colors of these annotated elements through the Project Options(see page 47)
dialog in the Animation group.
The Auto Open Diagrams option in the Project Options(see page 47) dialog and Simulation window
allows Cameo Simulation Toolkit to open a tab where you can see a diagram that contains a currently
active Element in a non-silent simulation (animation is enabled). If you want to enable this option, you
need to select true as its value. This is useful when you want to track the simulation current status.
Select false as the value of Auto Open Diagrams when you would like to focus on just one diagram
and avoid automatic switching or opening of diagrams.
If the value of Auto Open Diagrams is false and you run a silent-mode simulation of an activity
diagram that has a decision node without any decision input, Cameo Simulation Toolkit will open the
diagram and highlight all elements including the decision node and open a Question dialog to ask for a
decision when the simulation reaches the decision node. However, if the value of Auto Open Diagrams
is false, and you are running a non-silent simulation, Cameo Simulation Toolkit will open the diagram
and highlight only the decision node.
 Note
The default value of Auto Open Diagrams is false.
To select the Auto Open Diagrams option in the Simulation window
• Click the Auto Open Diagrams toggle button in the Simulation window as follows
 Information

When animation with selected Auto Open Diagrams is used, it must open animated diagrams
in the same tab and must not open new diagram windows as new tabs. If a diagram is already
open in a tab other than the active tab, the other tab will close, and the diagram animation will
be shown in the active tab.
Related page
Animation speed option

Animation Speed in the Simulation Configuration is the speed to run a particular Configuration
animation. The default value of Animation Speed is 95%. You can adjust it to avoid problems with delay
when the default speed is slow and large numbers of model elements are running. To run your
animation at a pace that is faster or slower than the default animation speed, change the value of the
Animation Speed option to your preferred one in the Specification window of the
<<SimulationConfig>>.

Animation Speed option in <<SimulationConfig>> is specified at the default value
of 95%.
 Note
Animation Speed will not affect animation in the Parametric diagram since no animation is
delayed during parametric solving.
The Animation Speed setting is visible through diagram animation. For example, if the speed is
specified at the value of 50%, the animation must be slower than the default value 95%. The speed
setting is consistent with the Simulation speed bar control; e.g., if the animation speed is specified at
50%, the speed bar is set to the middle as shown in the following figure
The animation speed selected is consistent with the Animation speed bar.
 Note
The speed of the animation does not affect the animation in the Parametric diagram as no
animation is delayed during parametric solving.
Opening a diagram of an executing behavior

When you simulate a model, the Sessions pane will open to display simulation of each element in the
model. During the simulation, if you ever need to see what diagram a Behavior being simulated has,
you can double-click the session in the Sessions pane of the Simulation window. The following figure
shows the Sessions pane when Cameo Simulation Toolkit is executing the Blackjack sample
(Blackjack.mdzip). If you double-click the Behaviors outlined in red, a new tab will open to display the
corresponding diagram.

The Sessions tab of the Simulation window.
Simulation information in diagrams
When simulating a model, you can display and manipulate simulation information in diagrams a similar
way you do it in the Simulation window. For example, you can see and edit runtime values directly on
Part shapes or send a trigger and see a flowing item with its name on a path.
In diagrams, the following simulation information can be displayed:
• Active state of the represented element(see page 187)

• Active state image(see page 188)
• Runtime values on Part shapes(see page 190)
• Flowing information on paths(see page 191)
In addition, you can manipulate simulation information the following way:
• Enter or change runtime values(see page 195)

• Send a trigger(see page 0)
 Types of diagrams
You can display and manipulate simulation information only in diagrams that are based on a
Composite Structure Diagram. However, the flowing information on paths can be displayed
both in diagrams based on a Composite Structure Diagram and an Activity Diagram.

This sample model simulation demonstrates how you can use diagrams to view
and manipulate the same simulation information as in the Simulation window.
Related pages
• Displaying simulation information(see page 186)

• Manipulating simulation information(see page 194)
Displaying simulation information
On this page

• Displaying active States(see page 187)
• Displaying active State images(see page 188)
• Displaying runtime values(see page 190)
• Displaying flowing information(see page 191)
• Disabling and enabling animation options(see page 192)
When simulating a model, you can choose to display simulation information not only in the Simulation
window but in diagrams as well. For example, you can see runtime values directly on Part shapes or a
flowing item with its name on a path.
 Types of diagrams
You can display simulation information only in diagrams that are based on a Composite
Structure Diagram. However, the flowing information on paths can also be shown in an Activity
Diagram.
Displaying active States

In diagrams, active States can be displayed on the shapes of all initialized Parts a similar way they are
displayed on the Variables pane of the Simulation window (in square brackets).
 Exception
Active States are not displayed for Parts with the multiplicity of more than one.

The diagram illustrates how active States are displayed on Part shapes.
If you do not want to see active States in diagrams during simulation, you can disable the Show Active
States on Part Shapes animation option. For more information, see Disabling and enabling animation
options(see page 192).
Displaying active State images

You can display active State images on Part shapes by applying an image to a State or by assigning an
Image Switcher to the Simulation Configuration from which you execute your model. When States
change during simulation, State images change as well.
 Important
If you specify State images both by applying them to States and assigning an Image Switcher to
the Simulation Configuration, the images of the Image Switcher will be used when running the
Simulation Configuration.
To display active State images when executing a model
1. Open the Specification window of the State you want to create an image for.
2. Click the specification cell of the Image property and select the image you want to use for a
specific State. Click to select an image from the default image library, click to select an
image from your file system, or click to specify an image URL.

Here you can see how active State images are displayed when simulating a model.
If you run a Simulation Configuration, use an Image Switcher to display active State images as described
below.
To display active State images when running a Simulation Configuration
1. Open the Simulation Configuration Diagram in which the Simulation Configuration is displayed
and create an Image Switcher.
2. In the Specification window of the Image Switcher, click the Represents property specification
cell and select the element for the states of which you want to create images.
3. For every active State image you want to create, create an Active Image element as the attribute
of the Image Switcher.
 Creating Active Image attributes

To create an Active Image attribute for an Image Switcher, click Active Image in the
diagram palette, then click the Image Switcher shape.
4. In the Specification window of every Active Image specify the following properties:
• Image property - select the image you want to use for a specific State. Click to select an
image from the default image library, click to select an image from your file system, or
click to specify an image URL.

• Active Element property - select the State which the Active Image represents.
5. Drag the Image Switcher created in step 1 to the Simulation Configuration shape. This way the
Image Switcher is specified as the value of the UI property of the Simulation Configuration.
Displaying runtime values

In diagrams, you can display the runtime values of Part properties the same way they are displayed in
the Variables pane of the Simulation window. Runtime values are displayed next to property names on
Part shapes instead of the default property values. Note that when you run a simulation, property types
are not displayed.
Runtime values can be displayed only for the following types of properties:
• Primitive
• ValueType
• Enumeration
• Custom DataType
 Automated Requirement verification

Runtime values on Part shapes are highlighted in green (the Requirement is
satisfied) or red (the Requirement is not satisfied) when the automated Requirement
verification is performed.
In addition, a tooltip with the text of unsatisfied Requirements or constraints appears when you
hover the mouse pointer over Part or Value Property shapes.

In this diagram, you can see how runtime values are displayed on Part shapes during model simulation.
 Resizing shapes to fit runtime values

If a runtime value does not fit in a shape and is cut off, resize the shape as described below.
1. Select the shape that you want to resize.
2. Do one of the following:
a. Click the Resize to Fit Runtime Values icon on the shape (displayed below).
b. Click in the diagram toolbar.
In addition, you can modify runtime values(see page 195) directly in diagrams and change simulation
results in real-time. If you do not want to see runtime values in diagrams during simulation, you can
disable the Show Runtime Values on Part Shapes animation option. For more information,
see Disabling and enabling animation options(see page 192).
Displaying flowing information

You can choose to display flowing information on animated paths when executing a model. In diagrams
based on a Composite Structure Diagram, the flowing item is displayed as a moving triangle with a label
showing the item name (see the image below). In Activity Diagrams, the flowing item is displayed as a
bubble.

In this Internal Block Definition Diagram, you can see the neutral signal flowing from the GearShift to the
TCU.
You can also send a trigger(see page 0) directly from a Part shape in a diagram and see the flowing item
on a path. If you do not want to see flowing information in diagrams during simulation, you can disable
the Show Flowing Information animation option. For more information, see Disabling and enabling
animation options(see page 192).
Disabling and enabling animation options

You can disable or enable animation options, such as displaying active States and runtime values on
Part shapes. The steps below explain how to change option values for the whole project and a specific
Simulation Configuration. Note that by default all simulation animation options are enabled.
To disable or enable animation options for a project
1. In the main menu, go to Options > Project.

2. On the left side of the Project Options dialog, expand the General option group and
select Simulation.

3. In the option specification area on the right side of the dialog, disable or enable the following
animation options:
• Show Active States on Part Shapes - if the option set to true, active States are displayed
on Part shapes. Set the option to false to disable it.
• Show Runtime Values on Part Shapes - if the option set to true, runtime values are
displayed on Part shapes. Set the option to false to disable it.
• Show Flowing Information - if the option set to true, the label of a flowing item is shown
on paths. If the option is set to false, paths are only highlighted when an item is flowing.
• Show Active State Images on Part Shapes - if the option set to true, active State images
are displayed on Part shapes.
4. Click OK to save the changes.
To disable or enable animation options for a Simulation Configuration
1. Open the Specification window of a Simulation Configuration element.

2. Disable or enable the following animation options located in the Animation category:
• Show Active States on Part Shapes - if the option set to true, active States are displayed
on Part Property shapes. Set the option to false to disable it.
• Show Active State Images - Select On Part shapes to show active State images on Part
shapes. Select In the Simulation UI to show active State images in the simulation UI
dialog. To show images both on Part shapes and in the simulation UI dialog, select Both.
• Show Runtime Values on Part Shapes - if the option set to true, runtime values are
displayed on Part shapes. Set the option to false to disable it.
• Show Flowing Information - if the option set to true, the label of a flowing item is shown
on paths. If the option is set to false, paths are only highlighted when an item is flowing.
3. Close the Specification window.
Manipulating simulation information
On this page
• Changing runtime values(see page 195)

• Sending a signal(see page 196)

When simulating a model, you can manipulate simulation information not only in the Simulation
window but in diagrams as well. For example, you can change runtime values or send a trigger directly
on Part shapes.
 Types of diagrams
You can manipulate simulation information only in diagrams that are based on a Composite
Structure Diagram.
Changing runtime values

You can change the runtime values of Part properties directly in diagrams the same way you change
them in the Variables pane of the Simulation window.
 Prerequisites
In order to display and change runtime values in diagrams, the Show Runtime Values on Part
Shapes animation option must be enabled. For more information, see Disabling and enabling
animation options(see page 192).
To change runtime values on Part shapes
1. During model simulation, select a Part shape and click a runtime value you want to change.
2. Enter a new runtime value and press Enter. The figure below shows how to change different
types of values.

Changing a numeric runtime value.
Changing an enumeration runtime value.
Changing a boolean runtime value.
When you change runtime values of Value Properties as described above, the simulation data is
updated in real-time accordingly.
Sending a signal
When simulating a model, you can send a signal directly from a Part shape in a diagram the same way
you would send it in the Sessions pane of the Simulation window. If it is possible to send a signal, a
special button is displayed on a Part shape after selecting it.
To send a signal from a Part shape
1. During model simulation, select the shape of the Part from which you want to send a signal.
2. Click the signal icon next to the part shape as displayed below. If you can send more than one
signal, the icons of all available signals are displayed.

Simulation debugging
This section presents an overview of simulation sessions, debugging process, components of

simulation console and log files, monitoring runtime values, updating default values from an Instance
Specification, adding and removing breakpoints, and the settings for automatic updates during
simulation sessions in the Simulation pane.
Related pages
Understanding simulation sessions
Cameo Simulation Toolkit creates a simulation session(s) while a model is being simulated. A simulation
session contains a context with a specified runtime value. The context of the simulation session is the
executing UML element that can be either a Class element or a sub-type of a Class. When the context
element is simulated, a runtime object will be created to store the simulated values.
You can create multiple simulation sessions during a single simulation, such as an Activity simulation. If
the simulated Activity contains any callBehaviorAction, a new simulation session will be created to
simulate each callBehaviorAction. The Sessions pane will display all simulation sessions during
simulation and order them by context elements in a tree node, as shown below.

The Simulation Sessions pane.
You can open the Simulation clock(see page 61) dialog to see the simulation clock in real time by right-
clicking any context elements in the Simulation Sessions pane and selecting Show Simulation Clock.
While executing a model, you can double-click a running session to open a diagram of that particular
session containing the progress of the simulation as shown below.

Double-clicking a running session to show the diagram at runtime.
Related page
Debug process simulation
Cameo Simulation Toolkit allows you to control a model simulation using the debug buttons such
as Suspend, Resume, Step into, and Step over. The table below explains the functions of all of the
debug buttons.

Bu Name Shortc Function
tto ut key
n
Start F8 To start simulating an object of the initialized session shown in

Simulatio the Sessions pane.
n
Restart F8 To restart the last simulated element.
Suspend F8 To pause a running simulation session in the Sessions.
Resume F8 To resume a simulation session.
Step into F5 To simulate and animate a currently active element in a selected simulation
session in the Sessions pane.
Step over F6 To simulate a currently active element in a selected simulation session and run
animation in the background.
Terminate None To stop a session in the Sessions pane. If the selected session contains sub-
sessions, all of the sub-sessions will also be terminated.
You can examine and edit variables in the Variables pane (see Variables Pane(see page 209)), pause the a
model simulation at predefined breakpoints (see Breakpoints(see page 250)), or simulate one element at a
time using the Step into or Step over button.
The Debugger pane includes a player-like control panel for a step-by-step simulation (see the table
above), threads or Behaviors with an expandable stack trace (see Understanding simulation
sessions(see page 197)), input/output console for custom commands or expressions evaluation (see
Simulation console(see page 200)), Variables pane/runtime structure (see Runtime Value Monitoring(see
page 206)), and Breakpoints pane.
Related pages
• Variables pane(see page 209)

• Breakpoints(see page 250)
• Runtime Value Monitoring(see page 206)
Simulation console
This chapter explains the fundamental concept and functions of buttons in the Simulation Console
pane and its displayed levels of information, log files as records of all simulation details displayed in the
Console pane during simulation, log's filter options, and constraint failures shown in the Console pane.
Related pages

Console pane
Cameo Simulation Toolkit provides the Simulation Console pane in the Simulation window.
The Console pane displays simulation information during a model simulation including the date and
time the simulation engine starts and the date and time the simulation runs and stops.
Runtime information of Cameo Simulation Toolkit.

The Console pane may contain a hyperlink to a model element in a MagicDraw project. During a model
simulation, scripts evaluation failures may happen and thus expression evaluation errors occur. If
Cameo Simulation Toolkit cannot evaluate some scripts in an element, it will create a hyperlink in
the Console pane to that element in the Containment tree. When you click the link, Cameo Simulation
Toolkit will highlight the element in the Containment tree.
The following figure shows a hyperlink resulting from errors in evaluating scripts in the Console pane.
The link points to the corresponding element in the Containment tree.

A hyperlink to the Element whose scripts cannot be simulated.
The table below shows the function of each button in the Console pane
B Name Function
u
tt
o
n
Clear Console To remove all simulation information displayed in the Console pane.
Show Runtime To display the runtime information of the Cameo Simulation Toolkit in
Information the Console pane.
The runtime information consists of the Cameo Simulation Toolkit version, registered
simulation engines, and available scripting engines.

B Name Function
u
tt
o
n
Options To filter outputs in the Console pane. There are four filter options: Debug, Info, Warn,
and Error (See Console Log's Filter Options(see page 205)
for more details.).
The following figure shows the simulation Console
The Simulation console.
Related page
• Console log's filter options(see page 205)
Simulation information
The Console pane can display four levels of information (sorted in ascending order by priority) as
follows

Option Description
DEBUG Displays debugging information.
INFO Displays normal information.
WARN Displays warnings.
ERROR Displays errors.

By default, only information with a priority equivalent to INFO or higher (WARN and ERROR) will be
displayed in the Console pane. You can customize the way information is displayed by editing
the simulation.properties file in the data directory in the MagicDraw installation directory. You can use a
text editor to edit this file.
To change the priority level, e.g., open log4j.category.SIM_CONSOLE.
log4j.category.SIM_CONSOLE=INFO,SimConsoleApp,SimXMLApp
Change the first parameter's priority level from INFO (default value) to DEBUG to display all levels of
simulation information in the Console tab.
log4j.category.SIM_CONSOLE=DEBUG,SimConsoleApp,SimXMLApp
You can see more information about customizing the information displayed in the Console pane from
the comment in the simulation.properties file.
Related page
• Console pane(see page 201)
Simulation log file
When Cameo Simulation Toolkit is executing a model, the Console pane in the Simulation window will
show you the simulation details. However, the Console pane is limited to display only 60,000 characters
owing to the performance constraints. The characters that exceed the maximum character limit will not
be displayed. Nevertheless, your old simulation information will be automatically archived in
the simulation.log file in the Configuration file directory, as follows
• Windows Vista / 7 / 8 / 10: C:/Users/<USERNAME>/AppData/Local/.magicdraw/<md.version.number>

• Windows XP / 2000: C:/Documents and Settings/<USERNAME>/Local Settings/
ApplicationData/.magicdraw/<md.version.number>
• Windows NT4: C:/WINNT/Profiles/<USERNAME>/Local Settings/Application Data/.magicdraw/
<md.version.number>
• Other OSs: <user.home>/.magicdraw/<md.version.number>

The simulation.log file is an XML file (or a text file) that records all simulation details that have ever been
displayed in the Console pane during model simulation (see the comment in
the simulation.properties file to customize the file).
Related page
Console log's filter options
When running a model, Cameo Simulation Toolkit always shows a log list in the Console pane that
records each and every element that is being simulated such as the start and end elements. If you want
to narrow down the log lists to display only specific messages, e.g., errors or warning messages, you
can use the Options button in the Console pane.
The Console's Options button.

The Options button on the Console pane contains four options to filter log reports as follows
Opti Description
on
Debu Debug, by default, shows all messages.

g
Info This option only shows information with a priority equivalent to INFO or higher (WARN and ERROR).
Warn This is the default filter option. It only shows information with a priority equivalent to WARN or higher
(ERROR).
Error This option only displays information with a priority equivalent to ERROR.

 Note
• By default, the user print output, the start time, the end time, and the duration of the
main Behavior simulation will always be printed.
• Duration Analysis information will be printed in the Debug filter option.
Related page
Printing constraint failures in the console
Most of model simulations involve with evaluating values that are in the model. Evaluation will fail if the
model cannot satisfy any of the constraints. Cameo Simulation Toolkit acknowledges this kind of failure
as a constraint failure and thus will print the error message in the Console pane. The message will
inform you about the unsatisfied constraint(s) including hyperlinks that help you navigate the failed
requirements and constraint(s), and the diagram where the simulation stopped.
The following figure shows an example of constraint failures printed on the Console pane
Printing constraint failures in the Console pane.

Related page
Runtime Value Monitoring

The topic describes about creating runtime objects and value in the Variables pane from Classifiers and
Instance Specifications including automatic initialization, exporting runtime objects to
InstanceSpecifications, and the Times series chart. This section also discusses about carrying values
using connectors, checking values against feature types, and verification status of runtime values to be
recorded.
Related pages
Context, runtime object, and runtime value
On this page
• Context(see page 207)

• Runtime object(see page 207)
• Runtime value(see page 207)
When you are executing a model simulation, Cameo Simulation Toolkit creates the context, runtime
objects, and runtime values to store the simulated values of the model.
Context
A simulation session is always associated with its context of simulation. The context of a simulation
session is a Class or one of its subtypes. When a context element is simulated, a runtime object (of the
context's type) will be created to store the runtime values. In the following figure, the context of the
selected simulation session is the Calculator class.
Runtime object
A runtime object is the simulated value of a Class. In other words, it is a runtime instance of a Class and
of the context as well. In the following figure, the runtime object of the simulation session context is the
"Calculator@6e46ab00" instance. Since the runtime instance is the "Calculator" Class type, it can
contain structural features (which correspond to the Class attributes), such as "display" and
"operand1".
Runtime value
A runtime value refers to the value of the structural features mentioned in the Runtime object section,
e.g., "200" and "120". However, if the type of a structural feature is a Classifier, its runtime value can
also refer to another runtime object of a structural feature type.

The Simulation console showing the context "Class, the runtime object of the simulation session
context "Calculator@6e46ab00", and the runtime values of "120" and "200".
Glossary
Class
Class is a Classifier that describes a set of objects that share the same features, constraints, and
semantics (meaning). A class is the most widely used Classifier. It is shown as a solid-outline
rectangle containing the Class name and with optional compartments separated by horizontal lines
containing features or other members of the Classifier.
Classifier
Classifier is a category of UML elements that have some common features, e.g., attributes and
methods. It describes a set of instances that have common behavioral and structural features
(operations and attributes respectively).
Element
Element is the abstract root UML metaclass, it has no superclass in the hierarchy of UML elements.
It is the superclass for all metaclasses in the UML infrastructure library.
Instance
Instance is a system's entity; it is a concrete manifestation (implementation) of an abstraction.

Abstraction could be represented by one or more Classifiers or no Classifiers at all. When an
instance manifests a Classifier, it is called instance of that Classifier. For example, Object is an
instance of a Class, while the link is an instance of an association. An instance could have a name or
be anonymous when the name is not important. The instance name allows you to distinguish it from
the other instances within the same naming context (scope).

Object
Object is an instance of a Class. It is an individual (thing) with a State and relationships to other
objects. The State of an object identifies the values for that object of properties of the Classifier of
the object.
Structural feature
Structural feature is a typed feature of a Classifier that specifies the structure of instances of the
classifier. It specifies that instances of the featuring classifier have a slot whose value or values are
of a specified type.
Sample model
Related pages
To learn more about working with context, runtime objects, and runtime values, you can visit the
following pages
• Creating values and objects in the variables pane(see page 220)

• Creating runtime objects from Classifiers(see page 222)
• Creating runtime objects from Instance Specifications(see page 224)
• Automatic initialization of context and runtime objects(see page 227)
• Exporting runtime objects to InstanceSpecifications(see page 237)
• Recording Verification status of runtime values(see page 243)
Variables pane

The Variables pane displays the structure of a model being executed and runtime values during model
simulation. This pane contains two major columns: Name and Value:
• Name: represents the context and structural features of a model being simulated. The [] and {}
notations are automatically shown after the structural feature as follows:
• []: the current State and number of Events of a State Machine and multiplicities.
• {}: constraint expressions with parameters and subsets.
• Value: represents runtime values of structural features from the Name column. A runtime value
can be the input or output of simulation. You can directly edit runtime values in the Value
column if they are Boolean, Integer, Real, and String.
The Variables pane of a simulation model session.

You can also display Causality, Show Requirement, and Show Margin columns and configure the
filtering by clicking the button at the top-right corner. Also, you can select a session in the
Sessions pane(see page 197) to display its runtime objects and values that will be shown in the Variables
pane accordingly.
The following table lists the toolbar buttons and options of the Variables pane
Bu Name Function
tto
n
Refresh To refresh the tree and values in the Variables pane.
Export to New To create a new InstanceSpecification and export a selected runtime object to a
Instance newly created Instance Specification.

Bu Name Function
tto
n
Export to Instance To export a selected runtime object to an InstanceSpecification, which is used to

create the runtime object, or to an existing InstanceSpecification (see Exporting
Runtime Objects to InstanceSpecifications(see page 237)). All of the slot values of
the InstanceSpecification will be replaced by the runtime values of the runtime
object.
Options: To allow displaying and filtering elements in the Variables pane. Each option will
be available only when the simulating model contains such kind of element to be
filtered.
• Causality To show the Causality column. The value of a property represents the result of
evaluating a mathematical equation(see page 421): None, Given, and Target. You
can change the causality of the property using the symbolic math toolbox if the
parametric evaluator, e.g., MATLAB, supports solving symbolic expressions.
• Show To display the simulation time near the Options button. The value can be paused
Simulation when clicking the Pause button and disappear when clicking the Stop the
Time simulation button.
• Show To display the Requirement column. The value is shown only for properties that
Requirement have Satisfy Relations with the Requirements in req IDs (req text format).
• Show Margin To display the Margin column. The value is calculated from value properties and
the Requirement boundary with a Satisfy Relation.
• Show Derived To display derived unions.

Unions
• Show To display redefined properties.

Redefined
Properties
• Show To display reference properties.

Reference
Properties
• Show Adjunct To display SysML adjunct properties.

Properties
• Show To display SysML constraint properties.

Constraint
Properties
• Show Ports To display Ports.

The options for displaying and filtering elements in the Variables pane.
The result of selecting the Show Simulation Time, Show Requirement, and Show
Margin options of the Variables pane.
Related page
• Exporting runtime objects to InstanceSpecifications(see page 237)

Watch pane
On this page
• Adding Watch items to the Watch pane(see page 214)

• Through the Variables pane(see page 214)
• Through the Console pane(see page 215)
• Through the Watch pane(see page 215)
• Using SelectPropertiesConfig(see page 216)
• Editing and removing Watch items(see page 217)
With the Watch pane, you can easily monitor selected properties and their expressions with runtime
values while debugging. The Watch pane displays a flat list of selected runtime values during model
simulation.
The Watch pane with expressions and their selected runtime values during
model simulation.
The Watch pane automatically shows all Watch actions. Also, you can manually open it by clicking the
Watch button on the Simulation toolbar. This pane contains two columns:
• Name/Expression that can be edited. When you add a Watch item(see page 214), it will be shown
in this column.
• Value that is read-only. When you add a Watch item, its value will be in this column. The Value
column will be highlighted in red or green the same as in the Variables pane. If the added item

cannot be evaluated, the column will display Not found! in Red unless you correct or remove the
selected property.
 Note
• If the Simulation toolbar is locked (in Monte-Carlo and Trade Study simulation), the
Watch pane will be disabled to maximize the performance.
• When adding items at runtime, the value will be evaluated and updated for all property
changes and state changes on each clock tick. However, if you add properties before
runtime, the value will not be evaluated until the simulation runs.
Adding Watch items to the Watch pane

You can add Watch items to the Watch pane via the following:
• Through the Variables pane

• Through the Console pane
• Through the Watch pane
• Using SelectPropertiesConfig
Through the Variables pane

On the Variables pane(see page 209), right-click any property and select Add Watch.
The Add Watch menu via the Variables pane.

Through the Console pane
On the Console pane(see page 201), select properties and expressions as inputs and click the Watch
button . Simulation will automatically save the selected language in the list box.
Adding a Watch action via the Console pane using the Watch button.
Through the Watch pane
Through the Watch pane, add an item manually by either clicking the + symbol in the table or on
the Watch pane toolbar. The + symbol will automatically move to the next row of the table after the
item has been added successfully.

Adding a Watch manually via the Watch pane by clicking the + symbol.
 Note
• You can add a name of a property without using the root object because the context of
the Watch pane is the main root context.
• A name of Type can also be used, if the name of a property does not exist, e.g.,
spacecraft.telecom.ma = 35.
• Multiplicity used will be shown as a flat list of an array of strings, e.g., Trade-
Study.MaxEfficiency.x = [0.4761, 0.4761,…, 0.4237].
• You can specify an index of Multiplicity starting at 1, e.g., Trade-Study.MaxEfficiency.x[1] =
0.4761.
Using SelectPropertiesConfig
You can use a «SelectPropertiesConfig» as the predefined list of properties and add it to a
SimulationConfig(see page 49) by following these steps:
1. Create a Simulation Configuration diagram.

2. Add a «SelectPropertiesConfig» and «SimulationConfig» to the diagram.
3. Set Name, Represents (=object), and Value (=properties) of the «SelectPropertiesConfig».
4. Set Watch Properties (=«SelectPropertiesConfig») of the «SimulationConfig».
 Note
The Watch Properties will be shown in Expert & All view mode.

5. When running the «SimulationConfig», the Watch pane will append the properties populated
from «SelectPropertiesConfig». If some properties already exist, they will not be added to the
Watch pane.
Adding multiple Watch items using the «SelectPropertiesConfig» (with

SimulationConfig.WatchProperties).
Editing and removing Watch items

You can edit and remove any items by selecting the Name/Expression column on the Watch pane.
To edit a Watch item
• Click an item to edit and press ENTER.
To remove Watch item(s), do one of the following
• To remove the selected item, click .
• To remove all items, click . All items will be removed after closing the project.

Clicking the Remove or Remove All button on the Watch pane.
The Time series chart
Cameo Simulation Toolkit allows you to show the plot between runtime values, which are the numerical
value and simulation time. This plot is called Time series chart. To view this chart during a model
simulation, right-click the row of a runtime value in the Variables pane and select Show in time series
chart.

The context menu showing the runtime value in the Time series chart.
The Time series chart shows the runtime value with respect to simulation time shown as follows

The Time series chart of runtime value of Property x.
Related page
Creating values and objects in the variables pane
You can create a new value or object through the shortcut menu Add Value of a property typed by a
primitive type, a Class, or a block in the Variables pane. The shortcut menu will be available only when
the number of existing values or objects of the selected property is less than the upper multiplicity of
the property.

Using the Add Value shortcut menu to add a new value.
If a property is typed by a primitive type (and SysML primitive value types), Cameo Simulation Toolkit
will add a new value, which is a default value of the primitive type, as the value of that property.
If a property is typed by a class or a Block, Cameo Simulation Toolkit will show a list of Classes or Blocks
containing the Class or the Block that types the property and all of its subtypes, which are not abstract
Classes or abstract Blocks. When you select a Class or a Block from the list, Cameo Simulation Toolkit
will initialize an object from that Class or Block and set the object as the value of the property.

Selecting a Class or a Block to initialize an object.
Related page
Creating runtime objects from Classifiers
With Cameo Simulation Toolkit, you can use a Classifier with nested parts as the simulation context
without the need to create Instance Specifications for those nested parts. Cameo Simulation Toolkit will
create runtime objects for those parts automatically. If the type of a property is Data Type, the default
value of the runtime value of that property will also be created, depending on the default value of the
property's type. In addition, if the type of the part contains a specified Classifier Behavior, and the type
itself is set as active, the Behavior will run (the autoStartActiveObjects option in the SimulationConfig
must be set as true).
The first figure shows a Class diagram located in the FlashingLight.mdzip sample, demonstrating
property light, button and timer as parts of the System Class.

Class System and its parts.
You may replace the SimulationTarget of the SimulationConfig named FlashLight with the System Class.
You can see the result of running this SimulationConfig. The result shows that Runtime Objects are
automatically created for the parts of the System Class, and the Behavior of each part also
automatically starts.
Modified SimulationConfig FlashLight.
Sessions and Variables Panes showing runtime objects with a Classifier.

Related page
Creating runtime objects from Instance Specifications
On this page
• Representation of a Runtime object(see page 225)

• Locating Instance Specification in the Containment tree(see page 226)
At the beginning of a model simulation, Cameo Simulation Toolkit will create a runtime object to store
runtime values. If the element to be simulated is an InstanceSpecification or an SimulationConfig whose
SimulationTarget is InstanceSpecification, the runtime values will be generated from the slot values.
These runtime values will later be assigned to the runtime object's structural features that are
equivalent to the defined feature of the slots.
If the slot of the InstanceSpecification is empty, and the defined feature of the slots has a defined
default value, Cameo Simulation Toolkit will generate a runtime value from the default value and assign
it to the structural feature of the runtime object.
The following figure shows the example of a runtime object that is created for executing the pipe
InstanceSpecification. The length slot of the InstanceSpecification contains only one value, which is 1.0.
The runtime value, which is produced for the length structural feature of the runtime object, will equal
this slot value (1.0), while the runtime values of radius and thickness will equal the default values of the
radius and thickness property of the Pipe class (0.05 and 0.002 respectively).

The Variables pane showing the runtime object.
Representation of a Runtime object

The Variables pane in Cameo Simulation Toolkit displays Name and Value information of a runtime
object that you are executing. If a runtime object is created by an Instance Specification, the name of
the Instance Specification will appear in the Value column as shown in the following figure
A representation of the runtime object in the Variables pane.
You can also see a representation of the element's name in tooltip as in the Value column if you point
over the element being activated on the diagram pane.

A representation of element being activated on the tooltip.
You can open a Message dialog that contains the runtime object being activated by clicking the
element and the tooltip icon on the tooltip menu.
A representation of the Element dialog.
Locating Instance Specification in the Containment tree

If you used an Instance Specification to create a runtime object and you want to find that particular
Instance Specification in the Containment tree among the other items, Cameo Simulation Toolkit can
locate and highlight it for you. This is particularly useful if you have a long list of items in the
Containment tree, and it takes some time to locate a specific item. All you need to do is select
the Go To command from the context menu of that runtime object in the Variables pane.
 Note
If a runtime object is not created from an instance specification, the Go To command will be
disabled on the context menu.
To locate and highlight an Instance Specification in the Containment tree through the Variables pane
1. Right-click a runtime object in the Variables pane and select Go To. The name of the Instance
Specification that you used so as to create the runtime object will appear on the submenu.

2. Click the Instance Specification's name. Cameo Simulation Toolkit will locate and highlight it in
the Containment tree.
Related pages
• Instance Specification(see page 38)

• Containment Tree61
Automatic initialization of context and runtime objects
On this page
61 https://docs.nomagic.com/display/MD2021xR2/Containment+Tree

• Context initialization(see page 228)
• Runtime object initialization(see page 231)
Cameo Simulation Toolkit is capable of initializing both context and runtime objects automatically even
if a simulation context does not exist, and no object is configured to initiate the runtime objects.
Context initialization
When executing a Behavior, Cameo Simulation Toolkit allows you to simulate its context as well.
To simulate a Behavior with its context
• Right-click a Behavior or a Behavior's diagram and select Simulation > Run with Context to
execute it together with its context.

To simulate a Behavior without its context
• Right-click a Behavior or a Behavior's diagram and select Simulation > Run to execute it without
its context.

When you simulate a Behavior with its context, Cameo Simulation Toolkit will initialize the context of
the selected Behavior and simulate the Classifier Behavior. During the Classifier Behavior simulation, if
the runtime object of the context Classifier is stable, the selected Behavior will be simulated.
If a selected Behavior has no context, the Run with Context menu will be disabled.

Running a model simulation using the shortcut menu.
Runtime object initialization

When you use an InstanceSpecification to initialize a runtime object, you will also need to use the
corresponding slot values of such InstanceSpecification to initialize the feature values of the runtime
object. Cameo Simulation Toolkit will use the default value of the corresponding feature (property) of
each slot if the slot value is empty.
The value of each feature (property) will be automatically initialized only if its Lower-
value Multiplicity is more than zero or is undefined. Otherwise (the feature's Lower-
value Multiplicity is zero), the feature value will be empty (nothing is initialized). However,

characteristic of the initialization depends on the type of the feature. The following sections explain the
types of feature that can influence initialization characteristics
Structural feature typed by primitive datatype

The default value of a structural feature, which is typed by a primitive datatype, is its initialized
value.This default initialization value, which can be set from Options > Environment >Simulation as
shown in following figure. When true and value property has no default value, the value will be
initialized to 0 value. The default value is false.
The datatypes which are affected by this option are listed in the table as follows
The Simulation Environment Options - Initialize Empty Values to 0.

This initialization value applies to numerical datatypes only. For other types, see the table for
values used for automatic initialization of the Structural Feature typed by primitive datatype as follows.

Primitive DataType (QualifiedName) Value
• UML Standard Profile::UML2 false

Metamodel::PrimitiveTypes::Boolean
• PrimitiveValueTypes::Boolean (SysML
Profile.mdzip)
• UML Standard Profile::MagicDraw
Profile::datatypes::boolean
• UML Standard Profile::UML2 All numerical data types pick up their default initialization
Metamodel::PrimitiveTypes::Integer value from Environment Options as shown in the above
• UML Standard Profile::UML2 figure
Metamodel::PrimitiveTypes::
UnlimitedNatural
• PrimitiveValueTypes::Integer (SysML
Profile.mdzip)
• PrimitiveValueTypes::UnlimitedNatural
(SysML Profile.mdzip)
Profile::datatypes::int
Profile::datatypes::long
Profile::datatypes::short
• UML Standard Profile::UML2 All numerical data types picks up their default initialization
Metamodel::PrimitiveTypes::Real value from the Environment Options as shown in the above
• PrimitiveValueTypes::Real (SysML figure
Profile.mdzip)
Profile::datatypes::double
Profile::datatypes::float
• Enumeration • UML Standard Profile::UML2

Metamodel::PrimitiveTypes::Real
• UML Standard Profile::UML2 "" (Empty String)

Metamodel::PrimitiveTypes::String
• PrimitiveValueTypes::String (SysML
Profile.mdzip)
Structural feature typed by non-datatype

If the type of a structural feature is not a datatype, the conditions are applied as follows
• If the structural feature has a non-empty slot value, it will be initialized with such value.
• Otherwise, if the structural feature's default value is specified, it will be initialized with the default
value.
If the structural feature also has internal feature(s), for each internal feature, the conditions are applied
as follows

• If the internal feature has a non-empty slot value, it will be initialized with such value.
• Otherwise, if the internal feature's default value is specified, it will be initialized with the default
value.
If an internal feature also has its own internal feature(s), the same rule above will be applied
recursively.
Structural feature typed by user-defined eatatype

For a structural feature typed by a user-defined datatype, the conditions are applied as follows
• If the Datatype has internal structural feature(s), the value of the structural feature will be
initialized as described in Structural feature typed by non-datatype(see page 0).
• If the Datatype has no internal structural feature, the following conditions are applied
• The value of the structural feature will be initialized as described in Structural feature
typed by primitive datatype(see page 232) if the Datatype is inherited from a primitive
datatype.
• The initialized value of the structural feature will be its default value if the Datatype is not
inherited from any primitive datatype. If the default value of the feature is, however, not
specified, the initialized value will be empty.
Related pages

• Getting a structural feature value(see page 517)
Carrying values using connectors
A connector can carry a runtime value over from one connectable element to another if the following
three conditions are present
• Datatypes on both elements are the same or compatible (equality of value can be defined), or
one is the subtype of another.
• If the elements are nested features, the owner of the nested features must exist.
• If the elements are nested properties, in this example, b1, a connector must be drawn from a3 to
the port and from the port to b1 because UML does not have a concrete definition about nested
properties. However, SysML does have a definition about nested properties; therefore, the
connector can be drawn between nested properties without the help of any ports.

Using Port and Connector to connect nested properties.
When primitive datatypes, in this example, n and a1, are bound together, the runtime values related to
the role of both connector ends must be equal (but not necessarily the same instance). If the feature
value of a data type value on one end changes, the data type value on the opposite end will change as
well. As a result, n must equal a1, r must equal a2, s must equal a3, and b must equal a4 as follows.
Connectors connecting primitive datatypes.

Related pages
• Connector62
• Binding Connector(see page 484)
Checking values against feature types
Cameo Simulation Toolkit will automatically run a compatibility check every time you assign a value to a
feature during simulation. It checks the value against the feature's type. The value you assign must
correspond with the type of the feature, meaning you can assign only values that are compatible with
62 https://docs.nomagic.com/display/MD2021xR2/Connector

the feature's type. If you assign an incompatible value to a feature, Cameo Simulation Toolkit will not
add it to the feature. The following table lists all compatible values for each datatype
Primitive datatype (Qualified name) Compatible value
• UML Standard Profile::UML2 Strings "true" or "false" (non-case sensitive).

Metamodel::PrimitiveTypes::Boolean
• PrimitiveValueTypes::Boolean (SysML
Profile.mdzip)
Profile::datatypes::boolean
• UML Standard Profile::UML2 Strings that can be cast to numbers (If the string is
Metamodel::PrimitiveTypes::Integer a real number, the floating point will be
• PrimitiveValueTypes::Integer (SysML eliminated).
Profile.mdzip)
• UML Standard Profile::MagicDraw Natural number datatypes
• UML Standard Profile::UML2
UnlimitedNatural
Real numbers, including the following four

datatypes (The floating point will be eliminated)

• PrimitiveValueTypes::Real (SysML
Profile.mdzip)
• UML Standard Profile::UML2 Strings that can be cast to numbers.

• PrimitiveValueTypes::Real (SysML Profile.mdzip) Integer numbers including the following five
• UML Standard Profile::MagicDraw datatypes
• UML Standard Profile::MagicDraw • UML Standard Profile::UML2
Profile::datatypes::float Metamodel::PrimitiveTypes::Integer
• PrimitiveValueTypes::Integer (SysML
Profile.mdzip)
UnlimitedNatural

Primitive datatype (Qualified name) Compatible value
• UML Standard Profile::UML2 Every value is compatible.

Metamodel::PrimitiveTypes::String
• PrimitiveValueTypes::String (SysML
Profile.mdzip)
• UML Standard Profile::UML2 Strings that can be cast into positive numbers.
Metamodel::PrimitiveTypes::UnlimitedNatural
• PrimitiveValueTypes::UnlimitedNatural (SysML Real and integer (positive) numbers including the
Profile.mdzip) following datatypes

Metamodel::PrimitiveTypes::Integer
• PrimitiveValueTypes::Integer (SysML Pro-
file.mdzip)
• UML Standard Profile::MagicDraw Pro-
file::datatypes::int
• PrimitiveValueTypes::Real (SysML
Profile.mdzip)
• Enumeration If a value equals to one of the Enumeration

Literals, the value is compatible.
Related page
• Primitive63
Exporting runtime objects to InstanceSpecifications
You can export the values of a runtime object through the Variables pane to the following
Specifications
• a new InstanceSpecification.
• an existing InstanceSpecification.
• the InstanceSpecification that created the runtime object. Once exported, the values of a runtime
object will be set to the slots of the InstanceSpecification.
63 https://docs.nomagic.com/display/MD2021xR2/Primitive

The type of InstanceSpecification you want to export the values of a runtime object to, depends on the
element you used to create the runtime object. If the element is a Classifier, you can export the values
of the runtime object to either of the following
• A new InstanceSpecification.
• An existing InstanceSpecification.
If the element is an InstanceSpecification, you can export the values of the runtime object to either of
the following
• A new InstanceSpecification.
• The same InstanceSpecification that you used to create that runtime object.
To export a runtime value to a new InstanceSpecification
1. Do either of the following

• Click a runtime object whose value you want to export in the Name column and click
the Export to New Instance icon on the Variables pane toolbar.
• Right-click the row and select Export Value To > New Instance
2. The Select Owner dialog will open. Select the owner of the new InstanceSpecification (the
system folder).

3. Click OK.
To export a runtime value to an existing InstanceSpecification

the Export to Instance icon on the Variables pane toolbar.
• Right-click the row and select Export Value To > Instance.

 Note
To export the value of a runtime object using this method, the runtime object must be created
from a Classifier.
2. The Select Instance dialog will open. Select an InstanceSpecification that will be used to save
the runtime object (You can select only the InstanceSpecification whose classifier is the same as
that of the runtime object).

3. Click OK.
To export a runtime value to the InstanceSpecification that has created the runtime object

the Export to Instance icon on the Variables pane toolbar.
• Right-click the row and select Export Value To > Instance.

2. Once Cameo Simulation Toolkit exported and saved the values of the runtime object to the
Instance Specification that created it, you can see the hyperlink to that particular Instance
Specification in the Simulation Console pane.
3. Click the hyperlink, and you will see the exact Instance Specification in the Containment tree.
This method allows you to export the value of the runtime object to the slots of the Instance
Specification that has created the object. You can see the notification of each successful export and a
location hyperlink, if any, in the Simulation Console pane.
 Note
To export the value of a runtime object using this method, the runtime object must be created
from an Instance Specification.

Related page
• Instance Specification(see page 38)

Recording Verification status of runtime values
On this page
• Requirement/Instance table highlighted(see page 243)

• VerificationStatus stereotype(see page 244)
• Remember Failure Status option(see page 246)
Requirement/Instance table highlighted

Cameo Simulation Toolkit supports recording verification status of runtime values. You can verify and
record the status of constraints during runtime. If constraints are not met during the simulation, cells in
the Requirement/Instance table will be highlighted in red on the Variables pane. You can do the
normal recording verification status of runtime values by using the resultLocation(see page 49) tag in
SimulationConfig(see page 49). The instances with recorded values in slots are created at the end of
simulation.
 Prerequisites
If you want constraint failures to be displayed in an Instance Table, the Simulation Profile must
be used in your model.
The Requirement(s) table shows that the constraint in the Requirement is not met, thus the
Requirement is colored in red as follows

The Requirement(s) table showing the constraint within a Requirement which is not met and colored in
red.
If you right-click on the Variables pane and select Export Value To > Instance, the variables will be
evaluated and colored in red if there are constraint failures in the instance table, as shown in the
following figure
The instance table showing the constraints after being exported to an Instance.
VerificationStatus stereotype
The status (pass/fail), related Requirements, and instances for constraints are recorded using the
VerificationStatus stereotype that is applied on the Value specification of the properties that you are
working on. You can also see the detail of the constraint failure in the tooltip when hovering the mouse
over any highlighted red values in the Requirement/Instance table as shown in the following figure

The simulation console showing the variables which have met or not met the constraints.
In addition, failed verdict of State Invariant(see page 363) is highlighted with red values and the tooltip.
However, you must create a Dependency relation between the testcase and value property as shown in
the following figure.
Failed State Invariant with highlighted red values and the tooltip.
If the VerificationStatus state on the Value specification fails, the active validation will be marked for
notification with the fail status tag as shown in the following figure

The Specification dialog showing verification status with the fail status tag.
The VerificationStatus stereotype, as shown in the figure above, has the tags as follows
Tag Description
constraint The name of the failure constraint.
margin The Requirement margin value calculated from value properties and the Requirement boundary
(a satisfy Relation).
requiremen The name of the failure Requirement.

t
status The result of the verification, either pass or fail.
timestamp The timestamp of the first failure recorded.
Remember Failure Status option

During the evaluation of particular configurations and scenarios, some Requirements/constraints can
fail, and those values are marked in red. However, they may pass later and are marked in green again,
but the failure is not recorded by default. To solve this problem, Simulation Toolkit provides the
Remember Failure Status option in «SimulationConfig» to remember any failure status until the
termination and record it as fail, even though it passes at the end. If the Remember Failure Status

option is set true, and there are constraint failures during the simulation, the first fail status will be
recorded in the status of «VerificationStatus» of new/recorded instance, and the time of the first failure
will also be recorded in the timestamp tag as shown in the figure below.
Setting the Remember Failure Status tag of a SimulationConfig to record the fail status and timestamp if
available.
Related pages
• Requirement Table64
Updating default values
When an object acquires the properties of another, there is an inheritance relationship between them.
The object that inherits the properties is called Subtype or Subclass (child) and the inheriting object is
called Supertype or Class (parent). This inheritance relationship allows the child and the parent to have
identical properties. If the property has a value, the Subclass will also inherits the value. Cameo
Simulation Toolkit allows you to change the default value of an object or a Subtype whose property is
defined in the Supertype or a read-only property. You can override this existing value in the subtype
without changing the default value of the property of the Supertype by creating a redefine property of
the subtype that represents the default values. The value of the property can be integer, real, or string.
When you change the inherited value in the subtype, e.g., from 2 to 3, in the Variables pane, the
simulation will initiate at 3.
64 https://docs.nomagic.com/display/SYSMLP2021xR2/Requirement+Table

This example uses the model depicted in to show you how to update default values to an inherited
and/or read-only property by creating redefined properties as follows
Inherited and read-only Properties of a Subtype.

To update default value(s) from an Instance Specification
1. Run a simulation on your model as follows
2. A Question dialog will open asking if you want to redefine the values in the Subtype. Click Yes.

Cameo Simulation Toolkit will create new redefined properties for the ExternalSubSystem (i, r, and
s), and save the default values (i = 0, r = 0.0000, and s = null) to the new properties.
3. On the Variables pane, change the default value of property i, r, and s of ExternalSubSystem.
4. Each time you finish updating the value, right-click the property in the Variables pane and
select Save ToDefault Value(s).

If Cameo Simulation Toolkit cannot create redefined properties, a warning message will appear.
Related page
• Redefine65
Breakpoints
Cameo Simulation Toolkit allows you to add or remove breakpoints to or from model elements. A
model simulation will pause when these model elements are activated during the simulation. You can
open the Breakpoints pane to see and manage all of the existing breakpoints in an active project.
The Breakpoints pane lists all breakpoints with their properties shown in separate columns.
65 https://docs.nomagic.com/display/CDMP2021xR2/Redefine

The Breakpoints pane.
The Breakpoints pane columns are listed in the table as follows
Colu Function
mn
Enab To display the enabled or disabled state of a breakpoint. If the value is true, the breakpoint is enabled.
led Otherwise, the breakpoint is disabled. A model simulation will be suspended at that particular
breakpoint only when the breakpoint is enabled (true).
Elem To represent a model element to which each breakpoint is applied. The model simulation will be
ent suspended when the symbol of the element is activated or deactivated (depending on the value in the
Suspend column).
Cond To represent a breakpoint condition, a boolean expression, that will be evaluated when a model
ition simulation reaches the element to which a breakpoint is applied. The simulation will be suspended at
that particular element or breakpoint when the result of the boolean expression is true. If the condition
is not defined, the simulation will always be suspended when it reaches that particular breakpoint.
Susp To suspend a model simulation. There are three kinds of simulation suspensions: On Entry, On Exit,
end and Both.
• On Entry to suspend simulation when a breakpoint's element is activated.
• On Exit to suspend simulation when a breakpoint's element is deactivated.
• Both to suspend simulation once a breakpoint's element is either activated or
deactivated.
Related pages
Adding breakpoints
You can add a Breakpoint to a model element using the model's Add Breakpoint(s) context menu.
To add a Breakpoint to a model element

• Right-click a model element either in the containment browser or on a symbol of the model
element on the diagram and select Simulation > Add Breakpoint(s).
Removing breakpoints
You can remove a Breakpoint from a model using the model's Remove Breakpoint(s) context menu.
To remove a Breakpoint
• Right-click a model element that has a breakpoint(s) and

select Simulation > Remove Breakpoint(s).

You can also click the Remove Breakpoint(s) or Remove All Breakpoints toolbar button or select the
Remove Breakpoint(s) context menu in the Breakpoints pane to remove all existing breakpoints.

Disabling updates in Simulation panes
You can turn off automatic updates of panes in the Simulation window by clicking . Turning off
auto-updates of panes will cause all of the panes (Sessions, Console, Variables, and Breakpoints) in the
Simulation window to be disabled and the simulation speed to increase. This can be seen in the
comparison of the Simulation window before turning off the auto-update option and after turning off
the auto-update option in the following figures respectively.
The following figure shows when the auto-update of panes is enabled
The Simulation window of the Calculator.mdzip sample with the auto-update of

panes option is enabled.
The following figure shows when the auto-update of panes is disabled
The Simulation window of the Calculator.mdzip sample with the auto-update of

panes option is disabled.
After the auto-update of panes option is disabled, you can work on the model, make changes, or run it,
but the actions that you are performing will not be displayed in any of the panes in the Simulation
window. If you enable the option, the Actions that you have performed will appear in the panes.
Validation and verification

Before executing UML or SysML model, you need to make sure that it has been correctly modeled, or
you can use the Cameo Simulation Toolkit's validation feature to help you validate the model against a
set of validation rules before executing it.
To validate a model
1. From the main menu, click Project > Options to open the model validation option in the Project
Options(see page 47) dialog.
3. In the Simulation Framework group, select the Check Model Before Execution option.
4. Click OK.
5. Simulate your model. A dialog will open, asking whether you want to load the required profiles
that contain the validation rules to validate your model (if your project does not contain the
required validation rules).

6. Click Yes to load the validation rules and validate the model before the simulation or No to
simulate the model without validating it.
Related page
State Machine simulation
Cameo Simulation Toolkit allows you to perform a State Machine Simulation (State Chart Simulation) on
existing State Machine diagrams, based on the W3C SCXML standard. This kind of simulation is
frequently used in the early stage of software development by designers or analysts to test the flow of
the software to be developed.
The W3C SCXML standard provides a generic State machine-based simulation environment based on
the Harel Statechart. SCXML is capable of describing complex State machines, including Substates,
concurrency, history, time events, and many more. Most of the things that can be represented as UML
statecharts, e.g., business process flows, views on navigation bits, interaction or dialog management,
and many more, can leverage the SCXML engine. When executing a State Machine, the SCXML engine is
capable of finding an initial state automatically even if the initial node is not defined. This feature is also
applicable to composite States and orthogonal States.
In addition to simulating an executable model as a demonstration tool to validate and verify the system
Behavior at key milestone reviews, the State Machine simulation supports exporting the UML State
Machine to standard SCXML files for further analyses or transformations.
To export the UML State Machine to an SCXML file
1. Open a Simulation project with the State Machine diagram.

2. From the main menu, select File > Export To > SCXML File. The SCXML File dialog opens to
select the State Machine diagram exported to an SCXML file.

3. Locate the State Machine diagram by doing one of the following:
• In the Search by Name box, type the name of the State Machine diagram.
• Click the Tree tab and select the State Machine diagram appearing in the tree.
• Click the List tab and select the State Machine diagram appearing in the list.
• At the File Location box, select to browse the State Machine diagram.
4. Click OK. The exported file, e.g., class.scxml, will be as follows.
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="null"

initial="initial__20_0_5630196_1596545104923_661917_23868">

<state id="initial__20_0_5630196_1596545104923_661917_23868">
<transition
target="State_Tests::Do_Activity_in_State::class::class::_20_0_5630196_15965451
04918_849035_23846::state">
</transition>
</state>
<state
id="State_Tests::Do_Activity_in_State::class::class::_20_0_5630196_159654510491
8_849035_23846::state">

<transition event="s2"
target="State_Tests::Do_Activity_in_State::class::class::_20_0_5630196_15965451
04918_849035_23846::state2">
</transition>
<invoke targettype="doactivity"
src="_20_0_5630196_1596545104909_691815_23820">
</invoke>
</state>
<state
id="final_State_Tests::Do_Activity_in_State::class::class::_20_0_5630196_159654
5104918_849035_23846::final" final="true">
</state>
<state
id="State_Tests::Do_Activity_in_State::class::class::_20_0_5630196_159654510491
8_849035_23846::state2">
<transition
event="COMPLETION_EVENT__20_0_5630196_1596545104923_763628_23871"
target="final_State_Tests::Do_Activity_in_State::class::class::_20_0_5630196_15
96545104918_849035_23846::final">
</transition>
</state>
</scxml>
Related pages
Supported elements
Most of the elements on a State Machine diagram are supported as follows
Element Type Executable (Yes/No) Exportable to SCXML (Yes/No)
state Yes Yes
composite state Yes Yes
orthogonal state Yes Yes
submachine state Yes Yes
initial state Yes Yes
final state Yes Yes

Element Type Executable (Yes/No) Exportable to SCXML (Yes/No)
onEntry Yes Yes
onExit Yes Yes
onTransition Yes Yes
doActivity Yes Yes
time event Yes Yes
deep history Yes Yes
shallow history Yes Yes
transition Yes Yes
transition-to-self Yes Yes
choice Yes Yes
junction Yes Yes
Adapting models for State Machine simulation
Currently, Cameo Simulation Toolkit can simulate only those elements whose types are specified in the
supported elements table in Supported elements(see page 258). Thus, you must modify your model so
that only the supported (executable) elements are included in your State Machine diagram.
State Machine simulation can be adapted in different useful ways, as shown below:

• Defining Triggers on Transitions
(see page 260)Changing the States of runtime objects on Transitions by defining Triggers on
Transitions.
• Using Guards on Transitions

(see page 262)Specifying Guard conditions on Transitions by using any action languages.
• Behaviors on Entry, Exit, and Do Activities of a State

(see page 264)Defining Behaviors that can be an Activity, a State Machine, an Interaction, or an
OpaqueBehavior of States for Activities.
• Signal properties mapping to Behavior parameters

(see page 266)Mapping Signal properties to Behavior parameters by sending Signals to target
objects to carry values to input parameters.
• State activation semantics

(see page 273)Specifying State Activation semantics regarding when Cameo Simulation Toolkit
activates Entry Behaviors on activating entries of States.
• Completion Events and Transitions

(see page 274)Enabling or disabling completion of Events and Transitions during State Machine
simulation.
• Deferred Events
(see page 277)Utilizing deferrable Triggers to save deferred Events for future processing until States
are entered.
Defining Triggers on Transitions
If you want a runtime object(see page 207) to change its State66 on a Transition67, you need to define a
Trigger68 on the Transition by assigning an Event Type to a Transition69. A runtime object will change its
State when it receives a Trigger on the Transition. A Trigger can be a Signal Event70, a Time Event71, or a
Change Event72.
66 https://docs.nomagic.com/display/MD2021xR2/State
67 https://docs.nomagic.com/display/MD2021xR2/Transition
68 https://docs.nomagic.com/display/MD2021xR2/
State+Machine+diagram+elements#StateMachinediagramelements-Trigger
69 https://docs.nomagic.com/display/MD2021xR2/Assigning+Event+Type
70 https://docs.nomagic.com/display/MD2021xR2/Event#Event-SignalEvent
71 https://docs.nomagic.com/display/MD2021xR2/Event#Event-TimeEvent
72 https://docs.nomagic.com/display/MD2021xR2/Event#Event-ChangeEvent

The StopWatch's State Machine diagram with defined Triggers on the
Transitions.
 Tip
Optionally, you can also use a Send Signal Action73 of an Activity(see page 26) as a Signal Event of
Transition. As shown in the following figure, the stopped State can wait for the off Send Signal
Action of the do Activity to proceed to the final State.
73 https://docs.nomagic.com/display/MD2021xR2/Send+Signal+Action

The off Send Signal Action of the do Activity as a Signal Event of Transition.
 Note
According to UML Version 2.5.1, the initial Transition must not have Triggers or Guards.
However, Simulation provides the validation rule to prevent the model error by displaying a
warning in the Validation Results panel74. You can select the Check Model Before
Execution option in the Simulation Project options through validation and verification(see page
254) or manually select Pre-execution constraints from the Validation Suite75 drop-down list in
the Validation dialog76.
Related page
• Signal properties mapping to behavior parameters(see page 266)
Using Guards on Transitions
You can specify Guard conditions on Transitions using any action language. Open
the SmallTestSamples.mdzip to see an example of how to specify Guards on Transitions.
You can use the properties of a context Classifier (the Classifier that is the context of a State Machine
diagram) in Guard expressions as variable names. The real values of the variables will be resolved at
runtime. In the example in SmallTestSamples.mdzip, the values come from the slots of the instance of
the context Classifier (see the Instance diagram in the sample project).
74 https://docs.nomagic.com/display/MD2021xR2/Validation+Results+panel
75 https://docs.nomagic.com/display/MD2021xR2/Validation+dialog#Validationdialog-
descrDescriptionofValidationdialogoptions
76 https://docs.nomagic.com/display/MD2021xR2/Validation+dialog

The Test_guard diagram sample.
During the simulation, any Guard that is not Boolean expression evaluation (the state 2 or state 3 body
of the Guard in this case) will show the Question dialog box displaying the body of the Guard as shown
in the figure below. You can click Yes to set the evaluation result true with the Transition according to
the Path or No to set the evaluation result false without the Transition.
The Question dialog box appears for any Guard not Boolean expression
evaluation during the simulation.
 Note

If you use a Choice with Transitions, the name of the Choice will be also shown in the Question
dialog box with the body of the Guard.
Behaviors on Entry, Exit, and Do Activities of a State
States can have defined Behaviors for any Activities: Entry, Exit, or Do Activity. Cameo Simulation Toolkit
creates a new simulation session to simulate those defined Behaviors. A defined Behavior can be an
Activity, a State Machine, an Interaction, or an OpaqueBehavior. The simulation engine corresponding
to a defined Behavior will be used to simulate a model. If the defined Behavior is OpaqueBehavior, the
ScriptEngine will be used to simulate the code in the body of OpaqueBehavior.

The Behavior simulation on the entry of a State in the StopWatch.mdzip sample
project.
According to Precise Semantics of UML State Machines (PSSM) Compatible CallEvent arguments
handling, the Caller is suspended until the running to the completion step is finished in case of the Sync
Call. The running to the completion step ends after the Entry or Do Activity is done. The input
parameter must match the argument of the Entry or Do Activity. If it has an output parameter, it will be
redefined until the running to the completion step is over. Therefore, the last output parameter is
returned to the Caller.

The Caller is suspended until the running to the completion step is completed
according to PSSM Compatible CallEvent arguments handling.
Related pages
• Opaque Behavior77
Signal properties mapping to Behavior parameters
Once the Activities Entry, Exit, and Do Activity of a State have been specified with a Behavior that has
input parameters, a signal, which triggers objects to change the State, can carry values to the input
parameters.
77 https://docs.nomagic.com/display/MD2021xR2/Opaque+Behavior

In order to send the signal to the target object, an instance of the signal will be created. The signal
instance can contain the values of its structural features. These values will be propagated to the
parameters of the Behavior specified at the Entry, Exit, and Do Activity when the two following
conditions are met
• The number and order of properties of the signal must be the same as the number and order of
parameters in the Behavior.
• The type, the order (isOrdered), and the multiplicity of each property of the signal must be the
same as the corresponding parameter of the Behavior. If the type of signal properties are
Subtype of the parameter type, it is considered a match.
If one of the two conditions is not satisfied, a warning will appear once the model is validated by pre-
simulation constraints before the simulation starts.
A send signal Action in an Activity can create a signal instance with the values of its structural features.
For example, the signal MySignal shown in the following figure. It contains three properties: attrib1,
attrib2, and attrib3. They are created with Real, String, and Boolean respectively.
A Signal with three properties.

The following figure shows the order of the three signal attributes

The arguments of MySignal signal.
To create the signal Instance of MySignal that contains the values of attrib1, attrib2 and attrib3, a send
signal Action must be created with three argument pins as shown in the following figure. The order and
types of the pins must match the order and type of the signal properties, therefore the first pin must be
typed by Real, the second by String, and the third by Boolean.

Send signal Actions with three arguments.
Now that the pins of the send signal Action have been created, you can specify the values of the signal
Instance through them (see the following figure). The figure shows the value specification Actions that
are used to create the values and add them to the pins of the send signal Action.

Creating values for argument and parameters of MySignal.
At this point, the signal Instance created by the send signal Action in the Send Signal Actions with
three arguments figure, will be sent to the context object of Activity A. The signal Instance
contains 12.34, Hello World, and true as the values of attrib1, attrib2, and attrib3 respectively. You can
get more information on State Machine simulation and Activity simulation in sections State Machine
simulation(see page 256) and Activity simulation(see page 286) respectively.

Details of the State Machine diagram.
In a State-Machine simulation, the state of an object will change if it receives a send signal instance.
Behaviors that are specified at the entry, do Activity, and exit of the State will be invoked in the State
transition. The values that come with the signal instance will be delivered to the parameters of the
behaviors. For example, prior to receiving a signal, an object is in State1, however, it will move to State2
once it has accepted the signal. The Behaviors to which the values of the signal Instance will be
delivered, are the Behaviors specified at Exit of State1, Entry and Do Activity of State2.
In the following figure, the object has accepted the signal Instance, that is MySignal, and it will move
from State1 to State2. A performOnEntry activity, which is the entry Activity of State 2 will be simulated.
The performOnEntry Activity contains three parameters which are param1, param2, and param3. They
are typed by Real, String, and Boolean respectively.

Details of the performOnEntry Activity.
You can see the order of the parameters. The values that come with the signal Instance of MySignal will
be delivered to these parameters. In this example, the value of attrib1 will be propagated to param1,
the value of attrib2 will be propagated to param2, and the value of attrib3 will be propagated to
param3. The values of param1, param2, and param3 are "12.34", "Hello World", and "true"
respectively.
Arguments of the performOnEntry Activity.

Related pages


State activation semantics
Cameo Simulation Toolkit provides State Activation Semantics as one of the simulation options. This
option allows you to determine whether Cameo Simulation Toolkit activates an Entry Behavior before
or after activating an entry of State. You can select one of the options: After entry and Before entry.
The After entry option allows activating the entry of State after the Entry Behavior is completely
activated. The Before entry option allows entering the entry of State before executing the Entry
Behavior.
To set the State Activation Semantics option
1. Open the Project options(see page 47) dialog.

2. In the SCXML Engine group, select State Activation Semantics.
3. From the drop-down list, select After entry or Before entry.
4. Click OK.

Completion Events and Transitions
Completion Events are standard UML Events which are fired during the execution of a State Machine
diagram. For composite or submachine States, a completion Event will be generated when all internal
Activities, e.g., entry and doActivity Behaviors, have completed execution under either of the
following circumstances
• If the State is a composite State, all its orthogonal Regions have reached a FinalState.
• if the State is a submachine State, the submachine StateMachine execution has reached a
FinalState.
 TIP
You can enable/disable the Completion Events and Transitions option in the SCXML Engine
group in the Project Options(see page 47) dialog for completion Events and Transitions support.

The Completion Events and Transitions option in the SCXML Engine group in the
Project Options dialog.
Case 1
Completion Events and Transitions in a State Machine diagram.

For example, in the above State Machine diagram, a Transition from the "on" State to the "off" State
does not happen until a completion Event is generated. The completion Event is generated after the
DoActivity Behavior completes and only then the State transits from "on" to "off".
Case 2

In the above State Machine diagram, a completion Event is generated after the entry and sendOff
Behaviors have completed.
Case 3

In the above State Machine diagram, a completion Event will be generated after the entry and working
Behaviors have completed.
 Information
Completion Events have dispatch priority over all other Events. They are put into the beginning
of the Event queue.

Related page

Deferred Events
On this page
• Deferrable Trigger(see page 277)
UML State Machines provide a special mechanism for deferring Events in States. In every State, you can
include a clause [Event list]/defer. If an Event in the current State’s deferred Event list occurs, the Event
will be saved (deferred) for future processing until a State is entered that does not list the Event in its
deferred Event list. Upon entry to such a State, the UML State Machine will automatically recall any
saved Event(s) that are no longer deferred and will then either consume or discard these Events.
• A deferred Event is activated as soon as it enters a State where it is not deferred.

• A deferred Event can only be added to a State Machine diagram at this time.
Deferrable Trigger
A list of Triggers that are candidates to be retained by the State Machine if they trigger no transitions
out of the State (not consumed). A deferred Trigger is retained until the State Machine reaches a State
configuration where it is no longer deferred.

The Specification window for Event State moving - showing the editable Deferrable Trigger tag.
As in the State Machine diagram in the following figure, the Elevator 'open' Event is deferred as long as
the Elevator is moving. Only when the State transitions to 'stopped' State again, the 'open' Event will
be executed because it is no longer deferred at this point.

A deferred clause added to Event moving which causes the Event to delay until it is no longer deferred.
 Important
This version of Cameo Simulation Toolkit does not support Deferred Events for Activity
diagrams. They can now only be added to a State in a State Machine diagram.
Related page

Running a State Machine simulation
Cameo Simulation Toolkit will perform a State Machine simulation if the following elements are
selected for the simulation
• A State Machine.
• A State Machine diagram.
• A class whose Classifier Behavior is defined by a State Machine.
• An InstanceSpecification whose Classifier is a Class that has a defined Classifier Behavior with
a State Machine.

The function of Triggers is to change the State of a runtime object during a State Machine simulation.
The Trigger can be either a signal or a time Event. If it is a signal Event Trigger, a signal will be sent to a
runtime object to trigger it from one State to another. To send the Trigger signal, you have to select a
runtime object, which is a target for the signal, in the Variables pane. All signals that can be received by
the selected runtime object will be listed on the Trigger drop-down menu on the Simulation window
toolbar as follows
The Trigger drop-down menu.

You can use a User Interface Mockup to send a signal to a runtime object. See more information about
UI mockup in UI Modeling Diagram Simulation(see page 70).
You can trigger a transition directly on a diagram. The menu Fire Transition on the smart manipulation
toolbar triggers a transition and sends it to the activeObject that is displayed on the diagram. The Fire
Transition command ignores guards.
To trigger a transition directly on a diagram, do either of the following
• Either select a target object from the Variables pane and right-click a transition line on the
diagram, and select Fire Transition.
• During the simulation, click a transition line on the diagram and select Fire Transition.
Related pages


State Machine duration simulation
On this page
• Min(see page 281)

• Max(see page 281)
• Average(see page 281)
• Random(see page 282)
You can specify a duration constraint on any State in a State Machine. The minimum and maximum
duration spent by the State can be provided through min and max of the duration constraints.
You can use one of the four different modes: min, max, average, and random, to simulate a State that
has a duration constraint. You can select a duration mode through the value of
the durationSimulationMode tag of the «SimulationConfig» stereotype.
Cameo Simulation Toolkit supports the following time suffixes: ms (millisecond), s (second), m or min
(minute), h (hour), and d (day). You can parse the time unit that is specified as a suffix after a number or
at the end of an expression string. If you do not specify a suffix, the millisecond will be used by default.
The examples are as follows
• 100 m or 100min is 100 minutes.

• xs is the value of the property x in seconds.
• 200 is 200 milliseconds.
Min
When you select min as the duration simulation mode, Cameo Simulation Toolkit will increase the time
spent on a State Machine by the min duration specified on the duration constraint when the element,
to which a duration constraint is applied, is activated.
Max
If you select max as the duration simulation mode, Cameo Simulation Toolkit will increase the time
spent on a State Machine by the max duration specified on the duration constraint when the element,
to which a duration constraint is applied, is activated.
Average
When Cameo Simulation Toolkit simulates your model with the average duration simulation mode, it
will use the average value between the max and min duration of the duration constraint as the
duration of time spent on simulating the element, to which the duration constraint applied.

Random
The random mode allows Cameo Simulation Toolkit to obtain the duration of time spent on simulating
an element, to which a duration constraint applied, from a uniformly distributed random number
between the min and max duration of the duration constraint.
If you simulate a model without specifying any duration simulation mode, Cameo Simulation Toolkit will
ignore duration constraints and obtain the time spent on simulating the States and State Machines
from the simulation clock.
If you simulation a State that has a duration constraint with a duration simulation mode and the time
spent on Entry, Exit, and DoActivity Behaviors are beyond the range of the duration constraint specified
on the State, the State will be considered as a broken constraint element, and Cameo Simulation Toolkit
will pause the model simulation at the State.
Related pages

Sample projects
On this page
• Do Activity in State(see page 283)

• Guard(see page 283)
• History(see page 284)
• Regions(see page 285)
• Timing Events(see page 285)
The State Machine simulation sample projects are available in the built-in Small Tests samples, in
<modeling_tool_installation_directory>\samples\simulation\SmallTestSamples.mdzip or from the Welcome
screen under the Simulation group of the modeling tool. In this topic, the focus is on the State Tests
section for the State Machine simulation sample projects as follows:

The State Tests section of the Small Tests samples.
• Do Activity in State
This test is designed to demonstrate how to use the Do Behavior in model execution. Run the
TestState_DoActivity simulation configuration to see how it works.
The Do Activity in State sample.
• Guard
This test is designed to demonstrate how to use Guards on Transitions in model execution. Run
the TestState_Guard simulation configuration to see how it works.

The Guard sample.
• History
This test is designed to demonstrate how to use the Composite State with Shallow History and
Deep History in model execution. Click the Run button on the diagram toolbar to see how it
works.

The History sample.
• Regions
This test is designed to demonstrate how to use the Orthogonal State with Parallel Regions and
Entry and Exit Activities in model execution. The Entry Activity is executed immediately after the
State Machine is activated before any States in the inner regions. Next, all Initial States in the
regions are activated simultaneously. The Regions sample demonstrates that multiple active
States are executed at the same time. The Event list in the Simulation Console contains Triggers
of all outgoing Transitions of all active States. If one of the parent States’ outgoing Transitions is
triggered, the Exit Activity will be executed before the State Machine is deactivated. Click the Run
with Context button on the diagram toolbar to see how it works.
The Regions sample.
• Timing Events
This test is designed to demonstrate how to use timing Events in model execution. Both relative
time and absolute time are supported (Is Relative=true/false). Click the Run button on the
diagram toolbar to see how it works.

The Timing Events sample.
Activity simulation
Activity simulations essentially require the Activity simulation engine in Cameo Simulation Toolkit to
perform all Activity-based simulations. The details are outlined in the following topics:
• Activity simulation engine

(see page 287)Running Activity Simulation in Activity diagrams or Activity elements.
• Creating a model for Activity simulation

(see page 295)Simulating Classifiers defined by Activities.
• Executing Activities
(see page 311)Suspending the simulation with breakpoints.
• Activity duration simulation

(see page 317)Calculating and analyzing Activity duration and specifying duration constraints.

• Duration analysis
(see page 326)Directing target objects to the callOperationAction.
• Running a Call Action simulation without a target pin

(see page 331)Simulating a CallOperationAction that does not have a target pin to select a runtime
object as a target.
• Activity Partition execution and allocated Behavior

(see page 332)Using Activity Partition as an element in the Activity diagram to set the boundary of
simulation of an execution.
• Execution of incomplete/dummy models

82
Executing incomplete and dummy models with Behaviors of Actions when input or output pins
or any properties of Actions are not specified or present.
• Using utility functions of Simulation

(see page 344)Facilitating common tasks through Opaque Behaviors under
SimulationProfile::library::utils.
Activity simulation engine
On this page
• fUML engine settings(see page 290)

• ReadLine support(see page 291)
• Guards in Swimlanes(see page 294)
Cameo Simulation Toolkit provides an Activity simulation engine that allows you to run an Activity
Simulation on Activity diagrams83 or Activity Elements. Cameo Simulation Toolkit also includes the
implementation of OMG Semantics of a Foundational Subset for Executable UML Models (fUML), an
executable subset of standard UML, that can be used to define the structural and Behavioral semantics
of systems. fUML defines a basic virtual machine for the Unified Modeling Language and supports
specific abstractions enabling compliant models to be transformed into various executable forms for
verification, integration, and deployment.
Various UML Activity diagram concepts are supported, including Object and Control Flows, Behavior
and Operation Calls, sending Signals via Connectors with or without Ports in Internal Structure,
accepting Signals and Time Events, Pins, Parameters, Decisions, Structured Activity Nodes, and many
more.
The Activity simulation engine features include the following
• fUML 1.3 specification support.

• Any Action languages in opaqueBehaviors, opaqueExpressions, Decisions, Guards, and
Constraints (see Integration with MATLAB®(see page 451) for more details).
• CallBehaviorAction with nested diagrams simulation and animation.
82 https://docs.nomagic.com/pages/viewpage.action?pageId=17678471
83 https://docs.nomagic.com/display/MD2021xR2/Activity+diagram

• SendSignalAction to send a Signal to a global Event queue to be used by the system level but not
by the subsystem, e.g., in State Machine.
 Note
• SendSignalAction has the Target input Pin for specifying the signal receiver. If this
Pin is omitted, the signal instance will be sent to the context itself.
• The On Port property on SendSignalAction is used for sending signals via the
specified port.
• CallOperationAction through a Port.

• Sending Signals through a Port.
• Support for Decision Nodes with probabilities(see page 495) over all outgoing edges.
• Support for Decision Nodes with a Decision input that provides input to Guard specifications on
outgoing edges from each Decision Node.
The supported Decision input for Decision nodes.
 Note
• You can simulate only Activities that are owned by a Package or a Class. As a
workaround, the CallBehavior Actions, owned by the Call Behaviors in a Package, will be
used for the entry/do/exit Behaviors in States.

• The Guards on an ObjectFlow are not Boolean expressions in fUML. They should contain
a value that matches the runtime value that flows on the ObjectFlow during simulation.
To change to a regular UML (Boolean expression)
1. On the main menu, click Options > Project and select Simulation on the left of the
Project Options dialog.
2. Select the Use fUML DecisionSemantics value check box so that the value becomes
false. The value is false by default in the UML mode.
• A decision value can be passed as a parameter of Behavior of an opaque expression

through a pin of Action. If a valid return value is from an assigned Behavior of a Guard,
the body of the Guard will be ignored. However, if the Behavior is <unspecified>, the
body of the Guard will be used.
Most of the elements on an Activity diagram are supported as follows
• Control Flow
• Object Flow
• Input Pin
• Output Pin
• Activity Final Node
• Flow Final Node
• Activity Parameter Node
• Decision Node
• Merge Node
• Join Node
• Fork Node
• Structured Activity Node
• Conditional Node
• Loop Node (the setup part will not be executed as the fUML specification.)
• Expansion Region
• Expansion Node
• Object Node
• Central Buffer Node
• Data Store Node
• Actions
• AcceptEventAction
• AddStructuralFeatureValueAction
• CallBehaviorAction
• CallOperationAction
• ClearAssociationAction
• ClearStructuralFeatureAction
• CreateLinkAction
• CreateObjectAction
• DestroyLinkAction
• DestroyObjectAction
• OpaqueAction
• ReadExtentAction
• ReadIsClassifiedObjectAction
• ReadLinkAction
• ReadSelfAction

• ReadStructuralFeatureAction
• ReclassifyObjectAction
• ReduceAction
• RemoveStructuralFeatureValueAction
• SendSignalAction
• StartObjectBehaviorAction
• TestIdentityAction
• ValueSpecificationAction
fUML engine settings

You can customize Behaviors of the fUML engine for Simulation to match your project Requirements
through the Project Options(see page 47) dialog as shown below.
To customize the fUML engine settings in the Project options dialog
1. On the main menu, click Options and select Project. The Project options dialog opens.
3. Go to the fUML Engine group and set any of the properties as desired.
The settings for the fUML engine are in the following table.
Property Function
Use fUML Decision If true (false by default when in the UML mode), all Guards will be solved to true
semantics when the flowing token value matches the Guard value (instead of evaluating every
Guard as Boolean operation).

Property Function
Auto Create fUML Object If true, automatically create an fUML object of output.
of Output
Pass Caller Context If true, pass the caller context to the called Behavior if it does not have its own
context specified. Otherwise, use the Behavior itself as context.
Terminate Nested If true, terminate nested Part Behaviors if their parent object Behavior is
Behaviors terminated.
 Note
You can instantiate nested composite structure using the standard PSCS construction
mechanism by default.
ReadLine support
ReadLine is a function that allows the user to enter value through the input line on the Console pane. A
Call Behavior Action can be set Behavior as ReadLine [fUML_Library::BasicInputOutput] using
fUML_Library.mdzip from the Use Project dialog. Before using the ReadLine function, you need to
include fUML_Library.mdzip in the project first.
To open the Use Project dialog and include fUML_Library.mdzip
1. Click File > Use Project > Use Local Project from the main menu to open the Use Project
dialog.

2. In the Select a project to use area, select the From predefined location option.
3. In the Paths to used projects list, select <install.root>\modelLibraries.
4. In the directory tree list, select fUML-Library and click Next> to proceed to the next step.

5. You will be at the Specify usage options step. Click Finish. The Question dialog opens to ask
you about showing auxiliary resources in the Containment tree. Click Yes.
Then a Call Behavior Action can now be set Behavior as a ReadLine Element. The ReadLine Element will
be shown with two default Pins, i.e., result and errorStatus. During the simulation, the ReadLine
Element is executed to allow entering value through the input line on the Console pane. The result of
the ReadLine Element can be used by other Elements with any proper data types, e.g., Guard, as in the
following figure

ReadLine support allows entering value through the input line on the Console
pane.
Guards in Swimlanes
Simulation supports Guards in Swimlanes in the Activity diagram as shown in the figure below. See also
Using Guards on Transitions(see page 262) and Swimlane84.
84 https://docs.nomagic.com/display/SYSMLP2021xR2/Swimlane

Guards in Swimlanes are supported in the Activity diagram.
Related pages
• Decision and Merge85

• Action86
Creating a model for Activity simulation
You can simulate a UML Activity or a Classifier whose Classifier Behavior is defined by an Activity. This
section demonstrates how to create a simple but executable Activity model through the following steps
1. Create a Class containing two properties typed by Integers.

2. Create an Activity to print the summation value of the two properties.
3. Assign the Activity as the Classifier Behavior of the created Class.
4. Create an opaque Behavior to print the summation value of two input parameters of
type Integer.
5. Write a script to print the summation of the given integer values that are referred to by the two
input parameters.
6. Complete the Activity diagram of the Class.
7. Create a ReadSelfAction to read a runtime object that will be supplied to the input pins of both
the readX and readY Actions.
85 https://docs.nomagic.com/display/MD2021xR2/Decision+and+Merge
86 https://docs.nomagic.com/display/MD2021xR2/Action

8. Create an InstanceSpecification and assign the values to the slots that correspond to the two
created properties.
To create a Class containing two attributes typed by Integers
1. To create a new UML project, click File > New Project on the main menu. The New
Project dialog will open.
2. Select SimulationProject from the Simulation group and specify the project's name, e.g.,
"SimpleActivitySimulation".
3. Specify the location where you want to save your project file, and then click OK.
4. Right-click the Model model in the containment browser and select Create Element > Class. A
new Class element, which is the context of the Activity, will be created in the containment
browser. Name the created Class, e.g., "SumPrinter".
5. Add two properties: x and y of type Integer.
Right-click the SumPrinter Class and select Create Element > Property. Type 'x' to name the
property (see the first figure below). Right-click x and select Specification to open
its Specification window. Select Integer as the property type (see the second figure below).

Creating a new Property x for the SumPrinter Class.
The Specification of Property x.

The SumPrinter Class with the Properties X and Y of Integer Type.
6. Repeat Step 5 to create Property y.
7. Once the Properties x and y have been created, define the Behavior of the created Class: Specify
the Classifier Behavior of the SumPrinter Class with a UML Activity element.
To create an Activity to print the summation value of the two properties
1. Right-click the SumPrinter Class in the containment browser and

select New Diagram > Activity Diagram to create a new Activity under it.
2. Name the diagram "PrintSum".

Now that the Activity has been created, you need to assign it as the Classifier Behavior of SumPrinter.
To assign the Activity as the Classifier Behavior of the created Class
1. Right-click the SumPrinter Class in the containment browser and select Specification to open
its Specification window.
2. Select All from the Properties drop-down menu to make sure that all of the properties are listed
in the dialog.
3. Click Classifier Behavior and select the PrintSum Activity from the drop-down list on the right-
hand side.
To create an opaque Behavior to print the summation value of the two input parameters of
type Integer:
1. Right-click the Model model in the Containment tree and select Create
Element > Opaque Behavior. A new opaque Behavior will be created under the Model model.
2. Name it "PrintSumOfIntegers". The following figure shows the PrintSumOfIntegers Opaque
Behavior in the Containment browser.

3. Add two input parameters of type Integer: a and b.
4. Right-click the PrintSumOfIntegers opaque Behavior and select Create Element > Parameter.
Name the created parameter 'a' in the name field and select Integer as the type of
Parameter a (see the following figure that shows the Specification of Parameter a).
5. Repeat Steps 3-4 to create Parameter b as shown in the following figure that shows the
PrintSumOfIntegers Opaque Behavior containing Parameters a and b in the Containment
browser.

To write a script to print the summation of the given integer values
• Open the Specification window of the PrintSumOfIntegers opaque Behavior and write a script
in the Body field (You can use any scripting language that is supported by MagicDraw's
Macro Engine, e.g., BeanShell, Groovy, JavaScript, Python, or Ruby). In this example, JavaScript will
be used to print the summation of the given integer values that are referred to by the
parameters a and b; therefore, the script will be: "print(a+b)".

 Note
If you want to use a scripting language other than JavaScript, you can specify it in the Language
attribute of the Specification window.
Specifying a Scripting Language in the Specification dialog.
The next step is to complete the PrintSum Activity diagram of the SumPrinter Class and add
a ReadStructuralFeatureAction so that the values of properties x and y, which are owned by
the SumPrinter Class, are readable. The values of a and b will later be passed on to
the PrintSumOfIntegers opaque Behavior as the values of input parameters a and b respectively.
To complete the Activity diagram of the Class
1. Drag the PrintSumOfIntegers opaque Behavior from the containment browser to

the PrintSum Activity diagram. A new Action of PrintSumOfIntegers will be created.
2. Name the Action "print".

3. Add the Initial and Activity Final nodes to the Activity diagram and connect them to the print
Action using a control flow. The following figure shows the Activity diagram with Initial and Final
Activity nodes.
4. Click Action and select Any Action from the Activity Diagram toolbar on the PrintSum Activity
diagram.
a. Select Read Structural Feature Action in the Select Action MetaClass dialog.

5. Click the PrintSum Activity diagram to create the Action and name it "readX" as shown in the
following figure
6. Open the Specification window of the Action readX.

7. Click the Structural Feature and the button to open the Select Property dialog to select
Structural Feature.

8. Select the Property x of the SumPrinter Class and click OK. The Select Property dialog will close.
9. Create an object flow from the pin result of the readX Action to pin a of the print Action. The
following figure shows the Flow between readX and print Actions in the Activity diagram.
10. Repeat Steps 4 to 10 to create another Action named readY, which is

the ReadStructuralFeatureAction, with the following arrangements
• The name of the Action is "readY".
• The structural feature is the attribute 'y' of the SumPrinter Class.
• The name of the output pin of readY is 'b'.
• The output pin b of readY connects to pin b of the print Action.

The following figure shows the Activity diagram with readX and readY Actions
To create a ReadSelfAction to read a runtime object that will be supplied to the input pins
of readX and readY Actions
1. Click Action > Any Action on the Activity Diagram toolbar. The Select Action MetaClass dialog
will open (see the following figure).
2. Select Read SelfAction.

3. Click the PrintSum Activity diagram to create an Action and name it, for example, readSelf. The
following figure shows the Activity diagram with Action readSelf.

4. Create a Fork Horizontal and use Object Flow to connect it to the pins of the
Actions readX, readY, and readSelf on the diagrams. The following figure shows a complete
PrintSum Activity diagram.
The final step is to create an InstanceSpecification whose Classifier is the SumPrinter and assign the
values to the slots that correspond to the properties x and y. These values will be used during the
simulation.
To create an InstanceSpecification whose Classifier is the SumPrinter and assign the values to the
slots that correspond to the Properties x and y
1. Right-click the Model model and select Create Element > InstanceSpecification.
2. Name the created InstanceSpecification, e.g., instance.

3. Right-click the created Instance and open the Specification window of instance.
4. Click the Classifier field and the button. The Select Elements dialog will open.
5. Select the SumPrinter Class to edit the Classifier and click OK.
6. Click Slots on the left-hand side pane of the Specification window and select x:Integer.

7. Click the Create Value button to create a new value of the slot. The Value box will open for you
to assign the value to Property x slot.
8. Type a number, e.g., 2 as the value of the property x slot.

9. Repeat Steps 6 to 8 to assign "8" as the value of the property y slot as shown in the following
figure and click Close.

The model is now ready for you to simulate.
Related pages

• Class(see page 32)
Executing Activities
You can add some breakpoints to the model created when Creating a model for Activity simulation(see
page 295) before executing it. This section demonstrates how to suspend the model simulation at some
specific points with breakpoints. You can use either the diagram or browser context menu to add a
breakpoint to an element.
The following example shows you how to add breakpoints to pins a and b of the action print. Once the
model simulation has reached these pins, the simulation will be suspended.
To add a breakpoint to an element and simulate the model
1. Right-click an element and select Simulation > AddBreakpoint(s). The breakpoints will be
shown in the Breakpoints pane of the Simulation window.

The Breakpoints pane in the Simulation window.
Clicking Window > Simulation on the main menu to open the Simulation window.
2. Right-click instance in the containment browser and select Simulation > Run to simulate the
model from instance, which is the InstanceSpecification of the SumPrinter Classifier.

3. A new simulation session will be created and displayed in the Sessions pane of
the Simulation window. The symbol of the elements with breakpoints attached will be highlighted
in yellow by default. Click the Start button on the Simulation window toolbar to animate the
simulation on the Print-Sum Activity diagram.

4. The simulation will be suspended when pin a or b of the print action is activated. You can hover
your mouse pointer over the active element to see its runtime value.
5. Click the Resume button on the Simulation window toolbar to continue the simulation.

6. The simulation will be suspended again when pin b is activated. Click the Resume button to
continue the simulation. In the Console pane of the Simulation window, you can see the printed
value of 10, which is the summation between 2 and 8.
 Note
If you do not want to display animation (silent simulation), you can create Simulation
Configuration to customize the simulation, select instance as the simulationTarget, and
set silent to true. See Simulating a Simulation Configuration(see page 42) and Simulation
Configuration and UI modeling(see page 46) for more information.
Related pages
• Simulating a Simulation Configuration(see page 42)

• Creating a model for Activity simulation(see page 295)
Activity duration simulation

On this page
• Supported time units(see page 319)

• Duration simulation modes(see page 320)
• Running an Activity simulation(see page 321)
• Duration constraints on Activities(see page 325)
Cameo Simulation Toolkit can simulate the time required to implement an Activity as specified by the
duration constraints. It calculates the total Activity duration by adding the simulation time of all visited
Actions, and aids in accurately identifying which activities take the longest time to complete. You can
see full details about the Activity duration for simulation, including the Activity names and the time
between the start and finish of an Activity, in the Simulation console(see page 200) by setting the Console
log's filter options(see page 205) to Info. An Activity can contain many Actions. You can specify a duration
constraint on any Action in the Activity. The minimum and maximum duration of an Action can be
provided through the min and max of the duration constraint. If you simulate the Activity with a
specific duration mode, Cameo Simulation Toolkit will compute the total time spent when simulating
the Activity for you.
When a Behavior's duration is empty or the time is unspecified, Cameo Simulation Toolkit will use the
duration of called Actions as the duration of the Behavior.
 Note
If a Behavior has a property or a structural feature value named duration, Cameo Simulation
Toolkit will automatically assign the duration value to that particular feature value at runtime.
The duration value property must be defined in the Activity, e.g., Change Color as shown in the
following figure, or the parent of the duration value property. You can have only one duration
value property in the parent Activity to avoid creating multiple duration value properties.

The duration value property is automatically assigned during simulation runtime.
Supported time units

Cameo Simulation Toolkit supports extensive Time Units (suffixes) in duration constraints, as well as
Time Units of Simulation Configuration(see page 49), accept time Event, and others. The following list
summarizes these suffixes
• ns, nsec, nanosecond, nanoseconds

• µs, microsec, microsecond, microseconds
• ms, millisec, millisecond, milliseconds (by default)
• s, sec, second, seconds
• m, min, minute, minutes (All UI, e.g. Charts, CSVExport, etc., will be shown as "min" instead of "m"
for meters.)
• h, hr, hrs, hour, hours
• d, day, days
• wk, week, weeks
• mo, month, months
• y, a, yr, year, years
You can parse the Time Unit specified as a suffix after a number or at the end of an expression string.
However, floating numbers in duration constraints are not supported. Floating numbers are rounded to
integers instead of automatically converted to smaller units. If you do not specify a suffix, the
millisecond will be used by default. The examples are as follows
• 100m or 100min is considered 100 minutes.

• xs is considered the value of the property x in seconds.
• 200 is considered 200 milliseconds.
 Note
• If the Time Unit is less than 1 nanosecond, e.g. 0.5 nanosecond or 0.0005
microsecond, a warning message is displayed in the Console pane stating that the
default value of 1 nanosecond is applied.

• Nanosecond and microsecond are supported only for the simulation clock and
model based clock, but they are not supported for the built-in PC clock because
the returned time of the PC clock using System.currentTimeMillis() is in
millisecond. See also in Simulation time and simulation clock(see page 61).
Duration simulation modes

Cameo Simulation Toolkit supports four duration simulation modes.
Duration Description
Simulation
Mode
Min When you select min as the duration simulation mode, Cameo Simulation Toolkit will
increase the time spent on an Activity by the min duration specified on the duration
constraint when an element with an applied duration constraint is activated.
Max If you select max as the duration simulation mode, Cameo Simulation Toolkit will increase
the time spent on an Activity by the max duration specified on the duration constraint when
an element with an applied duration constraint is activated.
Average When Cameo Simulation Toolkit simulates your model with the average duration
simulation mode, it will use the average value between the max and min duration of the
duration constraint as the duration of time spent on simulating an element with an applied
duration constraint.
Random The random mode allows Cameo Simulation Toolkit to obtain the duration of time spent on
simulating an element with an applied duration constraint from a uniformly distributed
random number between the min and max duration of the duration constraint.
If you specify a duration simulation mode, the time spent on an Activity simulation will be calculated
from the duration constraint applied to the elements of the Activity. The duration of time spent on
simulating elements with no duration constraints will be zero. If you simulate a model without
specifying any duration simulation mode, Cameo Simulation Toolkit will ignore those duration
constraints and obtain the time spent on simulating the Actions and activities from the simulation
clock.
The Duration Simulation modes (min, max, average, and random) are available in the
model's Specification window87. You can specify the duration constraints of the Activity element by
entering the value in the element's Specification window.

Running an Activity simulation
The DurationConstraint.mdzip88 sample is used as an example to explain how the Activity duration
simulation works.
To specify the duration simulation mode and the duration constraints of an Activity, and run the Activity
simulation
1. Either double-click or right-click a «SimulationConfig(see page 49)» (e.g., winter) on the diagram
pane and select Specification to open the Specification window.
2. From the Duration Simulation Mode property, select a duration type (e.g., min). The selected
duration mode will appear in the «SimulationConfig».
3. Click .
4. Open the rainy day scenario on the diagram pane and open the Specification window89 of each
element to specify the duration constraint for the selected duration simulation mode. In this
example, double-click 'dig the snow' and specify the duration constraint value.
88 https://docs.nomagic.com/download/attachments/20851829/DurationConstraint.mdzip?

5. Click .
6. Right-click the «SimulationConfig» or click on the toolbar to run the simulation. View the
simulation results of the Activity duration in the Simulation window(see page 201).

Right-clicking the «SimulationConfig» on the diagram pane to select the
Simulation menu to run the simulation of the «SimulationConfig».
The Run toolbar button triggers the command to run the simulation of
the «SimulationConfig».
The Console tab in the Simulation window contains the simulation of

Activity duration of the DurationConstraint.mdzip sample from start to
finish.
If you simulate a call Behavior Action having a duration constraint with a duration simulation mode and
the time spent on the called Behavior is beyond the range of the duration constraint specified on the
call Behavior Action, the call Behavior Action will be considered as a broken constraint element. Cameo
Simulation Toolkit will then pause the model simulation at the call Behavior Action.

Duration constraints on Activities
Cameo Simulation Toolkit also supports simulation when you define a duration constraint(see page 361)
for an Activity itself apart from a Call Behavior Action. The duration constraint on the Activity is
interpreted the same as the duration constraint on the Call Behavior Action. The duration constraint
can be shown in the Timeline chart or on the Console pane. In the following figure, the duration
constraint is shown on the Console pane.
A duration constraint is applied on the Activity as shown on the Console pane.
 Note
If the duration constraints are defined on both Activity and Call Behavior Action, the constraints
of the Call Behavior Action will be used, and the constraints of the Activity will be ignored.

Glossary
Concept Description
Activity(see page 26) The duration simulation mode specifies the duration to run the
simulation of the elements with applied duration constraints.
Duration constraint(see page 361) The duration constraint is an interval constraint that refers to
a duration interval. Use the duration interval to determine whether
the constraint is satisfied.
Call Behavior Action(see page 332) The call Behavior Action is a call Action that invokes
a Behavior directly rather than invoking an operation that invokes
the Behavior.
Sample model
DurationConstraint.mdzip90
Related pages
• Creating a model for Activity simulation(see page 295)

• Duration analysis(see page 326)
• Duration constraint(see page 361)
Duration analysis
Cameo Simulation Toolkit is capable of calculating the minimum, maximum, and average duration of
any Activity. It uses the values taken from duration constraints applied to each element in an Activity as
the basis to calculate the Activity's duration.
Cameo Simulation Toolkit can perform an analysis of activity duration in the two following scenarios
Duration analysis on visited elements
The duration analysis on visited elements feature is not enabled by default. To enable it, you need a
TimeHandler and register it in the execution listener of the <<SimulationConfig>>. You can create the
TimeHandler by creating a new Class and apply the <<TimeHandler>> stereotype.
90 https://docs.nomagic.com/download/attachments/82762134/DurationConstraint.mdzip?

Enabling duration analysis on visited elements in the <<SimulationConfig>>.
You can view the duration of a running Activity by using the diagram's context menu Analyze
Duration of Visited Elements.
To see the duration of visited elements
1. Pause a currently running Activity by either adding a breakpoint or clicking the Pause button.
2. Right-click the diagram and select Simulation > Analyze Duration of Visited Elements.

Analyze duration on visited elements menu on the diagram context menu.
3. The minimum, maximum, and average duration of the visited elements together with the
simulated trace listing all of the visited elements will appear in the Simulation Console pane.

Duration of visited elements in the Simulation Console.
Related pages

• Duration analysis on executed traces(see page 329)
Duration analysis on executed traces
You can also perform an analysis of Activity duration after an Activity has been simulated. Prior to the
analysis, be sure that the simulation log has been configured and the value of a Record Activation tag
is true (see Simulation log(see page 59) for more information about the simulation log).
To see the duration of a visited element
1. Right-click the simulation log and select Simulation > Analyze Duration of Executed Trace.
The Select Execution Session and Activity dialog will open (see the second figure below).

Analyze Duration of Executed Trace Menu on the Simulation Log Context
Menu.

Select Execution Session and Activity dialog.
2. Select a session and an Activity and click the Calculate Duration button. The result will appear in
the Simulation Console pane.
Duration of executed trace in the Simulation Console pane.
Related pages

• Duration analysis on visited elements(see page 326)
Running a Call Action simulation without a target pin
When Cameo Simulation Toolkit simulates a CallOperationAction that does not have a target pin, it will
select a runtime object, which is the context of the Activity, as a target. For example, a System Class,
which owns a Sub-System Class (see the second figure below), is the context of the SystemBehavior
Activity shown in the first figure. The CallOperationAction will call the SayHello operation using the
Activity context, which in this case is the System Class.
If an Action belongs to an Activity partition, and the Activity partition represents part of a Classifier,
which is a context of that Activity, Cameo Simulation Toolkit will select the runtime object specified by
the part as the target of the Action.
However, Cameo Simulation Toolkit will direct the target object to the callOperationAction only if an
element represented by the Activity partition is a property (or an inherited property) of the Classifier,
which owns the Activity and if there is only one runtime object specified by the property represented by
the Activity partition. For example, if the CallOperationAction that calls the Print operation is in the
Activity partition, which represents the SubSystem property of the System Class, this will result in a call
to invoke the Print operation in the SubSystem property.

Activity System Behavior.
Class diagram describing system Class structure.
Related pages
• Call Operation Action92

• Activity Partition execution and allocated Behavior(see page 332)
Activity Partition execution and allocated Behavior

An Activity Partition is an element in an Activity diagram. It sets the boundary of simulation of an
execution. If a Partition represents a property or a Classifier, all Actions and Activity calls inside the
Partition will be run using the context of the property or the Classifier, which is represented on the
Partition.
If the Activity Partition represents a part/property, the object playing the Partition is the object playing a
part/ property that is represented by the Partition. If the Partition represents an InstanceSpecification,
the object which is initialized from such instance specification shall be the object playing the Partition (if
there is no object initialized from such instance specification yet, Cameo Simulation Toolkit shall
initialized when the Behavior execution of the Activity is initialized.
92 https://docs.nomagic.com/display/MD2021xR2/Call+Operation+Action

When there are multiple objects playing an Activity Partition, only the first object that is not busy shall
be the one that performs the Action in the Partition and it shall be the context of the Behavior
execution invoked by the Action.
The following figure shows an example of the (Activity) system diagram on which a call Behavior
Action is placed within an Activity Partition. The context of the Activity Partition is the runtime objects of
workers. When the system model was run, the call Behavior Action was executed in the context of the
Activity Partition: workers. But since there were more than one worker, the simulation searched for a
worker that was not busy to perform the Behavior. If all the workers were busy, the simulation would
wait until one of them was available. If the call Behavior Action were outside the Activity Partition, the
context of the Behavior execution would be the system itself. The same also goes for an opaque
Action. If it is in the Activity Partition, the simulation will run the opaque Action using the context of the
property or the Classifier represented on the Partition.
Activity Partition simulation.

When a call Behavior Action is in an Activity Partition, the following conditions apply
• If the Behavior of the Action belongs to a Classifier of the object playing the Partition (or super
type of such Classifier), the context of the Behavior execution shall be the object playing the
Partition.
• If the Behavior does not belong to the Classifier of the object playing the Partition, but it belongs
to the Classifier of the object that is the context of the Activity containing the Action (or super
type of such Classifier), the Behavior execution shall be invoked in the context object of the
Activity containing the Action.

• For other cases that cannot be categorized to either (i) or (ii), for example, the Behavior is an
OpaqueBehavior or an OpaqueFunction, the context of the Behavior execution shall be the
object playing the Partition.
Execution of incomplete/dummy models
On this page
• AddStructuralFeatureValueAction(see page 334)

• ReadStructuralFeatureValueAction(see page 336)
• CallBehaviorAction(see page 336)
• CallOperationAction(see page 337)
• SendSignalAction(see page 338)
• ValueSpecificationAction(see page 339)
• StartClassifierBehaviorAction and StateObjectBehaviorAction(see page 340)
• OpaqueAction(see page 341)
Previous versions of Cameo Simulation Toolkit did not support execution of incomplete or dummy
models. From the 18.4 version and above, it will be possible to execute incomplete or dummy models.
Previously, the execution would halt. Now, if any input pin does not have an accompanying value, the
Behavior of the Action will not be to halt execution, instead a null value token will be passed to that pin,
or when simulating a CallOperationAction which does not have a target pin, a runtime object, which is
the context of the Activity will be selected as the target.
The information on this page describes the Behavior of an Action when any of the input or output pins,
or any properties of the Action, are not specified or not present.
 Supported Actions
The Actions which are currently supported are as follows
• AddStructuralFeatureValueAction
• ReadStructuralFeatureValueAction
• CallBehaviorAction
• CallOperationAction
• SendSignalAction
• ValueSpecificationAction
• StartClassifierBehaviorAction and StateObjectBehaviorAction
• OpaqueAction
AddStructuralFeatureValueAction
An add structural feature value Action is a write structural feature Action for adding values to a
structural feature. When any input pin is unspecified or empty, or when a Structural Feature is
unspecified or does not exist, this Action's Behavior will have the rules as follows

• If Object input pin is not specified, the runtime context of the Activity execution will be used as
the target.
• If Value input pin is not specified, this Action will be skipped.
• If Structural Feature is not specified or it does not exist in its own context, then this Action will
be skipped.
If an Object input pin is empty or unspecified, the runtime context of the Activity execution will be used
to add the value to the Structural Feature of the context.

A demo showing the situation if an object pin is unspecified.
ReadStructuralFeatureValueAction
A read structural feature Action is a structural feature Action that retrieves the values of a structural
feature. When any of the input or output pins are unspecified or not present, this Action's Behavior will
have the rules as follows
• If the Object pin is not specified, the runtime context of the Activity execution will be used as the
target.
• If Structural Feature is not specified or if the Structural Feature has no values, then a null
value token will be sent.
A demo showing the situation if an object pin is not specified.
CallBehaviorAction
Call Behavior Action is a call Action that invokes a Behavior directly rather than invoking an operation
that invokes the Behavior. When any of the Argument pins are either unspecified or not present, this
Action's Behavior will have the rules as follows
• If any of the Argument input pins are unspecified, this Action will send a null value token for
that parameter.

• If none of the Argument pins are unspecified, this Action will send null value tokens for all the
Arguments.
• If the Result output pin is specified and this Action does not return any results, it will return a
null value token instead.
A demo showing the situation if an argument pin is unspecified (A null value

token is passed to the pin.).
CallOperationAction
A call operation Action is an Action that transmits an operation call request to the target object, where it
may cause the invocation of associated Behavior. When any input or output pin is unspecified or not
present, this Action's Behavior will have the rules as follows
• This Action will send a null value token for each unspecified Argument input pin.
• In case no Argument pin is specified, this Action will send null value tokens for all the
parameters.
• If the Result output pin is specified and this Action does not return any results, it will return
a null value token instead.
• If the Target input pin is not specified, the runtime context of the Activity execution will be used
as the target.

A demo showing the situation if an argument input pin is unspecified (A
null value token will be passed.).
SendSignalAction
Send signal Action is an invocation Action that creates a signal from its inputs, and transmits it to the
specified target object, where it may cause the firing of a State Machine transition or the execution of
an Activity. When either Argument pin or Target input pin is unspecified or empty, this Action's
Behavior will have the rules as follows
• If there are any incomplete Argument pins, this Action will send null value tokens for those
parameters.
• If Argument pin is not present, this Action will send null value tokens for all parameters.
• If Target input pin is not present, the runtime context of the Activity execution will be used as the
target.

A demo showing the situation when there are incomplete argument pins.
ValueSpecificationAction
A value specification Action is an Action that evaluates a value specification. When the value of a
ValueSpecification Action is not specified, this Action's Behavior will apply the rule as follows
• If the value of a ValueSpecification Action is not specified, a null value token will be passed.

A demo showing the situation when the value of a ValueSpecification Action is
unspecified (A null value token is passed.).
StartClassifierBehaviorAction and StateObjectBehaviorAction

A start Classifier Behavior Action is an Action that starts the Classifier Behavior of the input. If
the Object input pin is not present or empty, this Action's Behavior will apply the rule as follows
• If the Object input pin is not present or empty, the StartClassifierBehaviorAction Action will
use the runtime context of the Activity execution as the target.

A demo showing the situation when the object pin is either not present or
empty.
OpaqueAction
Opaque Actions are a type of Action that can be used to represent implementation information. They
can also be used as placeholder Actions until you determine the specific type of Action to use. If the
opaque Action does not return a value to the OutputValue pin, this Action's Behavior will apply the
rule as follows
• If the opaque Action does not return any value to the OutputValue pin, a null value token will
be passed to the pin at runtime.

If an opaque Action does not return any value to the OutputValue pin, a null
token will be passed to the pin.
 Information
A "null value token" is an ObjectToken with has no values defined.
Dummy tokens of Actions through Output Pins
Simulation Toolkit has an option to support dummy tokens of CallBehaviorActions that do not have a
Behavior. Business-level abstract diagrams can be executed and animated because Simulation will
automatically create new objects according to type of those Output Pins if unspecified, even though this
action will break fUML semantics. You can set the Auto Create fUML Object of Output Pin option
(true by default) in the Environment Options Simulation dialog.

Objects are automatically created according to type of unspecified Output Pins,
e.g., order.
From the figure above, the Output Pin returns an object (ro is order@203c1eec). If the Auto Create
fUML Object of Output Pin option is set false, the Output Pin will have no value.
To set the Auto Create fUML Object of Output Pin option
1. From the main menu, click Options > Environment. The Environment Options dialog opens.
2. On the left pane, click Simulation.
3. Under the fUML Engine group, set the Auto Create fUML Object of Output Pin option to true.
4. Select OK.

The Auto Create fUML Object of Output Pin option in the Environment
Options Simulation dialog.
Related pages
• Execution of incomplete/dummy models(see page 334)

Using utility functions of Simulation

Simulation provides some utility functions to facilitate common tasks, e.g., running command line and
text file replacement. Those utility functions are encapsulated in Opaque Behaviors under
SimulationProfile::library::utils as shown in the figure below.
 Note
If the SimulationProfile package is not visible, click in the Containment tree pane and
select Show Auxiliary Resources.

CommandLine, one of the utility functions of Simulation, is used through
Opaque Behaviors in SimulationProfile::library::utils (shown in the circled area).
You can use those Opaque Behaviors by dragging them to the Activity diagram and setting parameters
as described in the Opaque Behavior93 section. Simulation also provides a few samples using the
Activity diagram in the utils package. As displayed in the figure below, you can use
WindowsCommandLine to open Notepad on Windows.
93 https://docs.nomagic.com/display/MD2021xR2/Opaque+Behavior

Using WindowsCommandLine to open Notepad on Windows.
From the following figure, you can use TextFileReplace to open the build_me_a_HAB.ses file
and replace $press_tunnel_len$ with 2.0. See also the UsingCommandLine.mdzip built-in sample in
Simulation on the Welcome page.

Using TextFileReplace to open the build_me_a_HAB.ses file and replace
$press_tunnel_len$ with 2.0.
Streaming Activity simulation
On this page
• Specifying parameter streaming rate(see page 350)

• Streaming Activity animation(see page 351)
You can model either non-streaming or streaming behaviors. Non-streaming behaviors consume their
input object tokens at the moment they begin executing and deliver their output object tokens when
they finish executing. If a system receives inputs and produces outputs even while behaviors continue
to execute, this is referred to as a streaming behavior.
An Activity with streaming parameters is terminated in the following cases:
• An Activity whose only streaming parameters are output parameters is terminated once all of its
actions finish executing.
• An Activity with streaming input parameters is terminated by an Activity final node or if the
execution is explicitly terminated by the Activity that invoked it.
• If the Terminate Streaming Behaviors by Output Parameter Multiplicity project option (or
Simulation Configuration property), is set to true, an Activity with streaming output parameters
terminates when each of its output parameters receives a cumulative number of values equal to
the upper bound of the parameter multiplicity.

Non-streaming vs streaming behavior.
You can model a streaming behavior by setting the parameter of a Pin or Activity Parameter Node as
streaming.
To set a parameter as streaming
• In the Specification window of a Parameter of a Pin or Activity Parameter Node, set the Is Stream
property to true.

Setting a parameter as streaming.
 Streaming parameter multiplicity

We recommend specifying the multiplicity of [1..*], [*], or [0..*] if you want to get an unlimited
number of tokens. Otherwise, the streaming input parameter stops receiving tokens when it
reaches the upper bound of multiplicity.

Specifying parameter streaming rate
Streaming rate is the number of objects or values that flow in or out of the parameter per time interval
while the behavior or operation is executing. You define input or output parameter streaming rate by
specifying the Rate property which determines the expected rate at which tokens can arrive at or leave
a Pin or Activity Parameter Node.
To specify streaming rate
1. Create an Instance Specification and name, e.g., 3 per min.

2. Open the Specification window of the Instance Specification and set the Specification property
to the number of objects or values that flow in or out of the parameter per time interval, e.g., 3.
3. Set the Instance Specification (created in step 1) as the value of the Rate property both for a Pin
(or Activity Parameter Node) and for the parameter of that Pin (or Activity Parameter Node).
4. Open the Specification window of the Simulation Configuration and specify the Time
Unit property by selecting the time interval per which the selected number of objects or values
flow in or out of the parameter. If the Time Unit is not specified, a second is used as the default
time interval.
Once you define parameter streaming rate, object tokens flow at fixed time intervals. This means that
the specified time interval (step 4) is divided by a specified number of tokens (step 2). For example, if
streaming rate is 3/min, object tokens are passed at fixed time intervals of 20 s. If a token does not
arrive at the specified time, then that time interval is skipped and object token is passed only after the
next fixed time interval. If there are more object tokens than an Action can accept, they wait in a
corresponding Pin and are passed after the next fixed time interval.
 To display streaming rate in a diagram

1. Right-click a Pin or Activity Parameter Node and select Symbol Properties.
2. In the Symbol Properties dialog, set the Show Tagged Values property to true.

Streaming Activity animation
The Activity Diagram below shows an example of a streaming Activity where the Manufacture, Paint, and
Dry Actions can be executed simultaneously. In this example, the Manufacture action has already
finished executing and is annotated in green (visited element). The Dry and Paint Actions are executing
simultaneously and are annotated in red (active elements). Note that you can control the held token
display (annotated as red bubbles with the number of waiting tokens) in the Project Options dialog or
Simulation Configuration properties.
The execution of this Activity will not terminate even when all the Actions finish executing.
An example of a streaming Activity
The following chart displays the timeline of the fully executed streaming Activity displayed above.

The timeline chart of a streaming Activity Diagram.
Interaction simulation
Cameo Simulation Toolkit comes with an interaction engine that can simulate an interaction element
based on the UML semantics. An interaction is a unit of Behavior that focuses on information exchange
among internal properties of a Class. You can use it to describe the main Behavior of the Class by
specifying the interaction as a Classifier Behavior of the Class. You can also assign it to be a method of
an operation of the Class. If an interaction is a Classifier Behavior, it will be simulated whenever the
object is started. If it is a method of an operation, it will be simulated when the operation is called.
Supported elements in interaction simulation
Elements supported in interaction simulation include the following items:

• Lifeline
(see page 353)Locating the sources and targets of Messages.
• Message
(see page 357)Signal, Call, and Reply Messages indicating communication between Lifelines of
Interaction.
• CallEvent
(see page 360)Used when Operations are called without Methods.
• Duration constraint.
(see page 361)Delaying delivery of two Messages run consecutively.
• Time constraint
(see page 363)As timestamps when recording simulation.
• State invariant
(see page 363)Validating whether current States are true.
• Test case verdict

(see page 365)As generated values in the Behavior return parameter.
• Combined fragment(see page 366)

A combination of Interaction fragments as choices of Behaviors and loops.
Lifeline
On this page
• Lifeline selector(see page 356)
You can use a lifeline in a Sequence diagram to represent a property owned by a Class or a block that is
the context of the diagram. Sending messages between objects specifying the properties presented by
the lifelines can occur. Cameo Simulation Toolkit uses lifelines to find a source and a target object of
the message.

Simulation console showing how lifelines can be used to find the source and
target of a message.
You can use a lifeline in a SysML project to represent a nested property of a Class or a block, which is
the context of a diagram. A path to the nested property appears as a dot notation on the lifeline
symbol. Cameo Simulation Toolkit uses the path on the lifeline symbol to find the object.
 Note
Cameo Simulation Toolkit uses a lifeline with a dot notation to represent a nested property
when you record a simulation as a Sequence diagram. See Recording a Simulation as a
Sequence Diagram(see page 387) for more information about recording a simulation.

Simulation console showing how a lifeline with a dot notation can represent a
nested property.
Because Messages recorded in the system are not executed that they are internal mechanisms, Cameo
Simulation Toolkit only executes Messages that are external to the system, e.g., a Message going from
User Lifeline (without types) and Found Messages. All other Messages are not executed but verified and
printed in the Console pane.
 Information
A Found Message is a Message where the occurrence of a receiving Event is known, but the
occurrence of a sending Event is not.

Executing only external outgoing Messages, e.g., User Lifeline and Found
Messages.
Lifeline selector
If a lifeline represents a part with the multiplicity of more than 1 (neither * nor 1..*), the list will also
contain more than one object (not only one object) at runtime. The lifeline has the Selector expression
that specifies the particular part represented by the lifeline.
Cameo Simulation Toolkit supports the lifeline selector which allows specifying an exact object from the
Selector expression. The Selector expression will be evaluated as an index integer to get an Object from
the object collection.

The ledger[3] object is selected according to the index integer of lifeline Selector 3 of the Ledger object.
If the selector of a receiver is invalid or cannot be evaluated as an index integer, e.g., "X", none of the
objects will be used, and a warning message will display in the simulation console.
Message
On this page
• Asynchronous Signal Message (asynchSignal)(see page 358)

• Synchronous Call Message (synchCall)(see page 358)
• Asynchronous Call Message (asynchCall)(see page 359)
• Reply Message (reply)(see page 360)

According to the UML specification, a message defines a particular communication between lifelines of
an Interaction. Cameo Simulation Toolkit simulates messages whose message sorts
are asynchSignal, synchCall, asynchCall, and reply. You can specify a connector for the message. If
the role of one connector end is the property specified by a source object of the message, Cameo
Simulation Toolkit will send the message along the connector. A target object will be the object at the
other end of the connector.
Asynchronous Signal Message (asynchSignal)

Cameo Simulation Toolkit simulates an asynchronous signal message by creating a signal object from a
signal specified as a signature of the message. It sends the signal object to a target object
asynchronously. The following figure shows that the bank sent the signal maintain to the teller using
an asynchronous signal message. When the target object (the ATM object specifying the teller) received
the signal, the State changed to Maintained.
Simulation console showing the simulation of an asynchronous signal message.
Synchronous Call Message (synchCall)

When executing a synchronous call message, Cameo Simulation Toolkit simulates a Behavior (the
method of called operation of a target object) from beginning to end before it can carry out the next
message. The simulation method is similar to that of the call operation Action with "isSynchronous =
true".
You can substitute values for input parameters of the called operation by specifying argument values
on a synchronous call message.

Simulation console showing the execution of an asynchronous call message.
The preceding figure illustrates the synchronous call messages simulation. A synchronous call
message 1 shows the bank object calling the operation retrieveAccount(accountNumber : String) of
the ledger object. The substitution value for accountNumber is the value of lookupAccountNumber,
which is 0003 in this example. lookupAccountNumber is the property of the bank.
The simulation looked for the account object with that particular accountNumber and returned it to
the bank object with a reply message 2 (2 is a reply message of 1). The returned account object would
be specified as the value of the buyerAccount represented by the lifeline buyerAccount:Account. The
bank object would then call the operation getBalance() of the account object with a synchronous call
message 3 that caused the balance value to reply to the bank with a reply message 4 (4 is a reply
message of 3). Finally, the bank called itself to print the balance value with the
operation printBalance(balance:Real).
Asynchronous Call Message (asynchCall)

The simulation of an asynchronous call message is similar to that of a synchronous call message. In this
simulation, Cameo Simulation Toolkit simulates a Behavior (a method of a called operation of a target
object) on a new thread. Cameo Simulation Toolkit will immediately proceed to the next message once

the simulation of the Behavior starts. It will not wait until the simulation of the Behavior completes. This
type of simulation is similar to that of a call operation Action with "isSynchronous = false".
Reply Message (reply)

A reply message is a message sent as a reply to a call message (synchronous or asynchronous). If there
is an argument value specified in the reply message, Simulation will evaluate the argument value.
 Note
You can stop the execution at breakpoints by setting the Constraint Failure As Breakpoint
option(see page 49) to true in the «SimulationConfig»(see page 49).
If the argument is not the name of a property, Simulation will verify (compare) the returned value from
the called operation with the argument value.
If the result of evaluating the argument is the name of a property owned by a target object, a context
object, or a source object, the value returned from the operation will be defined as the value of that
property. The reply message 2 in the preceding figure has an opaque expression whose body is
buyerAccount as an argument value.
buyerAccount is the property of the Balance Lookup Class which is the context of a sequence
diagram. Therefore, the returned account object from the operation of the ledger
object retrieveAccount(accountNumber : String) will be set as a value of the
property buyerAccount when the reply message 2 is simulated.
CallEvent
A CallEvent is a type of Event in UML elements supported by Cameo Simulation Toolkit. A CallEvent of
an Operation is triggered when you call an Operation with a specified Method. If an Operation is called
without a Method, the CallEvent will be automatically generated. You can use the CallEvent on
AcceptEventActions and Transitions as shown in the following figures.

A CallEvent on the AcceptEventActions of Actions.
A CallEvent on the Transitions of States.

Related pages
• Accept Event Action94

• Transition95
Duration constraint
Simulation allows you to evaluate duration constraints between Call Messages and Reply Messages,
e.g., you can specify that a Call Message must get a Reply Message in 500 ms, so the actual duration of
operation method execution must be compared with the duration constraint of 500 ms. The
comparison is done as an evaluation of the constraint and will generate a fail value for testcases or stop
94 https://docs.nomagic.com/display/MD2021xR2/Accept+Event+Action
95 https://docs.nomagic.com/display/MD2021xR2/Transition

at breakpoints on the Constraint Failure As Breakpoint option(see page 49). However, it does not
support the delay time of a message.
The default time unit of the duration constraint is millisecond (ms), but you can also use other time
units by specifying them after the duration value, e.g., you can use 10s to denote 10 seconds. If you
specify both the minimum and maximum values, Simulation will use the maximum value of the
duration constraint to delay the delivery of a Message.
A Sequence diagram showing how a Duration Constraint {500} can be used to

evaluate between the Call Message and Reply Message.
The figure above shows that cons sends a Call Message to bank to verify an account (12345678) with an
expected duration constraint of 500 ms from the Reply Message. The evaluation in the first run is failed
because the actual duration (431 ms) is less than 500 ms, while another run passes because the actual
duration (710 ms) is greater than 500 ms.
Related pages

• Message(see page 357)
Time constraint
You can specify a time constraint in Messages in the Sequence diagram. During simulating an
interaction, Simulation Toolkit checks if the active State contains the required State (State Invariant(see
page 363)), and the time is exactly as specified (Time constraint). However, the time constraint is not
used as the delay time.
Related pages
• Duration constraint(see page 361)

• Sequence diagram97
State invariant
A State Invariant is one of the UML elements. It is a runtime constraint applied to a lifeline in a
Sequence diagram to specify conditions that are always true when a State is a current State. It is used
to validate States. You may also specify State Invariants in the States directly. State Invariants on
lifelines resolves variables in the same order as it does in message arguments.
When Cameo Simulation Toolkit runs a State Invariant in a model, it also evaluates its constraints. If the
constraints are not satisfied, the evaluation will fail or return false and Cameo Simulation Toolkit will
stop simulation (if "ConstraintAsBreakpoint" is set to true) at that invalid constraint or point. However,
you can still continue the simulation to the next point. You can define constraints using any of the
supported languages in Cameo Simulation Toolkit. State Invariants are used mostly in Interactions, but
you can also use them in a State Machine diagram.
97 https://docs.nomagic.com/display/MD2021xR2/Sequence+diagram

A State Invariant containing constraints being evaluated during execution.
Cameo Simulation Toolkit supports duration constraints between State invariants. The following figure
shows the duration constraint, e.g., from playing to playing takes 5,000 ms of the total simulation time.

Duration constraints between State invariants are supported.
Time constraints of State invariants will be checked if right States are activated at the right time. When
States change, Cameo Simulation Toolkit will check if active States contain required States, and time is
exactly as specified in the constraints. If failed, an error message of the time constraints will be printed
in the Console pane with the value, time unit, and State invariant name with hyperlinks accordingly, as
shown in the figure below.
The time constraint of the State invariant is checked against the simulation
time.
Related pages
• Lifeline(see page 353)

• Sequence diagram98
Test case verdict
A testcase is one kind of Behavior Classifier. It can be a class, Behavior, activity, or operation. Since a
test case is a SysML element, you need to load a SysML profile into your model to run it. Cameo
Simulation Toolkit supports testcase verdicts.
A verdict kind is an Enumeration value in SysML. It can be error, inconclusive, pass, or fail. Cameo
Simulation Toolkit automatically assigns either Pass or Fail as the verdict value to a Testcase. If a
constraint in the test case (pre/post conditions, state invariants) is not satisfied in a model execution,
98 https://docs.nomagic.com/display/MD2021xR2/Sequence+diagram

Cameo Simulation Toolkit will automatically generate a fail verdict value for the Behavior return
parameter, terminate the Behavior simulation, and return the value.
If the "constraint as a breakpoint" option is used in the simulation, whenever the constraint fails,
evaluation will stop and will be highlighted in the model, and you will see the message in red in
the Variables pane. The requirement will be highlighted as well so that you can see what is wrong and
navigate to the requirement.
Cameo Simulation Toolkit will generate a Pass verdict value after the simulation terminates if there is
no constraint fails. If a constraint fails, the simulation will pause, and you will get a Fail verdict value in
the Console pane, but you can always resume the simulation afterwards.
Simulation console showing constraints that have been evaluated.
Related page
• Supported SysML elements(see page 480)
Combined fragment
On this page
• Alternative (alt)(see page 367)

• Option (opt)(see page 367)
• Loop (loop)(see page 368)
A Combined fragment is a combination (expression) of Interaction fragments defined by an Interaction

operator and corresponding Interaction operands. A Combined fragment may have Interaction
constraints, also called guards.
Cameo Simulation Toolkit supports three major Interaction operators: Alternative (alt), Option (opt),
and Loop (loop). Combined fragments with various Interaction operators will also be supported (e.g.,
alt inside loop, opt inside loop, loop inside alt, etc.).

Alternative (alt), Option (opt), and Loop (loop) are supported in Interaction
fragments.
Alternative (alt)
The Interaction operator alt signifies that the combined fragment represents a choice of Behavior. Only
one of the operands will be chosen. The chosen operand must have an explicit or implicit Guard
expression evaluated as true at a particular point in the Interaction. An implicit ‘true’ Guard is applied if
the operand has no Guard.
An operand guarded by else means a Guard that is the negation of the dis-junction of all other Guards.
If none of the operands has a Guard evaluated true, none of the operands are executed, and the
remainder of the enclosing Interaction fragment is executed.
Option (opt)
The Interaction operator opt signifies that the combined fragment represents a choice of Behavior
where either the (sole) operand happens or nothing happens. An option is semantically equivalent to
an alternative combined fragment where there is one operand with non-empty content, and the second
operand is empty. An implicit ‘true’ Guard is applied if the operand has no Guard.

Loop (loop)
The Interaction operator loop signifies that the combined fragment represents a loop. The loop
operand will be repeated a number of times. Only an Interaction constraint (not iteration bounds), a
Boolean expression shown in square brackets that guards an operand in a combined fragment, is
supported.
 Note
Any Guard that is not Boolean expression evaluation will show a Question dialog box to set the
evaluation result true or false. See also using Guards on Transitions(see page 262).
Related pages
• Using Guards on Transitions(see page 262)

• Operators(see page 438)
Creating a model for interaction simulation
You can simulate an Interaction element, a (UML or SysML) Sequence diagram, or a Classifier whose
Classifier Behavior is defined by an Interaction. This section demonstrates how to create a simple
executable Interaction model through the following steps
• Create a Class containing two properties typed by different Classes.

• Create an opaque Behavior, owned by one of the two properties of the Class specified in (i), for
printing the summation of two Integer input parameters.
• Write a script to print the summation of the two input parameters.
• Create an operation, owned by the properties specified in (i), and specify the opaque Behavior in
(ii) as its method.
• Create an Interaction as the Classifier Behavior of the Class specified in (i).
• Create call message to call operation specified in (iv) by another property.
To create a Class containing two properties typed by different Classes
1. To create a new UML project, click File > New Project on the main menu. The New
Project dialog will open.

2. Select UML Project from the General-Purpose Modeling group and specify the project's name,
e.g., 'SimpleSequenceExecution'.
3. Specify the location where you want to save your project file and click OK.
4. Right-click the Model node in the Containment tree and select Create Element > Class. A new
Class element will be created. Name the created Class, e.g., 'System'.
5. Create two more Classes and name them, e.g., 'a' and 'b.
6. Right-click the System model in the Containment tree and select Create Element > Property to
create property for the Class. Name the property, e.g., 'a1'.

7. Right-click a1 and select the Specification window. Select A as the property type.
8. Repeat step 6 to create property b1 of type B (see the following figure).

To create an opaque Behavior, owned by one of the two properties of the Class specified in ( a Class
containing two properties typed by different Classes(see page 368)), to print the summation of two Integer
input parameters
1. Right-click the Class B and select Create Element > Opaque Behavior. Name the opaque
Behavior, e.g., 'Add'.
2. Right-click the opaque Behavior Add and select Create Element > Parameter to add a
parameter element to the opaque Behavior. Name the parameter, e.g., 'par1'.

3. Right-click the parameter par1 and select the Specification window. Select Integer as the
parameter type.
4. Repeat Step 2 to create another parameter and name it, e.g., 'par2' of type Integer.
To write a script to print the summation of the two input parameters
• Open the Specification window of the opaque Behavior Add and write a script in the Body field
(you can use any scripting language that is supported by MagicDraw Macro Engine, e.g.,
BeanShell, Groovy, JavaScript, Python, or Ruby). In this example, JavaScript is used:
print(par1+par2); to print the summation of the two Integer parameters par1 and par2.

The Specification window of an Opaque Behavior.
To create an operation owned by the properties specified in (Class containing two properties typed by
different Classes)(see page 368), and to specify the opaque Behavior as in (opaque Behavior owned by one
of the two properties of the Class(see page 0)) as its method
1. Right-click B and select Create Element > Operation to add an operation element to the
Class. Name the operation, e.g., 'Add'.

2. Right-click the operation Add and select Create Element > Parameter to add a parameter to the
operation element. Name the parameter, e.g., 'par1'.
3. Right-click the parameter par1 and select Specification. Select Integer as the parameter type
and in as the parameter direction. The Specification window of parameter par1 will be as follows

4. Repeat Step 2 and 3 to create another parameter. Name it, e.g., par2 of type Integer,
having in as its direction. The parameters associated with the Operation will be as follows
5. Right-click the operation Add and select Specification. The Specification window will open.
6. Select the opaque Behavior Add as the Method of the operation. The Specification window of
the Opaque Behavior will be as follows

The parameters associated with an Operation in the Containment tree will be as follows.
To create an Interaction as the Classifier Behavior of the Class specified in (the Class containing two
properties typed by different Classes(see page 368))
1. Right-click System and select New Diagram > Sequence Diagram. Select all properties in
the Display Lifelines dialog and click OK.

2. Right-click the Class System in the containment browser and select Specification to open
3. Make sure that the Interaction System is the Classifier Behavior of the Class System.

To create a call message to call the operation specified in (operation owned by property(see page 373)) by
another property
1. Double-click the Interaction System to open the Sequence diagram containing two
lifelines: a1 and b1.
2. Select Call Message from the Diagram Modeling Elements toolbar and create a call message
from a1 to b1.

|
3. Double-click the call message created in Step 2 to open the Specification window and select the
operation Add as the Signature(operation) of the call message.
4. Select Argument on the left-hand side of the dialog to specify a value of the element. Type,
e.g., 4 and 5 as the values of parameters par1 and par2 respectively. The Specification window of
a call message showing its Arguments tags will be as follows

A Sequence diagram showing a call message between two lifelines will be as follows
Related pages
• Class(see page 32)

• Supported elements in interaction simulation(see page 352)

Executing an interaction model
This section illustrates the steps to simulate the interaction model mentioned in section Creating a
Model for Activity Simulation(see page 295).
To simulate the interaction model in section Creating a model for Activity simulation(see page 295)
1. Right-click the package Model in the containment browser and select Create
Element > Package. Name the package, for example, InstancePackage. The following figure
shows the Containment tree containing the objects within its hierarchy.
2. Right-click the InstancePackage and select Create Element > Instance Specification. Name
the instance specification, for example, Sys. The following figure shows the creation of an
InstancePackage element from its shortcut menu..

3. Right-click the instance specification Sys and select Specification to open the specification
dialog.
4. Click the browse button in the Classifier row to open the Select Elements dialog (see the
first figure below) and select class System as the classifier of the instance specification Sys (see
the second figure below).

The following figure shows the elements that can be selected in the Select Elements dialog.

5. Repeat steps 2 and 3 above to create the other instance specifications named aa1 and bb1 of the
classifiers A and B respectively. The following figure shows the Containment tree depicting
objects within its hierarchy.

6. Right-click the instance specification Sys and select Simulation > Run (see the first figure below).
The Simulation window will appear.

7. Click the Start button in the Simulation window.

The Simulation Console shows the results of a simulation and the constraints which have passed
or failed.
Recording simulation as a Sequence diagram

The recording capability of Cameo Simulation Toolkit allows you to:
• record created objects as CreateMessages connected between Lifelines that represent the object
creator and features of the created object respectively.
• record signals as SendMessages connected between Lifelines that represent signal senders and
signal receivers respectively. Connectors will be assigned to the messages if signals are sent via
ports or connectors.
• record operation calls as CallMessages connected between Lifelines that represent operation
caller and operation owners respectively. Connectors will be assigned to messages if operations
are called via ports.
• record changes of states and primitive values as StateInvariants on Lifelines that represent
features of objects that own the states or the values.
This section demonstrates how to record signal, state change, operation call, and value change as a
sequence diagram during a model simulation. The sample StereoSystem.mdzip, located in
the <md.install.dir>/samples/simulation/ directory, will be used throughout this section.
To record signals sent from and to a runtime object and subsequent state/value changes of the related
objects as a sequence diagram
1. In the Variables pane, select and right-click a runtime object.

2. Click Create Sequence Diagram on the context menu (see the following figure). An empty
sequence diagram will be created.

Shortcut menu that can be accessed from the simulation console.
Whenever you simulate a model (for example, Stereo System as shown in the figure above, Cameo
Simulation Toolkit will
• create the first Lifeline, which represents the selected runtime object.
• record each signal sent from the selected runtime object as a Message in the sequence diagram.
• record each operation call caused by a call message, a CallOperationAction, or a
ALH.callOperation with argument and return value as messages in the sequence diagram.
• record an object that receives a signal and(or) an operation call as a Lifeline, unless it exists in the
diagram, the object will be called 'lifeline object'.
• record each change in the state of a lifeline object as a StateInvariant on the Lifeline, with the
changed state symbol.
• record each change in the feature value of a lifeline object as a StateInvariant on the Lifeline.
Changes in value are enclosed in constraint brackets, for example, {a=10}.
 Note
StateInvariants are designated by yellow rounded rectangle symbols. See the following figure
for examples.

A sequence diagram depicting call messages running between lifelines.
To see what connector a signal or an operation call is sent through
• Double-click the message or right-click it and select Specification to open the specification
window.
To see the values of arguments sent with a signal or an operation call
1. Either double-click a message or right-click it and select Specification to open the specification
window.

2. Select Arguments in the tree on the left-hand side of the specification dialog to see the value of
each argument.
You can customize recorded messages (signals) and lifelines using
a SequenceDiagramGeneratorConfig.
A SequenceDiagramGeneratorConfig element showing its parameters.
A SequenceDiagramGeneratorConfig is a stereotype that is inherited from

an ExecutionListener stereotype. It contains the following six tag definitions:
• owner
It is an element that owns a generated Interaction element. A generated Sequence diagram will
be created under that particular Interaction element. You need to select only the element that
can own an Interaction element, otherwise a model inconsistency will occur.
• ignoredSignals
They are signals that will be ignored (will not be recorded) during a simulation recording.
• ignoredLifelines
They are a list of elements (objects) that will be ignored (will not be recorded as lifelines) during a
simulation recording. This list takes priority over the value list.
• recordedObjectPath
It is used to specify a property path to an object that will be recorded by a sequence diagram
generator. The path must start from a property owned by either a classifier, which is the target of
the simulation configuration or a classifier of an instance specification, which is the target of the
simulation configuration. The property at each successive position following the first position
must be contained in the classier that types the property at the immediate preceding position.
• recordStateChange
This is a boolean option. If true, state changes will be recorded.
• recordValueChange
It is a boolean option. If true, value changes will be recorded.

• recordTimestamp
It is a boolean option. If true, timestamps will be recorded on messages.
• value
Structural feature which value is represented for the configuration.
You can specify the default values of recordStateChange, recordValueChange,
and recordTimestamp through the Project/Environment Options(see page 47) dialog. The values in
the project options will be used instead if the tagged values of the sequence diagram generator are not
specified. The default values of these project options are true, true, and false (see the following
figure). True means all values will be recorded by default.
Options in the Sequence Diagram Generator group in the Project Options dialog.
To customize a Sequence diagram recording
1. Create a Simulation Configuration Diagram by doing one of the following:
• In the Containment tree, right-click the Model folder (root folder) and select Create
Diagram.

• On the main menu, select Diagrams > Create Diagram.
Under the Simulation group, choose Simulation Configuration Diagram.

2. From the Simulation Configuration Diagram palette, drag Sequence Diagram Generator to
the diagram.

3. Right-click the newly created SequenceDiagramGeneratorConfig and select Specification to
open its Specification dialog.
4. Specify the value(s) of the tag definition(s) of the config, e.g., Name.

 Tip
You can specify Represents and Value to be captured by the
SequenceDiagramGeneratorConfig along with other settings, e.g., RecordTimestamp.

5. Drag the configured SequenceDiagramGeneratorConfig to the SimulationConfig element (see
SimulationConfig stereotype(see page 49)). The executionListeners tag of the SimulationConfig
will be shown with the specified name of the SequenceDiagramGeneratorConfig as shown
below.

Use Case simulation
You can use Cameo Simulation Toolkit to simulate a Use Case model or diagram. This section illustrates
the steps to simulate the Use Case model.
To simulate a use case model
1. Create a use case diagram. See the following example of a Use Case diagram. The figure shows
the Use Case diagram in a block (a subject can be either a block or a class).
2. Either right-click the Use Case diagram in the Containment tree and select Simulation > Run
or click on the diagram toolbar to run the model. The classifier behaviors in the Use Case
diagram are run during simulation. Cameo Simulation Toolkit creates a window to represent
each Actor in the diagram (the preceding figure shows four actors: Worker1, Worker2, Worker3,
and Worker4.
3. You can click the button, which represents what Use Case the Actor can perform, in each window
to simulate it (the following figure shows the buttons Change Color and Paint).
 Note
The Block connected by the Association with a Use Case is shown as an Actor, e.g.
Worker3, so any Use Cases connected are shown as buttons in the GUI window of the
Actor. Also, the image of the Block is shown according to the selected Image above the
list of Use Case buttons.

The following figure shows the Actor's name and title, and the buttons (Change Color, Paint)
representing the Use Cases the actors can perform. Once you click the button, Cameo Simulation
Toolkit uses the subject (Worker1, Worker2, Worker3, and Worker4) as the context to access the
Classifier Behaviors of the Use Case diagram or read the values of the properties. If the Use Case
has no subject, Cameo Simulation Toolkit will run the Classifier Behavior of the Use Case. You can
change the values of the properties in the Variables pane. You can import an image to represent
an Actor through the Actor Specification window99.
Actions associated with actors within a Use Case diagram.
Parametric evaluator
Cameo Simulation Toolkit comes with the parametric evaluator to help you solve constraint
expressions in your model. The parametric evaluator is designed to work with the SysML Parametric
Diagram. But, you can also use it to solve constraints on any UML classes. With the parametric
evaluator, you can define a mathematical or a logical expression as a constraint on a block or a class to
limit the values of its properties. If the expression is an equation, the parametric evaluator will evaluate
the expression of the constraint and update the values of the properties with the result of the

evaluation. If the expression is a logical expression, the parametric evaluator will use the expression to
validate the values of the properties.
Specifying the language for the expression
The parametric evaluator only evaluates expressions that are written in the syntax it supports. By
default, the parametric evaluator uses the built-in math to solve expressions. The built-in math uses a
syntax that is similar to the Octave syntax (see Built-in Math(see page 434) for more information about
built-in math). You can also write an expression using a scripting language that is supported by
MagicDraw.
You can specify a scripting language to evaluate an expression through the Specification dialog of the
opaque expression, which is the specification of the constraint.
To specify the language to evaluate an expression in the Specification dialog
1. Right-click an opaque expression in the Containment tree and select Specification.

The Specification dialog of the opaque expression will open (see the following figure).

2. Click the row next to the Language option to open the text box and enter the name of the
language you want.
3. Click Close to close the dialog.
You can also select the language for constraints on a SysML constraint block through the context menu
on the constraint block or a constraint property typed by the constraint block (see the following figure).
To select the language for the constraint of a SysML constraint block
1. Right-click a SysML constraint block or a constraint property typed by the constraint block on the
diagram.
2. Click Language and select any supported language to evaluate constraint blocks from the list.
The language of the Default Parametric Evaluator in Cameo Simulation Toolkit is Built-in Math.
Therefore, it will use Built-in Math to evaluate an opaque expression whose language is not specified.
You can see the Default Parametric Evaluator language option in the Parametric Evaluator group in
the Project Options(see page 47) dialog.

The Default Parametric Evaluator option in the Parametric Evaluator group in
the Project Options dialog.
You can also specify the duration you want to wait for the parametric evaluator to evaluate an
expression. The timeout value is specified in second. If, for example, the timeout value is 15, the
parametric evaluator has 15 seconds to evaluate a given expression. If it cannot give you the result
within 15 seconds, it will stop evaluating the expression.
Related pages
• Value binding(see page 405)

• Evaluating expressions(see page 413)
• Evaluation with causality(see page 421)
• Dynamic constraint(see page 426)
• Manual value updates using the Parametric Evaluator(see page 430)
• Communicating with evaluators through simulation console(see page 432)
• Built-in Math(see page 434)
• Integration with external Evaluators(see page 449)
• Trade study analysis(see page 666)
• Sample project(see page 475)

Automatic and manual initialization of objects/values
The Solve After Initialization option allows modelers to control initialization of objects and values
automatically or manually from the initial parametric constraints solving. This flexibility improves the
parametric debugging experience. You can select the option through the Specification window of the
Simulation Config, or by clicking Environment > Simulation > Solve After Initialization as shown in
the following figure.
The Solve After Initialization option can initialize objects and values
automatically.
The value of the Solve After Initialization option is true by default to enable automatic initial solving.
If you wish to manually invoke initial solving, you can do so by clearing the check box (the value will
change to false), clicking Refresh in the Variables pane, or pressing Start (F8).
To invoke initial parametric solving manually:
1. Open/create a project with a parametric diagram.

2. In the Simulation Config, set the “Solve After Initialization” and “Auto Start” option to false (see
the following figure).

3. Run simulation via the Simulation Config. All related results will not be calculated automatically,
so you need to manually invoke it via the Refresh in Variables pane or Start (F8) (see the following
figure).
4. Select true for the Solve After Initialization option, and run the Simulation Config. All related
results will be calculated automatically (see the following figure)

Value binding
Value binding is the method to maintain values of properties, which are bound together, to be the
same. The properties whose values are bound, must be connected together with a connector. The type
of the properties which are bound together must be the same or one is a subtype of another. If the
type of the properties is a primitive type, you can bind them with either a UML connector that does not
have a type, or a SysML binding connector with a «BindingConnector» stereotype applied. If the type of
the properties is a class or a block, you can only use a SysML binding connector to tie them.
Related pages
• Specifying the language for the expression(see page 400)

Primitive value binding

Primitive value binding connects two value properties or properties that are typed by a primitive type
so that whenever the value of one property changes, the value of the other property will also change.
Cameo Simulation Toolkit maintains the values of those connected properties to be the same at both
ends. Changing the value at one end causes Cameo Simulation Toolkit to update the value of the

property at the other end of the connector. The figures below show the primitive value binding with a
SysML binding connector and a UML binding connector respectively.

Simulation console showing the execution of blocks.
Simulation console showing the results of a simulation.
Object binding
If a binding connector connects properties that is typed by either a class or a block, the runtime value
that specifies each property will be the referent of the same block object. Since you can use only a
SysML binding connector to bind objects, the SysML plugin is required.

Object Binding with a SysML Binding Connector.
Binding in a complex aggregate structure

A binding connector connecting deep nested properties in a block must apply a stereotype
«NestedConnectorEnd» at both ends and specify the propertyPath (see Nested Connector end(see page
495) for more information about the nested connector end). If there are multiple values specify a
property in the propertyPath (the upper bound of the multiplicity of the property is greater than 1 or is
infinite), Cameo Simulation Toolkit will construct a value list at each end of the connector and maintain
the values in the list. You can use (IsOrdered = true) to order each property in the propertyPath to
ensure that the order of values on the list remains the same.
The following figure illustrates an example of binding where the aggregate structure is complex. It
shows an executable InstanceSpecification of the block System, which is system:System. It has three
instances of subsystems as the values of the slot subsystem:Subsystem[0..]. In the SysML
Parametric diagram, the value property *value of the slot subsystem:Subsystem[0..]* are bound
to the value property value of the block System. So, the values of the value property value of
object System will be [25, 50, 75] respectively.

Value Binding in a Complex Aggregation Structure.
Many-to-one binding calculations

Constraint Blocks in Cameo Simulation Toolkit support many value properties connected to a constraint
parameter with multiplicity [*] to perform a specification without updating values back to those
properties. Any value properties which are not connected to the constraint parameter will not be used
as an input. The constraint parameter [*] shows a list of the connected value properties in the
Variables pane, Console pane (Info), and during debugging. The result from the specification of the
constraint Block is calculated from the list of value properties. For example:
inputs [*] = [2.0;3.0;4.0];

output = sum(inputs);
output = 9.0;

You can also use Add/Remove values with the parameter [*] in the Variables pane as shown in the
following figure.
Many-to-one binding supported by constraint Blocks through many value

properties.
A constraint Block supports many multiplicities of Part property connected to a constraint parameter
with multiplicity [*] to perform a specification as in the figure below.

Many-to-one binding supported by constraint Blocks through multiplicities of
Part property.
A constraint Block supports many multiplicities of Participant property of an association Block
connected to a constraint parameter with multiplicity [*] to perform a specification. The Connector
must be set type as the association Block in order to be a member of the input. Also, {end=...} must be
specified for each Participant. Any participant properties of a Connector property will be synchronized
with both the constraint parameter [*] and value properties as shown in the figure below.

Many-to-one binding supported by constraint Blocks through multiplicities of
Participant property.
Evaluating expressions
This section explains how to evaluate the mathematical equations and logical expressions in Cameo
Simulation Toolkit.
Cameo Simulation Toolkit provides constraint parameters substitution in the expressions to improve
the human readability of the constraint parameters. All user interface objects (including tooltips,
Console panel, and Variables panel related to a constraint property connected to a value property) will
display the value property name (actual binding) instead of the constraint parameter name. This
feature is applicable at the user interface level only, not at the original constraint property. For
example, “Width” and “Height” (value properties) are used instead of “w” and “h” (parameter properties)
in constraints, as shown in the following figure.

Constraint parameters substitution in expressions.
Related pages

Mathematical equation

When solving a constraint that is specified by a mathematical equation, Cameo Simulation Toolkit will
find a 'target' by evaluating a 'given'. By default, a target is on the left-hand side of the equation and a
given on the right-hand side of an equation.
The following figure shows an example of constraint parameters target and given in a mathematical
equation.
Evaluating a Mathematical Equation in a SysML Model.

As you can see from the example shown in the preceding figure, the block Circle contains a constraint
property typed by the constraint block Circle Area. The constraint block Circle Area has a constraint
that is defined by the mathematical expression {area = 3.14159 * (radius ^ 2)}. The target and the
given in the equation are the constraint parameters 'area' and 'radius' respectively. These constraint
parameters are bound to the value properties of the block Circle. The constraint parameter area of e1
is bound to the value property area of the block Circle, and the constraint parameter radius of e1 is
bound to the value property radius of the block Circle. So, the values of the constraint parameters and
the value properties bound together are always equal.
If you simulate the block Circle, the parametric evaluator in Cameo Simulation Toolkit will create an
object Circle and its internal values. It will substitute the value of radius of the block object Circle to the
equation and calculate the value of area. Once it obtains the value of area, parametric evaluator will
assign it to the area value property of the object Circle. If you change the value of the radius, Cameo

Simulation Toolkit will automatically calculate and update the value of the area with the result from
evaluating the equation.
You can also define a constraint on a UML class to constrain the values of its properties. The following
figure shows a constraint on the UML class Circle. The constraint is defined by the same Mathematical
expression as in the figure below {area = 3.14159 *** (radius ^ 2)}. If you simulate the class Circle, the
parametric evaluator will evaluate the value of radius in the equation. It will then use the value resulting
from evaluating the value of radius to update the value of property area.
Evaluating Mathematical Equation on a UML Class.
Related pages

• Logical expression(see page 416)
Logical expression
A logical expression is an expression that uses comparison operators. You can use a logical expression
to define a constraint. Cameo Simulation Toolkit uses the expression to validate values at runtime.
 Note
A logical expression must contain a comparison operator (==, <, >, <=, >=, and <>) as shown in
the following examples:
• val1 >= "500" is a valid expression.
• val2.equals("500") == true is a valid expression.
• val2.equals("500") is an invalid expression.

Red background for the labels and text fields in UI
If some constraints failed during evaluation, Cameo Simulation Toolkit (CST) will highlight the values in
the Variables pane with a red background to denote that the values fail the constraint. All parent
nodes (Name column) that contain the failed constraints will have a red background (until the root one
in the tree view), which indicates failures deeper in the structure tree. You can also see these values in
the Simulation Console pane.
Furthermore, both the values and validation that are highlighted must always be consistent with the
labels and text boxes of both the UI modeling diagram(see page 70) and the HTML UI during simulation.
Red backgrounds indicating failures during evaluation.

 Note
Neither green background nor tooltip will be used for "passed" verification status for both
Swing mockups and HTML UI.
A tooltip will also appear if you hover the mouse over the failed constraint. Each parent of the failed
constraint will appear with a contextual path "dot notation" starting from the node on which tooltip is
shown.
The parent node with a red background indicates failures deeper in the structure tree.

Nodes with green background indicating valid values.
This example uses the block Circle100 previously shown in the section Mathematical equation(see page
414). If we modify the expression of the constraint block Circle Area by changing the assignment
operator "=" to the equality operator "==", the parametric evaluator will use the expression to validate
the values of both area and radius. If the result is false, the values will be highlighted in red (see Figure:
The parent node with a red background indicates failures deeper in the structure tree). But, if the result
is true, the values will be highlighted in green (see Figure: Nodes with green background indicating valid
values).
Finding a constraint object that binds the value property

You can find the constraint object to which the value of the property is bound in the Variables pane.
To find a constraint object to which a value property is bound
100https://docs.nomagic.com/download/attachments/82761453/equationSysml.png?

• Right-click a constraint object row in the Variables pane, and select Go To. The constraint to
which the value of the property is bound will appear, as shown in the figure below.
Finding a constraint object that binds the value property through the shortcut menu.
When you export the object to the instance specification, if the exported object contains a constraint
object (an object of a constraint block) and if the expression of the constraint block is a boolean
expression, Cameo Simulation Toolkit will set the result of the evaluation, which is a literal boolean, to a
slot defined by the constraint property typed by the constraint block.
Exporting an instance as a slot value of the constraint property.

Related pages

• Mathematical equation(see page 414)
Evaluation with causality
As described in the section Mathematical equation(see page 414), the parametric evaluator is capable of
solving expressions in the mathematical equation to find the value of the target from the value of the
given. We could say that the target is an unknown value that you want to find and the given is a known
input value. Normally, a target is a variable on the left-hand side of an equation and a given is a variable
on the right-hand side.
Sometimes, however, you know the value of the variable on the left-hand side of an equation and need
to find the value of the variable on the right-hand side. You can use Cameo Simulation Toolkit to obtain
the given variable if you integrate an external evaluator, which supports solving symbolic equations, to
Cameo Simulation Toolkit. MATLAB with Symbolic Math Toolbox101 is one of the external evaluators you
can use.
 Note
As a prerequisite, you must integrate MATLAB with Symbolic Math Toolbox102 successfully. See
also Integration with MATLAB(see page 451).
If the language that defines an expression of a constraint block needs to be solved by an external
evaluator that is capable of solving symbolic equations, you can specify what property is the target and
the given through the Causality column in the Variables pane.
101 https://www.mathworks.com/products/symbolic.html
102 https://www.mathworks.com/products/symbolic.html

Using MATLAB to evaluate mathematical equations.
The preceding figure shows the block object Circle in the Variables pane. It has a constraint property
typed by the constraint block Circle Area. The expression of the constraint block
is {area = 3.14159 *** (radius ^ 2)}. The default causality of area and radius will
be target and given respectively. However, you can click the drop-down list box in
the Causality column to change the causality of area and radius to be given and target. Cameo
Simulation Toolkit will then evaluate the value of radius from the given value of area.
The expression of the constraint block Circle Area in the figure shows two roots: (i) a positive value
2.8209 and (ii) a negative value -2.8209. The parametric evaluator needs only one root to evaluate the
value of a radius from the given value of an area. Therefore, the Roots selection dialog will open for
you to select which root you want as shown in the following figure.

Roots Selection dialog.
The number of roots varies according to the expression and the multiplicity of a property, which is the
target. Therefore, it is possible to select more than one root. The following scenarios show you how to
work with multiple roots.
Scenario 1
The following figure shows the constraint Test Multiple Root 1 is applied to block A.

The Constraint Test Multiple Root 1 is Applied to Block A
Scenario 2
The given types of causality of y and x are given and target respectively. Once Cameo Simulation Toolkit
finished executing block A and performing a parametric simulation to satisfy the
constraint Test Multiple Root 1, the equation would result in three values of x and all are the possible
roots for the equation. Therefore, the Roots selection dialog would open, allowing you to select one of
these three values as the root (see the following figure).
The Roots Selection Dialog.

Scenario 3
However, you may select more than one value as the root. But, the number of values you can select
cannot be more than the upper multiplicity. Otherwise, an error will occur and an Error message dialog
will open. The following figure shows that two values were selected as the roots when in fact, the upper
multiplicity of x value property was one. Therefore, an error occurred and the Error dialog would open.

Error Occurs when the Number of Roots Selected is Greater than the Upper
Multiplicity.
Related pages

Constraints on parts
In a particular system or context where blocks are used, it is possible to add constraints on parts and
constraint value ranges. To better explain how it works, see the following example of a car model.
A car model has front: Wheel and rear: Wheel. The diameter of the Wheel block is specified as diameter:
Real value property. It is possible to add different constraints to different parts; e.g., the front wheel’s
diameter is {diameter < 19} and rear wheel’s diameter is {diameter < 20}.
The following figure demonstrates a Car (block) along with the diameter of Wheel (constraints) applied
to the rear, front, and spare wheel (part properties).

A sample model of constraints on part properties.
If the constraints of the block are applied to the part properties through another block with constraints
inside, you will get the following results.
1. The value ranges will be evaluated through all of the applied constraints. The constraints may
reside in the part properties, main block, or constraint blocks. For example, front wheel {diameter
>= 15, diameter < 19}.
2. If a constraint fails during evaluation, a failure message will appear on the owned constraint; e.g.,
part properties, main block, or constraint blocks In the Simulation Console panel.
3. In the Variables pane, the constraints applied to the part properties appear together with the
constraints of its own part properties in {...}. Cameo Simulation Toolkit highlights failed
constraints with a red background and opens the failure message in the tooltip of the applied
constraint.
This figure depicts the constraints failure message in the Console panes and the
details of failed constraints (in red background) that are applied to part
properties front : Wheel in the Variables pane.
Dynamic constraint

The concept of dynamic constraint is to allow parametric calculation of a Constraint Property with
another constraint rather than one from its type (Constraint Block). Such constraint can be dynamically
obtained during the simulation from typing Constraint Block or one of its subtypes. This section uses
the ForwardContractValuation.mdzip sample to demonstrate this concept.
To dynamically apply different constraints to a Constraint Property
1. Create a Constraint Block with all needed Constraint Parameter(s).

2. Create Constraint Blocks which inherit the Constraint Block created in step 1.
3. Specify the constraint expression of each Constraint Blocks created in step 2.
4. Type the Constraint Property with the Constraint Block created in step 1.
5. Create a behavior, for example State Machine, that will assign the runtime object of
different Constraint Blocks created in step 2 to the Constraint Property.
In ForwardContractValuation.mdzip, we will dynamically assign a constraint to
the Valuation_Rule Constraint Property, which is typed by the Valuation Constraint Block (having two
subtypes: Long Valuation and Short Valuation Constraint Blocks with two different constraint
expressions) as shown in the following figure. The context of this simulation will be the System Block.
A Valuation Constraint Block as the Type of the Valuation_Rule Constraint

Property.
In the following figure, the state machine is used as the classifier behavior of the System block.
The Calculate Contract Value for Long Position and Calculate Contract Value for
Short Position states apply different valuations to the System block via its entry activity.

System Classifier Behavior State Machine.
The Calculate Contract Value for Long Position's entry activity assigns the runtime value of
the Long Valuation Constraint Block to the Valuation_Rule Constraint Property (see the first figure
below). Consequently, the values of the constraint parameters will be calculated with the constraint
expression specified in Long Valuation.
Entry Activity of Calculate Contract Value for Long Position State.

Similarly, the second figure below demonstrates the Short Valuation dynamic assignment.

Entry Activity of Calculate Contract Value for Short Position State.
Sample model
The model used in the figures on this page is the ForwardContractValuation.mdzip sample model
that comes with the modeling tool.
To open this sample, do one of the following
• Download ForwardContractValuation.mdzip103
• Find in the modeling tool <modeling tool installation
directory>\samples\simulation\Parametrics\ForwardContractValuation.mdzip.
Related pages

3
10 https://docs.nomagic.com/download/attachments/82761412/ForwardContractValuation.mdzip?

Parametric debugging
Simulation Toolkit allows debugging the Parametric diagram through Breakpoints(see page 250). It is
especially helpful when working on projects with a large number of elements or parametric patterns
that are applied recursively. Because the Parametric diagram usually runs at the maximum speed
(without delay) regardless of the Animation Speed settings (see also SimulationConfig(see page 49)), you
must set Breakpoints to monitor values.
In the figure below, Simulation pauses at the margin breakpoint in the Parametric diagram in which you
can debug the model. You can also find the sample model of parametric debugging on the Welcome
screen by going to the Simulation sample group and selecting SpacecraftMassRollup.
Debugging parameters of the SpacecraftMassRollup built-in sample.
Manual value updates using the Parametric Evaluator
Changing values on a property of an object will cause the parametric evaluator to automatically update
the other related values with the constraint defined on the object. Or, you may want to update the
values with the constraint once you set all necessary values of the properties. The latter is possible by
executing your model with the SimulationConfig whose fireValueChangeEvent = false (see section
SimulationConfig stereotype(see page 49) for more information about the SimulationConfig and its tag
definitions) and call the API provided by the parametric evaluator whenever you desire. The following
figure shows an example of updating values manually with the parametric evaluator.
Signature: com.nomagic.magicdraw.simulation.parametrics.ParametricsEngine.executeObject(Object
object)

Parameter: Object is an object whose internal values will be updated by the parametric evaluator.
You can call the API with the MagicDraw script engine. For example, you may define it in the body of an
opaque behavior. Then, use a call behavior action to call the opaque behavior somewhere in your
model.
Manual Value Update with Activity in CylinderPipe.mdzip.
Sample model
The model used in the figures on this page is the CylinderPipe.mdzip sample model that comes with
the modeling tool.
To open this sample, do one of the following

• Download CylinderPipe.mdzip104
• Find in the modeling tool <modeling tool installation
directory>\samples\simulation\Parametrics\CylinderPipe.mdzip..
Related pages

Communicating with evaluators through simulation console
You can communicate with a parametric evaluator directly through the command prompt, which is
located in the lower part of the Simulation Console pane. You can click the arrow of the language
selection drop-down list to the right of the command prompt and select a language you want. Once
selected, the language will appear in the command prompt in the Console pane. For example, if you
select Matlab, the language in the command prompt will change from "»" to "matlab»" (see the
following figure).
104https://docs.nomagic.com/download/attachments/82761470/CylinderPipe.mdzip?

Selecting a Language for the Command Prompt.
You can enter an expression or a command, which is written in the syntax of the language you selected,
in the command prompt and press the Enter key on your keyboard to simulate it (see the following
figure).

Executing Expression in the Command Prompt.
 Note
You can also use the command prompt in the Simulation Console pane to communicate with
the script engine by selecting a scripting language from the language selection drop-down list.
For example, selecting JavaScript will cause the language to change to "js»".
Related pages

Built-in Math
Cameo Simulation Toolkit comes loaded with a built-in Math Solver. As a default Parametric Evaluator,
Math Solver can solve simple mathematical and logical expressions. You can use it to evaluate as
follows
• Mathematical and logical expressions defined in the Constraints of Constraint Blocks for
Parametric Simulation on a SysML Parametric diagram.
• Mathematical and logical expressions in Simulation Console.

See also:
Related pages

Evaluating strings from command input

You can type generic mathematical equations directly in command input of the Simulation Console
when it prompts for the built-in math. The examples are as follows
• math» x = 10;
• math» y = 20;
• math» z = x + y
z = 30.0000 (the calculation result) will be displayed on the simulation console.
 Note
The result of a calculation expression that ends with a semicolon (;) in the built-in Math will be
assigned to the corresponding variable in the selected built-in math environment. It will not be
displayed in the simulation Console tab.
Or, if you type, e.g., in command input of the Simulation Console, the examples are as follows
• math» a = true;
• math» b = false;
• math» c = a & b;
If false is the result of a calculation, it will be assigned to the variable c, but it will not be displayed in
the simulation Console tab.
If an expression does not contain any assignment operators, the result will be assigned to the variable
'ans'. The examples are as follows
• math» x = 10;
• math» 20 + x
• ans = 30.0000 will be displayed in the simulation Console tab.
You can calculate multiple expressions at the same time by ending each expression with a semicolon (;).
The examples are as follows

• math» x = 10; y = 20; z = x + y; a = z / x
• a = 3 will be displayed in the simulation Console tab.
Variables
You can use variables (operands) in the built-in Math Solver if they conform to the naming conventions
as follows
• The characters in a variable name must be a-z, A-Z, or 0-9.

• The first character must not be a number.
• Variable names must not be Constants ("E" or "PI")
• Variable names must not be Functions ("sqrt", "sin", "cos").
• Variable names must not be Operators ("+", "-", "*", "/").
Values
The valid values that you can use in an expression are as follows
• Real Number
• Complex Number
• Boolean
• Matrix
Real Number
x = 3.14159
y=2
Complex Number
c = 3 + 4i
d = 1.25 + 0.25i
 Note
An 'i' character in an expression can be parsed as either an imaginary unit or a character of a
variable name. If the character 'i' is placed after a number, and the next character is neither an
alphabet nor number, it will be parsed as an imaginary unit. Otherwise, it will be parsed as a
variable. The examples are as follows
• ca = 1i 'i' is parsed as an imaginary unit.
• cb = i 'i' is parsed as a variable.
• cx = 3.25i 'i' is parsed as an imaginary unit.
• cy = 4i4 'i' is parsed as the first character of a variable name 'i4'
Boolean
a = true
b = false

Matrix
U = [1.0, 2.0, 3.0; 4.0, 5.0, 6.0; 7.0, 8.0, 9.0]
A = [true; false; false; true]
You can add a matrix to the built-in Math Solver by using the following syntax (a semicolon is used as a
row separator and comma or space is used as a comma separator). The examples are as follows
U = [1.0, 2.0, 3.0; 4.0, 5.0, 6.0; 7.0, 8.0, 9.0]
A = [true; false; false; true]
You can refer to a matrix element with the row and column index specified in round brackets after a
matrix name. The examples are as follows (see U above)
U(1, 1) is 1.0
U(2, 3) is 6.0
You can also refer to a matrix element with only one index specified in round brackets after a matrix
name. In this case, the matrix will be considered as a column-major order matrix. The elements on the
given column-major order index will be returned. The examples are as follows (see U above)
U(2) is 4.0
U(6) is 8.0
Constants
Constant Value
E A real value that is closer than any other to e, the base of natural logarithms.
PI A real value that is closer than any other to pi, the ratio of the circumference of a circle to its
diameter.

Operators
 Important
• x and y represent numerical values or variables.
• m, n, and p represent integer values or variables.
• a and b represent boolean values or variables.
• U and V represent matrices of numerical values.
• A and B represent matrices of boolean values.
Arithmetic operators
Operator Operator name Syntax
+ Addition x+y
U + V (U and V are m x n matrices)
- Subtraction x-y
U + V (U and V are m x n matrices)
* Multiplication x*y
U*V (U is an m x n matrix and V is an n x p

matrix)
/ Division x/y
% Modulus m%n
U + V (U and V are m x n matrices of integer

values).
This operator operates element-wise on

matrices.
! Factorial m!
^ Power x^y

\ Left division x\y is equivalent to (1/x) * y
U \ V (U and V are m x n matrices) is equivalent

to (1/U) * V
.* Element-wise multiplication U .* V (U and V are m x n matrices)
./ Element-wise division U ./ V (U and V are m x n matrices)
.\ Element-wise left division U .\ V (U and V are m x n matrices) is equivalent

to (1/U) .* V
.^ Element-wise power U .^ V (U and V are m x n matrices)
 Note
An Element-wise operator performs an operation on each pair of Elements, which is in the
same location, of the operand matrices.
Assignment operators
= Assignment x=y
a=b
U=V
Comparison operators
> Greater x>y

U>V
< Less x<y

U<V
>= Greater or Equal x>=y

U>=V
<= Less of Equal x<=y

U<=V

== Equality x==y
a==b
U==V
!= Inequality x!=y
a!=b
U!=V
 All comparison operators operate Element-wise on matrices in the example as follows

A = [1; 2; 3]
B = [3; 2; 1]
Then
A>B is [false; false; true];
Boolean operators
Operator Operator Name Syntax
! NOT !A
NOT NOT A
not not A
& AND A&B
AND A AND B
and A and B
| OR A|B
OR A OR B
or A or B

Operator Operator Name Syntax
^ XOR (exclusive OR) A^B
XOR A XOR B
xor A xor B
 Important
All boolean operators operate element-wise on matrices in the example as follows
A = [true; true; false; false];
B = [true; false; true; false];
Then
A&B is [true; false; false; false];
Functions
 Note
• x and y represent real values or variables.
• c and d represent complex values or variables.
• m and n represent integer values or variables.
• U represents a matrix of values.
• A matrix can be passed to a function that operates Element-wise on matrices, as its
argument in the example as follows
X = [1, -2, 3; -4 5 -6; 7 -8 9];
Y = abs(X)
result:
Y = [1 2 3; 4 5 6; 7 8 9]
Function Syntax Function

name
abs abs(x) To return an absolute value of x or a complex modulus of c. This function operates
Element-wise on matrices.
abs(c)
acos acos(x) To return an arc cosine of an angle in the range of 0.0 through pi. All angles are
measured in radians.This function operates Element-wise on matrices.
acos(c)
acosd acosd(x) To return an inverse cosine of a given value expressed in degrees. This function
operates Element-wise on matrices.
acosd(c)

name
acosh acosh(x) To return an inverse hyperbolic cosine of a given value. This function operates
acosh(c)
acot acot(x) To return an inverse cotangent of a given value. This function operates Element-
wise on matrices.
acot(c)
acotd acotd(x) To return an inverse cotangent of a given value expressed in degrees. This function
acotd(c)
acoth acoth(x) To return an inverse hyperbolic cotangent of a given value. This function operates
acoth(c)
acsc acsc(x) To return an inverse cosecant of a given value. This function operates Element-wise
on matrices.
acsc(c)
acscd acscd(x) To return an inverse cosecant of a given value expressed in degrees. This function
acscd(c)
acsch acsch(x) To return an inverse hyperbolic cosecant of a given value. This function operates
acsch(c)
asec asec(x) To return an inverse secant of a given value. This function operates Element-wise
on matrices.
asec(c)
asecd asecd(x) To return an inverse secant of a given value expressed in degrees.This function
asecd(c)
asech asech(x) To return an inverse hyperbolic secant of a given value. This function operates
asech(c)

name
asin asin(x) To return an arc sine of an angle in the range of -pi/2 through pi/2. This function
asin(c)
asind asind(x) To return an inverse sine of a given value expressed in degrees. This function
asind(c)
asinh asinh(x) To return an inverse hyperbolic sine of a given value. This function operates
asinh(c)
atan atan(x) To return an arc tangent of an angle in the range of -pi/2 through pi/2. This function
atan(c)
atan2 atan2(x,y) To return an arc tangent of an angle in the range of -pi through pi. atan2(U, V)
returns a matrix of the same size as the U and V matrices containing the Element-
atan2(U,V) by-Element, inverse tangent of the real parts of U and V.
atand atand(x) To return an inverse tangent of a given value, expressed in degrees. This function
atand(c)
atanh atanh(x) To return an inverse hyperbolic tangent of a given value. This function operates
atanh(c)
ceil ceil(x) To return a smallest (closest to negative infinity) value that is not less than the value
of x and is equal to a mathematical integer. This function operates Element-wise on
matrices.
conj conj(c) To return a conjugated value of c. This function operates Element-wise on matrices.
cos cos(x) To return a trigonometric cosine of an angle. This function operates Element-wise
on matrices.
cos(c)

name
cosd cosd(x) To return a cosine of a given value expressed in degrees. This function operates
cosd(c)
cosh cosh(x) To return a hyperbolic cosine of a given value. This function operates Element-wise
on matrices.
cosh(c)
cot cot(x) To return a cotangent of a given value. This function operates Element-wise on
matrices.
cot(c)
cotd cotd(x) To return a cotangent of a given value expressed in degrees. This function operates
cotd(c)
coth coth(x) To return a hyperbolic cotangent of a given value. This function operates Element-
wise on matrices.
coth(c)
count count(U) To return a number of Elements of a given matrix.
csc csc(x) To return a cosecant of a given value. This function operates Element-wise on
matrices.
csc(c)
cscd cscd(x) To return a cosecant of a given value expressed in degree. This function operates
cscd(c)
csch csch(x) To return a hyperbolic cosecant of a given value. This function operates Element-
wise on matrices.
csch(c)
diag diag(U) To return a diagonal matrix and diagonals of the matrix. If U is a row matrix or a
column matrix of n Elements, this function will return a square matrix of order
diag(U,m) n+abs(m), with the Elements of U on the kth
diagonal. k = 0 represents the main
diagonal. k > 0 is above the main
diagonal. k < 0 is below the main

name
diagonal. If U is a square matrix, this function will return a column matrix formed by
the Elements of the kth diagonal of U.
exp exp(x) To return a Euler's number e raised to the power of a or c. This function operates
exp(c)
eye eye(m) To return an identity matrix of dimension m x m.
factorial factorial(m) To return a factorial of m value.
floor floor(x) To return a largest (closest to positive infinity) value that is not greater than the
value of x and is equal to a mathematical integer. This function
floor(c) operates Element-wise on matrices.
IEEErema IEEEremain To compute the remainder operation in two arguments as prescribed by the IEEE
inder der(x,y) 754 standard.
if if(b,x,y) To return the value of x if b is true. Otherwise, y is returned. Where b is a boolean

value.
imag imag(c) To return a real value of an imaginary part of a given complex number. This function
invert invert(U) To return an inverse or pseudo inverse of a given matrix. If the given matrix is a
square matrix, the inverse of a U matrix will be returned using the LU factorization.
If the given matrix is not a square matrix, a pseudo inverse matrix will be returned
using the QR factorization.
linsolve linsolve(U,V X = linsolve(U,V) solves the linear system

) U*X = V using the LU factorization with partial pivoting when U is a square matrix.
In ln(x) To return a natural logarithm (base e) of a given value. This function operates
ln(c)
log log(x) To return a natural logarithm (base e) of a given value. This function operates
log(c)
log10 log10(x) To return a logarithm base 10 of a given value. This function operates Element-wise
on matrices.
log10(c)

name
log2 log2(x) To return a logarithm base 2 of a given value. This function operates Element-wise
on matrices.
log2(c)
max max(x,y,...) To return a greater of the given values. max(U) returns the largest Element of a
given matrix. max(U, V) returns a matrix the same size as U and V with the largest
max(c,d,...) Elements taken from U or V. The dimensions of U and V must be the same.
max(U)
max(U,V)
mean mean(U) To return a mean or average value of a given matrix. U is a row or a column matrix:
mean(U) returns the mean value of all Elements in the given matrix.U is a 2-D
matrix: mean(U) returns a row matrix that contains the mean value of each column
of the given matrix.
median median(U) To return a median value of a given matrix. U is a row or column matrix: median(U)
returns the median value of all Elements in the given matrix. U is a 2-D matrix:
median(U) returns a row matrix that contains the median value of each column of
the given matrix.
min min(x,y,...) To return a smaller of the given values. min(U) returns the smallest Element of a
given matrix. min(U, V) returns a matrix the same size as U and V with the smallest
min(c,d,...) Elements taken from U or V. The dimensions of U and V must be the same.
min(U)
min(U,V)
num2str num2str(x) To return a string specifying a given number x.
num2str(c)
ones ones(m,n) To return an m x n matrix of all 1s.
pow pow(x, y) To return a value of the first argument raised to the power of the second argument.
pow(U, c) This function operates Element-wise on a given matrix U.
pow(c, d)
random random() To return a real value with a positive sign, greater than or equal to 0.0 but less than
1.0.

name
real real(c) To return a real value of the real part of a given complex number. This function
rint rint(x) To return a value that is closest in value to an argument and is equal to a
mathematical integer. This function operates Element-wise on matrices.
round round(x) To return a closest value to an argument and is equal to a mathematical integer.
This function operates Element-wise on matrices.
sec sec(x) To return a secant of a given value.This function operates Element-wise on

sec(c) matrices.
secd secd(x) To return a secant of a given value expressed in degree. This function operates
secd(c) Element-wise on matrices.
sech sech(x) To return a hyperbolic secant of a given value. This function operates Element-wise
sech(c) on matrices.
sin sin(x) To return a trigonometric sine of an angle. This function operates Element-wise on
sin(c) matrices.
sind sind(x) To return a sine of a given value, expressed in degree This function operates
sind(c)
sinh sinh(x) To return a hyperbolic sine of a given value. This function operates Element-wise on
sinh(c) matrices.
size size(U) To return a size of a given matrix. If only the matrix is passed to the function as an
size(U, m) argument, the returned value is a 1x2 matrix. The first Element
is the number of rows and the second Element is the number of columns.If the
second parameter (m) is specified, this function will return the size of an mth
dimension of a given matrix as a scalar value. The second argument can be 1 or 2 (1
for the row size and 2 for the column size). For example:
U = [1, 2, 3; 4, 5, 6];
size(U) is [2, 3]
size(U, 1) is 2
size(U, 2) is 3

name
sort sort(U) To sort the Elements of a given matrix in an ascending or descending order. If the
sort(U, second argument is specified with ‘ascend’ or ‘descend’, the Elements will be in an
‘descend’) ascending or descending order respectively. If this function is called without a
second argument, the Elements will be sorted in an ascending order.
U is a row or column matrix:
sort(U) and sort(U, ascend) sort all Elements in the given matrix.
U is a 2-D matrix: std(U) and std(U,flag) sort Elements in each column of the given
matrix.
ssqrt sqrt(x) To return a correctly rounded positive square root of a double value.This function
sqrt(c) operates Element-wise on matrices.
std std(U) To return a standard deviation of a given matrix. The ’flag’ argument can be 0 or 1. It
std(U, flag) specifies the method for calculating the standard deviation.
If the flag = 0, the standard deviation is normalized by N-1. If the flag = 1, the
standard deviation is normalized by N where N is the number of data.
The value of the flag will be zero by default. U is a row or column matrix:
std(U) and std(U, flag) returns the standard deviation of all Elements in the given
matrix. U is 2-D matrix: std(U) and std(U,flag) returns a row matrix that contains the
standard deviation of each column of the given matrix.
str2num str2num(s) To return a number specified by a given string s.
sum sum(U) To return a summation of all Elements in a U matrix.
tan tan(x) To return a trigonometric tangent of an angle. This function operates Element-wise
tan(c) on matrices.
tand tand(x) To return a tangent of a given value expressed in degree.This function operates
tand(c) Element-wise on matrices.
tanh tanh(x) To return a hyperbolic tangent of a given value. This function operates Element-
tanh(c) wise on matrices.
toDegree toDegrees(x To convert an angle measured in radians to an approximately equivalent angle

s ) measured in degrees.This function operates Element-wise on matrices.
toDegrees(c
)
toRadian To convert an angle measured in degrees to an approximately equivalent angle

s measured in radians. This function operates Element-wise on matrices.

name
transpos transpose(U To return a transposition of a given matrix

e )
zeros zeros(m, n) To return an m x n matrix of all 0s.
Integration with external Evaluators
Cameo Simulation Toolkit allows you to use an external Evaluator to evaluate an opaque expression in
your model. Therefore, you can use any language supported by the external Evaluator in the body of
the opaque expression.
• Integration with MATLAB(see page 451) (R2012a or later)

• Integration with MapleTM105 (17 or later)
• Integration with Mathematica(see page 467) (9 or later)
• Integration with Dymola(see page 470) (2021x or later)
You must specify the name of the language in the opaque expression. If you do not specify the
language of the opaque expression, Cameo Simulation Toolkit will use the Default Language option
specified in the Simulation Framework group in the Project Options(see page 47) dialog as follows.
105 https://docs.nomagic.com/display/CST2021xR2/Integration+with+MapleTM

The Default Language property in the Project Options dialog.
If the language of expressions of constraints of a SysML Constraint Block is not specified, Cameo
Simulation Toolkit will use the Evaluator, specified in the Default Parametric Evaluator option in the
Parametric Evaluator group in the Project Options(see page 47) dialog, to solve the expressions as
follows.

The Default Parametric Evaluator property in the Project Options dialog.
Related pages

Integration with MATLAB

You can use MATLAB Version R2012a or later to evaluate expressions written in MATLAB syntax in
Simulation Toolkit. You must install MATLAB and set up your modeling tools to call and use it.
 Note
• For successful integration, you must use either the 64-bit or 32-bit version of MATLAB to
align it with the 64-bit or 32-bit version of modeling tools, e.g., MagicDraw or Cameo
Systems Modeler.
• To enable the Integrations menu, you must change the perspective to Full Featured,
System Engineer, or Software Architect (from the main menu, select Options >
Perspectives > Perspectives, select Full Featured, System Engineer, or Software
Architect, and click Apply).
• When integrating with MATLAB for the first time or changing the MATLAB version, you
must restart your system. If the system has been previously integrated with MATLAB,
restart only the modeling tool.
• If there are problems with integrating MATLAB on Windows, please ensure that
MagicDraw is running with the administrator's privileges, and then try to integrate again.
To integrate a modeling tool with MATLAB (on Microsoft Windows and Mac OS X)
1. From the main menu, click Tools > Integrations. The Integrations dialog opens.

2. Select MATLAB and click Integrate/Remove Integration. The MATLAB directory selection
dialog opens.
3. Click Browse to specify the MATLAB home directory, e.g., C:\Program Files\MATLAB\R2019b.
4. Click OK and restart your system or the modeling tool.
 Note
You can manually verify the MATLAB integration process, e.g., setting the path of system
variables in the Environment Variables to the correct MATLAB path of each operating
system, through the following links:
• Using MATLAB on Microsoft Windows(see page 453)
• Using MATLAB on Mac OS(see page 456)
• Using MATLAB on Linux(see page 458)
Related pages

• Connecting to a running MATLAB session(see page 460)
• Simulink co-simulation(see page 461)
Using MATLAB on Microsoft Windows
To use MATLAB® on Microsoft Windows
1. Install MATLAB®.
2. Press Windows + R to open the Run dialog.
3. Type cmd in the open combo box and click OK to open the command prompt window.
4. Type "matlab /regserver" and press Enter to register the MATLAB® components to Windows.
The MATLAB® command prompt opens and is ready to use.

5. Add the path of the MATLAB® bin and bin/win32 (or bin/win64 for Microsoft Windows 64-
bit) folders to the Path environment variable using the following steps
5.1 Double-click System in Control Panel to open the System Properties dialog. Click
the Advanced tab.
5.2 Click Environment Variables. The Environment Variables dialog opens.

5.3 From the System variables list, select Path and click Edit. The Edit System
Variable dialog opens.
5.4 In the Variable value box, enter the path to MATLAB®...\bin and ...\bin\win64 (or ...
\bin\win32) folders, for example:
• C:\Program Files\MATLAB\R2010b\bin;
• C:\Program Files\MATLAB\R2010b\bin\win64;
5.5 For earlier versions of MATLAB®, you must enter the path of the runtime directory of
MATLAB® ...\runtime\win32 (or ...\runtime\win64), for example:
• C:\Program Files\MATLAB\R2010b\runtime\win32;
5.6 Click OK.
6. Restart Windows.
Related pages
• Integration with MATLAB(see page 451)


Using MATLAB on Mac OS
 Important
Simulation cannot integrate with MATLAB versions earlier than 2016b because of the new
security policies of the Mac OS.
To disable OS X El Capitan's System Integrity Protection (for Mac OS X)
1. Restart your Mac.

2. As soon as the screen turns black, hold down the command + R keys to access the Recovery
Partition.
3. When the Apple logo appears on the screen, release the keys.
4. Click the Utilities menu and select Terminal.
5. Type csrutil disable in the Terminal dialog and press Return. A message will appear to indicate
that SIP has been disabled.
6. Restart your Mac again for the changes to take effect.
7. Run MagicDraw/Cameo Systems Modeler and integrate it with MATLAB.
To use MATLAB® on Mac OS 10.6 (Snow Leopard)
1. Install MATLAB®.
2. Type the following commands in the terminal to show all files in Finder
• $ defaults write com.apple.finder AppleShowAllFiles TRUE
• $ killall Finder
3. Add the DYLD_LIBRARY_PATH variable to Mac OS:
3.1 Create an empty text file in the /etc folder and name it: launchd.conf.
3.2 Open it with a text editor, for example, TextEdit, and type the following text (no space)
setenv DYLD_LIBRARY_PATH /Applications/MATLAB_R2010b.app/bin/maci64:
/Applications/MATLAB_R2010b.app/runtime/maci64
3.3 Save the text file as launchd.conf to the desktop.

3.4 Move the launchd.conf file to the /etc folder.
4. Create a link to the MATLAB® executable file in /usr/bin if it does not yet exist.
5. Call the following commands in the terminal
• $ cd /usr/bin
• $ ln -s /Applications/MATLAB_R2010b.app/bin/matlab matlab
6. Type the following commands in the terminal to reset Finder
• $ defaults write com.apple.finder AppleShowAllFiles FALSE
• $ killall Finder
7. Restart Mac OS.

 Note
You can also use MATLAB if you are using MagicDraw 18.0 on either Mac OS X 10.10 Yosemite
or Mac OS X 10.11 El Capitan by following these steps:
1. Disable the SIP (if your Mac is OS X El Capitan) by following the instruction for disabling
OS X El Capitan's System Integrity Protection (SIP).
2. Install MATLAB ®.
3. Create the file com.nomagic.magicdraw.simulation.mathengine.plist.
3.1 Create a text file and type the following text.
<!DOCTYPE plist PUBLIC"-//Apple//DTD PLIST 1.0//EN" "http://

www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.nomagic.magicdraw.simulation.mathengine.plist</string>
<key>ProgramArguments</key>
<array>
<string>sh</string>
<string>-c</string>
<string>
launchctl setenv DYLD_LIBRARY_PATH
/Applications/MATLAB_R2012a.app/bin/maci64:/Applications/
MATLAB_R2012a.app/runtime/maci64
</string></array><key>RunAtLoad</key><true/></dict></plist>
3.2 Change the /Applications/MATLAB_R2012a.app to your MATLAB directory.

3.3 Save the text file. (If you are using TextEdit, change the file to plain text by clicking
Format > Make Plain Text).
3.4 Rename it as com.nomagic.magicdraw.simulation.mathengine.plist.
(Note: If you already have the file com.nomagic.magicdraw.simulation.mathengine.plist in /

Library/LaunchAgents, add :/Applications/MATLAB_R2012a.app/bin/maci64:/Applications/
MATLAB_R2012a.app/runtime/maci64 to your DYLD_LIBRARY_PATH in your
com.nomagic.magicdraw.simulation.mathengine.plist. F or example, launchctl setenv
DYLD_LIBRARY_PATH <Other_Path>:/Applications/MATLAB_R2012a.app/bin/maci64:/
Applications/MATLAB_R2012a.app/runtime/maci64 .)
4. Create the file com.nomagic.magicdraw.simulation.mathengine.matlab.plist.

4.1 Create a text file and type the following text.
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://

www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.nomagic.magicdraw.simulation.mathengine.matlab.plist</
string>
<key>ProgramArguments</key>
<array>
<string>sh</string>

<string>-c</string>
<string>
launchctl setenv MD_MATLAB_MATHENGINE
/Applications/MATLAB_R2012a.app/bin/maci64:/Applications/
MATLAB_R2012a.app/runtime/maci64
</string></array><key>RunAtLoad</key><true/></dict></plist>
4.2 Change "/Applications/MATLAB_R2012a.app" to your MATLAB directory.

4.3 Save the text file. (If you are using TextEdit, change the file to plain text by clicking
Format > Make Plain Text).
4.4 Rename it as com.nomagic.magicdraw.simulation.mathengine.matlab.plist.
5. Move the files to /Library/LaunchAgents/ by using the Terminal.

5.1 Run the Terminal.
5.2 Go to the plist files directory.
• $ cd [your plist file directory]
al5.3 Move the plist file to /Library/LaunchAgents/ using the following command
• $ sudo mv com.nomagic.magicdraw.simulation.mathengine.plist /Library/
LaunchAgents/
• $ sudo mv com.nomagic.magicdraw.simulation.mathengine.matlab.plist /Library/
LaunchAgents/
6. Create a link to the MATLAB® executable file in /usr/bin if it does not exist, by using the
following command in the Terminal
• $ cd /usr/bin
• $ sudo ln -s /Applications/MATLAB_R2012a.app/bin/matlab matlab
 Note
You need to change the /Applications/MATLAB_R2012a.app in the command line to your
MATLAB directory.
7. Restart Mac OS.
Related pages

Using MATLAB on Linux
To use MATLAB® on Linux (tested with Ubuntu)
1. Install MATLAB® (Assume that your MATLAB installation directory is /home/username/

MATHWORKS_R2011A).

2. Make sure that C Shell has already been installed on your Linux. To install C Shell on Ubuntu,
type the following command in the terminal
• ~$ sudo apt-get install csh
3. Create a link to the MATLAB® executable file in /usr/bin if it does not exist, and type the following
commands in the terminal
• ~$ sudo -i
• ~$ cd /usr/bin
• ~$ ln -s /home/username/MATHWORKS_R2011A/bin/matlab matlab
4. Use a text editor to open the magicdraw file in the bin folder in the MagicDraw installation
directory. Type the following text under the line that contains cd"$APP_HOME" to add the
MATLAB® bin folder to LD_LIBRARY_PATH of Java and save the magicdraw file.
• On Linux 32-bit, type: export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/username/
MATHWORKS_R2011A/bin/glnx86:/home/username/MATHWORKS_R2011A/sys/os/glnx86
• On Linux 64-bit, type: export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/username/
MATHWORKS_R2011A/bin/glnxa64:/home/username/MATHWORKS_R2011A/sys/os/glnxa64
LD_LIBRARY_PATH added to the MagicDraw file.

Related pages


Connecting to a running MATLAB session
Simulation Toolkit can make connection to a running MATLAB session, thus all variables in the
workspace can be used.
To connect Simulation Toolkit to a running MATLAB session through sharing
• Execute the matlab.engine.shareEngine command through the MATLAB Command window.
 Note
• MATLAB must be integrated successfully(see page 0) before the connection is made.
• If the sharing command shown above is not executed, the other MATLAB session loaded
by Simulation Toolkit will be used instead of the shared one.
After the session connection, Simulation Toolkit can access variables in the MATLAB shared workspace
that are not in the SysML model. You can define some variables in MATLAB, e.g., m1 and m2 and solve
parametric in Simulation Toolkit. These two groups of variables are then merged and can be accessed
in MATLAB as shown in the following figure.

Variables in the shared MATLAB workspace can be used in either Simulation Toolkit or MATLAB.
Simulink co-simulation
On this page
• Using Simulink in an Internal Block/Parametric diagram(see page 461)

• Using Simulink in an Activity diagram(see page 463)
Cameo Simulation Toolkit supports Simulink (MATLAB) co-simulation. Simulation executes the entire
Simulink model (*.slx) on all steps, if there are any value changes in the input, which is similar to FMI.
Simulation works with Simulink models as attached files and Simulink models located in the same
directory of the project.
 Warning
• You must successfully integrate MATLAB Version 2016b or later before using Simulink co-
simulation. See Integration with MATLAB(see page 451).
• Any duplicated Simulink model is not allowed in the project.
 Note
• Simulink models without input/output Ports are not executed because there is no
connectivity, and value change is not propagated to the Block.
• This type of Simulink integration is for atomic calculations. When any input changes,
outputs such as the parametric diagram are calculated, e.g. In1 → Gain5 → Out1. It
occurs as one step of Simulation time, the same as FMU.
• If the simulink file (.slx) is updated or modified, Simulation needs to restart the MATLAB
session by calling the kill matlab command in the Simulation console.
Using Simulink in an Internal Block/Parametric diagram

1. To import a Simulink model from the main menu, select File > Import From > Simulink File >
Import > *.slx. You can also drag the Simulink file into the Block Definition diagram, Internal
Block diagram, or Parametric diagram of the project. The Simulink Import Options dialog opens
as shown below.

The Simulink Import Options dialog opens after importing a Simulink model into the project.
2. All Input/Output Ports of the Simulink model are selected by default. However, you can select
Proxy Port, Flow Port, or both of them in the same Block for the simulation, e.g., In1 and In2
Proxy Ports and Out1 Flow Port. The following scenarios apply:
a. If you select the Proxy Port, you can select an existing Interface Block or <NEW> to
automatically create a new Interface Block for each Port with «SimulinkBlock» applied as
the model name with the Proxy Port. The automatically created Interface Block will have
the default settings with In/Out In1/Out1 : Real «FlowProperty» according to I/O Ports of the
Simulink model.
b. If you select the Flow Port, a Block with «SimulinkBlock» applied as the model name and
the Flow Port with In/Out In1/Out1 : Real «FlowPort» according to I/O Ports of the Simulink
model will be automatically created.
The Simulink model is created as Blocks with Proxy/Flow Ports.
 Warning
• The Interface Block of a Proxy Port must have only a Flow Property.

• The names of the Proxy Port and Simulink I/O Port must be the same, e.g.,
In1-In1 and Out1-Out1.
Otherwise, an error message will be printed in the Simulation console, and the
result will be invalid.
3. Connect those Proxy/Flow ports through binding Connectors106 in the Internal Block/Parametric
diagram.
4. Run the simulation. When inputs are available for initialization (e.g., passed via binding),
«SimulinkBlock» will be run at the first time and on every input change. You can also see
animation of Flow Ports and set breakpoints for debugging.
From the figure below, a system is with two Simulink models: GainAdd and Gain5. GainAdd will multiply
Port In1 by 10, multiply Port In2 by 2, and add the two results to Port Out1. Gain5 will multiply Port m by
5. Therefore, result will be [(2 * 10) + (2 * 2)] * 5 = 120.
The Simulink co-simulation result from the system which has two Simulink models (GainAdd.slx and
Gain5.slx) connected via Flow Ports.
Using Simulink in an Activity diagram

A Simulink model can be used in the Activity diagram through drag-and-drop operation. The dropped
Simulink file is presented as an Activity in the Containment tree with the same name as the Simulink
model name, and «SimulinkBlock» is automatically applied. Parameters and directions are the same as
the Simulink In/Out ports and can be used as a CallBehaviorAction on demand as shown in the figure
below.
106 https://docs.nomagic.com/display/SYSMLP2021xR2/Binding+Connector

A Simulink model, sumInport1, is presented as an Activity and used as a CallBehaviorAction in the
Activity diagram.
Integration with Maple

Cameo Simulation Toolkit supports Maple™, a mathematical computation engine, to analyze and solve
mathematical expressions. Once you have installed Maple™, you can specify it as the language of
opaque expressions.
First, you must install Maple™ on your local machine and set up your system in order to call Maple™
and use it in Cameo Simulation Toolkit.
To use Maple™ on a 32-bit or a 64-bit version of Microsoft Windows
1. Install Maple™.
2. Add the path of the Maple™ bin folder to the path environment variable using the steps as
follows
2.1 Double-click System in the Control Panel to open the System Properties dialog.
2.2 Click the Advanced tab.

2.3 Click the Environment Variables button to open the Environment Variables dialog.

2.4 Select Path from the System variables group and click the Edit button to open
the Edit System Variable dialog.
2.5 Enter the path to the Maple™ bin folder in the Variable value box. There are two
methods to enter the path:if the Variable value box has a default value, you need to add
the following path at the end of the text ;C:\Program Files\Maple 17\bin.X86_64_WINDOWS or
(ii) if the Variable value box is empty, you can just add the following path C:\Program
Files\Maple 17\bin.X86_64_WINDOWS.
2.6 Click OK.
3. Restart Windows.
To use Maple™ on Mac 10.7 or Linux

1. Install Maple™.
2. Open Maple™ and follow these steps:
2.1 Type: kernelopts( mapledir ) into command input to find the maple dir.
2.2 Type: kernelopts( bindir ) into command input to find the bin dir.
3. Open the /etc/launch.conf (if this file does not exist, create launch.conf with any text editor) and
follow these steps:
3.1 Type setenv DYLD_LIBRARY_PATH <BINDIR> where <BINDIR> is the bin dir from step 2.2
3.2 Type setenv MAPLE <MAPLEDIR> where <MAPLEDIR> is the maple dir from step 2.1
3.3 Save launch.conf.
4. Restart the computer.
Footnote
Maple™ is a registered trademark of Waterloo Maple, Inc.
Integration with Mathematica

Cameo Simulation Toolkit supports Mathematica®, a Mathematical computation engine, to analyze and
solve Mathematica®l expressions. Once you have installed Mathematica® , you can specify it as the
language of opaque expressions.
First, you must install Mathematica® on your local machine, and then set up your system to allow
Cameo Simulation Toolkit to use the installed Mathematica®.
To use Mathematica® on a 32-bit or 64-bit version of Microsoft Windows and Linux
1. On the MagicDraw main menu, select Tools > Integrations. The Integrations dialog opens.

2. From the list, select Mathematica and click Integrate/Remove Integration. The Mathematica
directory selection dialog opens.
3. Browse for the home directory of Mathematica®.

4. Click OK and restart MagicDraw.
To use Mathematica® on Mac OSX
1. From the main menu, click Tools > Integrations. The Integrations dialog opens.

2. From the list, select Mathematica and click Integrate/Remove Integration. The Mathematica
directory selection dialog opens.
3. Specify the directory where you have installed Mathematica® and click OK.
4. Restart the modeling tool.
 Information
(Only for integration with Mathematica Version 12.3) After completing the steps above using
the Integration dialog, you must change JAVA_HOME to JDK 11 by following the steps below:
1. Download JDK 11 (11.0.12 recommended) according to your operating system from
https://www.oracle.com/java/technologies/downloads/#java11. Alternatively, you can
use the bundled java from Mathematica 12.3 (JDK 11.0.10) in the [Mathematica
installation dir]\SystemFiles\Java\Windows-x86-64 directory.
2. Open the property file of the modeling tool, [Modeling Tool dir]/bin/[Modeling
Tool].properties, with a text editor, e.g., magicdraw.properties.
3. Change JAVA_HOME to the JDK 11 directory and save the file, for example:
JAVA_HOME=C\:\\Program Files\\AdoptOpenJDK\\jdk-11.0.12

4. Restart the modeling tool.
Integration with Dymola
On this page
• Dymola overview(see page 470)

• Integrating Simulation with Dymola(see page 470)
• Using Simulation with Dymola through the scripting language(see page 472)
• Using Simulation with Dymola through an Activity diagram(see page 473)
Dymola overview
Dymola107, an abbreviation for Dynamic Modeling Laboratory, is a complete tool for Modelica modeling
and simulation of integrated complex systems used with automotive, aerospace, robotics, process and
other applications. You can download and install Dymola from https://www.3ds.com/products-services/
catia/products/dymola/ and set up your modeling tool to allow integration between Simulation (2021x
and later) and Dymola , which can be specified as a language of Opaque expressions.
Integrating Simulation with Dymola

After successful integration, Dymola will be listed as available for language selection, e.g., through the
language option in the Simulation Console pane. Simulation will then be able to process Modelica
commands from the Simulation Console pane as shown in the image below.
To integrate Simulation with Dymola
1. On the modeling tool main menu, select Tools > Integrations. The Integrations dialog opens.
107 https://www.3ds.com/products-services/catia/products/dymola/

2. Select Dymola (the Not Integrated status by default) and click Integrate/Remove Integration.
3. The Dymola directory selection dialog opens. Click Browse to select the Dymola home
directory and click OK.
4. The Dymola integration dialog will be shown. Click OK. The Dymola integration status will
change to Integrated.
5. Restart the modeling tool to complete the integration.

 Note
• Dymola integration does not support Linux or Mac operating systems (only Windows).
• For Teamwork Cloud projects, the model file must be attached only to the project so that
the working directory of Dymola will be automatically set to the temp folder of the
modeling tool, e.g., C:\Users\ABC1\AppData\Local\.magicdraw
\2021x\tmp\2020-11-23-13-32-34\attachedFiles.
Using Simulation with Dymola through the scripting language

After installing Dymola, you can use Simulation with Dymola through the scripting language to call a
Modelica model via two built-in Dymola commands: simulateExtendedModel and
simulateMultiExtendedModel.
To use Simulation with Dymola through the scripting language (Steps 4 and 5 are optional)
1. Drag a Modelica model file, e.g., BouncingBall.mo, into the modeling tool to attach a Modelica
model to the project.
2. In the Console pane, select the language list box and choose Dymola. The input prompt will be
changed to dymola>>.
3. Enter the command below and press ENTER:
simulateExtendedModel(“BouncingBall”, stopTime=3, initialNames={“e”, “h0”},

initialValues={.8, 1}, finalNames={“h”});
The Starting Math Engine dialog appears shortly, and results will be shown in the Console
pane.
4. Create an Opaque Behavior to call the model using the following tags:
• language: Dymola
• name (optional): e.g., simulateExtendedModel(“BouncingBall”)
• body: Use the command from Step 3.
5. Run the Opaque Behavior. The results will be displayed in the Console pane as shown below.

Results from the simulateExtendedModel of Dymola called from an Opaque Behavior.
Using Simulation with Dymola through an Activity diagram

Alternatively, you can use Simulation with Dymola through an Activity diagram with parameters to call a
Modelica model through Dymola built-in commands.
To use simulation with Dymola through an Activity diagram
1. Create an Opaque Behavior to call the model with the following tags:
• language: Dymola
• name (optional): e.g., simulateExtendedModel
• body: (isSuccess,results)=simulateExtendedModel(problem,stopTime=stpTime,
initialNames=iniNames,initialValues=iniValues,finalNames=fnlNames);
• parameters: create parameters according to the command with valid Types and
Multiplicities, e.g., in modelName : String; in stpTime : Real; in fnlNames : String [1..*]; in
iniNames : String [1..*]; in iniValues : Real [1..*]; out isSuccess : Boolean; out results : Real [*].

2. Create a Call Behavior Action in an Activity diagram of a Block and create valid in/out Parameters
through in/out Pins according to the parameters of the Opaque Behavior. You can also create a
Block, e.g., Modelica, with value properties to keep values and set an Activity as the Classifier
Behavior of the Block as shown below.
3. Create an Instance Specification to specify parameter values, e.g., CoupledClutches. Run the
simulation through the instance to get results from Dymola back to Simulation as shown below.

Sample project
The Parametric Simulation sample projects are available in the <md.install.dir>/samples/simulation/

Parametrics directory. The SysML Parametric diagrams and InstanceSpecifications are as follows
• simple_parametrics.mdzip: basic Parametric Simulation.

• The CylinderPipe.mdzip sample: demonstrates how to deal with multiple values. It shows the
calculation for the cost of raw materials that will be used to manufacture the cylinder pipes. It
also demonstrates the use of OpaqueBehaviorAction to simulate the parametric.
• The ActParIntegrate.mdzip sample: demonstrates the use of OpaqueBehavior to simulate the
parametric.
• SCARA manipulator.mdzip: demonstrate the use of Parametric Simulation to evaluate the
position of end-effector of the SCARA manipulator from the given angles of actuators.
• MotionAnalysis.mdzip and SpringDisplacementUsingTimevariable.mdzip: show how to use Time
Series Chart for plotting the runtime values.
• Trade-Study for Brayton Cycle.mdzip: this sample shows you how to perform a trade-study.
• Forward Contract Valuation.mdzip: a dynamic constraint usage in Parametric Simulation.
 Note
All of the sample projects of the Parametric Simulation engine include a Simulation
Configurations package that contains two SimulationConfig elements for normal and silent
simulation. You can select this SimulationConfig class to start the Parametric Simulation
engine.
Related pages


Simulation of SysML models

Cameo Simulation Toolkit supports Functional Mockup Interface (FMI) version 1.0. FMI is a standard
that supports model exchange and co-simulation of models. A component which implements FMI is
called FMU (Functional Mockup Unit). An FMU is a zipped file containing an XML description file and an
implementation in source of binary form that executes the equation that represents the component
Behavior.
Cameo Simulation Toolkit is capable to read FMU files. Before simulating FMU blocks that are in the
FMU file (FMU blocks apply the <<FMU>> stereotype thus are recognizable), you have to be sure of the
following
• The FMU file and the project you are working on (in which you want to simulate the FMU blocks)
are in the same directory folder.
• The FMU file supports the platform you are using because Cameo Simulation Toolkit does not
support cross-platform execution of FMU files. You can see all supported platforms in the
Binaries folder of the FMU file. If the platform you are using is not in the Binaries folder, it is not
supported.
In order to co-simulate FMU blocks represented in SysML models, you need to have
• a config that specifies the start time, end time, and either step size or number of steps
properties.
You can click and drag the FMU file to your project to simulate it. When simulating the FMU blocks,
Cameo Simulation Toolkit does the following
• Runs the config and increase time.

• With each increment, it calls doStep() to every FMU block.
• Once Cameo Simulation Toolkit completes the steps, it updates the runtime variables from the
FMU outputs.
• Repeats the steps until it reaches the end time.
An example of FMU blocks simulation is shown as follows

A Functional Mockup Unit blocks simulation.

Simulation of a Time Series chart.
FMI 2.0 co-simulation

Cameo Simulation Toolkit supports Functional Mockup Interface (FMI) Version 1.0 and 2.0. FMI 2.0 co-
simulation applies when several FMIs are connected in Internal Block diagrams (IBD), an integration of
separate independent black box simulation models along with the master algorithm.
FMI is a standard that supports model exchange and co-simulation of models. A component that
implements FMI is called FMU (Functional Mockup Unit). Cameo Simulation Toolkit is also capable of
reading FMU files. An FMU is a zipped file containing an XML description file and implementation in
binary form that executes the equation representing the component’s Behavior.
 Important
Before simulating FMU files, you must make sure the following conditions are met:
• The FMU files and the project must be in the same directory.
• The FMU files must be OS-platform supported, e.g., Win64, Win32, linux64, linux32, etc.
(Cross-platform execution of FMU files is not supported.). You can see all supported
platforms in the Binaries folders of the FMU files. If the platform you are using is not in
the Binaries folder, it will not be supported.
• An FMU Block requires a SimulationConfig(see page 49) with endTime (optional) to provide
the reference time in the simulation (shown in Step 3 below). Please see also the
WaterTankFMI build-in sample of Simulation.
To co-simulate FMU Blocks
1. Drag FMU files into a Block Definition diagram of the SysML project. The FMU files will be
presented as «block» and «fmu» stereotypes along with ports. You may create associations
(aggregations) with the main system block to make the FMU files become part properties.
2. If there is only one FMU file to simulate, proceed to Step 3. Otherwise, you will have to create an
Internal Block diagram for the main system block to automatically include part properties in the
diagram. Select the Flow Port context menu to show flow ports of those properties and create
connections as needed.
3. Create a Simulation Configuration diagram with a SimulationConfig(see page 49) to specify

startTime, stepSize, and endTime (optional) in the properties. You can add a Time series chart(see
page 87) and specify represents and value of the FMU represented as user interfaces. You can also
include CSVExport(see page 141) to store the results.

4. Run the Simulation Configuration and see the results in the Time series chart and Variables
pane, as well as the resulting Excel file from CSVExport.
Supported SysML elements
The SysML elements that Cameo Simulation Toolkit supports are outlined below:
• Accept Change Structural Feature Event Action(see page 482)

An accept event action that waits for a Change Structural Feature Event.

• Adjunct property(see page 482)
A property to which the «AdjunctProperty» stereotype is applied.
• Binding Connector(see page 484)

A Connector that the «BindingConnector» stereotype is applied to and specifying that properties
at both ends of a connector have equal values.
• Block(see page 484)

A UML Class stereotyped with «Block».
• Association Block(see page 484)

A Block containing an instance that can link instances of the end Classifiers of the Association
together.
• BoundReference(see page 485)

A property applying the «BoundReference» stereotype that requires a binding Connector to a
property or nested property of an owning Block.
• Change Structural Feature Event(see page 486)

An Event that occurs when a value of a specified structural feature on the Event changes.

A property to which the stereotype «ClassifierBehaviorProperty» is applied that the value of a
classifier Behavior property is a Behavior simulation of the classifier Behavior of an object.
• Constraint Block(see page 488)

A class stereotyped with «ConstraintBlock» that has a constraint with an expression to constrain
the values of its constraint parameters.
• Flow property(see page 488)

A property to which the stereotype «FlowProperty» is applied and has a flow direction.
• Full Port(see page 490)

A port stereotyped with «FullPort» that specifies a separate element of an owning block.
• Invocation on nested Port Action(see page 494)

Cameo Simulation Toolkit uses the tagged value onNestedPort to send a signal if a send signal
Action is stereotyped with «InvocationOnNestedPortAction».
• Nested Connector end(see page 495)

If the ends of a connector that connects properties are stereotyped with «NestedConnectorEnd»,
Cameo Simulation Toolkit uses the information from the propertyPath of the nested connector
end to find the right objects that specify the properties at both ends of the connector.
• Probability(see page 495)

A stereotype in SysML applied to outgoing edges of decision nodes and object nodes that Cameo
Simulation Toolkit uses its probability value to select one outgoing edge from other outgoing
edges to go to.
• Proxy Port(see page 491)

A port stereotyped with «ProxyPort» that the value specifying the proxy port is the reference of
the object that is the target of the flow.
• Trigger on nested Port(see page 496)

A trigger stereotyped with «TriggerOnNestedPort» that Cameo Simulation Toolkit uses the
tagged value onNestedPort to check the port and find which object receives the triggering
Events.
• Value type(see page 496)

A data type stereotyped with «ValueType» that allows you to define a value type for typing value
properties in a model.
Accept Change Structural Feature Event Action

An Accept Change Structural Feature Event Action is an Accept Event Action that waits for a Change
Structural Feature Event. The Event will be sent to an object when the value of a specified Structural
Feature on the Event changes. When the Accept Change Structural Feature Event Action is activated, the
simulation stays on the Action until it accepts the Change Structural Feature Event that will be sent once
the value of the specified Structural Feature changes. The following figure shows the Accept Change
Structural Feature Event Action that waits for the Change Structural Feature Event of value property, in
this example, time.
An Accept Change Structural Feature Event Action in an Activity diagram.

When the value of the value property time changes, the Accept Change Structural Feature Event Action
will be activated. The token that flows through the pin before is the old value of the value
property time and the token that flows to the pin after is the current value of the value property time.
Cameo Simulation Toolkit will then simulate the next Action.
Adjunct property
An Adjunct Property is a property to which the stereotype «AdjunctProperty» is applied. Its tag
definition principal : Element[1] is for an element to determine the value of an adjunct property. With
regard to the SysML Specification, a principal can be a Connector, a CallAction, an ObjectNode, a

Variable, a Parameter, a Submachine State, or an InteractionUse. Now Cameo Simulation Toolkit
supports the adjunct property whose principal is a CallBehaviorAction, a CallOperationAction, an
ActivityParameterNode, or a Parameter.
If you use an adjunct property to represent an entry/do/exit behavior of a state, an effect behavior of a
transition, and a method behavior of a call operation in a CallMessage in MagicDraw SysML plugin and
Cameo System Modeler, you can use Cameo Simulation Toolkit to show you the value of such adjunct
property during simulation.
 Note
• CallBehaviorAction and CallOperationAction are subtypes of CallAction.
• ActivityParameterNode is a subtype of ObjectNode.
Executing an object with Adjunct and Classifier Behavior Properties.

The preceding shows an adjunct property in the Integrator activity. The adjunct property is typed by
the activity TimeDifferent. Besides having the Integrator activity as a classifier behavior, the
block Integrator also contains a classifier behavior property typed by the Integrator activity (see
Classifier Behavior property(see page 486) for more information about the classifier behavior property).
When the Integrator object is initialized from the block Integrator, the behavior simulation of its
classifier behavior will start and be set as a value of the classifier behavior property. While executing
the classifier behavior, Cameo Simulation Toolkit will activate the call behavior action getTimeDiff,
which is the principal of the adjunct property. It will create the behavior simulation of
the getTimeDiff and set it as the value of the adjunct property in the Variables pane.

Binding Connector
A binding Connector is a Connector to which a stereotype «BindingConnector» is applied. According to
the SysML specification, a binding Connector specifies that properties at both ends of a Connector have
equal values. See Value binding(see page 405) for more information about value binding with a binding
Connector.
Block
A SysML block is a UML Class stereotyped with «Block». Cameo Simulation Toolkit simulates a SysML
block the same way it simulates a UML Class.
Association Block
A Block stereotype extends Class so it can be applied to any specialization of Class including Association
Classes. Association Classes are informally called “Association Blocks.” An Association Block can own
properties and connectors just like any other Block. Each instance of an Association Block can link
together instances of the end Classifiers of the Association. To refer to the linked objects and values of
an instance of an Association Block, it is necessary for the modeler to specify which (participant)
properties of the Association Block identify the instances being linked at which end of the Association.
The value of a participant property on the instance (link) of the Association Block is the value or object
at the end of the link corresponding to this end of the Association.
The following figures depict the use of an Association Block in a model.

System initializes «ConnectorProperty» by an Association Block instance
according to "Connector" reference (AB) and «ParticipantProperty» (b2, b1. add.
b21. b11) according to "End" reference (b1, b2).
An Association Block can provide or add anything such as Behaviors and

connectors (a, b) so signals can flow. Parametric and all other constraints (a = b
+ 5) work automatically.
BoundReference
According to the SysML specification, a bound reference must have a binding connector to a property
or a nested property of an owning block. Therefore, Cameo Simulation Toolkit will set the value of the
bound reference so that it works with the properties connected with the binding connector. In
exceptional circumstances, for example, if a Classifier that types a bound reference is a subtype of a
Classifier that types a property at the other end of a binding connector, Cameo Simulation Toolkit will
use the Classifier that types the bound reference to initialize the object. You can see more information
about binding connector simulation in Binding Connector(see page 484).

Executing a Block Vehicle that contains Bound references.
Change Structural Feature Event

A Change Structural Feature Event is an Event that occurs when a value of a specified Structural Feature
on the Event changes. The Change Structural Feature Event will be accepted by an Accept Change
Structural Feature Event action. You can find more information about simulation of an Accept Change
Structural Feature Event Action and a Change Structural Feature Event in Accept change structural
feature Event action(see page 482).
Classifier Behavior property

A classifier Behavior property is a property to which the stereotype «ClassifierBehaviorProperty» is
applied. The value of a classifier Behavior property is a Behavior simulation of the classifier Behavior of
an object. Therefore, the value of the classifier Behavior property exists only after the Behavior of the
object has been started (See Executing an Object with Adjunct and Classifier Behavior Properties108.).
8
10 https://docs.nomagic.com/download/attachments/82762215/execute_objectwithAdjunct.png?

The block Integrator has a classifier Behavior property typed by the activity Integrator. You will see
the Behavior simulation as the value of the classifier Behavior in the Variables pane.
Note: Support multiple inherited Classifier Behaviors

When a block inherits from multiple other blocks which have a classifier Behavior (CB) only one of
them is run instead of all. In the figure below, block A inherits from block B and block C, however,
when running the simulation, only block A Behavior is simulated. The Behaviors C and B will be not
simulated.
Block A inheriting from multiple blocks, B and C.
Simulation console messages showing only Block A is run.

If the specialized block does not have a CB, all inherited should be run. In the figure below, System1,
System2, Super1 and Super2 Behaviors are simulated as asynchronous sessions because the
SubSystem block does not have a Classifier Behavior.

Block SubSystem without any inherited Classifier Behavior.
Simulation console messages showing Block System1, System2, Super1 and Super2 all running
asynchronously.
Constraint Block
A constraint Block is a subtype of a Block. It is a class stereotyped with «ConstraintBlock». It has a
constraint with an expression to constrain the values of its constraint parameters. If an object initialized
from a constraint Block and a value bound to a constraint parameter of that object is changed, Cameo
Simulation Toolkit will evaluate the expression of the constraint. You can see more information about
how Cameo Simulation Toolkit evaluates an expression in Evaluating expressions(see page 413).
Flow property
A flow property is a property to which the stereotype «FlowProperty» is applied. A flow property has a
flow direction. A flow due to flow properties will incur flow properties matching. Matching flow
properties must have the same direction and type. If the direction and type of multiple flow properties
at either end of a connector match, a flow will occur between the flow properties with the same name.

When the flow occurs between matching flow properties, the value of the flow property with a direction
'out' or 'inout' will be delivered to the flow property with the direction 'in' or 'inout'.
Port
Cameo Simulation Toolkit supports the following SysML ports:
• Flow Port(see page 489)

A Port stereotyped with «FlowPort» that specifies the input and output items that can flow
between a Block and its environment.

A Port stereotyped with «FullPort» that specifies a separate element of an owning Block.

A Port stereotyped with «ProxyPort» that the value specifying the Proxy Port is the reference of
the object that is the target of the Flow.
 Note
• A conjugated Port (isConjugated = True) is indicated with a tilde (∼) in front of the Port
type, showing that the property Flow direction of the Port is reversed, from in to out and
from out to in.
A conjugated Port with a tilde (∼) in front of the Port type.
• For the nested Port, if the parent Port is conjugated, all of property Flow directions of its
children and grandchildren will be reversed.
Related pages
Flow Port

A Flow Port109 is a Port that specifies the input and output items that can flow between a Block and its
environment. Flow updating depends on directions (in, out, and inout directions as shown in the figure
below). If there is the in or out direction, the value cannot be updated in the reverse direction. In
general, Flow Ports are used for asynchronous, broadcast, and send-and-forget interactions. Animation
of the value flow is animated through parts, Ports, and Connectors. Both atomic Flow Ports (typed by
Signal or ValueType) and non-atomic Flow Ports (typed by FlowSpecification) are supported. If the Flow
Port is connected to multiple external and/or internal Connectors, the items are propagated (broadcast)
to the other ends of all Connectors that have matching properties.
Flow Ports with animation of value propagation in the Internal Block diagram.
Related pages
• Port(see page 489)

Full Port
A Full port is a port stereotyped with «FullPort». It specifies a separate Element of an owning block.
Initializing the owning block will cause Cameo Simulation Toolkit to initialize a port object from a
Classifier that types the full port.
109 https://docs.nomagic.com/display/SYSMLP2021xR2/Flow+Port

An Object containing full Ports.
Related pages

Proxy Port
A Proxy Port is a Port stereotyped with «ProxyPort». When Cameo Simulation Toolkit simulates an
object that has a proxy Port, the value that specifies the proxy Port will be the reference of the object
that is the target of the Flow. A Classifier of the target object must be inherited from an interface Block

that types a proxy Port.
If the proxy Port is not connected by a delegation Connector to the internal structure of the owning
object, the target will be the object itself.
The target object owning object of the proxy Port.

If the proxy Port is connected by a delegation Connector to the internal structure of the object owning
the Port, the target of the Flow will be the object specifying the role at the other end of the delegation
Connector.

The target Objects of proxy Ports are visible when the Ports connected by Delegation Connector.
If Cameo Simulation Toolkit cannot find the target object, or the classifier of the target object does not
inherit from the interface Block that types the proxy Port, Cameo Simulation Toolkit will initialize the
Port object directly from its type.
Features defined by Interface Block, e.g., Flow properties, can be displayed in the Variables pane (when
selecting the Show Ports option for the Variables pane in the Environment option dialog) under
Proxy Port nodes during simulation as shown in the figure below.

Proxy Port nodes (level and valve) show only features defined by «interfaceBlock» (level and valve Flow
properties).
 Note
Other properties which are not part of the Ports, e.g., minlevel and maxlevel of Controller are not
shown because Ports can be only accessed and display what is defined by «interfaceBlock».
Related pages

Invocation on nested Port Action

Cameo Simulation Toolkit will use the tagged value onNestedPort to send a Signal if a Send Signal
Action is stereotyped with «InvocationOnNestedPortAction».

Simulation of the InvocationOnNestedPort.
Nested Connector end

If the ends of a Connector that connects properties are stereotyped with «NestedConnectorEnd»,
Cameo Simulation Toolkit will use the information from the propertyPath of the nested Connector end
to find the right objects that specify the properties at both ends of the Connector. Therefore, you can
send a Signal along the Connector to a deep nesting object. You can also use the binding Connector to
bind objects that specify the properties at different nesting levels.
Probability
Probability is a stereotype in SysML. You can apply it to outgoing edges of decision nodes and object
nodes. When Cameo Simulation Toolkit simulates a decision node or an object nodes whose outgoing
edges stereotyped with probability, it will use the probability values collected from all outgoing edges to
select one outgoing edge that it will go to.

Supported Probability Values for Decision Nodes on Outgoing Edges.
Normally, the summation of the probability values from all outgoing edges should be 1.0 (100%). If this
is not the case, Cameo Simulation Toolkit will scale the probability values with the summation.
Trigger on nested Port

When you model a State Machine in your system whose Transition has a Trigger stereotyped with
«TriggerOnNestedPort», Cameo Simulation Toolkit will use the tagged value onNestedPort to check the
Port and find which object receives the triggering Events.
Value type
On this page
• Interpreting ValueType as Real(see page 498)

A value type is a data type stereotyped with «ValueType». SysML allows you to define a value type for
typing value properties in your model. You can specify the quantity kind and the unit of the value type
with the quantity kinds and units defined in the QUDV library.

Value Types Inherited from Real.
A SysML Model Using the SysML Value Types Defined.
Interpreting ValueType as Real

Cameo Simulation Toolkit interprets all ValueTypes that are not inherited from any UML or SysML
primitive types as Real primitive numbers. For example, if the value property is typed by complex (not a
primitive type), it will be interpreted as real.
Non-Primitive Value Types Interpreted as Real.
Requirements traceability from the Variables pane

When you model with SysML, you can create a relationship between a SysML requirement and any
element in your model. Cameo Simulation Toolkit allows you to navigate from the runtime value or
from the object, to the related SysML requirement during the model simulation.
Requirement refined by a constraint block

If you use a constraint block, which refines a SysML requirement, to type a constraint property of a
block, you can select the object of the constraint property to navigate into a SysML requirement that is
related to that object in the Containment tree.
To navigate to a SysML requirement related to a constraint property in the Containment tree
1. Right click a constraint property object in the Variables pane and select Go To (see the following
figure).
2. Select the name of a requirement that appears on the sub menu. Cameo Simulation Toolkit will
show you the SysML requirement that is related to the constraint property specified by the
selected object in the Containment tree.

Navigating into a SysML Requirement related to a Constraint Property.
The preceding figure shows the block Circle whose constraint property typed by the constraint
block Maximum Area, which refines the requirement Maximum Area. It also shows you that if you
right-click the object that specifies the constraint property when Cameo Simulation Toolkit is executing
the block Circle, and select the Go To context menu, you will see the requirement Maximum Area.
Selecting the requirement on the menu will highlight that requirement in the Containment tree.
Requirement satisfied by a property

You can also select a value that specifies a property in the Variables pane to navigate into a SysML
Requirement, which is satisfied by the property, in the Containment tree. When you right-click the value
and select the Go To context menu, you will see a specific Requirement satisfied by the property.

Navigating into a Requirement satisfied by a Property.
Simulation Toolkit supports contextualized satisfy relationship that value property from inner nested
structure is connected to Requirements. For example, the constraint on value Requirement must be
satisfied by the length of the width of Rectangle object only in this context (not the length of the height of
Rectangle, length of Square, or length of Line objects) through the Source Context and Source Property
Path tags as shown in the figure below.

Contextualized satisfy relationship through the Source Context and Source
Property Path tags.
Requirement and test case traceability

During a model simulation, Cameo Simulation Toolkit lists all constraints and requirements or test
cases that are related in the model in the Console pane. When the simulation fails to satisfy or fulfill
some constraints, it will cause the model simulation to fail and errors to occur. You can see the error
messages and the links in the Console pane and Variables pane, to navigate to the requirement(s) that
cause the test case to fail.
A tooltip message of a failed test case in the Variables pane is in the example as follows.

Tracing to Failed Constraints.
Extraction of Constraints from Text Based Requirements

As of version 18.4, another new addition to Cameo Simulation Toolkit's already impressive repertoire, is
the ability to automatically extract constraint equations from the text of a requirement.
For example, if a requirement text states that a moving car must have speed more than 0, then the
constraint equation “speed > 0” is automatically extracted from the requirement text and will be
evaluated upon running of a simulation.
While typing the requirement text, a shortcut menu appears as soon as you type some keywords which
are available in the Glossary, see the example as follows
Constraints within text-based requirements.

For the constraint to execute properly, the requirement should be linked to a property, such as in the
above example, a satisfy relation is used to link between the property and the requirement.

When the simulation is run, the constraint is evaluated and color-coded according to the result of the
simulation, red if the constraint fails and green if it passes, as shown in figure below. Additionally, a
mouse over the variable will display a tooltip.
Running a simulation evaluates the constraint within the requirement and

color-codes it.
Non-normative extensions
Non-normative extensions to SysML considered for standardization in future versions of the language
consist of stereotypes and model libraries and are organized by major diagram types, which are
consistent with how the main body of this specification is organized.

Distribution Extensions
A Distributed Property is a property of a Block or a Value Type used to apply a probability distribution
to the values of the property. Specific distributions can be defined by applying a Subclass of the
«DistributedProperty» stereotype to a property according to OMG SysML 1.4110, E.7 Distribution
Extensions.
To set a distributed property
1. Select a property and double-click it to open the Specification window.

2. Select Applied Stereotype and click [...] to include a distribution property as needed.
3. Specify the required properties, e.g. Mean and Standard Deviation (SD) for «normal» or Min and
Max for other distributed properties as shown in the figure as follows
Setting a normal distribution with mean = 10, and SD = 2.
4. Click . The distributed property will be applied.

5. Run the simulation model. Depending on the applied stereotype, the distributed properties will
be initialized with a random value, e.g. normal distribution, constant distribution between min &
max value. You can review sampling results by running the model with association end
multiplicity, e.g. 100, and keep the result with «CSVExport» for analysis.
6. Results of the distributed property “normal” (with 500 samples) can be plotted as a normal
distribution via MATLAB or other tools as shown in the figure as follows
110 http://sysml.org/docs/specs/OMGSysML-v1.4-15-06-03.pdf

A normal distribution plotted via applying «normal» distributed property
stereotype.
7. You can apply «uniform» distributed property stereotype with Min and Max properties (e.g. 1 and
10) that you can plot as a uniform distribution as shown in the figure as follows
A uniform distribution plotted (Min = 1, and Max = 10).
Related pages
• Supported SysML elements(see page 480)

• Requirements traceability from the Variables pane(see page 499)

Action languages
UML and SysML allow you to define an Action or a Behavior using an expression or a scripting
language, for example, opaque Action, opaque Behavior, and function Behavior. Cameo Simulation
Toolkit can simulate the script or the expression in your model during the model simulation, when an
Element that contains the script is activated.
Normally, a script will be defined in an opaque expression. Therefore, if your model has any value
specifications (like guards, constraints, decisions, default values, and opaque Behaviors) that can be
defined with opaque expressions, they will be simulated during the model simulation.
Some special cases, however, apply for Activity edges that do not have any guard expression and
decision nodes that do not have any Decision Input specified. The name of the Activity edge and the
decision node will be evaluated by Cameo Simulation Toolkit using a default scripting language as
shown in the figure as follows.
The decision input that is unspecified and the guards that are empty.
You can use different languages for different opaque expressions in your model. Cameo Simulation
Toolkit will use a scripting engine that matches the specified language of the opaque expression to
simulate the script content.
Supported scripting languages

Cameo Simulation Toolkit includes several scripting languages out of the box :

• BeanShell
• Groovy
• JavaScript Nashorn (deprecated)
• JavaScript Rhino (default)
• Python (Jython)
• Ruby (Jruby)
These languages can be used as the language of any OpaqueExpression or OpaqueAction anywhere in
the model.
When CST is integrated with external Math engines (e.g. MATLAB, Mathematica, OpenModelica or
Maple), corresponding languages are also added into the supported language list.
Additionally, you can download and install any other JSR-223 standard compatible language.
Reading enumeration literal value

Cameo Simulation Toolkit can evaluate any expression that contains enumeration literal by name
directly, e.g., colour == "Green", but not colour.getName() == Green.
The following figure demonstrates how you can read Enumeration literal value by name directly
through the property Change Expression colour=="Green" and setting the guard condition
colour=="Red" instead of colour.getName()=="Green", and colour.getName()=="Red" accordingly in the
Specification window of the Transition<>.

Reading Enumeration literal value by name directly (without .getName()).
Backward compatibility with earlier version models using getName() is supported through an error
message in the Simulation console(see page 200) pane. The Script engine will throw one error message,
and then stop for Enumeration literal value. If getName() exists in many places, you will have to run the
simulation many times and manually fix it one by one.
References to elements with HTML
Cameo Simulation Toolkit can make references to model Elements using HTML through the Edit
Hyperlink dialog(see page 509). Those objects that allow references are ValueSpecification.Value,
LiteralString.Value, OpaqueExpression.Body, OpaqueAction.Body, OpaqueBehavior.Body,
Constraint.Specification, and ObjectFlow.Guard.
This feature has been developed to have references in text to model elements in various scripts.
Cameo Simulation Toolkit converts HTML into plain texts before execution. In the following figure,
ValueSpecification.Value (b) can refer to slot (b = 4) of an InstanceSpecification (Ins). If the value of slot
(b = 4) changes, ValueSpecification.Value (b) will change accordingly.

A sample of references to elements with HTML.
Related page
• Edit Hyperlink dialog(see page 509)
Value access and references by tags

Cameo Simulation Toolkit supports accessing tag111 elements by names in script evaluated from that
model element. All tags will be added as variables to that model element where the script is evaluated
through an Opaque expression (default language). Other variables with the same name referred to by
tags will be overwritten with the values of the Tags, e.g., the default value of a Distributed property can
be initialized from calculating the min and max variables as shown in the figure below.
111 https://docs.nomagic.com/display/MD2021xR2/Tag

Default values are calculated from the min and max tags as variables.
You can get any tag values by using names through console with the following command:
ALH.getTagValue(StructuredValue runtimeObject, String tagName)
You can also run the command without the runtime object even if no runtime object is provided, e.g.,
ALH.getTagValue(String tagName), as shown in the following figure.

Running ALH.setValue() and ALH.getTagValue() without runtime objects.
Importing external libraries

When you use a scripting language in your model, you may need to call some external libraries to do
some specific tasks. Therefore, you need to add the external libraries to your project before executing
it.
 Note
Only *.jar files are supported as the external libraries.
To add an external library to a project
1. Click Options > Project on the main menu to open the Project Options dialog.
2. Select General project options on the left-hand side of the dialog and select External
Libraries from the Simulation Script Engine option.

The Project Options dialog.
3. Click the button of External Libraries to open the Select Files and/or Directories dialog.

Selecting an External Library.
4. Click the Add button, to open the Open file dialog.

Project options.
5. Browse the file that you want to add to your project and click the Open button. The path
filename will be added to the Select Files and/or Directories dialog.
Action scripts APIs

Cameo Simulation Toolkit uses Java Scripting API to evaluate scripting languages. It is a scripting
language-independent framework that uses script engines from Java code.
Cameo Simulation Toolkit supports the following scripting languages
• ECMLScript/JavaScript Nashorn (deprecated)

• Beanshell
• Groovy
• Python
• Ruby
Predefined variables in an Action script represent a set of variables defined by the script engine before
a script evaluation is executed. You can refer to these predefined variables from any action script API.

Variable Description
$context$ or _context_ A context or runtime object of a current script evaluation.
$element$ or _element_ An owner element of the script.
$signal$ or _signal_ The last signal Instance in an Event pool of a specified object.
$state$ or _state_ An active State of a context or a runtime object of a current script evaluation.
$token$ or _token_ A token value of an active model element.
self Equivalent to $context$ or _context_.
sig_ + "property name" The specified property value of the last signal.
ALH APIs
This section contains all available ALH (Action Language Helper) APIs that you can use in Cameo
Simulation Toolkit, e.g., to get and specify a Structural Feature value. You can also call a specific
Behavior and operation by using ALH APIs. Creating a runtime object and getting its current State or
creating Signal instance are also possible. With ALH APIs, a Signal instance can even be sent to a specific
target object. Additionally, you are able to get a token value, retrieve the last signal instance from a
runtime object, evaluate an expression, create an Array list in Java, check the State of an object, add a
value to an object or remove it, get a context or runtime object of a current script evaluation, access
current simulation time and simulation time unit, and add a value to, get a value from, check an
existing, or remove a global variable. You can also check a specified State to see if it was visited and
trace the caller of a script to access it.
 Information
• You can find more examples of ALH usage at <installation
directory>\samples\simulation\SmallTestSamples.mdzip (ALH Tests section).
• For more information, see the JavaDoc of ALH at <installation
directory>\openapidocs\SimulationJavaDoc.
Related pages

Getting a structural feature value
You can use the following API to retrieve a structural feature value
object getValue(StructuredValue object, String featureName)
The following example shows how to get the value of the structural feature indicated above in ALH API.
value = ALH.getValue(object, "speed");
If the value of an object or a featureName is null, an IllegalArgumentException will be thrown.
 Information
While using Rhino JavaScript, the return value of ALH.getValue() is not automatically UnBoxed
to a primitive type. Users needs to handle such UnBoxing by themselves, by using
ALH.getValue(object, "speed").intValue() to get the value of primitive integer type.
 Information
Alternatively, you can use ALH API through the fUML object syntax, with
object.get(featureName). For example:
• value = object.get("speed");
Specifying a structural feature value

You can use the following API to specify a structural feature value:
void setValue(StructuredValue object, String featureName, Object value)
The following example shows how to specify the value of the structural feature in ALH API:
value = ALH.setValue(object, "speed", "10");
If the value of an object or a featureName is null, an IllegalArgumentException will be thrown. However,

null is acceptable for an assigned value.

In addition, the RuntimeObject can be omitted. The following example shows how to set a structural
feature value without specifying a RuntimeObject in ALH API:
void setValue(String featureName, Object value)
 Information
object.set(featureName, value). For example:
• value = object.set("speed", "10");
Calling a specific Behavior

You can use the following APIs to call any Behavior by its name.
object callBehavior(String name)

object callBehavior(String name, List<?> arguments)
object callBehavior(String name, List<?> arguments, boolean isSynchronous)
The following example shows how to call the "test" specified Behavior in ALH API
value = ALH.callBehavior("test");
You can also give initial parameter values in which the arguments lists must be created.
arguments = ALH.createList();
arguments.add("value1");
value = ALH.callBehavior("test", arguments);
If a found Behavior value is null or an argument's size is not equal to the in or inout parameter's size of
the found Behavior, an IllegalArgumentException will be thrown.
Calling a specific operation

You can use the following APIs to call an operation
object callOperation(String name)

object callOperation(String name, List<?> arguments)
object callOperation(Object_ object, String name)
object callOperation(Object_ object, String name, List<?> arguments)
object callOperation(Object_ object, String name, List<?> arguments, boolean
isSynchronous)
The following example shows how to call a specified operation in ALH API by passing the operation's
name
value = ALH.callOperation("test");
You can also give initial parameter values in which the arguments lists must be created by executing
the following code
value = ALH.callOperation("test", arguments);
If a found Behavior value is null or an argument's size is not equal to the in or inout parameter's size of
the found Behavior, an IllegalArgumentException will be thrown.
Creating a run-time object

You can use the following APIs to create a runtime object.
object_ createObject(Class classifier)

object_ createObject(String name)
The following example shows how to create a runtime object (Object_), typed by a specified Classifier in
ALH API.
If a passing parameter is typed by a String, the API will find a Class in the model that has a matching
name, and then create the runtime object typed by that Class.
ALH.createObject("Car");
If an instance of the com.nomagic.uml2.ext.magicdraw.classes.mdkernel.Class has been passed on to

the parameter "a", you can create an object through the specified Class directly as follows
ALH.createObject(a);

Note that if a parameter is equal to null, execution will be thrown.
Creating a signal instance

You can create Signal Instances by using the following API. The signatures of this API are as follows
SignalInstance createSignal(Signal signal)

SignalInstance createSignal(String keyword)
The following example demonstrates how to create a Signal Instance
ALH.createSignal("start");
ALH.createObject("statemachine::signals::start");
ALH.createSignal(s); ---> if 's' is an instance of a Signal.
The parameter of this API can be either a String or a Signal. If it is a String, the system will find a Signal
whose name or qualified name contains the String.
Sending a signal instance to a specific target object

You can send an existing Signal Instance (or create a new one and then send it) to a target object with
the following APIs
void sendSignal(String signalName, Object_ object)

void sendSignal(String signalName, String targetName)
void sendSignal(SignalInstance signal, Object_ object)
void sendSignal(SignalInstance signal, String targetName)
void sendSignal(String signalName, Object_ target, String portName)
void sendSignal(SignalInstance signal, Object_ target, String portName)
The conditions that apply when creating an Instance are as follows
• If a signal name contains "::", it will find the signal from a qualified name. The signal will be found
if its qualified name is ended with signalName.
• If an object is an instance of an Object_, send the signal to that Object_ directly.
• If an object is an instance of a String, there are two possible cases as follows
• It will find the target object(s) from all waiting objects whose part/property names match
the target's String parameter.
• It will find the target object(s) through connected ports, given that the port is the name of
the current object.
The following example shows how to send a specific signal to a specific target object in ALH API

ALH.sendSignal("play", o); → "o" references to a target object.
ALH.sendSignal("system::play", o); → Find a signal using a qualified name.
ALH.sendSignal("play", "Speaker"); → Send to all waiting objects that have "Speaker"
as their type name.
ALH.sendSignal("play", "Player", "out2"); → "Player" is an object, and "out2" is a
port name.
All parameters must not be null, otherwise the ScriptEngine errors will be thrown.
Getting a token value

You can use the following API to retrieve a token value. It is equivalent to $token$.
object getTokenValue()
The following code fragment shows how to get a token value of an active model element in ALH API
ALH.getTokenValue();
If there are no tokens available, it will return null.
Getting the current state of a run-time object

You can use the following API to retrieve a current State of a specified object. If the object has more
than one active State, it recognizes which the runtime State is, and finds it.
State getState(Object_ object)
The following code fragment shows how to get the current state of a specified object using ALH API
ALH.getState(o);
It returns the Instance of the following
com.nomagic.uml2.ext.magicdraw.statemachines.mdbehaviorstatemachines.State.

Getting the last signal instance from a run-time object
You can use the following API to retrieve the last signal instance from a runtime object. It is equivalent
to $signal$.
SignalInstance getLastSignal(Object_ o)
The following code fragment shows how to get the last signal instance in the event pool of a specified
object using ALH API
ALH.getLastSignal(o);
It returns the Instance of the following
fUML.Semantics.CommonBehaviors.Communications.SignalInstance.
Evaluating an expression
You can use the following API to evaluate an expression
object evaluate(String expression)

object evaluate(String language, String expression)
The following code fragment shows how to evaluate expressions in ALH API
result = ALH.evaluate("a+b");
ALH.setValue($context$, "display", result);
If no language is defined, the default language will be used (JavaScript Rhino).
Creating an ArrayList in Java

You can use the following API to create a Java ArrayList.

ArrayList<Object> createList()
ArrayList<Object> createList(Object object)
A Java List will be required under certain circumstances, e.g., if you want to create Argument values that
will be passed to some calling Behaviors or operations. In scripting languages, the built-in functions
importPackage and importClass can be used to import the Java packages and Classes.
The following code fragment shows how to create a Java ArrayList in the scripting language using a
"new" operator
importPackage(java.util);
arguments = new ArrayList();
The following code fragment shows how to create the Java ArrayList in the scripting language with ALH
arguemnts.add("value1");
Alternatively, you can use an initial value as the constructor's parameter.
arguments = ALH.createList("value1");
 Note
• Only one initial value of the list is allowed.
• Variable-length argument lists are not supported.
Checking the State of an object

The following ALH API checks whether a particular object is in a specific state name.
boolean inState(Object_ object, String stateName)

boolean inState(String stateName)
Unless the object is specified, it will use the current active object, for example:
if (ALH.inState(ccobj, "Operating")) {

force=ccForce
} else {
force = acc*2
}
 Information
Alternatively, you can use ALH API through the fUML object syntax, with object.in(stateName).
For example:
• ccobj.in(“Operating”);
Adding a value to an object

You can use ALH API to add a value to an object. For example, you can set a designated object, a
feature of the designated object to which a value will be added, a value via object, a featureName, and a
value parameter respectively.
You can add a value to an object using the code as follows
boolean addValue(StructuredValue object, String featureName, Object value)
If you have more than one value to add to an object, e.g., the value of the upper bound of the
multiplicity is more than one, you can still add the values by using the parameter insertAt.
boolean addValueAt(StructuredValue object, String featureName, Object value, Integer

insertAt)
The following code fragment shows how to add values to an object, e.g., System.p1, through ALH API.
ALH.addValue(System,”p1”,10); // System.p1 = [10]

ALH.addValue(System,”p1”,30); // System.p1 = [10, 30]
ALH.addValueAt(System,”p1”,20,2); // System.p1 = [10, 20, 30]
 Information
object.addValue(featureName, value) and object.addValueAt(featureName, value,
insertAt). For example:
• System.addValue(”p1”,10); // System.p1 = [10]
• System.addValue(”p1”,30); // System.p1 = [10, 30]
• System.addValueAt(”p1”,20,2); // System.p1 = [10, 20, 30]

Removing a value of an object
You can use ALH API to remove a value from an object. For example, you can set a designated object, a
feature of the designated object from which a value will be removed, a value via object, a featureName,
and a value parameter respectively.
You can remove an object's value by executing the following code fragment
boolean removeValue(StructuredValue object, String featureName, Value value)
If you want to remove more than one value from an object, e.g., the value of the upper bound of the
multiplicity is more than one, you can remove them by using the parameter removeAt.
boolean removeValueAt(StructuredValue object, String featureName, Integer removeAt)
The following code fragment shows how to remove values from an object, e.g., System.p1, through ALH
API.
print(System); // System.p1 = [10, 20, 30]

ALH.removeValueAt(System,”p1”,3); // System.p1 = [10, 20]
ALH.removeValue(System,”p1”,20); // System.p1 = [10]
 Information
Alternatively, you can use ALH API through the fUML object syntax,
with object.remove(featureName) and object.removeAt(featureName, removeAt). For
example:
• print(System); // System.p1 = [10, 20, 30]
• System.removeAt(”p1”,3); // System.p1 = [10, 20]
• System.remove(”p1”,20); // System.p1 = [10]
Getting a context
You can use ALH API to get a context or a runtime object of a current script evaluation. It is equivalent
to $context$ and self.
Object_ getContext()
The following code fragment shows how to get a context of a runtime object through ALH API.

ALH.getContext(); // Object@...
Accessing current simulation time

Simulation time is a timestamp that is retrieved from a simulation clock. You can use ALH API to get the
simulation time of execution.
double getCurrentTime()
double getCurrentTime(String timeUnit)
The following code fragment shows how to get the simulation time of execution through ALH API.
ALH.getCurrentTime();
ALH.getCurrentTime("ms");
Accessing the simulation time unit

The simulation time unit is defined in the tag "timeUnit" of an SimulationConfig stereotype. If you do
not define the value of this tag, the default unit of time is the millisecond. You can use ALH API to get a
simulation time unit of execution.
double getTimeUnit(String timeUnit)
The following code fragment shows how to get the TimeUnit tag of a SimulationConfig through ALH
API.
ALH.getTimeUnit(); // millisecond
Adding a value to a global variable

A global variable is a variable that is accessible from any session in the same execution. You can use
ALH API to create a global variable and specify its value by calling ALH.setGlobalVariable(String
variableName, Object value).
void setGlobalVariable(String variableName, Object value)
The code example is as follows

ALH.setGlobalVariable("GLOBAL_COUNT", 1);
The example code assigns 1 to a global variable named GLOBAL_COUNT. If the global variable with the
given name does not exist, this method will create a new global variable with the same name and add
the value to it.
Getting a value from a global variable

During execution of a model, you can obtain a value of a global variable, which has already been
defined, by calling getGlobalVariable(String variableName) of the ALH API. This method returns a Java
object, which is the value of the global variable specified by the given variable name.
object getGlobalVariable(String variableName)
The example code is as follows
var a = ALH.getGlobalVariable("GLOBAL_COUNT") + 1
 Note
You can obtain the value of a global variable directly by using its name.
var a = GLOBAL_COUNT + 1;
Removing a defined global variable

You can remove a global variable that has previously been defined by calling a
removeGlobalVariable(String variableName) of the ALH API.
void removeGlobalVariable(String variableName)
The following code fragment shows how to remove a global variable, e.g., GLOBAL_COUNT, that was
previously defined through ALH API.
ALH.removeGlobalVariable("GLOBAL_COUNT");
Checking an existing global variable

You can check if a global variable is defined in an environment by calling the isGlobalVariable(String
variableName) method

If the global variable specified by the given variable name is present in the scripting environment, this
method will return true. Otherwise, it returns false.
boolean isGlobalVariable(String variableName)
The following code fragment shows how to check if a global variable, e.g., GLOBAL_COUNT, is defined
through ALH API.
ALH.isGlobalVariable("GLOBAL_COUNT"); // Returns true or false.
Checking a visited State

You can check whether a specified State was visited by calling the following command
boolean wasInState(String stateName)
The following code fragment shows how to check whether a specified State of State Machine, e.g.,
State1, was visited through ALH API.
ALH.wasInState("State1"); // Returns true or false.
Getting the caller of a script

Once a script has been evaluated, you can use the following ALH API to trace from where the script was
called and access the Caller.
NamedElement getCaller()
It will return the Caller element of the script. For example, if a Behavior that runs a script is called from
a callBehavior, you will get a callBehavior action as the Caller.
The following code fragment shows how to trace from where the script was called, e.g., from State1,
through ALH API.
ALH.getCaller().getName(); // Trace from State1.

Getting a tag value
You can use the following API to get a tag value:
object getTagValue(Object_ object, String tagName) throws Exception
If the RuntimeObject is omitted, $context$ or self will be used as an object. The context object in the
parametric is the constraint block object that owns the constraint, not the actual context of the
diagram. The following example shows how to get a tag value without specifying a RuntimeObject in
ALH API:
object getTagValue(String tagName) throws Exception
The following code fragment shows how to get tag values, e.g., max, through ALH API. See also Value
access and references by tags(see page 510).
ALH.getTagValue(d, “uniform.max”); // 10
 Information
object.getTagValue(tagName). For example:
• d.getTagValue(“uniform.max”); // 10
Excel Helper APIs

Cameo Simulation Toolkit provides APIs to import data from an Excel file into runtime values, and
export the runtime values to an Excel file. Note that you need to install the Excel Import plugin in
MagicDraw before using these APIs. You will also need to create a mapping Class with this plugin. See
the Excel Import user guide for more information on using the plugin.
The provided APIs in Cameo Simulation Toolkit are given in the following pages
Reading runtime values from an Excel spreadsheet

Cameo Simulation Toolkit helps you read fUML runtime values from an Excel file. The following API will
read the values of a specific row from a spreadsheet in an Excel file, and then create an fUML ValueList
to store the values.

public ValueList readObjectFromSpreadSheet(String fileName, String sheetName, Number
rowIndex, Object mappingClass) {
...
}
The APIs can ignore the sheetName and use the first sheet of the selected spreadsheet instead.
public ValueList readObjectFromSpreadSheet(String fileName, Number rowIndex, Object

mappingClass) {
...
}
The following API will read the values from multiple rows of the selected spreadsheet in the Excel file,
and then create the fUML ValueList to store the values.
public ValueList readObjectsFromSpreadSheet(String fileName, String sheetName, Number

startRow, Number endRow, Object mappingClass) {
...
}
public ValueList readObjectsFromSpreadSheet(String fileName, Number startRow, Number

endRow, Object mappingClass) {
...
}
If you want to read all values from the selected spreadsheet, you can use the following API:
public ValueList readObjectsFromSpreadSheet(String fileName, String sheetName, Object

mappingClass) {
...
}
The API can ignore the sheetName and use the first sheet of the selected spreadsheet instead.

public ValueList readObjectsFromSpreadSheet(String fileName, Object mappingClass) {
...
}
The mappingClass parameter can be a String or an element for representing a mapping Class name or
a mapping Class element.
 Information
«ImportMap»112can be used as the mappingClass. However, it is strongly recommended that
you define the distinctive name of «ImportMap» and the «DiagramTableMapToDataSource» (an
Instance table linked to an Excel file) when using to avoid conflict of object mappingClass.
The APIs can ignore the mappingClass then create the runtime object of the file schema element that is
matched with filename.
public ValueList readObjectFromSpreadSheet(String fileName, String sheetName, Number

rowIndex) {
...
}
public ValueList readObjectFromSpreadSheet(String fileName, Number rowIndex) {
...
}
public ValueList readObjectsFromSpreadSheet(String fileName, String sheetName, Number
startRow, Number endRow) {
...
}
public ValueList readObjectsFromSpreadSheet(String fileName, Number startRow, Number
endRow) {
...
}
The following API can assign a name parameter to check the name of a mappingClass or a sheetName.
If the matching mappingClass cannot be found, this API will use the file schema element to create a
runtime object and check the sheet name of the Excel file with the name parameter.
public ValueList readObjectsFromSpreadSheet(String fileName, String name) {

...
}
112 https://docs.nomagic.com/display/MD2021xR2/Saving+an+Import+Map

Writing runtime values to an Excel spreadsheet
The following API helps you write fUML runtime values to an Excel file.
public void writeObjectsToSpreadSheet(Object object, String fileName, String

sheetName, Number atRow, boolean isReplace, Object mappingClass) {
...
}
public void writeObjectsToSpreadSheet(Object object, String fileName, Number atRow,

boolean isReplace, Object mappingClass) {
...
}
The mappingClass parameter can be String or Element for represent the mapping Class name or
mapping Class Element. The APIs can write the runtime objects of the file schema element to
spreadsheet that is matched the file name by ignore the mapping class.
public void writeObjectsToSpreadSheet(Object object, String fileName, String

sheetName, Number atRow, boolean isReplace) {
...
}
public void writeObjectsToSpreadSheet(Object object, String fileName, Number atRow,
boolean isReplace) {
...
}
 Information
You can also write runtime values to an Excel file (.xlsx) as an attached file supported(see page
145).
Setting a cell value in an Excel spreadsheet

You can assign an fUML runtime value to specific row and column in an Excel file by using the following
API

public void setCellValue(Object value, String fileName, String sheetName, Number
atRow, Number atCol) {
...
}
Getting a cell value from an Excel spreadsheet

You can get a value from a specific row and or column in an Excel file by using the following API
public Object getCellValue(String fileName, String sheetName, Number atRow, Number

atCol) {
...
}
Getting the latest row number from a spreadsheet

You can use the following API to get the latest row number from a sheet in an Excel file
public int getLatestRowNum(String fileName, String sheetName) {

...
}
Updating fUML runtime value with value from a spreadsheet

You can assign a value from a specific row in a spreadsheet in an Excel file to an fUML runtime value by
using the following API
public void updatefUMLValueFromSpreadSheet(StructuredValue value, String fileName,

String sheetName, Number rowIndex, Object mappingClass) {
...
}
public void updatefUMLValueFromSpreadSheet(StructuredValue value, String fileName,

Number rowIndex, Object mappingClass) {
...
}

The mappingClass parameter can be String or Element for represent the mapping Class name or
mapping Class Element. The APIs can ignore the mappingClass then update the runtime object of the
file schema element that is matched with file name.
Server-side simulation
On this page
• Preparing the environment for server-side simulation(see page 534)

• Preparing projects for server-side simulation(see page 535)
• Server-side simulation limitations(see page 535)
If you work with Teamwork Cloud projects, you can simulate them on the server without using a
modeling tool. You can execute your models either by using REST API or via Cameo Collaborator for
Teamwork Cloud user interface (if there are Cameo Collaborator documents published from those
models).
Preparing the environment for server-side simulation

Server-side simulation runs in Teamwork Cloud113, therefore you need to have access to a working
Teamwork Cloud instance.
To prepare the environment for server-side simulation
1. Install Teamwork Cloud114 if you have not already done that.

2. Stop Teamwork Cloud services (No Magic AuthServer, No Magic WebApp)
3. Go to <Teamwork_Cloud_installation_directory>\WebAppPlatform\webapps directory and replace
the webapp.war file with another webapp.war file provided by your sales executive.
4. Go to <Teamwork_Cloud_installation_directory\WebAppPlatform\shared\conf directory and open
the webappplatform.properties file.
5. In the file, make sure the following property is specified:
flexnet.server.name=<server_ip/server_address>
6. Restart the Web Application Platform.
113 https://docs.nomagic.com/display/TWCloud2021xR2/Teamwork+Cloud+Documentation
114 https://docs.nomagic.com/display/TWCloud2021xR2/Installation%2C+configuration%2C+and+licensing

Preparing projects for server-side simulation
To simulate a project on the web, it has to meet the following criteria:
• A project has to be added to Teamwork Cloud.

• For simulation results to be saved, you need to specify the Result Location property of a
Simulation Configuration. The value of the Result Location property should be the instance in
which you want to save the simulation results.
• The executable model should not require any user input. This means that the simulation needs
to be performed automatically.
• The executable model with behaviors must end automatically without any user input.
Server-side simulation limitations

There are several limitations related to server-side simulation:
• Currently, there is no UI in the simulation web application, so UI-based features (like charts,
timelines, controls, breakpoints, animation, variables tree, etc.) are not available.
• You can execute only one simulation at a time.
• Project options cannot be read, so default option values are always used instead of the actual
ones.
• Math engine integrations (Matlab, Mathematica, etc.) are not available.
• FMI/FMU co-simulation is not available.
• UseCase Execution is not available.
• Execution of historical project revisions is not available.
• Validating Requirement-based runtime models is not available.
• Lifelines representing Properties with nested paths in InteractionEngine are not available.
• DSL stereotypes are not applied to created Slot and InstanceSpecification elements
• Finding elements by Name (e.g Signals, Operations with ALH, mapping with ExcelHelper) is not
available.
Related pages
• Simulation using REST API(see page 535)

• Simulation using Jupyter Notebook(see page 542)
• Simulation in Cameo Collaborator for Teamwork Cloud(see page 548)
Simulation using REST API
On this page
• Start simulation(see page 536)

• Get simulation status(see page 538)
• Get simulation results(see page 539)

• Get the list of running simulations(see page 540)
• Terminate simulation(see page 540)
• Check for Simulation Configurations(see page 541)
• Get Simulation Configurations(see page 541)
It is possible to simulate Teamwork Cloud projects on the server by using REST API. The topics below
describe all available REST API requests and provide examples of how to use them.
 Prerequisites
Before starting the simulation, make sure you have prepared your environment and projects
for server-side simulation as described in the following topics:
You can use the following REST API requests to simulate Teamwork Cloud projects on the server:
• GET /simulation/api/start/project/<project>/branch/<branch>/element/<element_id>/config/
<config>(see page 536)
• GET /simulation/api/status/<simulation_id>(see page 538)
• GET /simulation/api/results/<simulation_id>(see page 539)
• GET /simulation/api/running(see page 540)
• GET /simulation/api/terminate/<simulation_id>(see page 540)
• GET /simulation/api/hasConfigs/project/<project>/branch/<branch>(see page 541)
• GET /simulation/api/configs/project/<project>/branch/<branch>/element/<element_id>(see page
541)
Start simulation
POST /simulation/api/start/project/<project>/branch/<branch>/element/<element_id>/config/
<config>
This REST API request starts the simulation. It connects to Teamwork Cloud, finds the element to
execute, and starts the simulation if the element exists. After the simulation is complete, the request
constructs and returns a unique ID (per application) for the given execution.
The following table describes the parameters used in the REST API request:
Parameter In Required or Description

optional
project path required The Teamwork Cloud project name or ID.
branch path optional The project branch name or ID. If the branch is omitted, the trunk is
used instead.

optional
element_id path optional The server ID of the Instance Specification to be executed.
config path required The Simulation Configuration name or server ID.
? quer optional A new project version is committed with the simulation results.
commitRes y Available values are true or false (default).
ults
inputs body optional A set of input parameters with values, which will be provided for the
simulation.
outputs body optional A set of output parameters, which will be obtained after the simulation
is complete. If no output parameters are specified, all initialized values
are returned.
Request and response examples
/simulation/api/start/project/SpacecraftMassRollup/branch/2/element/519701b0-
bec8-4f51-aad5-152a5411d60b/config/spacecraft mass analysis?resultAsJson=true
{
"simulationId": "c7944233-a1cb-4310-a62f-48bce07dd71c"
}
/simulation/api/start/project/CarBrakingAnalysis/config/Vehicle Analysis no Matlab
{
"simulationId": "cf83877b-86cc-466c-89a1-af97619a9a86"
}
/simulation/api/start/project/8715fcfa-fd34-4928-8480-13f4439cec3d/element/519701b0-
bec8-4f51-aad5-152a5411d60b/config/7915fcfa-fd88-4910-8560-13f4439cec3d
{
"simulationId": "b7bdf933-f58d-4e7e-b73b-8370c60485cd"
}
Request example with a request body
/simulation/api/start/project/SpacecraftMassRollup/config/spacecraft mass analysis

Request body:
{
"inputs":
{
"propulsion.tank.me": 38,
"propulsion.thruster.me": 30,
"telecom.antena.me": 19,
"telecom.amplifier.me": 8
},
"outputs":
[
"propulsion.me",
"telecom.me"
]
}
Response:
{
"simulationId": "b7bdf933-f58d-4e7e-b73b-8370c60485cd"
}
Get simulation status
GET /simulation/api/status/<simulation_id>
This REST API request gets the status and elapsed time for a specific simulation. It returns the actual
elapsed time of the simulation thread and the simulation state (RUNNING, COMPLETED, TERMINATED,
ERROR).

optional
simulation_id path required The ID of a specific simulation.
/simulation/api/status/ce8c8215-0515-43fd-9d34-92d1d7a95d87
{
"state": "COMPLETED",

"userId": "Administrator",
"elapsedTime": 8078
}
Get simulation results
GET /simulation/api/result/<simulation_id>
This REST API request returns the results of the specified simulation. In the start REST API body, you can
specify what output parameters should be returned. If output parameters are not specified, all output
parameters are obtained. In addition, if the CSV export results are available, they are returned in JSON
format.

optional
simulation_id path required The ID of the running simulation.
/simulation/api/results/ce8c8215-0515-43fd-9d34-92d1d7a95d87
{
"outputs": {
"me": 98.0,
"propulsion.me": 68.0,
"propulsion.tank.me": 38.0,
"propulsion.thruster.me": 30.0,
"telecom.me": 30.0,
"telecom.antenna.me": 10.0,
"telecom.amplifier.me": 20.0
},
"csv exports": {
"'SpaceCraftResults' csv export":
"me,propulsion.me,propulsion.tank.me,propulsion.thruster.me,telecom.me,telecom.amplif
ier.me,telecom.antenna.me\n98.0000,68.0000,38.0000,30.0000,30.0000,20.0000,10.0000\n9
8.0000,68.0000,38.0000,30.0000,30.0000,20.0000,10.0000\n98.0000,68.0000,38.0000,30.00
00,30.0000,20.0000,10.0000\n"
}
}

Get the list of running simulations
GET /simulation/api/running
This REST API request gets the list of all currently running simulations that you have started.
/simulation/api/running
["9bc18e3e-b544-4652-9bdb-6da1d75f7ea1"]
Terminate simulation
GET /simulation/api/terminate/<simulation_id>
This REST API request terminates the specified simulation.

optional
/simulation/api/terminate/4e35bc60-2c66-48e8-96e2-80f5270c08cf
/simulation/api/status/4e35bc60-2c66-48e8-96e2-80f5270c08cf
{
"state": "TERMINATED",

"userId": "Administrator",
"elapsedTime": 11702
}
Check for Simulation Configurations
GET /simulation/api/hasConfigs/project/<project>/branch/<branch>
This REST API request checks if the project has any Simulation Configurations.

optional
branch path optional The project branch name or ID. If the branch is omitted, the
trunk is used instead.
/simulation/api/hasConfigs/project/SpacecraftMassRollup
{
"hasConfigs": true
}
Get Simulation Configurations
GET /simulation/api/configs/project/<project>/branch/<branch>/element/<element_id>
This REST API request retrieves element IDs, names, and descriptions of the Simulation Configurations
available for the given executable element.
If the executable element is an Instance Specification, the method returns the following Simulation
Configurations:

• Whose execution target is the classifier of the executable element.
• Whose execution target is the Instance Specification having at least one classifier matching those
of the executable element.

optional
/simulation/api/configs/project/SpacecraftMassRollup
{
"configId": "7915fcfa-fd88-4910-8560-13f4439cec3d",
"configName": "spacecraft mass analysis",
"documentation": ""
}
Simulation using Jupyter Notebook

You can simulate Teamwork Cloud projects on the server by using Jupyter Notebook. This chapter
explains how to set up Jupyter Notebook for server-side simulation and lists all available commands
with examples.
 Prerequisites????
Before starting the simulation, make sure you have prepared your environment and projects
for server-side simulation as described in the following topics:
To set up Jupyter Notebook
• In Jupyter Notebook, run the following command to install a Python package from the
websimR1.zip file (contact your sales executive to get the archive file):

%pip install websimR1.zip
Use the following requests to simulate Teamwork Cloud projects on the server:
• Create client/session and authenticate???(see page 543)

• Start simulation(see page 543)
• Start simulation and get results(see page 545)
• Get simulation status(see page 546)
• Get simulation results(see page 546)
• Get the list of running simulations(see page 547)
• Terminate simulation(see page 547)
• Check for Simulation Configurations(see page 547)
• Get Simulation Configurations(see page 548)
Create client/session and authenticate???
from websim import SimulationWebClient
client = SimulationWebClient('https://kns-wapmaster.dsone.3ds.com:8443', 'https://kns-

waptwc1.dsone.3ds.com:8555', 'simweb', 'simweb', False)
This request starts a work session and provides authentication to Teamwork Cloud.
Start simulation
client.start(<project>, branch=<branch>, element_id=<element_id>, config=<config>,

commit_results=<True/False>, data=json.dumps(<param>))
This request starts the simulation.
The following table describes the parameters used in the request:

optional

optional
branch path optional The project branch name or ID. If the branch is omitted, the trunk is
used instead.
config path required The Simulation Configuration name or server ID.
commit_res path optional A new project version is committed with the simulation results.
ults Available values are True or False (default).
data path optional A set of output parameters, which will be obtained after the simulation
is complete.
# SpaceCraftMassRollup sample
parameters = {
"inputs":
{
"telecom.antenna.me":10,
"telecom.amplifier.me":20
},
"outputs":
[
"me",
"propulsion.me",
"propulsion.tank.me",
"propulsion.thruster.me",
"telecom.me",
"telecom.antenna.me",
"telecom.amplifier.me"
]
}
client.start('SpacecraftMassRollup_SimWeb', config='spacecraft mass analysis',

commit_results=False, data=json.dumps(parameters))

Start simulation and get results
client.simulate(<project>, branch=<branch>, element_id=<element_id>, config=<config>,

commit_results=<True/False>, data=json.dumps(<param>))
This request starts simulation and returns its results.
Paramete In Required or Description

r optional
project pat required The Teamwork Cloud project name or ID.

h
branch pat optional The project branch name or ID. If the branch is omitted, the trunk is used
h instead.
element_i pat optional The server ID of the Instance Specification to be executed.

d h
config pat required The Simulation Configuration name or server ID.

h
commit_r pat optional A new project version is committed with the simulation results. Available
esults h values are True or False (default).
data pat optional A set of output parameters, which will be obtained after the simulation is
h complete.
# SpaceCraftMassRollup sample
parameters = {
"inputs":
{
"telecom.antenna.me":10,
"telecom.amplifier.me":20
},
"outputs":
[
"me",

"propulsion.me",
"propulsion.tank.me",
"propulsion.thruster.me",
"telecom.me",
"telecom.antenna.me",
"telecom.amplifier.me"
]
}
client.simulate('SpacecraftMassRollup_SimWeb', config='spacecraft mass analysis',

commit_results=False, data=json.dumps(parameters))
Get simulation status
client.get_status(<simulation_id>)
This request gets the status of a specific simulation.

optional
Get simulation results
client.get_result(<simulation_id>)
This request returns the results of the specified simulation.

optional
simulation_id path required The ID of the running simulation.

Get the list of running simulations
client.get_running()
This request gets the list of all currently running simulations you have started.
Terminate simulation
client.terminate(<simulation_id>)
This request terminates the specified simulation.

optional
Check for Simulation Configurations
client.get_configurations(<project>, branch=<branch>, element_id=<element_id>)
This request checks if the project has any Simulation Configurations.

optional

Get Simulation Configurations
client.has_configurations(<project>, branch=<branch>)
This request retrieves the names and descriptions of the Simulation Configurations available for the
given project.

optional
Simulation in Cameo Collaborator for Teamwork Cloud
On this page
• Preparing projects for simulation in Cameo Collaborator for Teamwork Cloud(see page 548)
• Simulating projects in Cameo Collaborator for Teamwork Cloud(see page 551)
Cameo Collaborator for Teamwork Cloud(see page 548) has a user interface that allows you to simulate a
project directly in the Cameo Collaborator document published from that project.
Preparing projects for simulation in Cameo Collaborator for Teamwork Cloud

To simulate a project in Cameo Collaborator, it has to meet the following criteria:
• The project must have an Instance Table with the instance you want to execute, because
simulation in Cameo Collaborator is only possible using Instance Tables.
• For simulation results to be saved, you need to specify the Result Location property of a
Simulation Configuration. The value of the Result Location property should be the instance in
which you want to save simulation results.
• The executable model should not require any user input because Cameo Collaborator does not
support UI. This means that simulation needs to be performed fully automatically.
• The executable model must end automatically without any user input.

For more information about preparing projects for simulation in Cameo Collaborator for Teamwork
Cloud, analyze the example below. It explains how to modify the SpacecraftMassRollup.mdzip sample,
which you can find in the <modeling_tool_installation_directory>\samples\simulation directory.
To prepare the SpacecraftMassRollup.mdzip sample for simulation in Cameo Collaborator for Teamwork
Cloud
1. Go to the <modeling_tool_installation_directory>\samples\simulation directory and

open the SpacecraftMassRollup.mdzip sample.
2. Create an Instance Table with the instance you want to execute. Let's say you want to execute
the spacecraft Instance Specification. In this case, the project already has an Instance Table with
that instance, so you do not need to do anything.
3. Open the Specification window of the spacecraft mass analysis Simulation Configuration and
specify the Result Location property. Its value should be the instance in which you want to save
simulation results. Let's say you want to save the results in the same spacecraft instance which
you intend to execute.
4. In the same window, make sure the UI property is not specified because simulation should not
require any user input. If the UI is specified, it will be ignored.

5. Make sure the executable model ends automatically without any user input. You can do this in
one of the following ways:
• Model behavior diagrams in such a way that behaviors are terminated without any user
interaction.
• Specify Simulation Configuration timing properties so that simulation ends after a
certain End Time. For example, in the SpacecraftMassRollup.mdzip sample, do the
following:
i. In the Specification window of the spacecraft mass analysis Simulation Configuration,
select Timing Properties on the left side of the window.
ii. Specify the Start Time, End Time, and Step Size properties as shown below.

 Tip
The easiest way to check whether the executable model ends without user input is to run
it in a modeling tool.
6. Save and add the project to Teamwork Cloud115 (if the project is local).
7. Publish the project to Cameo Collaborator for Teamwork Cloud(see page 548).
Now you can open the Cameo Collaborator document and simulate the model on the web.
Simulating projects in Cameo Collaborator for Teamwork Cloud

Once you publish your project to Cameo Collaborator for Teamwork Cloud, you can simulate it in a
Cameo Collaborator document, as described below.
To simulate a project in Cameo Collaborator for Teamwork Cloud
1. Open the Cameo Collaborator document(see page 548) published from the project you want to
simulate.
2. Navigate to the Instance Table with the instance you intend to simulate.
115 https://docs.nomagic.com/display/MD2021xR2/Adding+projects+to+Teamwork+Cloud

3. Click on the bottom right corner of the screen.
 Requirement or Constraint verification

As you can see in the figure above, the Instance Table cells are highlighted in green or
red according to Requirement or Constraint verification results. To see the tooltip with
Requirement or Constraint text, hover the mouse pointer over a highlighted cell.
4. In the Instance table, select the instance you want to execute.

5. When the Select configuration and run pane opens on the right side of the screen, select the
Simulation Configuration you want to run.
6. Click on the top right corner of the pane.

7. Wait until the simulation is complete and the simulation results are displayed in the updated
document.
 Note
When you simulate a project in Cameo Collaborator for Teamwork Cloud, a new project
version is created with the following commit message: Simulation WebApp: '<Simulation
Config Name>' execution results.
Simulation with Simulation Template

You can simulate your model using a Simulation Template created in Simulia by simply dragging the
template to an Activity or Parametric Diagram.
 Prerequisites
To run the simulation with a Simulation Template from Simulia, the following conditions must
be met:
• The Process Composer Integration plugin has to be installed in your modeling tool.
• You need to have access to a Simulation Template in Simulia.
• The Simulation Profile must be used in the project you want to simulate.
To run the simulation using a Simulation Template from Simulia
1. In the main menu of a modeling tool, select 3DEXPERIENCE > Login and log into the
3DEXPERIENCE platform116.
116 https://docs.nomagic.com/display/MD2021xR2/Authentication+with+3DEXPERIENCE+platform

2. Use an internet browser to open the 3DEXPERIENCE platform and find the Simulation Template
from Simulia that you want to use.
3. Drag the Simulation Template from the 3DEXPERIENCE platform on the web to an Activity or
Parametric Diagram in your modeling tool.
 New model elements after adding a Simulation Template

• When a Simulation Template is dragged to an Activity diagram, an Activity with a
hyperlink to the Simulation Template is created. In addition, a Call Behavior Action
with the «3DXSimulationTemplate» stereotype is created and displayed in the
Activity Diagram. This Call Behavior Action invokes the Activity.
• When a Simulation Template is dragged to a Parametric Diagram, a Constraint
Block with a hyperlink to the Simulation Template is created. In addition, a
Constraint Property with the «3DXSimulationTemplate» stereotype is created and
displayed in the Parametric Diagram. This Constraint Property is typed by the
Constraint Block.
4. Model the Activity diagram to provide inputs and outputs for the Simulation Template (the Call
Behavior Action created after dragging the template to the diagram).

5. Run the simulation using a Simulation Configuration.
 Storing simulation results

If the Results Location property of a Simulation Configuration is specified as a Package,
the simulation results are stored in an Instance Specification. In addition, the Instance
Specification with the results has a hyperlink to the simulation process stored on the
3DEXPERIENCE platform.
Frequently asked questions
On this page

• Parametric evaluation(see page 556)
Activity simulation
Question 1:
Why isn't an operation outside a context object executed, e.g., an operation referring to an Activity
outside a Block?
Answer: According to the fUML specification, an operation will be dispatched to the target object only,
which is the context of the execution. You need to move the Activity into the Block and use it as a
CallBehaviorAction with the Behavior setting.

Question 2:
Can I simulate dummy tokens of CallBehaviorActions that do not have a Behavior?
Answer: Yes, you can set the Auto-Create fUML Object of Output Pin option in the
Simulation Project Options(see page 47) dialog to true, which is the default value in Version 19.0 SP2 and
later. Please see also Dummy tokens of Actions through Output Pins(see page 342).
Parametric evaluation
Question 1:
Why can't I use MATLAB as an external evaluator even after integration with MATLAB(see page 451) of the
modeling tool?
Answer: You must use either the 64-bit or 32-bit version of MATLAB (Version 2012a or later) to align it
with the 64-bit or 32-bit version of the modeling tool you are working with, e.g., MagicDraw or Cameo
Systems Modeler. According to using MATLAB on 32-bit and 64-bit Microsoft Windows117, you must also
ensure that Path of System variables in the Environment Variables dialog is set to the correct
MATLAB path.
Question 2:
Can I use MATLAB 2019b as an external evaluator?
Answer: Yes, you can use MATLAB 2019b as an external evaluator. MATLAB R2019b has a new option,
Single simulation output, set true by default in Simulink, which doesn’t affect the simulation.
However, there are a few limitations as follows:
• If Simulation cannot load the Simulink, e.g., an invalid URL/ filename, both warning and script
exception messages will be printed in the Console panel. In this case, the MATLAB engine cannot
be used, so you will need to manually restart MATLAB.
• If there is no input for the In Port, Simulation will skip the evaluation, and a warning message will
be printed in Console panel.
State Machine simulation

Question:
Can I change State activation semantics from before entry (official UML semantics) to after entry?
117 https://docs.nomagic.com/display/CST2021xR2/Using+MATLAB+on+32-bit+and+64-bit+Microsoft+Windows

Answer: Yes, you can set the State Activation Semantics option in the Simulation Project Options(see
page 47) dialog to After entry. The default value is Before entry in Version 19.0 and later. Please see
also State activation semantics.(see page 273)
Related pages

• Block(see page 484)
• Call Behavior Action118
• State activation semantics(see page 273)
• Dummy tokens of Actions through Output Pins(see page 342)
Simulation modeling: Do's and Don't's
On this page
• Don’t: Create an fUML loop without any Action Activation(see page 557)
• Do: Add an Action Activation in the loop(see page 558)
Don’t: Create an fUML loop without any Action Activation

When the fUML model has a loop without any Action Activation in the loop as shown in the figure
below, the code stack continually increases until StackOverflowError occurs, causing the execution to
be unexpectedly terminated. You can see StackOverflowError in the magicdraw.log file.
118 https://docs.nomagic.com/display/MD2021xR2/Call+Behavior+Action

The model runs an infinite loop until StackOverflowError occurs, and the
execution is terminated.
Do: Add an Action Activation in the loop

To avoid StackOverflowError, you must add at least an Action Activation, e.g., CallBehaviorAction in
the loop as shown in the figure below. The code stack will not increase continually without
StackOverflowError because Simulation has code to cut the stack loop and recall the Action at
ActivityNodeActivation.receiveOffer() and ActionActivation.fire() according to fUML v1.3
specification. The execution will be continuously run without unexpected termination.
The model runs an infinite loop without StackOverflowError, and the execution
is not terminated.
Related pages

• Action119
• Execution(see page 561)
• Call Behavior Action120
Developer Guide
Inc. All Rights Reserved.
Introduction
This document describes the Application Programming Interface (API) of Cameo Simulation Toolkit,
which is categorized into two fundamental APIs: (i) Java API and (ii) Action Scripts API.
The Java API is mostly used together with the MagicDraw plugin and the Action Script API is used
independently for each supported model element in a MagicDraw project.
All of the Cameo Simulation Toolkit API classes are packaged in the jar file simulation_api, which is
located in
• <MagicDraw installation directory>/plugins/com.nomagic.magicdraw.simulation/simulation_api.jar

You can find the Cameo Simulation Toolkit JavaDoc file in
• URL: http://jdocs.nomagic.com/190/CST121
• <MagicDraw installation directory>/openapi/docs/simulation/SimulationJavaDoc.zip
For more information about creating a new MagicDraw plugin, see the MagicDraw Open API user guide
located in
• <MagicDraw installation directory>/openapi/docs/MagicDraw OpenAPI UserGuide.pdf
 Note
Before going through each example given in this document, make sure that simulation.jar and
simulation_api.jar has been added to your IDE classpath.
SimulationOptionProvider interface
Simulation provides an internal API so that execution can have all simulation options from the
SimulationOptionProvider interface as shown in the figure below. You can use the Simulation API
independently in Teamwork Cloud or other platforms without modeling tool environment, e.g.,
MagicDraw.
Implementation Classes of the SimulationOptionProvider interface are

SimulationConfigOptionProvider (for Simulation Config(see page 49)) and
SimulationProjectOptionProvider (for project options(see page 47)), both of which will be used in the
SimulationOptions Class being deployed in the SimulationExecution Class. The
119 https://docs.nomagic.com/display/MD2021xR2/Action
120 https://docs.nomagic.com/display/MD2021xR2/Call+Behavior+Action
121 http://jdocs.nomagic.com/190/CST/

SimulationOptionConstants Class also contains all option constant variables used in Simulation, e.g.,
Active Color, Silent, etc.
SimulationOptionProvider interface.
 Information
You can find more details about the Simulation JavaDoc file at <MagicDraw installation
directory>/openapi/docs/simulation/SimulationJavaDoc.zip.
Java APIs
Through Java APIs, a simulation execution starts when the specific element is executed. You can start
the execution(see page 561), stop the execution(see page 561), and create and register a new Simulation
Execution Listener(see page 562) using Java APIs. Regarding the core component of the entire execution
mechanism, the execution engine(see page 564) defines how to execute a set of Element types. fUML
Helper(see page 568) is also available as a Class that provides Helper methods related to the fUML
structures. The Parametric engine also provides Java APIs for a parametric execution with a runtime
object of a Classifier.
 Information

For more information about Cameo Simulation Toolkit JavaDoc files, visit http://
jdocs.nomagic.com/190/CST122.
Related pages
Execution
A simulation execution represents a model execution of a specific element. It is the top level of the
model execution which contains running execution sessions and execution engines. A simulation
execution will start when the specific element is executed (through the graphical user interface or Java
API). The following APIs are available for handling executions.
• Start Execution
• Stop Execution
• Creating and Registering a New Execution Listener
Related pages
Starting execution
With Cameo Simulation Toolkit, you can start executing an element using the following Open APIs
• SimulationManager.execute(Element element) : SimulationSession

• SimulationManager.execute(Element element, Boolean isMainSession, Boolean start) :
SimulationSession
Once you use the aforementioned Open APIs, Cameo Simulation Toolkit creates corresponding
simulation sessions. The conditions when using the Open APIs to execute an element are as follows
• The specified element could be any executable element, such as a Class, a Behavior, or an
simulation configuration element.
• If the executed element is intended to be the main element of the execution, set the
"isMainSession" flag to true. Then, the created session will become the main session of the
execution. The main session is the first session created once the execution starts. If the main
session is terminated, all executions will be terminated accordingly.
• If the "start" flag is set to true, the created session will start itself automatically (similar to the
'autorun' option in an SimulationConfig).
Stopping execution
You can stop an execution by terminating its main session. Cameo Simulation Toolkit allows you to
terminate any simulation session using the following Open API
• SimulationManager.terminateSession(SimulationSession session) : void
122 http://jdocs.nomagic.com/190/CST/

Terminating a session will also cause all children of the specific session to be terminated.
Creating and registering a new SimulationExecutionListener

A SimulationExecutionListener Class is a listener for Events that will be activated during execution of a
model. All available Events are listed below.
• An execution is started.
• An element is activated.
• An element is deactivated.
• A signal event is triggered.
• An operation is called.
• A behavior is called.
• A runtime object is created.
• An execution is terminated.
public class SimulationExecutionListener {

void executionStarted(SimulationExecution execution);
void elementActivated(Element element, Collection<?> values);
void elementDeactivated(Element element, Collection<?> values);
void eventTriggered(SignalInstance signal);
void operationCalled(Operation operation, ParameterValueList pvl, Object_
caller, Object_ target, boolean isSynchronous);
void behaviorCalled(Behavior behavior, ParameterValueList pvl, Object_
caller, Object_ target, boolean isSynchronous);
void objectCreated(Object_ sender, Object_ object);
void valueChange(StructuredValue context, FeatureValue feature, Object
oldValue, Object newValue);
void executionTerminated(SimulationExecution execution);
void configLoaded(Element config);
void busyStatusChange(StructuredValue context, Object oldValue, Object
newValue);
}
Once you have created the execution listener, you can register it to a list of global execution listeners.
To register a new execution listener to a global list, type the following code
SimulationManager.registerSimulationExecutionListener(listener); //listener is an
instance of SimulationExecutionListener.
All registered listeners will be cleared and removed automatically when the execution is terminated.

 Note
ExecutionAdapter and ExecutionListener are not valid in Cameo Simulation Toolkit 19.0 and in
later versions.
All open APIs below are used by the Simulation Dashboard plugin and can be added for particular
purposes.
Open API Function
beforeObjectDestroyed(Object_ object) Works with an

object-destroying
Listener when added
into
SimulationExecution
Listener.
objectStateActivated(StructuredValue context, State newState) Works with a State

activation Listener
when added into
SimulationExecution
Listener.
SimulationExecutionListener.contextInitialized(SimulationExecution execution) Gets an Event when

objects have been
initialized but not
started the
execution yet.
SimulationHelper.findFeatureValue(Object_ runtimeContext, List<Property> Gets featureValue

propertyPath, Property target) : List<FeatureValue> objects that match
the given nested
property path.
SimulationHelper.getAvailableSignals(StructuredValue target, ExecutionEngine Retrieves available

engine) Signals from the
specified structured
value.
SimulationHelper.getConfigElement(SimulationExecution execution) Gets a Config

element.
SimulationHelper.isFeatureValueInvalid(FeatureValue featureValue, int index) Checks the validity

of FeatureValue.
SimulationManager.getContext(SimulationSession session) : Object_ Gets the execution

context.

Open API Function
SimulationManager.registerSimulationExecutionListener(SimulationExecutionList Registers
ener listener, SimulationExecution execution) SimulationExecution
Listener dynamically
during the
execution.
SimulationManager.unregisterSimulationExecutionListener(SimulationExecutionL Unregisters
istener listener) SimulationExecution
Listener.
SimulationManager.unregisterSimulationExecutionListener(SimulationExecutionL
istener listener, SimulationExecution execution)
Engine
An Execution Engine is a core component of the entire execution mechanism. It defines how to execute
a set of Element types, e.g., Elements in an Activity diagram, Elements in a State Machine diagram, and
so on.
API developers can create their own execution engines with the corresponding engine descriptors and
listeners, and register those engines to the simulation manager.
Creating a new execution engine

When creating an execution engine, you are required to implement three abstract methods in the
Subclass of ExecutionEngine (see JavaDoc for more details). These abstract methods are as follows
public abstract class ExecutionEngine {

...
public abstract void init(Element element);
public abstract void execute(Element element);
public abstract void onClose();
...
}
API developers can insert any desired code into the above abstract methods and get the events when
the execution engine is initialized, executed, and terminated.
You can execute the following code to create a MyExecutionEngine class
public class MyExecutionEngine extends ExecutionEngine {

public MyExecutionEngine(ExecutionEngineDescriptor engineDescriptor) {
super(engineDescriptor);
}
@Override
public void execute(Element element) {
...
}
@Override
public void init(Element element) {
Project project = Project.getProject(element);
// add engine listener if needed
EngineListener listener = new MyEngineListener(project);
addEngineListener(listener);
}
@Override
public void onClose() {
...
}
}
The created class MyExecutionEngine must be returned from createEngine() of its descriptor as defined
in Creating an execution engine descriptor(see page 565).
Creating an execution engine descriptor

The following example shows how to create an Execution Engine Descriptor
public interface ExecutionEngineDescriptor {

String getEngineName();
ImageIcon getEngineIcon();
boolean canExecute(Element element);
ExecutionEngine createEngine();
boolean canAnimate(PresentationElement element);
boolean isAutoDiagramOpened();
boolean canDebug();
boolean canUserTriggerEvents();
boolean isDiagramPerSession();
boolean isHasIdle();
boolean isFindEngine(Element element);
List<? Extends ValidationSuite> getValidationSuite();
}
The new execution engine descriptor must implement the ExecutionEngineDescriptor or extend the
AbstractExecutionEngineDescriptor abstract Class. You can find details about these Classes in JavaDoc.

public class MyExecutionEngineDescriptor extends
AbstractExecutionEngineDescriptor {
@Override
public boolean canExecute(Element element) {

return element instanceof Interaction;
}
@Override
public ExecutionEngine createEngine() {
return new MyExecutionEngine(this);
}
@Override
public String getEngineName() {
return "My Execution Engine";
}
}
The created execution engine descriptor must then be registered to the simulation manager (see
Registering an execution engine to the Simulation Manager(see page 567)).
Creating an execution engine listener

The following example shows how to create an engine listener
public class MyEngineListener implements EngineListener {
private Project project;

public MyEngineListener(Project project) {
this.project = project;
}
@Override
public void elementActivated(Element element, Collection<?> values) {
System.out.printIn("--Activate Element-- : element name =
" ((NamedElement)element).getName());
}
@Override
public void elementDeactivated(Element element, Collection<?> values) {
System.out.printIn("--Deactivate Element-- : element name = " +
((NamedElement)element).getName());
}
@Override
public void eventTriggered(String eventID) {
NamedElement element = (NamedElement)project.getElementByID(eventID);
System.out.printIn("--Event Trigger-- : event name = " +
((NamedElement)element).getName());

}
@Override
public void executionTerminated() {
System.out.printIn("--Engine Terminated--");
}
}
Once you have created an EngineListener, you can register it to the specified ExecutionEngine if you
want to receive events occurring in each execution engine. All engine listeners of a specific engine will
be activated under the conditions as follows
• An element is activated.
• An element is deactivated.
• An event is triggered.
• An engine is terminated.
public interface EngineListener {

void elementActivated(Element element, Collection<?> values);
void elementDeactivated(Element element, Collection<?> values);
void eventTriggered(String eventID);
void executionTerminated();
}
See Creating a new execution engine(see page 564) for more information about adding execution engine
listeners to the MyExecutionEngine class.
 Note
You can add more than one execution engine listener to an execution engine.
Registering an execution engine to the Simulation Manager

To register your new execution engine to the Simulation Manager, pass a new instance of your
execution engine descriptor to the Simulation Manager by typing the following code
SimulationManager.registerEngine(new MyEngineDescriptor());
In general, a new execution engine is registered at <Plugin Class>.init().
Activating and deactivating an element

An execution engine can activate a specific element with values by calling an activateElement(Element
element, Collection values)) of the ExecutionEngine. To deactivate the element, it will call a
deactivateElement(Element element, Collection values)) of the same class.

These two methods are mostly called in the ExecutionEngine.execute(element). For example, if an
Activity element on an Activity diagram is passed from the ExecutionEngine.execute(element), we use
the activateElement() and deactivateElement() methods to activate and deactivate the Actions in that
particular Activity respectively.
If activateElement() or deactivateElement() is called to a specific element, it will trigger all registered

engine listeners including both predefined and user-defined listeners. For example, an
AnimationListener is a predefined listener that is the Subclass of an EngineListener. It is used to display
a specific element animation (in highlight) on a diagram in MagicDraw.
Triggering an Event
An execution engine can trigger a given Event by calling the triggerEvent(String event) of an
ExecutionEngine. Just like the activateElement() and deactivateElement() methods, this method is
mostly used in the ExecutionEngine.execute(element).
If the triggerElement(String event) is called, the eventTriggered(String eventID) of all registered engine
listeners will be activated.
Printing messages in Simulation Console

You can print different types of messages on the Simulation Console pane by using the following
codes
• SimulationManager.logConsoleDebug (Project project, String message)

Displays debugging information.
• SimulationManager.logConsoleInfo (Project project, String message)

Displays information in general.
• SimulationManager.logConsoleWarn (Project project, String message)

Displays warning messages.
• SimulationManager.logConsoleError (Project project, String message)

Displays error messages.
fUML Helper
An fUMLHelper is a Class that provides Helper methods related to the fUML structures. See JavaDoc for
more details about this Class.

Parametric Helper as executing parametric simulation from an
Activity
The Parametric engine provides an API for a parametric execution with a runtime object of a Classifier.
The runtime object of the Classifier will be passed to the API as an argument and the engine will
execute the given object. With this API, you can use a scripting language to execute the parametric
simulation, shown below:
com.nomagic.magicdraw.simulation.parametrics.utility.ParametricsHelper.executeObject(
Object object);
An argument object is a runtime object of a classifier to be executed. To obtain this particular runtime
object, you can use some UML actions, e.g., ReadSelfAction, ReadStructuralFeatureValueAction,
ValueSpecificationAction, or the Cameo Simulation Toolkit Open API. The following figure shows the
Parametric Activity diagram in the CylinderPipe.mdzip sample. The action : ExecuteParametric is used
to run the parametric execution. The runtime object, which will be executed, is obtained from the value
Specification Action rawMaterialSupplier.

The Parametric Activity diagram in the CylinderPipe.mdzip sample.
Tutorial
Inc. All Rights Reserved.
Stopwatch model sample

This tutorial is intended to demonstrate how to create a UML model in MagicDraw that can be executed
by Cameo Simulation Toolkit. The model used in this tutorial is a simple stopwatch whose timer will
increment by 1 every second.
This tutorials provides the instructions to create a stopwatch model with MagicDraw and execute the
stopwatch model step-by-step. You will also learn how to create a mock-up user interface to use with
the stopwatch execution.
Before modeling a stopwatch, you will need to know the stopwatch structure and the stopwatch
Behavior.
Stopwatch structure
The structure of the stopwatch model in this tutorial is very simple. It only contains a time property,
which is typed by an integer. The time property will record the elapsed time when the stopwatch
receives a starting Signal. Therefore, the structure of the stopwatch system contains a StopWatch class
that has the time property.
Stopwatch Behavior
This tutorial uses the State Machine diagram to describe the main Behavior of the stopwatch. The
stopwatch has two stages: Initial and final.
A stage consists of four States as follows:
• Ready
The State where the stopwatch is ready to start.
• Running
When it receives the start Signal, the stopwatch will run, and the timer will start. In this State, the
stopwatch will be triggered by a time Event to increment the time value by 1 per second.
• Paused
The State where the stopwatch is paused and waiting for the user to restart it.
• Stopped
The State where the stopwatch stops running.
Related pages
• Executing the StopWatch class(see page 612)

Creating an executable stopwatch model
This section guides you through the steps required to create a stopwatch model in Cameo Simulation
Toolkit. You will learn how to create a new UML project as the first step, followed by creating the
stopwatch structure through defining the stopwatch Classifier and its structural features and adding a

Time attribute. In the next step, you will define the stopwatch Classifier Behavior by using the State
Machine Behavior (shown in this example). You will also be guided through creating an initial stage, the
ready, running, paused, stopped and final States, transition, Package of Signal elements, and Signal
Events for transitions for the stopwatch State Machine diagram. The last two sections explain new
operations required for defining the elapsed time and adding Activities to the ready and running States,
resetting the elapsed time to zero, and increasing the elapsed time by one.
Related pages
Creating a new UML project

First of all, we will need to create a new MagicDraw project.
To create a new MagicDraw project
1. Click File > New Project on the main menu. The New Project dialog will open.
2. Select UML Project from the General-Purpose Modeling group and enter the project name and
location. The project name will be "StopWatch" in this example.
3. Click OK.

Creating the stopwatch structure
Next, we will define the stopwatch Classifier and its structural features by using a Class diagram. We will
start by creating a new package to store the stopwatch model.
To create a new package to store the stopwatch model
1. Right-click Model in the containment browser and select New Element > Package. A new
package will be created under the Model node. Name the created package "system".
2. Create a new Class diagram in the system package by clicking the Class Diagram button on
the Diagrams toolbar. The Create Diagram dialog will open.

3. Name the Class diagram "System" and select the system package as the diagram owner.
4. Click OK.
 Note
You can also use the context menu of the system package to create a new Class diagram
by right-clicking the system package and select New Diagram > Class Diagram.
5. Use the diagram toolbar of Class Diagram to create a new Class Element and name the
created Class "StopWatch".

We will then add a Time Attribute to the StopWatch Class. Since this Attribute represents the elapsed
time in seconds, it will be typed by an Integer data type.
To add a Time Attribute to the StopWatch Class
1. Click the manipulated button (the small orange button) in the StopWatch Class. A new Attribute
will be created in the StopWatch Class.
2. Name the Attribute "time" and type it with an Integer by directly typing it into the Attribute
compartment of the StopWatch Class.

Defining the stopwatch Classifier Behavior
A Class Element, which can be executed with Cameo Simulation Toolkit, must have its Classifier
Behavior defined. The Classifier Behavior can be any kind of Behavior such as Activity, State Machine,
and Interaction. This tutorial uses the State Machine Behavior to define the Behavior of the stopwatch.
To define the Classifier Behavior for the StopWatch Class, you have to create the Behavior on the
StopWatch, which will be assigned later as the Classifier Behavior of the StopWatch automatically.
To define the Classifier Behavior for the StopWatch Class
1. Right-click the StopWatch symbol on the Class diagram and select New Diagram > State-
Machine Diagram.... A new State Machine Element will be created under the StopWatch Class
with a new State Machine diagram.
2. Name the State Machine diagram "StopWatch".
3. Make sure that the StopWatch State machine is the Classifier Behavior of the StopWatch Class.
To see the Classifier Behavior of the StopWatch Class, right-click the StopWatch symbol on the
Class diagram and select Specification from the context menu. The Specification window will
open.
4. Select All from the Properties drop-down menu.

5. Scroll down to see the ClassifierBehavior row, and you will see that the Classifier Behavior of
the StopWatch Class is defined by the StopWatch State Machine.

Next, we are going to create the StopWatch initial and final stages, and the four States (Ready,
Running, Paused, and Stopped) in the initial stage as well.
To add an Initial stage to the StopWatch State Machine
• Click Initial on the State Machine diagram toolbar, and then click any area on the State Machine
diagram to place the Initial stage.
To add the ready, running, paused, and stopped States
1. Click State on the State Machine diagram toolbar, and then click any area on the diagram to
place a State. Name the created State "ready".

2. Repeat Step 1 to create the "running", "paused", and "stopped" States.
To add a final stage to the State machine diagram
• Click Final State on the State Machine diagram toolbar, and then click any area on the diagram
to place the final stage.

Now that the initial and final stages have been created, you will need to add the transitions between
them and among the four States in the initial stage.
To add a transition from the Initial stage to the ready State
1. Click a stage (the Initial stage in this example) that will be the source of the transition to be
created. The smart manipulator toolbar will open.
2. Click the Transition icon on the smart manipulator toolbar.
3. Click a State (the ready State in this example) that will be the target of the transition.
4. Repeat Steps 1 to 3 to create more transitions between the following States:
from the ready to running State

from the running to paused State
from the running to stopped State
from the paused to running State
from the paused to stopped State
from the stopped to ready State
from the stopped State to the Final stage

5. Create a looping transition to the running State by clicking the Transitiontoself icon on the
smart manipulator toolbar.
6. Now your StopWatch State machine will look similar to the one shown in the following figure

You will see that some of the created transitions have the SignalEvent triggers. These triggers need
signal Elements and a package that is required to store those signal Elements. You can add a package
and create the signal Elements by using the browser context menu.
To add a new package for the signal Elements
1. Right-click the Model node in the containment browser and select New Element > Package.
2. Name the created package "signals".
To create signal Elements
1. Right-click the signals package and select New Element > Signal.
2. Name the created signal "reset". The reset signal will be created and stored in the signals
package.

3. Repeat Steps 1 to 2 to create the split, start, stop, and unsplit signal Elements.
To create signal Events for the transitions on the StopWatch State Machine diagram
• Drag a signal Element from the containment browser to a transition on the State Machine
diagram. The signal Event will later be specified as the trigger of the transition.

To create a signal Event for each transition
1. Drag the start signal to the transition between the ready and running States.
2. Drag the split signal to the transition between the running and paused States.
3. Drag the stop signal to the transition between the running and stopped States.
4. Drag the unsplit signal to the transition between the paused and running States.
5. Drag the stop signal to the transition between the paused and stopped States.
6. Drag the reset signal to the transition between the stopped and ready States.
7. Drag the stop signal to the transition between the stopped and Final States.
Now each and every transition between the States has its own signal Event. Next, you will also need to
create a signal Event for the transitiontoself of the running State. The signal Event that will be created
as the trigger for the transitiontoself is called TimeEvent.
To create a signal Event for the transition to self of the running State
1. Right-click the Transitiontoself of the running State and select Specification to open
2. Click the Categorized View button to open the properties of the transition in the categorized
view.
3. Click the EventType row in the Trigger category and select TimeEvent from the drop-down
menu.

4. Click the When row in the Trigger category and type "1s" to specify that the trigger will send the
time Event every second.
5. Click Close. You will see all of the created stages, States, transitions, and signal Events are shown
on the StopWatch State Machine diagram.

Defining the stopwatch operations by using Activities
This section defines the values of the elapsed time among the States in the StopWatch State Machine.
When the stopwatch enters the ready State, the elapsed time defined by the Attribute time:Integer[1]
should be reset to zero. In addition, the elapsed time should increment by 1 every second while the
StopWatch is at the running State. Therefore, we need to add two new operations: (i) ResetTime and (ii)
increaseTime to the StopWatch Class to define the elapsed time at the ready and running States. The
resetTime operation will reset the elapsed time to zero, and the increaseTime operation will
increment the elapsed time by one.
Related pages
• Creating resetTime Operation and resetTime Activity(see page 587)

• Creating increaseTime Operation and increaseTime Activity(see page 599)
Creating resetTime Operation and resetTime Activity

To create a resetTime operation
1. Right-click the StopWatch Class in the containment browser and select New Element >
Operation.

2. Name the new operation "resetTime". The resetTime operation will be created.
Next, we will use an Activity to define the resetTime operation. The Activity will contain the Actions and
the flows that will show the steps to set the time value to zero.
To create a resetTime Activity
1. Right-click the StopWatch Class in the containment browser and select New Element > Activity.
2. Name the created Activity "resetTime".
3. Add an Activity diagram to the resetTime Activity by right-clicking the resetTime Activity in the
containment browser and select New Diagram > ActivityDiagram. The new Activity diagram will
be created under the resetTime Activity. We will use the default name of this diagram, which is
"resetTime".

On the resetTime Activity diagram, you will need an AddStructuralFeatureValueAction to set the value
of time:Integer[1] to zero. The structural feature of the AddStructuralFeatureValueAction must be set
as the time attribute of the StopWatch Class.
To reset the time value of the StopWatch Object to zero using an AddStructuralFeatureValueAction
1. Click Action > Any Action... on the Activity diagram toolbar (see the following figure). The
Select Action MetaClass dialog will open.
2. Select AddStructuralFeatureValueAction and click OK.

3. Click the resetTime Activity diagram to place the position of the
created AddStructuralFeatureValueAction.
4. Right-click the symbol of the AddStructuralFeatureValueAction on the resetTime Activity
diagram and select Specification to open its Specification window.

5. Scroll down to the Structural Feature row, select it, and click the button.
The Select Property dialog will open.
6. The Attribute time:Integer[1] of the StopWatch Class will be selected as the structural feature of
this Action in this example.
7. Click OK to close the SelectProperty dialog and return to the Specification window.
8. Click the Is ReplaceAll row and select the check box. The AddStructuralFeatureValueAction
will remove any existing value and assign a new value to the structural feature.

We need to specify input pins for both the Object and the value of the
AddStructuralFeatureValueAction metaClass. The object of the Classifier that contains the structural
feature and its value will be supplied through these input pins respectively.
To create input pins
1. Click the Pins node on the left-hand side of the

AddStructuralFeatureValueActionSpecification dialog. The pins that are related to the
AddStructuralFeatureValueAction will appear.
2. Click the Value row and select InputPin.
3. Name the input pin "t" and specify its type as Integer.

4. Click the Close button.
5. Select AddStructuralFeatureValueAction on the resetTime Activity diagram and click the

Display Pins icon on the smart manipulator toolbar. The Select Pins dialog will open.

6. Select all pins and click OK.
To allow the object of the StopWatch to supply the value to self input using a ReadSelfAction
1. Click Action > AnyAction... on the Activity diagram toolbar. The SelectActionMetaClass dialog
will open.
2. Select ReadSelfAction and click OK.
3. Click the resetTime Activity diagram. A ReadSelfAction will be created on the diagram.
4. Click ObjectFlow on the Activity diagram toolbar and click the self output pin of the
ReadSelfAction and the self input pin of the AddStructuralFeatureValueAction. An object flow will
be created to connect these two pins together.

Next, we will create a ValueSpecificationAction to supply a value to the input pin t of
the AddStructuralFeatureValueAction.
To create a LiteralInteger of zero value using a ValueSpecificationAction
1. Click Action > AnyAction... on the Activity diagram toolbar. The Select Action MetaClass dialog
will open.
2. Select ValueSpecificationAction and click OK to close the Select Action MetaClass dialog.
3. Click the resetTime Activity diagram to create a ValueSpecificationAction.
4. Right-click the ValueSpecificationAction on the resetTime Activity diagram and select
Specification to open its Specification window.
5. Select the Value row and click the ShowShortcutMenu button, and select Value Specification
> Literal Integer to create a Literal Integer.

6. A new Literal Integer with a default value of 0 will be created as the value of
the ValueSpecificationAction.
7. Right-click the pin result of the ValueSpecificationAction on the resetTime Activity diagram and
select Specification to open its Specification window.
8. Rename the output pin (result) to "t" and specify its type as Integer.
9. Add an Initial stage and an Activity Final stage to the resetTime Activity diagram.
10. Click ControlFlow on the Activity diagram toolbar to connect the Initial Node to the
AddStructuralFeatureValueAction and the AddStructuralFeatureValueAction to the Final stage.

You have now created a complete resetTime Activity diagram. The next thing you will need to do is to
set the Specification of the resetTime Activity to the resetTime operation.
To set the Specification of the resetTime Activity to the resetTime operation
1. Right-click the resetTime Activity in the containment browser and select Specification to open
2. Select the Specification row and click the button (see the following figure). The
Select Element dialog will open.

3. Select the resetTime operation of the StopWatch Class as the specification of the Activity and
click OK to close the Select Element dialog.
4. Click Close to close the Specification window.

Creating increaseTime Operation and increaseTime Activity
An increaseTime operation is necessary for the StopWatch operation. It is used to increase the value of
time by 1 whenever the operation is called. Therefore, we need to create an operation and Activity for
the StopWatch Class to define this operation the same as we did for a resetTime operation and
resetTime Activity.
To create an operation and an Activity for the StopWatch
1. Right-click the StopWatch Class in the containment browser and select New Element >
Operation.
2. Name the new operation "increaseTime".
3. Right-click the StopWatch Class in the containment browser and select New Element > Activity.
4. Name the new Activity "increaseTime".
5. Right-click the increaseTime Activity in the containment browser and select New Diagram >
ActivityDiagram to add an Activity diagram to the increaseTime Activity. The new Activity
diagram will be created under the increaseTime Activity. We will use the default name of this
diagram, which is "increaseTime".
To increase the time values, the increaseTime Activity will do the following
(ii) get the object of the StopWatch using a ReadSelfAction
(ii) obtain the current time value using the ReadStructuralFeatureAction
(iii) increment the time value by one using an OpaqueBehaviorAction
(iv) set the increased time value to the object of the StopWatch using AddStructuralFeatureValueAction
(v) set the specification of the IncreaseTime Activity to the IncreaseTime Operation
(i) Getting the object of the StopWatch using a ReadSelfAction
The Object of the StopWatch, which contains the time value, must be obtained by using a
ReadSelfAction. To create the ReadSelfAction, you can follow the same steps used to create the
ReadSelfAction in the resetTime Activity. In this example, the Object, which is the value of the output
pin of the ReadSelfAction, needs to be supplied to multiple Actions (ReadStructuralFeatureAction and
AddStructuralFeatureValueAction that will be created later). Therefore, a Fork must be added to this
Activity.
To add a Fork to an Activity
1. Click Fork Vertical on the Activity diagram toolbar.
2. Click the increaseTime Activity diagram to create a Fork.

3. Click ObjectFlow on the Activity diagram toolbar to connect the fork and the self output pin.

(ii) Obtaining the current time value using a ReadStructuralFeatureAction
Once you have obtained the object of the Stopwatch, you will need to get the time value.
To get the current time value using a ReadStructuralFeatureAction
1. Click Action > Any Action on the Activity diagram toolbar. The Select Action MetaClass dialog
will open.
2. Select ReadStructuralFeatureAction and click OK.
3. Click the increaseTime Activity diagram. A new ReadStructuralFeatureAction will be created on
the diagram.
4. Right-click the ReadStructuralFeatureAction symbol on the diagram and select Specification to
open its Specification window.

5. Select the StructuralFeature row and click the button. The SelectProperty dialog will open.
6. Select the Attribute time:Integer[1] of the StopWatch Class and click the OK button.
7. Click ObjectFlow on the Activity diagram toolbar to connect the Fork and the self input pin
of ReadStructuralFeatureAction.

(iii) Incrementing the time value by one using an Opaque Behavior Action
We need an OpaqueBehaviorAction to increase the time value. An OpaqueBehaviorAction receives an

integer value as its input parameter and returns the integer value, which is the value of the input
parameter that has been incremented by one.
To create an Opaque Behavior for the increaseTime Activity
1. Right-click the increaseTime Activity in the containment browser and select New Element
> Opaque Behavior. A new Opaque Behavior will be created under the increaseTime Activity.
2. Name it "increase".
3. Right-click the increase Opaque Behavior in the containment browser and select Specification
to open its Specification window.
4. Select the Parameters node in the Specification window and click the Create button . A new
parameter will be created for the increase Opaque Behavior, and the Parameter Specification
window will open.
5. Name the parameter "ti", select Integer as its type, and select in as its direction.

6. Click the Back button to return to the Specification window of the increase Opaque Behavior.
7. Repeat the same steps used to create the parameter ti to create another parameter, which will
be a return parameter of the increase Opaque Behavior.
8. Name the return parameter "to", select Integer as its type, and select return as its direction.
9. Click the Back button to return to the Specification window of the increase Opaque Behavior.
Once the parameters "ti" and "to" have been created, we will write a simple JavaScript that will be
executed during the simulation.

To create a simple JavaScript to be executed in the simulation
1. Open the increase Opaque Behavior's Specification window and select the increase
Opaque Behavior node on the left-hand side of the dialog.
2. Type a JavaScript into the Body row, e.g., "to=ti+1".
 Note
You can use any scripting language that is supported by JSR-223. To specify the scripting
language that you are going to use, type it directly in the Language row. JavaScript will
be used by default if no scripting language is specified.

4. Create an OpaqueBehaviorAction on the increaseTime Activity by dragging the
created increase Opaque Behavior from the containment browser to the increaseTime Activity
diagram. A new OpaqueBehaviorAction will be created with the pins that correspond to the
defined parameters ti and to.
5. Name the created OpaqueBehaviorAction "inc".
6. Click ObjectFlow on the Activity diagram toolbar to connect the output pin t of
the ReadStructuralFeatureAction and the input pin ti of
the inc:increase OpaqueBehaviorAction .

(iv) Setting the increased time value to the object of StopWatch
using AddStructuralFeatureValueAction
Once the time value has been increased using the inc:increase OpaqueBehaviorAction, you need to set
it back to the Object of StopWatch. To do this, you can follow the same steps used to create the
AddStructuralFeatureValueAction on the resetTime Activity.

To set the increased time value to the object of StopWatch
1. Follow the same steps used to create the AddStructuralFeatureValueAction on the resetTime
Activity diagram.
2. Get the AddStructuralFeatureValueAction to set the value to the time:Integer of StopWatch. Make
sure that the IsReplaceAll of the AddStructuralFeatureValueAction is set to true.
3. Click ObjectFlow on the Activity diagram toolbar to connect from the output pin to of
inc:increase OpaqueBehaviorAction to the input pin t of the AddStructuralFeatureValueAction
(see the steps required for resetting the time value of the StopWatch object to zero with
AddStructuralFeatureValueAction in Creating resetTime Operation and resetTime Activity(see page
587)).
4. Add an Initial Node and an Activity Final stage to the increaseTime Activity and click
ControlFlow on the Activity diagram toolbar to connect between the Actions.
(v)Setting the specification of the increase time Activity to the IncreaseTime Operation
To set the specification of the increaseTime Activity to the increaseTime operation
1. Open the Specification window of the increaseTime Activity by right-clicking the

increaseTime Activity in the containment browser and select Specification.

2. Select the Specification row and click the button. The Select Element dialog will open.
3. Select the increaseTime operation of the StopWatch Class as the specification of the Activity.
4. Click OK to close the Select Element dialog.
Adding Activities to the ready and running States
Next, we are going to add some Activities to the ready and running States. These Activities will be
executed when these States are entered.
Related pages

• State124
Adding a reset Activity to the ready State

To add a reset Activity to the Entry to the ready State
1. Right-click the ready State on the StopWatch State Machine diagram and select Specification to
open the State's Specification window.
2. Select the Entry row and click the button. A context menu will open.
3. Select Activity. A new Activity will be created for the entry to the ready State.
124 https://docs.nomagic.com/display/MD2021xR2/State

4. Name the created Activity "reset".
5. Click Close to close the Specification window. The reset Activity will be added to the entry to the
ready State on the StopWatch State Machine diagram as shown .
6. Add an Activity diagram to the created reset Activity of the ready State by right-clicking the reset
Activity in the containment browser and select New Diagram > Activity Diagram. A new Activity
diagram will be created.

7. Use the default name of the diagram, which is "reset".
8. Add a CallBehaviorAction to the resetTime Activity on the reset Activity diagram by dragging the
resetTime Activity from the containment browser to the reset Activity Diagram.

9. Complete the reset Activity by adding an Initial stage and a Final Activity stage to the reset
Activity diagram and connect the two stages and the resetTime Action using ControlFlow, which
is on the Activity Diagram toolbar.
Adding an increase activity to the running state

Next, we are going to create an increased Activity, which will be called when the running State is
reached. To add the Activity to the running State, follow the same steps used to create the reset Activity
for the entry to the ready State.
To add an Increase Activity to the entry to the running State
1. Right-click the running State on the StopWatch State Machine diagram and select Specification
to open the State's Specification window.
2. Select the Entry row and click the button. A context menu will open. Select Activity to add a
new Activity to the Entry to the running State.
3. Name the created Activity "increase".

4. Click Close to close the Specification window. The increase Activity will be added to the entry to
the running State on the StopWatch State Machine diagram as shown in the following figure
5. Add an Activity diagram to the created increase Activity and use the default name, which
is "increase".
6. Add a CallBehaviorAction to the increaseTime Activity on the increase Activity diagram by
dragging the increaseTime Activity from the containment browser to the increase Activity
diagram.
7. Add an Initial stage and a Final Activity stage to the increase Activity diagram and connect the
two stages and the increaseTime action with ControlFlow, which is on the Activity Diagram
toolbar.
At this point, the StopWatch has been completely modeled. You can now execute the StopWatch class
using Cameo Simulation Toolkit.

Executing the stopwatch model
This section shows you how to execute the StopWatch model with Cameo Simulation Toolkit. The
StopWatch Class will be selected to execute the model.
Related pages
Executing the StopWatch class

The StopWatch Class is now ready to be executed. You can execute the StopWatch Class either from the
containment browser or from the diagram.
To execute the StopWatch Class
1. Either (i) select the StopWatch class in the containment tree and click the Run button on
the Simulation Control main toolbar or (ii) right-click the StopWatch class and
select Simulation > Run.

2. The Simulation window will open. It contains four tabs: (i) Sessions, (ii) Console, (iii) Variables,
and (iv) Breakpoints tabs. At this point, a simulation session to execute the StopWatch Class will
be created. You can see this session in the Sessions tab of the Simulation window.

3. Click the Start button on the Simulation window toolbar.
Once you have clicked the Run Execution button, the Object of the StopWatch Class will be created
and shown in the Variables tab. The Classifier Behavior of the StopWatch class and the StopWatch
State Machine will be executed respectively. A new session to execute the StopWatch State Machine
will be created under the simulation session of the StopWatch class, and the StopWatch State
Machine diagram will be open and ready for the simulation.
The StopWatch State Machine execution will start from the initial stage and automatically move to the
ready state because the transition which connects between the initial stage and ready state does not
have a defined trigger. When the ready State is entered, the reset Activity, which is assigned as the
entry to the ready State, will be invoked. This Activity also calls the resetTime activity of the StopWatch
Class for setting the time value to be zero. At this point, a new simulation session will be created to
execute the resetTime Activity, and the resetTime Activity diagram will be open and animated.

The execution of the resetTime Activity will be terminated once it has reached the final stage. When
the simulation stops, the session executing the resetTime Activity will be closed, the StopWatch State
Machine diagram will be reactivated, and the simulation will wait for an Event signal at the ready State.
You can browse the StopWatch object in the Variables tab to see the time value.

Now we want to trigger the StopWatch object from the ready State to the running State. To do this, we
need to send a start signal to the StopWatch object.
To send an event (start) signal to the object of the StopWatch Class
1. Select the StopWatch node in the Variables tab. The signals that can be sent to the StopWatch
will be listed in the Trigger drop-down menu.
2. Select the start signal from the Triggers drop-down menu (see the following figure).
 Note
You can click the arrow button on the left or right-hand side of the Simulation window toolbar
to scroll the toolbar to the left or to the right.

Once the start Signal has been sent, the StopWatch will go to the running State. At the entry to the
running State, the increase Activity will be defined; therefore, it will be invoked. The increase Activity
will then call the increaseTime Activity of the StopWatch Class to increment the time value by one
second. A new simulation session will be created to execute the increaseTime Activity, and the
increaseTime Activity diagram will be open and animated.

The increaseTime Activity will be completely executed when its Final stage has been reached. Once the
execution is complete, the simulation session of the increaseTime Activity will be closed and the
StopWatch State Machine will be activated again. Now you can see in the Variables tab that the time
value of the StopWatch object has been incremented by one.
The StopWatch object will still be at the running State and the time Event will be triggered at this State
every second. Therefore, a new simulation session will be created to execute the increaseTime activity
every second, and the time value will increment by one every time the increaseTime Activity is
executed.

While the StopWatch object is at the running State, we can send a split signal to trigger the object to
the paused State or send a stop signal to trigger the object to the stopped State.
To send a split signal to the StopWatch object
1. Select the StopWatch object in the Variables tab.

2. Select the split signal from the Triggers drop-down menu on the Simulation window toolbar.
The state of the StopWatch object will be changed to the paused State.
You can change the paused StopWatch object to the running State by sending an unsplit signal to the
object.

To change the StopWatch object from a paused state to a running State

2. Select the unsplit signal from the Triggers drop-down menu on the Simulation window toolbar.
The state of the StopWatch object will be changed to the running State, and the time value will
continuously increase.
To send a stop Signal to the StopWatch object

2. Select the stop signal from the Triggers drop-down menu on the Simulation window toolbar.
The State of the StopWatch object will be changed to the stopped State.

At the stopped State, if the reset signal is sent to the StopWatch object, the object will go to the ready
State, and the time value will be reset to zero at the entry to the ready state by calling the resetTime
Activity. If the stop signal is sent to the object again, the object will go to the final stage, and then the
simulation will stop and all of the simulation sessions will be closed.
Executing the StopWatch instance specification

In the previous section, we have shown you how to execute the StopWatch model from the StopWatch
Class. You can also use Cameo Simulation Toolkit to execute the model from an InstanceSpecification.
With this feature, you can specify values to the slots of an InstanceSpecification. These values will be
used as the input values for the execution such as using a ReadStructuralFeatureAction to read the
values.
In this tutorial, our StopWatch contains only one value property, which is time. The time value will
always reset to zero whenever the system enters the ready State. If we create an InstanceSpecification
of StopWatch and use it for model execution, the result will be the same as the model execution of the
StopWatch Class.
To create an InstanceSpecification of StopWatch
1. Open a System Class diagram.

2. Click Instance on the Class Diagram toolbar and click the System Class diagram. A
new InstanceSpecification will be created and the Select Classifier dialog will open.

3. Select the StopWatch Class and click OK.
4. On the Class diagram, name the created InstanceSpecification "stopwatch". Now we will need to
create values and assign them to the slots.
To create values and assign them to the slots
1. Right-click the symbol of the stopwatch InstanceSpecification and select Specification to open
the Specification window of the stopwatch InstanceSpecification.
2. Select the Slots node on the left-hand side of the dialog.
3. Select the Structural Feature of the slot to which the values will be applied. In this case,
select time:Integer[1].

4. Click the Create Value button. A new integer value will be created for the slot. If an Integer value
is selected, a zero will be created by default. You can modify this value by typing a new value into
the Value box.

To start executing the stopwatch InstanceSpecification, right-click it either on the System Class diagram
or in the containment browser and click Execute. A simulation session will be created in the Sessions
tab of the Simulation window to execute this instance. The steps to run the execution are the same as
those to execute the StopWatch Class.

Executing the StopWatch using Simulation Configuration
Cameo Simulation Toolkit allows you to customize model execution by using an Simulation
Configuration. The Simulation Configuration is a stereotype that can be applied to a Class Element. This
stereotype contains tag definitions for model execution customization such as enable or disable
animation and UI mockups. To be able to use the Simulation Configuration, we need to add the
SimulationProfile.mdzip file to our project.
To add the SimulationProfile.mdzip file to a project
1. Click File > Use Project on the main menu. The Use Project wizard dialog opens.
2. Select the From predefined location option.
3. Select <install.root>\profiles in Project modules paths, and then select SimulationProfile.mdzip.
4. Click Next to go to the second step, Module Settings.

5. Use the default settings and click Finish. The simulation profile will be added to the project. You
can see it in the containment browser.
An Simulation Configuration is a Class Element, which is applied with the «SimulationConfig»

stereotype (see the following figure). This stereotype contains tag definitions to customize model
execution (see SimulationConfig stereotype(see page 49)).

Next, we will create the Simulation Configuration to execute our StopWatch model without using
animation.
To execute our StopWatch model without using animation
1. Open a System Class diagram.

2. Create a new Class Element by clicking the Class button on the Class diagram toolbar.
3. Click the diagram to create the Class Element.
4. Name the created Class Element "SilentStopwatch".
5. Right-click the SilentStopwatch Class and select Stereotype to apply the
«SimulationConfig» stereotype to the created Class. The Stereotype context menu group will
open.

6. Select SimulationConfig from the list of available stereotypes for the Class Element.

7. Click Apply. The SilentStopwatch Class will be with the applied SimulationConfig stereotype.
Next, we will create a SimulationLog to record the runtime events occurrence and assign this
SimulationLog to the SimulationConfig.
To record all runtime events occurrence and assign a SimulationLog to the SimulationConfig
1. Create a new Class Element by clicking the Class button on the Class diagram toolbar.
2. Click the diagram to create the Class Element.
3. Name the created Class "SimulationLogs".
4. Right-click the SimulationLogs Class and select Stereotype to apply the
«SimulationLog» stereotype to the created Class. The Stereotype context menu will open.

5. Select SimulationLog and click Apply. The SimulationLogs Class will be with the
applied «SimulationLog» stereotype.

Now we need to specify the tagged values of the «SimulationConfig» stereotype that is applied to
the SilentStopwatch Class.
To specify the tagged values of the «SimulationConfig» stereotype
1. Open the Specification dialog of the SilentStopwatch Simulation Configuration by right-clicking

the SilentStopwatch symbol and select Specification.
2. Select the Tags node on the left-hand side of the dialog.
3. Select SimulationProfile from the Profile drop-down menu.

4. Specify the tagged value of the execution target to the StopWatch Class by selecting
executionTarget and click CreateValue. The SelectElements dialog will open for you to select
the Element that will be the execution target.

5. Select the StopWatch Class (you can also select the stopwatch InstanceSpecification, which has
been created in the previous section) as the executionTarget.
6. Click OK to close the Select Elements dialog.
7. Follow the same steps used to set the tagged value of executionTarget to the StopWatch Class
and specify the tagged values of the following tag definitions
i. log to SimulationLogs.
ii. resultLocation to the Stopwatch folder.
iii. silent to true.

8. Click Close to close the Specification dialog.
To execute the Simulation Configuration
1. Right-click the SilentStopwatch symbol on the diagram and select Simulation > Execute.
2. Click the RunSimulation button on the Simulation window toolbar to start the simulation. The
StopWatch Class will then be executed without animation. You will need to wait until the
runtime object of StopWatch is at the ready State. You can see the State of the runtime object at
the Variables tab. The State of the object will be displayed in square brackets.
3. Select the StopWatch node in the Variables tab.
4. Select the start signal from the Triggers drop-down menu on the Simulation window toolbar.
Now, you can see that the value of time:Integer, which is displayed in the Variables tab, will increase
by one every second.

To stop the execution
1. Select the StopWatch node in the Variables tab.

2. Select the stop signal from the Triggers drop-down menu. The StopWatch object will go to
the stopped State.
3. Select the stop signal again to move the object to the final stage to close the simulation session.
The latest value of time:Integer will be saved into the slot value of the stopwatch
Creating User Interface mockups for the stopwatch model

Cameo Simulation Toolkit allows you to use the MagicDraw's User Interface (UI) Modeler to create user
interface mockups that will be displayed during model execution. This session shows you how to create
a user interface for the stopwatch model. The user interface will be in the form of a panel with buttons
to send signals to the runtime object of the stopwatch during model execution. A label will be used to
show the runtime time value.
To create user a interface mockup
1. Right-click the Model node and select New Element > Package to create a new package for the
UI Elements.
2. Name the created package "ui".
3. Click the button on the Custom Diagram toolbar to create a new User
Interface Modeling Diagram. The Create Diagram dialog will open.
4. Name the diagram "StopWatchUI" and select the ui package as the owner of the diagram.

5. Click OK.
6. Create a new frame for the UI mockup by clicking Frame on the User Interface Modeling
Diagram toolbar.

7. Create a label to show the runtime time value by clicking Label on the diagram toolbar.

8. Create five buttons to send the signals to the runtime object of the stopwatch model by
clicking Button on the diagram toolbar.
9. Name the buttons: Start, stop, split, unsplit, and reset.

10. Create a UI Prototype by dragging the StopWatch Class from the containment browser to
the created UI frame on the diagram.

11. Create a Runtime Value Prototype by dragging the time property of the StopWatch Class from
the containment browser to the created label on the diagram.
12. Create a Signal Instance Prototype by dragging the Signal from the containment browser to each
of the buttons. The buttons will send the dragged signals to the runtime object when you click
them during the execution. Therefore, each signal in the stopwatch model will be dragged to
each button that has a corresponding name. For example, the start signal will be dragged to the
start button, and the stop signal will be dragged to the stop button.

13. Open the Specification window of the SilentStopwatch Simulation Configuration to add the
ready user interface mockup for the stopwatch to the SimulationConfig for the StopWatch.
14. Edit the UI field by clicking the button. The Select«UI» dialog will open.

15. Select the created Frame in the ui package and click OK.
The modified SilentStopwatch is now ready to run the stopwatch with the UI mockup. Next, you need to
run the SilentStopwatch Simulation Configuration.
To run the SilentStopwatch Simulation Configuration

1. Right-click the SilentStopwatch Simulation Configuration and select Simulation > Run.
A simulation session will be created to execute the StopWatch class.
2. Click the RunSimulation button on the Simulation window toolbar. The execution of the
StopWatch class will start with the designed UI mockup. The time value displayed in the label is
now zero (0).

You can click the start button to start the stopwatch. You can use the buttons on the UI mockup to
send the signals to the runtime object of the StopWatch class. The time value displayed on the
label of the UI mockup will increment by one every second.
Click the stop button to stop the execution and click it again to go to the final stage, which is the
termination of the execution.
Using simulation command line and showing test results

through Jenkins
On this page
• Preparing a simulation project and Configs in MagicDraw(see page 645)

• Running a project through simulate command line(see page 646)
• Creating a JUnit test case and configuration file(see page 647)
• Configuring Jenkins for the Automated testing(see page 647)
• Simulate command arguments and parameters(see page 649)
• Simulate command arguments with projects in Teamwork Cloud(see page 652)
• Property file sample: Project-Config1.properties(see page 653)
• JUnit test sample: TestSimulationCommandLine.java(see page 654)
• Ant configuration file sample: run_junit.xml(see page 656)

 Note
In these scenarios, all related items on this page to be used are in
the TestSimulationCommandLine.zip125 sample.
Preparing a simulation project and Configs in MagicDraw

To prepare a simulation project and Configs in MagicDraw
1. Create a simulation model with Behaviors, e.g., TestVerdictKind.mdzip.

2. Apply «TestCase» to the Behaviors so the pass/fail status will be returned to the VerdictKind
Activity parameters.
3. Create Simulation Configs and set those Behaviors as executionTarget of those Simulation
Configs.
 Note
All required resources must be available for the Simulation Configs, e.g., loadCSV and
fmu. All features preventing simulation from the start/terminate, e.g., false autoStart,
context without Classifier Behavior, chart windows at the end of execution, or output
parameters at the end of execution (running Activity) will also be automatically started/
terminated.
4. Run each Simulation Config to verify that an expected result, either pass or fail, must be
returned.
5
12 https://docs.nomagic.com/download/attachments/82761156/TestSimulationCommandLine.zip?

Preparing a simulation project and Configs in MagicDraw.
Running a project through simulate command line

To run a project through simulate command line
1. Run the command line console, e.g., cmd on Windows.

2. In the console, type any commands to go to the local installation of MagicDraw.
3. Go to the plugins\com.nomagic.magicdraw.simulation folder.
4. Use the following simulate command (see page 649)syntax: simulate -project “[Path of an MDZIP
project]” -config “[Config]”.
In this case, the following commands are used:
simulate -project “D:\\Simulation\\API\\TestVerdictKind.mdzip” -config “Run

GeneratePassResult”
simulate -project “D:\\Simulation\\API\\TestVerdictKind.mdzip” -config “Run
GenerateFailResult”

5. At the last line of the command prompt, pass or fail appears. You can also see the details of
execution through the Simulation Log File(see page 204).
Running the project through the simulate command line.
Creating a JUnit test case and configuration file

To create a JUnit test case and configuration file
1. Include the JUnit library in the Java project by creating a new Java project and adding the JUnit 4
library in current location using the Eclipse's JUnit.
2. Create a new JUnit test case, e.g., Test Simulation Command Line.java(see page 654).
3. Compile the test case and create a JAR file, e.g., TestSimulationCommandLine.JAR from the test
case.
4. Create properties file, e.g., TestGeneratePassResult.properties and
TestGenerateFailResult.properties.
5. Create an Ant configuration file(see page 656), e.g., run_junit.xml.
Configuring Jenkins for the Automated testing

To configure Jenkins for the Automated testing
1. Create a new Jenkins project.

2. Specify a Project Name, e.g., Test Simulation Command Line.
3. Go to Advanced Project Options, click Advanced, and select Use custom workspace.

4. In the Directory box, specify a path to the directory that contains run_junit.xml (Ant
configuration file(see page 656)).
5. Go to Build and click Add build step. Select Invoke Ant.
6. In the Targets box, type build.
7. Select Advanced. In the Build File box, type run_junit.xml.

8. In the Properties box, specify md.root=[MagicDraw installation directory] and
properties.files.dir=[Path containing the properties files], as shown in the example above.
 Tip
The path containing the property files can be either an absolute (full) path, e.g., C:
\Users\User\Desktop\TestSimulationCommandLine\tests or relative path, e.g., tests.
9. Go to Post-build Actions and click Add post-build action. Select Publish JUnit test result
report.
10. In the Test report XMLs box, specify a path to JUnit XML files, e.g., test-reports/**TEST*.xml.

11. Run the build. Test Result will be shown and allows you to view more details for those test cases.
Test Result of the simulation command line is shown on the Jenkins page.
Simulate command arguments and parameters

Examples of the simulate command lines are as follows:
• On Windows: simulate.bat -project "../../samples/simulation/HingeMonteCarloAnalysis.mdzip" -config

"Monte Carlo Analysis"
• On Mac OS: sh simulate.sh -project "../../samples/simulation/HingeMonteCarloAnalysis.mdzip" -config
"Monte Carlo Analysis"
Type of Parameter Description

argument
Mandatory -project Specify a file name with the path of a MagicDraw project. Both relative and
arguments absolute paths are supported.

-config Specify a SimulationConfig without a qualified name to run.
 Note
If SimulationConfig has duplicate names (in different package), a
warning message will be displayed in the Simulation log, and the first
name will be used.
-properties Specify the name of a properties file to use, e.g., in

propertiesFil the TestSimulationCommandLine.zip126 sample.
eName
 Note
• If the -properties option is specified, the argument is the
name of a properties file, and the mandatory argument is
no longer required.
• A properties file contains -project and -config, along with
the specified data of each parameter.
Optional -inputs Specify one or more properties with values that will be provided to the
arguments elementNam Simulation Configuration.
eListWithVal
ue
-inputsFile Specify the name of the properties file containing the parameters with values
propertiesFil that will be provided to the Simulation Configuration.
eName
 Note
If you provide both -inputs and -inputFile arguments, parameters
are collected from both arguments.
-outputs Specify one or more properties whose values should be obtained during the
elementNam simulation
eList
-outputsTem Specify the properties file that contains the parameters whose values should
plate be obtained during the simulation.
propertiesFil
eName
 Note
If you provide both -outputs and -outputTemplate arguments,
parameters are collected from both arguments.
6
12 https://docs.nomagic.com/download/attachments/33212749/TestSimulationCommandLine.zip?

-outputsFile Specify the properties file which will contain the output parameters with
propertiesFil values after the simulation. The specified file will contain the parameters
eName provided in the -outputTemplate or/and -outputs argument.
Optional -servertype Specify type of the server to connect, <tw> or <twcloud>, where <tw> is
(server) Teamwork Server, as the default type of the server, and <twcloud> is
arguments Teamwork Cloud.
-server Specify a name or an IP Address (and port) of the server.
-leaveproject Leave the project open per property file after simulating the project, in a series
open of project simulation. The default value is false.
-login Specify a login name to log on to the server.
-password Specify a password to log on to the server.
-spassword Specify an encrypted password to log on to the server.
 Note
To generate an encrypted password for this option, use the following
command line (the characters of the encrypted password will be
returned, e.g., 49034c0439….):
generate -generatepassword “Administrator”
-ssl Specify to use and enable Secured Connection (SSL), <true> or <false> as the
default value.
-pversion Specify the version of the server project.
-tag Specify the tag name of the server project.
 Note
• -tag can't be used with -pversion.
• If multiple projects are returned, only the latest version
will be run.

-readonly Specify true (by default) to open the project as historic in the latest version
without specifying -pversion.
Specify other values to open the latest version normally.
Teamwork -branch Specify a branch of Teamwork Cloud projects.

Cloud
arguments
 Note
• -branch and -pversion cannot be specified in the same
command.
• If -pversion and -tag are not specified, the latest version
of the specified branch will be returned.
-updatemod Specify update project usages if required, <true> or <false>, where <false> is
ule the default.
-projectpass Specify a project password.

word
Simulate command arguments with projects in Teamwork Cloud

To use simulate command arguments with projects in Teamwork Cloud127, the projects must be added
to Teamwork Cloud. The following examples demonstrate how to use the simulate command to run a
model from Teamwork Cloud.
Scenario Command argument
Simulate a project with an encrypted simulate -project "HingeMonteCarloAnalysis" -config "Monte Carlo
password and enable a secured Analysis" -servertype "twcloud" -server "localhost:1234" -login
connection (-spassword, -ssl). "Administrator" -spassword "49034c0439…" -ssl "true"
Simulate a project by specifying a project simulate -project "HingeMonteCarloAnalysis" -config "Monte Carlo
version and project password (-pversion, Analysis" -servertype "twcloud" -server "localhost" -login
-projectpassword). "Administrator" -password "Administrator" -pversion "5"
-projectpassword "Administrator"
Simulate a project by specifying a tag simulate -project "HingeMonteCarloAnalysis" -config "Monte Carlo
name and branch (-tag, -branch). Analysis" -servertype "twcloud" -server "localhost" -login
"Administrator" -spassword "49034c0439…" -tag "duplicatedTag"
-branch "19.0 SP2"
 Note
If there are any duplicated tags
in the branch, the latest version
will be run.
127 https://docs.nomagic.com/display/MD2021xR2/Using+Teamwork+Cloud

Simulate a command with three property simulate -properties "D:\\Simulation\\Project-Config1.properties" "D:
files having different parameters. \\Simulation\\Project-Config2.properties" "D:\\Simulation\\Project-
See Property file sample: Project- Config3.properties"
Config1.properties(see page 653).
Simulate a project in Teamwork Server by simulate -project "HingeMonteCarloAnalysis" -config "Monte Carlo
specifying a project version (-pversion). Analysis" -servertype "tw" -server "localhost" -login "Administrator"
-password "Administrator" -pversion "2"
Simulate a project in Teamwork Server by simulate -project "HingeMonteCarloAnalysis" -config "Monte Carlo
specifying an encrypted password and Analysis" -servertype "tw" -server "localhost" -login "Administrator"
tag name (-spassword, -tag). -spassword "49034c0439…" -tag "run2000"
Simulate multiple projects in a single simulate -leaveprojectopen true -properties

command with better performance "Properties1_Undefined.properties"
(-leaveprojectopen). "Properties2_Undefined.properties"
"Properties3_Undefined.properties"
 Tip
When large-size projects need to
be loaded and closed for many
property files, it takes longer
time to simulate projects. In this
case, you can use
-leaveprojectopen as an option
to reduce memory for loading
each project.
Simulate a project in Teamwork Cloud simulate -project "SpacecraftMassRollup" -config "spacecraft mass
while specifying several input parameters analysis" -inputs telecom.amplifier.me=8 telecom.antenna.me=29 -
that will be provided for the Simulation outputsFile “SimResults” -servertype "twcloud" -server "localhost”
Configuration (-inputs). -login “Administrator" -spassword "49034c0439…"
Simulate a project in Teamwork Cloud simulate -project "SpacecraftMassRollup" -config "spacecraft mass
while specifying the properties file that analysis" -inputsFile “D:\\Simulation\\InputsParams.properties”
will be provided to the Simulation -outputsTemplate “D:\\Simulation\\OutputParams.properties”
Configuration (-inputsFile), the properties -outputsFile "D:\\Simulation\\SimResults.properties" -servertype
file containing the parameters whose "twcloud" -server "localhost” -login “Administrator" -spassword
values should be obtained "49034c0439…"
(-outputsTemplate), and the properties
file that will contain output parameters
with their values after the simulation (-
outputsFile).
Property file sample: Project-Config1.properties
project=Project1
config=Config1
servertype=twcloud

server=localhost
login=Administrator
spassword=49034c0439d3d1acc8d212adc289670c6224af46f2ec597eea1f25071740d5615a82d82d446
0d5b95747f1e369ed26cdb5bb70fe6f50ff095cf978f1743
e5fbae6c4f2eef98abbca482133e4ca045c3ce407134e9c42966d2f245aed349d39fecd6a49f67b5019d5
668e09cfd7f10a9363c5657a01addb9829052ffc26c49364
JUnit test sample: TestSimulationCommandLine.java
package com.nomagic.magicdraw.simulation;
import static org.junit.Assert.assertNotNull;

import static org.junit.Assert.assertTrue;
import static org.junit.Assert.fail;
import java.io.BufferedReader;
import java.io.File;
import java.io.IOException;
import java.io.InputStreamReader;
import java.nio.file.Files;
import java.nio.file.Path;
import org.junit.Before;
import org.junit.Test;
/**
* A test class for running the simulation command line and checking for the pass/
fail result.
* @author Chanon S.
*/
public class TestSimulationCommandLine {

private static final String MD_ROOT_PROPERTY = "md.root";
private static final String PROPERTIES_FILES_PROPERTY = "properties.files.dir";
private static final String MD_DIR = System.getProperty(MD_ROOT_PROPERTY);
private static final String SIMULATION_COMMAND_LINE = MD_DIR + "/plugins/
com.nomagic.magicdraw.simulation/simulate.sh";
private static final String PROPERTIES_FILES_DIR =
System.getProperty(PROPERTIES_FILES_PROPERTY);
private static final String PASS_PROPERTIES =
"TestGeneratePassResult.properties";
private static final String FAIL_PROPERTIES =
"TestGenerateFailResult.properties";
private static final String SYSTEM_NEW_LINE =
System.getProperty("line.separator");
@Before
public void assertBuildExist() {
System.out.println(MD_ROOT_PROPERTY + "=" + MD_DIR);
System.out.println(PROPERTIES_FILES_PROPERTY + "=" + PROPERTIES_FILES_DIR);
assertNotNull(MD_ROOT_PROPERTY + " is not specified.", MD_DIR);

assertNotNull(PROPERTIES_FILES_PROPERTY + " is not specified.",
PROPERTIES_FILES_DIR);
assertTrue("MagicDraw directory does not exist, MD_DIR=" + MD_DIR, new

File(MD_DIR).exists());
assertTrue("Properties files directory does not exist,PROPERTIES_FILES_DIR="
+ PROPERTIES_FILES_DIR, new File(PROPERTIES_FILES_DIR).exists());
assertTrue("Could not find simulate.sh file, SIMULATION_COMMAND_LINE=", new
File(SIMULATION_COMMAND_LINE).exists());
}
@Test(timeout = 120000)
public void testGeneratePassResult() {
// This project and Simulation Config generate "pass" as the result of
TestCase.
String propertyFilePath = PROPERTIES_FILES_DIR + "/" + PASS_PROPERTIES;
String consoleOutput = runWithProperties(propertyFilePath);
System.out.println("Console output=" + consoleOutput);
boolean result = consoleOutput.contains(SYSTEM_NEW_LINE + "pass" +
SYSTEM_NEW_LINE);
assertTrue(consoleOutput, result);
}
@Test(timeout = 120000)
public void testGenerateFailResult() {
// This project and Simulation Config generate "fail" as the result of
TestCase.
String propertyFilePath = PROPERTIES_FILES_DIR + "/" + FAIL_PROPERTIES;
String consoleOutput = runWithProperties(propertyFilePath);
boolean result = consoleOutput.contains(SYSTEM_NEW_LINE + "pass" +
SYSTEM_NEW_LINE);
assertTrue(consoleOutput, result);
}
private String execute(String command) {

System.out.println("Executing, command=" + command);
StringBuilder result = new StringBuilder();

try {
Process p = Runtime.getRuntime().exec(command);
BufferedReader input = new BufferedReader(new
InputStreamReader(p.getInputStream()));
String line;
while ((line = input.readLine()) != null) {
result.append(line);
result.append(SYSTEM_NEW_LINE);
}
} catch (IOException e) {
e.printStackTrace();
}
return result.toString();
}
private String runWithProperties(String propFilePath) {

String absPropPath = propFilePath;
if (propFilePath != null) {
Path path = new File(propFilePath).toPath();
if (!Files.exists(path)) {
fail("Properties file <" + propFilePath + "> not found.");
} else {
absPropPath = path.toAbsolutePath().toString();
}
}
String cmd = propFilePath == null || propFilePath.isEmpty() ?
SIMULATION_COMMAND_LINE : SIMULATION_COMMAND_LINE + " -properties \"" + absPropPath +
"\"";
return execute(cmd);
}
}
Ant configuration file sample: run_junit.xml
<project name="Run JUnit and Generate Reports" default="build" basedir=".">

<target name="build" depends="set.properties, prepare, run.junit" />
<target name="set.properties">
<property name="md.root" location="${md.root}" />
<property name="properties.files.dir" location="${properties.files.dir}" />
<property name="test.reports.dir" location="test-reports"/>
</target>
<target name="prepare">
<delete dir="${test.reports.dir}" />
<mkdir dir="${test.reports.dir}" />
</target>
<target name="run.junit">
<junit printsummary="yes" fork="yes">
<classpath>
<pathelement location="lib/TestSimulationCommandLine.jar"/>
<pathelement location="lib/junit-4.12.jar"/>
<pathelement location="lib/hamcrest-core-1.3.jar"/>
</classpath>
<jvmarg value="-Xmx1200m" />
<jvmarg value="-Xms256m" />
<jvmarg value="-XX:PermSize=128M" />
<jvmarg value="-XX:MaxPermSize=256M" />
<jvmarg value="-XX:-UseSplitVerifier" />
<jvmarg value="-noverify" />
<sysproperty key="md.root" value="${md.root}" />

<sysproperty key="properties.files.dir" value="${properties.files.dir}" /
>
<batchtest todir="${test.reports.dir}">
<zipfileset src="lib/TestSimulationCommandLine.jar">
<include name="**/*.class"/>
</zipfileset>
</batchtest>

<formatter type="xml" />
</junit>
</target>
</project>
Analysis pattern
Rollup Pattern simulation
On this page
• Simulation with a built-in rollup pattern(see page 657)

• Simulation with a custom rollup pattern(see page 659)
Cameo Simulation Toolkit supports rollup calculations of total mass, cost, power, and another system
dimension, based on individual values of all the parts in the model. Please refer to Rollup Pattern
Wizard128, applying Rollup Pattern Blocks129, and LaptopCostAnalysis and SpacecraftMassRollup
built-in samples for more details.
Simulation with a built-in rollup pattern

The LaptopCostAnalysis sample applies built-in CostRollUpPattern. The sample uses the Cost
Analysis Block with the Laptop context Block as the Part. Optionally, you can add any constraint
(maxCost) and Requirement (Total cost) and use a Parametric diagram to connect them as shown in the
figure below.
128 https://docs.nomagic.com/display/SYSMLP2021xR2/Rollup+Pattern+Wizard
129 https://docs.nomagic.com/display/SYSMLP2021xR2/Applying+Rollup+Pattern+Blocks

The Cost Analysis Block containing the Laptop context Block applied with built-
in CostRollUpPattern as the Part.
You can also either run the simulation through the Cost Analysis Block directly or use a
SimulationConfig(see page 49) with executionTarget = the Cost Analysis Block. The result will be shown in the
totalCost context Block, e.g., 220 (80+50+90) as shown in the figure below.

The totalCost context Block as the result of Laptop cost analysis applied with
CostRollUpPattern.
Simulation with a custom rollup pattern

The SpacecraftMassRollup sample applies a custom rollup pattern through the same applying Rollup
Pattern Block130 like the built-in one but requires selecting a Pattern Block for the custom rollup
pattern, e.g., Component. The Component Pattern Block uses value type properties binding with 5
constraint properties in the Parametric diagram as shown below.
A Parametric diagram of the Component custom rollup pattern as a Pattern

Block.
Optionally, you can add any constraint (less) and Requirement (Estimated mass), and then run the
spacecraft mass analysis SimulationConfig(see page 49) with the executionTarget as an instance of the
spacecraft to run. The result of evaluation, according to the me < ma rule, will be highlighted at me :
mass[kilogram] for each component shown on the right side in the Block Definition diagram as shown
below.
130 https://docs.nomagic.com/display/SYSMLP2021xR2/Applying+Rollup+Pattern+Blocks

The evaluation result (me : mass[kilogram]) of the SpacecraftMassRollup sample
applied with the Component custom rollup pattern.
Monte Carlo simulation
On this page
• Creating a system model(see page 661)

• Inheriting the Hinge Analysis Block from the MonteCarloAnalysis Block(see page 662)
• Creating a parametric diagram and binding values(see page 662)
• Creating a Simulation Configuration diagram and configuring other settings(see page 663)
• Running SimulationConfig and reviewing results(see page 664)
Cameo Simulation Toolkit introduces built-in support for Monte Carlo analysis, a technique that
involves using random numbers and probability to solve problems. You can manage uncertainties and
estimate how random parameters affect the overall performance of the system being modeled. Please

refer to the HingeMonteCarloAnalysis131 sample model on the welcome screen as the feature
demonstration with the following steps.
Creating a system model

1. Transform the stochastic model: D > A+B+C (random components) to the deterministic model: D-
(A+B+C) > 0.
2. Create the system model and Parts with a Block Definition diagram with required value
properties, e.g., Blocks Hinge, AB, C, and D.
3. Create constraint Blocks with parameters and constraint specification according to the
requirement, e.g., Clearance_equation, R1, and R2.
4. Create a Requirement with a satisfy Relation to the value property to keep the result for the
constraint, e.g., Hinge Clearance and Unassemblable.
5. Apply a «distribution» Type to get a set of random inputs of the value properties of the Parts
based on Requirements, e.g., «uniform» with max and min and «normal» with mean and
standardDeviation.
The Block Definition diagram of the Hinge model with distributed value
properties applied.
6. Create a parametric diagram in the system to bind the value properties to the parameters of the
constraint Block, e.g., Clearance equation.
1
13 https://docs.nomagic.com/download/attachments/75335382/HingeMonteCarloAnalysis.mdzip?

A parametric diagram of the Hinge model.
Inheriting the Hinge Analysis Block from the MonteCarloAnalysis Block

1. Create another Block Definition diagram and include an analysis context definition by dragging
the MonteCarloAnalysis Block from MD Customization for SysML::analysis patterns into the newly
created Block Definition diagram, e.g., AnalysisDefinition.
2. Create and inherit a new Block from the Block Definition diagram created in Step 1 as an analysis
Block, e.g., Hinge Analysis, to get OutOfSpec, N, Mean, and Deviation properties. The inheritance
can be done through creating a generalization Relation from the MonteCarloAnalysis Block to the
system model Block (from the Creating a system model(see page 661) section).
3. Create an association Relation, e.g., hinge, to make the Hinge system model block part of the
analysis Block, e.g., Hinge Analysis.
Inheriting the Hinge Analysis Block from the predefined

MonteCarloAnalysis Block and setting the Hinge Block as part of the Hinge
Analysis Block.
Creating a parametric diagram and binding values

1. To specify a parameter as the target of Monte Carlo analysis, create a parametric diagram in the
analysis block to bind properties and constraints. The statistical value will be recorded in Mean as
a result from the termination of the analysis loop, e.g., clearance.
2. Connect constraints from Requirements to Mean for the Requirement verification and to
OutOfSpec for the percentage of the samples whose Mean value violates any of the attached
constraints or Requirements, e.g., R1 and R2.

Specifying the Requirement verification (R1) and OutOfSpec property (R2)
of the Monte Carlo analysis in another Parametric diagram.
Creating a Simulation Configuration diagram and configuring other settings

1. Create a Simulation Configuration diagram, add a SimulationConfig(see page 49) to the newly
created diagram, and set the following tags:
• executionTarget: the analysis block, e.g., Hinge Analysis Block.
• numberOfRuns: the number of runs, e.g., 5000.
• resultLocation: an Instance table, e.g., Analysis results.
• silent: true for the optimum performance of the simulation.
• name (optional): e.g., Monte Carlo Analysis.
 Note
• For a model that has Behaviors (Classifier Behavior and/or Part Property
with Behaviors), see the autoStart tag in SimulationConfig(see page 49).
• If numberOfRuns of any table (executionTarget) is more than 1, it will be
ignored in the Monte Carlo simulation. The table, however, will be run only
once.
• If silent is set to false, the simulation will run with animation and idle time
for each iteration, which is not practical for the Monte Carlo simulation.
2. Drag a Histogram(see page 125) control from the Simulation toolbar to the Simulation
Configuration diagram. You can use the histogram as a local user interface by setting the
following tags:

• represents: the analysis Block, e.g., Hinge Analysis.
• value: the monitored value property, e.g., clearance.
• dynamic: true for viewing dynamically updated statistical values (false will open the
histogram at the end of execution).
• name (optional): e.g., Histogram.
3. Record generated value properties of every iteration using the CSV Export(see page 141) control by
setting the following tags:
• represents: the system model Block, e.g., Hinge.
• value: related value properties, e.g., a.width, b.width, or clearance.
• fileName: the exported file name, e.g., clearance.csv.
• name (optional): e.g., clearance.
4. Drag the Histogram and CSV Export controls to the «SimulationConfig». UI and executionListeners
tags will be updated with the names of the Histogram and CSV Export controls accordingly, e.g.,
Histogram and clearance.
«SimulationConfig» setting with numberOfRuns, Histogram, CSV Export,

and Instance table.
Running SimulationConfig and reviewing results

1. Run the SimulationConfig from the previous section, e.g., Monte Carlo Analysis.
2. During the simulation, the histogram will dynamically show the estimated distribution of the
values of the analysis context definition at the top right, e.g., hinge.clearance, N, Mean, SD, and
OutOfSpec.
3. The simulation progress bar will be shown with the number of iterations and time elapsed. You
can click Cancel to terminate the simulation, and the analysis result will be saved at the
terminated iteration.

The histogram dynamically shows statistical results during the simulation.
4. The summary result is recorded in the Instance table along with «VerificationStatus(see page 243)»
between value property and constraint, e.g., Mean-R1 and OutOfSpec-R2. You can also see the
detail of constraint failure in the tooltip when hovering the mouse over any highlighted red
values.
The summary result is recorded in the Instance table with verification

status.
5. Sampling results of value properties from applied distributions stereotypes(see page 504) are
exported to the CSV file in the same location as the project. The file can be accessed through the
link, e.g., clearance.csv, in the Console pane.

Sampling results are exported to the clearance.CSV file.
Trade study analysis
On this page:
• Creating a Trade Study Analysis Block(see page 667)

• Inheriting the Analysis Block from the Trade Study Analysis Block(see page 668)
• Creating an Internal Block diagram for alternatives kind = Instance Table(see page 668)
• Creating an Internal Block diagram for alternatives kind = Subtypes(see page 669)
• Creating an Internal Block diagram for alternatives kind = Excel(see page 671)
• Creating an Internal Block diagram for alternatives kind = Parameter Sweep(see page 672)
• Creating a Simulation Configuration diagram and configuring other settings(see page 674)
• Running the SimulationConfig and reviewing results(see page 675)
A trade study or trade-off study is the activity of a multidisciplinary team to identify the most balanced
technical solutions among a set of proposed viable solutions (System Engineering Manual, Federal
Aviation Administration, 2006).

A trade study is used to compare with a number of alternative solutions to see whether and how well
they satisfy a particular set of criteria. Each solution is characterized by a set of measures of
effectiveness (often abbreviated “moe’s”) that corresponds to evaluation criteria and has a calculated
value or value distribution. The moe’s for a given solution is then evaluated using an objective function
(often called a cost function or utility function), and the results for each alternative are compared to
select a preferred solution.
Cameo Simulation Toolkit has built-in support for trade study analysis. The TradeStudyExamples
sample model is used as a demonstration for trade study analysis through the following steps.
Creating a Trade Study Analysis Block

1. Create a new Analysis Block in a Block Definition diagram (BDD), e.g., TradeStudyInstances.
2. Add the main Block of the simulation context as the Part Property of the newly created Analysis
Block, e.g., v : VehicleAnalysis.
3. Create a constraint Block containing a constant expression for determining the best weighted
value and related constraint parameters, e.g., Criteria.
4. Add the newly created constraint Block as a Constraint Property in the Analysis Block then right-
click the Constraint Property and select Stereotype objectiveFunction.
 Note
• «objectiveFunction» is a special type of a constraint Block for determining all
values of weighted alternatives in terms of weighted criteria.
• The specification of the constraint must be an equation with LHS = RHS, where
LHS contains only one parameter to bind with TradeAnalysis::^score, and RHS can
contain multiple parameters (bound with corresponding value properties) to
evaluate as winner criteria.
• The output of «objectiveFunction» will be compared with previous weighted
results. If an alternative is greater, it will be set as the winner (maximum value by
default). However, if you want the minimum value, use a negative value, e.g., value
= -distance.
5. Create alternatives by creating references properties typed by a Block of alternatives and apply
«alternatives» to the newly created references properties, e.g., C : Caliper, R : Rotor, and P : Pad as

The created structure of a Trade Study Analysis Block.
Inheriting the Analysis Block from the Trade Study Analysis Block
1. From the Containment tree under the MD Customization for SysML::analysis patterns::trade
study package, drag TradeStudy «Block» «Analysis» into the Block Definition diagram (BDD)
created in the previous section.
 Note
The TradeStudy package is available in all SysML projects. If the MD Customization for
SysML package is not visible, click in the Containment tree pane and select Show
Auxiliary Resources.
2. To inherit the TradeStudy «block» «Analysis», create a Generalization Relation from the
TradeStudyInstances Block to TradeStudy «block» «Analysis» as shown in the figure below.
Inheriting the Analysis Block from the TradeStudy «block» «Analysis».
Creating an Internal Block diagram for alternatives kind = Instance Table

1. Create an Internal Block diagram (IBD) of the TradeAnalysis Block. You must select Parts which
have been set as «objectiveFunction» and «alternatives» to display. You must also display
^score (inherited property) in the diagram.
2. Bind ^score with a Binding Connector to the LHS parameter of «objectiveFunction», e.g., ^score
– value. You must also bind a value property of the main simulation context with a Binding
Connector to the RHS parameter of «objectiveFunction», e.g., stoppingDistance – distance.
3. Bind each «alternatives» with a Binding Connector to each Part property.
4. For each «alternatives», source depends on kind through the Tags settings. If kind =
TABLE, source must be an instance table which must be the same Classifier as the alternative
property, as shown in the two figures below. However, sorting of rows in the table is not
necessary.

TABLE, kind of «alternatives», must be the same Classifier as the alternative
property.
Binding of the TradeAnalysis Block in the Internal Block diagram (kind = TABLE).
Creating an Internal Block diagram for alternatives kind = Subtypes

1. Refer to Step 1-3 about creating an Internal Block diagram for alternatives kind = Instance
Table(see page 668).

2. For each «alternatives», source depends on kind through the Tags settings. If kind =
SUBTYPES, source must be a parent Block of subtypes which must be the same type as the
alternative property, as shown in the two figures below. Also, the parent Block will not be
evaluated as well as any Blocks which have Is Abstract = true.
SUBTYPES, kind of «alternatives», must be the same type as the alternative

property.

Binding of the TradeAnalysis Block in the Internal Block diagram (kind =
SUBTYPES).
Creating an Internal Block diagram for alternatives kind = Excel

2. For each «alternatives», source depends on kind through the Tags settings. If kind = EXCEL,
source must be either an Instance table linked to an Excel file
(«DiagramTableMapToDataSource» applied) or using an «ImportMap»132. Table columns or
element properties must be correctly mapped to Excel/CSV columns as shown in the two figures
below (see also Sync with Excel or CSV files133). However, you do not need to use the Read from
File command from the Publish Excel toolbar to load data into the table.
132 https://docs.nomagic.com/display/MD2021xR2/Saving+an+Import+Map
133 https://docs.nomagic.com/display/MD2021xR2/Sync+with+Excel+or+CSV+files

EXCEL, kind of «alternatives» with an Instance table linked to Excel file
(«DiagramTableMapToDataSource» applied) settings.
EXCEL, kind of «alternatives» with Import Map settings.
Binding of the TradeAnalysis Block in the Internal Block diagram (kind = EXCEL,
source = Import Map).
Creating an Internal Block diagram for alternatives kind = Parameter Sweep

The parameter sweep is another way to specify alternatives. Simulation will generate alternatives based
on the specified properties: min, max, step, number of points, and values of «designVariable» as shown
in the image below.

2. Apply value properties in the scope of the TradeStudy analysis with the «BoundReference» and
«designVariable» stereotypes.
3. Create alternatives through «designVariable» of Tags using any of the four methods:
a. By step: min, max, step, e.g., min=1; max=5; step=1 > values: 1; 2; 3; 4; 5;
b. By number of points: min, max, numberOfPoints, e.g., min=1; max=5; numberOfPoints=3 >
calculated step: (5-1)/(3-1)= 2 > values: 1; 3; 5;
c. By number of points and step: min, max, numberOfPoints, step, e.g., min=1;
numberOfPoints=5; step=1 > values: 1; 2; 3; 4; 5; or max=1; numberOfPoints=2; step=-1 >
values: 1; 0;
d. By the specified value list: a set of possible values will be taken.
 Note
• If the values tag is specified together with step, numberOfPoints, min, or max, only
the values tag will take precedence and be used in parameter sweep.
A warning will be printed on the Console pane when one or more of the following
occurs:
• The min value is not specified that the default value (zero) will be used instead.
• The max value is not specified in the following combinations: [min, max, step], [min,
max, numberOfPoints], or step < 0.
• There are invalid values excluded from the Trade Study analysis.

Bindings of the Trade Analysis Block in the Internal Block diagram with
parameter sweep using all four different methods.
Creating a Simulation Configuration diagram and configuring other settings

Create a Simulation Configuration diagram, add a SimulationConfig(see page 49) to the newly created
diagram, and set the following tags:
• executionTarget: set to the TradeAnalysis Block, e.g., BrakeTradeStudy in the sample.

executionTarget can be an instance of the TradeAnalysis Block so that the instance can be
reconfigured.
• resultLocation: a package/instance table must be specified so an instance with related
information will be saved after running the simulation. The information includes N, OutOfSpec,
score, winner, and other elements.
 Note
• If you do not create a SimulationConfig and run the TradeAnalysis Block directly,
TradeStudy will not be triggered, but the TradeAnalysis Block will be run as
normal .
• If the executionTarget of a SimulationConfig is the TradeAnalysis Block,
TradeStudy execution will override other executions, so Monte Carlo simulation
will not be triggered even if numberOfRuns is more than 1.
• silent: set the silent tag accordingly to see the animation.

• rememberFailureStatus: use rememberFailureStatus when evaluating those weighted
alternatives. Any alternatives violating any of the attached constraints/Requirements will not be
considered as the winner, but they will be used in the calculation of OutOfSpec.
• Tags neglected: to neglect animationSpeed, constraintFailureAsBreakpoint, UI, and
autoStart.

SimulationConfig created for other settings, e.g., executionTarget and
resultLocation.
Running the SimulationConfig and reviewing results

1. Run the SimulationConfig created in the previous section.
2. When running the SimulationConfig, the information of TradeStudy will be printed in the
Console pane. The Simulation pane will be disabled, but all warning/errors will be printed.
3. There is a progress bar shown with the description of Executing alternative [n] of [total
iterations] (Time elapsed: [time]), and the Cancel button that allows canceling Trade Study as
4. Simulation automatically iterates all variants and instantiates all possible configurations in
memory. For example, Brake which contains the combinations of Pad (26 instances), Caliper (20
instances), and Rotor (4 instances) will have 26 x 20 x 4 = 2,080 configurations.
5. The winner value on each iteration will be compared directly with the score value property.
 Note
• The Starting Math Engine progress bar will be shown in this sample because
MATLAB is used as the external evaluator. See also Integration with MATLAB(see
page 451).
• Any alternatives violating any of the attached constraints/Requirements will not be
considered as the winner. They will be used in the calculation of OutOfSpec.
• The rememberFailureStatus of a SimulationConfig will be used when evaluating
those alternatives.
• When more than one alternative has the same winning score of a Trade Study, a
warning message is printed.
• In some cases, you can click Unlock in the Simulation pane to see execution
details during the execution.

A progress bar shown with description and the Cancel button during the
simulation.
6. When the simulation is either completed or canceled, winning information will be printed on the
Console pane in the following three lines as shown in the figure below.
• The first line shows the number of iterations (completed/canceled) of all alternatives for
executionTarget with elapsed time.
• The second line displays the winning configuration from the winner string.
• The third line is the winningscore from the ^score.
 Note
The winner string is printed with the formats as follows:
AlternativeProperty.Name1 : StringKind [, AlternativeProperty.Name2 : StringKind,
AlternativeProperty.Name3 : StringKind, …]
where StringKind will apply the following rules, depending on kind of alternative:
• kind=TABLE: then StringKind=InstanceName, e.g., P : Saphire 66, C : Alphine
K7, R : Rotus 30.
• kind=SUBTYPES: then StringKind=subtypesName, e.g., power : Diesel,
support : Wheels, stopping : Brakes.
• kind=EXCEL: then StringKind=#Row, e.g., R : #5, P : #21, C : #21, where Row is
the number of Excel rows.
• kind=Parameter Sweep: then StringKind=GeneratedValue, e.g., brakeMU :
0.66, centerLength : 0.12, outerDiameter : 0.29, thickness : 0.04, width :
0.038.
The result instance will be saved at the location as specified in resultLocation of

SimulationConfig. You can create an instance table, set a Classifier to the TradeAnalysis Block, and
set Scope to the package of the results.

The TradeAnalysis result (in the last 3 lines) is printed on the Console pane,
and the result instance is saved into a package and presented in the
instance table.
Integrating widgets for simulation

After you find any interesting widgets, please follow the steps below to integrate them for simulation. A
free widget, named jQuery Knob, will be used in this demonstration. This widget can be found and
downloaded via this link134.
134 https://github.com/aterrien/jQuery-Knob

The jQuery Knob widget.
To integrate widgets for simulation
1. See what information is needed to create the widget, e.g., the jQuery Knob widget needs an input
element, scripts, and jQuery Knob library, as displayed below.
Code example from https://github.com/aterrien/jQuery-Knob
<input type="text" value="75" class="dial">
<script>
$(function() {
$(".dial").knob();
});
</script>
2. Create a widget.HTML file with the content below.
widget.HTML
<!doctype html>
<html>
<head>
<title>@title@</title>
</head>

<body class="widget" paths="@paths@">
</body>
</html>
 Information
• class="widget" informs the simulation web server that this file is widget.
• paths="@paths@" is used for generating HTML code from the widget, and the
simulation web server will use the value of the paths attribute to register for value
change.
 Note
@title@ can be optionally replaced with any title. It is a predefined variable in simulation
which will be replaced by the property name whose type is of this widget.
3. Create a new js folder. Copy the jQuery Knob library to the created js folder.
 Note
Different widgets require different numbers of jQuery library files, including CSS files.
Please ensure that you copy and include all those files.
4. Import required jQuery libraries and CSS files, if any, to the HTML head element, and add the
widget code to the body element, as shown below.
widget.HTML
<!doctype html>
<html>
<head>
<script type="text/javascript" src="js/jquery.knob.js"></script>

</head>

<input type="text" class="dial">
<script>
$(function(){
$(".dial").knob();
});
</script>
</body>
</html>
5. Because this widget requires the jQuery library, it needs to also import the jQuery library before
the widget import statement. Alternatively, the @scripts@ predefined variable can be used so
that simulation will generate jQuery files and replace this variable with jQuery import

statements. In addition, the @simulation_js@ predefined variable must be added as the last
import statement in the head element because simulation will replace this variable with the core
simulation javascript import statement. See the code below for the detail in this step.
widget.HTML
<!doctype html>
<html>
<head>
@scripts@
@simulation_js@
</head>

<input type="text" class="dial">
<script>
$(function(){
$(".dial").knob();
});
</script>
</body>
</html>
6. Add the following attributes to the widget element, where the value of the paths attribute is the
name of a property/Port that will be used as input/output in simulation.
runtime="true" pathType="widget" paths="value"
Apply the added attributes to the widget element as shown below.
widget.HTML
<!doctype html>
<html>
<head>
@scripts@
@simulation_js@
</head>

<input type="text" class="dial" runtime="true" pathType="widget"
paths="value">
<script>

$(function(){
$(".dial").knob();
});
</script>
</body>
</html>
7. If the widget can be used as an output to display a value from simulation, you can override the
customSetHTMLValue method and set the widget value in the overridden method, e.g., the
jQuery Knob widget sets the value by using the following code.
<script>
$('.dial')
.val(27)
.trigger('change');
</script>
It can then be integrated for simulation as follows.
widget.HTML
<!doctype html>
<html>
<head>
@scripts@
@simulation_js@
</head>

paths="value">
<script>
$(function(){
$(".dial").knob();
});
/**
* This method will be called when a value of the widget element is
changed.
* @param item is an element with matching attribute paths in the
body and the element itself.
* @param data represents a new value.
* @param formattedValue indicates a new value formatted by the
simulation web server.
*/

function customSetHTMLValue(item, data, formattedValue) {
if ($(item).is($(".dial"))) {
$(item).val(data).trigger('change');
}
}
</script>
</body>
</html>
 Note
The line of code shown below is needed to prevent the customSetHTMLValue method
from being called when there is a value change from any other widgets with the same
property paths. The following line of code checks if the updating widget (the item
parameter), is the same element as this Knob widget.
8. If the widget can be used as an input to change simulation value, you can call the
doSetWidgetValue method when the widget changes the value, e.g., the jQuery Knob widget has
a hook to tell when the value is changed, as demonstrated below.
<input type="text" value="75" class="dial">
<script>
$(".dial").knob({
'change' : function (v) { console.log(v); }
});
</script>
This is integrated for simulation as following.
widget.HTML
<!doctype html>
<html>
<head>
@scripts@
@simulation_js@
</head>

paths="value">

<script>
$(function() {
$(".dial").knob({
'release' : function(value) {
//call the doSetWidgetValue method to set a simulation
value.
doSetWidgetValue($(".dial"), value);
}
});
});
/**
changed.
*/

}
}
</script>
</body>
</html>
9. If the widget has options, these options can be modified to customize in the widget Class in
MagicDraw, e.g., the jQuery Knob widget has the min and max options in the code below.
$(".dial").knob({
'min':-50,
'max':50
});
When integrated for simulation, the value for each option can be defined by using the
$widget_property$ format, where widget_property is the name of a property owned by the
widget Class in MagicDraw as shown below.
widget.HTML
<!doctype html>
<html>
<head>
@scripts@

@simulation_js@
</head>

paths="value">
<script>
$(function(){
$(".dial").knob({
'min' : $min$,
'max' : $max$,
'release' : function(value) {
//call the doSetWidgetValue method to set simulation
value.
doSetWidgetValue($(".dial"), value);
}
});
});
/**
changed.
*/

}
}
</script>
</body>
</html>

10. Archive the widget.HTML file and the js folder into a zip file.
 Note
The widget.HTML file and all related resources must be archived into a zip file and the
widget.HTML file must be the root directory of the zip file.

11. Open MagicDraw and create a new Simulation project.
 Information
You can also create other kinds of project, but you need to use the Simulation profile in
your created project before proceeding to the next steps.
12. Create a Class element in the Containment browser.

13. Apply the created Class with the «Widget» stereotype.
14. Drag the zipped widget file from File Explorer to the widget Class and select Create Attached
File.
15. Create a Port element with any corresponding widget type. The name of the Port must match
the value of the paths attribute of the widget element in the widget.HTML file.

16. Create a property for each option with any corresponding type. Also, the default value must be
set for each property to prevent javascript syntax errors when running simulation on the web
server.
17. Capture the screen of jQuery Knob on the jQuery Knob Web site and save it as an image to be
used as the icon of the widget Class.
18. Open the Specification dialog of the widget Class. Find and select the value field of the Image
property to set an icon for the widget Class.

19. Click the … button to open the browse dialog and select the captured image file.
20. Create the SysML Block diagram and a property with Integer as type, and specify 10 as the
default value, as illustrated below.

21. Create the SysML Internal Block diagram under the System Block.
22. Drag the Knob widget in the Containment browser to the IBD to create a widget symbol.
23. Specify a name for the widget property and create a binding Connector between the value Port
of the widget and the value property.

24. Open the Simulation Config diagram. Drag the System Block in the Containment browser to the
Simulation Config element to set as the execution target.
25. Right-click the Simulation Config element. Set the Auto Start option as true and the Silent
option as false. Also make sure that the startWebServer option is set true.

26. Run the Simulation Config element and open the System IBD to see the result of widget
integration.
Predefined variables
The table below explains how predefined variables will be replaced when widget files are generated.

Variable name Resolved text after generating widgets
@title@ A name of the Part property representing the widget.
@scripts@ Predefined javascript import statements:
<script type="text/javascript" src="js/jquery-1.12.4.min.js"></

script>
<script type="text/javascript" src="js/jquery-ui-1.12.0.min.js"></

script>
@simulation_js@ Core simulation javascript import statement:
<script type="text/javascript" src="js/Simulation.js"></script>
@paths@ Auto-generated paths to the widget.
$widget_property$ widget_property as the name of a property, owned by the widget

Class in MagicDraw. This variable will be replaced by the default value
of the property or the slot value of the widget instance.
Additional resources and support
On this page
• Web page(see page 693)

• Online Information(see page 694)
• E-mail(see page 694)
• Bug reports(see page 694)
• No Magic customer support system(see page 695)
• Frequently asked questions(see page 695)
Web page
To download the demo of this version and to get contact information or purchase details, please visit
http://www.nomagic.com/.

Online Information
Please visit No Magic training and information portal at http://training.nomagic.com/135.
 Note
You must add our news server, news.nomagic.com, to your server list before you can access
this forum.
E-mail
• support@magicdraw.com136 - for questions about product installation, features, questions about
how-tos, and suggestions.
• sales@magicdraw.com137 - for questions regarding academic and site discounts, delivery,
customer profile, invoices, and related issues.
• contact@magicdraw.com138 - for all other contact.
We are awaiting your comments and suggestions. More than half of the features of the current version
has been added because our demo version users have requested them. Do not miss the chance to see
your desired features in the future versions!
Bug reports
Your bug reports are welcome at support@magicdraw.com139. These reports allow us to fix bugs as
soon as possible and release the known-bug-free maintenance releases. While sending the bug report,
please include the following (if applicable):
• MagicDraw version number and the name of the edition (Standard, Enterprise, Professional Java,
Professional C++, Professional C#, Demo, or Academic).
• Source where you got the version from (demo CD or our homepage download).
• Your OS name and version.
• JDK version and JVM vendor.
• Cameo Simulation Toolkit plugin version (you can go to Help > About MagicDraw from the main
menu to open the About dialog and click the Licensing tab to see this information).
For information about your JVM and OS, see the Environment tab in the About dialog from the
MagicDraw Help main menu. If you have a file that the MagicDraw is not able to load, and it is not the
confidential one, please attach it as well. This will help us analyze the problem.
Bugs can be submitted directly from the MagicDraw application by going to Help on the main menu >
Report an Issue.
135 http://school.nomagic.com/
136 mailto:support@magicdraw.com
137 mailto:sales@magicdraw.com
138 mailto:contact@magicdraw.com
139 mailto:bugs@magicdraw.com

No Magic customer support system
Please visit https://support.nomagic.com for No Magic customer support system (JIRA).
Frequently asked questions

Please visit our website for FAQs at http://www.nomagic.com/support/faq.html.

Index
Constraint-violations 87
A Constraints 437
Accept-change-structural-feature-event-action 482 Constraints-on-parts 425
Action-languages 507 Context 207
Action-script-api 515 Context-initialization 227
Active-elements 180 Control-panel-for-web-ui 165
Active-image 75 Creating-objects-in-variables-tab 220
Active-objects 69 Creating-values-in-variables-tab 220
Active-state-images 186 Csv-export 141
Active-states-in-diagrams 186 Csv-file-data-in-time-series-chart 109
Activity-duration 317 Custom-html-widgets 171
Activity-execution 311 Customizing-animation 182
Activity-partition-execution 332
Activity-simulation 26, 286 D
Activity-simulation-engine 287 Deactivating-licenses 16
Activity-state-behaviors 264 Debug-buttons 199
Adapting-model-for-state-machine-simulation 259 Debugging 197
Adding-breakpoints 251 Deffering-events 277
Adjunct-property 482 Developer-guide 559
Alh-api 516 Diagram-of-executing-behavior 184
Animating-parametrics 430 Diagram-simulation 36
Animation 180 Disabling-updates-in-simulation-pane 254
Animation-customization 182 Displaying-parts-of-simulation-context 130
Animation-options 186 Displaying-parts-using-ui-configurations 134
Animation-speed 183 Dummy-models 334
Association-block 484 Dummy-tokens 342
Attached-file-support 145 Duration-analysis 326
Auto-save-plot-values 100 Duration-constraint 361
Automatic-start-of-active-objects 69 Dymola-integration 470
Dynamic-constraint 426
B
Basic-concepts 12 E
Behavior-simulation 25 Element-simulation 22
Behaviors-of-activity-states 264 Enumeration-literal-value 508
Binding-connector 484 Enumeration-value-representation 79
Binding-in-aggregate-structure 409 Error-messages-about-constraint-failures 206
Block 484 Evaluating-expressions 413
Bound-reference 485 Evaluating-strings 435
Breakpoints 250 Evaluation-with-causality 421
Built-in-clock 63 Event-deffering 277
Built-in-math-solver 434 Executed-trace-duration 329
Executing-activities 311
C Executing-state-machines 279
Call-action-simulation 331 Exporting-plot-data 97
Call-event 360 Exporting-plot-data-to-csv 98
Carrying-values-via-connectors 234 Exporting-plot-data-to-instance-model 100
Change-structural-feature-event 486 Exporting-runtime-objects 237
Changing-runtime-values 194 Exporting-runtime-values 237
Checking-runtime-values 235 Exporting-simulation-results-to-csv 141
Class-simulation 32 Exporting-timeline-chart 111
Classifier-behavior-property 486 Expression-evaluation 413
Combined-fragment 366 Expression-language 400
Communicating-with-parametric-evaluator 432 External-evaluators 449
Completion-events 274 External-libraries 512
Concepts 12 Extracting-constraints-from-text-based-requirements
Connecting-to-matlab-session 460 503
Connectors 234
Console-log-filter 205 F
Console-tab 201 Features 18
Constraint-block 488 Flow-port 489
Constraint-failures 206 Flow-property 488

Flowing-information-in-diagrams 186 Model-for-interaction-simulation 368
Fmi-co-simulation 478 Model-simulation 21
Frequently-asked-questions 555 Modeling-ui 46
Full-port 490 Monitoring-runtime-values 206
Functions 441
N
G Nested-connector-end 495
Generating-html-files 152 Nested-properties 144
Generating-html-table 156 Nested-ui-configuration-stereotype 129
Generating-web-project-homepage 149 Non-normative-extensions 504
Generic-table-simulation 40
Getting-started 17 O
Guards-on-transitions 262 Object-binding 408
Opening-executing-behavior-diagram 184
H Operators 438
Histogram 125
Html-files 152 P
Html-table 156 Parametric-animation 430
Html-widgets 171 Parametric-evaluator 399
Parametric-simulation-samples 475
I Plot-data 97
Image-switcher 75 Plot-data-to-csv-file 98
Image-switcher-in-web-ui 168 Plot-data-to-instance-model 100
Importing-external-libraries 512 Plot-results 103
Incomplete-model-execution 334 Plotting-on-web-ui 169
Initializing-objects 403 Plugin-installation 13
Initializing-references 49 Plugin-licensing 15
Initializing-values 403 Port 489
Installation 10 Primitive-value-binding 405
Installing-plugin 13 Probability 495
Instance-specification-simulation 38 Project-options 47
Instance-table-simulation 40 Project-template 19
Interaction-model-execution 381 Proxy-port 491
Interaction-simulation 30, 352
Interaction-simulation-elements 352 R
Interaction-simulation-model 368 Recording-runtime-value-verification-status 243
Internal-simulation-clock 64 Recording-simulation-as-sequence-diagram 387
Introduction 17 References-to-elements-using-html 509
Invocation-on-nested-port-action 494 Removing-breakpoints 252
Representing-enumeration-values 79
K Representing-object-states 76
Key-features 18 Requirement-refined-by-constraint-block 499
Requirement-satisfied-by-property 500
L Requirement-traceability 499
Last-visited-elements 180 Requirements 10
License-deactivation 16 Reusing-ui-mockup 139
Licensing 10 Runtime-object 207
Lifeline 353 Runtime-object-initialization 227
Log 59 Runtime-objects-from-classifiers 222
Log-file 204 Runtime-objects-from-instance-specifications 224
Log-filter-in-console 205 Runtime-value 207
Runtime-value-monitoring 206
M
Runtime-value-verification-status 243
Main-features 18
Runtime-values-in-diagrms 186
Many-to-one-binding-calculations 410
Maple-integration 464 S
Mapping-signal-properties-to-behavior-parameters Sample-projects 282
266 Saving-plot-results 103
Mathematica-integration 467 Scripting-languages 507
Matlab-integration 451 Selecting-nested-properties-for-configurations 144
Matlab-on-linux 458 Sending-singals 194
Matlab-on-mac 456 Showing-constraint-violations 87
Matlab-on-windows 453 Showing-csv-file-data 109
Matlab-session 460 Showing-parts-of-simulation-context 130
Message 357 Showing-requirements 87
Model-based-clock 66 Showing-time-series-chart-in-timeline-chart 111
Model-for-activity-simulation 295 Signal-property-mapping 266

Simulating-activities 26 T
Simulating-behaviors 25 Table-simulation 40
Simulating-classes 32 Test-case-traceability 502
Simulating-diagrams 36 Test-case-verdict 365
Simulating-elements 22 Time-axis-range 95
Simulating-instance-specifications 38 Time-constraint 363
Simulating-interactions 30 Time-series-chart 87, 218
Simulating-model 21 Time-series-chart-in-timeline-chart 111
Simulating-simulation-configuration 42 Timeline-chart 111
Simulating-state-machines 28 Transitions 274
Simulating-tables 40 Trigger-on-nested-port 496
Simulating-ui-modeling-diagram 70 Triggers-on-transitions 260
Simulation-animation 180 Turning-off-updates-in-simulation-pane 254
Simulation-clock 61
Simulation-configuration 46 U
Simulation-context 130, 207 Ui-configurations 134
Simulation-dashboard 185 Ui-mockup 139
Simulation-debugging 197 Ui-modeling 46
Simulation-information-in-console 203 Ui-modeling-diagram-simulation 70
Simulation-information-in-diagrams 185 Uninstalling-plugins 16
Simulation-log 59 Updating-plugins 16
Simulation-log-file 204 Updating-values-from-instance-specification 247
Simulation-modeling 557 Upgrading 16
Simulation-pane 200 Use-case-simulation 398
Simulation-project-options 47 User-guide 16
Simulation-sessions 197 User-interface 46
Simulation-time 61 Utility-functions 344
Simulationconfig-stereotype 49
Simulink-co-simulation 461 V
State-activation-semantics 273 Validating-model 254
State-duration-in-state-machines 281 Value-binding 405
State-invariant 363 Value-check 235
State-machine 256 Value-type 496
State-machine-simulation 28 Value-updates-with-parametric-evaluator 430
State-machine-simulation-samples 282 Values-in-expressions 436
State-representation 76 Variables-in-math-solver 436
Streaming-activity-simulation 347 Variables-tab 209
Streaming-parameters 347 Visited-element-duration 326
Subset-properties 44 Visited-elements 180
Supported-elements-on-state-machine-diagram 258 W
Supported-sysml-elements 480 Web-project-homepage 149
Sysml-model-simulation 476 Web-server-for-cameo-simulation-toolkit 147
System-requirements 10 Web-ui-control-panel 165
Widget-integration 171

Cameo Simulation Toolkit UserGuide

Uploaded by

Copyright:

Available Formats

Cameo Simulation Toolkit UserGuide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Cameo Simulation Toolkit UserGuide

Uploaded by

Copyright:

Available Formats

Cameo Simulation Toolkit 2021x

No Magic, Inc., a Dassault Systèmes company, 2021

Copyright © 1998 – 2021 No Magic, Incorporated, a Dassault Systèmes company.

Copyright © 1998 – 2021 No Magic, Incorporated, a Dassault Systèmes company. 3

Copyright © 1998 – 2021 No Magic, Incorporated, a Dassault Systèmes company. 4

Copyright © 1998 – 2021 No Magic, Incorporated, a Dassault Systèmes company. 5

Developer Guide 559

Copyright © 1998 – 2021 No Magic, Incorporated, a Dassault Systèmes company. 6

Copyright © 1998 – 2021 No Magic, Incorporated, a Dassault Systèmes company. 7

Additional resources and support 693

Copyright © 1998 – 2021 No Magic, Incorporated, a Dassault Systèmes company. 8

To learn how to install and use Cameo Simulation Toolkit, see:

• Installation and licensing(see page 10)

• Cameo Simulation Toolkit Documentation 2021x Refresh11

Copyright © 1998 – 2021 No Magic, Incorporated, a Dassault Systèmes company. 9

• System requirements(see page 10)

CPU Intel Core™ i5 or higher

The memory allocation for the modeling tool by project size:

Project Elements Count Allocated Memory 2

Earlier 2021x and later

1.5 million 1 million 6GB

2.5 million 2 million 7GB

5 million 3.5 million 11GB

Copyright © 1998 – 2021 No Magic, Incorporated, a Dassault Systèmes company. 10

• UPDM migration to UAF - 10GB, 10GB, 36GB

Project Elements Count Disk Space

Earlier 2021x and

1.5 million 1 million 6GB

2.5 million 2 million 10GB

5 million 3.5 million 30GB

 The amount of required disk space proportionally increases if working on multiple

Display Full HD (1920x1080) or higher

Copyright © 1998 – 2021 No Magic, Incorporated, a Dassault Systèmes company. 11

Java Virtual Java version support8

** 800x600, 1280x1024 display resolutions are compatible with a laptop or a projector.

FLEXnet License Server

• Borrowing(see page 13)

Copyright © 1998 – 2021 No Magic, Incorporated, a Dassault Systèmes company. 12

Using a floating license in the offline mode.

A license for the dedicated Host ID/Target ID received after purchase.

A program developed by CATIA / No Magic to implement the FlexNet license server.

Copyright © 1998 – 2021 No Magic, Incorporated, a Dassault Systèmes company. 13

To install a plugin bundle (.rdzip) via the Resource/Plugin Manager dialog

1. Start your modeling tool.

1. Start your modeling tool.

To install a plugin manually

1. Open Resource/Plugin Manager and click .

Copyright © 1998 – 2021 No Magic, Incorporated, a Dassault Systèmes company. 14

For more information on managing resources, please see Resource Manager10.

• Modeling tools and plugins licensing15

Copyright © 1998 – 2021 No Magic, Incorporated, a Dassault Systèmes company. 15

Unable to render include or excerpt-include. Could not retrieve page.

Uninstalling plugins and deactivating licenses

Unable to render include or excerpt-include. Could not retrieve page.

Unable to render include or excerpt-include. Could not retrieve page.

Copyright © 1998 – 2021 No Magic, Incorporated, a Dassault Systèmes company. 16

• Behavior(see page 25)

Introduction to Cameo Simulation Toolkit

The purpose of simulation is to understand the function or performance of a system without

Copyright © 1998 – 2021 No Magic, Incorporated, a Dassault Systèmes company. 17