Chapter 3. Tour of GMAT

When you start a session, the GMAT desktop is displayed with a default mission already loaded. The GMAT desktop has a native look and feel on each platform and most desktop components are supported on all platforms.

Windows GUI

When you open GMAT on Windows and click Run in the Toolbar, GMAT executes the default mission as shown in the figure below. The tools listed below the figure are available in the GMAT desktop.

Figure 3.1. GMAT Desktop (Windows)

Menu Bar	The menu bar contains File, Edit, Window and Help functionality. On Windows, the File menu contains standard Open, Save, Save As, and Exit functionality as well as Open Recent. The Edit menu contains functionality for script editing when the script editor is active. The Window menu contains tools for organizing graphics windows and the script editor within the GMAT desktop. Examples include the ability to Tile windows, Cascade windows and Close windows. The Help menu contains links to Online Help, Tutorials, Forums, and the Report An Issue option links to GMAT’s defect reporting system, the Welcome Page, and a Provide Feedback link.
Toolbar	The toolbar provides easy access to frequently used controls such as file controls, Run, Pause, and Stop for mission execution, and controls for graphics animation. On Windows and Linux, the toolbar is located at the top of the GMAT window; on the Mac, it is located on the left of the GMAT frame. Because the toolbar is vertical on the Mac, some toolbar options are abbreviated. GMAT allows you to simultaneously edit the raw script file representation of your mission and the GUI representation of your mission. It is possible to make inconsistent changes in these mission representations. The GUI/Script Sync Status indicator located in the toolbar shows you the state of the two mission representations. See the the section called “GUI/Script Interactions and Synchronization” section for further discussion.
Resources Tab	The Resources tab brings the Resources tree to the foreground of the desktop.
Resources Tree	The Resources tree displays all configured GMAT resources and organizes them into logical groups. All objects created in a GMAT script using a Create command are found in the Resources tree in the GMAT desktop.
Mission Tab	The Mission tab brings the Mission Tree to the foreground of the desktop.
Mission Tree	The Mission tree displays GMAT commands that control the time-ordered sequence of events in a mission. The Mission tree contains all script lines that occur after the BeginMissionSequence command in a GMAT script. You can undock the Mission tree as shown in the figure below by right-clicking on the Mission tab and dragging it into the graphics window. You can also follow these steps: Click on the Mission tab to bring the Mission Tree to the foreground. Right-click on the Mission Sequence folder in the Mission tree and select Undock Mission Tree in the menu. Figure 3.2. Undocked Mission Tree
Output Tab	The Output tab brings the Output Tree to the foreground of the desktop.
Output Tree	The Output tree contains GMAT output such as report files and graphical displays.
Message Window	When you run a mission in GMAT, information including warnings, errors, and progress are written to the message window. For example, if there is a syntax error in a script file, a detailed error message is written to the message window.
Status Bar	The status bar contains various informational messages about the state of the GUI. When a mission is running, a Busy indicator will appear in the left pane. The center pane displays the latitude and logitude of the mouse cursor as it moves over a ground track window.

The GMAT script editor is a textual interface that lets you directly edit your mission in GMAT's built-in scripting language. In Figure 3.3, “GMAT Script Editor” below, the script editor is shown maximized in the GMAT desktop and the items relevant to script editing are labeled.

Figure 3.3. GMAT Script Editor

The GMAT desktop supports both a script interface and a GUI interface and these interfaces are designed to be consistent with each other. You can think of the script and GUI as different "views" of the same data: the resources and the mission command sequence. GMAT allows you to switch between views (script and GUI) and have the same view open in an editable state simultaneously. Below we describe the behavior, interactions, and rules of the script and GUI interfaces so you can avoid confusion and potential loss of data.

Create Spacecraft Sat
Sat.X = 3000
BeginMissionSequence
Sat.X = 1000

Figure 3.4. Default Resources tree

The Resources tree displays created resources organized into folders by object category. The SolarSystem and Solvers folders contain more specific folders which can be found by clicking the expand (+) icon. Conversely, folders can be collapsed by clicking the minimize (-) icon.

Resources can be added by right clicking the folder of the resource and clicking the resource type from the available menu. Most folders have only one available resource type; for example if the Spacecraft folder is right-clicked, the user can only click “Add Spacecraft” (Figure 3.5). Other folders have multiple objects that can be added and the user must first select the “Add” menu before selecting the object; for example to add a ChemicalTank, right click the “Hardware” folder, select “Add”, then the list of available resource types is displayed and the user can click “Fuel Tank” (Figure 3.6). User-defined solar system resources are added by right-clicking either Sun or a default CelestialBody resource. By right-clicking Sun the user can add a Planet, Comet, or Asteroid to the solar system. By right-clicking a Planet the user can add a Moon to that Planet.

Figure 3.5. Folder menu for Spacecraft

Figure 3.6. Folder menu for Hardware

Resources can be edited by right-clicking on the resources and selecting one of the options from the menu (Figure 3.7).

Figure 3.7. Resource menu

The Mission Tree Display shows your hierarchical, ordered list of commands. Normally, the Mission Tree displays only the command name in the tree for each command node (more information such as command type, construction information, etc can be displayed using the Show Detail menu option). Commands are executed in the order they appear, e.g., GMAT executes commands from the top of the Mission Tree to the bottom. For control logic (If, For, and While) and the Optimize and Target commands, you can define a block of commands that execute as children of the parent command. These child commands of the control logic or the Optimize and Target commands appear indented. Use the plus (+) symbol to the left of the control logic command to show all the grouped commands and the minus (-) symbol to hide all the grouped commands. Commands that are grouped under control logic commands (e.g. If, For, and While) only execute if that control logic command is successfully executed (e.g., if the local expression evaluates to true for If command, or the loop condition evaluates to true for For and While commands).

In general, commands are executed only once. However, child commands grouped under the loop commands (e.g. For and While) may execute multiple times. These commands will execute for each time the loop command evaluates to true. Commands under the If commands are only executed if the If condition evaluates to true; otherwise, they are skipped. For the If-Else command, child commands grouped under the If portion of the command execute if the conditional statement evaluates to true; otherwise, the child commands grouped under the Else portion of the command execute.

The Mission Tree may display a subset of the commands of the full mission sequence based on your view filter options. There are 3 basic filtering options available within GMAT:

The view filters activate by clicking one of the view filter buttons to the right of the Mission Tree. The pressed (pushed in) button indicates which filter is currently enabled. The four buttons on the top are the Filter by branch level buttons. The next four buttons in the middle are the inclusive filter-by-command-types buttons, and the four buttons on the bottom are the exclusive filter-by-command-types buttons. The button at the very bottom of the view filters toolbar allows you to define a custom filter. You cannot combine filter-by-branch-level filters with the filter-by-command-type filters nor combine inclusive and exclusive command type filters. However, multiple inclusive command type filters can be combined (e.g., filter both physics related and solver related commands) or multiple exclusive command type filters can be combined.

The Mission Tree has two context-sensitive popup menus, depending on whether you right-click the Mission Sequence home item or a command in the Mission Tree. The Mission Sequence popup menu primarily allows you to manipulate the Mission Tree window and the entire command sequence. It also enables appending (adding to the end) commands to the mission tree.

Mission Sequence menu options are always available and active in the menu list.

The Command popup menu allows you to add, edit, or delete the commands in the Mission Tree by using the right mouse button. This displays a context sensitive menu for adding and modifying commands as well as viewing your command sequence and command summary. To add commands to the Mission Tree, right click a command and select Append, Insert Before, or Insert After. To edit commands, double click the command name or right click and select Open.

Most commands in GMAT can appear anywhere in the mission sequence. However, there are some exceptions and the Command popup menu is context sensitive, meaning the options available under the menu change based on what command is selected and where in the tree the command occurs. Here is a complete list of context sensitivities:

The Mission Tree window may be used as a floating window or docked with the Resource tree. GMAT remembers the placement and docking status of the Mission Tree even after you quit. The undocked Mission Tree window may be resized, moved, or minimized. When the Mission Tree is undocked, and the user opens a dialog box for a GUI component, the dialog box does not cover the Mission Tree.

To undock the Mission Tree Display, either:

To dock the Mission Tree display, either:

To view a Command Summary, you must first run the mission. If the mission has not been run during the current session, the Command Summary will be empty. If changes are made to your configuration, you must rerun the mission for those changes to take effect in the Command Summary.

The Command Summary contains several types of data. Orbit state representations include Cartesian, spherical, and Keplerian. For hyperbolic orbits, B-Plane coordinates, DLA and RLA are provided. Planetodetic information includes Longitude and Latitude among others. For a Maneuver command, the Maneuver properties are displayed in the CoordinateSystem specified on the ImpulsiveBurn resource. See the Coordinate Systems subsection below for more information on the command summary contents when some data is undefined.

In the event when the orbit is nearly singular conic section and/or any of the keplerian elements are undefined, an abbreviated Command Summary is displayed as shown in the Coordinate Systems subsection below.

For performance reasons, propagation in step mode does not write out a command summary. Additionally, if a command is nested in control logic and that command does not execute as a result, no command summary data is available.

The Coordinate System menu at the top of the Command Summary dialog allows you to select the desired coordinate system for the state data. When the Coordinate System has a celestial body at the origin, the Command Summary shows all supported data including Cartesian, Spherical, Keplerian, Other OrbitData, and Planetodetic properties as shown in the GUI screenshot above. When the Coordinate System does not have a celestial body at the origin, the CommandSummary contains an abbreviated command summary as shown below.

Note: GMAT currently requires that the selected CoordinateSystem cannot reference a spacecraft.

          Propagate Command: Propagate1
        Spacecraft       : DefaultSC
        Coordinate System: EarthMJ2000Eq

        Time System   Gregorian                     Modified Julian  
        --------------------------------------------------------------------    
        UTC Epoch:    01 Jan 2000 15:19:28.000      21545.1385185185
        TAI Epoch:    01 Jan 2000 15:20:00.000      21545.1388888889
        TT  Epoch:    01 Jan 2000 15:20:32.184      21545.1392613889
        TDB Epoch:    01 Jan 2000 15:20:32.184      21545.1392613881

        Cartesian State                       Spherical State 
        ---------------------------           ------------------------------ 
        X  =   7047.3574396928 km             RMAG =   7195.1179781105 km
        Y  =  -821.00373455465 km             RA   =  -6.6448962577676 deg 
        Z  =   1196.0053110175 km             DEC  =   9.5683789596091 deg 
        VX =   0.8470865225276 km/sec         VMAG =   7.4415324037805 km/s
        VY =   7.3062391027010 km/sec         AZI  =   81.377585410118 deg
        VZ =   1.1303623817297 km/sec         VFPA =   88.583915406742 deg  
                                              RAV  =   83.386645244484 deg
                                              DECV =   8.7370006427902 deg

        Spacecraft Properties 
        ------------------------------
        Cd                    =   2.200000
        Drag area             =   15.00000 m^2
        Cr                    =   1.800000
        Reflective (SRP) area =   1.000000 m^2
        Dry mass              =   850.00000000000 kg
        Total mass            =   850.00000000000 kg
        

• GUI/script synchronization

• Mission execution from the editor

• Syntax highlighting

• Comment/uncomment or indent blocks of text

• Standard features like copy/paste, line numbering, find-and-replace, etc.

Figure 3.8. Parts of the script editor

When you load a script into the GMAT GUI, it is added to the script list in the resources tree. GMAT can have many scripts loaded at any one time, but only one can be synchronized with the GUI. This script is called the active script, and is distinguished by a bolded name in the script list. The editor status indicator in the script editor for the active script shows “Active Script” as well. All other scripts are inactive, but can be viewed and edited in the script editor.

Figure 3.9. Active script indicators

To synchronize with the GUI, you must make an inactive script active by clicking either of the synchronization buttons (described in the next section). This will change the current script to active, synchronize the GUI, and change the the previously active script to inactive. Alternately, you can right-click the script name in the resources tree and click Build.

GMAT provides two separate representations of a mission: a script file and the GUI resources and mission trees. As shown in Figure 3.8, “Parts of the script editor”, you can have both representations open and active at the same time, and can make changes in both places. The GUI/Script Sync Status indicator shows the current status of the two representations relative to each other. The following states are possible:

The script editor provides two buttons that perform synchronization from the script to the GUI. Both the Save,Sync and the Save,Sync,Run buttons behave identically, except that the Save,Sync,Run button runs the mission after synchronization is complete. The following paragraphs describe the behavior of the Save,Sync button only, but the description applies to both buttons. If you right-click the name of a script in the resources tree, a context menu is displayed with the items Save, Sync and Save, Sync, Run. These are identical to the Save,Sync and Save,Sync,Run buttons in the script editor.

When pressed, the Save,Sync button performs the following steps:

If the GUI has existing modifications, a confirmation prompt will be displayed. If confirmed, the GUI modifications will be overwritten.

If the script is not active, a confirmation prompt will be displayed. If confirmed, the script will be made active before the steps above are performed.

If the script has errors, the GUI will revert to an empty base state until all errors are corrected and the script is synchronized successfully.

The scripts folder in the Resources tree contains items for each script that has been loaded into GMAT. Individual scripts can be added to the list by right-clicking the Scripts folder and clicking Add Script.

The right-click menu for an individual script contains several options:

The edit window displays the text of the loaded script and provides tools to edit it. The edit window provides the following features:

If you right-click anywhere in the edit window, GMAT will display a context menu with the following options:

When the script editor is active in the GMAT GUI, the Edit menu is also available with the following options:

See the Keyboard Shortcuts reference page for the list of keyboard shortcuts that are available when working in the script editor:

On the Edit menu, if you click Find or Replace (or press Ctrl+F or Ctrl+H), GMAT displays the Find & Replace utility, which can be used to find text in the active script and optionally replace it with different text. The utility looks like the following figure.

To find text within the active script, type the text you wish to find in the Find What box and click Find Next or Find Previous. Find Next (F3) will start searching forward (below) the current cursor position, while Find Previous will start searching backward (above). If a match is found, the match will be highlighted. You can continue clicking Find Next or Find Previous to continue searching. The search text (in the Find What box) can be literal text only; wildcards are not supported. To replace found instances with different text, type the replacement text in the Replace With box. Click Replace to replace the currently-highlighted match and highlight the next match, or click Replace All to replace all matches in the file at once. The Find & Replace utility saves a history of text previously entered in the Find What and Replace With boxes in the current session. Click the down arrow in each box to choose a previously-entered value.

The Save button saves the current script without checking syntax or synchronizing with the GUI, and without switching the active script. The Save As button is identical, but allows you to save to a different file.

The Close button closes the script editor, and prompts you to save any unsaved changes.

When the contents of the script have been modified, the script editor displays “**modified**” in the save status indicator. This is a visual indicator that there are unsaved changes in the script. Once the changes are saved or reverted, the indicator turns blank.