Simulator Setup User Guide
- 1 Setup document
- 1.1 Content of the Setup
- 1.2 Nodes
- 1.3 Modules
- 1.4 Extensions
- 1.5 Parameters
- 1.5.1 Simulation
- 1.5.1.1 Frame rate and Sync Mode
- 1.5.1.2 Application Mode
- 1.5.1.3 Communication Model
- 1.5.2 Logging
- 1.5.2.1 Log level
- 1.5.2.2 Log File Prefix
- 1.5.3 Profiling
- 1.5.4 Plugin Path
- 1.5.5 Remote Access
- 1.5.6 Python 3
- 1.5.1 Simulation
- 1.6 Seats
- 1.7 Application Setup Using a setup document
- 2 Editing the setup document in the Vortex Studio Editor
- 2.1 Setup Preset Templates
- 2.2 Defining Seats in a Setup
- 2.2.1 Preferred Roles
- 2.2.2 Creating a Seat
- 3 Loading Content at Start-Up
- 4 Seats and Roles
Setup document
A setup document (VXC extension) allows you to set up or configure a Vortex application without doing it all manually in code.
It can be passed to an application that will parse it (like the SimApp) and automatically configure itself based on the file's content.
Through the setup document, you can set some global parameters for the application (such as the default log level, the simulation frame rate, and the starting application mode) but most importantly you can specify which modules and extensions will need to be created along with the application and on which node. Specifying multiple nodes in a setup document allows a single document to contain the configuration of multiple types of nodes required for a simulator.
In the Vortex Studio Editor what the SDK calls an "ApplicationConfig" is referred to as an "Application Setup". Both terms represent the same concept but to avoid any confusion this guide will use the SDK terminology.
Content of the Setup
A setup document can contain the following elements:
Nodes
A node in a simulator represents, at the OS level, a process that will perform some tasks as part of your simulation. A simulator can be composed of a single node (what we call standalone or desktop) or multiple nodes. In the case of multiple nodes, they may or may not even be on the same physical machine. Whether they are or not, all nodes will use the Vortex network layer to communicate and exchange data between them.
Every Vortex simulator needs a master process. In standalone mode, since there is only one non-networked process, it is fairly straightforward. In a network setup, it is a bit more complicated since it is the master node that coordinates the exchange of data with the other nodes, called slaves, and instructs them on what to do. In most cases, the master will contain the dynamics module, while a slave node never will. If one of your nodes contains the dynamics module, it will be designated as the master by the application. A node can also be explicitly set as a master or a slave by settings its parameter "CommunicationModel" to master or slave.
The master node's configuration (or the configuration of the application in standalone mode) almost always contains the DynamicsEngine module. In a multi-node simulator, you must add the NetworkOpenDDS extension to your ApplicationConfig to allow nodes to communicate with each other.
Users of past versions of the SDK might remember having to add the VxSim::VxSlaveModule to their slave nodes' configuration. As of Vortex Studio 2017, this is no longer necessary as all that functionality has been integrated directly into the VxApplication.
To define setup nodes, it is important to understand the interactions between the different modules and extensions of the setup document, as well as the hardware configuration of the target computer.
The specific association between a node and a target computer is done when defining a simulator in the Vortex Player(Director) application: see Vortex Studio Director for more information.
Modules
As explained in Vortex Studio SDK: Making a Vortex Application, modules are a core part of a Vortex application. Modules are not part of the content like the other extensions and objects are. Modules are directly added to the application, either manually through VxSim::VxApplication::insertModule() or by adding them to an ApplicationConfig which is then applied to the VxApplication.
For a list of modules provided by Vortex Studio, see Vortex Studio Application Extensions and Modules.
Extensions
A common workflow is to add extensions to an application by embedding them in a content object and loading the object in the application. Though useful in many cases, if you find yourself re-adding extensions to your content that are not directly related to it (for example an extension handling a user interface or network communication), it is a clear sign that the extension probably belongs inside an ApplicationConfig instead. Extensions that are fundamental to your simulator application regardless of loaded content are good candidates for this.
For a list of modules provided by Vortex Studio, see Vortex Studio Application Extensions and Modules.
Parameters
A Vortex application exposes some high-level parameters that can be customized from the Application Setup. Some of these parameters are global while others can be overridden by each node.
Simulation
Frame rate and Sync Mode
Desired Simulation frame rate and the synchronization mode to reach it.
See Synchronization Modes for more information about each mode
Application Mode
Starting application mode. Should be set to editing. In some situations, simulating can be used.
See Application Modes for more information about each mode.
Communication Model
Automatic will determine the Master node by the presence of the dynamics module, all the other nodes will be slaves. This can also be set explicitly.
Logging
Log level
The log level can be set per node to the following values, be severity:
Off - nothing will be logged
Fatal
Error
Warn
Info
Debug
Trace
All - everything will be logged
Log File Prefix
Generates a log file named <prefix>_<hostname>_<process id>. When the value is empty, the prefix is the name of the application and the file is located in the %temp% folder.
Profiling
The Vortex Studio Player manipulates these settings as needed but the setup can be used to define the initial state.
See The Profiler Tab for some examples.
Plugin Path
Add additional folders for custom plugin files (vxp) that contain modules and extensions made by a third party. This allows Vortex to find them when loading your simulator Application.
See Customizing Vortex for information about custom plugins.
Remote Access
Enables remote access so that the Remote Debugger can connect to your Application.
See the Remote Debugger User Guide for information about the Remote debugger.
Python 3
The python 3 options must be set via the application context.
See Integrating Vortex Studio using Python 3 for more details.
Seats
A seat is a configuration of a group of modules and nodes that are meant to be assigned a specific role during the simulation. See Defining Seats in a Setup for more details.
Application Setup Using a setup document
When a setup document is applied to an application, the setup will first add its global modules, then extensions of the global section (first level), as well as its parameters to the application. Then the node-specific modules, extensions, and parameters are applied. When a parameter is present at both the node and the global level, the node will prevail.