philchudley
Integrating Decision Tables and Executable State Machines
Integrating Decision Tables and Executable Statemachines
Enterprise Architect provides extensive modelling of decision tables via the DMN 1.2 MDG. Decsion Tables can be used to model business rules of any complexity in a concise and understandable way. These decsion table models can be simulated using mutple input data sets to ttes the business rules. Once tested program code, such as Java, can be generated for use in applications.
Enterprise Architect also provdes modelling and simulation of state machines. State machines model the dynamic behaviour of applications.
At the recent EA User Group 2022 meeting held in Reading UK, I presented how decision tables can be integrated with state machines to provide a simulated model of the dynamic behaviour invoking business rules. The example used was for the application for a car insuarbnce quotation. The business rules for determining the insurance premium based upon certain inputs were modelled as a decsion table, and the dynamic process of applying for a quotation was modelled using a UML executable state machine. The language used for code generation in both cases was Java.
To supplement this presentation I have created a comprehensive step-by-step tutorial which is far too long to reproduce here, therefore this step-by-step guide is provided as a download.
I hope you find the step-by-step guide a useful aid to using this very useful feature of Enterprise Architect. The example has been implemented and tested in EA v 15.2 and EA v 16.
Phil Chudley
Dunstan Thomas
This email address is being protected from spambots. You need JavaScript enabled to view it.
How to Set the Default Language for a New Model Repository
How to Set the Default Language for a New Model Repository
Overview
written by Phil Chudley, Principle Consultant at Dunstan Thomas Consulting
A question I am asked quite often is "how can set the default language to a new repository, other than Java".
As far as I know there is no global EA prefernce to acheive this, so most EA users would
- Create a new local repository
- Make the Code Engineering toolbar visible if not already visible
- Change the language to <none>, or some language other than Java
I tend to use the language setting of <none>, this article describes a method of acheiving the objective of having a default language other than Java preset for all future new local repositories.
Method
EA iis installed by default into the directory C:\Program Files (x86)\Sparx Systems and in this folder are three repositories all named EABase. Theses three repositories are for *.eap,*.eapx and *.feap repositories. When a new local repository is created one of these EABase repositoriesis copied into the user folder and renamed according to the name entered by the user.
To set a default language, we siimply:
- Open a EABase repository in EA
- Change the Code Engineering language to your preference
- Close EA
Sounds simple? But there's a catch, since the EABase repositories are located C:\Program Files (x86)\Sparx Systems they cannot be opend for writing in EA!
No problem:
- Copy all three EABase repositories to a directory of your choice
- Open one of these repositories in EA
- Set the Code Engineering language to your preference
- Repeat steps 2 and 3 for the remaining 2 EABase repositories
- Copy the three EABase repositories back to C:\Program Files (x86)\Sparx Systems Please note, you will need to have Adminstrator privilege to do this
Now, whenever a new local repository is created it will have the Code Engineering language that you set in the steps above.
Summary
I hope you find the above a useful trick, but there is more you can do with this trick. As the EABase repositories are copied to form your new local repository, then here are some additional changes that you might like to make to the EABase repositories:
- Modify any General Types like Status, Priority
- Create a default structure other than just a Model Root Node
- Import useful resources such as scripts, documentation templates
In fact anyhthing that is repository based that you wish to include as standard in all your new local repositories.
Yes, the only condition of this working is that you must have Adminstrator privilege to achieve the copy back to C:\Program Files (x86)\Sparx Systems (or know someone who has got Adminstrator privilege for your workstation / lapto), but it is a useful trick to know,
Phil Chudley
Principle Consultant
Dunstan Thomas Consulting
follow me on Twiter @SparxEAGuru
Creating Navigable Models for HTML Publication
Creating Navigable Models for HTML Publication
By Phil Chudley, Prinicipal Consultant at Dunstan Thomas Consulting
Background
Once a model has been developed in Enterprise Architect, it can be shared to users who do not have Enterprise Architect by publishing the model to HTML where the model can be viewed in a browser.
However, out of the box, this common method of publication to HTML suffers from the following problems:
- Unless the model is organised very logically, the non-Enterprise Architect user can struggle to find their way around the model.
- The presence of the Project Browser tree in the Web Page(s), can be confusing to the non-Enterprise Architect user where too much information is provided.
In reality, the non-Enterprise Architect user is most interested in the diagrams, and ideally would wish to navigate the model using these diagrams.
Navigation techniques are already built-in to Enterprise Architect, namely:
- Composite Elements.
- Hyperlinks.
- Navigation Cells.
If a model is built so that it can be navigated purely via diagrams using the techniques above, then the presence of the project browser tree in the HTML publication is rather irrelevant. The question is how can this project browser tree be removed from the web pages? The answer can be found in this article.
Creating a Model that can be Navigable via Diagrams
This section uses built-in features of Enterprise Architect. For an example, let us consider the following model that has been built already in Enterprise Architect:
This model is a “typical” UML model supplemented with Requirements, User Interface Screens and a Dashboard. As its stands it is quite difficult to navigate for the non-Enterprise Architect user, therefore we add to the model the following:
- Table of Contents diagrams that contain Navigation Cells to other diagrams.
A navigation cell is created very easily by:
- Creating a diagram (I use the EA Extended Custom diagram type) in a Package.
- Navigate to a diagram.
- Drag and drop this diagram to the diagram created in step 1) and choose Navigation Cell from the list of options.
- Choose an appropriate image.
For the model illustrated above, we begin by:
- Adding a View named TOC (or Table of Contents) to the model root.
- Move this to be the first view in the model.
- Add to this View a diagram (for example an EA Extended Custom diagram type).
This is illustrated below:
The next step is to add navigation cells to this newly created diagram and there are two basic approaches:
- Add a navigation cell for each diagram within the model to the diagram named TOC.
- Create “TOC” diagrams for each view / package and created navigation cells for these lower level TOC diagrams.
Which option you use depends upon the complexity of the model, in this example I used option 2) which resulted in the TOC diagram being populated with navigation cells as shown below:
As an example of a lower level TOC diagram, consider the package named User Interface which is shown expanded below:
Each of the packages inside User Interface has a User Interface diagram. Generally I place one diagram in one package.
Creating navigation cells for these diagrams yields the TOC diagram for the User Interface package as shown below:
This process is repeated for other Views and Packages.
We now have a model that is navigable entirely via diagrams commencing with the top level TOC diagram.
In this example I created a “back link” to the level above, using a hyperlink and setting the Behavior property Printable to be false.
The final step is to ensure that when the model opens, the TOC diagram is displayed by default. This is achieved by:
- Opening the TOC diagram.
- Select the Layout Ribbon.
- Select Manage → Set as Model Default.
Publishing to HTML
The result of selecting the Model Root node and using the Publish to HTML function, out of the box is as shown below:
The modifications we are going to make are as follows:
- Change the header image.
- Remove the Project and Advanced information from the bottom of the diagram.
- Remove the Project Browser Navigation tree.
Making the Modifications
Changing the Header Image
This is very easy to do, as there is an option on the HTML generation dialog to navigate to and select an alternate image. However, there is a “gottcha”. So that the chosen image will fit in the frame at the top of the HTML page, it must be less than or equal to 60px in height.
In this section, I will show you how to customize the HTML output so that the frame resizes to fit the height of your image.
The following steps are used:
- Discover the height of your image (this can be achieved with Windows File Explorer by positioning the mouse on the image file and examining the tool tip that displays). The image that I am going to use has a height of 56px.
- Using the Resources View, open the section named Web Style Templates, right-click and select Create New HTML Template.
- Enter a suitable name and click OK.
- In the dialog that displays the list of Templates, select the template named CSS – Main.
- Scroll down to line 248 as shown below:
- Change line 252 to be the height of your image + 1, in my example this is 57.
- Similarly, change line 259 to be the height of your image, in my example this is 56:
- Click Save.
Remove the Project and Advanced information from the bottom of the diagram
The following steps are used, assuming that the dialog showing the HTML Templates is still visible, if not, right click your Web Style Template in the resources and select Modify HTML Template:
- Select the Template named Body – Diagram:
- Delete lines 13 through 32 inclusive:
- Click Save.
Remove the Project Browser Navigation tree
Saving the best for last, our final modification is to remove the Project Browser Tree. To achieve this the Javascript Template needs modification as follows:
- Select the Template named Javascript:
- Scroll down to line 520 which should be the function named resizePage().
- Scroll down to line 549 and replace this line with the following lines of Javascript:
- Scroll back to line 85 which should be the function named initLoad(src, toc, home).
- Insert the following line of Javascript between lines 128 and 129:
- As a check the modification above should be as shown below:
- Click Save and then Click Close.
The Result
To view the effect of the changes, re-publish the model to HTML this time selecting your Web Style Template and navigating to your Image:
The result as shown in the Browser is as shown below:
Conclusion
The next step would be to modify the HTML templates such that when the user clicks an element which does not link to a diagram, nothing happens rather than the default behavior of displaying an element properties screen. Alternatively, the element properties screen could be modified to display just name and notes for example. Once I have worked out how to do this, I will share this in another tutorial.
Phil Chudley
Principal Consultant
Dunstan Thomas Consulting
Follow me on Twitter @SparxEAGuru
Using Stereotyped Relationships to Define Quicklink rules
Using Stereotyped Relationships to Define Quicklink rules
by Phillip Chudley, Principal Consultant at Dunstan Thomas Consulting
Background
One of my favourite features of Enterprise Architect (EA) is the ability to define your own meta-models using MDG technology, and over the many years I have used Enterprise Architect, I have developed many such MDGs and have shared my experiences in their development at numerous EA User Group meetings.
However there has always been a “sting in the tail” with developing an MDG in the respect of defining Quicklink rules. These were (and can still be) defined using a spreadsheet where each row defined a connector between two elements for a specific diagram. Not only was this tedious, but also prone to error and not that intuitive.
With the arrival of EA version 14 and in particularEnterprise Architect version 14.1 a new method of defining Quicklink rules was introduced. This new method uses Meta-relationship, Stereotyped relationship and metaconstraint.
In this article I will explain through a simple example MDG how to use Stereotyped relationships to define Quicklink rules.
Example Meta-model
For this example a simple three element meta-model will be used and this is illustrated below together with the relationships that are defined between these three elements:
Plan of Attack
To experiment with the new features of MDGs, the following steps were used:
- Create a locally hosted model repository for the MDG model.
- Using the MDG Builder structure, model the profile, (including any Tagged Values and Shapescripts), model the custom toolbox(es) and model custom diagram(s) connecting them with the appropriate toolboxes.
- Generate the MDG.
- Test the MDG.
- Using a separate diagram model the view specifications.
- Regenerate the MDG.
- Test the view specifications.
- Using a separate diagram model Quicklink definitions using Meta-relationships / Stereotyped relationships.
- Regenerate the MDG.
- Test the Quicklink definitions.
Steps 1) through 4) are pretty much standard for the development of an MDG and hence will not be described in detail, however some important inclusions and “gotchas” will be described.
The complete EA Model and the MDG XML file are available for download.
The MDG Profile Model
The diagram below illustrates the profile model for the elements and relationships defined in the meta-model shown previously:
Notes
The following should be noted:
- The attribute named _HideUmlLinks of type Boolean and default value of True is necessary so as to prevent all the UML Quicklinks from the metaclass (in this case Class) being listed with your defined Quicklink definitions. This will have no effect until such Quicklink definitions have been included in the profile model. This attribute is added manually to the metaclass.
- The attributes named _MeaningForwards and _MeaningBackwoods for the metaclasses Association, Generalization and Composition are used to provide names for the Quicklink definitions. That is the names that will appear in the Quicklink menu. _MeaningForwards is the Quicklink name for Source to Target, whereas _MeaningBackwards is the Quicklink name for Target to Source. These values, along with the attributes named _linestyle and _direction can be defined using the Profile Helpers.
- Tagged Values named DateIndentified (type Date) and CauseDetails (type Memo) have been defined and added to the stereotypes Problem and Cause.
- All three elements have a basic Shapescript (shown in the table below in case you would like to create the MDG from scratch), and have Toolbox / Project Browser icons defined. These icons are optional, but are included in the MDG XML file available for download, however if you use the EA model, then you will have to exclude the icons in the stereotyped elements and toolbox prior to generating the MDG.
- EA version 14.0 moved many of the familiar right-click menu options to the Ribbons, and generating profiles for packages and diagrams is no exception. To generate a profile from a package or diagram:
- For a Profile Package:
- Select the Package containing the profile in the Project Browser.
- Select Publish → Publish Package as UML Profile from the Technologies section of the SPECIALIZE ribbon.
- For a Diagram that models a custom diagram, or custom toolbox:
- Open the diagram containing the model of the custom diagram or custom toolbox.
- Select Publish → Publish Diagram as UML Profile from the Technologies section of the SPECIALIZE ribbon.
- When the dialog opens, there is no value in the Version text field. Due to an issue in EA 14.1, this must have a value (I usually set this to the same value as the version used when generating the MDG). Failure to enter a value for the version, will result in the XML files for the diagram profiles to be missing from the MDG generation dialogs.
- For a Profile Package:
The following diagrams illustrate the models for a single custom toolbox and a custom diagram provided for reference for the MDG example used in this article.
Example; Custom Toolbox
Example; Custom Diagram
The attributes in the Diagam_Custom metaclass are:
- Show Qualifiers & Visibility Indicators – False
- Show Tagged Values Compartment – True
- Hide Attributes Compartment – True
- Hide Operations Compartment – True
- Hide Connector Stereotype Labels – True
NOTE: Due to the simple Shapescript used for the elements within the profile, the attributes for the compartment visibility will have no effect.
Using Stereotyped relationships to Define Quicklink Rules
In Enterprise Architect version 14, two new items were added to the development of MDGs, these are:
- Meta-relationship – used to define a Quicklink rule between stereotyped elements defined in an MDG using UML Connectors.
- Stereotyped relationship - used to define a Quicklink rule between stereotyped elements defined in an MDG using Stereotyped Connectors defined in the MDG
In my experiments with these new items, I discovered that Meta-relationships worked when used to defined Quicklink rules between different MDG stereotypes, but did not appear to work when used to define Quicklink rules between the same MDG stereotype (that is a self-relationship). Hence the reason why in this example I have defined MDG stereotypes for Composition and Generalization and used Stereotyped relationships exclusively to defined Quicklink rules.
Defining the Quicklink Rules
Using a new Profile diagram with the same package as where the MDG Profile is defined, simply:
-
- Re-use the MDG Stereotype element (or elements) for which a relationships is required.
- Using the Metamodel section of the Profile Toolbox create a relationship for each valid connection between these MDG Stereotyped elements, including any self-relationships.
- Set a tagged value named stereotype to the name of the MDG stereotyped relationship that is valid in this context.
The diagram for the Meta-model used in this diagram is as shown below:
The profile package is then saved as a UML Profile and the MDG re-generated. Upon testing, and using the Quicklink the result is as shown in the example below:
If, when using the Quicklink an attempt is made to create a connection between any two elements that do not have a Stereotyped-relationship defined (as between Cause and Solution), no connector will be allowed.
NOTE: The rules defined using Stereotyped-relationships only apply when using the Quicklinker, these rules can be broken by using any relationships visible in the toolbox.
Therefore, to fully enforce relationship rules, define all relationships using Stereotyped-relationships and do not provide any relationships in the diagram toolbox.
Conclusion
Does using Stereotyped-relationships ease the pain of Quicklink defintions? In my opinion, most definitely yes!
Accompanying this tutorial, is a zip file containing:
- The model used to define the example used in this tutorial. This is an .eapx file.
- The MDG XML file as generated from the model.
I hope this example is useful to all those of you who develop MDGs for Enterprise Architect and I welcome your feedback.
My next article will explore the other new features for MDGs, namely:
- View Specifications
- Metaconstraints
Follow me on Twitter @SparxEAGuru
Using Keyboard Shortcuts with Enterprise Architect Extension Menus
Using Keyboard Shortcuts with Enterprise Architect Extension Menus
by Phil Chudley, Principal Consultant at Dunstan Thomas Consulting
Background
Extensions written for Enterprise Architect often define menus to invoke functionality, and although a short cut of the form Alt+character can be defined by prefixing the character in the menu option with &, this does not work as a keyboard shortcut.
After digging around a bit, I have discovered a work-around so that defined keyboard shortcuts can invoke menu options.
In this article I will explain through a simple example how to use this work-around in your EA Extension. This example has been tested on EA version 13.5 and EA version 14.
Plan of Attack
The logic behind this workaround is summarised as follows:
- Encapsulate all functionality that is invoked from the menu options in a Manager class, with public methods. This allows the functionality to be invoked from the menu and from the keyboard shortcut.
- Define your keyboard shortcut, ideally selecting combinations that are not already in use by EA. These are of the form of:
- Modifier(s) + key – for example Alt+1 or Ctrl+Alt+D
- All these keyboard shortcuts are registered with a keyboard Hook class associated with a Windows Form class.
- A key pressed event handler is added to the keyboard Hook class.
- The Windows Form class is never displayed, but catches the key pressed event. The event can be tested against the keyboard shortcut keys that have been registered and the corresponding menu function invoked using the Menu Manager class.
Overview of the Classes Defined in the Example
The workaround uses several classes to provide the keyboard shortcut functionality:
- Main – the central class that is always required for all EA Extensions
- MenuManager – a C# class that provides the functionality for all menu options
- AboutBox – a standard Windows AboutBox Form class
- HotKeyForm – a Windows Form class defining an empty window, which is never displayed, but whose sole purpose is to catch the keyboard event raised when pressing the keyboard shortkey combination, and to invoke the Extension’s menu functionality.
- KeyBoardHook – a C# class which registers the keyboard shortcuts, and raises the keyboard event when the keyboard shortcut keys are pressed.
- KeyPressedEventArgs – a C# class that encapsulates the event after the keyboard shortcut keys have been pressed. (Defined within KeyBoardHook)
The following class diagram illustrates the design of the example:
Detail & Code of the Classes
Main
Description
This class provides the entry point to all EA Extensions and is where the developer will define:
- Menu text for the extensions menus
- Global references to other classes, including EA.Repository
- Handle the appropriate EA broadcast events for;
- the initial connection to the Extension made by EA
- the menu contents
- menu enable / disable check / uncheck
- menu click
- EA disconnecting from the Extension
- Helper methods to provide functionality such as if a model repository is loaded.
- Code to handle any events broadcast by EA.
In this example, there are four menu options which provide very basic functionality:
- Option 1 – displays a Message Box
- Option 2 – displays a Message Box
- Option 3 – displays a Message Box
- About – displays the About Box
This functionality is available whether or not a model repository has been loaded and can be invoked via the menu, or by pressing the defined keyboard shortcut key combination.
Code
In the method EA_Connect, the instantiation of HotKeyForm, registers the keyboard shortcuts and creates the form, its event and listener. An instantiation of the MenuManager class is also created.
MenuManager
Description
This class defines a public method for each menu option so that these can be invoked from the class Main (as shown above), and also from with the HotKeyForm (shown later).
Code
AboutBox
Description
For the purposes of this example, the class is the standard class that is provided by the C# .NET framework.
HotKeyForm
Description
This class is a Windows Form class and instantiates an instance of the KeyBoardHook class, adds an EventHandler for the KeyPressedEvent and registers each keyboard shortcut key combination with the KeyBoardHook instance.
Code
KeyBoardHook
Description
This class provides all the “wiring” between the registered keyboard shortcuts, and the keypressed event.
Code
Does it Work?
Absolutely! The only way to see that it works is to create the Extension and try it out. This could be achieved by adding the code above to you own extension, or using the attached zip file which contains:
- Visual Studio solution for classes used in the example
- MSI installer for the example
Please note that this example was built using Visual Studio 2017 and the .NET framework version 4.6.1
Next Steps
This simple example assumes all Extension menu options are enabled all of the time, I am working on a variation of this example to provide keyboard shortcuts which are active only if a menu option is enabled or checked, and not active when a menu option is disabled or unchecked.
I hope this example is useful to all those of you who develop extensions for EA and I welcome your feedback.
Follow me on Twitter @SparxEAGuru
Requirements Checklists
Requirements Checklist
by Phil Chudley, Principal Consultant
There is a hidden gem in Enterprise Architect (I am using version 13), but this gem is available in previous versions (I believe version 11 and version 12).
This is an element called a Requirements Checklist, although it could be used as a checklist for other elements.
A Requirements Checklist allows the modeller to create a list of check-boxes, which can be used against an element (or elements), to manage at least the following:
- Element completeness.
- Element quality.
This article introduces the Requirements Checklist and illustrates how such an element can be used and customised.
Default Use
A Requirements Checklist element can be added to a model diagram (the element can be found on the Requirements Diagram Toolbox) or added directly to a package within the project browser.
When added to a diagram, the Requirements Checklist has the following appearance:
Double-clicking opens the following dialog:
Clicking on a checkbox will check the checkbox as shown below:
Then upon clicking Close, the Requirements Checklist element will display on a diagram as shown below:
Using the dialog invoked via double-clicking, the appearance of the check box can be modified as shown below:
Checked Item Style <none> | Checked Item Style Strikeout | Checked Item Style Greyed |
Relating to an Element (or Elements)
Elements can be related to Requirement Checklist using any of the usual techniques in Enterprise Architect, namely:
- Quicklink on a diagram.
- Toolbox relationship on a diagram.
- Relationship Matrix.
Which Relationship to Use and which direction?
Using the diagram Quicklink, the modeller is presented with the following choices:
- Dependency.
- Trace.
- Information Flow.
Which relationship to choose to up to the individual modeller, but ideally, the modeller will choose a relationship that “makes sense” to all stakeholders in the project.
My own personal choice is Dependency drawn from an Element to the Requirements Checklist.
The most important issue is:
No matter what relationship is used and no matter which direction is used, the same type of relationship and the same direction must be used consistently throughout the entire model by all modellers.
The main reason for this statement is for the production of documentation and reporting (covered in a future newsletter).
Configuring the Requirements Checklist Element
Although not immediately obvious, is the ability to customise the list and text of the check boxes.
A modeller can define their own list of checkboxes by using the following steps:
- Double-click the Requirements Checklist to show Dialog.
- Right-click on a check box entry and select Edit (to modify), Delete (to remove) this checkbox item. An example of such a modification is shown below:
- Click Close to apply the changes.
Re-using Requirements Checklist
Different elements may require different checklist elements, therefore I recommend the following modelling strategy:
- Create a Package in which to create / store all the different configurations of the Requirements Checklist element. (A list of “master checklists)
- When wishing to use one of these checklist elements:
- Right-click a checklist element (or checklist elements) and select Copy to clipboard > Full structure for duplication.
- Select another package in the project browser, right-click and select Paste Element(s) from clipboard.
Summary
In this article I have presented an overview of an often overlooked element in Enterprise Architect, namely the Requirements Checklist. I have also described how such elements can be customised and re-used from a library of “master checklists”.
In a future article I will describe some techniques for producing documents which detail elements and their related checklists.
Phil Chudley
Principal Consultant
Dunstan Thomas Consulting
@SparxEAGuru
You’ll find lots of useful Enterprise Architect videos on our YouTube Channel.
Simulation Using SysML 1.4 and OpenModelica and Enterprise Architect Version 13 Beta
Enterprise Architect version 13 Beta ~ Simulation using SysML 1.4 and OpenModelica
Sparx Systems released the first Beta of Enterprise Architect version 13 to registered users on June 3rd 2016. Since then a further build of the Beta was released on July 20th 2016.
Numerous changes have been made in version 13 (a full summary can be found at http://www.sparxsystems.com/products/ea/13/ ). I have not tried them all, but one of the more complex features is explored in this tutorial, namely, Simulation using SysML 1.4 and OpenModelica.
In the help for Enterprise Architect version 13 is a good section, including examples, on simulation using SysML 1.4 and OpenModelica. These examples are also included in the example repository EA Example.eap which is part in the installation of Enterprise Architect version 13 and accessible via the Help Ribbon. However I found that whilst these are good, they are lacking in detail, hence the reason why I wrote this tutorial.
Rather than just expand upon the examples provided by Sparx Systems, I created my own example (used within this tutorial). I certainly learnt a lot more creating this, than I did by simply replicating one of the Sparx Systems Examples.
Once you have completed this tutorial, revisit these examples, and they should make more sense!
Overview
Simulation using SysML 1.4 and OpenModelica is the ability to create a Systems Engineering Model using SysML 1.4, model mathematical behaviour and perform time simulation using OpenModelica.
The subject of time simulation and in particular OpenModelica is complex, so this tutorial will illustrate a fairly basic example to get you started.
The simulation provided by Enterprise Architect Version 13 is a graphical plot for a number of variables (which have the same dimension) on the y-axis against time on the x-axis.
The Example and its Mathematical Theory
For this tutorial I have chosen to model a simple Weapon that is capable of launching a projectile, simply known as Ballistics.
The Weapon will have:
an initial launch velocity for its projectile.
an angle of launch for the projectile.
The simulation will plot two variables which have a dimension of distance:
the parabolic trajectory of the projectile (the time the projectile is in the air).
the range of the projectile.
The Math!
To conduct a simulation we have to bite the bullet and apply some math. If you are not a Systems Engineer then most equations for simulations like motion theory, pendulums, and indeed ballistics can be found on the World Wide Web.
I have included the math here, since it is fundamental to our tutorial.
First let us assume that we are on earth where the force of gravity is
9.81 m/s2
Also let us assume that we are not considering resistance due to air etc in our calculations.
Give the following definitions:
Then we have:
Combining these equations using Pythagoras’ Theorem we obtain:
For the range of the projectile we use:
In addition, OpenModelica trigonometrical functions expect their parameter angle to be specified in radians whereas in the “real world” we usually use degrees. A simple conversion formula is:
Now we have the math behind us we can build our model ready for simulation.
Creating the Model
Before creating the model ensure that you have installed OpenModelica, this can be downloaded free of charge from
Plan of Attack
I will be using linear approach to building the model, this approach is re-usable and applicable to any such Systems Modelling.
Create a new repository.
Model any valueTypes (this is optional).
Model any Blocks that will type Ports (in this tutorial none of our Blocks require Ports).
Model the equations as ConstraintBlocks.
Model the structural design using Blocks including Value Properties and Constraint Properties.
If the Blocks have Ports, model the interconnectivity between these Blocks.
Model a Parametric for the Block to be simulated.
Model variations for the Block to be simulated.
Configure the Simulation.
Run the Simulation(s),
Create a New Repository
Create a new model repository in a location of your choice using a name of your choice.
NOTES
When using the Model Wizard for SysML 1.4, you will observe that the ability to add a structure for the System Model is not present (it is for SysML 1.3). We do not need such a structure for this tutorial, but if you do require this structure for your own projects, then activate both SysML 1.3 and SysML 1.4 MDGs. Create you structure, then deactivate SysML 1.3.
As code will be generated during the simulation process, avoid using spaces or punctuation when naming any element including Packages in your model.
In this tutorial I added the PrimitiveValueTypes.
Add a Package named Ballistics to your Model Root and add further Packages to Ballistics so as to create the following structure:
Model the Equations using ConstraintBlocks
In the Package named Constraints add a SysML 1.4 Block Definition Diagram named Constraints.
Using the Toolbox add a ConstraintBlock named Trajectory to this diagram.
Whilst the Properties dialog is still open, enter the following (make sure that your constraint is syntactically correct!) as the name of a new constraint:
y=(x*tan(theta))-((g*x*x)/(2*u*u*cos(theta)*cos(theta)))
Save the Constraint.
Using the Toolbox add Properties named
theta
g
u
x
y
To the ConstraintBlock named Trajectory. There is no need to type these properties, since they will default to Real when we come to simulation.
Press Delete key for each of these Properties to remove them from the diagram and you should see the following:
If you do not see the constraints compartment, use the Diagram / Element properties to make the Constraints compartment visible.
Repeat the above process to create ConstraintBlocks for
HorizontalPosition
NOTE
We do not have to create a parameter for time since this is pre-defined already for simulation.
DegToRad
Range
Model the Structural Design
For this tutorial, this is really straightforward as our structural design just consists of a single block for the Weapon.
In the Package named Structure add a SysML 1.4 Block Definition Diagram named Structure.
Using the Toolbox add a Block named Weapon to this diagram.
Add the following Properties to the Block (there is no need to type them as they will all be Real and this is the assumed default for simulation).
g (set the default value to 9.81)
range
theta
u
y
Add the following ConstraintProperties typed to their corresponding ConstraintBlock to this Block.
ConstraintProperty Name |
Typed to ConstraintBlock |
d2r |
DegToRad |
hp |
HorizontalPosition |
rng |
Range |
traj |
Trajectory |
NOTE
You can add a ConstraintProperty to a Block by:
Adding a Property from the Toolbox.
Setting its Stereotype to SysML1.4::constraintProperty (use the … navigate button, select SysML 1.4 from the Profile dropdown, then select constraintProperty from the list of stereotypes).
Your Block should be as shown below:
NOTE
To aid locating the Package containing the ConstraintBlocks consider setting the Package as a Namepace Root, by right-clicking the package and selecting Code Engineering | Set as Namespace Root.
Model the Parametric for the Structural Design
Right-click the Block named Weapon and select New Child Diagram | Parametric Diagram, accepting the default diagram name of Weapon.
Right-click the Frame and select Synchronize Structural Elements. All the Properties and Constraint Properties will now be added to the Frame.
Arrange these as shown below:
Right-click the ConstraintProperty named d2r and select Structural Elements…
Click Show Owned/Inherited.
Select all the Properties.
Repeat the above for the remaining ConstraintProperties.
After some rearrangement, your diagram shown be as shown below:
Using Binding Connectors connect corresponding Parameters so your diagram is as shown below:
Modelling the Variations
We now model variations of the Block named Weapon so that we can use the simulation to compare different values of Initial Velocity and Angle of Elevation.
In the Package named Comparisons add a SysML 1.4 Block Definition Diagram named Comparisions.
Using the Toolbox add a Block named WeaponCompare to this diagram.
To this Block add three Properties named weapon1, weapon2 and weapon3 respectively. These Properties should all be typed to the Block named Weapon.
Once completed, your diagram should be as shown below:
Configure the Simulation
Select the Ribbon named Simulate then select
Select SysMLSim Configuration Manager.
This opens the SysMLSim workspace as shown below:
If this is the first time you have run a simulation, then select
from the top toolbar
Select Configure Modelica Solver
Navigate to the installation folder for OpenModelica (as shown below)
Click OK.
The first step for new simulation is to create a SysMLSimConfiguration Artifact (subsequently you can simply select a SysMLSimConfiguration Artifact Artifact).
Select from the top toolbar
Select Create Artifact
Select Ballistics in the Select Package Dialog and click Add New to create a new SysMLSimConfiguration Artifact named Ballistics.
We now have to set the Package using the … navigation adjacent to Package. It is important to select a Package that contains all elements in the model to be simulated, in this tutorial this is the Package named Ballistics.
The model structure is then added to the SysMLSim Configuration Manager as shown below:
Expand the node named Weapon and then expand Part:
First we need to inform the simulator that Weapon is a Class.
Select SysMLSimClass from its drop down.
Next we need to configure whether these Parts are Variables or Constants.
For this tutorial we have two variables, y and range, the remaining Parts are Constants.
For each part, click on its drop down and select either SimVariable or SimConstant as shown below:
We are going to simulate the Block named WeaponCompare (so as to compare different weapon settings), this is known as the SysMLSimModel.
This is selected by using the drop down for WeaponCompare and selecting SysMLSimModel.
This populates the Simulator section of the SysMLSim Configuration Manager as shown below:
So that we can run several simulations each using different settings for the Weapon Parameters, we create one or more DataSets for the Simulation Model.
Right-click the entry named WeaponCompare and select Create Simulation DataSet.
Do this twice more, and then expand WeaponCompare.
You can rename each DataSet by clicking on its default name DataSet_1 etc. and then typing a new name for example rename:
DataSet_1 as Same Velocity Different Angle
DataSet_2 as Same Angle Different Velocity
DataSet_3 as Different Velocity Different Angle
We now configure each DataSet by clicking Click button to configure… followed by clicking the … button. This opens the Configure Simulation Data dialog (the one shown is for the DataSet named Same Velocity Different Angle) :
Values are entered in Value column for their corresponding attribute as shown below:
Click OK when done.
Repeat the above using the following values for theta and u.
DataSet : Same Angle Different Velocity |
||
weapon1 |
theta |
45 |
u |
200 |
|
weapon2 |
theta |
45 |
u |
400 |
|
weapon3 |
theta |
45 |
u |
600 |
DataSet : Different Angle Different Velocity |
||
weapon1 |
theta |
60 |
u |
200 |
|
weapon2 |
theta |
45 |
u |
600 |
|
weapon3 |
theta |
30 |
u |
400 |
Save the settings by clicking in the toolbar.
Run the Simulation
To run a simulation:
Select a Model to simulate.
Select a DataSet from this Model.
Select a Start and Stop time (initially set to 0 and 20).
Select the Properties to Plot.
Click Solve
If all has gone well, you should see a simulation graph (if not refer to section named Troubleshooting in this tutorial).
For this tutorial and for the first simulation:
Select WeaponCompare as the Model.
Select Same Velocity Different Angle as the DataSet
Enter 85 as the Stop time (I found this value be running the simulation several times, until I had an optimum value)
Select all Properties to Plot.
Click Solve.
If you do not see this graph refer to the section named Troubleshooting.
The trajectory for weapon3 is difficult to see since it is coloured yellow, this can be changed by clicking Setup and selecting a different colour (for example Black).
I believe, it is not possible to save these colour settings for future simulations.
You can also set titles and a legend.
Some Observations
You may notice that the parabolic curve for the trajectory, does not look exactly the same as some examples you may have found elsewhere. This is due to the fact that most ballistic graphs plot distance on the x-axis and distance on the y-axis.
In Enterprise Architect Version 13 SysML Simulation always plots time on the x-axis, hence the parabolas above represent the time that the projectile is in the air.
Also notice that the plot continues for negative values of y. (There may be a method of controlling this using Modelica Functions created as an operation stereotyped as SimFunction and using Modelica code as the operation’s behaviour, but I have not tried this).
Also notice that we appear to have only one plot for the Range (which is a straight line since its value does not vary with time). This is due to the fact that complimentary angles (such as 30 and 60) always produce the same range value. In addition in this example, the Range values for the angles 30 / 60 and 45 are very close, and cannot be distinguished in the scale used for the y-axis.
Repeat the simulations for the other two datasets and you should see this following graphs.
Same Angle Different Velocity
Different Velocity Different Angle
Troubleshooting
When trying SysML Simulation for myself, I encountered numerous errors which prevented the graph from being displayed.
Error messages are displayed in the System Output window, the most common I encountered where:
Too many equations over determined system – the model has N equations and M variables
Too few equations under determined system – the model has M equations and N variables
Class name missing
Where N is greater than M and name is the name of the Block you are simulating.
The cause of the first two errors is simply that the Parts have the wrong type (you either have too many SimVariables or too few SimVariables. The most common cause of this I found is forgetting to set Parts to SimConstant (it appears that no setting is similar to a SImVariable).
The last error message is more puzzling, since the model class is plainly present. What the error actually means, is that code generated for the class has failed to parse (or compile), the most usual cause is a syntax error in the constraint text (miss-matched brackets etc).
There may be many other errors yet to be encountered, but hopefully the above will solve most of your problems.
Conclusion
In this article I have provided a tutorial to illustrate the new Simulation using SysML 1.4 and OpenModelica functionality provided in Enterprise Architecture version 13 Beta.
I hope you found this article useful and informative and please keep a lookout for further mini tutorials on the new and exciting features of EA version 13.
Phil Chudley
Principal Consultant
Dunstan Thomas Consulting
@SparxEAGuru
Time Aware Modelling in EA version 13 Beta
Enterprise Architect version 13 Beta ~ Time Aware Modelling
Sparx Systems released the first Beta of Enterprise Architect version 13 to registered users on June 3rd 2016. Since then a further build of the Beta was released on July 20th 2016.
Numerous changes have been made in version 13 (a full summary can be found at http://www.sparxsystems.com/products/ea/13/ ). I have not tried them all, but one of the more exciting features is explored in this tutorial, namely, Time Aware Modelling.
Overview
Time Aware Modelling is the ability to create an As-Is model, and to clone this to create a new To-Be version whilst maintaining traceability between all the elements. In previous versions of Enterprise Architect, this has been possible, but is quite a laborious process. In Enterprise Architect version 13, Time Aware Modelling becomes far easier as I hope this tutorial will illustrate.
Creating the As-Is Model
For this tutorial I will create a simple UML Model of a basic power supply, although Time Aware Modelling can be applied to any model.
Using EA version 13 Beta, create a new repository with a name and location of your choice.
Under the Model Root create the following Package structure:
In the Package named Design add a UML Class Diagram named Power Supply Version 1.0.
Create the following UML Class Model which is our As-Is model using Connector relationships between the Ports.
We observe that the Port named Earth-Out on the Class named Switch is not connected to anything (it should be connected to Ground). Also let us assume that for the next design we wish to use two controllers, hence we will need a transformer which has four outputs (or two transformers).
This provides us with an opportunity to create a To-Be model and relate this to our As-Is model.
Creating the To-Be Model
This is a four stage process:
Clone the As-Is package structure, creating a To-Be model.
Clone the Elements on the To-Be model.
Modify the To-Be model.
Create the Migration diagram(s).
Cloning the As-Is Package Structure
Right-click the Package named Design and select Clone Structure as New Version…
You will be prompted for a name and version for the new structure, which you should complete as shown below (any version other than 1.0 can be used):
Click OK.
You will then be prompted for a location for the new structure:
Select Power Supply
Click Add New and create a new Package named Version 2.0
Click OK.
You will see a new Diagram created in the Package named Version 2.0.
Rename this diagram Power Supply (Version 2.0).
This diagram contains links to the original As-Is model elements, but has its Version Property set to 2.0.
Cloning the Elements
Logically, you should only clone the elements where changes are to be made in the To-Be model, however I discovered, that when using the new Diagram Filter to Version Option (see later in this tutorial) potentially miss-leading results can occur, therefore I clone all elements in the To-Be model.
To clone an element:
Select an element (or more than one element).
Right-click on a selected element and select Clone Element(s) as New Version…
Click OK.
New elements (each with their Version Property set to 2.0) have been created and added to the package for the To-Be model.
In addition, the diagram has updated its links to refer to these new Elements.
Although not apparent, these new elements (add their child Ports), all have trace relationships back to their corresponding elements in Version 1.0 (the As-Is model).
Modify the To-Be Model
Now we can make some changes to the To-Be model.
By modifying elements and creating new elements create the following UML Class model:
NOTE
Do not forget to set the Version Property on any new elements (such as the Class named Ground and its Port named Earth-In to match those which have been cloned, that is, in this tutorial 2.0. This includes and child elements such as Ports.
Creating the Migration Diagram(s)
This stage is optional, but is a very useful analysis tool.
Create a Package named Migration in the View named Power Supply.
Ensure that you have saved the diagram named Power Supply (Version 2.0)
Right-click this diagram in the Project Browser and select Copy / Paste -> Copy Diagram
Right-click the Package named Migration and select Copy / Paste -> Paste Diagram…
Select Shallow Copy and rename the diagram to Power Supply Migration
Right-click the Class named Switch and select Insert Related Elements…
Check Switch and uncheck Layout Diagram when complete.
Click OK.
Right-click the newly added Class named Switch and select Structural Elements… and select all Ports.
Click Close.
After a bit of re-arranging you will have a good traceability diagram between the As-Is elements and the To-Be elements.
Repeat the above for the remaining elements and after some tidying up, you should have a diagram similar to that shown below:
NOTE
In the diagram above I have changed the line styles for the trace relationships to Orthogonal Square.
Once you have created this related migration diagram, you can use the new Filter to Version feature to highlight which elements are set to a selected version.
Ensure that this diagram has been saved.
Right-click this diagram in the Project Browser and select Copy / Paste -> Copy Diagram
Right-click the Package named Migration and select Copy / Paste -> Paste Diagram…
Select Shallow Copy and rename the diagram to Power Supply Migration – As-Is (Version 1.0)
Right-click the Package named Migration and select Copy / Paste -> Paste Diagram…
Select Shallow Copy and rename the diagram to Power Supply Migration – To-Be (Version 2.0)
Open the Diagram Properties for the Diagram named Power Supply Migration – As-Is (Version 1.0)
Set the Version to 1.0 and check Filter to Version: