Plots Python API

User's guide
Simcenter Amesim 2310
Unpublished work. © 2023 Siemens

This Documentation contains trade secrets or otherwise confidential information owned by Siemens Industry Software Inc. or
its affiliates (collectively, “Siemens”), or its licensors. Access to and use of this Documentation is strictly limited as set forth in
Customer’s applicable agreement(s) with Siemens. This Documentation may not be copied, distributed, or otherwise disclosed
by Customer without the express written permission of Siemens, and may not be used in any way not expressly authorized by
Siemens.

This Documentation is for information and instruction purposes. Siemens reserves the right to make changes in specifications
and other information contained in this Documentation without prior notice, and the reader should, in all cases, consult
Siemens to determine whether any changes have been made.
No representation or other affirmation of fact contained in this Documentation shall be deemed to be a warranty or give rise to
any liability of Siemens whatsoever.
If you have a signed license agreement with Siemens for the product with which this Documentation will be used, your use of
this Documentation is subject to the scope of license and the software protection and security provisions of that agreement.
If you do not have such a signed license agreement, your use is subject to the Siemens Universal Customer Agreement, which
may be viewed at [Link] as supplemented by the product specific terms
which may be viewed at [Link]
SIEMENS MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS DOCUMENTATION INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT OF
INTELLECTUAL PROPERTY. SIEMENS SHALL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL OR
PUNITIVE DAMAGES, LOST DATA OR PROFITS, EVEN IF SUCH DAMAGES WERE FORESEEABLE, ARISING OUT OF OR RELATED
TO THIS DOCUMENTATION OR THE INFORMATION CONTAINED IN IT, EVEN IF SIEMENS HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES.

TRADEMARKS: The trademarks, logos, and service marks (collectively, "Marks") used herein are the property of Siemens or other
parties. No one is permitted to use these Marks without the prior written consent of Siemens or the owner of the Marks,
as applicable. The use herein of third party Marks is not an attempt to indicate Siemens as a source of a product, but is
intended to indicate a product from, or associated with, a particular third party. A list of Siemens’ Marks may be viewed at:
[Link]/global/en/legal/[Link]. The registered trademark Linux® is used pursuant to a
sublicense from LMI, the exclusive licensee of Linus Torvalds, owner of the mark on a world-wide basis.

About Siemens Digital Industries Software

Siemens Digital Industries Software is a global leader in the growing field of product lifecycle management (PLM),
manufacturing operations management (MOM), and electronic design automation (EDA) software, hardware, and services.
Siemens works with more than 100,000 customers, leading the digitalization of their planning and manufacturing processes. At
Siemens Digital Industries Software, we blur the boundaries between industry domains by integrating the virtual and physical,
hardware and software, design and manufacturing worlds. With the rapid pace of innovation, digitalization is no longer
tomorrow’s idea. We take what the future promises tomorrow and make it real for our customers today. Where today meets
tomorrow. Our culture encourages creativity, welcomes fresh thinking and focuses on growth, so our people, our business, and
our customers can achieve their full potential.

Support Center: [Link]

Send Feedback on Documentation: [Link]/doc_feedback_form

2 Plots Python API, Simcenter Amesim 2310
© 2023 Siemens
 How to contact us
[Link]/plm/simcenter-amesim Web site

[Link] Technical support

See here for e-mail addresses for your local office: Sales, pricing and general
information
[Link]
about_us/contact/[Link]#lms

Simcenter Amesim™ software User’s guides

Plots Python API, Simcenter Amesim 2310 3

© 2023 Siemens
 Contents

Introduction 1-1

Getting started
Setting the environment ─────────────────────── 2-1
Plot a basic line graph ──────────────────────── 2-4

The Plot Python API environment in detail

Create a plot widget ───────────────────────── 3-1
Create a curve ──────────────────────────── 3-3
Customize a graph ────────────────────────── 3-5
Customize a curve ────────────────────────── 3-9
Update a curve ─────────────────────────── 3-12
Add annotations ────────────────────────── 3-13
Interaction with a plot ──────────────────────── 3-15
Add entry in a menu or a toolbar ─────────────────── 3-17

Simple examples
Plot a bar graph ─────────────────────────── 4-1
Plot a spider graph ────────────────────────── 4-6

Advanced examples
The Plot API demo ────────────────────────── 5-1
Create a plot in an App ──────────────────────── 5-4

Index Index-1

Plots Python API, Simcenter Amesim 2310 4

© 2023 Siemens
 1. Introduction
The Plots Python API provides access to the Plot analysis tool of Simcenter Amesim. It provides a
complete set of functions to create and modify graph displays using your data sets.

These functions are very useful when you want to generate a report from:

• Scripts that will plot the results of analysis performed by a series of automated tasks

• Apps that will display graphs directly in the Apps graphical interface

This manual explains how the API is structured. It describes the basic steps that make it possible to call
the Simcenter Amesim Plot from lines of code through the Python language.

You are advised to consult the Plots Python API References for the complete list of the available
functions with a short description for each. Through these functions you will be able to go further in
customizing graphs.

The following tables classify and illustrate the kinds of plots you can create with the Plots Python API.
They include lines, bars, density, maps, and pie graphs.

Two-Dimensional graph types

2D line Density Bar Bubble Colormap Multilines

basic plot Bubble size 2D Bars Bubble Basic

colormap colormap

xlog plot Colorscale Bubble size Colormap

with isoline

xlog plot Colormap

with isoline
and
annotations

Plots Python API, Simcenter Amesim 2310 1-1

© 2023 Siemens
 1. Introduction

2D line Density Bar Bubble Colormap Multilines

xylog plot Isoline

colorscale

Three-Dimensional graph types

3D line Mesh Surface Waterfall

basic plot 3D mesh plot Basic surface Basic waterfall

Surface with isolines

One-Dimensional discrete graph types

Parallel
1D line Bar Pie coordinates Spider

Horizontal lines Vertical bars Pie chart Horizontal lines Spider lines

Vertical lines Horizontal bars 3D Pie chart Vertical lines Spider areas

1-2 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 Parallel
1D line Bar Pie coordinates Spider

Vertical stacked
bars

Horizontal
stacked bars

Plots Python API, Simcenter Amesim 2310 1-3

© 2023 Siemens
 1. Introduction

1-4 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 2. Getting started
This section introduces the different contexts of the Plots Python API use and provides a simple example
to help you get started with the basics of the API.

First, check your AME environment variable. It must contain the absolute path to the root Simcenter
Amesim directory.

Secondly, check your PATH environment variable:

• under Windows: the %PATH% environment variable must contain at least %AME% and %AME%
\win32.

• under Linux: the $PATH environment variable must contain at least $AME and your
$LD_LIBRARY_PATH must contain at least $AME/lnx.

Note:
A complete Python 3.8.8 distribution including the Scientific Python toolbox is supplied with
Simcenter Amesim. It includes four libraries:

• Numpy 1.19.5

• Scipy 1.6

• Matplotlib 3.3.3

• PySide2 5.15.2

Note:
It is recommended to have some knowledge on the Python language. The official Python
documentation is available through the Simcenter Amesim platform manuals:

• Python Library Reference

• Python Tutorial

2.1 Setting the environment

The plotting facilities module is called amepyplot. To include the definitions of modules classes, use the
following directive:

import amepyplot

Plots Python API, Simcenter Amesim 2310 2-1

© 2023 Siemens
 2. Getting started

Note:
Several classes and functions contain references to PySide2, the Python binding for the Qt C++
framework.

Depending on the context of your script, the display of your graphs in a Simcenter Amesim plot
window can differ. Three cases occur when scripts are used to interact with Simcenter Amesim.

Standalone script

This kind of script is particularly designed for automating tasks such as setting or getting parameter
values, running temporal simulations or linear analysis, and post-processing result variables from
outside Simcenter Amesim. Simcenter Amesim does not need to be open to interact with it, this
is typically the case when using the Simulation scripting facility or the Simcenter Amesim API.

In that case you need to create a Qt Application that allows you to manage the plot widget.

Note:
The main event loop receives events from the window system and dispatches these to the
application widgets.

Below is a template of how the code needs to be structured to display your plot in an Simcenter
Amesim plot window.

import sys
import math
import amepyplot
from PySide2 import QtWidgets

# Check if there is already a Qt Application

app = [Link]()
if app is None:
app = [Link]([])

# Setup the curve

...
...

[Link]()

# Start the application

app.exec_()

2-2 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 Setting the environment

Python tools

In Simcenter Amesim the Python tools are located at system level or component level. These tools
call Python scripts to interact with an open model within Simcenter Amesim. They can be launched
from the script analysis tool, the script assistant component (SCRCALL01 submodel), and the editable
parameters group facility.

In this case the plot window is attached to the main Simcenter Amesim window.

Below is a template of how the code needs to be structured to display your plot in an Simcenter
Amesim plot window.

import sys
import math
import amepyplot
from PySide2 import QtWidgets
import apps

# Get the Simcenter Amesim main window

mainWindow = [Link]()

# Create a dedicated dialog for the plot

dialog = [Link](mainWindow)

# Create a layout to specify the behavior of the children widget

layout = [Link](dialog)

# Create the plot window as a child of the dialog

plot = [Link](dialog)

# Add the plot window to the layout of the dialog

[Link](plot)

# Setup the curve

...
...

[Link]()

Apps

In the App Designer there is a dedicated widget to integrate a plot within your Graphical User Interface.
When you insert this widget in your UI the associated code is automatically generated. You just need to
attach your graph to this widget through its name.

Below is a template of how the code needs to be structured to display your plot in an Simcenter
Amesim plot widget.

Plots Python API, Simcenter Amesim 2310 2-3

© 2023 Siemens
 2. Getting started

import math
import amepyplot

...
#>>>>>>> Extra initialization declarations here

# Setup the curve

graph = [Link]()
...
...

#>>>>>>> End of initialization

2.2 Plot a basic line graph

In this example we show how to use the Plots Python API functions in a standalone script to create a
curve of the variables resulting from an Simcenter Amesim simulation.

When using the Simulation scripting functions, you can run a simulation, then load the results and get
specific variables. This is typically done through the functions amerunsingle, ameloadt, and amegetvar.

The following piece of Python code illustrates the use of these functions:

# Post-processing the results

sysName = 'scrdemo'
Results, Varnames = ameloadt(sysName)
timeval, timelabel = amegetvar(Results, Varnames, 'time [s]')
name = amegetvarnamefromui(sysName, "theta@rotaryload2ports")[0]
rotangleval, rotanglelabel = amegetvar(Results, Varnames, name)

Here the time and the shaft angle are the two variables that are retrieved from the simulation results.
You are going to plot the 2D curve of the rotangleval as a function of timeval.

1. Create a new python file and save it as [Link].

This file is a new module where you can define different built-in graph display functions. In this
example you only define the 2D line graph.

The function is named plot2D and has as arguments the x values, y values, x label, and y label.

At this step the code is the following:

import amepyplot

2-4 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 Plot a basic line graph

def plot2D(x,y,xlabel,ylabel):

2. In the function plot2D you first create the plot widget PlotWidget(), set the plot window size using
the function resize(), and access the generated graph using firstGraph().

Note:
Here there is only one graph on the plot window, however you can define a layout that
contains several graphs on the same plot window.

At this step the code is the following:

import amepyplot

def plot2D(x,y,xlabel,ylabel):
plot = [Link]()
[Link](800, 550)
graph = [Link]()

3. Next, you need to create the x and y items of the curve (using the Item object) and create the 2D
curve that will be plotted (Curve2D).

Note:
The unit is already defined in the name of the variable, that's why the unit argument of the
object Item is empty.

At this step the code is the following:

import amepyplot

def plot2D(x, y, xlabel, ylabel):

plot = [Link]()
[Link](800, 550)
graph = [Link]()

x_item = [Link](x, xlabel, unit="")

y_item = [Link](y, ylabel, unit="")

curve = amepyplot.Curve2D(x_item, y_item)

4. The final step to fully define the function plot2D is to attach the curve to the graph and display the
widget.

Plots Python API, Simcenter Amesim 2310 2-5

© 2023 Siemens
 2. Getting started

At this step the code is the following:

import amepyplot

def plot2D(x, y, xlabel, ylabel):

plot = [Link]()
[Link](800, 550)
graph = [Link]()

x_item = [Link](x, xlabel, unit="")

y_item = [Link](y, ylabel, unit="")

curve = amepyplot.Curve2D(x_item, y_item)

[Link](curve)
[Link]()

return plot

5. Since the function to plot a 2D line graph is completed you just need to call it from your main
script. Remember that you need to import the new module ameplot.

...
import ameplot
from PySide2 import QtWidgets

...
...

# Post-processing the results

sysName = 'scrdemo'
Results, Varnames = ameloadt(sysName)
timeval, timelabel = amegetvar(Results, Varnames, 'time [s]')
name = amegetvarnamefromui(sysName, "theta@rotaryload2ports")[0]
rotangleval, rotanglelabel = amegetvar(Results, Varnames, name)

app = [Link]()
if app is None:
app = [Link]([])

plot = ameplot.plot2D(timeval[0], rotangleval[0], timelabel[0],

rotanglelabel[0])
app.exec_()

Using the Plots Python API you are able to display the results that are calculated from a standalone
scripts. You can create the following curve for instance:

2-6 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 Plot a basic line graph

Figure 2-1. Simcenter Amesim plot window

Note:
The function plot2D returns the plotWidget; you then have access to the graph for further
customization.

Plots Python API, Simcenter Amesim 2310 2-7

© 2023 Siemens
 2. Getting started

2-8 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 3. The Plot Python API environment in
detail
This section explains in detail how to perform the most frequently needed actions.

Each action contains a "step-by-step" workflow with examples of code.

3.1 Create a plot widget

The plot widget is the main object of the API.

This is the first object you need to create in any script to be able to use the API.

Figure 3-1. Empty plot widget

How to create

Here is a basic example of the creation of the object:

widget = [Link]()

Note:
The full documentation of the plot widget object can be found in the Plots Python API Reference

Plots Python API, Simcenter Amesim 2310 3-1

© 2023 Siemens
 3. The Plot Python API environment in detail

It can be displayed as a top level window or placed inside other widgets. To put it inside another widget
(we will call it A), you need to specify that A is the parent of the plot widget. To do this, you can indicate
the parent at the creation of the widget like in this example:

# Creation of a dialog
A = [Link]()

# Creation of the plot widget as a child of A

widget = [Link](A)

When the plot widget is a child of another widget, you need to use a layout to specify the behavior of
the plot widget inside its parent. For example, using a vertical box layout like in the example below, you
specify that all the children of the dialog A will be placed one above the other, and every widget will use
all the space available horizontally:

# Creation of the vertical layout on the dialog A

layout = [Link](A)

# Add the plot widget to the layout

[Link](widget)

Once you have performed these steps, you can display the top level window (whether it is a parent
dialog or the plot widget) using the method show. Note that you can also specify the required size:

# Set the wanted size

[Link](480, 350)

# Show the main dialog

[Link]()

The dialog will be shown when the QApplication will be executed with the line:

# Start the application

app.exec_()

The plot widget is now displayed like in the figure above.

Note:
Inside an App, you can create the plot widget using the App designer (see the advanced example
Create a plot in an App).

3-2 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 Create a curve

The abilities of the plot widget

The plot widget will allow you to access to:

• The object MenusAndToolBars that allow access to menus and toolbars.

• The status bar

• The graphs

The plot widget will allow you to:

• Create graph(s). For example, to add a graph in a second row, proceed as follows:

# Add a new row of graph(s)

[Link]()

# You can access to the new graph

graph2 = [Link](1, 0)

• Create a picture of the widget (method toPixmap). Here is an example of how to save this image on
your computer:

# Export the content of the plot widget to a PNG file

[Link]().save(r'C:\Data\[Link]')

• Update all the graphs (can be useful after the modification of data)

• Manage interactions allowed on the graph. By default, the plot widget doesn't allow any
modification. If you want to allow some modification, use the method setDefaultInteractions like
in this example:

# Allow to customize curve style (color, line style, thickness...)

[Link]([Link])

3.2 Create a curve

Once you have a plot widget, you need to create a curve to be displayed.

This section shows you how to do this.

Plots Python API, Simcenter Amesim 2310 3-3

© 2023 Siemens
 3. The Plot Python API environment in detail

Figure 3-2. Simple 2D curve

Storing the data: the "Item" object

A simple 2D curve is composed of 2 vectors of values: one for the x values, and the other for the y
values. The two vectors must have the same size. Use the Item object to store the x and y values.

Here is an example of the creation of two simple items:

# Creation of the x and y data

dataX = [0, 1, 2, 3, 4, 5]
dataY = [3, 2, 4, 7, 8, 10]

# Creation of the two items

itemX = [Link](dataX, title="Time", unit="s")
itemY = [Link](dataY, title="Output force", unit="N")

Note:
You can store the unit and the title of the data in the item. This information is displayed in the
graph (the title of the y item is used as the default title for a 2D curve).

If you retrieve the data from the scripting API, you can use this piece of code to create the items:

3-4 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 Customize a graph

[R, S] = [Link](systemName, variableList)

itemX = [Link](R[0], S[0])
itemY = [Link](R[1], S[1])

Note:
The full documentation of the Item object can be found in the Plots Python API Reference.

Create a curve

Once the Item objects are created, you can create the curve. Note that you are able to choose between
several types of curve depending on the data you want to visualize:

• Curve1DDiscrete can be used when the x data are not continuous but discrete (like a list of runs or a
list of criteria).

• Curve2D is the classic 2D curve. The x and y data are assumed to be continuous.

• Several types of 3D curves like CurveM1D, CurveMatrix or CurveXYZ. These kinds of curve can be
displayed in a 2D graph or a 3D graph.

Here is an example of the creation of a 2D curve:

# Create a 2D curve
curve = amepyplot.Curve2D(itemX, itemY)

Once the curve is created, you need to add it to a graph. You can access to the graph using the methods
available on the plot widget. Here is an example that adds the curve to the first graph of the plot widget:

# Get the first graph of the plot widget

graph = [Link]()

# Add curve to the graph

[Link](curve)

3.3 Customize a graph

You can fully customize a graph to your requirements.

This customization can be carried out on the graph type (2D, 3D, Pie chart...), on the displayed texts
(graph title, axis title, legend...), or on the axes (colors, unit text, tick marks...). This section shows how
to do this customization.

Plots Python API, Simcenter Amesim 2310 3-5

© 2023 Siemens
 3. The Plot Python API environment in detail

Graph type

The basic customization is to choose the type of graph you want to use. In the Graph documentation,
you can find a list of functions (called Graph type functions) that allow you to modify the graph type.

Note:
The Graph type functions section also contains some functions dedicated to a specific graph type.
Check the documentation to know if a function can be used on your type of graph.

When a graph is created, the default type is 2D. You can modify the type using the convertTo...functions
on the Graph object.

Here is an example to switch to a 3D graph type:

# Convert to 3D graph type

graph.convertTo3D()

Note:
You can change the graph type before or after adding the curves. Neverthless, the graph type
needs to support the curves type.

Figure 3-3. The same curve in 2D or 3D graph

Graph text management

You can display some predefined texts and indicators on the graph. The visibility of these objects is
mainly managed by the graph and can be modified using the function configureTitles.

3-6 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 Customize a graph

Figure 3-4. Predefined texts on the graph

Note:
The axis unit visibility is managed by the Axis object.

The Legend object can use several positions (using predefined anchors) that you can manage using the
same function.

Axis customization

You can customize the axes of a graph. To do this, first, access the Axis object through the graph, for
example:

axis = [Link]()

Plots Python API, Simcenter Amesim 2310 3-7

© 2023 Siemens
 3. The Plot Python API environment in detail

Figure 3-5. The properties of the Axis object

Then you are able to customize almost all the properties of the axis:

• Visibility

• Unit visibility

• Color, line style, thickness, font

• Graph grid (the grid drawn on the graph area, according to axis ticks)

• Range

• Tick-marks

• Format (log scale, power...)

• ...

Note:
See the documentation of the Axis object for further information. You can also consult the Plot
API App that contains examples of axis customization (see the associated documentation).

3-8 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 Customize a curve

3.4 Customize a curve

Once you have a curve on a graph, you can customize it to be exactly as you want. This section describes
the different ways to achieve this.

Figure 3-6. Matrix curve customization

Display object: how to draw the curve

Each curve has a Display object associated with it. This object specifies how the curve is drawn.

The first step is to select the type of display that you want to use. Each type of curve supports some
specific displays. To know the displays that can be used for your curve, consult the documentation

Plots Python API, Simcenter Amesim 2310 3-9

© 2023 Siemens
 3. The Plot Python API environment in detail

of the corresponding curve object. For example, the Curve2D supports the Display2DLine and the
DisplayDensity (see Curve2D).

At the creation of the curve, you can specify the display you want to use. If you do not specifiy, a default
display is used. For example, the Curve2D uses a Display2DLine by default:

# Create a 2D curve with default display: Display2DLine

curve = amepyplot.Curve2D(itemX, itemY)

# Create a 2D curve with given display

curve = amepyplot.Curve2D(itemX, itemY, amepyplot.Display2DLine())

Note:
The two curve creations in the above code example are equivalent.

To set a specific display on a curve, you can:

• Define the display at the creation.

# Create a 2D curve with given display

curve = amepyplot.Curve2D(itemX, itemY, [Link]())

• Change the display after the curve creation.

# Change curve display

[Link]([Link]())

Note:
You can consult the documentation of the object CurveDisplay to see examples of rendering for all
the available displays.

To know what kind of display is used for a specific curve, you can do the following:

print("display type:", type([Link]()))

The result for the previous curve with density display is:

display type: <class '[Link]'>

3-10 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 Customize a curve

Display customization

Once you have choosen a display type, you will be able to customize it to get the exact rendering you
want.

Here is an example where we want to draw a 2D curve using a blue line with a thickness of 2 pixels and
a dashed line style. Furthermore, we want to display a red cross symbol on each point:

# Creation of the display: we can set many parameters directly at the creation
display = amepyplot.Display2DLine([Link], [Link], 2)

# We can also set parameters afterwards

[Link]([Link], [Link], size=2)

# Now, don't forget to set the display to the curve

[Link](display)

Figure 3-7. Customized Display2DLine

Here is another example of a CurveM1D. We want to display it in a 3D graph with light, using a cold
colorscale with light blue isolines (without iso-values):

# Convert the graph if it is not in 3D

if not graph.is3DGraph():
graph.convertTo3D()

# Activate the light on the 3D graph

graph.configure3D(useLight=True)

Plots Python API, Simcenter Amesim 2310 3-11

© 2023 Siemens
 3. The Plot Python API environment in detail

# Surface display creation

display = [Link]([Link], showIsolines=True)

# Set isolines color and do not draw iso-values

[Link](color=[Link](145, 198, 212),
showText=False)

# Set the display on the curve

[Link](display)

Figure 3-8. Customized DisplaySurface

Note:
You can find many examples of display customization in the Plot API App. You can consult the
associated documentation

3.5 Update a curve

In some cases, an existing curve needs to be updated. This means the data values will be modified. This
section explains how to do that.

Access to the Item(s)

The data values are stored in the Item objects. To modify these values, you first need to access the
corresponding items. Here is an example on a 2D curve:

xItem = [Link]()
yItem = [Link]()

3-12 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 Add annotations

Set new values

The new values can come from a new simulation, a new computation or something else. Note that the
size of the new values must be coherent. That means for example that to be used in a 2D curve, the x
values and the y values must have the same size.

Here is an example where the x and y values of a 2D curve are updated:

[Link](xNewValues)
[Link](yNewValues)

Update the graph

Once the values have been updated, you need the graph to be redrawn. This can be done for a single
graph like this:

[Link]()

Or you can do it for all the graphs of a PlotWidget like this:

[Link]()

3.6 Add annotations

The plot python API allows you to add some annotation objects to graphs to add information. This
section explains how to do that.

Plots Python API, Simcenter Amesim 2310 3-13

© 2023 Siemens
 3. The Plot Python API environment in detail

Figure 3-9. Annotated graph

GraphOject : the base class

The base class for all the annotation objects is GraphObject. You can consult the reference
documentation that presents a hierarchy diagram of the available objects that inherit from this class.

The important information on these objects are:

• Linked to a graph: a GraphObject is attached to a specific graph. That is why all these objects need a
parent graph to be created.

# Creation of the blue area

zone = [Link](graph)

• Set a position: you can set the position in the graph coordinates using the function setModelPosition.
If an object is placed like this, it will move according to a user zoom / pan / rotate.

# Fix the y maximum position for the zone

[Link](yMax = 20)

• Manipulation: among all the GraphObject classes, there are two main categories: the manipulable
one (that uses the base class GraphManipulator) and the other one. The manipulable objects can be
used for annotation and their manipulation can be prevented using the function avoidManipulation.

# The blue vertical line is not movable

[Link]()

3-14 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 Interaction with a plot

• Associate information: you can add specific data on these objects using the method setUserData.

# Add information to the blue zone

[Link]("The blue security zone")

• Retrieve object: you can get an object from its parent graph using the previously associated data. To
do so, use the function findObject on the graph.

# Get the zone object using the parent graph

zone = [Link]("The blue security zone")

Here is an example of the creation of the "problem" text in the figure above:

# Creation of the text

text = [Link](graph, True)

# Set the text content

[Link]("Problem")

# Set the position of the text

[Link](dataX[problemIndex], dataY[problemIndex])

# Set the offset with the position

[Link](-25, -25)

# The the anchor position of the arrow

[Link]([Link])

# Customize text color

[Link]([Link])

# Customize arrow
[Link]([Link], [Link])
[Link](5)

Note:
The GraphText object can use graph anchors to have a "static" position in the drawing area.

3.7 Interaction with a plot

To allow custom interactions with the created graphs, the API provides some specific objects. This
section presents how to use them.

Plots Python API, Simcenter Amesim 2310 3-15

© 2023 Siemens
 3. The Plot Python API environment in detail

Figure 3-10. Manipulator in AMECamDesigner

GraphManipulator : the base class

The base class for all the manipulable objects is GraphManipulator. You can consult the reference
documentation that presents a hierarchy diagram of the available objects that inherit from this class.
You can also consult the section dedicated to annotations that presents the basic information about
these classes.

Here is the main information about these objects:

• Manipulation: you can specify the permitted manipulations using the function setAllowedMotions. It
will allow you, for example, to accept only the horizontal motion of a GraphPoint.

# Restricts the movement of the manipulator horizontally

[Link]([Link])

• Callbacks: the manipulators provide callbacks on user interactions. You can connect any of these
callbacks to associate your specific behavior. Here is an example where we want to change the curve
color to blue when the mainpulator is pressed:

# Creation of the point manipulator

manip = [Link](graph)

# Set user data to be able to retrieve the manipulator from the graph
[Link]("color manipulator")

3-16 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 Add entry in a menu or a toolbar

# Set the position of the manipulator

[Link](3, 50)

# Create the working function

def onPressed():
# Get the first curve of the graph
curve = [Link](0)

# Change the color of the curve to blue

[Link]().configure([Link])

# Update the graph

[Link]()

# Connect the signal "beginManipulation" to the working function

[Link](onPressed)

Note:
A manipulator has no default behavior. It means that you need to provide and connect a
working function that does the required behavior on the manipulation.

• Contextual menu: you can add contextual actions to a manipulator using the method addAction.

Note:
You can find an example of curve manipulation in the Plot API App. You can consult the reference
documentation

3.8 Add entry in a menu or a toolbar

If you want to provide a specific feature inside the plot widget, you can add an entry in a menu or a
toolbar. This section shows how to do that.

Plots Python API, Simcenter Amesim 2310 3-17

© 2023 Siemens
 3. The Plot Python API environment in detail

Figure 3-11. Custom action in menu and toolbar

The MenusAndToolBars object

All the interactions with menus and toolbars are done through the MenusAndToolBars object. You can
get it from the plot widget like this:

# Access to the MenusAndToolbars object

entries = [Link]()

You can display the menu bar like this:

# Show the menu bar

[Link](True)

3-18 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 Add entry in a menu or a toolbar

Menus

To access to a specific menu, you need to know its name. Use the function allMenusNames to obtain the
names of all available menus. Then you can add an action like this:

# Get the "view" menu

menu = [Link]("view")

# Add a separator
[Link]()

# Add the custom action

[Link](customAction)

Toolbars

To access to a specific toolbar, you need to know its name. Use the function allToolBarsNames to obtain
the names of all available toolbars. Then you can add an action like this:

# Get the "view" toolbar

toolbar = [Link]("view")

# Add a separator
[Link]()

# Add the custom action

[Link](customAction)

Plots Python API, Simcenter Amesim 2310 3-19

© 2023 Siemens
 3. The Plot Python API environment in detail

3-20 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 4. Simple examples
In these examples we show how to use the Plots Python API functions in a standalone script to create
special graphs such as bar chart or spider graph. These graphs use the values of variables resulting from
an Simcenter Amesim simulation.

When using the Simulation scripting functions, you can run a simulation, then load the results and get
specific variables. It is typically done through the functions amerunsingle, ameloadt, and amegetvar.

4.1 Plot a bar graph

When using the Simulation scripting functions, you can run a simulation, then load the results and get
specific variables. It is typically done through the functions amerunsingle, ameloadt, and amegetvar.

In this example it is assumed that 5 batch runs are simulated that correspond to different scenarios.

The following piece of Python code illustrates the use of these functions:

# Post-processing the results

Results1, Varnames1 = ameloadt('myModel', '1')
Results2, Varnames2 = ameloadt('myModel', '2')
Results3, Varnames3 = ameloadt('myModel', '3')
Results4, Varnames4 = ameloadt('myModel', '4')
Results5, Varnames5 = ameloadt('myModel', '5')
energy_1 = amegetvar(Results1, Varnames1, 'FX00_1 function of input x')
energy_2 = amegetvar(Results2, Varnames2, 'FX00_1 function of input x')
energy_3 = amegetvar(Results3, Varnames3, 'FX00_1 function of input x')
energy_4 = amegetvar(Results4, Varnames4, 'FX00_1 function of input x')
energy_5 = amegetvar(Results5, Varnames5, 'FX00_1 function of input x')

Here the variables energy_1, energy_2, energy_3, energy_4, and energy_5 contain all values during the
simulation time. You are going to plot a bar graph that shows the final values of all variables.

1. In the main script you first need to define the labels titles and the values that are used.

At this step the code is the following:

# Post-processing the results

Results1, Varnames1 = ameloadt('myModel', '1')
Results2, Varnames2 = ameloadt('myModel', '2')
Results3, Varnames3 = ameloadt('myModel', '3')
Results4, Varnames4 = ameloadt('myModel', '4')
Results5, Varnames5 = ameloadt('myModel', '5')
energy_1 = amegetvar(Results1, Varnames1, 'FX00_1 function of input x')

Plots Python API, Simcenter Amesim 2310 4-1

© 2023 Siemens
 4. Simple examples

energy_2 = amegetvar(Results2, Varnames2, 'FX00_1 function of input x')

energy_3 = amegetvar(Results3, Varnames3, 'FX00_1 function of input x')
energy_4 = amegetvar(Results4, Varnames4, 'FX00_1 function of input x')
energy_5 = amegetvar(Results5, Varnames5, 'FX00_1 function of input x')

data_labels = ['Scenario 1',

'Scenario 2',
'Scenario 3',
'Scenario 4',
'Scenario 5']
data = [energy_1[0][0][-1],
energy_2[0][0][-1],
energy_3[0][0][-1],
energy_4[0][0][-1],
energy_5[0][0][-1]]

Note:
data_labels is the list of the titles of the bars and data is the list of the values.

2. Create a new python file and save it as [Link].

This file is a new module where you can define different built-in graph display functions. In this
example you only define the bar graph.

The function is named plotBar and has as arguments the data and the labels.

At this step the code is the following:

import amepyplot

def plotBar(data, labels):

3. In the function plotBar you first create the plot widget using PlotWidget(), set the size of the plot
window using resize(), and access the graph using firstGraph().

Note:
Here there is only one graph on the plot window however you can define a layout that
contains several graphs in the same plot window.

At this step the code is the following:

import amepyplot

4-2 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 Plot a bar graph

def plotBar(data, labels):

plot = [Link]()
[Link](800, 550)
graph = [Link]()

4. Next, you need to create the data items (using Item object) that gather the values, and the curve
that is represented by one set of discrete values: Curve1DDiscrete.

The values of each variable are displayed as labels and their positions are set to
[Link].

Note:
By default the DisplayBarchart is used for 1D discrete curves. Then dedicated functions can
be applied to the graph to set horizontal bars or stacked bars.

At this step the code is the following:

import amepyplot

def plotBar(data, labels):

plot = [Link]()
[Link](450, 400)
graph = [Link]()

# Create data
item = [Link](data)

# Create curve
curve = amepyplot.Curve1DDiscrete(labels, item)

[Link]().configure(label=[Link])

5. The final step to fully define the function plotBar is to attach the curve to the graph using the
function addCurve.

At this step the code is the following:

import amepyplot

def plotBar(data, labels):

plot = [Link]()
[Link](450, 400)
graph = [Link]()

Plots Python API, Simcenter Amesim 2310 4-3

© 2023 Siemens
 4. Simple examples

# Create data
item = [Link](data)

# Create curve
curve = amepyplot.Curve1DDiscrete(labels, item)

[Link]().configure(label=[Link])

# Add the curve to the graph

[Link](curve)

# Configure graph
[Link](showXAxisTitle=False, showTitle=False)

[Link]()

return plot

Note:
Some functions are used to configure the graph elements such as the title and the axes.

6. Since the function to plot a 2D line graph is complete you just need to call it from your main script.
Remember that you need to import the new module ameplot.

...
import ameplot
from PySide2 import QtWidgets

...
...

# Post-processing the results

Results1, Varnames1 = ameloadt('myModel', '1')
Results2, Varnames2 = ameloadt('myModel', '2')
Results3, Varnames3 = ameloadt('myModel', '3')
Results4, Varnames4 = ameloadt('myModel', '4')
Results5, Varnames5 = ameloadt('myModel', '5')
energy_1 = amegetvar(Results1, Varnames1, 'FX00_1 function of input x')
energy_2 = amegetvar(Results2, Varnames2, 'FX00_1 function of input x')
energy_3 = amegetvar(Results3, Varnames3, 'FX00_1 function of input x')
energy_4 = amegetvar(Results4, Varnames4, 'FX00_1 function of input x')
energy_5 = amegetvar(Results5, Varnames5, 'FX00_1 function of input x')

data_labels = ['Scenario 1',

'Scenario 2',
'Scenario 3',

4-4 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 Plot a bar graph

'Scenario 4',
'Scenario 5']
data = [energy_1[0][0][-1],
energy_2[0][0][-1],
energy_3[0][0][-1],
energy_4[0][0][-1],
energy_5[0][0][-1]]

# Create the application if needed

app = [Link]()
if app is None:
app = [Link]([])

# Call the created function

plot = [Link](data, data_labels)

# Start the application

app.exec_()

Using the Plots Python API you are able to display the results that are calculated from a standalone
script. You can create the following curve for instance:

Figure 4-1. Simcenter Amesim plot window

Plots Python API, Simcenter Amesim 2310 4-5

© 2023 Siemens
 4. Simple examples

Note:
The function plotBar returns the plotWidget; you then have access to the graph for further
customization.

4.2 Plot a spider graph

When using the Simulation scripting functions, you can run a simulation, then load the results and get
specific variables. This is typically done through the functions amerunsingle, ameloadt, and amegetvar.

In this example it is assumed that 7 criteria are calculated within the model for analysis of its behavior.

The following piece of Python code illustrates the use of these functions:

# Post-processing the results

Results, Varnames = ameloadt('myModel')
consumption = amegetvar(Results,Varnames,'FX00_1 function of input x')
performance = amegetvar(Results,Varnames,'FX00_2 function of input x')
tipin = amegetvar(Results,Varnames,'FX00_3 function of input x')
tipout = amegetvar(Results,Varnames,'FX00_4 function of input x')
openthrottle = amegetvar(Results,Varnames,'FX00_5 function of input x')
closethrottle = amegetvar(Results,Varnames,'FX00_6 function of input x')
gearchange = amegetvar(Results,Varnames,'FX00_7 function of input x')

Here the variables consumption, performance, tipin, tipout, openthrottle, closethrottle, and gearchange
contain all values during the simulation time. You are going to plot a spider graph that shows the final
values of all variables.

1. In the main script you first need to define the labels titles and the values that are used.

At this step the code is the following:

# Post-processing the results

Results, Varnames = ameloadt('myModel')
consumption = amegetvar(Results,Varnames,'FX00_1 function of input x')
performance = amegetvar(Results,Varnames,'FX00_2 function of input x')
tipin = amegetvar(Results,Varnames,'FX00_3 function of input x')
tipout = amegetvar(Results,Varnames,'FX00_4 function of input x')
openthrottle = amegetvar(Results,Varnames,'FX00_5 function of input x')
closethrottle = amegetvar(Results,Varnames,'FX00_6 function of input x')
gearchange = amegetvar(Results,Varnames,'FX00_7 function of input x')

data_labels = ['Consumption',
'Performance',

4-6 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 Plot a spider graph

'Tip-in',
'Tip-out',
'Wide\nopen throttle',
'Zero\nthrottle',
'Gear change']

data = [consumption[0][0][-1],
performance[0][0][-1],
tipin[0][0][-1],
tipout[0][0][-1],
openthrottle[0][0][-1],
closethrottle[0][0][-1],
gearchange[0][0][-1]]

Note:
data_labels is the list of the titles of the spider chart axes and data is the list of the values.

2. Create a new python file and save it as [Link].

This file is a new module where you can define different built-in graph display functions. In this
example you only define the spider graph.

The function is named plotSpider and has as arguments the data and the labels.

At this step the code is the following:

import amepyplot

def plotSpider(data, labels):

3. In the function plotSpider you first create the plot widget PlotWidget(), set the size of the plot
window using the function resize(), and access the graph (through firstGraph()).

Note:
Here there is only one graph in the plot window however you can define a layout that
contains several graphs in the same plot window.

At this step the code is the following:

import amepyplot

def plotSpider(data, labels):

plot = [Link]()

Plots Python API, Simcenter Amesim 2310 4-7

© 2023 Siemens
 4. Simple examples

[Link](800, 550)
graph = [Link]()

4. Next, you need to create the data items (using Item object) that gather the values, and the curve
that is represented by one set of discrete values: Curve1DDiscrete.

The display of the curve can be changed using the function changeDisplay and to modify the
symbol for the markers, use configureSymbol on the curve display.

Note:
For spider graphs, you can also use the Display2DArea to fill the area defined by the curve
with color.

At this step the code is the following:

import amepyplot

def plotSpider(data, labels):

plot = [Link]()
[Link](450, 400)
graph = [Link]()

# Create data
item = [Link](data)

# Create curve
curve = amepyplot.Curve1DDiscrete(labels, item)

# Change the display to use the 2D line

[Link](amepyplot.Display2DLine(lineThickness=2))

# Configure the markers

[Link]().configureSymbol(style=[Link],
fill=[Link],
antialiasing=True,
size=2)

5. The final step to fully define the function plotSpider is to attach the curve to the graph using
the function addCurve. For the spider graph, you need to apply a conversion of the graph
(convertToSpider) otherwise the display will be a basic 2D line.

At this step the code is the following:

import amepyplot

4-8 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 Plot a spider graph

def plotSpider(data, labels):

plot = [Link]()
[Link](450, 400)
graph = [Link]()

# Create data
item = [Link](data)

# Create curve
curve = amepyplot.Curve1DDiscrete(labels, item)

# Change the display to use the 2D line

[Link](amepyplot.Display2DLine(lineThickness=2))

# Configure the markers

[Link]().configureSymbol(style=[Link],
fill=[Link],
antialiasing=True,
size=2)

# Add the curve to the graph

[Link](curve)

# Convert graph to spider

[Link]()
[Link]([Link])

# Configure graph
[Link](showXAxisTitle=False, showTitle=False)
[Link]().setUnitDrawn(False)

[Link]()
return plot

Note:
Some functions are used to configure the graph elements such as the drawing area (straight
or rounded), the title, and the axes.

6. Since the function to plot a spider graph is complete you just need to call it from your main script.
Remember that you need to import the new module ameplot.

...
import ameplot
from PySide2 import QtWidgets

Plots Python API, Simcenter Amesim 2310 4-9

© 2023 Siemens
 4. Simple examples

...
...

# Post-processing the results

Results, Varnames = ameloadt('myModel')
consumption = amegetvar(Results, Varnames, 'FX00_1 function of input x')
performance = amegetvar(Results, Varnames, 'FX00_2 function of input x')
tipin = amegetvar(Results, Varnames, 'FX00_3 function of input x')
tipout = amegetvar(Results, Varnames, 'FX00_4 function of input x')
openthrottle = amegetvar(Results, Varnames, 'FX00_5 function of input
x')
closethrottle = amegetvar(Results, Varnames, 'FX00_6 function of input
x')
gearchange = amegetvar(Results, Varnames, 'FX00_7 function of input x')

data_labels = ['Consumption',
'Performance',
'Tip-in',
'Tip-out',
'Wide\nopen throttle',
'Zero\nthrottle',
'Gear change']

data = [consumption[0][0][-1],
performance[0][0][-1],
tipin[0][0][-1],
tipout[0][0][-1],
openthrottle[0][0][-1],
closethrottle[0][0][-1],
gearchange[0][0][-1]]

# Create the application if needed

app = [Link]()
if app is None:
app = [Link]([])

# Call the created function

plot = [Link](data, data_labels)

# Start the application

app.exec_()

Using the Plots Python API you are able to display results that are calculated from a standalone scripts.
You can create the following curve for instance:

4-10 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 Plot a spider graph

Figure 4-2. Simcenter Amesim plot window

Note:
The function plotSpider returns the plotWidget; you then have access to the graph for further
customization.

Plots Python API, Simcenter Amesim 2310 4-11

© 2023 Siemens
 4. Simple examples

4-12 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 5. Advanced examples
In these examples we show how to use the Plots Python API functions in an App.

To understand these examples App Designer knowledge is required.

5.1 The Plot API demo

In the Simcenter Amesim demos section related to the App Designer, there is a dedicated demo named
Plot API App. The purpose of the demo is to show how to use the Plots Python API inside an App using
the App Designer.

When launching the App you can scroll through the list of plot types and observe the Python code and
the generated graph display.

If you want to generate such plot in your own App you can copy and paste the code and provide a
PlotWidget reference to the Plot method.

Below are some plot types that you can find in the demo:

• Plot contour

Plots Python API, Simcenter Amesim 2310 5-1

© 2023 Siemens
 5. Advanced examples

Figure 5-1. Contour

• Plot surface

5-2 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 The Plot API demo

Figure 5-2. Surface

• Plot pie chart

Plots Python API, Simcenter Amesim 2310 5-3

© 2023 Siemens
 5. Advanced examples

Figure 5-3. Pie chart

5.2 Create a plot in an App

In this example we show how to use the dedicated Simcenter Amesim widget for plot that is available
in the User Interface editor of the App Designer.

A piece of code is copied from the Plot API demo in order to demonstrate how to use it in the main
project of an app. It is recommended to keep the app from the Plot API demo open.

1. Create a new App and select Dialog as type of window.

2. From the User Interface editor, select the Amesim Display Widgets Plot and drag-and-drop it
onto your MainForm.

5-4 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 Create a plot in an App

Figure 5-4. Widget Plot in a MainForm object

3. Select the MainForm object and apply a grid layout .

4. Select the plotWidget and rename it as myPlotWidget .

Figure 5-5. Grid layout applied

5. In the Plot API demo app select Separated Axes as plot type.

6. Copy all the code but the module import lines.

Plots Python API, Simcenter Amesim 2310 5-5

© 2023 Siemens
 5. Advanced examples

7. Then from the Python editor you can paste it in the section Insert extra code here/End of extra
code of the [Link] file at the line 70.

Figure 5-6. Insert code of plot method

8. Add the import of the modules in the section Insert extra code here/End of extra code at the line
11.

Figure 5-7. Insert import of modules

5-6 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 Create a plot in an App

9. Call the createPlot method in the section Extra initialization declarations here/End of initialization
at line 38 to display the plot in the widget.

Figure 5-8. Call createPlot method

When you launch the app the following window appears:

Note:
The values are defined by mathematical functions in the code. You can also retrieve variables from
the model to have them in the plot instead.

Plots Python API, Simcenter Amesim 2310 5-7

© 2023 Siemens
 5. Advanced examples

5-8 Plots Python API, Simcenter Amesim 2310

© 2023 Siemens
 Index
P
Plots Python API, Getting started 2-1
Plots Python API, Setting the environment 2-1
Plots Python API, User's guide 1-1

Plots Python API, Simcenter Amesim 2310 Index-1

© 2023 Siemens