DSim

Create a DSim Session

In order to run a DSim simulation from within VisualCommander, we need to create a new data session with DSim as the data source.

Press CMD+D to pull up the Data window, and click on the Sessions tab. Press the "+" button in the lower left corner to create a new session. Choose a name for your session, and set the source type to be "DSim", as shown in the screenshot below. Note, if the "Quick Start" box is checked, the simulation will start immediately after it is configured.

Configure with a DSim Setup File

At this point, VisualCommander has a blank session. The next step is to supply configuration data to the session. Because this is a DSim simulation, we configure it by selecting a simulation setup file. A new "Configure" button will be displayed in the bottom right corner, as shown below. Press this button to select a setup file.

VisualCommander provides some example setup files, located in the following folder:
/Library/Application Support/VisualCommander/Model Libraries/
You can select any .dss file you wish. To follow along with this tutorial, choose the "second_order.dss" file. This will run a very basic simulation of a second order dynamic system.

Upon selecting the setup file, a new window will appear prompting you to verify your selection. Press the "Send Configuration" button.

Note that you can avoid repeating the above manual steps by using a "Session Manager" plugin. Click to learn more.

• Using the Session Manager

Run the Simulation

If you checked the "QuickStart" box, the simulation will already be running. Otherwise, in the "Sessions" tab of the Data window, the "Configure" button will now have been replaced by a "Start" button. Press it to begin running the simulation.

Now click on the "Tree" tab of the Data window. This provides a hierarchical tree of all the currently available data sources. You will see an entry here with the session name that you chose. In this case we have named it "my simulation". Click on the name to expand it.

The expanded list will have two volumes: "second_order" and "Simulation". The "second_order" volume corresponds to the DSim object named "second_order", which runs the second order dynamic simulation. In general, a single DSim simulation can have multiple objects, which would all appear as separate volumes in this data hierarchy. In this case, it has only one object.

The "Simulation" volume is common to all DSim simulations. It contains information related to the simulation timing, speed, and run status.

Click on the "second_order" and "Simulation" volumes to expand them and view their contents. The entries in each volume are called "data points". The ones shown in italics are commands.

View the Simulation

Begin with a blank interface. Press CMD+N to create a new blank interface.

Drag the data point "y" from the "second_order" volume to the interface. This will create a raw data display, showing the value of the data point.

Now drag the command "u" from the "second_order" volume to the interface. This will create a command display, enabling you to set the value of the data point.

The screenshot below shows the raw data and command displays in an interface window. You are currently in edit mode, which means you can edit the appearance of the graphical plugins on the interface page. Switch from edit mode to run mode (hit CMD+Shift+R). Now you can USE the command plugin. Type in a value in the "u" command plugin and hit the "Send" button. The value of the output "y" will track the input "u" according to the second order system dynamics.

For a more illustrative example, you can open the "second_order.vci" interface, which includes more commands, data displays, and a plot of the second order system.

Click here to learn more.

• DSim Example: A Second Order System

Creating a Setup File from DSim Components

Every DSim simulation is defined with a setup file. The setup file specifies a basic set of simulation parameters (including the start time, time step, duration, and time scale). It also lists all of the DSim components that are included in the simulation, and provides initialization data (as necessary) for each of those components.

Setup files are just text files. They can be written by hand, or they can be generated using the SimBuilder application (a separate utility that is included with VisualCommander). This section gives a brief overview of the setup file structure.

Consider the setup file for the second order demo as an example. The entire file is shown below:

# DSim Setup File (v1), generated

# Base Simulation Parameters
TimeStep 0.010000;
TimeScale 1.000000;
EndSimulationSecs 60.000000;

# Constraints

# Object Hierarchy
Object second_order dsim_second_order builtin
SetIntegrator dsim_rk4 builtin
EndObject

# End simulation file

Lines beginning with # are comments. The file is organized into 3 sections:

• Base simulation parameters
• Constraints
• Object Hierarchy

The first section defines the base simulation parameters. Here, we use a time step of 0.01 seconds, a time scale of 1.0 (synced with real-time) and run for 60 seconds. The starting time is ignored in this file. If we were to include it, we would add a line such as the one shown below, which specifies the start time in Julian date format:

StartJD 2454176.0

The next section of the file is for constraints. This can be used to specify stopping conditions, or to perform simple scripting. For example, you can cause variable X to be set to value Y when condition C (some expression involving values in the simulation) becomes true or becomes untrue.

Finally, we have the object hierarchy. This represents the main portion of the setup file. Here, we list all of the objects and components that are included in the simulation. Each object is added with an object creation line of the form:

Object OBJ_NAME CLASS BUNDLE

where OBJ_NAME is the name you give the object for this simulation (anything you want), CLASS is the DSim class that the defines the object, and BUNDLE is the name of the bundle that provides that class.

In general, Objects can have children, called "Components". The component creation line is:

Component COMP_NAME OBJ_NAME : CLASS BUNDLE

The hierarchy implies that a child's frame of reference is relative to their parent's frame of reference and that their parent will check to see if the child is exerting forces and torques on the parent. Custom objects can also exploit the parent/child relationship for many other calculations, including easily making function calls on children or parents.

The hierarchy can also be extended to an arbitrary number of levels. The rule is that components must have parents, and objects must not have parents. For example, the syntax for a hierarchy that has an object at the top level, and then children that extend down to COMP_NAME_0 is:

Component COMP_NAME_0 COMP_NAME_2 COMP_NAME_1 OBJ_NAME : CLASS BUNDLE

In this simulation, we have only one object. We name it "second_order". It derives from the "dsim_second_order" class. It is not included in any separate bundle, but is one of the "builtin" classes that is provided with DSim.

After the object (or component) creation line, we can specify various features for the object (or component). For example, we can specify which integrator to use. In this case we use the "dsim_rk4" integrator, which is again one of the "builtin" classes. In general, we can perform the following actions:

• Select the integrator
• Define the mass, center of mass, inertia, position, velocity, attitude and body rate
• Specify timing dependencies with respect to other objects/components
• Initialize the value of any member variable
• Define targets for outlet variables
• Add a telemetry point
• Add a command point
• Add custom directives

For more information about the building and customizing a simulation from Dsim components, see the SimBuilder help documentation.