The Tortoise and the Hare Tutorial
Overview
To understand the thought process and mechanisms through which you can create and then execute a SysML v2 model, you are going to construct a model for the infamous race between the Tortoise and the Hare from Aesop’s Fables. This provides a mechanism to discuss and demonstrate the process through which the Behavior Execution Engine can:
- Facilitate the simulation of dynamically evolving systems
- Enact interactions between these systems
- Measure the effectiveness of operating the systems in their intended use cases
You are going to explore two approaches to modeling the race.
The first will be a simplified discrete-timestep-based approach, something most engineers should recognize. You will use a heartbeat mechanism to move the simulation forward at a fixed cadence. With this approach, Behavior Execution Engine will evaluate events, provide comparisons, and drive transitions at the precision of the check in rate you defined.
The second approach will utilize features of Behavior Execution Engine to perform continuous event detection as a continuous function of time. In this approach, the transitions will traverse at precisely computed time instants as opposed to the fixed cadence timestep. Through both approaches, Behavior Execution Engine will handle the simulation execution: controlling the time progression, event finding, math operations, and comparisons between the instances in the simulation.
Building the SysML v2 Model
This tutorial will walk you through creating the model step by step. If at any time you would like to compare your version to the final tutorial version, please see the tutorial result example in <BEE Install Directory>/samples/sysml2/tutorialTortoiseVsHare/part-1/models. You can follow these instructions for more information on importing the file. Otherwise, we have provided an alternative format [.sysml] file as a reference to demonstrate the textual representation of the model.
As mentioned before, the first iteration of the model you are going to create for the race will make use of a traditional discrete time delay check in approach. While this approach functionally enables you to model the race and answer the basic question posed with Behavior Execution Engine, you will notice during execution that the fixed-step approach has the potential to result in imprecise solutions. Time to start creating your model of the race!
| Section | Description |
|---|---|
| Building the System Definition Diagram |
To execute a simulation with Behavior Execution Engine, you need to have a model with a case to target. It is a good practice to design one, so that we can create a use case with actors and a subject. |
| The Tortoise |
At this point, you should start thinking about how to describe the behaviors of the two different racers as they perform the race simulation. You can use the process of constructing the behaviors to educate and guide aspects of defining the attributes and operations necessary for simulation of these systems. Now start creating some state diagrams. |
| The Hare |
The Tortoise state behavior diagram was simple in that you know the tortoise starts the race and just runs until it ends. The hare, due to an inflated ego, is going to have a more complex behavior. The hare’s state diagram will have similar basic functions to the tortoise’s state diagram: it will have a waiting state, running the race state, and transition determine a “winner” or “loser” status. However, you have added wrinkles. The hare could give the tortoise a head start, and the hare also could decide to take a quick (or not so quick) nap after taking the lead. Start by creating the framework for Hare’s behavior diagram. |
| Creating a Use Case Diagram |
At this point, the state describing the arrogant behaviors of the hare is complete. At the beginning of the race, the hare has an opportunity to give the tortoise a head start if you provide a nonzero duration for “startingDelay.” Once the hare starts running, the behavior we described will have the hare to proceed to run until half way through the race. At that point the hare will consider resting if the tortoise is further behind in the race, assuming the “hasTakenANap” attribute is still “false.” The hare will continue to nap for a prescribed duration before resuming the race. Like the tortoise the determination of a "Winner” or “Loser” status is based on the status of the other reference part usage to the other racer. |
| A Retrospective on Design |
Looking back at the design decisions in retrospect, we identify some of the strengths and shortcomings of our modeling approach. |
Start Tutorial!
Writing the Delegates
In the first exercise, you explored how to use Behavior Execution Engine to build and execute a simple model for the race between the tortoise and the hare. This exercise is going to take the concepts you previously learned and use Behavior Execution Engine delegates to expand and refine the functionality. In the first example, you intentionally introduced several deficiencies: fixed timestep, imprecise event finding, etc. This tutorial will help you remedy them through your use of delegates. You will also be able to simplify the part definitions and associated state diagrams.
After you complete this exercise, you will understand the basics of the following:
- Building a simulation intending to use delegates during execution
- Customizing delegate implementations
- Building, deploying, and executing a simulation with delegates
Before you start, if you have not already completed the first tutorial (Simple Version), we highly recommend you do so. Also, it may be useful to read through the materials in the Developing Delegate Modules section of the help so you are familiar with the terms that will be used during this training.
Also, ensure that you have downloaded and configured Gradle version 5.6 or newer. This lesson will assume you are using an integrated software development environment (IDE), but it does not require one. If you are interested in guidance for setting up an IDE, review the Developer Environment section of the help.
| Section | Description |
|---|---|
| Updating the Part Definitions for the System |
The basic design of the race, in terms of part definitions, will be the same as the previous version. The part definitions specified for Race, a Racer, etc. still meet all the underlying needs and concepts for an animal race. However, because you will be leveraging the delegate system to implement this version, you will need to make several changes. |
| Updating the Diagrams |
This step involves replacing functionality for the start and stop racing actions. When delegating for an action, it is important to keep in mind that Behavior Execution Engine will ignore any of the delegated action’s owned actions. For our model, this means the implementation details of the Racer diagram are no longer necessary, and can be deleted. |
| Code Creation |
Now that you have finished updating the state diagrams to reflect the new approach to modeling the behavior, you are ready to start writing some code. Ensure that you have Gradle installed and configured correctly, as that is the build script you will be using for this example. Behavior Execution Engine provides a delegate source code project template to assist you in authoring the code base for execution. The folder can be found in the <BEE Install Directory>/samples/sysml2/build. The prepared template files will serve as the skeleton to which you can add all the meat (backing code) that facilitates the bespoke functionality you need for the simulation. To start this process, you’ll need to configure the directory to work with the delegate files. |
| Writing and Modifying Delegates |
Now you need to provide the code implementation for overriding the distance covered by the racers. Building a delegate module with the SysML v2 API has never been easier. The code required to get up is small and only needs to be setup once. The <BEE Install Directory>/samples/sysml2/tutorialTortoiseVsHare/part-2 contains the completed delegate module that you can reference at any time. |
Start Tutorial!
Integrating with Tools
The previously completed lessons showed you how to construct and execute a basic model using Behavior Execution Engine with SysML v2. Furthermore, you learned how to extend and augment the SysML v2 model using delegates.
In this lesson, you are going to further enhance the previous delegate module you have been working with to add a visualization element via a custom GUI. This will enable you to “see” the race while Behavior Execution Engine is simulating it.
Before you start, if you have not already completed the previous Delegate related lessons, we highly recommend you do so. This lesson will assume you are using an IDE, but it does not require one. If you are interested in guidance for setting up an IDE review the Developer Environment section of the help.
| Section | Description |
|---|---|
| Examining the Custom Visualization Controller |
Through instance data registration and listening to when the simulation time has advanced, you can create custom interactions that allow you to coordinate actions between the simulation and your analysis tools. |
Start Tutorial!