Building a GMAT Plug-in: A Walkthrough Using Visual Studio 2010

Darrel J. Conway Thinking Systems, Inc.

December 7, 2012

Abstract

This document walks a Visual Studio Windows developer through the process of building a plug- in module for the General Mission Analysis Tool (GMAT). The procedure starts the reader from a predefined set of skeleton code available online, and shows the user how to configure that code to add a custom feature to GMAT. The example plug-in used in this walkthrough writes information to the GMAT message window. An appendix to this document describes the steps needed to configure the GUI for the new object(s).

The General Mission Analysis Tool (GMAT) is a spacecraft mission design and analysis tool that lets users model spacecraft trajectories using high fidelity physical models. The tool provides capabilities for spacecraft trajectory propagation, maneuvering using impulsive or finite duration thruster firings, parameter targeting and optimization, and mission data modeling and analysis. Additional capabilities can be added to GMAT by writing shared libraries that extend the core system functionality. These plug-in modules have been used to add new optimizers, numerical integrators, atmospheric models, and event computations to GMAT. Complex subsystem can also be added using the plug-in interfaces. One example is the prototype estimation capabilities added to GMAT and released starting in 2011, which includes both batch least squares and extended Kalman filter estimators, along with several simple and complex measurement models and a data simulator. The Plug-in system was first presented at the 4th International Conference on Aerospace Tools and Techniques[1] and described in some detail in an earlier developer's document[2]. In this document, I will walk new developers through the process of adding a plug-in module to GMAT. The example used for this tutorial will add a new command to GMAT's Mission Control Sequence that writes data to the GMAT Message Window. I'll begin by describing the basic configuration needed as a starting point, and then direct you to the files needed to work through the exercise. Next we'll look at the desired functionality, and then use the starting files to add this functionality to GMAT. Once the code compiles, we'll configure GMAT to use the new plug-in, completing the lesson. The instructions provided here assume you are building GMAT using Visual Studio 2010 on a Windows based computer. This lesson is driven from a core set of configuration files that set up the basic Visual Studio project settings for compilation, which you will download as part of the process described here.

1. Preparation

In order to build a GMAT plug-in, you need a computer configured to build GMAT on the operating system you plan to use with your plug-in. This document is aimed at developers working on Microsoft Windows, developing with Visual Studio 2010. The development environment setup instructions are provided in a document in GMAT's repository on SourceForge[4]. You'll need to retrieve the source code and data files
from that location in order to proceed. The Plug-in code builds on code contained in GMAT's source files, so you need those files, arranged as described below, in order to proceed1 .

2. Configuration to Build a Plug-in

The project files used for this walkthrough assume that you have a specific arrangement of source code files and dependencies. The path data is entered in the Visual Studio project files using relative path information. If you are using a different file arrangement, you'll need to make adjustments to the project file settings to match your configuration. Figure 1 shows the folder structure used in the instructions that follow. You should already have the Gmat3rdParty folder and GmatDevelopment folder set up on your computer from when you configured it and built GMAT, following the instructions referenced in the preceding section. We will now proceed to collect the files you need for this Walkthrough. Those files are managed in the GMAT Plugins project at SourceForge.

 
Figure 1: Folder Structure after Downloading Plugin Repository

2.1 Retrieving and Setting Up the Files

The code used in this tutorial can be downloaded from the GMAT Plugins repository at SourceForge. The command line checkout of the entire plug-ins repository can be perfomed by changing directories to the desired location of the code (that is, to the folder containing your Gmat3rdParty and GmatDevelopment folders), and then executing this command:

The file arrangement and other setup requirements described here are needed regardless of your development platform. Visual Studio specifics don't enter the discussion until I start describing the code in the next section. 

This command places all of the projects available in the GMAT Plugins repository on your machine. The code we use for this tutorial is found in the folder named PluginShell{}src. We will work with a copy of the files contained in that folder, so that the project files and associated source remain in an unconfigured state in case you want to start a new plug-in from them after completing this exercise. To finish preparing to work:

• Create a new folder named SamplePlugin in the folder containing GmatDevelopment and Gmat3rdParty.

• Copy the PluginShell folder into the SamplePlugin folder.

• Open the example folder in your SamplePlugin folder, and copy the command folder from that location into the SamplePlugin{}src folder.

When you are finished with this step, your folders should be arranged as shown in Figure 2.

 
Figure 2: Folder Arrangement for the Walkthrough

We are now ready to begin defining and building our plug-in.

3. Defining the Desired Functionality

When GMAT runs a mission, it provides the user with information about progress in the run in a window at the bottom of the main GMAT window. The panel that receives this information is called the Message Window. Figure 3 shows this window. GMAT defines a static class named MessageInterface which is used to send text to this window using a syntax similar to the C printf function. A call to write to the message window looks like this:

 
Figure 3: The Message Window

When this code executes, the scripted line appears in the message window. The code that we'll use in the plug-in described here uses this framework to create a new GMAT Mission Control Sequence command that wraps this interface into a scriptable instruction for your GMAT missions. When we are done, you'll be able to pass strings, variables, and some object parameters to the command, which will then write their values to the message window. The command syntax for this is scripted in GMAT as follows:

Let's begin setting Visual Studio up to build the plugin that makes this work. 

4. Setting Up Visual Studio 2010

Follow these steps to set up Visual Studio 2010 (VS2010) to use the solution and project files we copied from the plugins repository earlier:

• Open Visual Studio 2010.

• From the File menu, select Open >Project/Solution...

• Select the PluginShell.sln solution file from your SamplePlugin{}PluginShell{}build{}VS2010 folder and select the Open button.

This opens the solution and project files in Visual Studio. First we need to set the development environment to build the plug-in library with settings compatible with the standard GMAT build. We want to set the system to build a release version of the library using Microsoft's 32-bit compiler. These settings are made using comboboxes (that is, drop-down selections) at the top of the VS2010 window, just below the menu bar. In the first combobox, select Release. In the second combobox, select Win32. When you are finished, your configuration should look like Figure 4.

 
Figure 4: Selecting the Configuration and Platform for the Build

If you look closely at Figure 4, you'll see that the factory and plugin folders in the project do not contain any files, and that there is no command folder in the project. That is because the project as stored in the SourceForge repository does not yet contain any source code file references. We need to tell it about the code that we will be compiling. We set the new folder up as a "filter" in VS2010, and then set the file references using Windows Explorer:

• In the Solution Explorer on the left side of the VS2010 window, right click on the "Source Files" label and select Add >New Filter. A new folder is added to the project tree named "NewFilter1'. 

• Change the filter's name to "command".

• If VS2010 is running full screen on your computer, select the "Restore Down" button to shrink it into a window that you can place next to another window.

• Open Windows Explorer, and size it so that you can see both the Windows Explorer contents and the VS2010 Solution Explorer.

• Navigate in Windows Explorer to your PluginShell{}src{}include folder. You should see a file named SampleDefs.hpp.

• Drag the SampleDefs.hpp file from Windows Explorer to the VS2010 Solution Explorer, and drop it into the GmatPluginShell{}Header Files folder.

• Navigate in Windows Explorer to your PluginShell{}src{}factory folder. You should see two files in this folder.

• Select both files, and drag them from Windows Explorer into the VS2010 Solution Explorer, dropping them into the GmatPluginShell{}Source Files{}factory folder.

• Repeat this procedure for the files in the PluginShell{}src{}command and PluginShell{}src{}plugin folders. When you have finished, your VS2010 Solution Explorer should match the one shown in Figure 5.

 
Figure 5: VS2010 with the Plug-in File References Set

5. Coding the Plug-in

GMAT plug-ins consist of three distinct pieces: the code that implements the new functionality, a set of Factory subclasses that are used to build new GMAT components coded into the plug-in, and a set of C style interfaces GMAT uses to learn about and access the plugin contents. The following sections describe each of these elements.

5.1 Coding the New Functionality

The lines in the Mission Control Sequence that define the actions taken when you run a mission are imple- mented through classes derived from the GmatCommand class. GmatCommand, in turn, is derived from GmatBase, the core class for all of the objects in the model describing the user's mission. The ConsolePrint command we are building into the plug-in is derived from GmatCommand. Source code for this command is in the command folder you copied into the src folder in Section 2.1. Open the file src{}command{}ConsolePrint.hpp in a text editor. Near the top of that file you'll find the lines

This command adds functionality to GMAT that enables scripting of text to the GMAT Message Window.