Feature Specification for Mission Tree

 

Overview

The Mission Tree is an ordered, hierarchical, display of your GMAT script command mission sequence (everything after the BeginMissionSequence in your script).  It represents the ordered list of commands to be executed to model your mission.  The hierarchical grouping in the mission tree represent commands that are executed inside a control logic command, e.g., If , For , While , etc.  The mission tree allows you to add, edit, delete and rename commands.  It allows you to configure or filter the display of the commands in the Mission Tree to make the command execution easier to understand or modify.  An example Mission Tree screenshot is below.  The Mission Tree Window is made up of 2 elements: the mission sequence on the left and the view filters toolbar on the right.

 

Figure 1 Mission Tree Window

 

Edits to the Mission Tree will be reflected in your script after it is synchronized and vice-versa.  If you edit the Mission Tree, you need to synchronize with the script to see it in the script editor.  If you edit the script, you need to synchronize with the GUI to see your changes reflected in the Mission Tree.

 

 

 

Mission Tree Display

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 , If-Else , 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 , If-Else , For , and While ) only execute if that Control Logic command is successfully executed (e.g., if the conditional statement evaluates to true for If and If-Else commands, 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.

Note that all commands in the Mission Tree are grouped under a special Mission Sequence home item.  This home item is always present as the first item in the Mission Tree and cannot be deleted.

 

 

View Filters Toolbar

 

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:

      Filter by branch level

      Filter by command types (inclusive)

      Filter by command types (exclusive)

 

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 inclusive Filter by Command types, 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.

Note that all parents of a viewable command are displayed, even if the parent command is not part of the viewable command set.

 

Also note that the Mission Tree automatically reconfigures to show all commands when the user Appends or Inserts a new command.  

 

 

Filter by Branch Level

 

Filtering by branch level causes GMAT to not display commands in the mission tree that are below a certain level.  To select the number of levels you wish to display, click the buttons on the top.  The four buttons correspond to (from top to bottom):

      Show all branches

      Show one level of branching

      Show two levels of branching

      Show three levels of branching

 

Only one Filter by Branch level button may be active at a time.  The default GMAT behavior is to display all branches of a mission tree.

 

Filter by Command Types

 

GMAT allows you to filter what commands are displayed by their command type.  You may select to only display commands that are in a filter command type set (inclusive) or only display commands that are not in a filter command type set (exclusive).  GMAT provides both pre-configured command type sets (e.g., physics related or output related) and custom command type sets that you define.

 

The four middle buttons in the View Options toolbar are pre-configured inclusive command filters, e.g., only display commands that are in the desired command set. The four inclusive filter buttons correspond to (from top to bottom):

      Physics Related (Propagate, Maneuver, BeginFiniteBurn, and EndFiniteBurn)

      Solver Related  (Target, Optimize, Vary, Achieve, NonlinearConstraint, Minimize, EndTarget, EndOptimize)

      Script Events

      Control Flow (If, If-Else, For, and While, EndIf, EndFor, EndWhile)

 

Multiple inclusive command type filters can be active at once.  For example, to filter both physics related and solver related commands, click both the Physics related and Solver related filter buttons so that they appear pressed down.  This option will show all physics related and solver related commands and hide all other commands (except Parents of the viewable commands)).

 

The four buttons at the bottom in the View Options toolbar are pre-configured exclusive command filters, e.g., only display commands that are not in the command set. The four exclusive filter buttons correspond to (from top to bottom):

      Report

      Equation

      Output related (Report, Toggle, PenUp, PenDown, Markpoint, and ClearPlot)

      Call function (GMAT and MATLAB Functions) and Save

 

Multiple exclusive command type filters can be active at once.  For example, to show everything but Reports and Output related commands, click both the Reports and Output related filter buttons so that they appear pressed down.

Note that the Mission Tree shows an ellipsis (...) after a command name if the command is followed by items not graphically displayed in the tree because of filter options.

 

 

Custom View Filter

 

Open Issue Reported by SPH:  Filters are not persistent from one session to the next.  This could really annoy users because they can take the time to create a custom filter, and the information is lost on close.  I think this behavior causes too much user pain to leave as is and suggest saving filter information in the .ini file.  (this would mean filters are not specific to mission though)

 

Here is a suggested approach for modifications to the ini file:

 

%  In this case, the Filters are the number of branch levels to display

[MissionTree]

FilterType = BranchLevels        

Filters         ={All}                                    

 

%  In this case, the Filters are all Include filters that are selected

[MissionTree]

FilterType = Include  

Filters       = {Physics,Solver,ScriptEvent,ControlFlow}       

 

%  In this case, the Filters are all Exclude filters that are selected

[MissionTree]

FilterType =  Exclude      

Filters         =  {Report,Equation,PlotRelated,FunctionCall}       

 

% In this case, the list of Filters are the names of the commands to be included or excluded.

[MissionTree]

FilterType = CustomInclude   %  complete list of options : CustomInclude or CustomExclude     

Filters         = {Propagate,Maneuver,BeginFiniteBurn,Report}       

 

Another approach that I think will be easier to develop [TGG]:

[MissionTree]

FilterType = Levels/Include/Exclude

ShowLevels=0(All)/1/2/3...

[FILTER_NAME]=True/False where True equals checked or depressed, e.g.,

Report=True

Equation=False

 

 

 

 

GMAT also allows you to define a custom command filter.  You may select to only display commands that are in a filter command type set (inclusive) or only display commands that are not in a filter command type set (exclusive).  To define a custom command filter, click the button at the very bottom of the toolbar.  The Mission Tree Customize View Window will appear.

Figure 2 Mission Tree Customize dialog box

 

To define a custom command filter:

      Select whether this is an inclusive or exclusive command set

      Check the commands to add them to the inclusive or exclusive command set

      Click Apply

Mission Sequence Menu

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. 

Figure 3 Mission Sequence menu

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

 

 

Mission Sequence Menu Options:

Collapse All

This menu option collapses all the branches in the Mission Tree so that you only see the top-level commands.  To show branches, click the Plus (+) button next to a command or select Expand All from the Mission Sequence popup menu.

 

Expand All

This menu option expands all the branches and sub-branches in the Mission Tree so that you see every command in the mission sequence.  To hide branches, click the Minus (-) button next to a command or select Collapse All from the Mission Sequence popup menu.

 

Append

The append menu option displays the submenu of commands that can be appended to the mission sequence. This menu is not available when the Mission Tree view is filtered.

 

 

Run

The run menu option executes the mission command sequence.  This menu option is always available.

 

Show Detail

The Show Detail menu option toggles an option to display the mission tree with short or verbose text.  When the show detail menu option is checked, each command is displayed with the script line for the command (e.g. what appears in “Show Script” for the command).  When the show detail menu option is unchecked, th e mission tree shows only the label for the command which will be your custom label if you have provided one and a system provided label if you have not labelled the command. This menu option is always available.

 

Show Mission Sequence

The Show Mission Sequence menu option displays a streamlined text view of the mission sequence in text window.  This view shows a hierarchical view of every command (similar to a script view) in the mission sequence.  Unlike the script editor, this view only includes the command names and labels.  This menu option is always available.

 

Show Script

The Show Script menu option displays the script associated with the GUI version of the current mission script.  This is the complete script that would be saved to a file if you clicked the GUI save button.  Note that when the GUI is unsynchronized with the script editor (please see INSERT REFERENCE HERE for more details), this mission script is different than the script displayed in the script editor.  This menu option is always available.

 

Mission Summary - All

The Mission Summary - All menu option displays a mission simulation summary for the all commands in the mission sequence.  This summary information includes spacecraft state information, spacecraft physical properties, time information, Planetodetic Properties, and other orbit data for each command. This information is only available after a mission simulation is run and the data shows state information after the execution of the command.  Showing Mission Summary data for a Script Event is equivalent to showing summary data for the last command in that Script Event.  If commands are nested in control flow or solver branches, the summary data that is displayed is for the last pass through the sequence. This menu option is always available.

 

 

 

Open Issue Reported by SPH:  Summary information is not available for all command types due to performance problems. For Assignment commands and some others we do not show command summary information.  We need to include a list of which commands do not have summary information.  This list could appear here, or appear under Command Sumamry section below and be referenced here.  

 

 

 

For performance reasons, Summary data is

 

Mission Summary - Physics

The Mission Summary - Physics menu option displays a mission simulation summary for physics related commands in the mission sequence.  This summary information includes spacecraft state information, spacecraft physical properties, time information, Planetodetic properties, and other orbit data for each command.  This information is only available after a mission simulation is run and the data shows state information after the execution of the command.  Note that if you have physics-based commands such as Propagate or Maneuver inside a Script Event, then summary information for those commands, are not displayed.  Showing Mission Summary data for a Script Event is equivalent to showing summary data for the last command in that Script Event.  If commands are nested in control flow or solver branches, the summary data that is displayed is for the last pass through the sequence. This menu option is always available.

 

Dock Mission Tree

The Dock Mission Tree menu option docks the Mission Tree window in the notebook containing the Resources tree and Output tree.  This option is only selectable if the Mission Tree is currently floating or undocked.  Please see the Docking/Undocking/Placement section for more information.

 

Undock Mission Tree

The Undock Mission Tree menu option undocks, or makes floating, the Mission Tree window from the Resources tree and Output tree.  The undocked Mission Tree Window may be resized, moved, maximized, minimized, and restored.  This option is only selectable if the Mission Tree is currently docked.  Please see the Docking/Undocking/Placement section for more information.

 

Command Menu

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:

 

      Insert and Append are not available unless the mission tree filter is set to show all levels.

      Achieve commands can only appear inside of a Target Sequence. 

      Vary commands can only appear in a Target or Optimize Sequence,

      NonlinearConstraint and Minimize commands can only appear in an Optimize sequence.

 

For Developers/GUI Testers:  There are some commands that should not appear in Production release because they are associated with Beta functionality.  The following commands should not be available:

 

      PrepareMissionSequence.  (Turning off C-API Plugin may make this unavailable automatically).

      RunSimulator:  Turning off estimation plug-in will make this go away.

      RunEstimator: Turning off estimation plug-in will make this go away.

 

Not sure if this command should be included or not.

 

      SaveMission: 

 

These commands are at risk and may or may not be in the release depending upon the schedule:

 

      Global

      Call GMATFuction

      Save

 

 

Figure 4 Target Sequence

Command Menu Options:

Open

This menu option opens the command editor window for the selected command.  The Open menu option is always active in the menu list.  If the window is already open, the Open option brings the window to the front and makes it the active window.


Close

This menu options closes the command editor window for the selected command.  The Close menu option is always active in the menu list.

 

Append

The append menu option displays the submenu of commands that can be appended as the last sub-item of the selected command in the Mission Tree.  As such, the Append menu option only appears when the selected tree item can contain sub-items, e.g., the Mission Sequence home item, Control Logic commands, and Optimize and Target commands.  Note that the Append submenu is context-sensitive and will only show commands that may be appended to the selected command.  Finally, this menu is not available when the Mission Tree view is filtered.

 

Insert After

The Insert After menu option displays the submenu of commands that can be inserted after the selected command (and any child commands, if any) in the Mission Tree.  Nominally, the new command is inserted at the same level as the selected command.  However, if the selected command is the “End” Command of a Control Logic or Optimize or Target command (e.g., “End For, End If, End Optimize, etc), the new command is inserted after the End command and on the same level (e.g., the next level up) as the parent command.  The Insert After menu option is always active in the menu list except when the Mission Sequence Home item is selected.  Note that the Insert After submenu is context-sensitive and will only show commands that may be added after the selected command.  Finally, this menu is not available when the Mission Tree view is filtered.

 

Insert Before

The Insert Before menu option displays the submenu of commands that can be inserted before the selected command (and any child commands, if any) in the Mission Tree.  The new command is always inserted at the same level as the selected command.  The Insert Before menu option is always active in the menu list except when the Mission Sequence Home item is selected.  Note that the Insert Before submenu is context-sensitive and will only show commands that may be added before the selected command.  Finally, this menu is not available when the Mission Tree view is filtered.

 

Rename

The Rename menu option displays a dialog box where you can rename the selected command.  A command name may contain any characters except the single quote.  Note that, unlike resources, command names do not have to be unique.  The Rename menu option is always active in the menu list except when the Mission Sequence Home item is selected. 

Delete

The Delete menu option deletes the selected command.  GMAT does not confirm the option before deletion occurs.  The Delete menu option is always active in the menu list except when the Mission Sequence Home item is selected. 

 

Command Summary

 

The Command Summary menu option displays a mission simulation summary for the selected command, including spacecraft state information, time information, Planetodetic Properties, and other orbit data.  This information is only available after a mission simulation run.  This menu option is always available. However, command summary data is not available for Propagate Command in single step mode.  The button is available but no data is displayed.

Docking/Undocking/Placement

 

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 shall not cover the Mission Tree.

 

To undock the Mission Tree Display:

      Right click and drag the Mission Tree Tab out of the Resource Tree Window

      Right click the Mission Sequence Home item and select Undock Mission Tree

 

To dock the Mission Tree display, either:

      Left click the close button (x) of the Mission Tree Window

      RIght click the Mission Sequence Home item and select Dock Mission Tree

 

Graphics Window Persistency

 

      The GUI shall keep  the  state (minimized, maximize, or restore) of the following windows persistent from session to session for a given script configuration: 

      XY Plot graphics window

      Orbit View graphics window

      Ground Track Plot graphics window

      Report file data window if that window was opened in the saved session

      Ephemeris file window  if that window was opened in the saved session

      The GUI shall keep location of the following windows persistent from session to session for a given script configuration: 

      XY Plot graphics window

      Orbit View graphics window

      Ground Track Plot graphics window

      Report file data window if that window was opened in the saved session

      Ephemeris file window  if that window was opened in the saved session

      The GUI shall keep  z-order of the following windows persistent from session to session for a given script configuration: 

      XY Plot graphics window

      Orbit View graphics window

      Ground Track Plot graphics window

      Report file data window if that window was opened in the saved session

      Ephemeris file window  if that window was opened in the saved session

      The GUI shall keep  size of the following windows persistent from session to session for a given script configuration: 

      XY Plot graphics window

      Orbit View graphics window

      Ground Track Plot graphics window

      Report file data window if that window was opened in the saved session

      Ephemeris file window  if that window was opened in the saved session

      The GUI shall retain the z order of all windows except the mission tree from one script session to another.

      If the Mission tree is docked and the script editor is closed when configuring a new session the mission tree shall be the first layer.

      If the Mission tree is undocked and the script editor is open when configuring a new session the Mission Tree shall be the first layer and the script editor shall be the second layer.

      If the Mission tree is docked and the script editor is open when configuring a new session the the script editor shall be the first layer.

      The GUI shall keep the location of the following windows persistent from session to session:

      Mission Tree (if undock option is selected)

      Script editor

      When the Mission Tree is undocked, and the user opens a dialog box for a GUI component, the dialog box shall not cover the Mission Tree.

      When a new graphical resource is added to the mission, the GUI shall cascade the new MDI child window and not cover the Mission tree. (e.g.  NOT tile the MDI child windows )

      The system shall not reorganize output window configurations if the user has custom arranged them. 

      If the user configures the location of a graphics window, and then adds new graphics windows to the mission, the new graphics windows shall be placed in cascade over the top most graphics window.