Beruflich Dokumente
Kultur Dokumente
Think SysML
Tutorials
Peter L. Jackson
Professor
Systems Engineering Program
School of Operations Research and Information Engineering
Version 2 August, 2012
8/22/2012
Page |1
1 Executive Summary
This document is a collection of tutorials for using SysML, the Systems Modeling Language,
with Topcased, a free, open source SysML editor. These tutorials are intended for use in a graduate course
in Model-Based Systems Engineering at Cornell University but they are made publicly available on the
Think SysML website (www.thinksysml.org) which is hosted by the Cornell Systems Engineering
Program. The purpose is to promote the widespread use of SysML.
The theme of the website is Think SysML, that is, use SysML for as many applications as you
can think of. Only by frequent use will you become comfortable with its constructs and only by many
people using it will the language grow and develop. In the spirit of Think SysML, we have chosen to
write these tutorials using SysML. Each tutorial is expressed as an activity diagram: a sequence of steps to
follow, with documentation attached to each step. The activity diagrams are stored in a single SysML
model, called Tutorial. You can view the structure of the model by visiting the Tutorial page of the
Think SysML website and clicking on TutorialTree.
This document was generated automatically from the SysML model, Tutorial, using a custom
script and Microsoft Word template. One of the tutorials will introduce you to this feature.
8/22/2012
Page |2
2 Contents
1
Contents ................................................................................................................................................ 3
3.1
3.2
3.3
3.4
3.5
3.6
4.2
5.2
6.2
7.2
7.3
7.4
7.5
7.6
7.7
7.8
8.2
8/22/2012
Page |3
8.3
8.4
8.5
8.6
8.7
8.8
8.9
8.10
8.11
9.2
9.3
9.4
8/22/2012
Page |4
This collection of tutorials guides you through the process of setting up your computer to use the
Topcased editor for SysML and to import some pre-built models to get you started.
8/22/2012
Page |5
3.1
This tutorial explains how to download and install the Eclipse development environment and the
Topcased editor.
3.1.1
Is JRE Installed?
JRE stands for the Java Runtime Environment. To discover if JRE is installed on your system, go
to the Java website and click on the test link: http://www.java.com/en/download/testjava.jsp.
The link is labelled "test the currently installed version of Java."
If {true} then go to the step called "Navigate your browser to ThinkSysML-3rd Party."
If {false} then go to the step called "Install Java Runtime Environment."
8/22/2012
Page |6
It is likely that the Java Runtime Environment is already installed on your computer. If it is not,
you can find instructions on manually installing it for a Windows system
at:http://www.java.com/en/download/help/windows_manual_download.xml.
3.1.3
These tutorials were developed for Topcased version 4.3. To ensure that you download the
correct version, a copy has been placed on the Think SysML website.
3.1.4
3.1.5
8/22/2012
Page |7
3.1.6
We suggest unzipping the file into the Program Files (x86) directory. The detailed steps are:
1. Locate the downloaded file in the Downloads directory.
2. Right-click the file and select "Extract all".
3. In the "Select Destination" dialog, navigate to c:\Program Files (x86) and click OK.
8/22/2012
Page |8
3.1.7
Launch eclipse
Find the executable program called "eclipse" in the Topcased-4.3.0 directory and double-click it.
8/22/2012
Page |9
3.1.8
Eclipse may fail to launch if the Java Runtime Environment is not installed. For other troubleshooting ideas, consult the Topcased installation guide.
3.1.9
8/22/2012
P a g e | 10
Create a workspace
When Eclipse first launches it asks to create a workspace. We recommend creating a workspace
in a location of your choice. In the images below, we show the creation of a workspace as a new
folder: "c:\ThinkSysML".
3.1.11
Select a workspace
From now on, whenever Eclipse launches it will prompt you to choose a workspace. Use the
"Browse" button to select the one you created in the previous step.
8/22/2012
P a g e | 11
3.1.12
If you have been successful to this point, your screen should look something like this:
If it does, then you have the correct perspective open. If eclipse opens with a different
perspective, it might look like this:
8/22/2012
P a g e | 12
In that case, you need to open the Topcased Modeling Perspective (next step).
3.1.13
3.1.14
8/22/2012
P a g e | 13
3. The resulting perspective should show a "Navigator" tab in the upper left corner of the Eclipse
workbench. That tab will be the starting point in subsequent tutorials.
8/22/2012
P a g e | 14
If you are viewing this documentation in a browser from the link "Tutorial Tree", return to the
next higher level diagram for a suggestion as to what tutorial to visit next. There are navigation
buttons at the top of the diagram window:
8/22/2012
P a g e | 15
The custom ThinkSysML scripts use open source plugins to the Eclipse framework that are not
part of the Topcased download. This tutorial shows how to download and install these plugins.
This tutorial assumes that you have installed Topcased.
3.2.1
These tutorials were developed for a particular version of SWTChart (an eclipse plugin). To
ensure that you download the correct version, a copy has been placed on the Think SysML
website.
8/22/2012
P a g e | 16
3.2.2
3.2.3
Locate the SWTChart jar file in the plugins folder of the downloaded SWTChart zip file. Copy
this file to the clipboard (<ctrl>C).
3.2.4
Navigate your file explorer to the Topcased/plugins folder and paste the SWTChart.jar into this
folder.
8/22/2012
P a g e | 17
8/22/2012
P a g e | 18
3.3.1
These tutorials were developed using OpenModelica 1.6. To ensure that you download the
correct version, a copy has been placed on the Think SysML website.
8/22/2012
P a g e | 19
Download OpenModelica
3.3.3
Navigate to the Downloads folder and double-click on the installation program ("OpenModelica1.6.0-revision-7524.msi").
After you have launched the installation program and given Windows permission to proceed, you
will see a welcome screen like this:
8/22/2012
P a g e | 20
Click 'Next'. On the next screen, check to be sure that the default directory is
"C:\OpenModelical1.6.0\".
8/22/2012
P a g e | 21
Click "Next".
8/22/2012
P a g e | 22
Click "Next".
8/22/2012
P a g e | 23
8/22/2012
P a g e | 24
This tutorial explains how to download and install custom ThinkSysML scripts and plugins.
3.4.1
8/22/2012
P a g e | 25
3.4.3
Locate the SysML2Modelica jar file in the plugins folder of the downloaded zip file. Copy this
file to the clipboard (<ctrl>C).
3.4.4
Navigate your file explorer to the Topcased/plugins folder and paste the SysML2Modelica jar
file into this folder.
8/22/2012
P a g e | 26
The Topcased website includes a SysML model describing a digital watch. This tutorial
describes how to download the project and import it directly into your Topcased workspace. It
illustrates how you can import existing projects into your workspace.
This tutorial assumes you have installed the Topcased software and created a workspace called
'ThinkSysML.'
3.5.1
These tutorials were developed for a particular version of the Watch Project(a SysML model).
To ensure that you download the correct version, a copy has been placed on the Think SysML
website.
8/22/2012
P a g e | 27
3.5.2
Click on the link to the SysML model example to download the project zip file.
3.5.3
Using your file explorer, locate the downloaded file in your Downloads folder. Right-click the
file and select "Extract all." Use the browse button to locate your Topcased workspace directory.
Click "OK."
3.5.4
Using your file explorer, open the Watch (SysML) folder and observe that it contains a project
file. That is a good indicator that the whole Watch (SysML) folder can be imported into your
Topcased workspace as an existing project.
8/22/2012
P a g e | 28
3.5.5
From the File menu, select Import. A wizard dialog appears. From the first screen, select
"General->Existing Projects into Workspace."
8/22/2012
P a g e | 29
Use the browse button to locate the Watch (SysML) folder within your workspace folder. Once
you have selected this root directory, the wizard should display the Watch (SysML) project as
available for import.
3.5.7
Click the Finish button. (Do not select the "Copy files" feature because you have already copied
the files into the ThinkSysML workspace folder.) A folder for the Watch (SysML) project should
now appear in the Topcased Navigator Window.
8/22/2012
P a g e | 30
3.5.8
In the navigator component, double-click on the file "Digital watch.sysmldi". This is the diagram
file for one of the models in this project. Double-clicking should open a graphical editor to
display this model. Other tutorials may exploit this model.
8/22/2012
P a g e | 31
The Think SysML website offers several downloadable SysML models. Only the model files are
downloaded, not the full project structure. This tutorial describes how to download one such
model (SimpleParametric) and import the model into your Topcased workspace. As part of this
tutorial, you will create a temporary folder to hold the downloaded model files. You will also
create a SysML project within your workspace to receive such imported models. The tutorial
describes two ways to import a model from a file folder into a project folder: a menu-based
approach and a drag-and-drop approach.
3.6.1
Use your file explorer to navigate to your workspace folder. We created the workspace folder
"ThinkSysML" in an earlier tutorial. Create a new folder called, say, "DownloadedModels" to
temporarily hold models you want to import.
8/22/2012
P a g e | 32
3.6.2
Navigate your browser to the Gallery page of the Think SysML website:
http://thinksysml.org/Gallery.html.
3.6.3
Locate the hyperlink "SimpleParametric.zip" and click on it to download the zip file.
3.6.4
Use your file explorer to locate the SimpleParametric.zip file in your downloads folder. Rightclick the file and select "Extract all...". Use the browse button to locate the DownloadedModels
folder you created in the workspace folder earlier in this tutorial. Click OK to uncompress the
model files from the zip file into this DownloadedModels folder. This folder is only for
temporary use. You may delete it and its contents at the end of the tutorial.
8/22/2012
P a g e | 33
3.6.5
From Topcased select menu item File->New->Project and choose a "Topcased Project" from the
first wizard page.
3.6.6
Give the project a name such as "Assorted" to suggest that it will contain diverse models.
8/22/2012
P a g e | 34
3.6.7
From the Topcased Navigator, open the Models folder within the "Assorted" project.
3.6.8
Choose file import method
The model files must be "imported" into the Topcased project. There are at least two equivalent ways of
performing the import action: a menu-based approach and a drag and drop approach. Use whichever
approach you like.
If {Use drag and drop approach} then go to the step called "Select model files to import."
If {Use menu-based approach} then go to the step called "From Topcased, select Import-GeneralFile System."
3.6.9
With the Assorted-Models folder open in the Topcased Navigator, select menu item File>Import->General->File System. Click "Next."
8/22/2012
P a g e | 35
3.6.10
Click the Browse button and select the directory "DownloadedModels" that contains the model
files. This is the temporary directory you created in an earlier step.
8/22/2012
P a g e | 36
3.6.11
Click "Select All" to import both model files for the SimpleParametric model
(SimpleParametric.sysml and SimpleParametric.sysmldi). Click the "Finish" button to confirm
the import action.
8/22/2012
P a g e | 37
Use your file explorer to open the DownloadedModels folder within the ThinkSysML folder.
Select the two model files for the SimpleParametric model (SimpleParametric.sysml and
SimpleParametric.sysmldi).
8/22/2012
P a g e | 38
Drag and drop files from file explorer to Topcased project Models folder
Drag the selected model files from the file explorer window to the Topcased window and drop
them in the Models folder of the Assorted project within the Topcased Navigator.
3.6.14
Click "OK" to confirm that the model files should be copied into the project. This will complete
the import action.
Import completed
8/22/2012
P a g e | 39
A graph-based editor displaying the SimpleParametric model should appear within the Topcased
environment. This will be the starting point for a later tutorial on parametric diagrams in SysML.
If this is not the diagram that displays when the model is first opened, try clicking the "Go to the
Root Diagram" button on the menu bar.
8/22/2012
P a g e | 40
8/22/2012
P a g e | 41
4.1
This tutorial picks up from where the Installation and Setup group of tutorials left off.
4.1.1
8/22/2012
P a g e | 42
Click on "Go to the Root Diagram" to navigate to the top level diagram.
The root diagram simply shows a collection of three packages: "Basic Definitions," "Equations,"
and "Structure."
4.1.2
In the Outline panel, click on the "Show Both" mode to view both the model navigator and the
outline overview.
8/22/2012
P a g e | 43
Drag the viewport rectangle and observe how it changes the view of the diagram editor.
8/22/2012
P a g e | 44
To see a simple example of filtering model elements, click on "Filters On" mode.
Select "Hide Edges" from the resulting dialog and click "OK".
8/22/2012
P a g e | 45
Can you see what has changed? (Hint: where have all the associations gone?) Now, before
moving on, be sure to reset the filter so "Hide Edge" is unchecked.
Another filter that is interesting is the "Show Only" Diagrams Filter. Try it but make sure change
it back to "Show" Diagrams Filter when you are finished.
8/22/2012
P a g e | 46
Expand the packages "Basic Definitions" and "Equations" so that you are comfortable exploring
the model elements in outline view. For example, can you find a block named "Test1"?
As you might expect, if you double-click on a diagram title in outline view, the associated
diagram will appear in the editor window.
4.1.3
Before moving on, double-check to make sure that the "Hide Edge" filter is unchecked in the
"Filters On" dialog and click "OK". (Hidden edges would cause problems in later tutorials.)
4.1.4
Observe the panels containing tabs for supplementary editors. These should be at the bottom
center of your window.
8/22/2012
P a g e | 47
Close the view of the SME Scenario editor by clicking on the "X" in its tab. We will not be using
this editor.
Drag the Documentation tab and drop it into the panel that contains the Properties tab.
Check the box labelled "Use HTML Editor" to get a nicer view of the documentation text.
8/22/2012
P a g e | 48
4.1.5
From the Structure diagram, double-click on the TestResults block to navigate to its diagram.
The parametric diagram associated with TestResults is the diagram we want to "solve" in a
subsequent tutorial.
8/22/2012
P a g e | 49
Using these techniques, you can explore the rest of the model and its documentation.
4.1.6
Export to HTML
8/22/2012
P a g e | 50
In the folder selection dialog, select the parent folder "Assorted" and click "Create New Folder."
In the New Folder dialog, enter the name "HTML" and click OK.
8/22/2012
P a g e | 51
Eventually, we will have more than one model in the Assorted folder, so let's create a sub-folder
to hold the HTML for the SimpleParametric model. Select the "HTML" folder and click "Create
New Folder."
8/22/2012
P a g e | 52
The export process exports all the diagrams from the model with supporting documentation.
When complete, the files created are visible in the Navigator window.
8/22/2012
P a g e | 53
The diagrams and supporting documentation can now be explored using a browser.
4.1.7
Using the Windows Explorer, navigate to the folder containing the HTML content for the
SimpleParametric model. Right click on the folder and select "Send to ... Compressed Folder".
8/22/2012
P a g e | 54
If this were your model, you could e-mail the resulting compressed file to other members of your
team who could then view your model using a browser. Your instructor in this course may ask
for a copy of the file as evidence that you have completed this tutorial.
8/22/2012
P a g e | 55
The SimpleParametric model contains parametric diagrams that describe equations which must be
satisfied by certain value properties. OpenModelica can be used to solve the equation for unknown
variables. A special script, called SysML2Modelica, can be used to convert the parametric diagrams into a
model that OpenModelica can solve. This tutorial demonstrates the use of this script. It assumes that all of
the required software (OpenModelica, SWTChart, and SysML2Modelica) have been installed.
4.2.1
Open the SimpleParametric model and navigate to the Structure diagram. Select the block
"TestResults" by clicking on it.
8/22/2012
P a g e | 56
4.2.2
This will launch a wizard for solving parametric diagrams using OpenModelica. The wizard is
custom, non-proprietary code from ThinkSysML. Source code for the wizard is available upon
request.
8/22/2012
P a g e | 57
Click Next. (The Finish button is the same as Cancel, in this implementation.)
4.2.3
Prior to running this script, you need to have installed OpenModelica. On this screen, use the
browse buttons to locate the directory where the program OMShell.exe is stored and to locate a
directory that may be used for temporary storage.
8/22/2012
P a g e | 58
Click Next.
4.2.4
The starting point for the SysML2Modelica wizard is a block that contains a parametric diagram.
On this screen, you confirm the starting block selected or use the outline to find a different
starting block. Click Next to confirm.
8/22/2012
P a g e | 59
4.2.5
On the Graph View page of the wizard, you may view a graph representing the parametric
diagram. The nodes of the graph represent variables and the arcs represent equations. The nodes
with red squares represent constraint properties. These constraint properties likely contain
Modelica code in text format. The arcs connecting variables to red squares indicate which
variables participate in the Modelica code. The graph is very useful when debugging a model: it
is easy to spot missing connections. Click "Create and Show Graph" to view the graph.
8/22/2012
P a g e | 60
Note that the graph is more complicated than the parametric diagram associated with the
TestResults block. That is because it merges all of the nested parametric diagrams into what is
called a "flattened" graph.
You may click the "Create and Show Graph" button several times: Each time will result in a new
randomized layout of the graph.
Click Next to proceed. This will take you to the Parameter and Variable Values page.
Click Refresh Values to see the initial values of the variables and parameters for the parametric
diagram.
8/22/2012
P a g e | 61
In this example, we see that Test1_Score and Test2_Score are parameters with values 80 and 90,
respectively. TotalScore is a target variable (indicated by the TBD value: "To Be Determined").
Click Next.
4.2.6
Execute Script
From the information provided, the wizard will generate a Modelica model and an
OpenModelica script to solve the model. In future tutorials we will explain Modelica more fully.
For this tutorial, we will simply execute the script. Click the button Execute Script. After a delay
(in which the OpenModelica shell program is launched and the model solved) a listing of the
solution results is displayed in the text box below the buttons.
8/22/2012
P a g e | 62
If the model execution was successful, you should see the result 85.0 displayed for the
TotalScore variable. Recall this was the variable whose value was To Be Determined. Click
Next.
If this is not the result you get, then perhaps there was a problem with the OpenModelica
installation. Try executing the script again, but this time with "Verbose" Output Detail checked.
8/22/2012
P a g e | 63
If there was a problem, there may be useful error messages in the verbose output.
4.2.7
View Results
On the Simulation Plot Results page, you can plot the results for different target variables. In this
example, there is only one target variable, TotalScore, and there is no time dimension to the
model so the plot is not very interesing. Nevertheless you can see the plot by clicking "Plot
Values" and then checking the box "TotalScore".
8/22/2012
P a g e | 64
The plot shows the value 85, which is the value of TotalScore.
Click Next to proceed.
4.2.8
The Update SysML Model page is the last page of the wizard. Click Refresh Values to see the
ending values of the target variables from the Modelica simulation. In this case, the TotalScore
8/22/2012
P a g e | 65
variable ends with the value 85. Note that we retain the phrase "TBD" in the value as a reminder
that this was a target variable.
The last step of the wizard is to copy these ending values back into the SysML model. This step
is optional. Click the button Update SysML to perform the copy. Then click Finish to exit the
wizard.
In the TestResults block of the SysML model, the value "TotalScore" should now read "TBD
(end=85.0)", reflecting the results of the model solution. To see where this value is stored, click
the properties tab and the Specification property. This is where default values are stored.
8/22/2012
P a g e | 66
Let's solve the model again but with different inputs and a different target variable. Since the
model consists simply of a system of equations we should be able to choose different inputs and
outputs. Initially, Test1_Score and Test2_Score were treated as inputs and the value TotalScore
was treated as an output. Suppose we knew the Test1_Score and knew the TotalScore we wanted
to achieve. We would like to compute the Test2_Score required to achieve that TotalScore.
Locate the default value for TotalScore (select TestResults, click TotalScore value
property, click Properties tab, click Specification property) and change its default value to 87.
Locate the default value for Score2 (select Score2, click Properties, click Specification).
Currently, its value is 90.
8/22/2012
P a g e | 67
Change the default value of Score2 from 90 to "TBD". This signals that Score2 is now a target
variable.
Now, repeat all the steps to solving a parametric diagram using the SysML2Modelica wizard.
You should end with a value of Score2 = 94. The screenshots below are highlights of the steps.
8/22/2012
P a g e | 68
(This image does not show the "Verbose Output" option that has been added to the wizard
recently.)
8/22/2012
P a g e | 69
8/22/2012
P a g e | 70
5.1
5.1.1
Use your browser to visit the gallery page of the Think SysML website:
http://thinksysml.org/Gallery.html
8/22/2012
P a g e | 71
Click on the link "FSAERaceCarExport.zip". This will cause the file to be downloaded to your
"Downloads" directory.
5.1.3
Import Project
The import wizard will launch. On the Select screen, choose General->Archive and click "Next".
8/22/2012
P a g e | 72
In the "Import from Archive file" pop-up, navigate to your Windows downloads folder and
select the compressed file that was just downloaded ("FSAERacecarExport.zip"). Then, click
"Open".
8/22/2012
P a g e | 73
Back in the Import wizard, de-select the folder with no name and select, instead, the folder
named "FSAERacecar". Ensure that all its sub-folders are also selected, as shown. Then click
"Browse" to select the "Into Folder".
8/22/2012
P a g e | 74
8/22/2012
P a g e | 75
8/22/2012
P a g e | 76
If this step was successful, you will see the FSAERacecar project in the Assorted folder.
8/22/2012
P a g e | 77
5.2.1
Open the FSAE Racecar model by double-clicking on the file FSAERacecar.sysmldi in the
Navigator window.
8/22/2012
P a g e | 78
The root diagram is a requirements diagram that displays two packages: "Systems Engineering
Team Lead" and "SysML Student".
8/22/2012
P a g e | 79
A viewpoint block in each package explains the purpose of that package. The most natural
viewpoint is the Systems Engineer viewpoint because the motivation for building the SysML
model is to orient a new systems engineer to the FSAE Racecar project. The SysML
student viewpoint was added to the model after the systems engineer viewpoint was complete.
We did this to meet educational needs.
5.2.2
8/22/2012
P a g e | 80
This diagram displays eight packages. Some of these packages, such as the Requirements
package, contain further packages. These packages were created during concept analysis and
there is a logical sequence in which to view their contents. Rather than specify a rigid sequence
to the reader, we provide information as to which packages are dependent on other packages.
This is done with dependency relationships.
For example, we show a dependency relation from the Stakeholders package to the Initial
Context package. We read this relation as "The Stakeholders package depends on the Initial
Context package." It makes sense therefore for the reader to start with exploring the Initial
Context Package before exploring the Stakeholders package. Similarly, the Organization Chart
Package depends on the Stakeholders package. However, the Requirements package has no
dependency relation with the Stakeholders package, in either direction. So the reader can choose
to explore these two packages in any order.
8/22/2012
P a g e | 81
Return to the root diagram and double-click the SysML Student package.
In this diagram, we display nearly all of the packages from the Systems Engineering Team Lead
diagram. Note that there is only one instance of each of these packages in the model, even
though we display them on multiple diagrams. So keep in mind the distinction between the
model and the diagram. Double-clicking on any package in this diagram takes you to exactly the
same diagram as double-clicking on it in a different diagram. What is different about this
diagram is that we have added views that would be interesting to a SysML student. For example,
for students who are interested in finding examples of use case or state machine diagrams, we
have created views called Use Case Diagrams and State Machine Diagrams and we include in
those views all packages that contain use case diagrams or state machine diagrams, respectively.
The inclusion is through containment and import relations.
8/22/2012
P a g e | 82
The Use Case Diagram view contains the Behavior package, so you would visit the Behavior
package if you want to find an example of a use case diagram. Only one view can contain the
Behavior package but it is the package you should visit if you want to find an example of a state
machine diagram and an activity diagram. We indicate that with import relations. We say "The
State Machine Diagram view imports the Behavior package." Similarly, "The Activity Diagram
view imports the Behavior package". The purpose of a view can be suggested by connecting the
view to a viewpoint. In this diagram, we link all the views to the Language viewpoint using
conform relations. The viewpoint contains information about the organizing principle ("I want to
learn how to represent systems and processes using SysML."). Hence, we say "the State machine
diagram view conforms to the SysML Student viewpoint."
In summary, views are collections of contained or imported packages which conform to one or
more viewpoints.
5.2.4
8/22/2012
P a g e | 83
The systems engineer will be concerned not only about the actual vehicle design but also about
how the design project itself is organized and run. So it is useful to specify an overall context.
Composite arcs connect the FSAE TeamContext block with numerous other entities. The context
of our system is composed of the student team, faculty and staff, the team project, the
competition, and other related entities. More such entities can be added to the context if we
discover their relevance to the design project.
The FSAE Team Context block has a diagram associated with it, as indicated by the turned
arrow in the upper right corner.
Double-click on the FSAE Team Context block to view the associated diagram. It is an internal
block diagram (ibd).
8/22/2012
P a g e | 84
Here we are using the internal block diagram to represent a context diagram: a diagram of our
system (or systems) of focus in relationship to other systems and actors. The arcs represent
associations with verb phrases. In a context diagram, we position the verb phrases close to the
subject of the sentence they imply.
8/22/2012
P a g e | 85
For example, we read from this diagram that "the FSAE Student Team enrolls for Project Course
Credits," and "the FSAE Student Team solicits support from Corporate Sponsors."
This is a simple starting point for modeling. As we proceed with deeper levels of analysis, there
will be more entities discovered and included in the model. As new entities are added to the
model, we should return to the context diagram and describe their relationships to existing
entities. The context diagram will grow in size and complexity. To control the complexity, we
may eventually want multiple context diagrams to reveal different levels of relationship. Here
again, the model is capturing all of the relationships, we are using diagrams to capture and reveal
those relationships.
Navigate to the FSAE Student Team diagram (Top..Systems Engineering Team Lead..Initial
Context..FSAE Student Team.
8/22/2012
P a g e | 86
Here we see detailed the types of roles students play on the project team. Some students work on
the project not for course credit but as volunteers. Their engagement is often short so they are not
assigned leadership roles. Note the use of generalization arcs to add specificity to the model. We
read from the generalization arcs that "the Team Leader is a type of Student Team Member and
the Engine Team Leader is a type of Team Leader." Similarly, "the Lubrication Subteam Leader
is a type of Sub-team Leader which is also a type of Student Team Member."
5.2.5
Navigate to the Mission and Goals package. (Root..Systems Engineering Team Lead..Mission
and Goals.)
8/22/2012
P a g e | 87
This diagram illustrates a feature of the SysML language called stereotyping. The SysML
language has no model elements for "mission" or for "goals" but we needed such elements to
accurately describe our model. Fortunately, the SysML language is extensible by means of
stereotypes. For our purposes, we have defined two stereotypes (mission and goal) that are
derived from the requirement model element. This diagram shows us putting those two
stereotypes to use as part of our model.
The diagram also illustrates that relationships between requirement model elements can be
captured. Here we use the refine relationship to link each goal with the mission. That is, the goals
refine the mission. The mission is primary, the goals are secondary refinements.
5.2.6
8/22/2012
P a g e | 88
The FSAE Competition has published official rules for the racecar competition. These rules are
one source of requirements or constraints on the FSAE project team. Another source of
requirements and constraints might be rules imposed by Cornell University on the conduct of
projects or the use of facilities. We would like to represent such requirements in our model in
some form. One idea is to create an explicit requirement object in the SysML model for each of
these external or upstream requirements. Another idea is to use the Topcased feature of
importing upstream requirements. This feature is unique to Topcased: It is not part of SysML.
You should not expect to find this particular feature in other software packages that support
SysML. Nevertheless, it is reasonable to expect other packages to support some form of
connection to requirements databases so we have chosen to illustrate the Topcased approach.
In a separate activity, we downloaded the document describing the official FSAE rules (2012)
from the SAE website and (painstakingly) extracted the textual requirements one by one into a
MS Excel spreadsheet. This spreadsheet is included as part of the FSAERacecar project in the
Resources folder.
If you have MS Excel installed on your computer, you can view the file by double-clicking it.
8/22/2012
P a g e | 89
Notice that we created five columns to capture information about the requirements. We labeled
the columns "ID,SECTION, ARTICLE, TOPIC,TEXT", respectively. Topcased required at least
two columns, labeled "ID" and "TEXT", respectively. The other columns are useful for
organizing the requirements. We then imported this spreadsheet file as upstream requirements.
You can see that a file was created in the Models folder.
To view these imported requirements within Topcased, we must change the perspective. Click
the menu Window->Open Perspective->Other
8/22/2012
P a g e | 90
Now, in the navigation panel you should see a tab for "Upstream Requirements" and a link to the
requirements document file.
8/22/2012
P a g e | 91
It is likely that your view of the upstream requirements does not display the custom elements
"Section, Article, and Abstract" shown here:
To view these attributes, you must customize the perspective. Go to Window->Preferences>Topcased-Requirement->Upstream Settings and use the panel on the right to add attributes
8/22/2012
P a g e | 92
"Section," "Article," and "Abstract." You may need to close the model and re-open it for this
customization to take effect. The menu is located here:
8/22/2012
P a g e | 93
It would be nice to see these requirements in a tabular form. Unfortunately, Topcased 4.3 does
not provide tabular views even though the SysML specification allows for them. Developing
tabular views would be a useful open source project idea.
In the next step, we will show how Topcased allows these upstream requirements to be linked to
packages in the model. For this step, we want to stay with Topcased Requirements Perspective.
5.2.7
It can be useful to map upstream requirements to model elements in the SysML model. Topcased
allows a restricted form of mapping in that an upstream requirement can be mapped to a package
within the model. The mapping is not more specific than that. It does this by copying the
upstream requirement and associating it with a package. The copied requirement is known as a
current requirement in Topcased. Keep in mind that these terms are part of the Topcased
specification, not the SysML specification.
To illustrate the mapping, we have taken a single upstream requirement, FSAE-A1.2, and
mapped it to the Official FSAE Rules package. You can see the mapping in the current
requirement panel:
8/22/2012
P a g e | 94
Refer to the Topcased documentation on the Topcased website for more information on how to
exploit and manage these mappings.
This completes our exploration of upstream and current requirements in Topcased. To return to
the Topcased Modeling Perspective, click the corresponding icon in the toolbar at the top of the
window.
One possible activity of a systems engineer on the FSAE Racecar team is to manage system
requirements. SysML supports requirements management by allowing you to add requirements
model elements on a requirement diagram. To see an example of a small collection of
requirements, navigate to the Car Functional Requirements package (Top..Systems Engineering
Team Lead..Requirements..Car Functional Requirements).
8/22/2012
P a g e | 95
This is only an initial set of requirements and would have to be revised and expanded as part of
the team project.
5.2.9
Explore Stakeholders
8/22/2012
P a g e | 96
On this diagram, we have collected several actors whose perspective would be useful to keep in
mind. These entities have been defined in other packages using other diagrams. What is
interesting about this diagram is the fact that you can use the same entities on multiple diagrams.
When an entity appears on a diagram but is contained in a different package or block, the
containing object is indicated in parentheses. For example, the University Administrator was
defined as part of the Faculty and Staff block (in the Initial Context package) and the Student
Team Member was defined as part of the FSAE Student Team block. This serves to emphasize
again the distinction between models and diagrams ("the diagram is not the model").
5.2.10
8/22/2012
P a g e | 97
The organization chart is intended to show how the project team is organized in terms of
reporting requirements. For this purpose, we use a block definition diagram and generic
association arcs to show the reporting relationships. For example, we read from the diagram that
"the Flow Subteam Leader reports to the Engine Team Leader who reports to the Project
Leader." There is nothing in the model to tell us that we interpret the association arcs as
"reporting relationships" on this diagram. However, we could have extended the model to have a
stereotype for reporting relationships and then used that stereotype for each of the relationships
on this diagram.
5.2.11
Explore SE Roles
8/22/2012
P a g e | 98
The purpose of this diagram is to suggest different roles that the systems engineer on the FSAE
project team could play. The technical team leaders often have difficulty imagining what role the
systems engineer can play. The diagram starts by listing the twelve roles of a systems engineer as
identified by Sarah Sheard in her paper:
Sheard, Sarah, "Twelve Systems Engineering Roles", Proceedings of the INCOSE Sixth Annual
International Symposium (Boston, Massachusetts, USA). Copyright 1996 Software Productivity
Consortium, NRP, Inc., http://www.software.org.
At the bottom of the diagram, a block is created for the Systems Engineering Roles in the
Context of the FSAE Team and it is connected to the most suitable of the twelve roles identified
by Sheard.
8/22/2012
P a g e | 99
For example, it is not likely that the systems engineer on the team will be a technical manager or
a process engineer so no connection is made with those roles. Seven of the other roles might be a
possibility. In addition to the roles identified by Sheard, we have listed two other roles, Project
Manager and Project Scheduler, that are potential roles for the systems engineer.
5.2.12
Explore Behavior
As the comment on the left explains, the purpose of this package is to propose a part design
process that is more formal than the ad hoc processes typically used on student team projects. So
the focus of the behavior analysis in this model is not on the vehicle being designed and built
but, rather, the focus is on the project team itself. The use case, Design a Part, is shown as an
8/22/2012
P a g e | 100
oval and the users who interact with the use case are the actors arrayed around the use case.
Attached to the use case is an activity diagram that describes the activity associated with the use
case in more detail.
Double-click on the use case, Design a Part, to view the activity diagram.
The activity diagram displays a pre-condition and a post-condition. This is a useful convention to
include in your diagrams because it can clarify when the activity is appropriate and what the
expected result is. This activity diagram further uses swimlanes to group the actions and suggest
ownership. The swimlanes have been named "Designer," "Systems Engineer," "Project
Scheduler," " Sub-team Leader," and "Project Leader" but there is no actual connection in the
model between these swimlanes and the entities they represent (ED. Note: we have not yet
figured out how to make that connection). Start reading the diagram with the action that follows
the initial node ("Authorize part design and assign to designer") and follow the control flow,
paying attention to who is expected to perform each action (which swimlane it belongs to). The
diamond-shaped decision nodes indicate a critical juncture in which the process may stop if the
condition being tested in not true. As the comment suggests, only the true control branches are
displayed because the backtracking inherent in design would be visually confusing to display.
This style of activity diagram is also useful for suggesting where interface specifications are
required. Every control flow that crosses a swimlane boundary signals the need for an interface
specification. For example, what is the designer expected to present to the systems engineer at
the preliminary design review? It is pre-mature to define such interfaces during concept analysis
so we have not done so.
This is an ideal view of a part design process. Student team members are likely to rebel against
such a formal process even though it is what will be expected of them in many employment
8/22/2012
P a g e | 101
settings. It would be a success if the systems engineer on the FSAE team could persuade the
team leaders to implement even part of this process, such as the preliminary design review.
The activity diagram with swimlanes is useful for describing test procedures, discovering
functional requirements, and identifying interfaces with actors and other systems.
Return to the use case diagram and double click on the use case "Design a Part in Stages" to view
an example of a state machine diagram.
This is another view of the part design process described by the activity diagram. Typically, you
would not use both an activity diagram and a state machine diagram to describe a process: You
would use one or the other. We included both representations to provide an example of each. The
nodes of the diagram are states in which the system can be in and the connections denote events
which cause the system to transition from one state to another.
5.2.13
Explore Structure
8/22/2012
P a g e | 102
The intended reader of this model is a student who has been newly assigned to be the systems
engineer on this year's FSAE Team Project. As the comment on the left indicates, the purpose of
this package is to provide the new systems engineer with a basic model detailing the structure of
a generic racecar. This would be a starting point for customizing the model to represent this
year's car design. The block ARGXX Car is the high level representation of the generic vehicle.
It has three diagrams associated with it, a block definition diagram, an internal block diagram,
and a parametric diagram. We will consider the parametric diagram in the next step of this
tutorial. For now, we concentrate on the block diagrams.
Double-click on the ARGXX Car block and, in the pop-up window, select the Block definition
diagram that is attached to it. Click OK.
8/22/2012
P a g e | 103
The block definition diagram that results shows that the vehicle is composed of eleven major
subsystems.
Many of these subsystems are further detailed by block definition diagrams to reveal major
components in the subsystems. You can explore these diagrams on your own, after the tutorial is
completed.
Note that the block ARGXX Car also appears on this diagram. Double-click on it again and
select the Internal block diagram that is attached to it. Click OK.
8/22/2012
P a g e | 104
This calls up an internal block diagram in which the basic relationships between the subsystems
are described.
Note that we are using the internal block diagram to represent a context diagram in which
relationships are given by verb phrases on the arcs. We read for example that "the Flow
8/22/2012
P a g e | 105
subsystem provides turbocharged air/fuel flow to the Engine." This should help to orient the
incoming systems engineer to the roles of the subsystems.
5.2.14
Observe that the ARGXX Car block has a value property called CarWeight with a current value
of "TBD" meaning "To Be Determined." Each of the subsystems also have value properties that
represent their respective weights. The weight of the vehicle is simply the sum of the weights of
its subsystems. That is an example of a parametric relationship. That relationship is represented
in this SysML model using a parametric diagram. To view the diagram, double-click on the
ARGXX Car block and, in the resulting pop-up window, select the Parametric diagram choice
and click OK.
The parametric diagram attached to the ARGXX Car block displays the value property for
CarWeight in the top right of the diagram. The value properties for the weights of the subsystems
are listed down the left side of the diagram.
8/22/2012
P a g e | 106
The diagram uses the "add" constraint block that is defined in the Modelica Elementary Library
which was introduced in the tutorial on "Simple Parametric." That constraint block was defined
for only two summands. It would be nice to have a constraint block for eleven summands, but we
are keeping the library simple intentionally. As a result, this diagram is rather complicated as we
build up the sum of eleven summands using pairwise addition. Note that we have introduced
value properties for the intermediate subtotals of the calculation. We found that if we connected
the sum port of one constraint block directly to a summand port of the next constraint block, the
SysML model was ill-defined. Introducing the subtotal value properties solved this difficulty.
For many of the subsystems there are parametric diagrams describing how their weights are
related to the weights of their components. You can explore these additional diagrams on your
own.
5.2.15
We wish to solve for the CarWeight value property based on the weights of the subsystems and
the components. There are quite a few parametric diagrams involved but we have taken care to
ensure they are all consistent. We will use the SysML2Modelica plug-in and the OpenModelica
solver to solve the problem.
8/22/2012
P a g e | 107
Click the Next button until you get to the Graph View page. Click the "Create and Show Graph" button.
Ignore the errors by clicking OK. There are some value properties in the model that are not part
of any parametric diagram.
The flattened graph is displayed. This is the combined set of relationships from all of the
parametric diagrams in the model.
8/22/2012
P a g e | 108
Click Next until you reach the Modelica Simulation page. Then click the "Execute Script" button
and wait for the solver to complete its processing. When it is completed, the solution should
appear in the text box below.
8/22/2012
P a g e | 109
Observe that the vehicle weight has been calculated to be 507 pounds.
Click the "Finish" button to terminate the wizard and this tutorial. In the next tutorial, we will
demonstrate how to generate a report from this model.
8/22/2012
P a g e | 110
8/22/2012
P a g e | 111
6.1
In order to successfully generate a report for the FSAE Racecar model, you may have to make a
few adjustments to the model. This tutorial goes through a step that may be necessary.
6.1.1
Re-Apply ATMProfile
In general, document scripts can be run at any time. However, for the FSAERacecar example, we
have discovered a problem in the downloading of this model that may prevent the script from
running. Fortunately, it is easily corrected and, once made, this step does not have to be
performed again. [Do not perform this step unless you experience errors in document
generation.]
Using the Navigator, double-click on the file ATMConcept.sysmldi to open it.
8/22/2012
P a g e | 112
In the Outline panel, select top line (<Model> FSAERacecar), right-click it, and select "Unapply
Profile."
8/22/2012
P a g e | 113
In the Choices panel of the resulting dialog, select "FSAEProfile", click Add, and then click OK.
8/22/2012
P a g e | 114
This completes the Unapply step. We now wish to reapply the same profile to the model. From
the Outline panel, select the top line (<Model> FSAERacecar), right-click it, and select "Apply
Profile."
In the Choices panel of the resulting dialog, select "FSAEProfile", click Add and click OK.
8/22/2012
P a g e | 115
This has modified the FSAERacecar model. The diagram editor should show an asterisk ('*') on
the tab to indicate that there are unsaved changes to the model. Click the diskette button to save
the changes.
When the changes have been saved, the asterisk should disappear.
The FSAEProfile should now be applied to the model correctly. Profiles and stereotypes are the
topic of a future tutorial.
8/22/2012
P a g e | 116
6.2.1
8/22/2012
P a g e | 117
This is Microsoft Word 2007 format document that contains both formatted content and scripts
to extract SysML content. We will explore this file as part of the tutorial. First, however, we will
simply use the file to generate a report.
Right-click the template file and select "Generate Document".
8/22/2012
P a g e | 118
If there are errors from this process, make sure you have downloaded and installed the current
version of FSAERacecarExport.zip from the website. Otherwise, if the process completed
successfully, the following message should appear.
8/22/2012
P a g e | 119
This indicates that a generated document has been stored in the sub-folder called "Generated." If
that folder did not exist, it would have been created but it may not be visible yet in the Navigator
panel. If it is not visible, then right-click on the project folder "FSAERacecar" and select
"Refresh".
Now the folder, "Generated", and generated document, "FSAERacecar.docx", should be visible.
8/22/2012
P a g e | 120
In general, document generation is a one-step process once you have a valid template file for
your SysML model. Any time your model changes, you can easily re-generate the document to
reflect the changes.
In the tutorial steps to follow, we will explore the generated document and the template file and
show how to make some changes to each.
6.2.2
6.2.3
This should launch a version of Microsoft Word as a tab in the editor window. Scroll down to the
table of contents section.
The table of contents needs to be updated with the SysML content that the generation process has
included. To update the table contents, right-click anywhere in the table and select the "Update
Table..." option.
8/22/2012
P a g e | 121
When presented with the choice of updating page numbers or the whole table, select "Update
entire table" and click OK.
6.2.4
From here, you can now scroll through the document. You will recognize the content of the
report as being extracted phrases and diagrams from the SysML model. You will also note that
only a subset of the diagrams in the model are included in the document. That is because we felt
that some of the diagrams were not relevant or were too detailed for this report. The point is that
we have control over what appears in a final document. We are free to allow the model itself to
include more information than would be appropriate in any report.
Scroll down to approximately page 3, where you will find the section entitled "Systems
Engineering Team Lead."
8/22/2012
P a g e | 122
This is a typical page in the report. It contains a header and a footer, a section heading, and a
displayed figure. It is atypical for this report in that it also includes a block of formatted text (rich
text). Can you spot which of these items came from the SysML model and which were present in
the original template document? When we explore the template file that was used to generate this
document we will see the distinction more clearly.
6.2.5
Suppose we were unhappy with the way this document appears. We will need to make changes
to either the SysML model or the template file in order to improve the document. Suppose we
give ourselves the following tasks:
1. Change the heading of the current page (currently called "Systems Engineering Team Lead") to
something more meaningful.
2. Add an appendix containing the diagram of the SysML Student Viewpoint.
8/22/2012
P a g e | 123
These tasks will give focus to our exploration of the template file.
6.2.6
The template file will be opened using Microsoft Word within the document editor window of
Topcased. (Some students have reported getting a file conversion error message at this point
based on their version of MS Word. Ignoring the error --clicking OK-- worked for them except
that pagination and diagram sizes were different with their version of MS Word than what is
displayed in this tutorial.) The template file consists of formatted content such as headers,
footers, Executive Summary, and table of contents, as well as scripts that describe what content
to extract from the SysML model and how to format it. When the document generation process is
applied (as shown in a previous tutorial step), the scripts are replaced with content from the
SysML model and the resulting document is saved as a new file.
Scroll down to below the table of contents.
8/22/2012
P a g e | 124
You may ignore the error messages in the table of contents. A previous tutorial step showed how
to update the table of contents in the generated document. The tag <config> marks the beginning
of a script element that will be executed during document generation. The tag </config> marks
the end of that script element. Within the <config> and </config> tags there are three
configuration elements. The first sets the parameter key "project" equal to the location of the
project FSAERacecar. The second sets the parameter key "model" to the location of the model
file "FSAERacecar.sysml". Once a parameter key has been set, it can be used in subsequent
scripting statements using the notation ${parameter key}. For example, the location of the model
is specified relative to the location of the project: ${project}\Models\FSAERacecar.sysml. The
third configuration element specifies the output path. It is here that we are telling the document
generator to store the output file as "FSAERacecar.docx" in a folder called "Generated" within
the folder designated by the "project" parameter key. You may notice that a parameter key called
"workspace_loc" is used in the first configuration element but it has not been set. That is because
it is a pre-defined parameter key.
The configuration element must be located near the beginning of the document, or at least before
any other script elements are found.
6.2.7
After this configuration element, you will find blocks of scripting elements each beginning with
a <context> element. In this example, each of these blocks is used to generate a separate section
in the generated document. We will examine one of these blocks in detail. Scroll or search for
the <context> block that contains the phrase "/Systems Engineering Team Lead'". It should be on
the first page.
The context element begins with the partial tag "<context" and ends with the closing "/>". This
element identifies the SysML model element that is the reference point for the script to follow.
Each new context element changes the reference point in the model. The script that follows
8/22/2012
P a g e | 125
begins with the tag "<gendoc>". On the next page you will find the matching tag </gendoc>
indicating where the script ends. That script operates on the reference element identified by the
context element. The address of the reference element is given as
"FSAERaceCar/FSAERaceCar/Systems Engineering Team Lead". To see how this address
works, go back to the SysML model (click the editor tab for FSAERacecar.sysmldi) and expand
the outline panel to see the following:
That is, the context element has identified the Systems Engineering Team Lead package in our
SysML model. That is now the reference point for the following script.
6.2.8
Continuing from the <context> element and the beginning of the <gendoc> element, scroll to the
next page.
Keep in mind that this content is inside the <gendoc></gendoc> pair of tags. In this region, any
items within square bracket pairs ("[" with matching "/]") will be extracted from the SysML
model. For example, the heading will be replaced by the content of "self.name" where self is the
reference point specified in the most recent context element. In this case, the most recent context
element is the Systems Engineering Team Lead package. So, self.name will be replaced by the
name of the package, which is currently "Systems Engineering Team Lead". The text formatting
in MS Word is carried over to the new content. Consequently, since "[self.name/]" is in the MS
Word Heading 1 style, the generated document will have the phrase "Systems Engineering Team
Lead" in a heading level 1 style (Bold, blue, left-justified, with a page break). Similarly, in the
next line, the square brackets contain the item self.GetDiagram(). This will be replaced by the
string address of the first diagram attached to the Systems Engineering Team Lead package. This
address is used by the image script element to insert the corresponding model diagram into the
generated report.
There is also an 'if' statement that checks to see that a diagram actually exists for this element.
8/22/2012
P a g e | 126
Here you can see the end of the image element ("</image>"). What you cannot see is that the
image element contains a Microsoft Word frame. The document generation program will place
the image identified by the image element into this frame.
After the image element, the 'if' statement is concluded using an 'else' clause to print an error
message if the diagram was missing.
One other script element that is visible here is the reference to self.getDocumentation(). This will
be replaced by the documentation attached to the Systems Engineering Team Lead package. This
content is surrounded by the <richText></richText> pair of tags indicating that it needs to be
converted from rich text format into MS Word formatted text.
You can also see the </gendoc> tag which marks the end of this script block.
6.2.9
The problem is that the script is displaying the name of the Systems Engineering Team Lead
package when we really want the name of the diagram associated with the package. Instead of
the model element self.name, therefore, we should be using the element
self.getFirstDiagram().name. We are not going to describe all the possible ways to reference
model elements in this tutorial (visit the Topcased website for more advanced tutorials on
Gendoc2). It is enough for now that you see how the scripts operate. Change the heading on the
current page to the following:
8/22/2012
P a g e | 127
After this change, the tab on the editor window shows an asterisk ("*") indicating that there are
unsaved changes. Save the template file by clicking the diskette button.
Do not attempt to generate a document from this file yet because there is a small change required
in the model file before our task is complete.
6.2.10
Return to the editor tab containing the SysML model (FSAERacecar.sysmldi). In the outline
panel, navigate to the Systems Engineering Team Lead package and expand it (by clicking on the
triangle-shaped handle):
Scroll down the outline view until you locate the block definition diagram diagram that is owned
by the Systems Engineering Team Lead package.
8/22/2012
P a g e | 128
You can see that the name of this diagram is "Systems Engineering Team Lead". This is the
same name as the package. So, in the template, our reference to self.getFirstDiagram().name will
still end up generating the uninteresting heading "Systems Engineering Team Lead."
Let's change the name of the diagram. Double-click on the element "Block definition diagram
Systems Engineering Team Lead" in the Outline panel and activate the Properties panel.
Select the Model tab and then change the name of the diagram to "Orientation for Incoming
FSAE Systems Engineer".
Note that the Outline has changed to reflect the new name. (You may have to click on another
panel outside of the Properties panel to force the panel to refresh.)
8/22/2012
P a g e | 129
Now, repeat the step of generating a document from the template file (that is, in the Navigator,
right-click the template file and select "Generate Document"). Locate and open the resulting
document "FSAERacecar.docx" (you may have to close a previously opened copy first). Scroll
to the page containing the block definition diagram and verify that the heading has changed:
6.2.11
The template script will need to know the address of the model element that owns this diagram
so let's begin by finding the address.
Activate the editor tab for the FSAERacecar.sysmldi model. In the Outline panel, navigate to the
package "SysML Student." This is the element which owns the viewpoint diagram we want.
To add an appendix to the generated document, we simply need to copy a working script that is
similar to what we need and paste it at the end of the template document. We will then (in the
next step) change the address in the context element to refer to model element containing
the SysML Student viewpoint diagram.
Open or activate the template file (FSAERacecarTemplate.docx).
8/22/2012
P a g e | 130
In the editor window (MS Word) scroll down to the end of the template document and then scroll
up to the last context element. This element contains the phrase "Drivetrain."
Place your cursor to the left of the <context> tag and select everything from this point to the end
of the document. Make sure your selection includes the closing </gendoc> tag.
Copy this selection to the clipboard (key combination <Ctrl>C or menu Clipboard->Copy).
Position your cursor at the end of the document. Hit the <enter> key so that your cursor is now
on the line below the closing </gendoc> tag.
8/22/2012
P a g e | 131
After pasting a copy of a working script to the end of the document, scroll up to the context
element (the last context element in the document). Change it from this:
to this:
(You will recall that we determined this address by locating the package "SysML Student" in the
Outline of the SysML model.)
Make one more change: add the prefix "Appendix: " to the heading in the gendoc script block
below this context statement.
8/22/2012
P a g e | 132
Now, generate a document from this template file and verify that the final page looks like this:
You could now take the template file and adapt it to other models by adding or deleting script
blocks and changing the addresses of model elements. There are many more things that can be
performed within the scripting language but this basic introduction should be enough to get you
started. The Topcased website has further tutorials on the GenDoc2 scripting language, but check
to make sure you use only those features compatible with Topcased 4.3, the version we are using
for these tutorials.
6.2.14
Some students report an error during document generation with the message "The model Model
can not be loaded from URL..."
8/22/2012
P a g e | 133
8/22/2012
P a g e | 134
8/22/2012
P a g e | 135
7.1
7.1.1
At the beginning of this tutorial, your workspace will look something like the following:
In this step, we will create a new project within our workspace. Begin by selecting File->New>Project... from the menu system.
8/22/2012
P a g e | 136
In the resulting dialog box, select the wizard that will create a Topcased project and click Next.
8/22/2012
P a g e | 137
7.1.2
8/22/2012
P a g e | 138
Observe that two files are created by the wizard. The file "ToyCatapultModel.sysml" will contain
model elements. The file "ToyCatapultModel.sysmldi" will contain graphical information (size,
location, and color of displayed elements) for the diagrams. Note that the model is separate from
the diagrams.
8/22/2012
P a g e | 139
At this point, there is basically only one model element (a package called "ToyCatapultModel")
and one diagram.
7.1.3
In the diagram editor window, select the "Package" object from the palette and then click once
anywhere in the diagram area. A graphical element representing a package will be added.
8/22/2012
P a g e | 140
In the Properties tab, make sure the "Model" option is highlighted and then change the name
from "Package1" to "Requirements." (You will need to click outside the Properties panel to force
the panel to refresh and display the new name.)
Observe in the Outline panel that we now have a new model element, package "Requirements",
nested within the package called "ToyCatapultModel". All model elements are listed as
belonging to (nested within) some other model element except the root element (the Model
element).
8/22/2012
P a g e | 141
In diagramming tools such as MS Visio, the focus is on creating diagrams. The diagram elements
in such tools have limited usefulness. SysML, on the other hand, is primarily a database in which
diagrams are used to create and display elements in the database. In the tutorial on exploring the
FSAE Racecar model, we attempted to emphasize the concept that "the model is not the
diagram." The purpose of this step is to make that distinction clear. To do so, we will delete the
package we just created from the diagram but not delete it from the model. It is sometimes useful
to delete objects from diagrams because they may clutter the view and so obscure what you are
trying to convey. You may not want to delete the object from the model because you may want
to display the object on a different diagram.
Right-click the package graphical element in the diagram window and select "Delete from
Diagram." Note that one of the other choices, which we do NOT select, is to completely delete
the element from both the model and the diagram ("Delete from Model" ).
8/22/2012
P a g e | 142
Notice in the Outline panel that the package called Requirements is still there. In fact, you can
drag and drop the package onto the diagram to restore it.
The package, Requirements, should now appear on the diagram. Any special formatting (size and
color) has been lost but the other properties have been retained. This is to emphasize that "the
diagram is not the model." The Outline view is a listing of all the model elements. The diagrams
may or may not contain representations of every model element. Also, the same model element
can appear on more than one diagram but it can exist only once in the model.
In the tab of the diagram window, note that an asterisk appears, warning you that there are
unsaved changes to the model. Click the diskette button to save the file.
8/22/2012
P a g e | 143
Periodically, in these tutorials, we will remind you to save your file but you should remember, in
any case, to save your file frequently.
7.1.5
In this step, we demonstrate how to add model elements without using the diagram editor. Begin
by selecting the top level package "ToyCatapultModel" in the Outline panel.
Right-click this package and select Create child->Nested Package->Package from the pop-up
menu.
8/22/2012
P a g e | 144
A package called "Package1" is created within the package we had selected. It is called a child
element.
Use the properties tab to change the name of this new package to "Structure."
8/22/2012
P a g e | 145
If you wish this new element to appear on a diagram, simply drag and drop it onto the diagram.
Note however, that there are rules, which Topcased enforces, about which elements are
appropriate on which diagram types.
Next, using your favorite method, add a package called "Behavior" to the diagram. You should
have three packages now, as shown:
In the Outline panel, observe the three packages as model elements belonging to (children of) the
Package "ToyCatapultModel".
8/22/2012
P a g e | 146
In this step, we will improve the appearance of our three graphical elements. Select all three
packages (for multiple selection, hold down the <ctrl> key when selecting or simply drag a
selection box around the elements):
With the group of elements selected, activate the Graphics section of the Properties tab. Then,
enter the desired width and height of the graphical elements. Be sure to press the <enter> key
after each entry to record the change.
Activate the diagram window (click on the editor tab) and then click the "Align Middle" button
in the tool bar to improve the horizontal alignment of the graphical elements. You can
experiment with the other buttons on this toolbar to learn their function. (Sorry, but there does
not seem to be a "snap to grid" or a "space evenly" button if you are looking for one.)
8/22/2012
P a g e | 147
You are free to edit other graphical features of these elements (such as color, font, etc.) but keep
in mind that such features are not generic to SysML. Different vendors of SysML products will
provide different graphical capabilities.
7.1.7
Thinking ahead, I anticipate that we will create quite a few requirements. Let's create packages to
organize them and use a diagram to reveal this organization.
Double-click the package "Requirements" in the diagram editor window. This will result in a
dialog asking you what type of diagram to create. Select "Requirement diagram" and click OK.
8/22/2012
P a g e | 148
Note that this results in a diagram, called Requirements, to be added to the model as a child of
the Package "Requirements." You can see that the default name of the diagram was chosen from
the name of the parent package. You can change the diagram name in the Properties tab.
Next, select the Package object in the diagram palette and hold down the <ctrl> key as you click
three times in succession in the diagram window. This will create three packages. However, the
cursor will remain in "auto-addition" mode until you click the select tool in the palette.
8/22/2012
P a g e | 149
If you accidentally create too many packages, select the extra ones, right-click and choose
"Delete from Model."
Use the Properties tab to rename the packages as "Mission and Success Factors," "Functional
Requirements," and "Non-functional Requirements." Improve their appearance with changes to
the graphical elements as shown in a previous step.
Keep an eye on the Outline panel to see how your model is expanding. There are now three child
packages to the Requirements package.
8/22/2012
P a g e | 150
As a final step in this tutorial, we will create a mission statement for this project. In the Outline
panel, right-click the package "Mission and Success Factors" and select Add diagram>Requirements diagram. This is a second way of adding diagrams (the first was to double-click
the graphical element).
8/22/2012
P a g e | 151
In the resulting diagram editor window, select the Requirement object in the palette and click
anywhere in the diagram window. This adds a requirement element to the model and a
corresponding graphical element to the diagram.
Change the name of the requirement and type some suitable text to represent the mission
statement of this project.
Observe where the requirement model element has been added to the model. It is a child of the
package "Mission and Success Factors."
8/22/2012
P a g e | 152
8/22/2012
P a g e | 153
7.2.1
A model profile contains changes to the modeling language that can be applied within a model.
You may be asked, for example, to create a profile that customizes SysML to the design
practices and conventions of your company. Let's suppose our company has asked to us to make
sure that the language supports mission statements.
The first step (after saving changes to our project from previous steps) is to create a
profile. Right-click the Models folder of the ToyCatapult project and select New->SysML Model
with Topcased from the pop-up menu.
8/22/2012
P a g e | 154
In the resulting dialog, enter the name ToyCatapultProfile and be sure to select "From Template
Model" with template "Profile Template." Click Finish.
8/22/2012
P a g e | 155
A profile model has only one type of diagram: a profile diagram. In this diagram you relate
newly created stereotypes with existing stereotypes and metaclasses.
Select the Metaclasss object in the diagram editors palette and click anywhere in the diagram to
add a metaclass.
Next, we need to select which existing object type will be used for the metaclass. We think the
closest object in SysML to a Mission Statement is a Requirement, so we will identify our
metaclass with the Requirement class. In the Properties tab, activate the Model section and click
on the "..." button to select a metaclass.
8/22/2012
P a g e | 156
There are quite a few metaclasses to choose from, both from UML and SysML. To narrow the
search, click on the option "Show qualified name" and type "sysml" into the Search string. A list
of sysml objects should appear. Select the Requirement object and click OK.
8/22/2012
P a g e | 157
7.2.3
Select the object Stereotype from the palette of the diagram window. Click anywhere in the
profile diagram to create a stereotype.
Use the Properties tab to change the name of the stereotype to "Mission". You could also name it
"Mission Statement" if you prefer.
8/22/2012
P a g e | 158
Select the Extension connector from the Connections palette and click once on the stereotype and
once on the metaclass. We read the resulting relationship as "The Mission stereotype is an
extension of the Requirement metaclass."
One of the powerful features of stereotypes is that they can specify properties. In this way, we
can increase the information that is associated with a model object. Select the Property object in
the palette and then click on the Mission stereotype. This adds a property to the stereotype.
8/22/2012
P a g e | 159
Name the property "Organization." We intend this data element to store the identity of the
organization which owns or exhibits the mission.
With the property selected, click the elipsis ("...") button associated with its type. In the selection
dialog, search for uml::Actor, select it, and click OK.
8/22/2012
P a g e | 160
We have now created a stereotype of the Requirement class, called "Mission" that possesses a
property of type Actor, called "Organization."
7.2.4
The final step before closing the profile model is to run a process to complete its definition.
Right-click the profile "ToyCatapultProfile" in the Outline panel and select Define Profile.
8/22/2012
P a g e | 161
Save your file. You may be asked to define the profile again. If so, respond in the affirmative.
You may now close the profile by clicking the "X" on its tab in the diagram editor window.
7.2.5
Now that the profile has been created, we need to load it into the ToyCatapultModel model.
Open the model ToyCatapultModel (double-click ToyCatapultModel.sysmldi in the Navigator).
In the Outline panel, right-click the top level Model element and select Load Resource... from
the pop-up menu.
8/22/2012
P a g e | 162
8/22/2012
P a g e | 163
8/22/2012
P a g e | 164
(Some students have reported that the profile did not show up under "Additional Resources" in
their workspace but that the rest of the tutorial steps worked in spite of that. We suspect that they
had not cleared the filter from the Outline view: recall an earlier tutorial had shown how to hide
edges in the Outline view using a filter.)
7.2.6
In this step we will apply our newly loaded profile to the top level model element. In the Outline
panel, select the top level Model element, right-click it, and select Apply Profile.
8/22/2012
P a g e | 165
In the resulting dialog, select the ToyCatapultProfile from the list of choices on the left and click
the Add button to add the profile. Click OK to confirm your choice.
The profile is now added at the model level. It is now available in every nested package within
the model. It is possible to add profiles to specific packages but we have chosen to add it at the
highest level.
7.2.7
Apply Stereotype
In this step, we will apply the stereotype we created. Navigate to the requirement we created to
represent the mission statement of our toy catapult project. It is in the Mission and Success
Factors package. (Note, you could use the diagram editor or the Outline view to locate it.)
8/22/2012
P a g e | 166
In the Outline panel, right-click on this requirement and select Apply Stereotype from the pop-up
menu.
We have only one stereotype in our profile so the list of choices of stereotypes to apply has only
one element. Select the Mission stereotype from the choices list, click Add, and then click OK to
confirm the Apply Stereotype action.
The stereotype has now been applied. The Mission Statement that we created in an earlier step is
now a stereotype of type "Mission".
8/22/2012
P a g e | 167
Recall that we created the stereotype property "Organization" to designate who owns the mission
being represented. In the case of the toy catapult project, that would be me, the grandfatherbuilder who wants to build the toy cataput. So we need to add an actor to the model to represent
the builder and then identify that actor as the organization owning the mission statement. The
remaining steps of the tutorial accomplish that.
7.2.8
Navigate to the diagram containing the Structure package and double-click it. Select the Block
definition diagram as the diagram you would like to create and click OK.
In the resulting block definition diagram, select the Package object from the palette and click
anywhere in the diagram to create a package. Name the package "Context." We will likely have
several more packages within this Structure package as we conduct the concept analysis.
8/22/2012
P a g e | 168
In the Context diagram, add an actor and name it "Builder," or "Owner-Builder," as you prefer.
8/22/2012
P a g e | 169
7.2.9
Navigate back to the Mission and Success Factors package and select the Mission Statement. In
the Properties tab, activate the section called Stereotype Attributes. There you will see the
Organization property that belongs to Mission objects. Click the ellipsis ("...") button to select an
Organization.
The selection list that appears in the dialog shows us all the model elements that could be used in
this context. Since the Organization property can be filled only by an actor and since we have
created only one actor in our model, the list consists of just actor Builder that we just created.
Select it and click OK.
8/22/2012
P a g e | 170
We have successfully applied a Mission stereotype within our model and mapped its
organization property to the Builder actor of our model.
It is possible to make changes to profiles after you have created them but those changes do not
automatically propagate to the model elements that have stereotypes applied to them. You will
have to un-apply the profile from the model (or package) and then re-apply the profile.
8/22/2012
P a g e | 171
Unfortunately, you will then have to re-apply the stereotypes to the model elements one by one. I
have not found a way to avoid this yet. So, design your profiles carefully.
8/22/2012
P a g e | 172
In this tutorial, we create a context diagram to represent the context (or environment) of the toy catapult
system. We purposely start with a very simple context. In subsequent tutorials we show how this grows
naturally in complexity as we consider different use cases.
7.3.1
In a previous tutorial, we created a block definition diagram within the Context package of the
Toy Catapult model. We added a single actor to that diagram and called it the Builder to
represent the designer-builder of the toy catapult. Navigate to that diagram.
8/22/2012
P a g e | 173
Using the Actor and Block objects on the diagram palette, create two additional actors and three
blocks. Name the new actors "Parent" and "Child" and name the blocks "Toy Context," "Toy
Catapult System," and "Projectile."
7.3.2
In the Connections section of the palette, open the list of Associations and select Association
(Composite).
8/22/2012
P a g e | 174
Hold down the <ctrl> key as you add connections from the Toy Context to each of the other
entities (5 connections in total). When you have finished, click the Select option in the palette to
turn off the addition of further connections.
The result is unattractive but subsequent steps will improve the appearance.
8/22/2012
P a g e | 175
Format Associations
Select all of the connections in this diagram by holding down the <ctrl> key as you select each
connection in turn.
With all of the connections selected, open the Graphics section of the Properties tab and select
"Rectilinear" from the combination box associated with the Router.
Next, select all of the visible elements and click "Hide." A rapid way to select all elements is to
select the first in the list and then hold down the <shift> key as you select the last element in the
list.
8/22/2012
P a g e | 176
Now all of the elements should appear in the "Hidden Elements" list.
This improves the appearance of the diagram but routing of the connections is odd.
By dragging different segments of the connections, you can improve the appearance of the
routings. We suggest the following rearrangement:
8/22/2012
P a g e | 177
In words, this diagram says that the Toy Context is composed of three actors (the Builder,
Parent, and Child) and two blocks (the Toy Catapult System and the Projectile).
Keep looking at the Outline panel to see how your model is growing and where the model
elements are being stored.
The actors, blocks, and associations we have created are all model elements in the package
"Context." The diagram is separate but is shown as a child of the package "Context" as well. The
names of the associations were auto-generated as we created them. You could change those
names using the Properties tab if you wanted named associations in your model.
8/22/2012
P a g e | 178
In the block definition diagram called "Context," double-click on the Toy Context block. If there
is no diagram attached to a block, this is the signal that you want to create one. A diagram
creation dialog box will appear. Select an Internal Block Diagram as the type of diagram you
would like to create. We will take advantage of the fact that the Toy Context block has a number
of other blocks associated with it by clicking "Initialize the diagram with existing model
objects." In general, it is safer to leave this option unchecked. Click OK.
An internal block diagram will be created and a number of parts will be added automatically: one
for each object that is associated with the Toy Context block. No part is added for the Toy
Context block (since a block cannot be a part of itself).
Drag these parts into a more pleasing layout. It is natural to place the system of interest (the toy
Catapult System) at the center of the diagram.
8/22/2012
P a g e | 179
In the Outline panel, note how the model has changed. The Toy Context now has a number of
parts (classed as "Property"). The name of the part is derived from the name of the block by
changing the first character to lower case. Thus, the Context includes at least one part of type
Projectile. This part will be known as "projectile." This is a useful convention but not required.
We will attempt to follow this convention by using leading upper case characters to describe
blocks and leading lower case characters when parts (components, subsystems, etc.) are typed.
7.3.5
Internal block diagrams allow only a limited number of connector types. Select the Connector
type from the diagram palette.
8/22/2012
P a g e | 180
Hold down the <ctrl> key as you connect the different parts together as shown below. Click the
select tool in the palette when you are finished adding connections. Note that we have moved the
location of the projectile to improve the layout.
One by one, select each connector in turn and edit its name in the Properties tab.
Name the connections something like shown below and drag the naming labels to be close to the
subject of the sentence implied by the connection. For example, because the label "selects" is
close to the part "child," we would read the connection as "the child selects the projectile."
Similarly, "the parent demonstrates use of the toy Catapult System" describes another
connection. The connections are symmetric. For example, we could have named the connection
between the projectile and the toy Catapult System by "throws." In that case, we would position
8/22/2012
P a g e | 181
the label closer to the toy Catapult System part than to the projectile part. The connection would
then be read as "the toy Catapult System throws the projectile."
Use the Comment palette item to add a comment to your diagram. We have added a comment to
the effect that the projectile is currently viewed as being outside of the toy Catapult System. We
remind ourselves that we may want to revisit that decision at a later stage of design.
8/22/2012
P a g e | 182
It is a useful technique in concept analysis to identify the diverse ways in which a system might
be used. Think of this as part of a discovery process: what do these use cases teach us about
system requirements? Use cases can also be thought of as protoytpes for customer acceptance
tests. That is, if our system cannot pass these basic tests, it will likely be rejected by our target
customer. In this tutorial, we brainstorm a variety of use cases for the toy catapult.
7.4.1
From the high-level diagram of the Toy Catapult Model, double-click the behavior package we
created earlier. A diagram creation dialog should appear. Select the Use Case diagram as the type
of diagram to create. Uncheck the "Initialize" option and click OK.
8/22/2012
P a g e | 183
7.4.2
The use cases will employ actors that we created in the model earlier. In the Outline panel, locate
the actors Child and Parent (in the Context package), and drag them one at a time into the Use
Case Diagram that was created in the previous step.
8/22/2012
P a g e | 184
Observe that the model elements Child and Parent appear in the diagram with the label "(from
Context)" which points to the package which owns these elements in the model.
Select the Use Case object from the diagram palette and add two use cases to the diagram.
Change their names as shown below using the Properties tab.
7.4.3
Add Associations
Connect the Child actor to the Child Plays With Toy use case using an Association connection
from the palette. Use the graphics section of the properties tab to hide all graphical elements.
Similarly, add an association between the Parent actor and the Parent Entertains Child With Toy
use case. Finally, add a generalization connection from the Parent Entertains Child With Toy use
case to the Child Plays With Toy use case.
8/22/2012
P a g e | 185
By adding the generalization connection, we are saying that the Parent Entertains Child With
Toy use case is a special case of the Child Plays With Toy use case. Since the Child is associated
with the Child Plays With Toy use case, we may infer that the Child is also associated with the
Parent Entertains Child With Toy use case. That is, the latter use case (Parent Entertains Child
With Toy) inherits the associations of the more general use case (Child Plays With Toy).
7.4.4
Use cases are also an opportunity to consider negative possibilities such as accidental or
malicious use of the system of interest. We refer to these as secondary use cases because they
describe use of the system in ways that were not intended. The primary use cases are the
intended uses. Such secondary use cases may surface as the result of team brainstorming
activities or during design reviews with potential customers. Consideration of these use cases
will likely result in numerous requirements of a defensive nature. Add a few such secondary
cases to your diagram as shown below.
8/22/2012
P a g e | 186
8/22/2012
P a g e | 187
In this tutorial, we take one of the use cases identified earlier and develop a behavior to describe it. We
choose an activity diagram with swimlanes as our diagramming tool.
7.5.1
Double-click the use case "Child Plays With Toy" and select Activity Diagram in the resulting
dialog box. Leave the box "Initialize..." unchecked and click OK.
8/22/2012
P a g e | 188
In the activity diagram, select the object Activity Partition from the palette and create three
partitions in the diagram. The easiest way is to hold down the <ctrl> key as you click three times
in the diagram and then click the Select tool from the palette to return to selection mode.
Select the first partition ("ActivityPartition1") and change its name to "child" in the Model
section of the Property tab. While you are there, click the ellipsis button ("...") associated with
the "Represents" property. This will launch a dialog box allowing you to select an object that the
partition will represent. The list of possibilities is quite long, so type "child" into the Search box
to narrow the list. Select the object "<Actor> Child" from the list and click OK.
8/22/2012
P a g e | 189
In similar fashion, name the other partitions and connect them to related objects in your model
("toy Catapult System" to Toy Catapult System and "projectile" to Projectile).
These are the swimlanes for our description of behavior. As we add actions to the diagram you
may have to adjust the size of these partitions to accommodate all the actions. That can be done
by selecting the partition and dragging the handle at the bottom of the partition.
7.5.3
Since a use case behavior is like a test procedure (think of it as a customer acceptance test), it is a
good practice to identify the starting conditions for the test. Select the Constraint object from the
Comment section of the palette and add a constraint to the diagram. To visually connect it with
the behavior, size it to fit across the swimlanes at the top of the diagram.
8/22/2012
P a g e | 190
In the Specification section of the Properties tab, click the Create button, select Literal String
from the resulting dialog and click OK.
8/22/2012
P a g e | 191
A Value box should become available in the Specification Detail group. Enter the assumed state
of the system at the beginning of the use case behavior. In our case, we assume that the toy
catapult is unloaded and unarmed for this behavior.
7.5.4
Add Actions
There are many different types of actions which can be represented on an activity diagram. They
can be used to achieve a high level of specificity in terms of how a behavior is described and
implemented. For our purposes, we seek the simplest construct, which is an Opaque Action. The
word "opaque" in SysML is used to mean that the expression has meaning outside of the
language. That is, someone or something outside of the language may be able to translate the
description into a real action. There is no attempt to explain it further within the model.
Select the Opaque Action object within the Action section of the diagram palette. It is part of a
group of actions headed by the Call Behavior Action so you may need to open the group to find
it.
8/22/2012
P a g e | 192
Hold the <ctrl>key down as you add Opaque Actions to the diagram. We will need 10 such
actions. Click the Select tool in the palette to return to selection mode.
Name the actions as shown below, size the graphical elements appropriately and drag them into
the swimlanes in the pattern shown.
8/22/2012
P a g e | 193
7.5.5
Add an Initial Node to the diagram at the top of the Child swimlane and add an Activity Final at
the bottom of the Projectile swimlane.
8/22/2012
P a g e | 194
7.5.6
Connect all the actions into a sequence using Control Flow connections. That is, select the
Control Flow Connection from the palette, hold down the <ctrl> key and click 'from-to"
relationships as shown below. Since there are twelve nodes, there will be eleven connections.
Click the Select tool to return to selection mode.
8/22/2012
P a g e | 195
Select all of the connections on the diagram, change the Router to Rectilinear and hide all of the
visible elements.
Manipulate the segments of the connections until you are satisfied with the appearance of the
diagram.
8/22/2012
P a g e | 196
7.5.7
In a similar fashion to the step in which we added a precondition to the diagram, use the
Constraint object to add a post-condition to the behavior indicating the anticipated ending state.
In general, test procedures should specify both beginning and ending conditions.
This completes our creation of a use case behavior for "Child Plays With Toy."
8/22/2012
P a g e | 197
In this tutorial, we illustrate the principle that system requirements often flow out of a consideration of
use cases. We take the functions that the system performed in the use case behavior and formalize them
into functional requirements for the system.
7.6.1
"Walking the column" refers to the capture of system requirements by reading down the system
swimlane of a use case behavior. When we review the use case behavior for Child Plays With
Toy, we see that there are a number of functions the system must be capable of performing, from
detecting the receptacle in position to ejecting the contents of the receptacle at the end of the
behavior.
8/22/2012
P a g e | 198
7.6.2
8/22/2012
P a g e | 199
7.6.3
Create Requirements
Using the Requirement object from the diagram palette, and by holding down the <ctrl> key,
create five requirements. Click the select tool to return to Selection model.
Select each requirement in turn and edit its name, Id, and text. The Id will be based on a
requirements numbering scheme that you or your organization has established for the design
8/22/2012
P a g e | 200
project. We have chosen to use the nomenclature "OR.x" where OR stands for Originating
Requirement and the "x" is the number of the requirement.
Use these five requirements to formally capture the functional requirements that were captured
by "walking the column."
8/22/2012
P a g e | 201
In this tutorial we illustrate two principles: the first is that our context diagram grows as we
consider more use cases and the second is that we may want to modify the system functional
requirements as we consider additional use cases. In the process of doing this, we illustrate how
to add parts to an internal block diagram.
The use case we are considering is the "Parent Entertains Child With Toy" use case and the story
is that we imagine entertaining the child by having a toy train trigger the toy catapult.
7.7.1
In the use case "Parent Entertains Child With Toy" we imagine aligning the toy catapult with the
toy train so that the train triggers the toy catapult as it passes. This complicated behavior is likely
to be fun for both the parent and the child. Our use case analysis has led to the discovery of
8/22/2012
P a g e | 202
another entity that is in the context of the Toy Catapult System (namely, the toy train), so we
return to the Context package to include it.
In the block definition diagram for the Context package, add a block for the Toy Train and
connect it to the Toy Context block with a Composite Association.
In the internal block diagram attached to the Toy Context block, select the Part object from the
palette and click once in the diagram to add a Part. You will be prompted to select the type of the
part to be added. Scroll through the dropdown list until you locate and select the Toy Train
object.
8/22/2012
P a g e | 203
Change the name of the part to "toy train" (recall our lower case convention for parts).
Add connectors between the parent and the toy train and between the toy train and the toy
Catapult System. Change their names to reflect the nature of the connection. Position the labels
close to the part which forms the subject of the relationship.
8/22/2012
P a g e | 204
In this use case behavior, we assume that the toy catapult is already armed and loaded since that
behavior has already been described in the Child Plays With Toy use case behavior. Here, the
focus is on the interaction with another entity, the toy train. Our convention is to add swimlanes
to the right of the system of interest as we include more external entities. The user swimlane is
placed to the left of the system of interest.
Using the techniques described in the Create Activity Diagram tutorial, create an Activity
Diagram similar to the following, attached to the Parent Entertains Child With Toy use case.
7.7.3
Update Requirements
Consideration of this use case has led to the discovery that we expect to be able to trigger the toy
catapult from a passing toy train. That could easily be overlooked in the design process so we
should make it an explicit system requirement. Return to the list of requirements and modify
OR.4 to include this requirement.
8/22/2012
P a g e | 205
8/22/2012
P a g e | 206
In this tutorial, we demonstrate the mechanics of creating a state machine diagram. This is
another view of behavior that can be useful in summarizing the key features of several use case
behaviors.
We imagine that we have thought through several use case behaviors before creating this
diagram. For example, what happens if the child releases the toy catapult before the receptacle is
secured into position? What happens if the child triggers the release before loading the
receptacle? All of these possibilities can be summarized in the state machine diagram.
7.8.1
In SysML, state machine diagrams cannot be added to use cases but they can be added to blocks.
For this reason, we choose to attach a state machine diagram to the Toy Catapult System block.
8/22/2012
P a g e | 207
Navigate to the block definition diagram attached to the Context package and double-click on the
Toy Catapult System block. Select State Machine Diagram from the list and click OK.
7.8.2
Add States
Select the State object from the palette and add seven states.
8/22/2012
P a g e | 208
Name the states as shown below, sizing and aligning the graphical elements for better
readability.
7.8.3
Add Transitions
Connect the states with External Transition Connections as shown. There should be nine
transitions created.
8/22/2012
P a g e | 209
Change the name of each transition to suggest the event that causes the transition to take place.
For example, when the child applies energy to the toy catapult (pushing the receptacle into
position) the state becomes unstable. That is what the transition from Unloaded,stable, unarmed
to Unloaded, unstable, unarmed is supposed to represent.
Continue until you have a reasonable label for each transition. Note that the stop event is likely
to be simultaneous with the launch event. That is, the projectile will be ejected when the catapult
motion is stopped.
8/22/2012
P a g e | 210
Observe how this state machine summarizes what might have been the subject of several
separate use case behaviors.
8/22/2012
P a g e | 211
8/22/2012
P a g e | 212
8.1
From the Navigator, double-click the profile "ToyCatapultProfile.sysmldi." Since the model file
which uses the profile is still open (from the previous tutorial), the profile editor will launch in
read mode. Click OK to continue.
8/22/2012
P a g e | 213
We want to make changes to the profile, so click the Edit icon on the toolbar.
Since we are editing the profile, the model file will switch to read only mode. Click OK to
continue.
The model file is now in read-only mode while the profile is in edit mode.
8/22/2012
P a g e | 214
From the Object palette, select the Metaclass object and then click once in the diagram area to
add a metaclass.
With the new metaclass selected, click the elipsis button in the Model section of the Properties
tab.
There are quite a few objects to choose from, so type "prop" in the Search box to narrow the
search. Select the <Class> Property and click OK.
8/22/2012
P a g e | 215
Select the Stereotype object in the palette and then click in the diagram once to add a stereotype.
Change the name of the stereotype to "moe."
Select the Extension tool in the Connections palette, and add a connection going from the
stereotype "moe" to the metaclass "Property".
8/22/2012
P a g e | 216
We have now declared "moe" to be a stereotype that extends the class "Property."
8.1.4
You will be prompted with the opportunity to re-define the profile before saving it. Click OK to
launch the Define Profile process.
We are now finished with the profile. Close it by clicking the "X" on its tab in the editor
window.
8/22/2012
P a g e | 217
We now want to resume editing the toy catapult model, so click the edit button on the toolbar.
This will change it from read-only mode to edit mode.
The editor should detect the related profile has changed and prompt you to reload the resource.
Click OK to continue.
Profile changes are not automatically reflected in the model file so we must go through a process
of re-applying the profile to the model. We begin by un-applying the profile. From the Outline
panel, select the Model, ToyCatapultModel, right-click it and select Unapply Profile from the
pop-up menu.
8/22/2012
P a g e | 218
Select the ToyCatapultProfile from the list of choices and click Add (you are "adding" the profile
to the list of features you want to "unapply"). Then click OK to confirm your choice.
Now, right-click the model in the Outline panel again and, this time, select Apply Profile from
the pop-up menu.
If the list of choices is long, enter the search string "toy" in the Pattern box to narrow the list.
Select the ToyCatapultProfile, click Add, and then click OK.
8/22/2012
P a g e | 219
8.1.6
Unfortunately, unapplying the profile caused the model to lose the stereotypes we had previously
applied. We must add them back, one at a time. Navigate to the Mission And Success Factors
package and select the Mission Statement requirement. From the Stereotypes section of the
Properties tab, select the Mission stereotype from the list of available stereotypes, and click the
Add button.
8/22/2012
P a g e | 220
8/22/2012
P a g e | 221
In this tutorial, we create a new package to hold our model of performance analysis for the toy catapult.
Using a top-down approach, we define measures of effectiveness for the customer and user of the toy and
then translate those measures into more specific technical measures of effectiveness that will be
associated with the toy catapult system.
8.2.1
In the Structure package, add a package to the diagram and name it "Performance Analysis."
8/22/2012
P a g e | 222
Double-click the new package and create a block definition diagram attached to it.
8/22/2012
P a g e | 223
Use the Outline panel to locate the blocks "Toy Context" and "Toy Catapult System". Drag each
of these blocks and drop them on the new diagram.
Observe that the Composite association between the two blocks is automatically represented in
the diagram. Select this association and hide its visible elements. Make it Rectilinear as well.
8/22/2012
P a g e | 224
We are finally in a position to add measures of effectiveness to the model. Select the Property
object from the palette and click on the Toy Context block to add a property. Change the name of
the resulting property to "Fun".
With the "Fun" property selected, go the Stereotypes section of the Property tab, select the "moe"
stereotype and click the Add button to add the stereotype. Observe, that the properties editor
presented us with a restricted list of stereotypes: only the stereotypes extending the "Property"
class can be used to modify the Property "Fun."
8/22/2012
P a g e | 225
The property is now displayed with the tag "<<moe>>" signifying the application of the
stereotype "moe." Add another moe called "Cost" to the Toy Context block. Add three moe's to
the Toy Catapult System block:"MaximumLaunchMass," "MaximumLaunchVelocity," and
"SystemCost." Be sure to use names that have no spaces or special characters in them. This is
because these names will likely be used as variable names in a Modelica model.
Note the top-down progression: our analysis of the customer led us to their concern for fun and
cost. However, we need something more specific than "fun" to conduct engineering analysis, so
we have derived measures of effectiveness for projectile mass and launch velocity, thinking that
these will be strongly correlated with the sense of fun for the device.
8.2.4
The nice thing about libraries is that they are modular and reusable. We want to make use of the
library that was created for the FSAE Racecar model, but extend it for our purposes in
performance analysis. We begin by copying the library into the ToyCatapult project.
From the Navigator, locate the FSAERacecar project and select the two files the make up the
ModelicaElementaryLibrary. Right-click the selection and choose Copy from the pop-up menu.
8/22/2012
P a g e | 226
Navigate back to the ToyCatapult project, and right-click on the Models folder. Choose Paste
from the pop-up menu.
8/22/2012
P a g e | 227
Double-click on the ToyCatapultModel.sysmldi file to open the model for editing (if it is not
already open).
From the Outline panel, right-click on the ToyCatapultModel model and choose "Load resource"
from the menu.
8/22/2012
P a g e | 228
We want to load the library model, so click the Browse Workspace button.
Select the diagram file for the ModelicaElementaryLibrary and click OK.
8/22/2012
P a g e | 229
As the library is loaded, the model file may switch to read-only mode. If this happens, click OK
to acknowledge this action but then click the Edit icon in the toolbar to put the model file back
into edit mode.
8/22/2012
P a g e | 230
At this stage, the library file should be in read-only mode and the model file should be in edit
mode.
8.2.5
We may want to use the moe's we created in a Modelica model so we will change each of their
types to Real. For example, select the moe "MaximumLaunchMass" and click the ellipsis button
("...") associated with Type on the Model section of the Properties tab.
8/22/2012
P a g e | 231
Enter the search phrase "real" in the search box to narrow the list of possibilities. Locate the Data
Type "Real" from the list and select it. This Data Type is defined in the
ModelicaElementaryLibrary, so we are about to make use of our personal library. Click OK.
8/22/2012
P a g e | 232
Repeat this process with each of the Toy Catapult System moe's.
Observe that these properties now appear as values. That is, by typing a property, we convert it
from a generic property to a more formal value property.
8/22/2012
P a g e | 233
In this tutorial, we create a number of different concepts for the toy catapult system and select the
Weighted Pendulum concept to develop further. For this concept, we add a number of technical
performance measures that we believe are related to the measures of effectiveness identified earlier.
8.3.1
Performance analysis will depend upon a specific design concept. Systems engineering embraces
techniques to assist in generating design concepts and in selecting the best concept to advance
with. Let us suppose that we have conducted a process of concept generation and concept
selection for the toy catapult system. We can represent the results of that process with a block
definition diagram. In the Performance Analysis package, add five blocks and name them for
five different design concepts: Spring and Piston, Weighted Pendulum, Spring and Catapult,
Piston and Compressed Air, and Cannon and Compressed Air. Connect them to the Toy Catapult
System block using generalization arcs. Format the arcs and arrange the blocks as shown below.
8/22/2012
P a g e | 234
In what follows, we assume that the Weighted Pendulum concept has been selected for further
development. We will conduct performance analysis on this particular design concept.
8.3.2
Having selected the Weighted Pendulum design concept for further development, let's identify
engineering characteristics specific to this design concept that will help us to assess the measures
of effectiveness. The measures of effectiveness are projectile launch velocity, projectile launch
mass, and system cost. We want to develop an analytical model that will relate these quantities to
design parameters and engineering characteristics of a weighted pendulum ("trebuchet")-style
catapult. A simple view of the catapult has the following basic parts: a counterweight, an arm,
the projectile, and the pivot (or fulcrum).
8/22/2012
P a g e | 235
The most expensive component of the catapult is likely to be the counterweight. Consequently,
system cost will be highly correlated with the mass of the counterweight. The launch velocity of
a projectile will also depend on the mass of the counterweight but also on a number of other
engineering characteristics, as labelled in the diagram below. We consider the catapult in two
states: before launch, when the counterweight has been raised to its maximum position, and at
launch when the pendulum is stopped and the projectile released.
We can relate these technical performance measures using a system of equations (making
simplifying assumptions such as frictionless pivots and mass-less arms):
8/22/2012
P a g e | 236
8/22/2012
P a g e | 237
8/22/2012
P a g e | 238
8.3.3
Select the ArmLength property and open the Specification section of the Properties tab. Click the
Create button for the Default Value property.
8/22/2012
P a g e | 239
In the resulting dialog, select "Literal String" for the Default Value type and click OK.
In the Details property, enter the value "0.3". That is, we are imagining a toy catapult with an
arm length of 0.3 meters.
Repeat this process with the other technical performance measures, entering 0.06 for the
ArmFractionByCounterWeight, and 2.1 (radians) for each of the two angles.
8/22/2012
P a g e | 240
8.3.4
8/22/2012
P a g e | 241
Rather than add all of the pendulum constraints directly to the Weighted Pendulum block, we have
decided to group them under a separate constraint block and link them to the Weighted Pendulum block
through the interface of the constraint block. In this tutorial, we create the constraint block and its
interface and then connect the interface to the Weighted Pendulum block. In subsequent tutorials, we add
constraints to the constraint block.
8.4.1
Rearrange the diagram layout to provide more space below the Weighted Pendulum block. We
will be adding a constraint block below it that will contain quite a few properties.
8/22/2012
P a g e | 242
8.4.2
Select the Constraint block from the palette and add a constraint block to the diagram below the
Weighted Pendulum. (This step represents a modeling choice. We could have proceeded to add
all of the catapult formulas as constraints to the Weighted Catapult block (using a parametric
diagram attached to that block). We tried that but found that the diagram got to be too
complicated. We discarded that approach and instead have opted to represent all of the catapult
formulas as constraints in a separate constraint block. This results in more readable diagrams.)
When looking for the Constraint block in the tool palette, look under the Block object (the two
are grouped together and only one is visible at a time).
8/22/2012
P a g e | 243
8.4.3
Name the new constraint block "PendulumRelations" and add six properties. As mentioned
earlier, do not use names with spaces or special characters because the names will become
Modelica variable names.
8/22/2012
P a g e | 244
ProjectileHeightGain. Select all six properties as a group and click the elipsis button for the Type
property.
Select <Data Type> Real for the group as a whole. That is a useful shortcut for setting properties.
8/22/2012
P a g e | 245
Select the Constraint property from the palette (it should be one of the options under the Property
object) and add a constraint property to the Weighted Pendulum block (not to the
PendulumRelations block!).
Name the constraint "PendulumEquations". Click the elipsis button for the constraint property
type, enter "pen" in the search box to narrow the search, select <Class> PendulumRelations for
the type, and click OK.
8/22/2012
P a g e | 246
We have created a constraint property of type PendulumRelations for the Weighted Pendulum
block. We named it PendulumEquations to emphasize the distinction between the constraint
block and the constraint property.
8.4.5
This is an interesting step. In this step, we create a parametric diagram to show how the
properties of the Weighted Catapult block are connected to the interface properties of the
PendulumRelations constraint block.
8/22/2012
P a g e | 247
Begin by double-clicking on the Weighted Pendulum block and creating a parametric diagram.
From the Outline panel, select all the properties of the Weighted Pendulum, including the
constraint property, and drag them onto the newly created parametric diagram.
Rearrange the diagram elements so that all of the properties are clearly visible. Place the
constraint property "PendulumEquations" in the center of the arrangement.
8/22/2012
P a g e | 248
Again, using the Outline panel, locate the Constraint Block "PendulumRelations," select all of its
properties, drag them as a group, and drop them onto the constraint property
"PendulumEquations." Since the constraint property has the matching type
("PendulumRelations"), the diagram will accept this action and display the properties as interface
connection points.
Drag the interface properties around so that each label is clearly visible.
Select the connector tool from the palette and, by holding down on the <Ctrl> key, connect each
of the Weighted Pendulum properties to its matching interface point.
8/22/2012
P a g e | 249
Your diagram will appear more cluttered than this image. Select all of the newly added
connections and hide all visible elements in the graphics section of the Properties tab. It will
take a little bit of time to make your diagram readable: adjust the positions of the properties and
the shapes of the connectors until all of the text is visible.
8/22/2012
P a g e | 250
8/22/2012
P a g e | 251
In this tutorial, we add the first of several generic constraints to the Modelica Library.
8.5.1
It is not necessary to extend the library to implement the toy catapult formulas but it is
instructive. Some of the formulas (such as the trigonometric formulas, the energy formulas, and
the rotational velocity formula) are generic and it might be useful in future models to have these
formulas available as part of a standard library. In this tutorial, we show how to add the
trigonometric formula to the library.
Open the library file and click the edit button on the toolbar. This will place the model file
(ToyCatapultModel.sysmldi) into read-only mode.
8/22/2012
P a g e | 252
Double-click on the newly created Physical Relationships package and create a block definition
diagram.
8/22/2012
P a g e | 253
8.5.2
From the diagram palette, select the Constraint block and add five constraint blocks to the
diagram (hold down the <Ctrl> key to speed the operation).
8/22/2012
P a g e | 254
In this step, we will work with only one of the constraint blocks. Name it
"HeightToRadiusRatio" (no spaces). Add three properties.
Name the newly created properties: Height, Radius, and AngleFromHorizontal. Set their type to
<Data Type> Real. Recall that you can set the type property for groups of properties at one time.
8/22/2012
P a g e | 255
8.5.3
Set the type of this constraint property to <Data Type> Modelica. The wizard SysML2Modelica
will expect to find a string formula for such a constraint property.
8/22/2012
P a g e | 256
In the Specification section of the GetHeight property, click the Create button for the Default
Value.
8/22/2012
P a g e | 257
8/22/2012
P a g e | 258
In this tutorial, we create a parametric model to calculate the height loss by the counterweight and the
height gain by the projectile during operation of the catapult. These are necessary inputs to the calculation
of the change in potential energy of the system which comes in a subsequent tutorial.
8.6.1
Switch back to editing the Toy Catapult Model, clicking the edit button if necessary.
Double-click on the constraint block PendulumRelations and add a parametric diagram.
8/22/2012
P a g e | 259
In the Outline panel, locate the constraint block PendulumRelations, and drag all of its properties
onto the newly created parametric diagram.
These properties show up as interface points on the edge of the diagram. Henceforth, we refer to
these interface points as "parameters." You may have to scroll the diagram to read the labels.
Rearrange the parameters so that the text of each parameter is visible.
8/22/2012
P a g e | 260
8.6.2
From the palette of the diagram editor, select the Constraint property and click anywhere on the
diagram to add a constraint property. You will be prompted to identify the type but we will do
that in a separate step. Select the "No type" option and click OK. (If we had tried to "choose an
existing type," we would have failed to find the library constraint blocks among the set of
choices.)
8/22/2012
P a g e | 261
Name the newly create constraint property "multiply" and click the ellipsis button for the Type
property. Enter the search string "mult" to narrow the list of possibilities and select "<Class>
Multiply". This is a constraint block defined in the ModelicaElementaryLibrary library. You
could verify that by clicking the qualified name checkbox if you like. Click the OK button.
8/22/2012
P a g e | 262
In the Outline panel, locate the Additional Resources section. Recall we loaded the
ModelicaElementaryLibrary model as a resource. Locate the Constraint Block Multiply within
that library. (If no resources are visible, make sure you do not have any filters active in the
Outline view.) Select all of its properties, except the constraint property, and drag them onto the
constraint property "multiply" in the diagram. Since this constraint property is of type
"Multiply," it will accept the properties and display them as parameters.
8/22/2012
P a g e | 263
8.6.3
Using the connector tool from the palette, add connections from the parameter ArmLength to the
parameter factor1 and from the parameter ArmFractionByCounterWeight to the parameter
factor2.
Observe that the parameter "product" now represents the product of ArmLength and
ArmFractionByCounterWeight. In other words, it represents the radius from the pivot to the
counterweight.
8/22/2012
P a g e | 264
Next, we want to represent the formula for the radius from the pivot to projectile.
This is a subtraction operation Add a constraint property. Name it "subtract." Set its type to
"Subtract." Drag and drop the properties of the library function Subtract onto this property.
Connect the minuend parameter to ArmLength and the subtrahend parameter to the product
parameter of the multiply operation.
The parameter "difference" now represents the radius from the pivot to the projectile.
8.6.5
Add four constraint properties to the parametric diagram and name them "getHeight1" through
"getHeight4."
8/22/2012
P a g e | 265
Select all four height constraint properties, click the ellipsis button for their type property, use
the search string "heig", and select "HeightToRadiusRatio", clicking OK when you are done.
Locate the constraint block HeightToRadiusRatio in the library resource (we created that block
in an earlier step) and drag its properties (but not its constraint property) onto the first of the
newly created constraint properties in the parametric diagram.
8/22/2012
P a g e | 266
Connect the parameter "product" from the "multiply" constraint property to parameter "Radius"
of the constraint property "getHeight1". Connect the parameter "StartingAngleAboveHorizontal"
to the parameter "AngleFromHorizontal." The parameter"Height" now represents the height of
the counterweight above the pivot before launch.
8/22/2012
P a g e | 267
8.6.6
Add two constraint properties to the parametric diagram. Name one of them
"addCWHeightLoss" and name the other "addProjHeightGain."
Set the type of each constraint property to "Add." Drag and drop the properties of the Add
constraint block (in the library resource) onto each of the constraint properties.
8/22/2012
P a g e | 268
8/22/2012
P a g e | 269
That completes the entry of the first block of formulas. Save your file.
8/22/2012
P a g e | 270
In this tutorial, we conduct an intermediate test of the model to ensure we have entered the relations
correctly. We also discuss some debugging techniques if your model fails to execute correctly.
8.7.1
By this point, we have a completely specified parametric model for the first block of catapult
formulas. It is a good idea to test the model before going any further. It will become harder to
debug problems when we add more formulas.
Select the Weighted Pendulum block.
8/22/2012
P a g e | 271
This will launch the SysML2Modelica wizard. We assume that you have successfully installed
this plug-in and tested it as part of earlier tutorials.
8.7.2
Inspect Model
Within the SysML2Modelica wizard advance to the Graph page and click Create and Show
Graph button.
8/22/2012
P a g e | 272
The graph layout is randomized so your view will not be exactly the same as the above
screenshot. The important thing to check for here is that all of the nodes appears to be connected.
If you spot a group of nodes not connected to the rest, that will indicate a problem with one of
your parametric diagrams. By clicking on the nodes and studying their names you should be able
to figure out where to look for a connection problem in your diagrams.
If your graph looks connected, then advance to the next page and click Refresh Values. Two of
the variables should be identified as "TBD" and the other four should have values as shown
below.
8/22/2012
P a g e | 273
If your display does not agree with this snapshot, then return to the model and correct the default
values of the corresponding properties.
8.7.3
Execute Model
Advance to the simulate page and click the Execute Script button. Allow some time for the
OpenModelica program to launch and solve the model. The results displayed should match the
screenshot below.
Congratulations: you have successfully created a non-trivial parametric model. If you encounter
a problem at this point, repeat the SimpleParametric tutorial to ensure that you have
OpenModelica installed and linked correctly. Other debugging techniques include clicking on the
ViewModel button and exploring the generated Modelical model.
This completes the test of the parametric model. Click the Cancel button on the wizard.
8/22/2012
P a g e | 274
8/22/2012
P a g e | 275
In preparation for completing the parametric model of the weighted pendulum, we add a few generic
constraints to the Modelica library. In particular, we create constraints representing formulas for potential
energy, kinetic energy, conservation of energy, and rotational velocity.
8.8.1
Select the tab for the ModelicaElementaryLibrary (or open the model) and click the pencil icon
to switch the editor into edit mode.
8/22/2012
P a g e | 276
In an earlier tutorial, we created a number of blank constraint blocks. Take one of those blank
constraint blocks, name it "PotentialEnergy" (no spaces or special characters) and add four
properties each of type "<Data Type> Real". Name the properties "Energy," "Mass,"
"AccelerationDueToGravity," and "Height".
Add a constraint property to the PotentialEnergy block, name it something like "PotEnergy", and
set its type to "<Data Type> Modelica."
8/22/2012
P a g e | 277
In the specification section of the Properties tab, set the default value type of the constraint
property to "Literal String." In the resulting value field enter the formula "Energy = Mass *
AccelerationDueToGravity * Height." Make sure that you spell the names of the variables
exactly the same as you named the corresponding properties.
8/22/2012
P a g e | 278
Repeat the previous step, taking one of the blank constraint blocks and making it a formula for
kinetic energy. That is, name the block "KineticEnergy," add three properties of <Data Type>
Real, name them "Energy," "Mass," and "Velocity," add a constraint property of <Data Type>
Modelica, name it "KinEnergy", create a default value of type Literal String, and enter the
formula "Energy = 0.5*Mass*Velocity^2".
8.8.4
Repeat the previous step, taking one of the blank constraint blocks and making it a formula for
rotational velocity. That is, name the block "RotationalVelocityFormula," add three properties of
<Data Type> Real, name them "RotationalVelocity," "LinearVelocity," and "Radius," add a
constraint property of <Data Type> Modelica, name it "RotVelocity", create a default value of
type Literal String, and enter the formula "RotationalVelocity=LinearVelocity/(2*Pi()*Radius)".
8/22/2012
P a g e | 279
8.8.5
Repeat the previous step, taking one of the blank constraint blocks and making it a formula
for the conservation of energy. That is, name the block "Conservation," add two properties of
<Data Type> Real, name them "Input," and "Output," add a constraint property of <Data Type>
Modelica, name it "Equality", create a default value of type Literal String, and enter the formula
"Input=Output".
8/22/2012
P a g e | 280
We now have all of the formulas we need to complete the Weighted Pendulum model.
Select the Toy Catapult model tab and click the pencil icon to switch its editor to edit mode.
8/22/2012
P a g e | 281
In this tutorial, we complete our description of the weighted pendulum model by adding constraints that
connect the mass of the counterweight with the velocity of the projectile. This tutorial repeats steps that
should be quite familiar now so you will feel confident in the modeling process.
8.9.1
Next, we want to represent the formula for the net loss in potential energy.
8/22/2012
P a g e | 282
Name one of the properties "CounterweightMass" and set its type to "<Data Type> Real."
Repeat the process with the other three properties, naming them "ProjectileMass,"
"AccelerationDueToGravity," and "NetLossPotentialEnergy."
8/22/2012
P a g e | 283
Navigate to the parametric diagram attached to the PendulumRelations block (i.e. double-click
the block), and drag the four new properties from the outline panel into the diagram.
Rearrange the parameters at the edge of the diagram so that you can read each of their labels.
Remember that you may need to scroll to the left of the diagram for these labels to be visible.
8/22/2012
P a g e | 284
8.9.2
In the parametric diagram, add two constraint properties (checking the "No type" box in the
resulting dialog), and name them "potentialEnergyCW" and "potentialEnergyProj." We will use
one of them to compute the potential energy loss of the counterweight and the other to compute
the potential energy gain of the projectile.
8/22/2012
P a g e | 285
Select both constraint properties and change their type to "<Class> Potential Energy." Recall that
we created this class within the library model in the previous tutorial. When search for this class
in the dialog, try typing "pot" into the search string box to narrow the search.
The parameters for these constraints are part of the library. In the Outline panel, under
"Additional Resources," open the library package and select the four properties of the
PotentialEnergy constraint block (do not select the constraint property of that block).
Drag and drop these parameters into your parametric diagram twice: dropping them once onto
the potentialEnergyCW constraint property and once onto the potentialEnergyProj constraint
property. Rearrange the parameters on the diagram so that the labels are clearly visible.
8/22/2012
P a g e | 286
Repeat the connection process for the projectile potential energy formula. Connect
"ProjectileHeightGain," "ProjectileMass," and "AccelerationDueToGravity" to the parameters
"Height," "Mass," and "AccelerationDueToGravity" of the potentialEnergyProj constraint
property.
8/22/2012
P a g e | 287
8.9.3
Connect to NetLossPotentialEnergy
In this step, we complete the description of the potential energy calculation by representing the
subtraction of the projectile potential energy gain from the counterweight projectile energy loss.
Add a constraint property (selecting "No type" in the dialog) and name it "subtractPotEng." Set
its type to "<Class> Subtract."
The Subtract class is part of the library. Select the Subtract class properties (minuend,
subtrahend, and difference) in the Outline panel.
8/22/2012
P a g e | 288
Drag these properties and drop them onto the subtractPotEng contraint property and rearrange
them to see the labels.
Connect the "Energy" parameter of the potentialEnergyCW to the "minuend" parameter. Connect
the "Energy" parameter of the potentialEnergyProj to the "subtrahend" parameter. Connect the
"difference" parameter to the "NetLossPotentialEnergy" interface parameter. Hide the visible
elements of the connections and rearrange parameter locations to improve the readability of the
diagram.
8.9.4
In the next two steps, we perform the operations of adding a constraint in a different order. It
doesn't really save any time to do it this way.
8/22/2012
P a g e | 289
On the parametric diagram for PendulumRelations, add four properties (selecting "No type" in
the dialog) to the boundary of the diagram.
8.9.5
We need to show the calculation of the kinetic energy of the counterweight, the kinetic energy of
the projectile, and the summation of these two kinetic energy components to get the total gain in
kinetic energy.
Add three constraint properties (no type) to the parametric diagram. Name them
"kineticEnergyCW," "kineticEnergyProj," and "addKinEng."
8/22/2012
P a g e | 290
Select the first two constraint properties and set their type to "<Class> KineticEnergy."
Select the appropriate parameters from the Outline view of the library and drag them onto the
matching constraint property in the parametric diagram. Rearrange parameters for label
visibility.
8/22/2012
P a g e | 291
8.9.6
Add a constraint property to the parametric diagram, call it "conservationOfEnergy," and set its
type to "<Class> Conservation."
8/22/2012
P a g e | 292
Use the Outline view to get the parameters of the Conservation constraint block (from the library
model) and drag them onto the constraint property "conservationOfEnergy."
Connect the Input parameter to the NetLossPotentialEnergy parameter and the Output parameter
to the GainKineticEnergy parameter.
8.9.7
Finally, we want to add the relationships linking projectile and counterweight velocities to the
rotational velocity of the catapult.
8/22/2012
P a g e | 293
Add two constraint properties, with no type initially, and name them "rotationalVelocityCW"
and "rotationalVelocityProj." Set their type to "<Class> RotationalVelocityFormula."
Locate the parameters of the RotationalVelocityFormula constraint block in the library and drag
them twice: dropping them on the two newly-created constraint properties.
8/22/2012
P a g e | 294
8.9.8
The rotational velocity formula has radius as one of its parameters. When considering the
counterweight, that radius would be the product of the ArmLength and the
ArmFractionByCounterWeight. When considering the projectile that would be difference of the
ArmLength and radius to the counterweight. We already have parameters representing these two
quantities, as shown below:
Connect these two parameters to the Radius parameter on the appropriate constraint property for
rotational velocity.
8/22/2012
P a g e | 295
Even though the parametric model for PendulumRelations is fully described, the graphical
objects do not completely represent the model. Recall that we added some parameters to the
parametric diagram. These parameters are a part of the model but they do not automatically show
up on the block representing PendulumRelations. It is a simple matter to show these parameters
on the block.
For this step to work, you have to be able to see the complete block for Pendulum Relations in
your diagram. It may be that you must change the size of your page for the block to be fully
visible. Try right-clicking on the diagram and selecting "Graphical Properties->Auto Resize
Page".
8/22/2012
P a g e | 296
Using the Outline panel, select the properties that we added to the diagram that are not currently
showing in the constraint block. These are "CounterweightVelocity," "ProjectileVelocity,"
"GainKineticEnergy," and "CatapultRotationalVelocity." Drag and drop this group onto the
PendulumRelations constraint block. This updates the graphical view to match the actual model.
8.9.10
The PendulumRelations constraint block is complete but we now need to connect it with valuebased properties in the Weighted Pendulum block.
Begin by adding eight properties to the Weighted Pendulum block.
8/22/2012
P a g e | 297
In the specification section of the properties tab, set the type of each default value to "Literal
String." Set the value of the CounterweightMass to 4, the ProjectileMass to 0.05, and
AccelerationDueToGravity to 9.81. Set the remaining values to "TBD."
8/22/2012
P a g e | 298
Locate these eight properties in the Outline panel (they are owned by the Weighted Pendulum
block). Double-click on the Weighted Pendulum block to open the parametric diagram attached
to it. Drag the eight properties from the Outline panel and drop them on the parametric diagram.
Rearrange the visible properties in the diagram so that input values are on the left and output
("TBD") values are on the right.
8/22/2012
P a g e | 299
8.9.11
Locate the matching eight parameters under the PendulumRelations constraint block in the
Outline panel.
8/22/2012
P a g e | 300
Drag these parameters and drop them onto the PendulumEquations constraint property in the
parametric diagram. Resize the constraint property and rearrange the parameters so that all
parameters and properties are visible.
Connect the value properties with their matching constraint block parameters. Because we used
the same names for each property-parameter pair, this will be easy. Hide the visible elements of
the connectors using the graphics section of the properties tab.
8/22/2012
P a g e | 301
8/22/2012
P a g e | 302
When we attempt to solve the parametric model of the weighted pendulum we discover that there is a
mistake somewhere. We detail the steps we used to locate the bug, but you may skip those steps if you
like and simply correct the mistake directly. The main debugging step we use is to force OpenModelica to
print error messages. You may want to remember that step for future use.
8.10.1 Skip Debugging Steps
8.10.2
Select the Weighted Pendulum block and then launch the SysML2Modelica wizard (select
Modelica from the SysMLTo menu). Advance to the Graph View page and click the Create and
Show Graph button. The layout is randomized but it should be a connected graph (no isolated
sub-graphs) of comparable complexity to this image:
8/22/2012
P a g e | 303
If the graph is not connected, return to your parametric diagrams and look for a missing link.
Advance to the Parameter and Variable Values page and click the Refresh button. Verify that the
correct number of properties have numerical values and "TBD" values.
8/22/2012
P a g e | 304
Advance to the Modelica Simulation page and click the Execute Script button. In our case, the
wizard returns with a list of variables but no values. This indicates that the simulation was
unsuccessful. There is an error somewhere in our model.
Unfortunately, there are no error messages displayed to help us debug the problem. In the next
step, we will force OpenModelica to display the error messages.
8.10.3
In debugging a model it is sometimes useful to see the Modelica model that has been generated
from the SysML model. Click on the View Model to see the model.
8/22/2012
P a g e | 305
This is the model that Modelica is unable to solve. Clearly, you will need to understand the
Modelica language to make sense of this model. That is out of scope for this tutorial. Let's try
something else.
On the Simulation page, check the box called "Verbose" for "Output Detail" and then click the
"Execute" button again to re-run the simulation.
This provides more detailed output from OpenModelica. In this case, we notice that the
simulation failed because "Class Pi not found." Somewhere in our model we make use of Pi in an
invalid way.
8.10.4
Fix Bug
The previous debugging steps led us to discover that our model makes invalid use of the function
Pi. There is only one place where we use "Pi": that is in the RotationalVelocityFormula
constraint block in the ModelicaElementaryLibrary.
Open the library and find the default value property for the constraint property "RotVelocity."
8/22/2012
P a g e | 306
The problem is that "Pi()" is not a recognized function in Modelica. (We assumed,
incorrectly, that such a function existed.) There is defined constant PI but it is not easy to access
using the current version of the SysML2Modelica wizard. To fix this bug, we will simply replace
the function "Pi()" with the explicit value "3.14159265." (The SysML2Modelica wizard has been
improved since this tutorial was created. With the new version, alternatively, we could replace
"Pi()" with "Modelica.constants.pi".)
Switch the library editor to edit mode by clicking the pencil icon.
Save the library file, return to the Toy Catapult model, switch to edit mode, launch the
SysML2Modelica wizard and execute the simulation script again.
8/22/2012
P a g e | 307
This time it works. The resulting projectile velocity is 5.44. We have a working model of
catapult relationships.
8/22/2012
P a g e | 308
Now that we have a working model of the weighted pendulum we can perform some interesting
studies. For example, if we are given a target velocity for the projectile, we may want to solve
for the required mass of the counterweight. As another example, we may want to optimize the
location of the pivot on the catapult arm. For this latter optimization, we employ a trick to get
OpenModelica to vary the location of the pivot and report the resulting projectile velocity. When
we plot the result, we quickly see where the optimal pivot position is located.
This tutorial completes the performance analysis group of tutorials.
8.11.1 Find Counterweight Mass for Required Projectile Velocity
Suppose that through our customer and competitive analysis we decided that we needed the
catapult to achieve a projectile velocity of 6.1 meters per second. How heavy would the
8/22/2012
P a g e | 309
counterweight have to be to achieve that? We assume that all other parameters (arm length,
projectile mass, starting and ending angles) are unchanged.
To solve this problem, we simply need to change the ProjectileVelocity value from "TBD" to
"6.1" and change the CounterweightMass value from "4" to "TBD." Resolving the model will
give us the required counterweight mass.
On the Weighted Pendulum block, select the ProjectileVelocity property. In the specification
section of the properties tab, change its default value from "TBD" to "6.1".
8/22/2012
P a g e | 310
To achieve the new projectile velocity requirement, we would need to increase the counterweight
mass from 4 kilograms to 5.1 kilograms.
8.11.2
Suppose we ask a different question: keeping the counterweight mass at 4 kilograms, where
should we position the pivot on the catapult arm to maximize the projectile velocity? This is an
example of a design optimization study.
This is a more difficult question to answer. We would need to solve the model for multiple
values of the property "ArmFractionByCounterWeight" and keep track of resulting values of
ProjectileVelocity and then pick the best value (the ArmFractionByCounterWeight value that
maximizes ProjectileVelocity).
One way to accomplish this is to take the Modelica model and script that are generated by the
SysML2Modelica wizard and modify them to loop over different values of the
ArmFractionByCounterWeight parameter. This would require learning more about the
OpenModelica scripting language.
Another idea is to exploit the simulation capability of Modelica and trick it into varying the
ArmFractionByCounterWeight parameter for us. This is actually quite simple to implement so
we will demonstrate this idea. Keep in mind that it is a trick and not the normal way in which
you would conduct a design optimization study.
Modify the default values of three parameters: set ArmFractionByCounterWeight to "TBD," set
ProjectileVelocity to "TBD," and set CounterweightMass back to its original value of "4".
8/22/2012
P a g e | 311
Double-click on the Weighted Pendulum block to open its parametric diagram. Add a constraint
property to the diagram, naming it something like "makeTime," and set its type to "<Data Type>
Modelica." (Although not evident in the image below, the box for the constraint property has
slightly rounded corners.)
8/22/2012
P a g e | 312
In the specification section of the properties tab for the makeTime constraint property, create a
default value of type "Literal String," and enter the expression
"ArmFractionByCounterWeight=time."
We have just added another equation to the system of equations describing the Weighted
Pendulum block.
This is the trick: the equation forces the pivot position (ArmFractionByCounterWeight) to equal
the variable "time." The variable "time" is what Modelica uses to simulate dynamical systems.
We have just converted our model from a static system of equations to a dynamic system: there
is a different set of equations to be solved for each value of the "time" variable. When
OpenModelica simulates this system, it will be solving that system of equations for different
values of the ArmFractionByCounterWeight property. The only values that make sense are
fractions between 0 and 1, so as long as we restrict the "time" variable to lie in this range the
resulting solutions will be valid.
8.11.3
8/22/2012
P a g e | 313
Assuming the model solves without error, advance to the next page, "Simulation Plot Results."
Click the Plot Values button and select the ProjectileVelocity variable. The SysML2Modelica
wizard will read the simulation output file and display a time plot of the selected variable(s).
8/22/2012
P a g e | 314
As a further challenge, now, suppose you wanted to minimize the counterweight mass required
to achieve a projectile velocity of 6.1 meters per second given that you could also optimize the
pivot location. In the previous tutorial, we discovered that we needed a counterweight mass of
5.1 kilograms when the pivot location was 6% of the arm length. Can we reduce that mass
required by positioning the pivot location in a better place?
8/22/2012
P a g e | 315
Beginning from a pre-constructed model, this set of tutorials describes how to develop a system
architecture using SysML. A system architecture is a description of how the components of a system
interact to achieve a system level behavior.
8/22/2012
P a g e | 316
A pre-constructed initial architecture model for the toy catapult case study is available for download on
the ThinkSysML website. In this tutorial, we download the model, unzip it, and import the files into the
ToyCatapult model.
9.1.1
This tutorial can be followed anytime after the "Create SysML Model" tutorial group. We
assume that your workspace has a project called "ToyCatapult" and a models folder containing
the following files:
8/22/2012
P a g e | 317
9.1.2
Select the Models folder of your ToyCatapult project as the destination for the extracted files.
Click OK.
8/22/2012
P a g e | 318
8/22/2012
P a g e | 319
The pre-constructed model consists of two folders containing architectural elements of the toy catapult.
What is missing are the relations between these elements. In this tutorial, we simply examine the
elements. Subsequent tutorials will step through supplying the missing relations.
9.2.1
Launch Eclipse and open your ThinkSysML workspace. When you look in the Models folder of
the ToyCatapult project you would expect to see the files that were extracted in the previous
tutorial. Eclipse does not automatically refresh its folders so these files are likely not visible.
Right-click the Models folder and select "Refresh."
8/22/2012
P a g e | 320
After the Navigator panel is refreshed you should see the ToyCatapultArchitecture model files in
the Models folder.
8/22/2012
P a g e | 321
This pre-constructed model has two folders, "Structure" and "Behavior", and no connections
whatsoever to the other ToyCatapult models. In practice, your models within the same project
are likely to be connected as you share model elements between the different models. For
educational purposes, so that this tutorial group could be followed independently of other
tutorials, we have replicated model elements rather than re-use them. Where you see a model
element that also appears in the ToyCatapult model, keep in mind that they are unconnected
duplicates of each other.
9.2.2
Double-click on the "Structure" folder to open the block definition diagram called "Structure."
You will see that we have replicated the basic structure of a "Toy Catapult System" belonging to
a "Toy Catapult Context" together with a "Child" actor and a "Projectile."
In addition, we now show that the "Toy Catapult System" is composed of five subsystems: an
"Energy Storage System," a "Locking System," a "Projectile Containment System," a "Trigger
System," and a "Projectile Launch System." We have named these subsystems abstractly with
the purpose of permitting multiple design solutions. For example, we do not want to lock in a
decision of whether to use a spring, a pendulum, or compressed air to store energy, so we simply
refer to a generic "Energy Storage System." It is not practical to completely avoid design
decisions as we develop the architecture but it is desirable to maintain flexibility in the design.
In anticipation of the behavior analysis to follow, we will be describing how these subsystems
interact. In particular, we will analyze what flows between these subsystems. For this purpose,
we have created the blocks "Energy," and "Signal" (of type Signal) to supplement the
"Projectile" block. Flows will consist of energy, signals, and projectiles.
In the pre-constructed model, we have also added operations to each subsystem block but this
step would logically follow the behavior analysis, so we defer discussion of these operations to a
later point in the tutorial.
8/22/2012
P a g e | 322
9.2.3
Double-click the block "Toy Catapult System" to open the internal block diagram we have
associated with this block. We have loaded this diagram with parts representing the five major
subsystems. Later in this tutorial, we will show how these parts interconnect.
8/22/2012
P a g e | 323
9.2.4
Return to the top level diagram and double-click the "Behavior" folder. That will open a use case
diagram. The activity we want to describe in more detail is the "OperateCatapult" use case. We
could create a single activity diagram for this purpose but it would likely span multiple pages of
printed output. In anticipation of that, we break up the use case into three smaller use cases, each
with its own related activity diagram. We use the "include" relationship to indicate that the use
case "OperateCatapult" includes all three of the simpler uses cases.
8/22/2012
P a g e | 324
Double-click on the "ArmCatapult" use case to open the "ArmCatapultDetail" activity diagram.
To save you time, we have created swimlanes ("Activity Partitions") for each of the subsystems,
and for the external actors (the Child) and participating systems (the Projectile). By convention,
we place the User swimlane (the Child) on the left, the particating external systems on the right,
and the internal subsystems in the middle. Since this diagram is likely to be the basis for a
system test procedure, we add a pre-condition constraint comment and a post-condition
constraint comment.
We have also created a set of actions to describe the behavior "ArmCatapult." We use Opaque
Actions to describe what the Child does. We use Call Behavior Actions to describe what the
internal subsystems do. The Call Behavior Actions have a fork icon in the lower right corner.
(You can also click on an action and see its class in the Property panel.) The Call Behavior
Action allows us to specify an activity that is performed as part of the action. This would permit
subsequent models to describe this activity in more detail (imagine an activity diagram showing
how the components of the subsystem interact to achieve the behavior). In each case, we name
the Call Behavior Action and the underlying Activity with the same name. Thus, we have
the Call Behavior Action "AcceptEnergyInput" with Activity "AcceptEnergyInput."
Note that each action has been assigned to a particular swimlane. We are indicating that the
action is performed by the associated subsystem or actor.
In a subsequent tutorial, we will connect these actions with object flows.
9.2.6
The LoadCatapult activity diagram is quite simple but by treating it separately we avoid
complexity in the other behavior diagrams. It is also evident that maintaining a swimlane for the
8/22/2012
P a g e | 325
Projectile seems a bit foolish: the projectile is quite a passive system. However, it allows us to
make the point that behavior may involve actions performed by external systems.
9.2.7
8/22/2012
P a g e | 326
Return to the ArmCatapultDetail activity diagram (double-click the "ArmCatapult" use case). As
mentioned, we use Call Behavior Action to describe what functions the different subsystems
perform. Click on the "AcceptEnergyInput" action and open the Advanced section of the
properties tab. Observe that we have created a separate activity "AcceptEnergyInput" and
registered it as the behavior of the Call Behavior Action. In the Outline panel, note that these
model elements are separate: the Activity "AcceptEnergyInput" is different from the Call
Behavior Action "AcceptEnergyInput" even though we use the same name for both of them.
9.2.9
After describing the behavior of the system using use cases and activity diagrams, we returned to
the block definition diagram and added operations to each of the subsystem blocks. Discovering
these operations was a simple matter of "walking the columns" of our activity diagrams. For
example, looking at the swimlane for the Energy Storage System in each of the activity
diagrams, we discover that it performs three functions: it accepts energy input from the user, it
limits that input, and it converts potential energy to kinetic energy. We have listed these
functions as operations of the associated block, using the same names as the actions on the
activity diagrams.
8/22/2012
P a g e | 327
[This discussion is for advanced users.] There is no direct link between an operation on a block
in a block definition diagram and an action in an activity diagram. As a modeler, I want to show
that the two are related. How do I do that? What we have done is to use the Method property of
the operation to specify the same activity as the corresponding action. For example, on the
Energy Storage System block, we added an operation called "AcceptEnergyInput()". One of the
attributes of the Operation class is the "Method" attribute. For this method, we located the
existing activity "AcceptEnergyInput." This activity was created in the Activity Diagram
ArmCatapultDetail when the action "AcceptEnergyInput" was created. So, we can reference the
activity, but not the action directly.
8/22/2012
P a g e | 328
The pre-constructed model contains activities describing what functions each subsystem must perform to
achieve the required behavior of the toy catapult. In this tutorial, we connect these activities with object
flows to clarify how the subsystems work together.
9.3.1
Navigate to the ArmCatapultDetail activity diagram (double-click the "ArmCatapult" use case in
the "Behavior" folder). You may need to stretch and lay out the diagram elements to improve the
appearance of the diagram.
We want to describe what is flowing between subsystems as the behavior is executed. We do this
through typed pins on the actions and object flows between the pins.
Begin by adding an output pin to the "PushReceptacleIntoPosition" action and an input pin to the
"AcceptEnergyInput" action.
8/22/2012
P a g e | 329
The output pin is displayed as a box with an outgoing arrow. The input pin is displayed as a box
with an incoming arrow.
Select the output pin. In the model section of the properties tab, click the ellipsis button on the
type property. We are selecting an object type to identify with this pin. To narrow the search,
type some portion of the string "Energy" into the search string box. Select the class "Energy" and
click OK. Recall that the block "Energy" was defined on the block definition diagram.
8/22/2012
P a g e | 330
8/22/2012
P a g e | 331
Repeat the process with the input pin. Name it "EnergyIn" as well and set its type to "<Class>
Energy." There is nothing special about these names. We are re-using names to keep the model
simple. If that later causes confusion, we would come back and compose more distinct names.
9.3.2
From the connections palette, choose "Object Flow" and add an object flow connection from the
"EnergyIn" output pin to the "EnergyIn" input pin.
8/22/2012
P a g e | 332
Select the connection and use the Graphics section of the Properties tab to change its routing to
"rectilinear" and to hide all visible elements. The result is visually cleaner.
We have defined a behavioral relationship between the Child operator and Energy Storage
System. That is, the Child takes action to apply energy to the Energy Storage System. It is a
required function of the Energy Storage System to accept this energy and store it.
9.3.3
In describing how the energy storage system interacts with the locking subsystem, we think in
terms of signals being passed. This is natural in electrical and computer systems but less so in
purely mechanical systems. In the final design, it may in fact be a mechanical device that is used
but we can still interpret the interaction as one of signal passing.
Place input pins on each of the actions: "DetectReceptaclePosition," "LimitEnergyInput," and
"SecureReceptaclePosition." Place output pins on each of the actions "AcceptEnergyInput,"
"DetectReceptaclePosition," "LimitEnergyInput," and "SecureReceptaclePosition."
8/22/2012
P a g e | 333
Select these seven pins as a group (hold down the <Ctrl> key as you select). In the Properties
tab, click the ellipsis button for the Type property and select the Signal object. All seven pins
will be assigned the Signal object for their type.
Use the names "Position," "SecureReady," and "Secured" as shown below. By "Position," we
mean the current position of the catapult receptacle relative to its secured position and to its
8/22/2012
P a g e | 334
extreme limit. That is a somewhat vague concept at this point. Further design will have to clarify
the concept. The other signals are likely just "True/False" type information. Again, further design
can make this more specific.
9.3.4
Use object flow connections to connect the Position signal pin on the "AcceptEnergyInput"
action to the corresponding input pins on the "LimitEnergyInput" and
"DetectReceptaclePosition" actions.
8/22/2012
P a g e | 335
Note that you may need to rearrange actions and pins to make the diagram readable. If you see
tiny pink triangles next to an action, it means that the action does not clearly belong to a single
swimlane. Resize the action and move it so that it lies completely inside its proper swimlane.
9.3.5
Under normal operation, the child will stop pushing once he or she realizes that the receptacle is
secured. However, the child might continue pushing until the EnergyStorageSystem resists any
further energy input. We generalize this in terms of signals: the child will stop pushing once it
receives either a "Secured" signal or an "EnergyMaxed" signal. A merge node would be useful to
emphasize this either/or situation.
From the control palette, add a Merge Node to the EnergyStorageSystem swimlane.
Add a signal-type input pin to the "StopPushing" action. Name it "SignalStop." Connect the
output pins of the "LimitEnergyInput" and "SecureReceptaclePosition" actions to the merge node
and connect the merge node to the "SignalStop". In each case use an object flow connection. You
may need to rearrange actions and pins to make the diagram readable.
8/22/2012
P a g e | 336
As you move actions around to improve the appearance of your diagram, you may find it
difficult to keep each action in its proper swimlane. (Indeed, you may see warning icons from
Topcased telling you that the object no longer has the right parent.) One trick to make sure
actions are correctly placed in their swimlanes is to group-select all of the actions in a swimlane
and the swimlane itself and then click the "Align Center" button. The illustration below shows
how we centered all of the actions within the "EnergyStorageSystem" swimlane.
8/22/2012
P a g e | 337
9.3.6
Add a Signal-type input pin on the "EnterArmedState" action and connect it with the Secured
signal pin on the "SecureReceptaclePosition" action.
8/22/2012
P a g e | 338
9.3.7
Navigate to the "LoadCatapultDetail" activity diagram. Add input pins to the "StoreProjectile"
and "SitInReceptacle" actions. Add output pins to the "LoadProjectile" and "StoreProjectile"
actions.
8/22/2012
P a g e | 339
Select all of the pins and make their type "<Class> Projectile." (We created the Projectile as a
"Block." A "Block" in SysML is derived from a "Class" in UML; Topcased sometimes displays
the UML term.)
P a g e | 340
This is a little unusual. We have indicated the Projectile is an external system with which toy
catapult system interacts. We have also indicated that there is an object flow of type Projectile
passing through the behavior of the system. This simply means that we conceive of the Projectile
in its relation to our system of interest in different ways.
9.3.8
Navigate to the "LoadProjectileDetail" activity diagram. Add seven output pins and seven input
pins as shown below.
Select the group of pins shown below. Set their type to "Signal."
8/22/2012
P a g e | 341
Select the group of pins shown below and set their type "Energy."
8/22/2012
P a g e | 342
Select the remaining pins, as shown below, and set their type to "Projectile."
Name the pins "ReleaseCommand," "Release," "EnergyOut," "Stop," and "projectile" as shown
below.
8/22/2012
P a g e | 343
9.3.9
Use the object flow connector to connect the pins as shown below. It is hard to see but there is a
connector from "TransmitEnergyToReceptacle" and "TransmitEnergyToProjectile."
8/22/2012
P a g e | 344
These object flows do a good job of showing how the different actions interact but there is a
problem in that there is no connection between the "TransmitEnergyToReceptacle" action and
"Stop" action in the "ProjectileLaunchSystem." As we think about it, there is no object flow
between these two actions but one action logically precedes the other. Add a control flow
connection between the actions to convey this information.
8/22/2012
P a g e | 345
This completes our description of the behavior of the system in terms of interactions between the
subsystems. We move next to a structural perspective.
8/22/2012
P a g e | 346
In this tutorial, we use the internal block diagram to describe the static (non-behavioral) view of the
interfaces of each subsystem and how these interfaces connect with the interfaces of other subsystems and
with the outside context.
9.4.1
Navigate to the internal block diagram (double-click on the "Toy Catapult System" block in the
"Structure" package).
Our goal now is to describe the interfaces of each subsystem across which energy, material, and
information flows. We begin with describing the flow of energy.
From the Objects palette, select In Flow Port and add a port to the diagram. In the resulting
dialog box, specify the type of the port as "<Class> Energy" much as you did in selecting pin
types in the activity diagrams.
8/22/2012
P a g e | 347
The port is attached to the boundary of the diagram, signifying it is an interface for the Toy
Catapult System as a whole.
Add three more inflow ports but, this time, add them to the subsystems: "Energy Storage
System," "Projectile Launch System," and "Projectile Containment System." Make their type
"Energy" and name them all "EnergyIn."
Add outflow ports to the "Energy Storage System" and the "Projectile Launch System." Type
them as "Energy" and name them "EnergyOut."
8/22/2012
P a g e | 348
9.4.2
Use the connector to add connections as shown below. You may have to move pins around to
make all of the text legible.
9.4.3
Add inflow and outflow ports of type "Projectile" as shown below and add the connections as
well. We have defined two more interfaces with the outside context ("ProjectileIn" and
"ProjectileOut").
8/22/2012
P a g e | 349
9.4.4
As we detail our design, we will want to make the information passing more specific. For the
behavior model, we were content with identifying flows as simply "Energy," "Signal," or
"Projectile." Suppose, we want to make the signalling flows more specific. Our analysis of the
behavior reveals that there are seven types of signals being processed in the toy catapult system.
Let's make that explicit. Return to the block definition diagram and add seven signal blocks,
named "Position," "EnergyMaxed," "SecureReady," "Secured," "Stop," "ReleaseCommand," and
"Release." Connect them to the generic Signal block with "generalization" arcs. (The Signal
signal is a generalization of the more specific "Position" and other signals.)
9.4.5
Navigate to the internal block diagram again. Add outflow ports of type "<signal>
EnergyMaxed" and "<signal> Secured" to the border of the diagram. These are interfaces of the
Toy Catapult System with the outside context. Add inflow and outflow ports to the "Energy
Storage System," "Locking System," and "Trigger System" as shown and type them by the
appropriate signal type. Add connections as shown as well.
8/22/2012
P a g e | 350
9.4.6
The communication of launch signals is shown below. Add ports and connections corresponding
to the highlighted relations.
9.4.7
This completes our description of the static (non-behavioral) interfaces between subsystems
within the toy catapult. The completed internal block diagram should look something like this.
8/22/2012
P a g e | 351
We have described the architecture of the toy catapult system in terms of both behavior and
structure, describing how its major subsystems must work together to achieve the desired
behavior (i.e. the "Operate Catapult" use case) and how the different subsystems are connected
with one another through their interfaces (ports).
8/22/2012
P a g e | 352